InputDevice.java revision e7a9ae8ba0fb7fc61960e3facd0c5534e9ffce1e
1031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova/* 2031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova * Copyright (C) 2010 The Android Open Source Project 3031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova * 4031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova * Licensed under the Apache License, Version 2.0 (the "License"); 5031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova * you may not use this file except in compliance with the License. 6031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova * You may obtain a copy of the License at 7031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova * 8031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova * http://www.apache.org/licenses/LICENSE-2.0 9031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova * 10031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova * Unless required by applicable law or agreed to in writing, software 11031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova * distributed under the License is distributed on an "AS IS" BASIS, 12031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova * See the License for the specific language governing permissions and 14031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova * limitations under the License. 15031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova */ 16031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova 17031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtovapackage android.view; 187f31bb047820bd5bbf3baab461d24d49f1128052Alexandru-Andrei Rotaru 19031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtovaimport android.content.Context; 200de748d833bef8e08329ef1abb9b681391e34ac8yuemingwimport android.hardware.input.InputManager; 2108841efcdf4ff8cf5d743fd5f6f995730b5f876farangelovimport android.os.Parcel; 22b6ef86985dd79923c08ea6ecb1c8c56fa76b5193Alex Chauimport android.os.Parcelable; 23a173064047d304837d907b9b39ece5c14adf2b25Eran Messeriimport android.os.Vibrator; 24a173064047d304837d907b9b39ece5c14adf2b25Eran Messeriimport android.os.NullVibrator; 25e3d9c099e5b27779ea112408e5a74599d1cfc8ecyuemingw 26031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtovaimport java.util.ArrayList; 27031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtovaimport java.util.List; 28031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova 29031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova/** 3004d61ae6c3ea1ddba22a8557f2fa372cd13b26efSudheer Shanka * Describes the capabilities of a particular input device. 31e3d9c099e5b27779ea112408e5a74599d1cfc8ecyuemingw * <p> 327f31bb047820bd5bbf3baab461d24d49f1128052Alexandru-Andrei Rotaru * Each input device may support multiple classes of input. For example, a multi-function 337f31bb047820bd5bbf3baab461d24d49f1128052Alexandru-Andrei Rotaru * keyboard may compose the capabilities of a standard keyboard together with a track pad mouse 34031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova * or other pointing device. 35031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova * </p><p> 36031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova * Some input devices present multiple distinguishable sources of input. 37031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova * Applications can query the framework about the characteristics of each distinct source. 38031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova * </p><p> 39031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova * As a further wrinkle, different kinds of input sources uses different coordinate systems 40031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova * to describe motion events. Refer to the comments on the input source constants for 41031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova * the appropriate interpretation. 42031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova * </p> 43031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova */ 44031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtovapublic final class InputDevice implements Parcelable { 45031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova private final int mId; 46031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova private final int mGeneration; 47031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova private final String mName; 48031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova private final String mDescriptor; 49031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova private final boolean mIsExternal; 50031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova private final int mSources; 51031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova private final int mKeyboardType; 52031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova private final KeyCharacterMap mKeyCharacterMap; 53031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova private final boolean mHasVibrator; 54031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova private final ArrayList<MotionRange> mMotionRanges = new ArrayList<MotionRange>(); 55031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova 56031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova private Vibrator mVibrator; // guarded by mMotionRanges during initialization 57031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova 58031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova /** 59031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova * A mask for input source classes. 60031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova * 61031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova * Each distinct input source constant has one or more input source class bits set to 62031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova * specify the desired interpretation for its input events. 63031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova */ 64031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova public static final int SOURCE_CLASS_MASK = 0x000000ff; 65031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova 66031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova /** 67031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova * The input source has no class. 68a173064047d304837d907b9b39ece5c14adf2b25Eran Messeri * 690de748d833bef8e08329ef1abb9b681391e34ac8yuemingw * It is up to the application to determine how to handle the device based on the device type. 7008841efcdf4ff8cf5d743fd5f6f995730b5f876farangelov */ 718bae4eaa4db74c71d5658d8ee1905be8ecf4dfc2arangelov public static final int SOURCE_CLASS_NONE = 0x00000000; 72c4f87e9ceb4d5ce78c1663912bc166e0d41554aaPavel Grafov 73a173064047d304837d907b9b39ece5c14adf2b25Eran Messeri /** 7494d56761249a8e8c073867c17bba59b4a898f113Eran Messeri * The input source has buttons or keys. 7594d56761249a8e8c073867c17bba59b4a898f113Eran Messeri * Examples: {@link #SOURCE_KEYBOARD}, {@link #SOURCE_DPAD}. 76a173064047d304837d907b9b39ece5c14adf2b25Eran Messeri * 77a173064047d304837d907b9b39ece5c14adf2b25Eran Messeri * A {@link KeyEvent} should be interpreted as a button or key press. 78c4f87e9ceb4d5ce78c1663912bc166e0d41554aaPavel Grafov * 797f31bb047820bd5bbf3baab461d24d49f1128052Alexandru-Andrei Rotaru * Use {@link #getKeyCharacterMap} to query the device's button and key mappings. 807f31bb047820bd5bbf3baab461d24d49f1128052Alexandru-Andrei Rotaru */ 817f31bb047820bd5bbf3baab461d24d49f1128052Alexandru-Andrei Rotaru public static final int SOURCE_CLASS_BUTTON = 0x00000001; 827f31bb047820bd5bbf3baab461d24d49f1128052Alexandru-Andrei Rotaru 837f31bb047820bd5bbf3baab461d24d49f1128052Alexandru-Andrei Rotaru /** 847f31bb047820bd5bbf3baab461d24d49f1128052Alexandru-Andrei Rotaru * The input source is a pointing device associated with a display. 857f31bb047820bd5bbf3baab461d24d49f1128052Alexandru-Andrei Rotaru * Examples: {@link #SOURCE_TOUCHSCREEN}, {@link #SOURCE_MOUSE}. 867f31bb047820bd5bbf3baab461d24d49f1128052Alexandru-Andrei Rotaru * 877f31bb047820bd5bbf3baab461d24d49f1128052Alexandru-Andrei Rotaru * A {@link MotionEvent} should be interpreted as absolute coordinates in 887f31bb047820bd5bbf3baab461d24d49f1128052Alexandru-Andrei Rotaru * display units according to the {@link View} hierarchy. Pointer down/up indicated when 897f31bb047820bd5bbf3baab461d24d49f1128052Alexandru-Andrei Rotaru * the finger touches the display or when the selection button is pressed/released. 907f31bb047820bd5bbf3baab461d24d49f1128052Alexandru-Andrei Rotaru * 917f31bb047820bd5bbf3baab461d24d49f1128052Alexandru-Andrei Rotaru * Use {@link #getMotionRange} to query the range of the pointing device. Some devices permit 927f31bb047820bd5bbf3baab461d24d49f1128052Alexandru-Andrei Rotaru * touches outside the display area so the effective range may be somewhat smaller or larger 937f31bb047820bd5bbf3baab461d24d49f1128052Alexandru-Andrei Rotaru * than the actual display size. 947f31bb047820bd5bbf3baab461d24d49f1128052Alexandru-Andrei Rotaru */ 957f31bb047820bd5bbf3baab461d24d49f1128052Alexandru-Andrei Rotaru public static final int SOURCE_CLASS_POINTER = 0x00000002; 96c4f87e9ceb4d5ce78c1663912bc166e0d41554aaPavel Grafov 97c4f87e9ceb4d5ce78c1663912bc166e0d41554aaPavel Grafov /** 98c4f87e9ceb4d5ce78c1663912bc166e0d41554aaPavel Grafov * The input source is a trackball navigation device. 99ecf0f22e5831832afb48c86abfaa81234c8db619Eran Messeri * Examples: {@link #SOURCE_TRACKBALL}. 100ecf0f22e5831832afb48c86abfaa81234c8db619Eran Messeri * 101ecf0f22e5831832afb48c86abfaa81234c8db619Eran Messeri * A {@link MotionEvent} should be interpreted as relative movements in device-specific 102ecf0f22e5831832afb48c86abfaa81234c8db619Eran Messeri * units used for navigation purposes. Pointer down/up indicates when the selection button 103ecf0f22e5831832afb48c86abfaa81234c8db619Eran Messeri * is pressed/released. 104b6ef86985dd79923c08ea6ecb1c8c56fa76b5193Alex Chau * 105b6ef86985dd79923c08ea6ecb1c8c56fa76b5193Alex Chau * Use {@link #getMotionRange} to query the range of motion. 106b6ef86985dd79923c08ea6ecb1c8c56fa76b5193Alex Chau */ 107b6ef86985dd79923c08ea6ecb1c8c56fa76b5193Alex Chau public static final int SOURCE_CLASS_TRACKBALL = 0x00000004; 108b6ef86985dd79923c08ea6ecb1c8c56fa76b5193Alex Chau 10993ae42b04debca35cdc23feef0cf54c9e6ca4400Alex Chau /** 11093ae42b04debca35cdc23feef0cf54c9e6ca4400Alex Chau * The input source is an absolute positioning device not associated with a display 11193ae42b04debca35cdc23feef0cf54c9e6ca4400Alex Chau * (unlike {@link #SOURCE_CLASS_POINTER}). 11293ae42b04debca35cdc23feef0cf54c9e6ca4400Alex Chau * 11393ae42b04debca35cdc23feef0cf54c9e6ca4400Alex Chau * A {@link MotionEvent} should be interpreted as absolute coordinates in 11493ae42b04debca35cdc23feef0cf54c9e6ca4400Alex Chau * device-specific surface units. 11593ae42b04debca35cdc23feef0cf54c9e6ca4400Alex Chau * 11693ae42b04debca35cdc23feef0cf54c9e6ca4400Alex Chau * Use {@link #getMotionRange} to query the range of positions. 11793ae42b04debca35cdc23feef0cf54c9e6ca4400Alex Chau */ 11893ae42b04debca35cdc23feef0cf54c9e6ca4400Alex Chau public static final int SOURCE_CLASS_POSITION = 0x00000008; 11993ae42b04debca35cdc23feef0cf54c9e6ca4400Alex Chau 12093ae42b04debca35cdc23feef0cf54c9e6ca4400Alex Chau /** 12193ae42b04debca35cdc23feef0cf54c9e6ca4400Alex Chau * The input source is a joystick. 12293ae42b04debca35cdc23feef0cf54c9e6ca4400Alex Chau * 12393ae42b04debca35cdc23feef0cf54c9e6ca4400Alex Chau * A {@link MotionEvent} should be interpreted as absolute joystick movements. 12493ae42b04debca35cdc23feef0cf54c9e6ca4400Alex Chau * 12593ae42b04debca35cdc23feef0cf54c9e6ca4400Alex Chau * Use {@link #getMotionRange} to query the range of positions. 126792d58fbcef3da36dbde5fd8b0cf5a5b972bd12eVladislav Kuzkokov */ 127792d58fbcef3da36dbde5fd8b0cf5a5b972bd12eVladislav Kuzkokov public static final int SOURCE_CLASS_JOYSTICK = 0x00000010; 128792d58fbcef3da36dbde5fd8b0cf5a5b972bd12eVladislav Kuzkokov 129792d58fbcef3da36dbde5fd8b0cf5a5b972bd12eVladislav Kuzkokov /** 130792d58fbcef3da36dbde5fd8b0cf5a5b972bd12eVladislav Kuzkokov * The input source is unknown. 131792d58fbcef3da36dbde5fd8b0cf5a5b972bd12eVladislav Kuzkokov */ 132792d58fbcef3da36dbde5fd8b0cf5a5b972bd12eVladislav Kuzkokov public static final int SOURCE_UNKNOWN = 0x00000000; 133792d58fbcef3da36dbde5fd8b0cf5a5b972bd12eVladislav Kuzkokov 134792d58fbcef3da36dbde5fd8b0cf5a5b972bd12eVladislav Kuzkokov /** 135792d58fbcef3da36dbde5fd8b0cf5a5b972bd12eVladislav Kuzkokov * The input source is a keyboard. 136792d58fbcef3da36dbde5fd8b0cf5a5b972bd12eVladislav Kuzkokov * 137792d58fbcef3da36dbde5fd8b0cf5a5b972bd12eVladislav Kuzkokov * This source indicates pretty much anything that has buttons. Use 138792d58fbcef3da36dbde5fd8b0cf5a5b972bd12eVladislav Kuzkokov * {@link #getKeyboardType()} to determine whether the keyboard has alphabetic keys 139792d58fbcef3da36dbde5fd8b0cf5a5b972bd12eVladislav Kuzkokov * and can be used to enter text. 140792d58fbcef3da36dbde5fd8b0cf5a5b972bd12eVladislav Kuzkokov * 14104d61ae6c3ea1ddba22a8557f2fa372cd13b26efSudheer Shanka * @see #SOURCE_CLASS_BUTTON 14204d61ae6c3ea1ddba22a8557f2fa372cd13b26efSudheer Shanka */ 14304d61ae6c3ea1ddba22a8557f2fa372cd13b26efSudheer Shanka public static final int SOURCE_KEYBOARD = 0x00000100 | SOURCE_CLASS_BUTTON; 14404d61ae6c3ea1ddba22a8557f2fa372cd13b26efSudheer Shanka 14504d61ae6c3ea1ddba22a8557f2fa372cd13b26efSudheer Shanka /** 14604d61ae6c3ea1ddba22a8557f2fa372cd13b26efSudheer Shanka * The input source is a DPad. 14704d61ae6c3ea1ddba22a8557f2fa372cd13b26efSudheer Shanka * 14804d61ae6c3ea1ddba22a8557f2fa372cd13b26efSudheer Shanka * @see #SOURCE_CLASS_BUTTON 14904d61ae6c3ea1ddba22a8557f2fa372cd13b26efSudheer Shanka */ 15004d61ae6c3ea1ddba22a8557f2fa372cd13b26efSudheer Shanka public static final int SOURCE_DPAD = 0x00000200 | SOURCE_CLASS_BUTTON; 151e3d9c099e5b27779ea112408e5a74599d1cfc8ecyuemingw 152e3d9c099e5b27779ea112408e5a74599d1cfc8ecyuemingw /** 153e3d9c099e5b27779ea112408e5a74599d1cfc8ecyuemingw * The input source is a game pad. 154e3d9c099e5b27779ea112408e5a74599d1cfc8ecyuemingw * (It may also be a {@link #SOURCE_JOYSTICK}). 155e3d9c099e5b27779ea112408e5a74599d1cfc8ecyuemingw * 156e3d9c099e5b27779ea112408e5a74599d1cfc8ecyuemingw * @see #SOURCE_CLASS_BUTTON 157e3d9c099e5b27779ea112408e5a74599d1cfc8ecyuemingw */ 158e3d9c099e5b27779ea112408e5a74599d1cfc8ecyuemingw public static final int SOURCE_GAMEPAD = 0x00000400 | SOURCE_CLASS_BUTTON; 159e3d9c099e5b27779ea112408e5a74599d1cfc8ecyuemingw 160e3d9c099e5b27779ea112408e5a74599d1cfc8ecyuemingw /** 161e3d9c099e5b27779ea112408e5a74599d1cfc8ecyuemingw * The input source is a touch screen pointing device. 162e3d9c099e5b27779ea112408e5a74599d1cfc8ecyuemingw * 163e3d9c099e5b27779ea112408e5a74599d1cfc8ecyuemingw * @see #SOURCE_CLASS_POINTER 164e3d9c099e5b27779ea112408e5a74599d1cfc8ecyuemingw */ 165e3d9c099e5b27779ea112408e5a74599d1cfc8ecyuemingw public static final int SOURCE_TOUCHSCREEN = 0x00001000 | SOURCE_CLASS_POINTER; 166e3d9c099e5b27779ea112408e5a74599d1cfc8ecyuemingw 167e3d9c099e5b27779ea112408e5a74599d1cfc8ecyuemingw /** 168e3d9c099e5b27779ea112408e5a74599d1cfc8ecyuemingw * The input source is a mouse pointing device. 169e3d9c099e5b27779ea112408e5a74599d1cfc8ecyuemingw * This code is also used for other mouse-like pointing devices such as trackpads 170e3d9c099e5b27779ea112408e5a74599d1cfc8ecyuemingw * and trackpoints. 171e3d9c099e5b27779ea112408e5a74599d1cfc8ecyuemingw * 172e3d9c099e5b27779ea112408e5a74599d1cfc8ecyuemingw * @see #SOURCE_CLASS_POINTER 173e3d9c099e5b27779ea112408e5a74599d1cfc8ecyuemingw */ 174e3d9c099e5b27779ea112408e5a74599d1cfc8ecyuemingw public static final int SOURCE_MOUSE = 0x00002000 | SOURCE_CLASS_POINTER; 175e3d9c099e5b27779ea112408e5a74599d1cfc8ecyuemingw 176e3d9c099e5b27779ea112408e5a74599d1cfc8ecyuemingw /** 177e3d9c099e5b27779ea112408e5a74599d1cfc8ecyuemingw * The input source is a stylus pointing device. 178e3d9c099e5b27779ea112408e5a74599d1cfc8ecyuemingw * <p> 179031a2f1aafbc4e39ab5601567862d498e8949538Lenka Trochtova * Note that this bit merely indicates that an input device is capable of obtaining 180 * input from a stylus. To determine whether a given touch event was produced 181 * by a stylus, examine the tool type returned by {@link MotionEvent#getToolType(int)} 182 * for each individual pointer. 183 * </p><p> 184 * A single touch event may multiple pointers with different tool types, 185 * such as an event that has one pointer with tool type 186 * {@link MotionEvent#TOOL_TYPE_FINGER} and another pointer with tool type 187 * {@link MotionEvent#TOOL_TYPE_STYLUS}. So it is important to examine 188 * the tool type of each pointer, regardless of the source reported 189 * by {@link MotionEvent#getSource()}. 190 * </p> 191 * 192 * @see #SOURCE_CLASS_POINTER 193 */ 194 public static final int SOURCE_STYLUS = 0x00004000 | SOURCE_CLASS_POINTER; 195 196 /** 197 * The input source is a trackball. 198 * 199 * @see #SOURCE_CLASS_TRACKBALL 200 */ 201 public static final int SOURCE_TRACKBALL = 0x00010000 | SOURCE_CLASS_TRACKBALL; 202 203 /** 204 * The input source is a touch pad or digitizer tablet that is not 205 * associated with a display (unlike {@link #SOURCE_TOUCHSCREEN}). 206 * 207 * @see #SOURCE_CLASS_POSITION 208 */ 209 public static final int SOURCE_TOUCHPAD = 0x00100000 | SOURCE_CLASS_POSITION; 210 211 /** 212 * The input source is a touch device whose motions should be interpreted as navigation events. 213 * 214 * For example, an upward swipe should be as an upward focus traversal in the same manner as 215 * pressing up on a D-Pad would be. Swipes to the left, right and down should be treated in a 216 * similar manner. 217 * 218 * @see #SOURCE_CLASS_NONE 219 */ 220 public static final int SOURCE_TOUCH_NAVIGATION = 0x00200000 | SOURCE_CLASS_NONE; 221 222 /** 223 * The input source is a joystick. 224 * (It may also be a {@link #SOURCE_GAMEPAD}). 225 * 226 * @see #SOURCE_CLASS_JOYSTICK 227 */ 228 public static final int SOURCE_JOYSTICK = 0x01000000 | SOURCE_CLASS_JOYSTICK; 229 230 /** 231 * A special input source constant that is used when filtering input devices 232 * to match devices that provide any type of input source. 233 */ 234 public static final int SOURCE_ANY = 0xffffff00; 235 236 /** 237 * Constant for retrieving the range of values for {@link MotionEvent#AXIS_X}. 238 * 239 * @see #getMotionRange 240 * @deprecated Use {@link MotionEvent#AXIS_X} instead. 241 */ 242 @Deprecated 243 public static final int MOTION_RANGE_X = MotionEvent.AXIS_X; 244 245 /** 246 * Constant for retrieving the range of values for {@link MotionEvent#AXIS_Y}. 247 * 248 * @see #getMotionRange 249 * @deprecated Use {@link MotionEvent#AXIS_Y} instead. 250 */ 251 @Deprecated 252 public static final int MOTION_RANGE_Y = MotionEvent.AXIS_Y; 253 254 /** 255 * Constant for retrieving the range of values for {@link MotionEvent#AXIS_PRESSURE}. 256 * 257 * @see #getMotionRange 258 * @deprecated Use {@link MotionEvent#AXIS_PRESSURE} instead. 259 */ 260 @Deprecated 261 public static final int MOTION_RANGE_PRESSURE = MotionEvent.AXIS_PRESSURE; 262 263 /** 264 * Constant for retrieving the range of values for {@link MotionEvent#AXIS_SIZE}. 265 * 266 * @see #getMotionRange 267 * @deprecated Use {@link MotionEvent#AXIS_SIZE} instead. 268 */ 269 @Deprecated 270 public static final int MOTION_RANGE_SIZE = MotionEvent.AXIS_SIZE; 271 272 /** 273 * Constant for retrieving the range of values for {@link MotionEvent#AXIS_TOUCH_MAJOR}. 274 * 275 * @see #getMotionRange 276 * @deprecated Use {@link MotionEvent#AXIS_TOUCH_MAJOR} instead. 277 */ 278 @Deprecated 279 public static final int MOTION_RANGE_TOUCH_MAJOR = MotionEvent.AXIS_TOUCH_MAJOR; 280 281 /** 282 * Constant for retrieving the range of values for {@link MotionEvent#AXIS_TOUCH_MINOR}. 283 * 284 * @see #getMotionRange 285 * @deprecated Use {@link MotionEvent#AXIS_TOUCH_MINOR} instead. 286 */ 287 @Deprecated 288 public static final int MOTION_RANGE_TOUCH_MINOR = MotionEvent.AXIS_TOUCH_MINOR; 289 290 /** 291 * Constant for retrieving the range of values for {@link MotionEvent#AXIS_TOOL_MAJOR}. 292 * 293 * @see #getMotionRange 294 * @deprecated Use {@link MotionEvent#AXIS_TOOL_MAJOR} instead. 295 */ 296 @Deprecated 297 public static final int MOTION_RANGE_TOOL_MAJOR = MotionEvent.AXIS_TOOL_MAJOR; 298 299 /** 300 * Constant for retrieving the range of values for {@link MotionEvent#AXIS_TOOL_MINOR}. 301 * 302 * @see #getMotionRange 303 * @deprecated Use {@link MotionEvent#AXIS_TOOL_MINOR} instead. 304 */ 305 @Deprecated 306 public static final int MOTION_RANGE_TOOL_MINOR = MotionEvent.AXIS_TOOL_MINOR; 307 308 /** 309 * Constant for retrieving the range of values for {@link MotionEvent#AXIS_ORIENTATION}. 310 * 311 * @see #getMotionRange 312 * @deprecated Use {@link MotionEvent#AXIS_ORIENTATION} instead. 313 */ 314 @Deprecated 315 public static final int MOTION_RANGE_ORIENTATION = MotionEvent.AXIS_ORIENTATION; 316 317 /** 318 * There is no keyboard. 319 */ 320 public static final int KEYBOARD_TYPE_NONE = 0; 321 322 /** 323 * The keyboard is not fully alphabetic. It may be a numeric keypad or an assortment 324 * of buttons that are not mapped as alphabetic keys suitable for text input. 325 */ 326 public static final int KEYBOARD_TYPE_NON_ALPHABETIC = 1; 327 328 /** 329 * The keyboard supports a complement of alphabetic keys. 330 */ 331 public static final int KEYBOARD_TYPE_ALPHABETIC = 2; 332 333 public static final Parcelable.Creator<InputDevice> CREATOR = 334 new Parcelable.Creator<InputDevice>() { 335 public InputDevice createFromParcel(Parcel in) { 336 return new InputDevice(in); 337 } 338 public InputDevice[] newArray(int size) { 339 return new InputDevice[size]; 340 } 341 }; 342 343 // Called by native code. 344 private InputDevice(int id, int generation, String name, String descriptor, 345 boolean isExternal, int sources, 346 int keyboardType, KeyCharacterMap keyCharacterMap, boolean hasVibrator) { 347 mId = id; 348 mGeneration = generation; 349 mName = name; 350 mDescriptor = descriptor; 351 mIsExternal = isExternal; 352 mSources = sources; 353 mKeyboardType = keyboardType; 354 mKeyCharacterMap = keyCharacterMap; 355 mHasVibrator = hasVibrator; 356 } 357 358 private InputDevice(Parcel in) { 359 mId = in.readInt(); 360 mGeneration = in.readInt(); 361 mName = in.readString(); 362 mDescriptor = in.readString(); 363 mIsExternal = in.readInt() != 0; 364 mSources = in.readInt(); 365 mKeyboardType = in.readInt(); 366 mKeyCharacterMap = KeyCharacterMap.CREATOR.createFromParcel(in); 367 mHasVibrator = in.readInt() != 0; 368 369 for (;;) { 370 int axis = in.readInt(); 371 if (axis < 0) { 372 break; 373 } 374 addMotionRange(axis, in.readInt(), 375 in.readFloat(), in.readFloat(), in.readFloat(), in.readFloat()); 376 } 377 } 378 379 /** 380 * Gets information about the input device with the specified id. 381 * @param id The device id. 382 * @return The input device or null if not found. 383 */ 384 public static InputDevice getDevice(int id) { 385 return InputManager.getInstance().getInputDevice(id); 386 } 387 388 /** 389 * Gets the ids of all input devices in the system. 390 * @return The input device ids. 391 */ 392 public static int[] getDeviceIds() { 393 return InputManager.getInstance().getInputDeviceIds(); 394 } 395 396 /** 397 * Gets the input device id. 398 * <p> 399 * Each input device receives a unique id when it is first configured 400 * by the system. The input device id may change when the system is restarted or if the 401 * input device is disconnected, reconnected or reconfigured at any time. 402 * If you require a stable identifier for a device that persists across 403 * boots and reconfigurations, use {@link #getDescriptor()}. 404 * </p> 405 * 406 * @return The input device id. 407 */ 408 public int getId() { 409 return mId; 410 } 411 412 /** 413 * Gets a generation number for this input device. 414 * The generation number is incremented whenever the device is reconfigured and its 415 * properties may have changed. 416 * 417 * @return The generation number. 418 * 419 * @hide 420 */ 421 public int getGeneration() { 422 return mGeneration; 423 } 424 425 /** 426 * Gets the input device descriptor, which is a stable identifier for an input device. 427 * <p> 428 * An input device descriptor uniquely identifies an input device. Its value 429 * is intended to be persistent across system restarts, and should not change even 430 * if the input device is disconnected, reconnected or reconfigured at any time. 431 * </p><p> 432 * It is possible for there to be multiple {@link InputDevice} instances that have the 433 * same input device descriptor. This might happen in situations where a single 434 * human input device registers multiple {@link InputDevice} instances (HID collections) 435 * that describe separate features of the device, such as a keyboard that also 436 * has a trackpad. Alternately, it may be that the input devices are simply 437 * indistinguishable, such as two keyboards made by the same manufacturer. 438 * </p><p> 439 * The input device descriptor returned by {@link #getDescriptor} should only be 440 * used when an application needs to remember settings associated with a particular 441 * input device. For all other purposes when referring to a logical 442 * {@link InputDevice} instance at runtime use the id returned by {@link #getId()}. 443 * </p> 444 * 445 * @return The input device descriptor. 446 */ 447 public String getDescriptor() { 448 return mDescriptor; 449 } 450 451 /** 452 * Returns true if the device is a virtual input device rather than a real one, 453 * such as the virtual keyboard (see {@link KeyCharacterMap#VIRTUAL_KEYBOARD}). 454 * <p> 455 * Virtual input devices are provided to implement system-level functionality 456 * and should not be seen or configured by users. 457 * </p> 458 * 459 * @return True if the device is virtual. 460 * 461 * @see KeyCharacterMap#VIRTUAL_KEYBOARD 462 */ 463 public boolean isVirtual() { 464 return mId < 0; 465 } 466 467 /** 468 * Returns true if the device is external (connected to USB or Bluetooth or some other 469 * peripheral bus), otherwise it is built-in. 470 * 471 * @return True if the device is external. 472 * 473 * @hide 474 */ 475 public boolean isExternal() { 476 return mIsExternal; 477 } 478 479 /** 480 * Returns true if the device is a full keyboard. 481 * 482 * @return True if the device is a full keyboard. 483 * 484 * @hide 485 */ 486 public boolean isFullKeyboard() { 487 return (mSources & SOURCE_KEYBOARD) == SOURCE_KEYBOARD 488 && mKeyboardType == KEYBOARD_TYPE_ALPHABETIC; 489 } 490 491 /** 492 * Gets the name of this input device. 493 * @return The input device name. 494 */ 495 public String getName() { 496 return mName; 497 } 498 499 /** 500 * Gets the input sources supported by this input device as a combined bitfield. 501 * @return The supported input sources. 502 */ 503 public int getSources() { 504 return mSources; 505 } 506 507 /** 508 * Gets the keyboard type. 509 * @return The keyboard type. 510 */ 511 public int getKeyboardType() { 512 return mKeyboardType; 513 } 514 515 /** 516 * Gets the key character map associated with this input device. 517 * @return The key character map. 518 */ 519 public KeyCharacterMap getKeyCharacterMap() { 520 return mKeyCharacterMap; 521 } 522 523 /** 524 * Gets information about the range of values for a particular {@link MotionEvent} axis. 525 * If the device supports multiple sources, the same axis may have different meanings 526 * for each source. Returns information about the first axis found for any source. 527 * To obtain information about the axis for a specific source, use 528 * {@link #getMotionRange(int, int)}. 529 * 530 * @param axis The axis constant. 531 * @return The range of values, or null if the requested axis is not 532 * supported by the device. 533 * 534 * @see MotionEvent#AXIS_X 535 * @see MotionEvent#AXIS_Y 536 * @see #getSupportedAxes() 537 */ 538 public MotionRange getMotionRange(int axis) { 539 final int numRanges = mMotionRanges.size(); 540 for (int i = 0; i < numRanges; i++) { 541 final MotionRange range = mMotionRanges.get(i); 542 if (range.mAxis == axis) { 543 return range; 544 } 545 } 546 return null; 547 } 548 549 /** 550 * Gets information about the range of values for a particular {@link MotionEvent} axis 551 * used by a particular source on the device. 552 * If the device supports multiple sources, the same axis may have different meanings 553 * for each source. 554 * 555 * @param axis The axis constant. 556 * @param source The source for which to return information. 557 * @return The range of values, or null if the requested axis is not 558 * supported by the device. 559 * 560 * @see MotionEvent#AXIS_X 561 * @see MotionEvent#AXIS_Y 562 * @see #getSupportedAxes() 563 */ 564 public MotionRange getMotionRange(int axis, int source) { 565 final int numRanges = mMotionRanges.size(); 566 for (int i = 0; i < numRanges; i++) { 567 final MotionRange range = mMotionRanges.get(i); 568 if (range.mAxis == axis && range.mSource == source) { 569 return range; 570 } 571 } 572 return null; 573 } 574 575 /** 576 * Gets the ranges for all axes supported by the device. 577 * @return The motion ranges for the device. 578 * 579 * @see #getMotionRange(int, int) 580 */ 581 public List<MotionRange> getMotionRanges() { 582 return mMotionRanges; 583 } 584 585 // Called from native code. 586 private void addMotionRange(int axis, int source, 587 float min, float max, float flat, float fuzz) { 588 mMotionRanges.add(new MotionRange(axis, source, min, max, flat, fuzz)); 589 } 590 591 /** 592 * Gets the vibrator service associated with the device, if there is one. 593 * Even if the device does not have a vibrator, the result is never null. 594 * Use {@link Vibrator#hasVibrator} to determine whether a vibrator is 595 * present. 596 * 597 * Note that the vibrator associated with the device may be different from 598 * the system vibrator. To obtain an instance of the system vibrator instead, call 599 * {@link Context#getSystemService} with {@link Context#VIBRATOR_SERVICE} as argument. 600 * 601 * @return The vibrator service associated with the device, never null. 602 */ 603 public Vibrator getVibrator() { 604 synchronized (mMotionRanges) { 605 if (mVibrator == null) { 606 if (mHasVibrator) { 607 mVibrator = InputManager.getInstance().getInputDeviceVibrator(mId); 608 } else { 609 mVibrator = NullVibrator.getInstance(); 610 } 611 } 612 return mVibrator; 613 } 614 } 615 616 /** 617 * Provides information about the range of values for a particular {@link MotionEvent} axis. 618 * 619 * @see InputDevice#getMotionRange(int) 620 */ 621 public static final class MotionRange { 622 private int mAxis; 623 private int mSource; 624 private float mMin; 625 private float mMax; 626 private float mFlat; 627 private float mFuzz; 628 629 private MotionRange(int axis, int source, float min, float max, float flat, float fuzz) { 630 mAxis = axis; 631 mSource = source; 632 mMin = min; 633 mMax = max; 634 mFlat = flat; 635 mFuzz = fuzz; 636 } 637 638 /** 639 * Gets the axis id. 640 * @return The axis id. 641 */ 642 public int getAxis() { 643 return mAxis; 644 } 645 646 /** 647 * Gets the source for which the axis is defined. 648 * @return The source. 649 */ 650 public int getSource() { 651 return mSource; 652 } 653 654 655 /** 656 * Determines whether the event is from the given source. 657 * 658 * @param source The input source to check against. This can be a specific device type, 659 * such as {@link InputDevice#SOURCE_TOUCH_NAVIGATION}, or a more generic device class, 660 * such as {@link InputDevice#SOURCE_CLASS_POINTER}. 661 * @return Whether the event is from the given source. 662 */ 663 public boolean isFromSource(int source) { 664 return (getSource() & source) == source; 665 } 666 667 /** 668 * Gets the inclusive minimum value for the axis. 669 * @return The inclusive minimum value. 670 */ 671 public float getMin() { 672 return mMin; 673 } 674 675 /** 676 * Gets the inclusive maximum value for the axis. 677 * @return The inclusive maximum value. 678 */ 679 public float getMax() { 680 return mMax; 681 } 682 683 /** 684 * Gets the range of the axis (difference between maximum and minimum). 685 * @return The range of values. 686 */ 687 public float getRange() { 688 return mMax - mMin; 689 } 690 691 /** 692 * Gets the extent of the center flat position with respect to this axis. 693 * <p> 694 * For example, a flat value of 8 means that the center position is between -8 and +8. 695 * This value is mainly useful for calibrating self-centering devices. 696 * </p> 697 * @return The extent of the center flat position. 698 */ 699 public float getFlat() { 700 return mFlat; 701 } 702 703 /** 704 * Gets the error tolerance for input device measurements with respect to this axis. 705 * <p> 706 * For example, a value of 2 indicates that the measured value may be up to +/- 2 units 707 * away from the actual value due to noise and device sensitivity limitations. 708 * </p> 709 * @return The error tolerance. 710 */ 711 public float getFuzz() { 712 return mFuzz; 713 } 714 } 715 716 @Override 717 public void writeToParcel(Parcel out, int flags) { 718 out.writeInt(mId); 719 out.writeInt(mGeneration); 720 out.writeString(mName); 721 out.writeString(mDescriptor); 722 out.writeInt(mIsExternal ? 1 : 0); 723 out.writeInt(mSources); 724 out.writeInt(mKeyboardType); 725 mKeyCharacterMap.writeToParcel(out, flags); 726 out.writeInt(mHasVibrator ? 1 : 0); 727 728 final int numRanges = mMotionRanges.size(); 729 for (int i = 0; i < numRanges; i++) { 730 MotionRange range = mMotionRanges.get(i); 731 out.writeInt(range.mAxis); 732 out.writeInt(range.mSource); 733 out.writeFloat(range.mMin); 734 out.writeFloat(range.mMax); 735 out.writeFloat(range.mFlat); 736 out.writeFloat(range.mFuzz); 737 } 738 out.writeInt(-1); 739 } 740 741 @Override 742 public int describeContents() { 743 return 0; 744 } 745 746 @Override 747 public String toString() { 748 StringBuilder description = new StringBuilder(); 749 description.append("Input Device ").append(mId).append(": ").append(mName).append("\n"); 750 description.append(" Descriptor: ").append(mDescriptor).append("\n"); 751 description.append(" Generation: ").append(mGeneration).append("\n"); 752 description.append(" Location: ").append(mIsExternal ? "external" : "built-in").append("\n"); 753 754 description.append(" Keyboard Type: "); 755 switch (mKeyboardType) { 756 case KEYBOARD_TYPE_NONE: 757 description.append("none"); 758 break; 759 case KEYBOARD_TYPE_NON_ALPHABETIC: 760 description.append("non-alphabetic"); 761 break; 762 case KEYBOARD_TYPE_ALPHABETIC: 763 description.append("alphabetic"); 764 break; 765 } 766 description.append("\n"); 767 768 description.append(" Has Vibrator: ").append(mHasVibrator).append("\n"); 769 770 description.append(" Sources: 0x").append(Integer.toHexString(mSources)).append(" ("); 771 appendSourceDescriptionIfApplicable(description, SOURCE_KEYBOARD, "keyboard"); 772 appendSourceDescriptionIfApplicable(description, SOURCE_DPAD, "dpad"); 773 appendSourceDescriptionIfApplicable(description, SOURCE_TOUCHSCREEN, "touchscreen"); 774 appendSourceDescriptionIfApplicable(description, SOURCE_MOUSE, "mouse"); 775 appendSourceDescriptionIfApplicable(description, SOURCE_STYLUS, "stylus"); 776 appendSourceDescriptionIfApplicable(description, SOURCE_TRACKBALL, "trackball"); 777 appendSourceDescriptionIfApplicable(description, SOURCE_TOUCHPAD, "touchpad"); 778 appendSourceDescriptionIfApplicable(description, SOURCE_JOYSTICK, "joystick"); 779 appendSourceDescriptionIfApplicable(description, SOURCE_GAMEPAD, "gamepad"); 780 description.append(" )\n"); 781 782 final int numAxes = mMotionRanges.size(); 783 for (int i = 0; i < numAxes; i++) { 784 MotionRange range = mMotionRanges.get(i); 785 description.append(" ").append(MotionEvent.axisToString(range.mAxis)); 786 description.append(": source=0x").append(Integer.toHexString(range.mSource)); 787 description.append(" min=").append(range.mMin); 788 description.append(" max=").append(range.mMax); 789 description.append(" flat=").append(range.mFlat); 790 description.append(" fuzz=").append(range.mFuzz); 791 description.append("\n"); 792 } 793 return description.toString(); 794 } 795 796 private void appendSourceDescriptionIfApplicable(StringBuilder description, int source, 797 String sourceName) { 798 if ((mSources & source) == source) { 799 description.append(" "); 800 description.append(sourceName); 801 } 802 } 803} 804