InputDevice.java revision e33348ba54cd68d6936cffd4507037c14d4b10c2
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 17package android.view; 18 19/** 20 * Describes the capabilities of a particular input device. 21 * <p> 22 * Each input device may support multiple classes of input. For example, a multifunction 23 * keyboard may compose the capabilities of a standard keyboard together with a track pad mouse 24 * or other pointing device. 25 * </p><p> 26 * Some input devices present multiple distinguishable sources of input. For example, a 27 * game pad may have two analog joysticks, a directional pad and a full complement of buttons. 28 * Applications can query the framework about the characteristics of each distinct source. 29 * </p><p> 30 * As a further wrinkle, different kinds of input sources uses different coordinate systems 31 * to describe motion events. Refer to the comments on the input source constants for 32 * the appropriate interpretation. 33 */ 34public final class InputDevice { 35 private int mId; 36 private String mName; 37 private int mSources; 38 39 /** 40 * A mask for input source classes. 41 * 42 * Each distinct input source constant has one or more input source class bits set to 43 * specify the desired interpretation for its input events. 44 */ 45 public static final int SOURCE_CLASS_MASK = 0x000000ff; 46 47 /** 48 * The input source has buttons or keys. 49 * Examples: {@link #SOURCE_KEYBOARD}, {@link #SOURCE_GAMEPAD}, {@link #SOURCE_DPAD}. 50 * 51 * A {@link KeyEvent} should be interpreted as a button or key press. 52 * 53 * Use {@link #hasKey} to query whether the device supports a particular button or key. 54 */ 55 public static final int SOURCE_CLASS_BUTTON = 0x00000001; 56 57 /** 58 * The input source is a pointing device associated with a display. 59 * Examples: {@link #SOURCE_TOUCHSCREEN}, {@link #SOURCE_MOUSE}. 60 * 61 * A {@link MotionEvent} should be interpreted as absolute coordinates in 62 * display units according to the {@link View} hierarchy. Pointer down/up indicated when 63 * the finger touches the display or when the selection button is pressed/released. 64 * 65 * Use {@link #getMotionRange} to query the range of the pointing device. Some devices permit 66 * touches outside the display area so the effective range may be somewhat smaller or larger 67 * than the actual display size. 68 */ 69 public static final int SOURCE_CLASS_POINTER = 0x00000002; 70 71 /** 72 * The input source is a trackball navigation device. 73 * Examples: {@link #SOURCE_TRACKBALL}. 74 * 75 * A {@link MotionEvent} should be interpreted as relative movements in device-specific 76 * units used for navigation purposes. Pointer down/up indicates when the selection button 77 * is pressed/released. 78 * 79 * Use {@link #getMotionRange} to query the range of motion. 80 */ 81 public static final int SOURCE_CLASS_TRACKBALL = 0x00000004; 82 83 /** 84 * The input source is an absolute positioning device not associated with a display 85 * (unlike {@link #SOURCE_CLASS_POINTER}). 86 * 87 * A {@link MotionEvent} should be interpreted as absolute coordinates in 88 * device-specific surface units. 89 * 90 * Use {@link #getMotionRange} to query the range of positions. 91 */ 92 public static final int SOURCE_CLASS_POSITION = 0x00000008; 93 94 /** 95 * The input source is a joystick. 96 * 97 * A {@link KeyEvent} should be interpreted as a joystick button press. 98 * 99 * A {@link MotionEvent} should be interpreted in absolute coordinates as a joystick 100 * position in normalized device-specific units nominally between -1.0 and 1.0. 101 * 102 * Use {@link #getMotionRange} to query the range and precision of motion. 103 */ 104 public static final int SOURCE_CLASS_JOYSTICK = 0x00000010; 105 106 /** 107 * The input source is unknown. 108 */ 109 public static final int SOURCE_UNKNOWN = 0x00000000; 110 111 /** 112 * The input source is a keyboard. 113 * 114 * @see #SOURCE_CLASS_BUTTON 115 */ 116 public static final int SOURCE_KEYBOARD = 0x00000100 | SOURCE_CLASS_BUTTON; 117 118 /** 119 * The input source is a DPad. 120 * 121 * @see #SOURCE_CLASS_BUTTON 122 */ 123 public static final int SOURCE_DPAD = 0x00000200 | SOURCE_CLASS_BUTTON; 124 125 /** 126 * The input source is a gamepad. 127 * 128 * @see #SOURCE_CLASS_BUTTON 129 */ 130 public static final int SOURCE_GAMEPAD = 0x00000400 | SOURCE_CLASS_BUTTON; 131 132 /** 133 * The input source is a touch screen pointing device. 134 * 135 * @see #SOURCE_CLASS_POINTER 136 */ 137 public static final int SOURCE_TOUCHSCREEN = 0x00001000 | SOURCE_CLASS_POINTER; 138 139 /** 140 * The input source is a mouse pointing device. 141 * This code is also used for other mouse-like pointing devices such as trackpads 142 * and trackpoints. 143 * 144 * @see #SOURCE_CLASS_POINTER 145 */ 146 public static final int SOURCE_MOUSE = 0x00002000 | SOURCE_CLASS_POINTER; 147 148 /** 149 * The input source is a trackball. 150 * 151 * @see #SOURCE_CLASS_TRACKBALL 152 */ 153 public static final int SOURCE_TRACKBALL = 0x00010000 | SOURCE_CLASS_TRACKBALL; 154 155 /** 156 * The input source is a touch pad or digitizer tablet that is not 157 * associated with a display (unlike {@link #SOURCE_TOUCHSCREEN}). 158 * 159 * @see #SOURCE_CLASS_POSITION 160 */ 161 public static final int SOURCE_TOUCHPAD = 0x00100000 | SOURCE_CLASS_POSITION; 162 163 /** 164 * The input source is a joystick mounted on the left or is a standalone joystick. 165 * 166 * @see #SOURCE_CLASS_JOYSTICK 167 */ 168 public static final int SOURCE_JOYSTICK_LEFT = 0x01000000 | SOURCE_CLASS_JOYSTICK; 169 170 /** 171 * The input source is a joystick mounted on the right. 172 * 173 * @see #SOURCE_CLASS_JOYSTICK 174 */ 175 public static final int SOURCE_JOYSTICK_RIGHT = 0x02000000 | SOURCE_CLASS_JOYSTICK; 176 177 /** 178 * Constant for retrieving the range of values for {@link MotionEvent.PointerCoords#x}. 179 * 180 * @see #getMotionRange 181 */ 182 public static final int MOTION_RANGE_X = 0; 183 184 /** 185 * Constant for retrieving the range of values for {@link MotionEvent.PointerCoords#y}. 186 * 187 * @see #getMotionRange 188 */ 189 public static final int MOTION_RANGE_Y = 1; 190 191 /** 192 * Constant for retrieving the range of values for {@link MotionEvent.PointerCoords#pressure}. 193 * 194 * @see #getMotionRange 195 */ 196 public static final int MOTION_RANGE_PRESSURE = 2; 197 198 /** 199 * Constant for retrieving the range of values for {@link MotionEvent.PointerCoords#size}. 200 * 201 * @see #getMotionRange 202 */ 203 public static final int MOTION_RANGE_SIZE = 3; 204 205 /** 206 * Constant for retrieving the range of values for {@link MotionEvent.PointerCoords#touchMajor}. 207 * 208 * @see #getMotionRange 209 */ 210 public static final int MOTION_RANGE_TOUCH_MAJOR = 4; 211 212 /** 213 * Constant for retrieving the range of values for {@link MotionEvent.PointerCoords#touchMinor}. 214 * 215 * @see #getMotionRange 216 */ 217 public static final int MOTION_RANGE_TOUCH_MINOR = 5; 218 219 /** 220 * Constant for retrieving the range of values for {@link MotionEvent.PointerCoords#toolMajor}. 221 * 222 * @see #getMotionRange 223 */ 224 public static final int MOTION_RANGE_TOOL_MAJOR = 6; 225 226 /** 227 * Constant for retrieving the range of values for {@link MotionEvent.PointerCoords#toolMinor}. 228 * 229 * @see #getMotionRange 230 */ 231 public static final int MOTION_RANGE_TOOL_MINOR = 7; 232 233 /** 234 * Constant for retrieving the range of values for 235 * {@link MotionEvent.PointerCoords#orientation}. 236 * 237 * @see #getMotionRange 238 */ 239 public static final int MOTION_RANGE_ORIENTATION = 8; 240 241 /** 242 * Gets information about the input device with the specified id. 243 * @param id The device id. 244 * @return The input device or null if not found. 245 */ 246 public static InputDevice getDevice(int id) { 247 // TODO 248 return null; 249 } 250 251 /** 252 * Gets the name of this input device. 253 * @return The input device name. 254 */ 255 public String getName() { 256 return mName; 257 } 258 259 /** 260 * Gets the input sources supported by this input device as a combined bitfield. 261 * @return The supported input sources. 262 */ 263 public int getSources() { 264 return mSources; 265 } 266 267 /** 268 * Gets the key character map associated with this input device. 269 * @return The key character map. 270 */ 271 public KeyCharacterMap getKeyCharacterMap() { 272 return KeyCharacterMap.load(mId); 273 } 274 275 /** 276 * Gets information about the range of values for a particular {@link MotionEvent} 277 * coordinate. 278 * @param range The motion range constant. 279 * @return The range of values, or null if the requested coordinate is not 280 * supported by the device. 281 */ 282 public MotionRange getMotionRange(int range) { 283 // TODO 284 return null; 285 } 286 287 /** 288 * Returns true if the device supports a particular button or key. 289 * @param keyCode The key code. 290 * @return True if the device supports the key. 291 */ 292 public boolean hasKey(int keyCode) { 293 // TODO 294 return false; 295 } 296 297 /** 298 * Provides information about the range of values for a particular {@link MotionEvent} 299 * coordinate. 300 */ 301 public static final class MotionRange { 302 /** 303 * Gets the minimum value for the coordinate. 304 * @return The minimum value. 305 */ 306 public float getMin() { 307 // TODO 308 return 0; 309 } 310 311 /** 312 * Gets the maximum value for the coordinate. 313 * @return The minimum value. 314 */ 315 public float getMax() { 316 // TODO 317 return 0; 318 } 319 320 /** 321 * Gets the range of the coordinate (difference between maximum and minimum). 322 * @return The range of values. 323 */ 324 public float getRange() { 325 // TODO 326 return 0; 327 } 328 329 /** 330 * Gets the extent of the center flat position with respect to this coordinate. 331 * For example, a flat value of 8 means that the center position is between -8 and +8. 332 * This value is mainly useful for calibrating joysticks. 333 * @return The extent of the center flat position. 334 */ 335 public float getFlat() { 336 // TODO 337 return 0; 338 } 339 340 /** 341 * Gets the error tolerance for input device measurements with respect to this coordinate. 342 * For example, a value of 2 indicates that the measured value may be up to +/- 2 units 343 * away from the actual value due to noise and device sensitivity limitations. 344 * @return The error tolerance. 345 */ 346 public float getFuzz() { 347 // TODO 348 return 0; 349 } 350 } 351} 352