1 /* 2 * Copyright (C) 2010 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.view; 18 19 import android.annotation.IntDef; 20 import android.annotation.NonNull; 21 import android.annotation.RequiresPermission; 22 import android.annotation.TestApi; 23 import android.compat.annotation.UnsupportedAppUsage; 24 import android.content.Context; 25 import android.hardware.BatteryState; 26 import android.hardware.SensorManager; 27 import android.hardware.input.InputDeviceIdentifier; 28 import android.hardware.input.InputManager; 29 import android.hardware.lights.LightsManager; 30 import android.os.Build; 31 import android.os.NullVibrator; 32 import android.os.Parcel; 33 import android.os.Parcelable; 34 import android.os.Vibrator; 35 import android.os.VibratorManager; 36 37 import com.android.internal.annotations.GuardedBy; 38 import com.android.internal.annotations.VisibleForTesting; 39 40 import java.lang.annotation.Retention; 41 import java.lang.annotation.RetentionPolicy; 42 import java.util.ArrayList; 43 import java.util.List; 44 45 /** 46 * Describes the capabilities of a particular input device. 47 * <p> 48 * Each input device may support multiple classes of input. For example, a multi-function 49 * keyboard may compose the capabilities of a standard keyboard together with a track pad mouse 50 * or other pointing device. 51 * </p><p> 52 * Some input devices present multiple distinguishable sources of input. 53 * Applications can query the framework about the characteristics of each distinct source. 54 * </p><p> 55 * As a further wrinkle, different kinds of input sources uses different coordinate systems 56 * to describe motion events. Refer to the comments on the input source constants for 57 * the appropriate interpretation. 58 * </p> 59 */ 60 public final class InputDevice implements Parcelable { 61 private final int mId; 62 private final int mGeneration; 63 private final int mControllerNumber; 64 private final String mName; 65 private final int mVendorId; 66 private final int mProductId; 67 private final String mDescriptor; 68 private final InputDeviceIdentifier mIdentifier; 69 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.P) 70 private final boolean mIsExternal; 71 private final int mSources; 72 private final int mKeyboardType; 73 private final KeyCharacterMap mKeyCharacterMap; 74 private final boolean mHasVibrator; 75 private final boolean mHasMicrophone; 76 private final boolean mHasButtonUnderPad; 77 private final boolean mHasSensor; 78 private final boolean mHasBattery; 79 private final ArrayList<MotionRange> mMotionRanges = new ArrayList<MotionRange>(); 80 81 @GuardedBy("mMotionRanges") 82 private Vibrator mVibrator; // guarded by mMotionRanges during initialization 83 84 @GuardedBy("mMotionRanges") 85 private VibratorManager mVibratorManager; 86 87 @GuardedBy("mMotionRanges") 88 private SensorManager mSensorManager; 89 90 @GuardedBy("mMotionRanges") 91 private BatteryState mBatteryState; 92 93 @GuardedBy("mMotionRanges") 94 private LightsManager mLightsManager; 95 96 /** 97 * A mask for input source classes. 98 * 99 * Each distinct input source constant has one or more input source class bits set to 100 * specify the desired interpretation for its input events. 101 */ 102 public static final int SOURCE_CLASS_MASK = 0x000000ff; 103 104 /** 105 * The input source has no class. 106 * 107 * It is up to the application to determine how to handle the device based on the device type. 108 */ 109 public static final int SOURCE_CLASS_NONE = 0x00000000; 110 111 /** 112 * The input source has buttons or keys. 113 * Examples: {@link #SOURCE_KEYBOARD}, {@link #SOURCE_DPAD}. 114 * 115 * A {@link KeyEvent} should be interpreted as a button or key press. 116 * 117 * Use {@link #getKeyCharacterMap} to query the device's button and key mappings. 118 */ 119 public static final int SOURCE_CLASS_BUTTON = 0x00000001; 120 121 /** 122 * The input source is a pointing device associated with a display. 123 * Examples: {@link #SOURCE_TOUCHSCREEN}, {@link #SOURCE_MOUSE}. 124 * 125 * A {@link MotionEvent} should be interpreted as absolute coordinates in 126 * display units according to the {@link View} hierarchy. Pointer down/up indicated when 127 * the finger touches the display or when the selection button is pressed/released. 128 * 129 * Use {@link #getMotionRange} to query the range of the pointing device. Some devices permit 130 * touches outside the display area so the effective range may be somewhat smaller or larger 131 * than the actual display size. 132 */ 133 public static final int SOURCE_CLASS_POINTER = 0x00000002; 134 135 /** 136 * The input source is a trackball navigation device. 137 * Examples: {@link #SOURCE_TRACKBALL}. 138 * 139 * A {@link MotionEvent} should be interpreted as relative movements in device-specific 140 * units used for navigation purposes. Pointer down/up indicates when the selection button 141 * is pressed/released. 142 * 143 * Use {@link #getMotionRange} to query the range of motion. 144 */ 145 public static final int SOURCE_CLASS_TRACKBALL = 0x00000004; 146 147 /** 148 * The input source is an absolute positioning device not associated with a display 149 * (unlike {@link #SOURCE_CLASS_POINTER}). 150 * 151 * A {@link MotionEvent} should be interpreted as absolute coordinates in 152 * device-specific surface units. 153 * 154 * Use {@link #getMotionRange} to query the range of positions. 155 */ 156 public static final int SOURCE_CLASS_POSITION = 0x00000008; 157 158 /** 159 * The input source is a joystick. 160 * 161 * A {@link MotionEvent} should be interpreted as absolute joystick movements. 162 * 163 * Use {@link #getMotionRange} to query the range of positions. 164 */ 165 public static final int SOURCE_CLASS_JOYSTICK = 0x00000010; 166 167 /** @hide */ 168 @IntDef(flag = true, prefix = { "SOURCE_CLASS_" }, value = { 169 SOURCE_CLASS_NONE, 170 SOURCE_CLASS_BUTTON, 171 SOURCE_CLASS_POINTER, 172 SOURCE_CLASS_TRACKBALL, 173 SOURCE_CLASS_POSITION, 174 SOURCE_CLASS_JOYSTICK 175 }) 176 @Retention(RetentionPolicy.SOURCE) 177 @interface InputSourceClass {} 178 179 /** 180 * The input source is unknown. 181 */ 182 public static final int SOURCE_UNKNOWN = 0x00000000; 183 184 /** 185 * The input source is a keyboard. 186 * 187 * This source indicates pretty much anything that has buttons. Use 188 * {@link #getKeyboardType()} to determine whether the keyboard has alphabetic keys 189 * and can be used to enter text. 190 * 191 * @see #SOURCE_CLASS_BUTTON 192 */ 193 public static final int SOURCE_KEYBOARD = 0x00000100 | SOURCE_CLASS_BUTTON; 194 195 /** 196 * The input source is a DPad. 197 * 198 * @see #SOURCE_CLASS_BUTTON 199 */ 200 public static final int SOURCE_DPAD = 0x00000200 | SOURCE_CLASS_BUTTON; 201 202 /** 203 * The input source is a game pad. 204 * (It may also be a {@link #SOURCE_JOYSTICK}). 205 * 206 * @see #SOURCE_CLASS_BUTTON 207 */ 208 public static final int SOURCE_GAMEPAD = 0x00000400 | SOURCE_CLASS_BUTTON; 209 210 /** 211 * The input source is a touch screen pointing device. 212 * 213 * @see #SOURCE_CLASS_POINTER 214 */ 215 public static final int SOURCE_TOUCHSCREEN = 0x00001000 | SOURCE_CLASS_POINTER; 216 217 /** 218 * The input source is a mouse pointing device. 219 * This code is also used for other mouse-like pointing devices such as trackpads 220 * and trackpoints. 221 * 222 * @see #SOURCE_CLASS_POINTER 223 */ 224 public static final int SOURCE_MOUSE = 0x00002000 | SOURCE_CLASS_POINTER; 225 226 /** 227 * The input source is a stylus pointing device. 228 * <p> 229 * Note that this bit merely indicates that an input device is capable of obtaining 230 * input from a stylus. To determine whether a given touch event was produced 231 * by a stylus, examine the tool type returned by {@link MotionEvent#getToolType(int)} 232 * for each individual pointer. 233 * </p><p> 234 * A single touch event may multiple pointers with different tool types, 235 * such as an event that has one pointer with tool type 236 * {@link MotionEvent#TOOL_TYPE_FINGER} and another pointer with tool type 237 * {@link MotionEvent#TOOL_TYPE_STYLUS}. So it is important to examine 238 * the tool type of each pointer, regardless of the source reported 239 * by {@link MotionEvent#getSource()}. 240 * </p> 241 * 242 * @see #SOURCE_CLASS_POINTER 243 */ 244 public static final int SOURCE_STYLUS = 0x00004000 | SOURCE_CLASS_POINTER; 245 246 /** 247 * The input device is a Bluetooth stylus. 248 * <p> 249 * Note that this bit merely indicates that an input device is capable of 250 * obtaining input from a Bluetooth stylus. To determine whether a given 251 * touch event was produced by a stylus, examine the tool type returned by 252 * {@link MotionEvent#getToolType(int)} for each individual pointer. 253 * </p><p> 254 * A single touch event may multiple pointers with different tool types, 255 * such as an event that has one pointer with tool type 256 * {@link MotionEvent#TOOL_TYPE_FINGER} and another pointer with tool type 257 * {@link MotionEvent#TOOL_TYPE_STYLUS}. So it is important to examine 258 * the tool type of each pointer, regardless of the source reported 259 * by {@link MotionEvent#getSource()}. 260 * </p><p> 261 * A bluetooth stylus generally receives its pressure and button state 262 * information from the stylus itself, and derives the rest from another 263 * source. For example, a Bluetooth stylus used in conjunction with a 264 * touchscreen would derive its contact position and pointer size from the 265 * touchscreen and may not be any more accurate than other tools such as 266 * fingers. 267 * </p> 268 * 269 * @see #SOURCE_STYLUS 270 * @see #SOURCE_CLASS_POINTER 271 */ 272 public static final int SOURCE_BLUETOOTH_STYLUS = 273 0x00008000 | SOURCE_STYLUS; 274 275 /** 276 * The input source is a trackball. 277 * 278 * @see #SOURCE_CLASS_TRACKBALL 279 */ 280 public static final int SOURCE_TRACKBALL = 0x00010000 | SOURCE_CLASS_TRACKBALL; 281 282 /** 283 * The input source is a mouse device whose relative motions should be interpreted as 284 * navigation events. 285 * 286 * @see #SOURCE_CLASS_TRACKBALL 287 */ 288 public static final int SOURCE_MOUSE_RELATIVE = 0x00020000 | SOURCE_CLASS_TRACKBALL; 289 290 /** 291 * The input source is a touch pad or digitizer tablet that is not 292 * associated with a display (unlike {@link #SOURCE_TOUCHSCREEN}). 293 * 294 * @see #SOURCE_CLASS_POSITION 295 */ 296 public static final int SOURCE_TOUCHPAD = 0x00100000 | SOURCE_CLASS_POSITION; 297 298 /** 299 * The input source is a touch device whose motions should be interpreted as navigation events. 300 * 301 * For example, an upward swipe should be as an upward focus traversal in the same manner as 302 * pressing up on a D-Pad would be. Swipes to the left, right and down should be treated in a 303 * similar manner. 304 * 305 * @see #SOURCE_CLASS_NONE 306 */ 307 public static final int SOURCE_TOUCH_NAVIGATION = 0x00200000 | SOURCE_CLASS_NONE; 308 309 /** 310 * The input source is a rotating encoder device whose motions should be interpreted as akin to 311 * those of a scroll wheel. 312 * 313 * @see #SOURCE_CLASS_NONE 314 */ 315 public static final int SOURCE_ROTARY_ENCODER = 0x00400000 | SOURCE_CLASS_NONE; 316 317 /** 318 * The input source is a joystick. 319 * (It may also be a {@link #SOURCE_GAMEPAD}). 320 * 321 * @see #SOURCE_CLASS_JOYSTICK 322 */ 323 public static final int SOURCE_JOYSTICK = 0x01000000 | SOURCE_CLASS_JOYSTICK; 324 325 /** 326 * The input source is a device connected through HDMI-based bus. 327 * 328 * The key comes in through HDMI-CEC or MHL signal line, and is treated as if it were 329 * generated by a locally connected DPAD or keyboard. 330 */ 331 public static final int SOURCE_HDMI = 0x02000000 | SOURCE_CLASS_BUTTON; 332 333 /** 334 * The input source is a sensor associated with the input device. 335 * 336 * @see #SOURCE_CLASS_NONE 337 */ 338 public static final int SOURCE_SENSOR = 0x04000000 | SOURCE_CLASS_NONE; 339 340 /** 341 * A special input source constant that is used when filtering input devices 342 * to match devices that provide any type of input source. 343 */ 344 public static final int SOURCE_ANY = 0xffffff00; 345 346 /** 347 * Constant for retrieving the range of values for {@link MotionEvent#AXIS_X}. 348 * 349 * @see #getMotionRange 350 * @deprecated Use {@link MotionEvent#AXIS_X} instead. 351 */ 352 @Deprecated 353 public static final int MOTION_RANGE_X = MotionEvent.AXIS_X; 354 355 /** 356 * Constant for retrieving the range of values for {@link MotionEvent#AXIS_Y}. 357 * 358 * @see #getMotionRange 359 * @deprecated Use {@link MotionEvent#AXIS_Y} instead. 360 */ 361 @Deprecated 362 public static final int MOTION_RANGE_Y = MotionEvent.AXIS_Y; 363 364 /** 365 * Constant for retrieving the range of values for {@link MotionEvent#AXIS_PRESSURE}. 366 * 367 * @see #getMotionRange 368 * @deprecated Use {@link MotionEvent#AXIS_PRESSURE} instead. 369 */ 370 @Deprecated 371 public static final int MOTION_RANGE_PRESSURE = MotionEvent.AXIS_PRESSURE; 372 373 /** 374 * Constant for retrieving the range of values for {@link MotionEvent#AXIS_SIZE}. 375 * 376 * @see #getMotionRange 377 * @deprecated Use {@link MotionEvent#AXIS_SIZE} instead. 378 */ 379 @Deprecated 380 public static final int MOTION_RANGE_SIZE = MotionEvent.AXIS_SIZE; 381 382 /** 383 * Constant for retrieving the range of values for {@link MotionEvent#AXIS_TOUCH_MAJOR}. 384 * 385 * @see #getMotionRange 386 * @deprecated Use {@link MotionEvent#AXIS_TOUCH_MAJOR} instead. 387 */ 388 @Deprecated 389 public static final int MOTION_RANGE_TOUCH_MAJOR = MotionEvent.AXIS_TOUCH_MAJOR; 390 391 /** 392 * Constant for retrieving the range of values for {@link MotionEvent#AXIS_TOUCH_MINOR}. 393 * 394 * @see #getMotionRange 395 * @deprecated Use {@link MotionEvent#AXIS_TOUCH_MINOR} instead. 396 */ 397 @Deprecated 398 public static final int MOTION_RANGE_TOUCH_MINOR = MotionEvent.AXIS_TOUCH_MINOR; 399 400 /** 401 * Constant for retrieving the range of values for {@link MotionEvent#AXIS_TOOL_MAJOR}. 402 * 403 * @see #getMotionRange 404 * @deprecated Use {@link MotionEvent#AXIS_TOOL_MAJOR} instead. 405 */ 406 @Deprecated 407 public static final int MOTION_RANGE_TOOL_MAJOR = MotionEvent.AXIS_TOOL_MAJOR; 408 409 /** 410 * Constant for retrieving the range of values for {@link MotionEvent#AXIS_TOOL_MINOR}. 411 * 412 * @see #getMotionRange 413 * @deprecated Use {@link MotionEvent#AXIS_TOOL_MINOR} instead. 414 */ 415 @Deprecated 416 public static final int MOTION_RANGE_TOOL_MINOR = MotionEvent.AXIS_TOOL_MINOR; 417 418 /** 419 * Constant for retrieving the range of values for {@link MotionEvent#AXIS_ORIENTATION}. 420 * 421 * @see #getMotionRange 422 * @deprecated Use {@link MotionEvent#AXIS_ORIENTATION} instead. 423 */ 424 @Deprecated 425 public static final int MOTION_RANGE_ORIENTATION = MotionEvent.AXIS_ORIENTATION; 426 427 /** 428 * There is no keyboard. 429 */ 430 public static final int KEYBOARD_TYPE_NONE = 0; 431 432 /** 433 * The keyboard is not fully alphabetic. It may be a numeric keypad or an assortment 434 * of buttons that are not mapped as alphabetic keys suitable for text input. 435 */ 436 public static final int KEYBOARD_TYPE_NON_ALPHABETIC = 1; 437 438 /** 439 * The keyboard supports a complement of alphabetic keys. 440 */ 441 public static final int KEYBOARD_TYPE_ALPHABETIC = 2; 442 443 private static final int MAX_RANGES = 1000; 444 445 private static final int VIBRATOR_ID_ALL = -1; 446 447 public static final @android.annotation.NonNull Parcelable.Creator<InputDevice> CREATOR = 448 new Parcelable.Creator<InputDevice>() { 449 public InputDevice createFromParcel(Parcel in) { 450 return new InputDevice(in); 451 } 452 public InputDevice[] newArray(int size) { 453 return new InputDevice[size]; 454 } 455 }; 456 457 /** 458 * Called by native code 459 * @hide 460 */ 461 @VisibleForTesting InputDevice(int id, int generation, int controllerNumber, String name, int vendorId, int productId, String descriptor, boolean isExternal, int sources, int keyboardType, KeyCharacterMap keyCharacterMap, boolean hasVibrator, boolean hasMicrophone, boolean hasButtonUnderPad, boolean hasSensor, boolean hasBattery)462 public InputDevice(int id, int generation, int controllerNumber, String name, int vendorId, 463 int productId, String descriptor, boolean isExternal, int sources, int keyboardType, 464 KeyCharacterMap keyCharacterMap, boolean hasVibrator, boolean hasMicrophone, 465 boolean hasButtonUnderPad, boolean hasSensor, boolean hasBattery) { 466 mId = id; 467 mGeneration = generation; 468 mControllerNumber = controllerNumber; 469 mName = name; 470 mVendorId = vendorId; 471 mProductId = productId; 472 mDescriptor = descriptor; 473 mIsExternal = isExternal; 474 mSources = sources; 475 mKeyboardType = keyboardType; 476 mKeyCharacterMap = keyCharacterMap; 477 mHasVibrator = hasVibrator; 478 mHasMicrophone = hasMicrophone; 479 mHasButtonUnderPad = hasButtonUnderPad; 480 mHasSensor = hasSensor; 481 mHasBattery = hasBattery; 482 mIdentifier = new InputDeviceIdentifier(descriptor, vendorId, productId); 483 } 484 InputDevice(Parcel in)485 private InputDevice(Parcel in) { 486 mKeyCharacterMap = KeyCharacterMap.CREATOR.createFromParcel(in); 487 mId = in.readInt(); 488 mGeneration = in.readInt(); 489 mControllerNumber = in.readInt(); 490 mName = in.readString(); 491 mVendorId = in.readInt(); 492 mProductId = in.readInt(); 493 mDescriptor = in.readString(); 494 mIsExternal = in.readInt() != 0; 495 mSources = in.readInt(); 496 mKeyboardType = in.readInt(); 497 mHasVibrator = in.readInt() != 0; 498 mHasMicrophone = in.readInt() != 0; 499 mHasButtonUnderPad = in.readInt() != 0; 500 mHasSensor = in.readInt() != 0; 501 mHasBattery = in.readInt() != 0; 502 mIdentifier = new InputDeviceIdentifier(mDescriptor, mVendorId, mProductId); 503 504 int numRanges = in.readInt(); 505 if (numRanges > MAX_RANGES) { 506 numRanges = MAX_RANGES; 507 } 508 509 for (int i = 0; i < numRanges; i++) { 510 addMotionRange(in.readInt(), in.readInt(), in.readFloat(), in.readFloat(), 511 in.readFloat(), in.readFloat(), in.readFloat()); 512 } 513 } 514 515 /** 516 * Gets information about the input device with the specified id. 517 * @param id The device id. 518 * @return The input device or null if not found. 519 */ getDevice(int id)520 public static InputDevice getDevice(int id) { 521 return InputManager.getInstance().getInputDevice(id); 522 } 523 524 /** 525 * Gets the ids of all input devices in the system. 526 * @return The input device ids. 527 */ getDeviceIds()528 public static int[] getDeviceIds() { 529 return InputManager.getInstance().getInputDeviceIds(); 530 } 531 532 /** 533 * Gets the input device id. 534 * <p> 535 * Each input device receives a unique id when it is first configured 536 * by the system. The input device id may change when the system is restarted or if the 537 * input device is disconnected, reconnected or reconfigured at any time. 538 * If you require a stable identifier for a device that persists across 539 * boots and reconfigurations, use {@link #getDescriptor()}. 540 * </p> 541 * 542 * @return The input device id. 543 */ getId()544 public int getId() { 545 return mId; 546 } 547 548 /** 549 * The controller number for a given input device. 550 * <p> 551 * Each gamepad or joystick is given a unique, positive controller number when initially 552 * configured by the system. This number may change due to events such as device disconnects / 553 * reconnects or user initiated reassignment. Any change in number will trigger an event that 554 * can be observed by registering an {@link InputManager.InputDeviceListener}. 555 * </p> 556 * <p> 557 * All input devices which are not gamepads or joysticks will be assigned a controller number 558 * of 0. 559 * </p> 560 * 561 * @return The controller number of the device. 562 */ getControllerNumber()563 public int getControllerNumber() { 564 return mControllerNumber; 565 } 566 567 /** 568 * The set of identifying information for type of input device. This 569 * information can be used by the system to configure appropriate settings 570 * for the device. 571 * 572 * @return The identifier object for this device 573 * @hide 574 */ getIdentifier()575 public InputDeviceIdentifier getIdentifier() { 576 return mIdentifier; 577 } 578 579 /** 580 * Gets a generation number for this input device. 581 * The generation number is incremented whenever the device is reconfigured and its 582 * properties may have changed. 583 * 584 * @return The generation number. 585 * 586 * @hide 587 */ getGeneration()588 public int getGeneration() { 589 return mGeneration; 590 } 591 592 /** 593 * Gets the vendor id for the given device, if available. 594 * <p> 595 * A vendor id uniquely identifies the company who manufactured the device. A value of 0 will 596 * be assigned where a vendor id is not available. 597 * </p> 598 * 599 * @return The vendor id of a given device 600 */ getVendorId()601 public int getVendorId() { 602 return mVendorId; 603 } 604 605 /** 606 * Gets the product id for the given device, if available. 607 * <p> 608 * A product id uniquely identifies which product within the address space of a given vendor, 609 * identified by the device's vendor id. A value of 0 will be assigned where a product id is 610 * not available. 611 * </p> 612 * 613 * @return The product id of a given device 614 */ getProductId()615 public int getProductId() { 616 return mProductId; 617 } 618 619 /** 620 * Gets the input device descriptor, which is a stable identifier for an input device. 621 * <p> 622 * An input device descriptor uniquely identifies an input device. Its value 623 * is intended to be persistent across system restarts, and should not change even 624 * if the input device is disconnected, reconnected or reconfigured at any time. 625 * </p><p> 626 * It is possible for there to be multiple {@link InputDevice} instances that have the 627 * same input device descriptor. This might happen in situations where a single 628 * human input device registers multiple {@link InputDevice} instances (HID collections) 629 * that describe separate features of the device, such as a keyboard that also 630 * has a trackpad. Alternately, it may be that the input devices are simply 631 * indistinguishable, such as two keyboards made by the same manufacturer. 632 * </p><p> 633 * The input device descriptor returned by {@link #getDescriptor} should only be 634 * used when an application needs to remember settings associated with a particular 635 * input device. For all other purposes when referring to a logical 636 * {@link InputDevice} instance at runtime use the id returned by {@link #getId()}. 637 * </p> 638 * 639 * @return The input device descriptor. 640 */ getDescriptor()641 public String getDescriptor() { 642 return mDescriptor; 643 } 644 645 /** 646 * Returns true if the device is a virtual input device rather than a real one, 647 * such as the virtual keyboard (see {@link KeyCharacterMap#VIRTUAL_KEYBOARD}). 648 * <p> 649 * Virtual input devices are provided to implement system-level functionality 650 * and should not be seen or configured by users. 651 * </p> 652 * 653 * @return True if the device is virtual. 654 * 655 * @see KeyCharacterMap#VIRTUAL_KEYBOARD 656 */ isVirtual()657 public boolean isVirtual() { 658 return mId < 0; 659 } 660 661 /** 662 * Returns true if the device is external (connected to USB or Bluetooth or some other 663 * peripheral bus), otherwise it is built-in. 664 * 665 * @return True if the device is external. 666 */ isExternal()667 public boolean isExternal() { 668 return mIsExternal; 669 } 670 671 /** 672 * Returns true if the device is a full keyboard. 673 * 674 * @return True if the device is a full keyboard. 675 * 676 * @hide 677 */ isFullKeyboard()678 public boolean isFullKeyboard() { 679 return (mSources & SOURCE_KEYBOARD) == SOURCE_KEYBOARD 680 && mKeyboardType == KEYBOARD_TYPE_ALPHABETIC; 681 } 682 683 /** 684 * Gets the name of this input device. 685 * @return The input device name. 686 */ getName()687 public String getName() { 688 return mName; 689 } 690 691 /** 692 * Gets the input sources supported by this input device as a combined bitfield. 693 * @return The supported input sources. 694 */ getSources()695 public int getSources() { 696 return mSources; 697 } 698 699 /** 700 * Determines whether the input device supports the given source or sources. 701 * 702 * @param source The input source or sources to check against. This can be a generic device 703 * type such as {@link InputDevice#SOURCE_MOUSE}, a more generic device class, such as 704 * {@link InputDevice#SOURCE_CLASS_POINTER}, or a combination of sources bitwise ORed together. 705 * @return Whether the device can produce all of the given sources. 706 */ supportsSource(int source)707 public boolean supportsSource(int source) { 708 return (mSources & source) == source; 709 } 710 711 /** 712 * Gets the keyboard type. 713 * @return The keyboard type. 714 */ getKeyboardType()715 public int getKeyboardType() { 716 return mKeyboardType; 717 } 718 719 /** 720 * Gets the key character map associated with this input device. 721 * @return The key character map. 722 */ getKeyCharacterMap()723 public KeyCharacterMap getKeyCharacterMap() { 724 return mKeyCharacterMap; 725 } 726 727 /** 728 * Gets whether the device is capable of producing the list of keycodes. 729 * @param keys The list of android keycodes to check for. 730 * @return An array of booleans where each member specifies whether the device is capable of 731 * generating the keycode given by the corresponding value at the same index in the keys array. 732 */ hasKeys(int... keys)733 public boolean[] hasKeys(int... keys) { 734 return InputManager.getInstance().deviceHasKeys(mId, keys); 735 } 736 737 /** 738 * Gets information about the range of values for a particular {@link MotionEvent} axis. 739 * If the device supports multiple sources, the same axis may have different meanings 740 * for each source. Returns information about the first axis found for any source. 741 * To obtain information about the axis for a specific source, use 742 * {@link #getMotionRange(int, int)}. 743 * 744 * @param axis The axis constant. 745 * @return The range of values, or null if the requested axis is not 746 * supported by the device. 747 * 748 * @see MotionEvent#AXIS_X 749 * @see MotionEvent#AXIS_Y 750 */ getMotionRange(int axis)751 public MotionRange getMotionRange(int axis) { 752 final int numRanges = mMotionRanges.size(); 753 for (int i = 0; i < numRanges; i++) { 754 final MotionRange range = mMotionRanges.get(i); 755 if (range.mAxis == axis) { 756 return range; 757 } 758 } 759 return null; 760 } 761 762 /** 763 * Gets information about the range of values for a particular {@link MotionEvent} axis 764 * used by a particular source on the device. 765 * If the device supports multiple sources, the same axis may have different meanings 766 * for each source. 767 * 768 * @param axis The axis constant. 769 * @param source The source for which to return information. 770 * @return The range of values, or null if the requested axis is not 771 * supported by the device. 772 * 773 * @see MotionEvent#AXIS_X 774 * @see MotionEvent#AXIS_Y 775 */ getMotionRange(int axis, int source)776 public MotionRange getMotionRange(int axis, int source) { 777 final int numRanges = mMotionRanges.size(); 778 for (int i = 0; i < numRanges; i++) { 779 final MotionRange range = mMotionRanges.get(i); 780 if (range.mAxis == axis && range.mSource == source) { 781 return range; 782 } 783 } 784 return null; 785 } 786 787 /** 788 * Gets the ranges for all axes supported by the device. 789 * @return The motion ranges for the device. 790 * 791 * @see #getMotionRange(int, int) 792 */ getMotionRanges()793 public List<MotionRange> getMotionRanges() { 794 return mMotionRanges; 795 } 796 797 // Called from native code. 798 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) addMotionRange(int axis, int source, float min, float max, float flat, float fuzz, float resolution)799 private void addMotionRange(int axis, int source, 800 float min, float max, float flat, float fuzz, float resolution) { 801 mMotionRanges.add(new MotionRange(axis, source, min, max, flat, fuzz, resolution)); 802 } 803 804 /** 805 * Gets the vibrator service associated with the device, if there is one. 806 * Even if the device does not have a vibrator, the result is never null. 807 * Use {@link Vibrator#hasVibrator} to determine whether a vibrator is 808 * present. 809 * 810 * Note that the vibrator associated with the device may be different from 811 * the system vibrator. To obtain an instance of the system vibrator instead, call 812 * {@link Context#getSystemService} with {@link Context#VIBRATOR_SERVICE} as argument. 813 * 814 * @return The vibrator service associated with the device, never null. 815 * @deprecated Use {@link #getVibratorManager()} to retrieve the default device vibrator. 816 */ 817 @Deprecated getVibrator()818 public Vibrator getVibrator() { 819 synchronized (mMotionRanges) { 820 if (mVibrator == null) { 821 if (mHasVibrator) { 822 mVibrator = InputManager.getInstance().getInputDeviceVibrator(mId, 823 VIBRATOR_ID_ALL); 824 } else { 825 mVibrator = NullVibrator.getInstance(); 826 } 827 } 828 return mVibrator; 829 } 830 } 831 832 /** 833 * Gets the vibrator manager associated with the device. 834 * Even if the device does not have a vibrator manager, the result is never null. 835 * Use {@link VibratorManager#getVibratorIds} to determine whether any vibrator is 836 * present. 837 * 838 * @return The vibrator manager associated with the device, never null. 839 */ 840 @NonNull getVibratorManager()841 public VibratorManager getVibratorManager() { 842 synchronized (mMotionRanges) { 843 if (mVibratorManager == null) { 844 mVibratorManager = InputManager.getInstance().getInputDeviceVibratorManager(mId); 845 } 846 } 847 return mVibratorManager; 848 } 849 850 /** 851 * Gets the battery state object associated with the device, if there is one. 852 * Even if the device does not have a battery, the result is never null. 853 * Use {@link BatteryState#isPresent} to determine whether a battery is 854 * present. 855 * 856 * @return The battery object associated with the device, never null. 857 */ 858 @NonNull getBatteryState()859 public BatteryState getBatteryState() { 860 if (mBatteryState == null) { 861 mBatteryState = InputManager.getInstance().getInputDeviceBatteryState(mId, mHasBattery); 862 } 863 return mBatteryState; 864 } 865 866 /** 867 * Gets the lights manager associated with the device, if there is one. 868 * Even if the device does not have lights, the result is never null. 869 * Use {@link LightsManager#getLights} to determine whether any lights is 870 * present. 871 * 872 * @return The lights manager associated with the device, never null. 873 */ getLightsManager()874 public @NonNull LightsManager getLightsManager() { 875 if (mLightsManager == null) { 876 mLightsManager = InputManager.getInstance().getInputDeviceLightsManager(mId); 877 } 878 return mLightsManager; 879 } 880 881 /** 882 * Gets the sensor manager service associated with the input device. 883 * Even if the device does not have a sensor, the result is never null. 884 * Use {@link SensorManager#getSensorList} to get a full list of all supported sensors. 885 * 886 * Note that the sensors associated with the device may be different from 887 * the system sensors, as typically they are builtin sensors physically attached to 888 * input devices. 889 * 890 * @return The sensor manager service associated with the device, never null. 891 */ getSensorManager()892 public @NonNull SensorManager getSensorManager() { 893 synchronized (mMotionRanges) { 894 if (mSensorManager == null) { 895 mSensorManager = InputManager.getInstance().getInputDeviceSensorManager(mId); 896 } 897 } 898 return mSensorManager; 899 } 900 901 /** 902 * Returns true if input device is enabled. 903 * @return Whether the input device is enabled. 904 */ isEnabled()905 public boolean isEnabled() { 906 return InputManager.getInstance().isInputDeviceEnabled(mId); 907 } 908 909 /** 910 * Enables the input device. 911 * 912 * @hide 913 */ 914 @RequiresPermission(android.Manifest.permission.DISABLE_INPUT_DEVICE) 915 @TestApi enable()916 public void enable() { 917 InputManager.getInstance().enableInputDevice(mId); 918 } 919 920 /** 921 * Disables the input device. 922 * 923 * @hide 924 */ 925 @RequiresPermission(android.Manifest.permission.DISABLE_INPUT_DEVICE) 926 @TestApi disable()927 public void disable() { 928 InputManager.getInstance().disableInputDevice(mId); 929 } 930 931 /** 932 * Reports whether the device has a built-in microphone. 933 * @return Whether the device has a built-in microphone. 934 */ hasMicrophone()935 public boolean hasMicrophone() { 936 return mHasMicrophone; 937 } 938 939 /** 940 * Reports whether the device has a button under its touchpad 941 * @return Whether the device has a button under its touchpad 942 * @hide 943 */ hasButtonUnderPad()944 public boolean hasButtonUnderPad() { 945 return mHasButtonUnderPad; 946 } 947 948 /** 949 * Reports whether the device has a sensor. 950 * @return Whether the device has a sensor. 951 * @hide 952 */ hasSensor()953 public boolean hasSensor() { 954 return mHasSensor; 955 } 956 957 /** 958 * Sets the current pointer type. 959 * @param pointerType the type of the pointer icon. 960 * @hide 961 */ setPointerType(int pointerType)962 public void setPointerType(int pointerType) { 963 InputManager.getInstance().setPointerIconType(pointerType); 964 } 965 966 /** 967 * Specifies the current custom pointer. 968 * @param icon the icon data. 969 * @hide 970 */ setCustomPointerIcon(PointerIcon icon)971 public void setCustomPointerIcon(PointerIcon icon) { 972 InputManager.getInstance().setCustomPointerIcon(icon); 973 } 974 975 /** 976 * Provides information about the range of values for a particular {@link MotionEvent} axis. 977 * 978 * @see InputDevice#getMotionRange(int) 979 */ 980 public static final class MotionRange { 981 private int mAxis; 982 private int mSource; 983 private float mMin; 984 private float mMax; 985 private float mFlat; 986 private float mFuzz; 987 private float mResolution; 988 MotionRange(int axis, int source, float min, float max, float flat, float fuzz, float resolution)989 private MotionRange(int axis, int source, float min, float max, float flat, float fuzz, 990 float resolution) { 991 mAxis = axis; 992 mSource = source; 993 mMin = min; 994 mMax = max; 995 mFlat = flat; 996 mFuzz = fuzz; 997 mResolution = resolution; 998 } 999 1000 /** 1001 * Gets the axis id. 1002 * @return The axis id. 1003 */ getAxis()1004 public int getAxis() { 1005 return mAxis; 1006 } 1007 1008 /** 1009 * Gets the source for which the axis is defined. 1010 * @return The source. 1011 */ getSource()1012 public int getSource() { 1013 return mSource; 1014 } 1015 1016 1017 /** 1018 * Determines whether the event is from the given source. 1019 * 1020 * @param source The input source to check against. This can be a specific device type, 1021 * such as {@link InputDevice#SOURCE_TOUCH_NAVIGATION}, or a more generic device class, 1022 * such as {@link InputDevice#SOURCE_CLASS_POINTER}. 1023 * @return Whether the event is from the given source. 1024 */ isFromSource(int source)1025 public boolean isFromSource(int source) { 1026 return (getSource() & source) == source; 1027 } 1028 1029 /** 1030 * Gets the inclusive minimum value for the axis. 1031 * @return The inclusive minimum value. 1032 */ getMin()1033 public float getMin() { 1034 return mMin; 1035 } 1036 1037 /** 1038 * Gets the inclusive maximum value for the axis. 1039 * @return The inclusive maximum value. 1040 */ getMax()1041 public float getMax() { 1042 return mMax; 1043 } 1044 1045 /** 1046 * Gets the range of the axis (difference between maximum and minimum). 1047 * @return The range of values. 1048 */ getRange()1049 public float getRange() { 1050 return mMax - mMin; 1051 } 1052 1053 /** 1054 * Gets the extent of the center flat position with respect to this axis. 1055 * <p> 1056 * For example, a flat value of 8 means that the center position is between -8 and +8. 1057 * This value is mainly useful for calibrating self-centering devices. 1058 * </p> 1059 * @return The extent of the center flat position. 1060 */ getFlat()1061 public float getFlat() { 1062 return mFlat; 1063 } 1064 1065 /** 1066 * Gets the error tolerance for input device measurements with respect to this axis. 1067 * <p> 1068 * For example, a value of 2 indicates that the measured value may be up to +/- 2 units 1069 * away from the actual value due to noise and device sensitivity limitations. 1070 * </p> 1071 * @return The error tolerance. 1072 */ getFuzz()1073 public float getFuzz() { 1074 return mFuzz; 1075 } 1076 1077 /** 1078 * Gets the resolution for input device measurements with respect to this axis. 1079 * @return The resolution in units per millimeter, or units per radian for rotational axes. 1080 */ getResolution()1081 public float getResolution() { 1082 return mResolution; 1083 } 1084 } 1085 1086 @Override writeToParcel(Parcel out, int flags)1087 public void writeToParcel(Parcel out, int flags) { 1088 mKeyCharacterMap.writeToParcel(out, flags); 1089 out.writeInt(mId); 1090 out.writeInt(mGeneration); 1091 out.writeInt(mControllerNumber); 1092 out.writeString(mName); 1093 out.writeInt(mVendorId); 1094 out.writeInt(mProductId); 1095 out.writeString(mDescriptor); 1096 out.writeInt(mIsExternal ? 1 : 0); 1097 out.writeInt(mSources); 1098 out.writeInt(mKeyboardType); 1099 out.writeInt(mHasVibrator ? 1 : 0); 1100 out.writeInt(mHasMicrophone ? 1 : 0); 1101 out.writeInt(mHasButtonUnderPad ? 1 : 0); 1102 out.writeInt(mHasSensor ? 1 : 0); 1103 out.writeInt(mHasBattery ? 1 : 0); 1104 1105 final int numRanges = mMotionRanges.size(); 1106 out.writeInt(numRanges); 1107 for (int i = 0; i < numRanges; i++) { 1108 MotionRange range = mMotionRanges.get(i); 1109 out.writeInt(range.mAxis); 1110 out.writeInt(range.mSource); 1111 out.writeFloat(range.mMin); 1112 out.writeFloat(range.mMax); 1113 out.writeFloat(range.mFlat); 1114 out.writeFloat(range.mFuzz); 1115 out.writeFloat(range.mResolution); 1116 } 1117 } 1118 1119 @Override describeContents()1120 public int describeContents() { 1121 return 0; 1122 } 1123 1124 @Override toString()1125 public String toString() { 1126 StringBuilder description = new StringBuilder(); 1127 description.append("Input Device ").append(mId).append(": ").append(mName).append("\n"); 1128 description.append(" Descriptor: ").append(mDescriptor).append("\n"); 1129 description.append(" Generation: ").append(mGeneration).append("\n"); 1130 description.append(" Location: ").append(mIsExternal ? "external" : "built-in").append("\n"); 1131 1132 description.append(" Keyboard Type: "); 1133 switch (mKeyboardType) { 1134 case KEYBOARD_TYPE_NONE: 1135 description.append("none"); 1136 break; 1137 case KEYBOARD_TYPE_NON_ALPHABETIC: 1138 description.append("non-alphabetic"); 1139 break; 1140 case KEYBOARD_TYPE_ALPHABETIC: 1141 description.append("alphabetic"); 1142 break; 1143 } 1144 description.append("\n"); 1145 1146 description.append(" Has Vibrator: ").append(mHasVibrator).append("\n"); 1147 1148 description.append(" Has Sensor: ").append(mHasSensor).append("\n"); 1149 1150 description.append(" Has battery: ").append(mHasBattery).append("\n"); 1151 1152 description.append(" Has mic: ").append(mHasMicrophone).append("\n"); 1153 1154 description.append(" Sources: 0x").append(Integer.toHexString(mSources)).append(" ("); 1155 appendSourceDescriptionIfApplicable(description, SOURCE_KEYBOARD, "keyboard"); 1156 appendSourceDescriptionIfApplicable(description, SOURCE_DPAD, "dpad"); 1157 appendSourceDescriptionIfApplicable(description, SOURCE_TOUCHSCREEN, "touchscreen"); 1158 appendSourceDescriptionIfApplicable(description, SOURCE_MOUSE, "mouse"); 1159 appendSourceDescriptionIfApplicable(description, SOURCE_STYLUS, "stylus"); 1160 appendSourceDescriptionIfApplicable(description, SOURCE_TRACKBALL, "trackball"); 1161 appendSourceDescriptionIfApplicable(description, SOURCE_MOUSE_RELATIVE, "mouse_relative"); 1162 appendSourceDescriptionIfApplicable(description, SOURCE_TOUCHPAD, "touchpad"); 1163 appendSourceDescriptionIfApplicable(description, SOURCE_JOYSTICK, "joystick"); 1164 appendSourceDescriptionIfApplicable(description, SOURCE_GAMEPAD, "gamepad"); 1165 description.append(" )\n"); 1166 1167 final int numAxes = mMotionRanges.size(); 1168 for (int i = 0; i < numAxes; i++) { 1169 MotionRange range = mMotionRanges.get(i); 1170 description.append(" ").append(MotionEvent.axisToString(range.mAxis)); 1171 description.append(": source=0x").append(Integer.toHexString(range.mSource)); 1172 description.append(" min=").append(range.mMin); 1173 description.append(" max=").append(range.mMax); 1174 description.append(" flat=").append(range.mFlat); 1175 description.append(" fuzz=").append(range.mFuzz); 1176 description.append(" resolution=").append(range.mResolution); 1177 description.append("\n"); 1178 } 1179 return description.toString(); 1180 } 1181 appendSourceDescriptionIfApplicable(StringBuilder description, int source, String sourceName)1182 private void appendSourceDescriptionIfApplicable(StringBuilder description, int source, 1183 String sourceName) { 1184 if ((mSources & source) == source) { 1185 description.append(" "); 1186 description.append(sourceName); 1187 } 1188 } 1189 } 1190