MotionEvent.java revision 9ea77fc821918ea562ff4907945b865e39e0201a
1/* 2 * Copyright (C) 2007 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 19import android.graphics.Matrix; 20import android.os.Parcel; 21import android.os.Parcelable; 22import android.os.SystemClock; 23import android.util.SparseArray; 24 25/** 26 * Object used to report movement (mouse, pen, finger, trackball) events. 27 * Motion events may hold either absolute or relative movements and other data, 28 * depending on the type of device. 29 * 30 * <h3>Overview</h3> 31 * <p> 32 * Motion events describe movements in terms of an action code and a set of axis values. 33 * The action code specifies the state change that occurred such as a pointer going 34 * down or up. The axis values describe the position and other movement properties. 35 * </p><p> 36 * For example, when the user first touches the screen, the system delivers a touch 37 * event to the appropriate {@link View} with the action code {@link #ACTION_DOWN} 38 * and a set of axis values that include the X and Y coordinates of the touch and 39 * information about the pressure, size and orientation of the contact area. 40 * </p><p> 41 * Some devices can report multiple movement traces at the same time. Multi-touch 42 * screens emit one movement trace for each finger. The individual fingers or 43 * other objects that generate movement traces are referred to as <em>pointers</em>. 44 * Motion events contain information about all of the pointers that are currently active 45 * even if some of them have not moved since the last event was delivered. 46 * </p><p> 47 * The number of pointers only ever changes by one as individual pointers go up and down, 48 * except when the gesture is canceled. 49 * </p><p> 50 * Each pointer has a unique id that is assigned when it first goes down 51 * (indicated by {@link #ACTION_DOWN} or {@link #ACTION_POINTER_DOWN}). A pointer id 52 * remains valid until the pointer eventually goes up (indicated by {@link #ACTION_UP} 53 * or {@link #ACTION_POINTER_UP}) or when the gesture is canceled (indicated by 54 * {@link #ACTION_CANCEL}). 55 * </p><p> 56 * The MotionEvent class provides many methods to query the position and other properties of 57 * pointers, such as {@link #getX(int)}, {@link #getY(int)}, {@link #getAxisValue}, 58 * {@link #getPointerId(int)}, {@link #getToolType(int)}, and many others. Most of these 59 * methods accept the pointer index as a parameter rather than the pointer id. 60 * The pointer index of each pointer in the event ranges from 0 to one less than the value 61 * returned by {@link #getPointerCount()}. 62 * </p><p> 63 * The order in which individual pointers appear within a motion event is undefined. 64 * Thus the pointer index of a pointer can change from one event to the next but 65 * the pointer id of a pointer is guaranteed to remain constant as long as the pointer 66 * remains active. Use the {@link #getPointerId(int)} method to obtain the 67 * pointer id of a pointer to track it across all subsequent motion events in a gesture. 68 * Then for successive motion events, use the {@link #findPointerIndex(int)} method 69 * to obtain the pointer index for a given pointer id in that motion event. 70 * </p><p> 71 * Mouse and stylus buttons can be retrieved using {@link #getButtonState()}. It is a 72 * good idea to check the button state while handling {@link #ACTION_DOWN} as part 73 * of a touch event. The application may choose to perform some different action 74 * if the touch event starts due to a secondary button click, such as presenting a 75 * context menu. 76 * </p> 77 * 78 * <h3>Batching</h3> 79 * <p> 80 * For efficiency, motion events with {@link #ACTION_MOVE} may batch together 81 * multiple movement samples within a single object. The most current 82 * pointer coordinates are available using {@link #getX(int)} and {@link #getY(int)}. 83 * Earlier coordinates within the batch are accessed using {@link #getHistoricalX(int, int)} 84 * and {@link #getHistoricalY(int, int)}. The coordinates are "historical" only 85 * insofar as they are older than the current coordinates in the batch; however, 86 * they are still distinct from any other coordinates reported in prior motion events. 87 * To process all coordinates in the batch in time order, first consume the historical 88 * coordinates then consume the current coordinates. 89 * </p><p> 90 * Example: Consuming all samples for all pointers in a motion event in time order. 91 * </p><p><pre><code> 92 * void printSamples(MotionEvent ev) { 93 * final int historySize = ev.getHistorySize(); 94 * final int pointerCount = ev.getPointerCount(); 95 * for (int h = 0; h < historySize; h++) { 96 * System.out.printf("At time %d:", ev.getHistoricalEventTime(h)); 97 * for (int p = 0; p < pointerCount; p++) { 98 * System.out.printf(" pointer %d: (%f,%f)", 99 * ev.getPointerId(p), ev.getHistoricalX(p, h), ev.getHistoricalY(p, h)); 100 * } 101 * } 102 * System.out.printf("At time %d:", ev.getEventTime()); 103 * for (int p = 0; p < pointerCount; p++) { 104 * System.out.printf(" pointer %d: (%f,%f)", 105 * ev.getPointerId(p), ev.getX(p), ev.getY(p)); 106 * } 107 * } 108 * </code></pre></p> 109 * 110 * <h3>Device Types</h3> 111 * <p> 112 * The interpretation of the contents of a MotionEvent varies significantly depending 113 * on the source class of the device. 114 * </p><p> 115 * On pointing devices with source class {@link InputDevice#SOURCE_CLASS_POINTER} 116 * such as touch screens, the pointer coordinates specify absolute 117 * positions such as view X/Y coordinates. Each complete gesture is represented 118 * by a sequence of motion events with actions that describe pointer state transitions 119 * and movements. A gesture starts with a motion event with {@link #ACTION_DOWN} 120 * that provides the location of the first pointer down. As each additional 121 * pointer that goes down or up, the framework will generate a motion event with 122 * {@link #ACTION_POINTER_DOWN} or {@link #ACTION_POINTER_UP} accordingly. 123 * Pointer movements are described by motion events with {@link #ACTION_MOVE}. 124 * Finally, a gesture end either when the final pointer goes up as represented 125 * by a motion event with {@link #ACTION_UP} or when gesture is canceled 126 * with {@link #ACTION_CANCEL}. 127 * </p><p> 128 * Some pointing devices such as mice may support vertical and/or horizontal scrolling. 129 * A scroll event is reported as a generic motion event with {@link #ACTION_SCROLL} that 130 * includes the relative scroll offset in the {@link #AXIS_VSCROLL} and 131 * {@link #AXIS_HSCROLL} axes. See {@link #getAxisValue(int)} for information 132 * about retrieving these additional axes. 133 * </p><p> 134 * On trackball devices with source class {@link InputDevice#SOURCE_CLASS_TRACKBALL}, 135 * the pointer coordinates specify relative movements as X/Y deltas. 136 * A trackball gesture consists of a sequence of movements described by motion 137 * events with {@link #ACTION_MOVE} interspersed with occasional {@link #ACTION_DOWN} 138 * or {@link #ACTION_UP} motion events when the trackball button is pressed or released. 139 * </p><p> 140 * On joystick devices with source class {@link InputDevice#SOURCE_CLASS_JOYSTICK}, 141 * the pointer coordinates specify the absolute position of the joystick axes. 142 * The joystick axis values are normalized to a range of -1.0 to 1.0 where 0.0 corresponds 143 * to the center position. More information about the set of available axes and the 144 * range of motion can be obtained using {@link InputDevice#getMotionRange}. 145 * Some common joystick axes are {@link #AXIS_X}, {@link #AXIS_Y}, 146 * {@link #AXIS_HAT_X}, {@link #AXIS_HAT_Y}, {@link #AXIS_Z} and {@link #AXIS_RZ}. 147 * </p><p> 148 * Refer to {@link InputDevice} for more information about how different kinds of 149 * input devices and sources represent pointer coordinates. 150 * </p> 151 * 152 * <h3>Consistency Guarantees</h3> 153 * <p> 154 * Motion events are always delivered to views as a consistent stream of events. 155 * What constitutes a consistent stream varies depending on the type of device. 156 * For touch events, consistency implies that pointers go down one at a time, 157 * move around as a group and then go up one at a time or are canceled. 158 * </p><p> 159 * While the framework tries to deliver consistent streams of motion events to 160 * views, it cannot guarantee it. Some events may be dropped or modified by 161 * containing views in the application before they are delivered thereby making 162 * the stream of events inconsistent. Views should always be prepared to 163 * handle {@link #ACTION_CANCEL} and should tolerate anomalous 164 * situations such as receiving a new {@link #ACTION_DOWN} without first having 165 * received an {@link #ACTION_UP} for the prior gesture. 166 * </p> 167 */ 168public final class MotionEvent extends InputEvent implements Parcelable { 169 private static final long NS_PER_MS = 1000000; 170 171 /** 172 * An invalid pointer id. 173 * 174 * This value (-1) can be used as a placeholder to indicate that a pointer id 175 * has not been assigned or is not available. It cannot appear as 176 * a pointer id inside a {@link MotionEvent}. 177 */ 178 public static final int INVALID_POINTER_ID = -1; 179 180 /** 181 * Bit mask of the parts of the action code that are the action itself. 182 */ 183 public static final int ACTION_MASK = 0xff; 184 185 /** 186 * Constant for {@link #getActionMasked}: A pressed gesture has started, the 187 * motion contains the initial starting location. 188 * <p> 189 * This is also a good time to check the button state to distinguish 190 * secondary and tertiary button clicks and handle them appropriately. 191 * Use {@link #getButtonState} to retrieve the button state. 192 * </p> 193 */ 194 public static final int ACTION_DOWN = 0; 195 196 /** 197 * Constant for {@link #getActionMasked}: A pressed gesture has finished, the 198 * motion contains the final release location as well as any intermediate 199 * points since the last down or move event. 200 */ 201 public static final int ACTION_UP = 1; 202 203 /** 204 * Constant for {@link #getActionMasked}: A change has happened during a 205 * press gesture (between {@link #ACTION_DOWN} and {@link #ACTION_UP}). 206 * The motion contains the most recent point, as well as any intermediate 207 * points since the last down or move event. 208 */ 209 public static final int ACTION_MOVE = 2; 210 211 /** 212 * Constant for {@link #getActionMasked}: The current gesture has been aborted. 213 * You will not receive any more points in it. You should treat this as 214 * an up event, but not perform any action that you normally would. 215 */ 216 public static final int ACTION_CANCEL = 3; 217 218 /** 219 * Constant for {@link #getActionMasked}: A movement has happened outside of the 220 * normal bounds of the UI element. This does not provide a full gesture, 221 * but only the initial location of the movement/touch. 222 */ 223 public static final int ACTION_OUTSIDE = 4; 224 225 /** 226 * Constant for {@link #getActionMasked}: A non-primary pointer has gone down. 227 * <p> 228 * Use {@link #getActionIndex} to retrieve the index of the pointer that changed. 229 * </p><p> 230 * The index is encoded in the {@link #ACTION_POINTER_INDEX_MASK} bits of the 231 * unmasked action returned by {@link #getAction}. 232 * </p> 233 */ 234 public static final int ACTION_POINTER_DOWN = 5; 235 236 /** 237 * Constant for {@link #getActionMasked}: A non-primary pointer has gone up. 238 * <p> 239 * Use {@link #getActionIndex} to retrieve the index of the pointer that changed. 240 * </p><p> 241 * The index is encoded in the {@link #ACTION_POINTER_INDEX_MASK} bits of the 242 * unmasked action returned by {@link #getAction}. 243 * </p> 244 */ 245 public static final int ACTION_POINTER_UP = 6; 246 247 /** 248 * Constant for {@link #getActionMasked}: A change happened but the pointer 249 * is not down (unlike {@link #ACTION_MOVE}). The motion contains the most 250 * recent point, as well as any intermediate points since the last 251 * hover move event. 252 * <p> 253 * This action is always delivered to the window or view under the pointer. 254 * </p><p> 255 * This action is not a touch event so it is delivered to 256 * {@link View#onGenericMotionEvent(MotionEvent)} rather than 257 * {@link View#onTouchEvent(MotionEvent)}. 258 * </p> 259 */ 260 public static final int ACTION_HOVER_MOVE = 7; 261 262 /** 263 * Constant for {@link #getActionMasked}: The motion event contains relative 264 * vertical and/or horizontal scroll offsets. Use {@link #getAxisValue(int)} 265 * to retrieve the information from {@link #AXIS_VSCROLL} and {@link #AXIS_HSCROLL}. 266 * The pointer may or may not be down when this event is dispatched. 267 * <p> 268 * This action is always delivered to the window or view under the pointer, which 269 * may not be the window or view currently touched. 270 * </p><p> 271 * This action is not a touch event so it is delivered to 272 * {@link View#onGenericMotionEvent(MotionEvent)} rather than 273 * {@link View#onTouchEvent(MotionEvent)}. 274 * </p> 275 */ 276 public static final int ACTION_SCROLL = 8; 277 278 /** 279 * Constant for {@link #getActionMasked}: The pointer is not down but has entered the 280 * boundaries of a window or view. 281 * <p> 282 * This action is always delivered to the window or view under the pointer. 283 * </p><p> 284 * This action is not a touch event so it is delivered to 285 * {@link View#onGenericMotionEvent(MotionEvent)} rather than 286 * {@link View#onTouchEvent(MotionEvent)}. 287 * </p> 288 */ 289 public static final int ACTION_HOVER_ENTER = 9; 290 291 /** 292 * Constant for {@link #getActionMasked}: The pointer is not down but has exited the 293 * boundaries of a window or view. 294 * <p> 295 * This action is always delivered to the window or view that was previously under the pointer. 296 * </p><p> 297 * This action is not a touch event so it is delivered to 298 * {@link View#onGenericMotionEvent(MotionEvent)} rather than 299 * {@link View#onTouchEvent(MotionEvent)}. 300 * </p> 301 */ 302 public static final int ACTION_HOVER_EXIT = 10; 303 304 /** 305 * Bits in the action code that represent a pointer index, used with 306 * {@link #ACTION_POINTER_DOWN} and {@link #ACTION_POINTER_UP}. Shifting 307 * down by {@link #ACTION_POINTER_INDEX_SHIFT} provides the actual pointer 308 * index where the data for the pointer going up or down can be found; you can 309 * get its identifier with {@link #getPointerId(int)} and the actual 310 * data with {@link #getX(int)} etc. 311 * 312 * @see #getActionIndex 313 */ 314 public static final int ACTION_POINTER_INDEX_MASK = 0xff00; 315 316 /** 317 * Bit shift for the action bits holding the pointer index as 318 * defined by {@link #ACTION_POINTER_INDEX_MASK}. 319 * 320 * @see #getActionIndex 321 */ 322 public static final int ACTION_POINTER_INDEX_SHIFT = 8; 323 324 /** 325 * @deprecated Use {@link #ACTION_POINTER_INDEX_MASK} to retrieve the 326 * data index associated with {@link #ACTION_POINTER_DOWN}. 327 */ 328 @Deprecated 329 public static final int ACTION_POINTER_1_DOWN = ACTION_POINTER_DOWN | 0x0000; 330 331 /** 332 * @deprecated Use {@link #ACTION_POINTER_INDEX_MASK} to retrieve the 333 * data index associated with {@link #ACTION_POINTER_DOWN}. 334 */ 335 @Deprecated 336 public static final int ACTION_POINTER_2_DOWN = ACTION_POINTER_DOWN | 0x0100; 337 338 /** 339 * @deprecated Use {@link #ACTION_POINTER_INDEX_MASK} to retrieve the 340 * data index associated with {@link #ACTION_POINTER_DOWN}. 341 */ 342 @Deprecated 343 public static final int ACTION_POINTER_3_DOWN = ACTION_POINTER_DOWN | 0x0200; 344 345 /** 346 * @deprecated Use {@link #ACTION_POINTER_INDEX_MASK} to retrieve the 347 * data index associated with {@link #ACTION_POINTER_UP}. 348 */ 349 @Deprecated 350 public static final int ACTION_POINTER_1_UP = ACTION_POINTER_UP | 0x0000; 351 352 /** 353 * @deprecated Use {@link #ACTION_POINTER_INDEX_MASK} to retrieve the 354 * data index associated with {@link #ACTION_POINTER_UP}. 355 */ 356 @Deprecated 357 public static final int ACTION_POINTER_2_UP = ACTION_POINTER_UP | 0x0100; 358 359 /** 360 * @deprecated Use {@link #ACTION_POINTER_INDEX_MASK} to retrieve the 361 * data index associated with {@link #ACTION_POINTER_UP}. 362 */ 363 @Deprecated 364 public static final int ACTION_POINTER_3_UP = ACTION_POINTER_UP | 0x0200; 365 366 /** 367 * @deprecated Renamed to {@link #ACTION_POINTER_INDEX_MASK} to match 368 * the actual data contained in these bits. 369 */ 370 @Deprecated 371 public static final int ACTION_POINTER_ID_MASK = 0xff00; 372 373 /** 374 * @deprecated Renamed to {@link #ACTION_POINTER_INDEX_SHIFT} to match 375 * the actual data contained in these bits. 376 */ 377 @Deprecated 378 public static final int ACTION_POINTER_ID_SHIFT = 8; 379 380 /** 381 * This flag indicates that the window that received this motion event is partly 382 * or wholly obscured by another visible window above it. This flag is set to true 383 * even if the event did not directly pass through the obscured area. 384 * A security sensitive application can check this flag to identify situations in which 385 * a malicious application may have covered up part of its content for the purpose 386 * of misleading the user or hijacking touches. An appropriate response might be 387 * to drop the suspect touches or to take additional precautions to confirm the user's 388 * actual intent. 389 */ 390 public static final int FLAG_WINDOW_IS_OBSCURED = 0x1; 391 392 /** 393 * Private flag that indicates when the system has detected that this motion event 394 * may be inconsistent with respect to the sequence of previously delivered motion events, 395 * such as when a pointer move event is sent but the pointer is not down. 396 * 397 * @hide 398 * @see #isTainted 399 * @see #setTainted 400 */ 401 public static final int FLAG_TAINTED = 0x80000000; 402 403 /** 404 * Flag indicating the motion event intersected the top edge of the screen. 405 */ 406 public static final int EDGE_TOP = 0x00000001; 407 408 /** 409 * Flag indicating the motion event intersected the bottom edge of the screen. 410 */ 411 public static final int EDGE_BOTTOM = 0x00000002; 412 413 /** 414 * Flag indicating the motion event intersected the left edge of the screen. 415 */ 416 public static final int EDGE_LEFT = 0x00000004; 417 418 /** 419 * Flag indicating the motion event intersected the right edge of the screen. 420 */ 421 public static final int EDGE_RIGHT = 0x00000008; 422 423 /** 424 * Axis constant: X axis of a motion event. 425 * <p> 426 * <ul> 427 * <li>For a touch screen, reports the absolute X screen position of the center of 428 * the touch contact area. The units are display pixels. 429 * <li>For a touch pad, reports the absolute X surface position of the center of the touch 430 * contact area. The units are device-dependent; use {@link InputDevice#getMotionRange(int)} 431 * to query the effective range of values. 432 * <li>For a mouse, reports the absolute X screen position of the mouse pointer. 433 * The units are display pixels. 434 * <li>For a trackball, reports the relative horizontal displacement of the trackball. 435 * The value is normalized to a range from -1.0 (left) to 1.0 (right). 436 * <li>For a joystick, reports the absolute X position of the joystick. 437 * The value is normalized to a range from -1.0 (left) to 1.0 (right). 438 * </ul> 439 * </p> 440 * 441 * @see #getX(int) 442 * @see #getHistoricalX(int, int) 443 * @see MotionEvent.PointerCoords#x 444 * @see InputDevice#getMotionRange 445 */ 446 public static final int AXIS_X = 0; 447 448 /** 449 * Axis constant: Y axis of a motion event. 450 * <p> 451 * <ul> 452 * <li>For a touch screen, reports the absolute Y screen position of the center of 453 * the touch contact area. The units are display pixels. 454 * <li>For a touch pad, reports the absolute Y surface position of the center of the touch 455 * contact area. The units are device-dependent; use {@link InputDevice#getMotionRange(int)} 456 * to query the effective range of values. 457 * <li>For a mouse, reports the absolute Y screen position of the mouse pointer. 458 * The units are display pixels. 459 * <li>For a trackball, reports the relative vertical displacement of the trackball. 460 * The value is normalized to a range from -1.0 (up) to 1.0 (down). 461 * <li>For a joystick, reports the absolute Y position of the joystick. 462 * The value is normalized to a range from -1.0 (up or far) to 1.0 (down or near). 463 * </ul> 464 * </p> 465 * 466 * @see #getY(int) 467 * @see #getHistoricalY(int, int) 468 * @see MotionEvent.PointerCoords#y 469 * @see InputDevice#getMotionRange 470 */ 471 public static final int AXIS_Y = 1; 472 473 /** 474 * Axis constant: Pressure axis of a motion event. 475 * <p> 476 * <ul> 477 * <li>For a touch screen or touch pad, reports the approximate pressure applied to the surface 478 * by a finger or other tool. The value is normalized to a range from 479 * 0 (no pressure at all) to 1 (normal pressure), although values higher than 1 480 * may be generated depending on the calibration of the input device. 481 * <li>For a trackball, the value is set to 1 if the trackball button is pressed 482 * or 0 otherwise. 483 * <li>For a mouse, the value is set to 1 if the primary mouse button is pressed 484 * or 0 otherwise. 485 * </ul> 486 * </p> 487 * 488 * @see #getPressure(int) 489 * @see #getHistoricalPressure(int, int) 490 * @see MotionEvent.PointerCoords#pressure 491 * @see InputDevice#getMotionRange 492 */ 493 public static final int AXIS_PRESSURE = 2; 494 495 /** 496 * Axis constant: Size axis of a motion event. 497 * <p> 498 * <ul> 499 * <li>For a touch screen or touch pad, reports the approximate size of the contact area in 500 * relation to the maximum detectable size for the device. The value is normalized 501 * to a range from 0 (smallest detectable size) to 1 (largest detectable size), 502 * although it is not a linear scale. This value is of limited use. 503 * To obtain calibrated size information, use 504 * {@link #AXIS_TOUCH_MAJOR} or {@link #AXIS_TOOL_MAJOR}. 505 * </ul> 506 * </p> 507 * 508 * @see #getSize(int) 509 * @see #getHistoricalSize(int, int) 510 * @see MotionEvent.PointerCoords#size 511 * @see InputDevice#getMotionRange 512 */ 513 public static final int AXIS_SIZE = 3; 514 515 /** 516 * Axis constant: TouchMajor axis of a motion event. 517 * <p> 518 * <ul> 519 * <li>For a touch screen, reports the length of the major axis of an ellipse that 520 * represents the touch area at the point of contact. 521 * The units are display pixels. 522 * <li>For a touch pad, reports the length of the major axis of an ellipse that 523 * represents the touch area at the point of contact. 524 * The units are device-dependent; use {@link InputDevice#getMotionRange(int)} 525 * to query the effective range of values. 526 * </ul> 527 * </p> 528 * 529 * @see #getTouchMajor(int) 530 * @see #getHistoricalTouchMajor(int, int) 531 * @see MotionEvent.PointerCoords#touchMajor 532 * @see InputDevice#getMotionRange 533 */ 534 public static final int AXIS_TOUCH_MAJOR = 4; 535 536 /** 537 * Axis constant: TouchMinor axis of a motion event. 538 * <p> 539 * <ul> 540 * <li>For a touch screen, reports the length of the minor axis of an ellipse that 541 * represents the touch area at the point of contact. 542 * The units are display pixels. 543 * <li>For a touch pad, reports the length of the minor axis of an ellipse that 544 * represents the touch area at the point of contact. 545 * The units are device-dependent; use {@link InputDevice#getMotionRange(int)} 546 * to query the effective range of values. 547 * </ul> 548 * </p><p> 549 * When the touch is circular, the major and minor axis lengths will be equal to one another. 550 * </p> 551 * 552 * @see #getTouchMinor(int) 553 * @see #getHistoricalTouchMinor(int, int) 554 * @see MotionEvent.PointerCoords#touchMinor 555 * @see InputDevice#getMotionRange 556 */ 557 public static final int AXIS_TOUCH_MINOR = 5; 558 559 /** 560 * Axis constant: ToolMajor axis of a motion event. 561 * <p> 562 * <ul> 563 * <li>For a touch screen, reports the length of the major axis of an ellipse that 564 * represents the size of the approaching finger or tool used to make contact. 565 * <li>For a touch pad, reports the length of the major axis of an ellipse that 566 * represents the size of the approaching finger or tool used to make contact. 567 * The units are device-dependent; use {@link InputDevice#getMotionRange(int)} 568 * to query the effective range of values. 569 * </ul> 570 * </p><p> 571 * When the touch is circular, the major and minor axis lengths will be equal to one another. 572 * </p><p> 573 * The tool size may be larger than the touch size since the tool may not be fully 574 * in contact with the touch sensor. 575 * </p> 576 * 577 * @see #getToolMajor(int) 578 * @see #getHistoricalToolMajor(int, int) 579 * @see MotionEvent.PointerCoords#toolMajor 580 * @see InputDevice#getMotionRange 581 */ 582 public static final int AXIS_TOOL_MAJOR = 6; 583 584 /** 585 * Axis constant: ToolMinor axis of a motion event. 586 * <p> 587 * <ul> 588 * <li>For a touch screen, reports the length of the minor axis of an ellipse that 589 * represents the size of the approaching finger or tool used to make contact. 590 * <li>For a touch pad, reports the length of the minor axis of an ellipse that 591 * represents the size of the approaching finger or tool used to make contact. 592 * The units are device-dependent; use {@link InputDevice#getMotionRange(int)} 593 * to query the effective range of values. 594 * </ul> 595 * </p><p> 596 * When the touch is circular, the major and minor axis lengths will be equal to one another. 597 * </p><p> 598 * The tool size may be larger than the touch size since the tool may not be fully 599 * in contact with the touch sensor. 600 * </p> 601 * 602 * @see #getToolMinor(int) 603 * @see #getHistoricalToolMinor(int, int) 604 * @see MotionEvent.PointerCoords#toolMinor 605 * @see InputDevice#getMotionRange 606 */ 607 public static final int AXIS_TOOL_MINOR = 7; 608 609 /** 610 * Axis constant: Orientation axis of a motion event. 611 * <p> 612 * <ul> 613 * <li>For a touch screen or touch pad, reports the orientation of the finger 614 * or tool in radians relative to the vertical plane of the device. 615 * An angle of 0 radians indicates that the major axis of contact is oriented 616 * upwards, is perfectly circular or is of unknown orientation. A positive angle 617 * indicates that the major axis of contact is oriented to the right. A negative angle 618 * indicates that the major axis of contact is oriented to the left. 619 * The full range is from -PI/2 radians (finger pointing fully left) to PI/2 radians 620 * (finger pointing fully right). 621 * <li>For a stylus, the orientation indicates the direction in which the stylus 622 * is pointing in relation to the vertical axis of the current orientation of the screen. 623 * The range is from -PI radians to PI radians, where 0 is pointing up, 624 * -PI/2 radians is pointing left, -PI or PI radians is pointing down, and PI/2 radians 625 * is pointing right. See also {@link #AXIS_TILT}. 626 * </ul> 627 * </p> 628 * 629 * @see #getOrientation(int) 630 * @see #getHistoricalOrientation(int, int) 631 * @see MotionEvent.PointerCoords#orientation 632 * @see InputDevice#getMotionRange 633 */ 634 public static final int AXIS_ORIENTATION = 8; 635 636 /** 637 * Axis constant: Vertical Scroll axis of a motion event. 638 * <p> 639 * <ul> 640 * <li>For a mouse, reports the relative movement of the vertical scroll wheel. 641 * The value is normalized to a range from -1.0 (down) to 1.0 (up). 642 * </ul> 643 * </p><p> 644 * This axis should be used to scroll views vertically. 645 * </p> 646 * 647 * @see #getAxisValue(int, int) 648 * @see #getHistoricalAxisValue(int, int, int) 649 * @see MotionEvent.PointerCoords#getAxisValue(int) 650 * @see InputDevice#getMotionRange 651 */ 652 public static final int AXIS_VSCROLL = 9; 653 654 /** 655 * Axis constant: Horizontal Scroll axis of a motion event. 656 * <p> 657 * <ul> 658 * <li>For a mouse, reports the relative movement of the horizontal scroll wheel. 659 * The value is normalized to a range from -1.0 (left) to 1.0 (right). 660 * </ul> 661 * </p><p> 662 * This axis should be used to scroll views horizontally. 663 * </p> 664 * 665 * @see #getAxisValue(int, int) 666 * @see #getHistoricalAxisValue(int, int, int) 667 * @see MotionEvent.PointerCoords#getAxisValue(int) 668 * @see InputDevice#getMotionRange 669 */ 670 public static final int AXIS_HSCROLL = 10; 671 672 /** 673 * Axis constant: Z axis of a motion event. 674 * <p> 675 * <ul> 676 * <li>For a joystick, reports the absolute Z position of the joystick. 677 * The value is normalized to a range from -1.0 (high) to 1.0 (low). 678 * <em>On game pads with two analog joysticks, this axis is often reinterpreted 679 * to report the absolute X position of the second joystick instead.</em> 680 * </ul> 681 * </p> 682 * 683 * @see #getAxisValue(int, int) 684 * @see #getHistoricalAxisValue(int, int, int) 685 * @see MotionEvent.PointerCoords#getAxisValue(int) 686 * @see InputDevice#getMotionRange 687 */ 688 public static final int AXIS_Z = 11; 689 690 /** 691 * Axis constant: X Rotation axis of a motion event. 692 * <p> 693 * <ul> 694 * <li>For a joystick, reports the absolute rotation angle about the X axis. 695 * The value is normalized to a range from -1.0 (counter-clockwise) to 1.0 (clockwise). 696 * </ul> 697 * </p> 698 * 699 * @see #getAxisValue(int, int) 700 * @see #getHistoricalAxisValue(int, int, int) 701 * @see MotionEvent.PointerCoords#getAxisValue(int) 702 * @see InputDevice#getMotionRange 703 */ 704 public static final int AXIS_RX = 12; 705 706 /** 707 * Axis constant: Y Rotation axis of a motion event. 708 * <p> 709 * <ul> 710 * <li>For a joystick, reports the absolute rotation angle about the Y axis. 711 * The value is normalized to a range from -1.0 (counter-clockwise) to 1.0 (clockwise). 712 * </ul> 713 * </p> 714 * 715 * @see #getAxisValue(int, int) 716 * @see #getHistoricalAxisValue(int, int, int) 717 * @see MotionEvent.PointerCoords#getAxisValue(int) 718 * @see InputDevice#getMotionRange 719 */ 720 public static final int AXIS_RY = 13; 721 722 /** 723 * Axis constant: Z Rotation axis of a motion event. 724 * <p> 725 * <ul> 726 * <li>For a joystick, reports the absolute rotation angle about the Z axis. 727 * The value is normalized to a range from -1.0 (counter-clockwise) to 1.0 (clockwise). 728 * <em>On game pads with two analog joysticks, this axis is often reinterpreted 729 * to report the absolute Y position of the second joystick instead.</em> 730 * </ul> 731 * </p> 732 * 733 * @see #getAxisValue(int, int) 734 * @see #getHistoricalAxisValue(int, int, int) 735 * @see MotionEvent.PointerCoords#getAxisValue(int) 736 * @see InputDevice#getMotionRange 737 */ 738 public static final int AXIS_RZ = 14; 739 740 /** 741 * Axis constant: Hat X axis of a motion event. 742 * <p> 743 * <ul> 744 * <li>For a joystick, reports the absolute X position of the directional hat control. 745 * The value is normalized to a range from -1.0 (left) to 1.0 (right). 746 * </ul> 747 * </p> 748 * 749 * @see #getAxisValue(int, int) 750 * @see #getHistoricalAxisValue(int, int, int) 751 * @see MotionEvent.PointerCoords#getAxisValue(int) 752 * @see InputDevice#getMotionRange 753 */ 754 public static final int AXIS_HAT_X = 15; 755 756 /** 757 * Axis constant: Hat Y axis of a motion event. 758 * <p> 759 * <ul> 760 * <li>For a joystick, reports the absolute Y position of the directional hat control. 761 * The value is normalized to a range from -1.0 (up) to 1.0 (down). 762 * </ul> 763 * </p> 764 * 765 * @see #getAxisValue(int, int) 766 * @see #getHistoricalAxisValue(int, int, int) 767 * @see MotionEvent.PointerCoords#getAxisValue(int) 768 * @see InputDevice#getMotionRange 769 */ 770 public static final int AXIS_HAT_Y = 16; 771 772 /** 773 * Axis constant: Left Trigger axis of a motion event. 774 * <p> 775 * <ul> 776 * <li>For a joystick, reports the absolute position of the left trigger control. 777 * The value is normalized to a range from 0.0 (released) to 1.0 (fully pressed). 778 * </ul> 779 * </p> 780 * 781 * @see #getAxisValue(int, int) 782 * @see #getHistoricalAxisValue(int, int, int) 783 * @see MotionEvent.PointerCoords#getAxisValue(int) 784 * @see InputDevice#getMotionRange 785 */ 786 public static final int AXIS_LTRIGGER = 17; 787 788 /** 789 * Axis constant: Right Trigger axis of a motion event. 790 * <p> 791 * <ul> 792 * <li>For a joystick, reports the absolute position of the right trigger control. 793 * The value is normalized to a range from 0.0 (released) to 1.0 (fully pressed). 794 * </ul> 795 * </p> 796 * 797 * @see #getAxisValue(int, int) 798 * @see #getHistoricalAxisValue(int, int, int) 799 * @see MotionEvent.PointerCoords#getAxisValue(int) 800 * @see InputDevice#getMotionRange 801 */ 802 public static final int AXIS_RTRIGGER = 18; 803 804 /** 805 * Axis constant: Throttle axis of a motion event. 806 * <p> 807 * <ul> 808 * <li>For a joystick, reports the absolute position of the throttle control. 809 * The value is normalized to a range from 0.0 (fully open) to 1.0 (fully closed). 810 * </ul> 811 * </p> 812 * 813 * @see #getAxisValue(int, int) 814 * @see #getHistoricalAxisValue(int, int, int) 815 * @see MotionEvent.PointerCoords#getAxisValue(int) 816 * @see InputDevice#getMotionRange 817 */ 818 public static final int AXIS_THROTTLE = 19; 819 820 /** 821 * Axis constant: Rudder axis of a motion event. 822 * <p> 823 * <ul> 824 * <li>For a joystick, reports the absolute position of the rudder control. 825 * The value is normalized to a range from -1.0 (turn left) to 1.0 (turn right). 826 * </ul> 827 * </p> 828 * 829 * @see #getAxisValue(int, int) 830 * @see #getHistoricalAxisValue(int, int, int) 831 * @see MotionEvent.PointerCoords#getAxisValue(int) 832 * @see InputDevice#getMotionRange 833 */ 834 public static final int AXIS_RUDDER = 20; 835 836 /** 837 * Axis constant: Wheel axis of a motion event. 838 * <p> 839 * <ul> 840 * <li>For a joystick, reports the absolute position of the steering wheel control. 841 * The value is normalized to a range from -1.0 (turn left) to 1.0 (turn right). 842 * </ul> 843 * </p> 844 * 845 * @see #getAxisValue(int, int) 846 * @see #getHistoricalAxisValue(int, int, int) 847 * @see MotionEvent.PointerCoords#getAxisValue(int) 848 * @see InputDevice#getMotionRange 849 */ 850 public static final int AXIS_WHEEL = 21; 851 852 /** 853 * Axis constant: Gas axis of a motion event. 854 * <p> 855 * <ul> 856 * <li>For a joystick, reports the absolute position of the gas (accelerator) control. 857 * The value is normalized to a range from 0.0 (no acceleration) 858 * to 1.0 (maximum acceleration). 859 * </ul> 860 * </p> 861 * 862 * @see #getAxisValue(int, int) 863 * @see #getHistoricalAxisValue(int, int, int) 864 * @see MotionEvent.PointerCoords#getAxisValue(int) 865 * @see InputDevice#getMotionRange 866 */ 867 public static final int AXIS_GAS = 22; 868 869 /** 870 * Axis constant: Brake axis of a motion event. 871 * <p> 872 * <ul> 873 * <li>For a joystick, reports the absolute position of the brake control. 874 * The value is normalized to a range from 0.0 (no braking) to 1.0 (maximum braking). 875 * </ul> 876 * </p> 877 * 878 * @see #getAxisValue(int, int) 879 * @see #getHistoricalAxisValue(int, int, int) 880 * @see MotionEvent.PointerCoords#getAxisValue(int) 881 * @see InputDevice#getMotionRange 882 */ 883 public static final int AXIS_BRAKE = 23; 884 885 /** 886 * Axis constant: Distance axis of a motion event. 887 * <p> 888 * <ul> 889 * <li>For a stylus, reports the distance of the stylus from the screen. 890 * A value of 0.0 indicates direct contact and larger values indicate increasing 891 * distance from the surface. 892 * </ul> 893 * </p> 894 * 895 * @see #getAxisValue(int, int) 896 * @see #getHistoricalAxisValue(int, int, int) 897 * @see MotionEvent.PointerCoords#getAxisValue(int) 898 * @see InputDevice#getMotionRange 899 */ 900 public static final int AXIS_DISTANCE = 24; 901 902 /** 903 * Axis constant: Tilt axis of a motion event. 904 * <p> 905 * <ul> 906 * <li>For a stylus, reports the tilt angle of the stylus in radians where 907 * 0 radians indicates that the stylus is being held perpendicular to the 908 * surface, and PI/2 radians indicates that the stylus is being held flat 909 * against the surface. 910 * </ul> 911 * </p> 912 * 913 * @see #getAxisValue(int, int) 914 * @see #getHistoricalAxisValue(int, int, int) 915 * @see MotionEvent.PointerCoords#getAxisValue(int, int) 916 * @see InputDevice#getMotionRange 917 */ 918 public static final int AXIS_TILT = 25; 919 920 /** 921 * Axis constant: Generic 1 axis of a motion event. 922 * The interpretation of a generic axis is device-specific. 923 * 924 * @see #getAxisValue(int, int) 925 * @see #getHistoricalAxisValue(int, int, int) 926 * @see MotionEvent.PointerCoords#getAxisValue(int) 927 * @see InputDevice#getMotionRange 928 */ 929 public static final int AXIS_GENERIC_1 = 32; 930 931 /** 932 * Axis constant: Generic 2 axis of a motion event. 933 * The interpretation of a generic axis is device-specific. 934 * 935 * @see #getAxisValue(int, int) 936 * @see #getHistoricalAxisValue(int, int, int) 937 * @see MotionEvent.PointerCoords#getAxisValue(int) 938 * @see InputDevice#getMotionRange 939 */ 940 public static final int AXIS_GENERIC_2 = 33; 941 942 /** 943 * Axis constant: Generic 3 axis of a motion event. 944 * The interpretation of a generic axis is device-specific. 945 * 946 * @see #getAxisValue(int, int) 947 * @see #getHistoricalAxisValue(int, int, int) 948 * @see MotionEvent.PointerCoords#getAxisValue(int) 949 * @see InputDevice#getMotionRange 950 */ 951 public static final int AXIS_GENERIC_3 = 34; 952 953 /** 954 * Axis constant: Generic 4 axis of a motion event. 955 * The interpretation of a generic axis is device-specific. 956 * 957 * @see #getAxisValue(int, int) 958 * @see #getHistoricalAxisValue(int, int, int) 959 * @see MotionEvent.PointerCoords#getAxisValue(int) 960 * @see InputDevice#getMotionRange 961 */ 962 public static final int AXIS_GENERIC_4 = 35; 963 964 /** 965 * Axis constant: Generic 5 axis of a motion event. 966 * The interpretation of a generic axis is device-specific. 967 * 968 * @see #getAxisValue(int, int) 969 * @see #getHistoricalAxisValue(int, int, int) 970 * @see MotionEvent.PointerCoords#getAxisValue(int) 971 * @see InputDevice#getMotionRange 972 */ 973 public static final int AXIS_GENERIC_5 = 36; 974 975 /** 976 * Axis constant: Generic 6 axis of a motion event. 977 * The interpretation of a generic axis is device-specific. 978 * 979 * @see #getAxisValue(int, int) 980 * @see #getHistoricalAxisValue(int, int, int) 981 * @see MotionEvent.PointerCoords#getAxisValue(int) 982 * @see InputDevice#getMotionRange 983 */ 984 public static final int AXIS_GENERIC_6 = 37; 985 986 /** 987 * Axis constant: Generic 7 axis of a motion event. 988 * The interpretation of a generic axis is device-specific. 989 * 990 * @see #getAxisValue(int, int) 991 * @see #getHistoricalAxisValue(int, int, int) 992 * @see MotionEvent.PointerCoords#getAxisValue(int) 993 * @see InputDevice#getMotionRange 994 */ 995 public static final int AXIS_GENERIC_7 = 38; 996 997 /** 998 * Axis constant: Generic 8 axis of a motion event. 999 * The interpretation of a generic axis is device-specific. 1000 * 1001 * @see #getAxisValue(int, int) 1002 * @see #getHistoricalAxisValue(int, int, int) 1003 * @see MotionEvent.PointerCoords#getAxisValue(int) 1004 * @see InputDevice#getMotionRange 1005 */ 1006 public static final int AXIS_GENERIC_8 = 39; 1007 1008 /** 1009 * Axis constant: Generic 9 axis of a motion event. 1010 * The interpretation of a generic axis is device-specific. 1011 * 1012 * @see #getAxisValue(int, int) 1013 * @see #getHistoricalAxisValue(int, int, int) 1014 * @see MotionEvent.PointerCoords#getAxisValue(int) 1015 * @see InputDevice#getMotionRange 1016 */ 1017 public static final int AXIS_GENERIC_9 = 40; 1018 1019 /** 1020 * Axis constant: Generic 10 axis of a motion event. 1021 * The interpretation of a generic axis is device-specific. 1022 * 1023 * @see #getAxisValue(int, int) 1024 * @see #getHistoricalAxisValue(int, int, int) 1025 * @see MotionEvent.PointerCoords#getAxisValue(int) 1026 * @see InputDevice#getMotionRange 1027 */ 1028 public static final int AXIS_GENERIC_10 = 41; 1029 1030 /** 1031 * Axis constant: Generic 11 axis of a motion event. 1032 * The interpretation of a generic axis is device-specific. 1033 * 1034 * @see #getAxisValue(int, int) 1035 * @see #getHistoricalAxisValue(int, int, int) 1036 * @see MotionEvent.PointerCoords#getAxisValue(int) 1037 * @see InputDevice#getMotionRange 1038 */ 1039 public static final int AXIS_GENERIC_11 = 42; 1040 1041 /** 1042 * Axis constant: Generic 12 axis of a motion event. 1043 * The interpretation of a generic axis is device-specific. 1044 * 1045 * @see #getAxisValue(int, int) 1046 * @see #getHistoricalAxisValue(int, int, int) 1047 * @see MotionEvent.PointerCoords#getAxisValue(int) 1048 * @see InputDevice#getMotionRange 1049 */ 1050 public static final int AXIS_GENERIC_12 = 43; 1051 1052 /** 1053 * Axis constant: Generic 13 axis of a motion event. 1054 * The interpretation of a generic axis is device-specific. 1055 * 1056 * @see #getAxisValue(int, int) 1057 * @see #getHistoricalAxisValue(int, int, int) 1058 * @see MotionEvent.PointerCoords#getAxisValue(int) 1059 * @see InputDevice#getMotionRange 1060 */ 1061 public static final int AXIS_GENERIC_13 = 44; 1062 1063 /** 1064 * Axis constant: Generic 14 axis of a motion event. 1065 * The interpretation of a generic axis is device-specific. 1066 * 1067 * @see #getAxisValue(int, int) 1068 * @see #getHistoricalAxisValue(int, int, int) 1069 * @see MotionEvent.PointerCoords#getAxisValue(int) 1070 * @see InputDevice#getMotionRange 1071 */ 1072 public static final int AXIS_GENERIC_14 = 45; 1073 1074 /** 1075 * Axis constant: Generic 15 axis of a motion event. 1076 * The interpretation of a generic axis is device-specific. 1077 * 1078 * @see #getAxisValue(int, int) 1079 * @see #getHistoricalAxisValue(int, int, int) 1080 * @see MotionEvent.PointerCoords#getAxisValue(int) 1081 * @see InputDevice#getMotionRange 1082 */ 1083 public static final int AXIS_GENERIC_15 = 46; 1084 1085 /** 1086 * Axis constant: Generic 16 axis of a motion event. 1087 * The interpretation of a generic axis is device-specific. 1088 * 1089 * @see #getAxisValue(int, int) 1090 * @see #getHistoricalAxisValue(int, int, int) 1091 * @see MotionEvent.PointerCoords#getAxisValue(int) 1092 * @see InputDevice#getMotionRange 1093 */ 1094 public static final int AXIS_GENERIC_16 = 47; 1095 1096 // NOTE: If you add a new axis here you must also add it to: 1097 // native/include/android/input.h 1098 // frameworks/base/include/ui/KeycodeLabels.h 1099 1100 // Symbolic names of all axes. 1101 private static final SparseArray<String> AXIS_SYMBOLIC_NAMES = new SparseArray<String>(); 1102 static { 1103 SparseArray<String> names = AXIS_SYMBOLIC_NAMES; 1104 names.append(AXIS_X, "AXIS_X"); 1105 names.append(AXIS_Y, "AXIS_Y"); 1106 names.append(AXIS_PRESSURE, "AXIS_PRESSURE"); 1107 names.append(AXIS_SIZE, "AXIS_SIZE"); 1108 names.append(AXIS_TOUCH_MAJOR, "AXIS_TOUCH_MAJOR"); 1109 names.append(AXIS_TOUCH_MINOR, "AXIS_TOUCH_MINOR"); 1110 names.append(AXIS_TOOL_MAJOR, "AXIS_TOOL_MAJOR"); 1111 names.append(AXIS_TOOL_MINOR, "AXIS_TOOL_MINOR"); 1112 names.append(AXIS_ORIENTATION, "AXIS_ORIENTATION"); 1113 names.append(AXIS_VSCROLL, "AXIS_VSCROLL"); 1114 names.append(AXIS_HSCROLL, "AXIS_HSCROLL"); 1115 names.append(AXIS_Z, "AXIS_Z"); 1116 names.append(AXIS_RX, "AXIS_RX"); 1117 names.append(AXIS_RY, "AXIS_RY"); 1118 names.append(AXIS_RZ, "AXIS_RZ"); 1119 names.append(AXIS_HAT_X, "AXIS_HAT_X"); 1120 names.append(AXIS_HAT_Y, "AXIS_HAT_Y"); 1121 names.append(AXIS_LTRIGGER, "AXIS_LTRIGGER"); 1122 names.append(AXIS_RTRIGGER, "AXIS_RTRIGGER"); 1123 names.append(AXIS_THROTTLE, "AXIS_THROTTLE"); 1124 names.append(AXIS_RUDDER, "AXIS_RUDDER"); 1125 names.append(AXIS_WHEEL, "AXIS_WHEEL"); 1126 names.append(AXIS_GAS, "AXIS_GAS"); 1127 names.append(AXIS_BRAKE, "AXIS_BRAKE"); 1128 names.append(AXIS_DISTANCE, "AXIS_DISTANCE"); 1129 names.append(AXIS_TILT, "AXIS_TILT"); 1130 names.append(AXIS_GENERIC_1, "AXIS_GENERIC_1"); 1131 names.append(AXIS_GENERIC_2, "AXIS_GENERIC_2"); 1132 names.append(AXIS_GENERIC_3, "AXIS_GENERIC_3"); 1133 names.append(AXIS_GENERIC_4, "AXIS_GENERIC_4"); 1134 names.append(AXIS_GENERIC_5, "AXIS_GENERIC_5"); 1135 names.append(AXIS_GENERIC_6, "AXIS_GENERIC_6"); 1136 names.append(AXIS_GENERIC_7, "AXIS_GENERIC_7"); 1137 names.append(AXIS_GENERIC_8, "AXIS_GENERIC_8"); 1138 names.append(AXIS_GENERIC_9, "AXIS_GENERIC_9"); 1139 names.append(AXIS_GENERIC_10, "AXIS_GENERIC_10"); 1140 names.append(AXIS_GENERIC_11, "AXIS_GENERIC_11"); 1141 names.append(AXIS_GENERIC_12, "AXIS_GENERIC_12"); 1142 names.append(AXIS_GENERIC_13, "AXIS_GENERIC_13"); 1143 names.append(AXIS_GENERIC_14, "AXIS_GENERIC_14"); 1144 names.append(AXIS_GENERIC_15, "AXIS_GENERIC_15"); 1145 names.append(AXIS_GENERIC_16, "AXIS_GENERIC_16"); 1146 } 1147 1148 /** 1149 * Button constant: Primary button (left mouse button). 1150 * 1151 * This button constant is not set in response to simple touches with a finger 1152 * or stylus tip. The user must actually push a button. 1153 * 1154 * @see #getButtonState 1155 */ 1156 public static final int BUTTON_PRIMARY = 1 << 0; 1157 1158 /** 1159 * Button constant: Secondary button (right mouse button, stylus first button). 1160 * 1161 * @see #getButtonState 1162 */ 1163 public static final int BUTTON_SECONDARY = 1 << 1; 1164 1165 /** 1166 * Button constant: Tertiary button (middle mouse button, stylus second button). 1167 * 1168 * @see #getButtonState 1169 */ 1170 public static final int BUTTON_TERTIARY = 1 << 2; 1171 1172 /** 1173 * Button constant: Back button pressed (mouse back button). 1174 * <p> 1175 * The system may send a {@link KeyEvent#KEYCODE_BACK} key press to the application 1176 * when this button is pressed. 1177 * </p> 1178 * 1179 * @see #getButtonState 1180 */ 1181 public static final int BUTTON_BACK = 1 << 3; 1182 1183 /** 1184 * Button constant: Forward button pressed (mouse forward button). 1185 * <p> 1186 * The system may send a {@link KeyEvent#KEYCODE_FORWARD} key press to the application 1187 * when this button is pressed. 1188 * </p> 1189 * 1190 * @see #getButtonState 1191 */ 1192 public static final int BUTTON_FORWARD = 1 << 4; 1193 1194 // NOTE: If you add a new axis here you must also add it to: 1195 // native/include/android/input.h 1196 1197 // Symbolic names of all button states in bit order from least significant 1198 // to most significant. 1199 private static final String[] BUTTON_SYMBOLIC_NAMES = new String[] { 1200 "BUTTON_PRIMARY", 1201 "BUTTON_SECONDARY", 1202 "BUTTON_TERTIARY", 1203 "BUTTON_BACK", 1204 "BUTTON_FORWARD", 1205 "0x00000020", 1206 "0x00000040", 1207 "0x00000080", 1208 "0x00000100", 1209 "0x00000200", 1210 "0x00000400", 1211 "0x00000800", 1212 "0x00001000", 1213 "0x00002000", 1214 "0x00004000", 1215 "0x00008000", 1216 "0x00010000", 1217 "0x00020000", 1218 "0x00040000", 1219 "0x00080000", 1220 "0x00100000", 1221 "0x00200000", 1222 "0x00400000", 1223 "0x00800000", 1224 "0x01000000", 1225 "0x02000000", 1226 "0x04000000", 1227 "0x08000000", 1228 "0x10000000", 1229 "0x20000000", 1230 "0x40000000", 1231 "0x80000000", 1232 }; 1233 1234 /** 1235 * Tool type constant: Unknown tool type. 1236 * This constant is used when the tool type is not known or is not relevant, 1237 * such as for a trackball or other non-pointing device. 1238 * 1239 * @see #getToolType 1240 */ 1241 public static final int TOOL_TYPE_UNKNOWN = 0; 1242 1243 /** 1244 * Tool type constant: The tool is a finger. 1245 * 1246 * @see #getToolType 1247 */ 1248 public static final int TOOL_TYPE_FINGER = 1; 1249 1250 /** 1251 * Tool type constant: The tool is a stylus. 1252 * 1253 * @see #getToolType 1254 */ 1255 public static final int TOOL_TYPE_STYLUS = 2; 1256 1257 /** 1258 * Tool type constant: The tool is a mouse or trackpad. 1259 * 1260 * @see #getToolType 1261 */ 1262 public static final int TOOL_TYPE_MOUSE = 3; 1263 1264 /** 1265 * Tool type constant: The tool is an eraser or a stylus being used in an inverted posture. 1266 * 1267 * @see #getToolType 1268 */ 1269 public static final int TOOL_TYPE_ERASER = 4; 1270 1271 // NOTE: If you add a new tool type here you must also add it to: 1272 // native/include/android/input.h 1273 1274 // Symbolic names of all tool types. 1275 private static final SparseArray<String> TOOL_TYPE_SYMBOLIC_NAMES = new SparseArray<String>(); 1276 static { 1277 SparseArray<String> names = TOOL_TYPE_SYMBOLIC_NAMES; 1278 names.append(TOOL_TYPE_UNKNOWN, "TOOL_TYPE_UNKNOWN"); 1279 names.append(TOOL_TYPE_FINGER, "TOOL_TYPE_FINGER"); 1280 names.append(TOOL_TYPE_STYLUS, "TOOL_TYPE_STYLUS"); 1281 names.append(TOOL_TYPE_MOUSE, "TOOL_TYPE_MOUSE"); 1282 names.append(TOOL_TYPE_ERASER, "TOOL_TYPE_ERASER"); 1283 } 1284 1285 // Private value for history pos that obtains the current sample. 1286 private static final int HISTORY_CURRENT = -0x80000000; 1287 1288 private static final int MAX_RECYCLED = 10; 1289 private static final Object gRecyclerLock = new Object(); 1290 private static int gRecyclerUsed; 1291 private static MotionEvent gRecyclerTop; 1292 1293 // Shared temporary objects used when translating coordinates supplied by 1294 // the caller into single element PointerCoords and pointer id arrays. 1295 private static final Object gSharedTempLock = new Object(); 1296 private static PointerCoords[] gSharedTempPointerCoords; 1297 private static PointerProperties[] gSharedTempPointerProperties; 1298 private static int[] gSharedTempPointerIndexMap; 1299 1300 private static final void ensureSharedTempPointerCapacity(int desiredCapacity) { 1301 if (gSharedTempPointerCoords == null 1302 || gSharedTempPointerCoords.length < desiredCapacity) { 1303 int capacity = gSharedTempPointerCoords != null ? gSharedTempPointerCoords.length : 8; 1304 while (capacity < desiredCapacity) { 1305 capacity *= 2; 1306 } 1307 gSharedTempPointerCoords = PointerCoords.createArray(capacity); 1308 gSharedTempPointerProperties = PointerProperties.createArray(capacity); 1309 gSharedTempPointerIndexMap = new int[capacity]; 1310 } 1311 } 1312 1313 // Pointer to the native MotionEvent object that contains the actual data. 1314 private int mNativePtr; 1315 1316 private MotionEvent mNext; 1317 1318 private static native int nativeInitialize(int nativePtr, 1319 int deviceId, int source, int action, int flags, int edgeFlags, 1320 int metaState, int buttonState, 1321 float xOffset, float yOffset, float xPrecision, float yPrecision, 1322 long downTimeNanos, long eventTimeNanos, 1323 int pointerCount, PointerProperties[] pointerIds, PointerCoords[] pointerCoords); 1324 private static native int nativeCopy(int destNativePtr, int sourceNativePtr, 1325 boolean keepHistory); 1326 private static native void nativeDispose(int nativePtr); 1327 private static native void nativeAddBatch(int nativePtr, long eventTimeNanos, 1328 PointerCoords[] pointerCoords, int metaState); 1329 1330 private static native int nativeGetDeviceId(int nativePtr); 1331 private static native int nativeGetSource(int nativePtr); 1332 private static native int nativeSetSource(int nativePtr, int source); 1333 private static native int nativeGetAction(int nativePtr); 1334 private static native void nativeSetAction(int nativePtr, int action); 1335 private static native boolean nativeIsTouchEvent(int nativePtr); 1336 private static native int nativeGetFlags(int nativePtr); 1337 private static native void nativeSetFlags(int nativePtr, int flags); 1338 private static native int nativeGetEdgeFlags(int nativePtr); 1339 private static native void nativeSetEdgeFlags(int nativePtr, int action); 1340 private static native int nativeGetMetaState(int nativePtr); 1341 private static native int nativeGetButtonState(int nativePtr); 1342 private static native void nativeOffsetLocation(int nativePtr, float deltaX, float deltaY); 1343 private static native float nativeGetXOffset(int nativePtr); 1344 private static native float nativeGetYOffset(int nativePtr); 1345 private static native float nativeGetXPrecision(int nativePtr); 1346 private static native float nativeGetYPrecision(int nativePtr); 1347 private static native long nativeGetDownTimeNanos(int nativePtr); 1348 private static native void nativeSetDownTimeNanos(int nativePtr, long downTime); 1349 1350 private static native int nativeGetPointerCount(int nativePtr); 1351 private static native int nativeGetPointerId(int nativePtr, int pointerIndex); 1352 private static native int nativeGetToolType(int nativePtr, int pointerIndex); 1353 private static native int nativeFindPointerIndex(int nativePtr, int pointerId); 1354 1355 private static native int nativeGetHistorySize(int nativePtr); 1356 private static native long nativeGetEventTimeNanos(int nativePtr, int historyPos); 1357 private static native float nativeGetRawAxisValue(int nativePtr, 1358 int axis, int pointerIndex, int historyPos); 1359 private static native float nativeGetAxisValue(int nativePtr, 1360 int axis, int pointerIndex, int historyPos); 1361 private static native void nativeGetPointerCoords(int nativePtr, 1362 int pointerIndex, int historyPos, PointerCoords outPointerCoords); 1363 private static native void nativeGetPointerProperties(int nativePtr, 1364 int pointerIndex, PointerProperties outPointerProperties); 1365 1366 private static native void nativeScale(int nativePtr, float scale); 1367 private static native void nativeTransform(int nativePtr, Matrix matrix); 1368 1369 private static native int nativeReadFromParcel(int nativePtr, Parcel parcel); 1370 private static native void nativeWriteToParcel(int nativePtr, Parcel parcel); 1371 1372 private MotionEvent() { 1373 } 1374 1375 @Override 1376 protected void finalize() throws Throwable { 1377 try { 1378 if (mNativePtr != 0) { 1379 nativeDispose(mNativePtr); 1380 mNativePtr = 0; 1381 } 1382 } finally { 1383 super.finalize(); 1384 } 1385 } 1386 1387 static private MotionEvent obtain() { 1388 final MotionEvent ev; 1389 synchronized (gRecyclerLock) { 1390 ev = gRecyclerTop; 1391 if (ev == null) { 1392 return new MotionEvent(); 1393 } 1394 gRecyclerTop = ev.mNext; 1395 gRecyclerUsed -= 1; 1396 } 1397 ev.mNext = null; 1398 ev.prepareForReuse(); 1399 return ev; 1400 } 1401 1402 /** 1403 * Create a new MotionEvent, filling in all of the basic values that 1404 * define the motion. 1405 * 1406 * @param downTime The time (in ms) when the user originally pressed down to start 1407 * a stream of position events. This must be obtained from {@link SystemClock#uptimeMillis()}. 1408 * @param eventTime The the time (in ms) when this specific event was generated. This 1409 * must be obtained from {@link SystemClock#uptimeMillis()}. 1410 * @param action The kind of action being performed, such as {@link #ACTION_DOWN}. 1411 * @param pointerCount The number of pointers that will be in this event. 1412 * @param pointerProperties An array of <em>pointerCount</em> values providing 1413 * a {@link PointerProperties} property object for each pointer, which must 1414 * include the pointer identifier. 1415 * @param pointerCoords An array of <em>pointerCount</em> values providing 1416 * a {@link PointerCoords} coordinate object for each pointer. 1417 * @param metaState The state of any meta / modifier keys that were in effect when 1418 * the event was generated. 1419 * @param buttonState The state of buttons that are pressed. 1420 * @param xPrecision The precision of the X coordinate being reported. 1421 * @param yPrecision The precision of the Y coordinate being reported. 1422 * @param deviceId The id for the device that this event came from. An id of 1423 * zero indicates that the event didn't come from a physical device; other 1424 * numbers are arbitrary and you shouldn't depend on the values. 1425 * @param edgeFlags A bitfield indicating which edges, if any, were touched by this 1426 * MotionEvent. 1427 * @param source The source of this event. 1428 * @param flags The motion event flags. 1429 */ 1430 static public MotionEvent obtain(long downTime, long eventTime, 1431 int action, int pointerCount, PointerProperties[] pointerProperties, 1432 PointerCoords[] pointerCoords, int metaState, int buttonState, 1433 float xPrecision, float yPrecision, int deviceId, 1434 int edgeFlags, int source, int flags) { 1435 MotionEvent ev = obtain(); 1436 ev.mNativePtr = nativeInitialize(ev.mNativePtr, 1437 deviceId, source, action, flags, edgeFlags, metaState, buttonState, 1438 0, 0, xPrecision, yPrecision, 1439 downTime * NS_PER_MS, eventTime * NS_PER_MS, 1440 pointerCount, pointerProperties, pointerCoords); 1441 return ev; 1442 } 1443 1444 /** 1445 * Create a new MotionEvent, filling in all of the basic values that 1446 * define the motion. 1447 * 1448 * @param downTime The time (in ms) when the user originally pressed down to start 1449 * a stream of position events. This must be obtained from {@link SystemClock#uptimeMillis()}. 1450 * @param eventTime The the time (in ms) when this specific event was generated. This 1451 * must be obtained from {@link SystemClock#uptimeMillis()}. 1452 * @param action The kind of action being performed, such as {@link #ACTION_DOWN}. 1453 * @param pointerCount The number of pointers that will be in this event. 1454 * @param pointerIds An array of <em>pointerCount</em> values providing 1455 * an identifier for each pointer. 1456 * @param pointerCoords An array of <em>pointerCount</em> values providing 1457 * a {@link PointerCoords} coordinate object for each pointer. 1458 * @param metaState The state of any meta / modifier keys that were in effect when 1459 * the event was generated. 1460 * @param xPrecision The precision of the X coordinate being reported. 1461 * @param yPrecision The precision of the Y coordinate being reported. 1462 * @param deviceId The id for the device that this event came from. An id of 1463 * zero indicates that the event didn't come from a physical device; other 1464 * numbers are arbitrary and you shouldn't depend on the values. 1465 * @param edgeFlags A bitfield indicating which edges, if any, were touched by this 1466 * MotionEvent. 1467 * @param source The source of this event. 1468 * @param flags The motion event flags. 1469 * 1470 * @deprecated Use {@link #obtain(long, long, int, int, PointerProperties[], PointerCoords[], int, int, float, float, int, int, int, int)} 1471 * instead. 1472 */ 1473 @Deprecated 1474 static public MotionEvent obtain(long downTime, long eventTime, 1475 int action, int pointerCount, int[] pointerIds, PointerCoords[] pointerCoords, 1476 int metaState, float xPrecision, float yPrecision, int deviceId, 1477 int edgeFlags, int source, int flags) { 1478 synchronized (gSharedTempLock) { 1479 ensureSharedTempPointerCapacity(pointerCount); 1480 final PointerProperties[] pp = gSharedTempPointerProperties; 1481 for (int i = 0; i < pointerCount; i++) { 1482 pp[i].clear(); 1483 pp[i].id = pointerIds[i]; 1484 } 1485 return obtain(downTime, eventTime, action, pointerCount, pp, 1486 pointerCoords, metaState, 0, xPrecision, yPrecision, deviceId, 1487 edgeFlags, source, flags); 1488 } 1489 } 1490 1491 /** 1492 * Create a new MotionEvent, filling in all of the basic values that 1493 * define the motion. 1494 * 1495 * @param downTime The time (in ms) when the user originally pressed down to start 1496 * a stream of position events. This must be obtained from {@link SystemClock#uptimeMillis()}. 1497 * @param eventTime The the time (in ms) when this specific event was generated. This 1498 * must be obtained from {@link SystemClock#uptimeMillis()}. 1499 * @param action The kind of action being performed, such as {@link #ACTION_DOWN}. 1500 * @param x The X coordinate of this event. 1501 * @param y The Y coordinate of this event. 1502 * @param pressure The current pressure of this event. The pressure generally 1503 * ranges from 0 (no pressure at all) to 1 (normal pressure), however 1504 * values higher than 1 may be generated depending on the calibration of 1505 * the input device. 1506 * @param size A scaled value of the approximate size of the area being pressed when 1507 * touched with the finger. The actual value in pixels corresponding to the finger 1508 * touch is normalized with a device specific range of values 1509 * and scaled to a value between 0 and 1. 1510 * @param metaState The state of any meta / modifier keys that were in effect when 1511 * the event was generated. 1512 * @param xPrecision The precision of the X coordinate being reported. 1513 * @param yPrecision The precision of the Y coordinate being reported. 1514 * @param deviceId The id for the device that this event came from. An id of 1515 * zero indicates that the event didn't come from a physical device; other 1516 * numbers are arbitrary and you shouldn't depend on the values. 1517 * @param edgeFlags A bitfield indicating which edges, if any, were touched by this 1518 * MotionEvent. 1519 */ 1520 static public MotionEvent obtain(long downTime, long eventTime, int action, 1521 float x, float y, float pressure, float size, int metaState, 1522 float xPrecision, float yPrecision, int deviceId, int edgeFlags) { 1523 MotionEvent ev = obtain(); 1524 synchronized (gSharedTempLock) { 1525 ensureSharedTempPointerCapacity(1); 1526 final PointerProperties[] pp = gSharedTempPointerProperties; 1527 pp[0].clear(); 1528 pp[0].id = 0; 1529 1530 final PointerCoords pc[] = gSharedTempPointerCoords; 1531 pc[0].clear(); 1532 pc[0].x = x; 1533 pc[0].y = y; 1534 pc[0].pressure = pressure; 1535 pc[0].size = size; 1536 1537 ev.mNativePtr = nativeInitialize(ev.mNativePtr, 1538 deviceId, InputDevice.SOURCE_UNKNOWN, action, 0, edgeFlags, metaState, 0, 1539 0, 0, xPrecision, yPrecision, 1540 downTime * NS_PER_MS, eventTime * NS_PER_MS, 1541 1, pp, pc); 1542 return ev; 1543 } 1544 } 1545 1546 /** 1547 * Create a new MotionEvent, filling in all of the basic values that 1548 * define the motion. 1549 * 1550 * @param downTime The time (in ms) when the user originally pressed down to start 1551 * a stream of position events. This must be obtained from {@link SystemClock#uptimeMillis()}. 1552 * @param eventTime The the time (in ms) when this specific event was generated. This 1553 * must be obtained from {@link SystemClock#uptimeMillis()}. 1554 * @param action The kind of action being performed, such as {@link #ACTION_DOWN}. 1555 * @param pointerCount The number of pointers that are active in this event. 1556 * @param x The X coordinate of this event. 1557 * @param y The Y coordinate of this event. 1558 * @param pressure The current pressure of this event. The pressure generally 1559 * ranges from 0 (no pressure at all) to 1 (normal pressure), however 1560 * values higher than 1 may be generated depending on the calibration of 1561 * the input device. 1562 * @param size A scaled value of the approximate size of the area being pressed when 1563 * touched with the finger. The actual value in pixels corresponding to the finger 1564 * touch is normalized with a device specific range of values 1565 * and scaled to a value between 0 and 1. 1566 * @param metaState The state of any meta / modifier keys that were in effect when 1567 * the event was generated. 1568 * @param xPrecision The precision of the X coordinate being reported. 1569 * @param yPrecision The precision of the Y coordinate being reported. 1570 * @param deviceId The id for the device that this event came from. An id of 1571 * zero indicates that the event didn't come from a physical device; other 1572 * numbers are arbitrary and you shouldn't depend on the values. 1573 * @param edgeFlags A bitfield indicating which edges, if any, were touched by this 1574 * MotionEvent. 1575 * 1576 * @deprecated Use {@link #obtain(long, long, int, float, float, float, float, int, float, float, int, int)} 1577 * instead. 1578 */ 1579 @Deprecated 1580 static public MotionEvent obtain(long downTime, long eventTime, int action, 1581 int pointerCount, float x, float y, float pressure, float size, int metaState, 1582 float xPrecision, float yPrecision, int deviceId, int edgeFlags) { 1583 return obtain(downTime, eventTime, action, x, y, pressure, size, 1584 metaState, xPrecision, yPrecision, deviceId, edgeFlags); 1585 } 1586 1587 /** 1588 * Create a new MotionEvent, filling in a subset of the basic motion 1589 * values. Those not specified here are: device id (always 0), pressure 1590 * and size (always 1), x and y precision (always 1), and edgeFlags (always 0). 1591 * 1592 * @param downTime The time (in ms) when the user originally pressed down to start 1593 * a stream of position events. This must be obtained from {@link SystemClock#uptimeMillis()}. 1594 * @param eventTime The the time (in ms) when this specific event was generated. This 1595 * must be obtained from {@link SystemClock#uptimeMillis()}. 1596 * @param action The kind of action being performed, such as {@link #ACTION_DOWN}. 1597 * @param x The X coordinate of this event. 1598 * @param y The Y coordinate of this event. 1599 * @param metaState The state of any meta / modifier keys that were in effect when 1600 * the event was generated. 1601 */ 1602 static public MotionEvent obtain(long downTime, long eventTime, int action, 1603 float x, float y, int metaState) { 1604 return obtain(downTime, eventTime, action, x, y, 1.0f, 1.0f, 1605 metaState, 1.0f, 1.0f, 0, 0); 1606 } 1607 1608 /** 1609 * Create a new MotionEvent, copying from an existing one. 1610 */ 1611 static public MotionEvent obtain(MotionEvent other) { 1612 if (other == null) { 1613 throw new IllegalArgumentException("other motion event must not be null"); 1614 } 1615 1616 MotionEvent ev = obtain(); 1617 ev.mNativePtr = nativeCopy(ev.mNativePtr, other.mNativePtr, true /*keepHistory*/); 1618 return ev; 1619 } 1620 1621 /** 1622 * Create a new MotionEvent, copying from an existing one, but not including 1623 * any historical point information. 1624 */ 1625 static public MotionEvent obtainNoHistory(MotionEvent other) { 1626 if (other == null) { 1627 throw new IllegalArgumentException("other motion event must not be null"); 1628 } 1629 1630 MotionEvent ev = obtain(); 1631 ev.mNativePtr = nativeCopy(ev.mNativePtr, other.mNativePtr, false /*keepHistory*/); 1632 return ev; 1633 } 1634 1635 /** @hide */ 1636 @Override 1637 public MotionEvent copy() { 1638 return obtain(this); 1639 } 1640 1641 /** 1642 * Recycle the MotionEvent, to be re-used by a later caller. After calling 1643 * this function you must not ever touch the event again. 1644 */ 1645 @Override 1646 public final void recycle() { 1647 super.recycle(); 1648 1649 synchronized (gRecyclerLock) { 1650 if (gRecyclerUsed < MAX_RECYCLED) { 1651 gRecyclerUsed++; 1652 mNext = gRecyclerTop; 1653 gRecyclerTop = this; 1654 } 1655 } 1656 } 1657 1658 /** 1659 * Applies a scale factor to all points within this event. 1660 * 1661 * This method is used to adjust touch events to simulate different density 1662 * displays for compatibility mode. The values returned by {@link #getRawX()}, 1663 * {@link #getRawY()}, {@link #getXPrecision()} and {@link #getYPrecision()} 1664 * are also affected by the scale factor. 1665 * 1666 * @param scale The scale factor to apply. 1667 * @hide 1668 */ 1669 public final void scale(float scale) { 1670 if (scale != 1.0f) { 1671 nativeScale(mNativePtr, scale); 1672 } 1673 } 1674 1675 /** {@inheritDoc} */ 1676 @Override 1677 public final int getDeviceId() { 1678 return nativeGetDeviceId(mNativePtr); 1679 } 1680 1681 /** {@inheritDoc} */ 1682 @Override 1683 public final int getSource() { 1684 return nativeGetSource(mNativePtr); 1685 } 1686 1687 /** {@inheritDoc} */ 1688 @Override 1689 public final void setSource(int source) { 1690 nativeSetSource(mNativePtr, source); 1691 } 1692 1693 /** 1694 * Return the kind of action being performed. 1695 * Consider using {@link #getActionMasked} and {@link #getActionIndex} to retrieve 1696 * the separate masked action and pointer index. 1697 * @return The action, such as {@link #ACTION_DOWN} or 1698 * the combination of {@link #ACTION_POINTER_DOWN} with a shifted pointer index. 1699 */ 1700 public final int getAction() { 1701 return nativeGetAction(mNativePtr); 1702 } 1703 1704 /** 1705 * Return the masked action being performed, without pointer index information. 1706 * Use {@link #getActionIndex} to return the index associated with pointer actions. 1707 * @return The action, such as {@link #ACTION_DOWN} or {@link #ACTION_POINTER_DOWN}. 1708 */ 1709 public final int getActionMasked() { 1710 return nativeGetAction(mNativePtr) & ACTION_MASK; 1711 } 1712 1713 /** 1714 * For {@link #ACTION_POINTER_DOWN} or {@link #ACTION_POINTER_UP} 1715 * as returned by {@link #getActionMasked}, this returns the associated 1716 * pointer index. 1717 * The index may be used with {@link #getPointerId(int)}, 1718 * {@link #getX(int)}, {@link #getY(int)}, {@link #getPressure(int)}, 1719 * and {@link #getSize(int)} to get information about the pointer that has 1720 * gone down or up. 1721 * @return The index associated with the action. 1722 */ 1723 public final int getActionIndex() { 1724 return (nativeGetAction(mNativePtr) & ACTION_POINTER_INDEX_MASK) 1725 >> ACTION_POINTER_INDEX_SHIFT; 1726 } 1727 1728 /** 1729 * Returns true if this motion event is a touch event. 1730 * <p> 1731 * Specifically excludes pointer events with action {@link #ACTION_HOVER_MOVE}, 1732 * {@link #ACTION_HOVER_ENTER}, {@link #ACTION_HOVER_EXIT}, or {@link #ACTION_SCROLL} 1733 * because they are not actually touch events (the pointer is not down). 1734 * </p> 1735 * @return True if this motion event is a touch event. 1736 * @hide 1737 */ 1738 public final boolean isTouchEvent() { 1739 return nativeIsTouchEvent(mNativePtr); 1740 } 1741 1742 /** 1743 * Gets the motion event flags. 1744 * 1745 * @see #FLAG_WINDOW_IS_OBSCURED 1746 */ 1747 public final int getFlags() { 1748 return nativeGetFlags(mNativePtr); 1749 } 1750 1751 /** @hide */ 1752 @Override 1753 public final boolean isTainted() { 1754 final int flags = getFlags(); 1755 return (flags & FLAG_TAINTED) != 0; 1756 } 1757 1758 /** @hide */ 1759 @Override 1760 public final void setTainted(boolean tainted) { 1761 final int flags = getFlags(); 1762 nativeSetFlags(mNativePtr, tainted ? flags | FLAG_TAINTED : flags & ~FLAG_TAINTED); 1763 } 1764 1765 /** 1766 * Returns the time (in ms) when the user originally pressed down to start 1767 * a stream of position events. 1768 */ 1769 public final long getDownTime() { 1770 return nativeGetDownTimeNanos(mNativePtr) / NS_PER_MS; 1771 } 1772 1773 /** 1774 * Sets the time (in ms) when the user originally pressed down to start 1775 * a stream of position events. 1776 * 1777 * @hide 1778 */ 1779 public final void setDownTime(long downTime) { 1780 nativeSetDownTimeNanos(mNativePtr, downTime * NS_PER_MS); 1781 } 1782 1783 /** 1784 * Returns the time (in ms) when this specific event was generated. 1785 */ 1786 public final long getEventTime() { 1787 return nativeGetEventTimeNanos(mNativePtr, HISTORY_CURRENT) / NS_PER_MS; 1788 } 1789 1790 /** 1791 * Returns the time (in ns) when this specific event was generated. 1792 * The value is in nanosecond precision but it may not have nanosecond accuracy. 1793 * 1794 * @hide 1795 */ 1796 public final long getEventTimeNano() { 1797 return nativeGetEventTimeNanos(mNativePtr, HISTORY_CURRENT); 1798 } 1799 1800 /** 1801 * {@link #getX(int)} for the first pointer index (may be an 1802 * arbitrary pointer identifier). 1803 * 1804 * @see #AXIS_X 1805 */ 1806 public final float getX() { 1807 return nativeGetAxisValue(mNativePtr, AXIS_X, 0, HISTORY_CURRENT); 1808 } 1809 1810 /** 1811 * {@link #getY(int)} for the first pointer index (may be an 1812 * arbitrary pointer identifier). 1813 * 1814 * @see #AXIS_Y 1815 */ 1816 public final float getY() { 1817 return nativeGetAxisValue(mNativePtr, AXIS_Y, 0, HISTORY_CURRENT); 1818 } 1819 1820 /** 1821 * {@link #getPressure(int)} for the first pointer index (may be an 1822 * arbitrary pointer identifier). 1823 * 1824 * @see #AXIS_PRESSURE 1825 */ 1826 public final float getPressure() { 1827 return nativeGetAxisValue(mNativePtr, AXIS_PRESSURE, 0, HISTORY_CURRENT); 1828 } 1829 1830 /** 1831 * {@link #getSize(int)} for the first pointer index (may be an 1832 * arbitrary pointer identifier). 1833 * 1834 * @see #AXIS_SIZE 1835 */ 1836 public final float getSize() { 1837 return nativeGetAxisValue(mNativePtr, AXIS_SIZE, 0, HISTORY_CURRENT); 1838 } 1839 1840 /** 1841 * {@link #getTouchMajor(int)} for the first pointer index (may be an 1842 * arbitrary pointer identifier). 1843 * 1844 * @see #AXIS_TOUCH_MAJOR 1845 */ 1846 public final float getTouchMajor() { 1847 return nativeGetAxisValue(mNativePtr, AXIS_TOUCH_MAJOR, 0, HISTORY_CURRENT); 1848 } 1849 1850 /** 1851 * {@link #getTouchMinor(int)} for the first pointer index (may be an 1852 * arbitrary pointer identifier). 1853 * 1854 * @see #AXIS_TOUCH_MINOR 1855 */ 1856 public final float getTouchMinor() { 1857 return nativeGetAxisValue(mNativePtr, AXIS_TOUCH_MINOR, 0, HISTORY_CURRENT); 1858 } 1859 1860 /** 1861 * {@link #getToolMajor(int)} for the first pointer index (may be an 1862 * arbitrary pointer identifier). 1863 * 1864 * @see #AXIS_TOOL_MAJOR 1865 */ 1866 public final float getToolMajor() { 1867 return nativeGetAxisValue(mNativePtr, AXIS_TOOL_MAJOR, 0, HISTORY_CURRENT); 1868 } 1869 1870 /** 1871 * {@link #getToolMinor(int)} for the first pointer index (may be an 1872 * arbitrary pointer identifier). 1873 * 1874 * @see #AXIS_TOOL_MINOR 1875 */ 1876 public final float getToolMinor() { 1877 return nativeGetAxisValue(mNativePtr, AXIS_TOOL_MINOR, 0, HISTORY_CURRENT); 1878 } 1879 1880 /** 1881 * {@link #getOrientation(int)} for the first pointer index (may be an 1882 * arbitrary pointer identifier). 1883 * 1884 * @see #AXIS_ORIENTATION 1885 */ 1886 public final float getOrientation() { 1887 return nativeGetAxisValue(mNativePtr, AXIS_ORIENTATION, 0, HISTORY_CURRENT); 1888 } 1889 1890 /** 1891 * {@link #getAxisValue(int)} for the first pointer index (may be an 1892 * arbitrary pointer identifier). 1893 * 1894 * @param axis The axis identifier for the axis value to retrieve. 1895 * 1896 * @see #AXIS_X 1897 * @see #AXIS_Y 1898 */ 1899 public final float getAxisValue(int axis) { 1900 return nativeGetAxisValue(mNativePtr, axis, 0, HISTORY_CURRENT); 1901 } 1902 1903 /** 1904 * The number of pointers of data contained in this event. Always 1905 * >= 1. 1906 */ 1907 public final int getPointerCount() { 1908 return nativeGetPointerCount(mNativePtr); 1909 } 1910 1911 /** 1912 * Return the pointer identifier associated with a particular pointer 1913 * data index is this event. The identifier tells you the actual pointer 1914 * number associated with the data, accounting for individual pointers 1915 * going up and down since the start of the current gesture. 1916 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 1917 * (the first pointer that is down) to {@link #getPointerCount()}-1. 1918 */ 1919 public final int getPointerId(int pointerIndex) { 1920 return nativeGetPointerId(mNativePtr, pointerIndex); 1921 } 1922 1923 /** 1924 * Gets the tool type of a pointer for the given pointer index. 1925 * The tool type indicates the type of tool used to make contact such 1926 * as a finger or stylus, if known. 1927 * 1928 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 1929 * (the first pointer that is down) to {@link #getPointerCount()}-1. 1930 * @return The tool type of the pointer. 1931 * 1932 * @see #TOOL_TYPE_UNKNOWN 1933 * @see #TOOL_TYPE_FINGER 1934 * @see #TOOL_TYPE_STYLUS 1935 * @see #TOOL_TYPE_MOUSE 1936 * @see #TOOL_TYPE_INDIRECT_FINGER 1937 * @see #TOOL_TYPE_INDIRECT_STYLUS 1938 */ 1939 public final int getToolType(int pointerIndex) { 1940 return nativeGetToolType(mNativePtr, pointerIndex); 1941 } 1942 1943 /** 1944 * Given a pointer identifier, find the index of its data in the event. 1945 * 1946 * @param pointerId The identifier of the pointer to be found. 1947 * @return Returns either the index of the pointer (for use with 1948 * {@link #getX(int)} et al.), or -1 if there is no data available for 1949 * that pointer identifier. 1950 */ 1951 public final int findPointerIndex(int pointerId) { 1952 return nativeFindPointerIndex(mNativePtr, pointerId); 1953 } 1954 1955 /** 1956 * Returns the X coordinate of this event for the given pointer 1957 * <em>index</em> (use {@link #getPointerId(int)} to find the pointer 1958 * identifier for this index). 1959 * Whole numbers are pixels; the 1960 * value may have a fraction for input devices that are sub-pixel precise. 1961 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 1962 * (the first pointer that is down) to {@link #getPointerCount()}-1. 1963 * 1964 * @see #AXIS_X 1965 */ 1966 public final float getX(int pointerIndex) { 1967 return nativeGetAxisValue(mNativePtr, AXIS_X, pointerIndex, HISTORY_CURRENT); 1968 } 1969 1970 /** 1971 * Returns the Y coordinate of this event for the given pointer 1972 * <em>index</em> (use {@link #getPointerId(int)} to find the pointer 1973 * identifier for this index). 1974 * Whole numbers are pixels; the 1975 * value may have a fraction for input devices that are sub-pixel precise. 1976 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 1977 * (the first pointer that is down) to {@link #getPointerCount()}-1. 1978 * 1979 * @see #AXIS_Y 1980 */ 1981 public final float getY(int pointerIndex) { 1982 return nativeGetAxisValue(mNativePtr, AXIS_Y, pointerIndex, HISTORY_CURRENT); 1983 } 1984 1985 /** 1986 * Returns the current pressure of this event for the given pointer 1987 * <em>index</em> (use {@link #getPointerId(int)} to find the pointer 1988 * identifier for this index). 1989 * The pressure generally 1990 * ranges from 0 (no pressure at all) to 1 (normal pressure), however 1991 * values higher than 1 may be generated depending on the calibration of 1992 * the input device. 1993 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 1994 * (the first pointer that is down) to {@link #getPointerCount()}-1. 1995 * 1996 * @see #AXIS_PRESSURE 1997 */ 1998 public final float getPressure(int pointerIndex) { 1999 return nativeGetAxisValue(mNativePtr, AXIS_PRESSURE, pointerIndex, HISTORY_CURRENT); 2000 } 2001 2002 /** 2003 * Returns a scaled value of the approximate size for the given pointer 2004 * <em>index</em> (use {@link #getPointerId(int)} to find the pointer 2005 * identifier for this index). 2006 * This represents some approximation of the area of the screen being 2007 * pressed; the actual value in pixels corresponding to the 2008 * touch is normalized with the device specific range of values 2009 * and scaled to a value between 0 and 1. The value of size can be used to 2010 * determine fat touch events. 2011 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 2012 * (the first pointer that is down) to {@link #getPointerCount()}-1. 2013 * 2014 * @see #AXIS_SIZE 2015 */ 2016 public final float getSize(int pointerIndex) { 2017 return nativeGetAxisValue(mNativePtr, AXIS_SIZE, pointerIndex, HISTORY_CURRENT); 2018 } 2019 2020 /** 2021 * Returns the length of the major axis of an ellipse that describes the touch 2022 * area at the point of contact for the given pointer 2023 * <em>index</em> (use {@link #getPointerId(int)} to find the pointer 2024 * identifier for this index). 2025 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 2026 * (the first pointer that is down) to {@link #getPointerCount()}-1. 2027 * 2028 * @see #AXIS_TOUCH_MAJOR 2029 */ 2030 public final float getTouchMajor(int pointerIndex) { 2031 return nativeGetAxisValue(mNativePtr, AXIS_TOUCH_MAJOR, pointerIndex, HISTORY_CURRENT); 2032 } 2033 2034 /** 2035 * Returns the length of the minor axis of an ellipse that describes the touch 2036 * area at the point of contact for the given pointer 2037 * <em>index</em> (use {@link #getPointerId(int)} to find the pointer 2038 * identifier for this index). 2039 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 2040 * (the first pointer that is down) to {@link #getPointerCount()}-1. 2041 * 2042 * @see #AXIS_TOUCH_MINOR 2043 */ 2044 public final float getTouchMinor(int pointerIndex) { 2045 return nativeGetAxisValue(mNativePtr, AXIS_TOUCH_MINOR, pointerIndex, HISTORY_CURRENT); 2046 } 2047 2048 /** 2049 * Returns the length of the major axis of an ellipse that describes the size of 2050 * the approaching tool for the given pointer 2051 * <em>index</em> (use {@link #getPointerId(int)} to find the pointer 2052 * identifier for this index). 2053 * The tool area represents the estimated size of the finger or pen that is 2054 * touching the device independent of its actual touch area at the point of contact. 2055 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 2056 * (the first pointer that is down) to {@link #getPointerCount()}-1. 2057 * 2058 * @see #AXIS_TOOL_MAJOR 2059 */ 2060 public final float getToolMajor(int pointerIndex) { 2061 return nativeGetAxisValue(mNativePtr, AXIS_TOOL_MAJOR, pointerIndex, HISTORY_CURRENT); 2062 } 2063 2064 /** 2065 * Returns the length of the minor axis of an ellipse that describes the size of 2066 * the approaching tool for the given pointer 2067 * <em>index</em> (use {@link #getPointerId(int)} to find the pointer 2068 * identifier for this index). 2069 * The tool area represents the estimated size of the finger or pen that is 2070 * touching the device independent of its actual touch area at the point of contact. 2071 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 2072 * (the first pointer that is down) to {@link #getPointerCount()}-1. 2073 * 2074 * @see #AXIS_TOOL_MINOR 2075 */ 2076 public final float getToolMinor(int pointerIndex) { 2077 return nativeGetAxisValue(mNativePtr, AXIS_TOOL_MINOR, pointerIndex, HISTORY_CURRENT); 2078 } 2079 2080 /** 2081 * Returns the orientation of the touch area and tool area in radians clockwise from vertical 2082 * for the given pointer <em>index</em> (use {@link #getPointerId(int)} to find the pointer 2083 * identifier for this index). 2084 * An angle of 0 radians indicates that the major axis of contact is oriented 2085 * upwards, is perfectly circular or is of unknown orientation. A positive angle 2086 * indicates that the major axis of contact is oriented to the right. A negative angle 2087 * indicates that the major axis of contact is oriented to the left. 2088 * The full range is from -PI/2 radians (finger pointing fully left) to PI/2 radians 2089 * (finger pointing fully right). 2090 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 2091 * (the first pointer that is down) to {@link #getPointerCount()}-1. 2092 * 2093 * @see #AXIS_ORIENTATION 2094 */ 2095 public final float getOrientation(int pointerIndex) { 2096 return nativeGetAxisValue(mNativePtr, AXIS_ORIENTATION, pointerIndex, HISTORY_CURRENT); 2097 } 2098 2099 /** 2100 * Returns the value of the requested axis for the given pointer <em>index</em> 2101 * (use {@link #getPointerId(int)} to find the pointer identifier for this index). 2102 * 2103 * @param axis The axis identifier for the axis value to retrieve. 2104 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 2105 * (the first pointer that is down) to {@link #getPointerCount()}-1. 2106 * @return The value of the axis, or 0 if the axis is not available. 2107 * 2108 * @see #AXIS_X 2109 * @see #AXIS_Y 2110 */ 2111 public final float getAxisValue(int axis, int pointerIndex) { 2112 return nativeGetAxisValue(mNativePtr, axis, pointerIndex, HISTORY_CURRENT); 2113 } 2114 2115 /** 2116 * Populates a {@link PointerCoords} object with pointer coordinate data for 2117 * the specified pointer index. 2118 * 2119 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 2120 * (the first pointer that is down) to {@link #getPointerCount()}-1. 2121 * @param outPointerCoords The pointer coordinate object to populate. 2122 * 2123 * @see PointerCoords 2124 */ 2125 public final void getPointerCoords(int pointerIndex, PointerCoords outPointerCoords) { 2126 nativeGetPointerCoords(mNativePtr, pointerIndex, HISTORY_CURRENT, outPointerCoords); 2127 } 2128 2129 /** 2130 * Populates a {@link PointerProperties} object with pointer properties for 2131 * the specified pointer index. 2132 * 2133 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 2134 * (the first pointer that is down) to {@link #getPointerCount()}-1. 2135 * @param outPointerProperties The pointer properties object to populate. 2136 * 2137 * @see PointerProperties 2138 */ 2139 public final void getPointerProperties(int pointerIndex, 2140 PointerProperties outPointerProperties) { 2141 nativeGetPointerProperties(mNativePtr, pointerIndex, outPointerProperties); 2142 } 2143 2144 /** 2145 * Returns the state of any meta / modifier keys that were in effect when 2146 * the event was generated. This is the same values as those 2147 * returned by {@link KeyEvent#getMetaState() KeyEvent.getMetaState}. 2148 * 2149 * @return an integer in which each bit set to 1 represents a pressed 2150 * meta key 2151 * 2152 * @see KeyEvent#getMetaState() 2153 */ 2154 public final int getMetaState() { 2155 return nativeGetMetaState(mNativePtr); 2156 } 2157 2158 /** 2159 * Gets the state of all buttons that are pressed such as a mouse or stylus button. 2160 * 2161 * @return The button state. 2162 * 2163 * @see #BUTTON_PRIMARY 2164 * @see #BUTTON_SECONDARY 2165 * @see #BUTTON_TERTIARY 2166 * @see #BUTTON_FORWARD 2167 * @see #BUTTON_BACK 2168 */ 2169 public final int getButtonState() { 2170 return nativeGetButtonState(mNativePtr); 2171 } 2172 2173 /** 2174 * Returns the original raw X coordinate of this event. For touch 2175 * events on the screen, this is the original location of the event 2176 * on the screen, before it had been adjusted for the containing window 2177 * and views. 2178 * 2179 * @see getX() 2180 * @see #AXIS_X 2181 */ 2182 public final float getRawX() { 2183 return nativeGetRawAxisValue(mNativePtr, AXIS_X, 0, HISTORY_CURRENT); 2184 } 2185 2186 /** 2187 * Returns the original raw Y coordinate of this event. For touch 2188 * events on the screen, this is the original location of the event 2189 * on the screen, before it had been adjusted for the containing window 2190 * and views. 2191 * 2192 * @see getY() 2193 * @see #AXIS_Y 2194 */ 2195 public final float getRawY() { 2196 return nativeGetRawAxisValue(mNativePtr, AXIS_Y, 0, HISTORY_CURRENT); 2197 } 2198 2199 /** 2200 * Return the precision of the X coordinates being reported. You can 2201 * multiply this number with {@link #getX} to find the actual hardware 2202 * value of the X coordinate. 2203 * @return Returns the precision of X coordinates being reported. 2204 * 2205 * @see #AXIS_X 2206 */ 2207 public final float getXPrecision() { 2208 return nativeGetXPrecision(mNativePtr); 2209 } 2210 2211 /** 2212 * Return the precision of the Y coordinates being reported. You can 2213 * multiply this number with {@link #getY} to find the actual hardware 2214 * value of the Y coordinate. 2215 * @return Returns the precision of Y coordinates being reported. 2216 * 2217 * @see #AXIS_Y 2218 */ 2219 public final float getYPrecision() { 2220 return nativeGetYPrecision(mNativePtr); 2221 } 2222 2223 /** 2224 * Returns the number of historical points in this event. These are 2225 * movements that have occurred between this event and the previous event. 2226 * This only applies to ACTION_MOVE events -- all other actions will have 2227 * a size of 0. 2228 * 2229 * @return Returns the number of historical points in the event. 2230 */ 2231 public final int getHistorySize() { 2232 return nativeGetHistorySize(mNativePtr); 2233 } 2234 2235 /** 2236 * Returns the time that a historical movement occurred between this event 2237 * and the previous event. Only applies to ACTION_MOVE events. 2238 * 2239 * @param pos Which historical value to return; must be less than 2240 * {@link #getHistorySize} 2241 * 2242 * @see #getHistorySize 2243 * @see #getEventTime 2244 */ 2245 public final long getHistoricalEventTime(int pos) { 2246 return nativeGetEventTimeNanos(mNativePtr, pos) / NS_PER_MS; 2247 } 2248 2249 /** 2250 * {@link #getHistoricalX(int, int)} for the first pointer index (may be an 2251 * arbitrary pointer identifier). 2252 * 2253 * @param pos Which historical value to return; must be less than 2254 * {@link #getHistorySize} 2255 * 2256 * @see #getHistorySize 2257 * @see #getX() 2258 * @see #AXIS_X 2259 */ 2260 public final float getHistoricalX(int pos) { 2261 return nativeGetAxisValue(mNativePtr, AXIS_X, 0, pos); 2262 } 2263 2264 /** 2265 * {@link #getHistoricalY(int, int)} for the first pointer index (may be an 2266 * arbitrary pointer identifier). 2267 * 2268 * @param pos Which historical value to return; must be less than 2269 * {@link #getHistorySize} 2270 * 2271 * @see #getHistorySize 2272 * @see #getY() 2273 * @see #AXIS_Y 2274 */ 2275 public final float getHistoricalY(int pos) { 2276 return nativeGetAxisValue(mNativePtr, AXIS_Y, 0, pos); 2277 } 2278 2279 /** 2280 * {@link #getHistoricalPressure(int, int)} for the first pointer index (may be an 2281 * arbitrary pointer identifier). 2282 * 2283 * @param pos Which historical value to return; must be less than 2284 * {@link #getHistorySize} 2285 * 2286 * @see #getHistorySize 2287 * @see #getPressure() 2288 * @see #AXIS_PRESSURE 2289 */ 2290 public final float getHistoricalPressure(int pos) { 2291 return nativeGetAxisValue(mNativePtr, AXIS_PRESSURE, 0, pos); 2292 } 2293 2294 /** 2295 * {@link #getHistoricalSize(int, int)} for the first pointer index (may be an 2296 * arbitrary pointer identifier). 2297 * 2298 * @param pos Which historical value to return; must be less than 2299 * {@link #getHistorySize} 2300 * 2301 * @see #getHistorySize 2302 * @see #getSize() 2303 * @see #AXIS_SIZE 2304 */ 2305 public final float getHistoricalSize(int pos) { 2306 return nativeGetAxisValue(mNativePtr, AXIS_SIZE, 0, pos); 2307 } 2308 2309 /** 2310 * {@link #getHistoricalTouchMajor(int, int)} for the first pointer index (may be an 2311 * arbitrary pointer identifier). 2312 * 2313 * @param pos Which historical value to return; must be less than 2314 * {@link #getHistorySize} 2315 * 2316 * @see #getHistorySize 2317 * @see #getTouchMajor() 2318 * @see #AXIS_TOUCH_MAJOR 2319 */ 2320 public final float getHistoricalTouchMajor(int pos) { 2321 return nativeGetAxisValue(mNativePtr, AXIS_TOUCH_MAJOR, 0, pos); 2322 } 2323 2324 /** 2325 * {@link #getHistoricalTouchMinor(int, int)} for the first pointer index (may be an 2326 * arbitrary pointer identifier). 2327 * 2328 * @param pos Which historical value to return; must be less than 2329 * {@link #getHistorySize} 2330 * 2331 * @see #getHistorySize 2332 * @see #getTouchMinor() 2333 * @see #AXIS_TOUCH_MINOR 2334 */ 2335 public final float getHistoricalTouchMinor(int pos) { 2336 return nativeGetAxisValue(mNativePtr, AXIS_TOUCH_MINOR, 0, pos); 2337 } 2338 2339 /** 2340 * {@link #getHistoricalToolMajor(int, int)} for the first pointer index (may be an 2341 * arbitrary pointer identifier). 2342 * 2343 * @param pos Which historical value to return; must be less than 2344 * {@link #getHistorySize} 2345 * 2346 * @see #getHistorySize 2347 * @see #getToolMajor() 2348 * @see #AXIS_TOOL_MAJOR 2349 */ 2350 public final float getHistoricalToolMajor(int pos) { 2351 return nativeGetAxisValue(mNativePtr, AXIS_TOOL_MAJOR, 0, pos); 2352 } 2353 2354 /** 2355 * {@link #getHistoricalToolMinor(int, int)} for the first pointer index (may be an 2356 * arbitrary pointer identifier). 2357 * 2358 * @param pos Which historical value to return; must be less than 2359 * {@link #getHistorySize} 2360 * 2361 * @see #getHistorySize 2362 * @see #getToolMinor() 2363 * @see #AXIS_TOOL_MINOR 2364 */ 2365 public final float getHistoricalToolMinor(int pos) { 2366 return nativeGetAxisValue(mNativePtr, AXIS_TOOL_MINOR, 0, pos); 2367 } 2368 2369 /** 2370 * {@link #getHistoricalOrientation(int, int)} for the first pointer index (may be an 2371 * arbitrary pointer identifier). 2372 * 2373 * @param pos Which historical value to return; must be less than 2374 * {@link #getHistorySize} 2375 * 2376 * @see #getHistorySize 2377 * @see #getOrientation() 2378 * @see #AXIS_ORIENTATION 2379 */ 2380 public final float getHistoricalOrientation(int pos) { 2381 return nativeGetAxisValue(mNativePtr, AXIS_ORIENTATION, 0, pos); 2382 } 2383 2384 /** 2385 * {@link #getHistoricalAxisValue(int, int, int)} for the first pointer index (may be an 2386 * arbitrary pointer identifier). 2387 * 2388 * @param axis The axis identifier for the axis value to retrieve. 2389 * @param pos Which historical value to return; must be less than 2390 * {@link #getHistorySize} 2391 * 2392 * @see #getHistorySize 2393 * @see #getAxisValue(int) 2394 * @see #AXIS_X 2395 * @see #AXIS_Y 2396 */ 2397 public final float getHistoricalAxisValue(int axis, int pos) { 2398 return nativeGetAxisValue(mNativePtr, axis, 0, pos); 2399 } 2400 2401 /** 2402 * Returns a historical X coordinate, as per {@link #getX(int)}, that 2403 * occurred between this event and the previous event for the given pointer. 2404 * Only applies to ACTION_MOVE events. 2405 * 2406 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 2407 * (the first pointer that is down) to {@link #getPointerCount()}-1. 2408 * @param pos Which historical value to return; must be less than 2409 * {@link #getHistorySize} 2410 * 2411 * @see #getHistorySize 2412 * @see #getX(int) 2413 * @see #AXIS_X 2414 */ 2415 public final float getHistoricalX(int pointerIndex, int pos) { 2416 return nativeGetAxisValue(mNativePtr, AXIS_X, pointerIndex, pos); 2417 } 2418 2419 /** 2420 * Returns a historical Y coordinate, as per {@link #getY(int)}, that 2421 * occurred between this event and the previous event for the given pointer. 2422 * Only applies to ACTION_MOVE events. 2423 * 2424 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 2425 * (the first pointer that is down) to {@link #getPointerCount()}-1. 2426 * @param pos Which historical value to return; must be less than 2427 * {@link #getHistorySize} 2428 * 2429 * @see #getHistorySize 2430 * @see #getY(int) 2431 * @see #AXIS_Y 2432 */ 2433 public final float getHistoricalY(int pointerIndex, int pos) { 2434 return nativeGetAxisValue(mNativePtr, AXIS_Y, pointerIndex, pos); 2435 } 2436 2437 /** 2438 * Returns a historical pressure coordinate, as per {@link #getPressure(int)}, 2439 * that occurred between this event and the previous event for the given 2440 * pointer. Only applies to ACTION_MOVE events. 2441 * 2442 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 2443 * (the first pointer that is down) to {@link #getPointerCount()}-1. 2444 * @param pos Which historical value to return; must be less than 2445 * {@link #getHistorySize} 2446 * 2447 * @see #getHistorySize 2448 * @see #getPressure(int) 2449 * @see #AXIS_PRESSURE 2450 */ 2451 public final float getHistoricalPressure(int pointerIndex, int pos) { 2452 return nativeGetAxisValue(mNativePtr, AXIS_PRESSURE, pointerIndex, pos); 2453 } 2454 2455 /** 2456 * Returns a historical size coordinate, as per {@link #getSize(int)}, that 2457 * occurred between this event and the previous event for the given pointer. 2458 * Only applies to ACTION_MOVE events. 2459 * 2460 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 2461 * (the first pointer that is down) to {@link #getPointerCount()}-1. 2462 * @param pos Which historical value to return; must be less than 2463 * {@link #getHistorySize} 2464 * 2465 * @see #getHistorySize 2466 * @see #getSize(int) 2467 * @see #AXIS_SIZE 2468 */ 2469 public final float getHistoricalSize(int pointerIndex, int pos) { 2470 return nativeGetAxisValue(mNativePtr, AXIS_SIZE, pointerIndex, pos); 2471 } 2472 2473 /** 2474 * Returns a historical touch major axis coordinate, as per {@link #getTouchMajor(int)}, that 2475 * occurred between this event and the previous event for the given pointer. 2476 * Only applies to ACTION_MOVE events. 2477 * 2478 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 2479 * (the first pointer that is down) to {@link #getPointerCount()}-1. 2480 * @param pos Which historical value to return; must be less than 2481 * {@link #getHistorySize} 2482 * 2483 * @see #getHistorySize 2484 * @see #getTouchMajor(int) 2485 * @see #AXIS_TOUCH_MAJOR 2486 */ 2487 public final float getHistoricalTouchMajor(int pointerIndex, int pos) { 2488 return nativeGetAxisValue(mNativePtr, AXIS_TOUCH_MAJOR, pointerIndex, pos); 2489 } 2490 2491 /** 2492 * Returns a historical touch minor axis coordinate, as per {@link #getTouchMinor(int)}, that 2493 * occurred between this event and the previous event for the given pointer. 2494 * Only applies to ACTION_MOVE events. 2495 * 2496 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 2497 * (the first pointer that is down) to {@link #getPointerCount()}-1. 2498 * @param pos Which historical value to return; must be less than 2499 * {@link #getHistorySize} 2500 * 2501 * @see #getHistorySize 2502 * @see #getTouchMinor(int) 2503 * @see #AXIS_TOUCH_MINOR 2504 */ 2505 public final float getHistoricalTouchMinor(int pointerIndex, int pos) { 2506 return nativeGetAxisValue(mNativePtr, AXIS_TOUCH_MINOR, pointerIndex, pos); 2507 } 2508 2509 /** 2510 * Returns a historical tool major axis coordinate, as per {@link #getToolMajor(int)}, that 2511 * occurred between this event and the previous event for the given pointer. 2512 * Only applies to ACTION_MOVE events. 2513 * 2514 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 2515 * (the first pointer that is down) to {@link #getPointerCount()}-1. 2516 * @param pos Which historical value to return; must be less than 2517 * {@link #getHistorySize} 2518 * 2519 * @see #getHistorySize 2520 * @see #getToolMajor(int) 2521 * @see #AXIS_TOOL_MAJOR 2522 */ 2523 public final float getHistoricalToolMajor(int pointerIndex, int pos) { 2524 return nativeGetAxisValue(mNativePtr, AXIS_TOOL_MAJOR, pointerIndex, pos); 2525 } 2526 2527 /** 2528 * Returns a historical tool minor axis coordinate, as per {@link #getToolMinor(int)}, that 2529 * occurred between this event and the previous event for the given pointer. 2530 * Only applies to ACTION_MOVE events. 2531 * 2532 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 2533 * (the first pointer that is down) to {@link #getPointerCount()}-1. 2534 * @param pos Which historical value to return; must be less than 2535 * {@link #getHistorySize} 2536 * 2537 * @see #getHistorySize 2538 * @see #getToolMinor(int) 2539 * @see #AXIS_TOOL_MINOR 2540 */ 2541 public final float getHistoricalToolMinor(int pointerIndex, int pos) { 2542 return nativeGetAxisValue(mNativePtr, AXIS_TOOL_MINOR, pointerIndex, pos); 2543 } 2544 2545 /** 2546 * Returns a historical orientation coordinate, as per {@link #getOrientation(int)}, that 2547 * occurred between this event and the previous event for the given pointer. 2548 * Only applies to ACTION_MOVE events. 2549 * 2550 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 2551 * (the first pointer that is down) to {@link #getPointerCount()}-1. 2552 * @param pos Which historical value to return; must be less than 2553 * {@link #getHistorySize} 2554 * 2555 * @see #getHistorySize 2556 * @see #getOrientation(int) 2557 * @see #AXIS_ORIENTATION 2558 */ 2559 public final float getHistoricalOrientation(int pointerIndex, int pos) { 2560 return nativeGetAxisValue(mNativePtr, AXIS_ORIENTATION, pointerIndex, pos); 2561 } 2562 2563 /** 2564 * Returns the historical value of the requested axis, as per {@link #getAxisValue(int, int)}, 2565 * occurred between this event and the previous event for the given pointer. 2566 * Only applies to ACTION_MOVE events. 2567 * 2568 * @param axis The axis identifier for the axis value to retrieve. 2569 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 2570 * (the first pointer that is down) to {@link #getPointerCount()}-1. 2571 * @param pos Which historical value to return; must be less than 2572 * {@link #getHistorySize} 2573 * @return The value of the axis, or 0 if the axis is not available. 2574 * 2575 * @see #AXIS_X 2576 * @see #AXIS_Y 2577 */ 2578 public final float getHistoricalAxisValue(int axis, int pointerIndex, int pos) { 2579 return nativeGetAxisValue(mNativePtr, axis, pointerIndex, pos); 2580 } 2581 2582 /** 2583 * Populates a {@link PointerCoords} object with historical pointer coordinate data, 2584 * as per {@link #getPointerCoords}, that occurred between this event and the previous 2585 * event for the given pointer. 2586 * Only applies to ACTION_MOVE events. 2587 * 2588 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 2589 * (the first pointer that is down) to {@link #getPointerCount()}-1. 2590 * @param pos Which historical value to return; must be less than 2591 * {@link #getHistorySize} 2592 * @param outPointerCoords The pointer coordinate object to populate. 2593 * 2594 * @see #getHistorySize 2595 * @see #getPointerCoords 2596 * @see PointerCoords 2597 */ 2598 public final void getHistoricalPointerCoords(int pointerIndex, int pos, 2599 PointerCoords outPointerCoords) { 2600 nativeGetPointerCoords(mNativePtr, pointerIndex, pos, outPointerCoords); 2601 } 2602 2603 /** 2604 * Returns a bitfield indicating which edges, if any, were touched by this 2605 * MotionEvent. For touch events, clients can use this to determine if the 2606 * user's finger was touching the edge of the display. 2607 * 2608 * This property is only set for {@link #ACTION_DOWN} events. 2609 * 2610 * @see #EDGE_LEFT 2611 * @see #EDGE_TOP 2612 * @see #EDGE_RIGHT 2613 * @see #EDGE_BOTTOM 2614 */ 2615 public final int getEdgeFlags() { 2616 return nativeGetEdgeFlags(mNativePtr); 2617 } 2618 2619 /** 2620 * Sets the bitfield indicating which edges, if any, were touched by this 2621 * MotionEvent. 2622 * 2623 * @see #getEdgeFlags() 2624 */ 2625 public final void setEdgeFlags(int flags) { 2626 nativeSetEdgeFlags(mNativePtr, flags); 2627 } 2628 2629 /** 2630 * Sets this event's action. 2631 */ 2632 public final void setAction(int action) { 2633 nativeSetAction(mNativePtr, action); 2634 } 2635 2636 /** 2637 * Adjust this event's location. 2638 * @param deltaX Amount to add to the current X coordinate of the event. 2639 * @param deltaY Amount to add to the current Y coordinate of the event. 2640 */ 2641 public final void offsetLocation(float deltaX, float deltaY) { 2642 if (deltaX != 0.0f || deltaY != 0.0f) { 2643 nativeOffsetLocation(mNativePtr, deltaX, deltaY); 2644 } 2645 } 2646 2647 /** 2648 * Set this event's location. Applies {@link #offsetLocation} with a 2649 * delta from the current location to the given new location. 2650 * 2651 * @param x New absolute X location. 2652 * @param y New absolute Y location. 2653 */ 2654 public final void setLocation(float x, float y) { 2655 float oldX = getX(); 2656 float oldY = getY(); 2657 offsetLocation(x - oldX, y - oldY); 2658 } 2659 2660 /** 2661 * Applies a transformation matrix to all of the points in the event. 2662 * 2663 * @param matrix The transformation matrix to apply. 2664 */ 2665 public final void transform(Matrix matrix) { 2666 if (matrix == null) { 2667 throw new IllegalArgumentException("matrix must not be null"); 2668 } 2669 2670 nativeTransform(mNativePtr, matrix); 2671 } 2672 2673 /** 2674 * Add a new movement to the batch of movements in this event. The event's 2675 * current location, position and size is updated to the new values. 2676 * The current values in the event are added to a list of historical values. 2677 * 2678 * Only applies to {@link #ACTION_MOVE} or {@link #ACTION_HOVER_MOVE} events. 2679 * 2680 * @param eventTime The time stamp (in ms) for this data. 2681 * @param x The new X position. 2682 * @param y The new Y position. 2683 * @param pressure The new pressure. 2684 * @param size The new size. 2685 * @param metaState Meta key state. 2686 */ 2687 public final void addBatch(long eventTime, float x, float y, 2688 float pressure, float size, int metaState) { 2689 synchronized (gSharedTempLock) { 2690 ensureSharedTempPointerCapacity(1); 2691 final PointerCoords[] pc = gSharedTempPointerCoords; 2692 pc[0].clear(); 2693 pc[0].x = x; 2694 pc[0].y = y; 2695 pc[0].pressure = pressure; 2696 pc[0].size = size; 2697 2698 nativeAddBatch(mNativePtr, eventTime * NS_PER_MS, pc, metaState); 2699 } 2700 } 2701 2702 /** 2703 * Add a new movement to the batch of movements in this event. The event's 2704 * current location, position and size is updated to the new values. 2705 * The current values in the event are added to a list of historical values. 2706 * 2707 * Only applies to {@link #ACTION_MOVE} or {@link #ACTION_HOVER_MOVE} events. 2708 * 2709 * @param eventTime The time stamp (in ms) for this data. 2710 * @param pointerCoords The new pointer coordinates. 2711 * @param metaState Meta key state. 2712 */ 2713 public final void addBatch(long eventTime, PointerCoords[] pointerCoords, int metaState) { 2714 nativeAddBatch(mNativePtr, eventTime * NS_PER_MS, pointerCoords, metaState); 2715 } 2716 2717 /** 2718 * Returns true if all points in the motion event are completely within the specified bounds. 2719 * @hide 2720 */ 2721 public final boolean isWithinBoundsNoHistory(float left, float top, 2722 float right, float bottom) { 2723 final int pointerCount = nativeGetPointerCount(mNativePtr); 2724 for (int i = 0; i < pointerCount; i++) { 2725 final float x = nativeGetAxisValue(mNativePtr, AXIS_X, i, HISTORY_CURRENT); 2726 final float y = nativeGetAxisValue(mNativePtr, AXIS_Y, i, HISTORY_CURRENT); 2727 if (x < left || x > right || y < top || y > bottom) { 2728 return false; 2729 } 2730 } 2731 return true; 2732 } 2733 2734 private static final float clamp(float value, float low, float high) { 2735 if (value < low) { 2736 return low; 2737 } else if (value > high) { 2738 return high; 2739 } 2740 return value; 2741 } 2742 2743 /** 2744 * Returns a new motion events whose points have been clamped to the specified bounds. 2745 * @hide 2746 */ 2747 public final MotionEvent clampNoHistory(float left, float top, float right, float bottom) { 2748 MotionEvent ev = obtain(); 2749 synchronized (gSharedTempLock) { 2750 final int pointerCount = nativeGetPointerCount(mNativePtr); 2751 2752 ensureSharedTempPointerCapacity(pointerCount); 2753 final PointerProperties[] pp = gSharedTempPointerProperties; 2754 final PointerCoords[] pc = gSharedTempPointerCoords; 2755 2756 for (int i = 0; i < pointerCount; i++) { 2757 nativeGetPointerProperties(mNativePtr, i, pp[i]); 2758 nativeGetPointerCoords(mNativePtr, i, HISTORY_CURRENT, pc[i]); 2759 pc[i].x = clamp(pc[i].x, left, right); 2760 pc[i].y = clamp(pc[i].y, top, bottom); 2761 } 2762 ev.mNativePtr = nativeInitialize(ev.mNativePtr, 2763 nativeGetDeviceId(mNativePtr), nativeGetSource(mNativePtr), 2764 nativeGetAction(mNativePtr), nativeGetFlags(mNativePtr), 2765 nativeGetEdgeFlags(mNativePtr), nativeGetMetaState(mNativePtr), 2766 nativeGetButtonState(mNativePtr), 2767 nativeGetXOffset(mNativePtr), nativeGetYOffset(mNativePtr), 2768 nativeGetXPrecision(mNativePtr), nativeGetYPrecision(mNativePtr), 2769 nativeGetDownTimeNanos(mNativePtr), 2770 nativeGetEventTimeNanos(mNativePtr, HISTORY_CURRENT), 2771 pointerCount, pp, pc); 2772 return ev; 2773 } 2774 } 2775 2776 /** 2777 * Gets an integer where each pointer id present in the event is marked as a bit. 2778 * @hide 2779 */ 2780 public final int getPointerIdBits() { 2781 int idBits = 0; 2782 final int pointerCount = nativeGetPointerCount(mNativePtr); 2783 for (int i = 0; i < pointerCount; i++) { 2784 idBits |= 1 << nativeGetPointerId(mNativePtr, i); 2785 } 2786 return idBits; 2787 } 2788 2789 /** 2790 * Splits a motion event such that it includes only a subset of pointer ids. 2791 * @hide 2792 */ 2793 public final MotionEvent split(int idBits) { 2794 MotionEvent ev = obtain(); 2795 synchronized (gSharedTempLock) { 2796 final int oldPointerCount = nativeGetPointerCount(mNativePtr); 2797 ensureSharedTempPointerCapacity(oldPointerCount); 2798 final PointerProperties[] pp = gSharedTempPointerProperties; 2799 final PointerCoords[] pc = gSharedTempPointerCoords; 2800 final int[] map = gSharedTempPointerIndexMap; 2801 2802 final int oldAction = nativeGetAction(mNativePtr); 2803 final int oldActionMasked = oldAction & ACTION_MASK; 2804 final int oldActionPointerIndex = (oldAction & ACTION_POINTER_INDEX_MASK) 2805 >> ACTION_POINTER_INDEX_SHIFT; 2806 int newActionPointerIndex = -1; 2807 int newPointerCount = 0; 2808 int newIdBits = 0; 2809 for (int i = 0; i < oldPointerCount; i++) { 2810 nativeGetPointerProperties(mNativePtr, i, pp[newPointerCount]); 2811 final int idBit = 1 << pp[newPointerCount].id; 2812 if ((idBit & idBits) != 0) { 2813 if (i == oldActionPointerIndex) { 2814 newActionPointerIndex = newPointerCount; 2815 } 2816 map[newPointerCount] = i; 2817 newPointerCount += 1; 2818 newIdBits |= idBit; 2819 } 2820 } 2821 2822 if (newPointerCount == 0) { 2823 throw new IllegalArgumentException("idBits did not match any ids in the event"); 2824 } 2825 2826 final int newAction; 2827 if (oldActionMasked == ACTION_POINTER_DOWN || oldActionMasked == ACTION_POINTER_UP) { 2828 if (newActionPointerIndex < 0) { 2829 // An unrelated pointer changed. 2830 newAction = ACTION_MOVE; 2831 } else if (newPointerCount == 1) { 2832 // The first/last pointer went down/up. 2833 newAction = oldActionMasked == ACTION_POINTER_DOWN 2834 ? ACTION_DOWN : ACTION_UP; 2835 } else { 2836 // A secondary pointer went down/up. 2837 newAction = oldActionMasked 2838 | (newActionPointerIndex << ACTION_POINTER_INDEX_SHIFT); 2839 } 2840 } else { 2841 // Simple up/down/cancel/move or other motion action. 2842 newAction = oldAction; 2843 } 2844 2845 final int historySize = nativeGetHistorySize(mNativePtr); 2846 for (int h = 0; h <= historySize; h++) { 2847 final int historyPos = h == historySize ? HISTORY_CURRENT : h; 2848 2849 for (int i = 0; i < newPointerCount; i++) { 2850 nativeGetPointerCoords(mNativePtr, map[i], historyPos, pc[i]); 2851 } 2852 2853 final long eventTimeNanos = nativeGetEventTimeNanos(mNativePtr, historyPos); 2854 if (h == 0) { 2855 ev.mNativePtr = nativeInitialize(ev.mNativePtr, 2856 nativeGetDeviceId(mNativePtr), nativeGetSource(mNativePtr), 2857 newAction, nativeGetFlags(mNativePtr), 2858 nativeGetEdgeFlags(mNativePtr), nativeGetMetaState(mNativePtr), 2859 nativeGetButtonState(mNativePtr), 2860 nativeGetXOffset(mNativePtr), nativeGetYOffset(mNativePtr), 2861 nativeGetXPrecision(mNativePtr), nativeGetYPrecision(mNativePtr), 2862 nativeGetDownTimeNanos(mNativePtr), eventTimeNanos, 2863 newPointerCount, pp, pc); 2864 } else { 2865 nativeAddBatch(ev.mNativePtr, eventTimeNanos, pc, 0); 2866 } 2867 } 2868 return ev; 2869 } 2870 } 2871 2872 @Override 2873 public String toString() { 2874 StringBuilder msg = new StringBuilder(); 2875 msg.append("MotionEvent { action=").append(actionToString(getAction())); 2876 2877 final int pointerCount = getPointerCount(); 2878 for (int i = 0; i < pointerCount; i++) { 2879 msg.append(", id[").append(i).append("]=").append(getPointerId(i)); 2880 msg.append(", x[").append(i).append("]=").append(getX(i)); 2881 msg.append(", y[").append(i).append("]=").append(getY(i)); 2882 msg.append(", toolType[").append(i).append("]=").append( 2883 toolTypeToString(getToolType(i))); 2884 } 2885 2886 msg.append(", buttonState=").append(MotionEvent.buttonStateToString(getButtonState())); 2887 msg.append(", metaState=").append(KeyEvent.metaStateToString(getMetaState())); 2888 msg.append(", flags=0x").append(Integer.toHexString(getFlags())); 2889 msg.append(", edgeFlags=0x").append(Integer.toHexString(getEdgeFlags())); 2890 msg.append(", pointerCount=").append(pointerCount); 2891 msg.append(", historySize=").append(getHistorySize()); 2892 msg.append(", eventTime=").append(getEventTime()); 2893 msg.append(", downTime=").append(getDownTime()); 2894 msg.append(", deviceId=").append(getDeviceId()); 2895 msg.append(", source=0x").append(Integer.toHexString(getSource())); 2896 msg.append(" }"); 2897 return msg.toString(); 2898 } 2899 2900 /** 2901 * Returns a string that represents the symbolic name of the specified action 2902 * such as "ACTION_DOWN", "ACTION_POINTER_DOWN(3)" or an equivalent numeric constant 2903 * such as "35" if unknown. 2904 * 2905 * @param action The action. 2906 * @return The symbolic name of the specified action. 2907 * @hide 2908 */ 2909 public static String actionToString(int action) { 2910 switch (action) { 2911 case ACTION_DOWN: 2912 return "ACTION_DOWN"; 2913 case ACTION_UP: 2914 return "ACTION_UP"; 2915 case ACTION_CANCEL: 2916 return "ACTION_CANCEL"; 2917 case ACTION_OUTSIDE: 2918 return "ACTION_OUTSIDE"; 2919 case ACTION_MOVE: 2920 return "ACTION_MOVE"; 2921 case ACTION_HOVER_MOVE: 2922 return "ACTION_HOVER_MOVE"; 2923 case ACTION_SCROLL: 2924 return "ACTION_SCROLL"; 2925 case ACTION_HOVER_ENTER: 2926 return "ACTION_HOVER_ENTER"; 2927 case ACTION_HOVER_EXIT: 2928 return "ACTION_HOVER_EXIT"; 2929 } 2930 int index = (action & ACTION_POINTER_INDEX_MASK) >> ACTION_POINTER_INDEX_SHIFT; 2931 switch (action & ACTION_MASK) { 2932 case ACTION_POINTER_DOWN: 2933 return "ACTION_POINTER_DOWN(" + index + ")"; 2934 case ACTION_POINTER_UP: 2935 return "ACTION_POINTER_UP(" + index + ")"; 2936 default: 2937 return Integer.toString(action); 2938 } 2939 } 2940 2941 /** 2942 * Returns a string that represents the symbolic name of the specified axis 2943 * such as "AXIS_X" or an equivalent numeric constant such as "42" if unknown. 2944 * 2945 * @param axis The axis 2946 * @return The symbolic name of the specified axis. 2947 */ 2948 public static String axisToString(int axis) { 2949 String symbolicName = AXIS_SYMBOLIC_NAMES.get(axis); 2950 return symbolicName != null ? symbolicName : Integer.toString(axis); 2951 } 2952 2953 /** 2954 * Gets an axis by its symbolic name such as "AXIS_X" or an 2955 * equivalent numeric constant such as "42". 2956 * 2957 * @param symbolicName The symbolic name of the axis. 2958 * @return The axis or -1 if not found. 2959 * @see #keycodeToString 2960 */ 2961 public static int axisFromString(String symbolicName) { 2962 if (symbolicName == null) { 2963 throw new IllegalArgumentException("symbolicName must not be null"); 2964 } 2965 2966 final int count = AXIS_SYMBOLIC_NAMES.size(); 2967 for (int i = 0; i < count; i++) { 2968 if (symbolicName.equals(AXIS_SYMBOLIC_NAMES.valueAt(i))) { 2969 return i; 2970 } 2971 } 2972 2973 try { 2974 return Integer.parseInt(symbolicName, 10); 2975 } catch (NumberFormatException ex) { 2976 return -1; 2977 } 2978 } 2979 2980 /** 2981 * Returns a string that represents the symbolic name of the specified combined 2982 * button state flags such as "0", "BUTTON_PRIMARY", 2983 * "BUTTON_PRIMARY|BUTTON_SECONDARY" or an equivalent numeric constant such as "0x10000000" 2984 * if unknown. 2985 * 2986 * @param buttonState The button state. 2987 * @return The symbolic name of the specified combined button state flags. 2988 * @hide 2989 */ 2990 public static String buttonStateToString(int buttonState) { 2991 if (buttonState == 0) { 2992 return "0"; 2993 } 2994 StringBuilder result = null; 2995 int i = 0; 2996 while (buttonState != 0) { 2997 final boolean isSet = (buttonState & 1) != 0; 2998 buttonState >>>= 1; // unsigned shift! 2999 if (isSet) { 3000 final String name = BUTTON_SYMBOLIC_NAMES[i]; 3001 if (result == null) { 3002 if (buttonState == 0) { 3003 return name; 3004 } 3005 result = new StringBuilder(name); 3006 } else { 3007 result.append('|'); 3008 result.append(name); 3009 } 3010 } 3011 i += 1; 3012 } 3013 return result.toString(); 3014 } 3015 3016 /** 3017 * Returns a string that represents the symbolic name of the specified tool type 3018 * such as "TOOL_TYPE_FINGER" or an equivalent numeric constant such as "42" if unknown. 3019 * 3020 * @param toolType The tool type. 3021 * @return The symbolic name of the specified tool type. 3022 * @hide 3023 */ 3024 public static String toolTypeToString(int toolType) { 3025 String symbolicName = TOOL_TYPE_SYMBOLIC_NAMES.get(toolType); 3026 return symbolicName != null ? symbolicName : Integer.toString(toolType); 3027 } 3028 3029 public static final Parcelable.Creator<MotionEvent> CREATOR 3030 = new Parcelable.Creator<MotionEvent>() { 3031 public MotionEvent createFromParcel(Parcel in) { 3032 in.readInt(); // skip token, we already know this is a MotionEvent 3033 return MotionEvent.createFromParcelBody(in); 3034 } 3035 3036 public MotionEvent[] newArray(int size) { 3037 return new MotionEvent[size]; 3038 } 3039 }; 3040 3041 /** @hide */ 3042 public static MotionEvent createFromParcelBody(Parcel in) { 3043 MotionEvent ev = obtain(); 3044 ev.mNativePtr = nativeReadFromParcel(ev.mNativePtr, in); 3045 return ev; 3046 } 3047 3048 public void writeToParcel(Parcel out, int flags) { 3049 out.writeInt(PARCEL_TOKEN_MOTION_EVENT); 3050 nativeWriteToParcel(mNativePtr, out); 3051 } 3052 3053 /** 3054 * Transfer object for pointer coordinates. 3055 * 3056 * Objects of this type can be used to specify the pointer coordinates when 3057 * creating new {@link MotionEvent} objects and to query pointer coordinates 3058 * in bulk. 3059 * 3060 * Refer to {@link InputDevice} for information about how different kinds of 3061 * input devices and sources represent pointer coordinates. 3062 */ 3063 public static final class PointerCoords { 3064 private static final int INITIAL_PACKED_AXIS_VALUES = 8; 3065 private long mPackedAxisBits; 3066 private float[] mPackedAxisValues; 3067 3068 /** 3069 * Creates a pointer coords object with all axes initialized to zero. 3070 */ 3071 public PointerCoords() { 3072 } 3073 3074 /** 3075 * Creates a pointer coords object as a copy of the 3076 * contents of another pointer coords object. 3077 * 3078 * @param other The pointer coords object to copy. 3079 */ 3080 public PointerCoords(PointerCoords other) { 3081 copyFrom(other); 3082 } 3083 3084 /** @hide */ 3085 public static PointerCoords[] createArray(int size) { 3086 PointerCoords[] array = new PointerCoords[size]; 3087 for (int i = 0; i < size; i++) { 3088 array[i] = new PointerCoords(); 3089 } 3090 return array; 3091 } 3092 3093 /** 3094 * The X component of the pointer movement. 3095 * 3096 * @see MotionEvent#AXIS_X 3097 */ 3098 public float x; 3099 3100 /** 3101 * The Y component of the pointer movement. 3102 * 3103 * @see MotionEvent#AXIS_Y 3104 */ 3105 public float y; 3106 3107 /** 3108 * A normalized value that describes the pressure applied to the device 3109 * by a finger or other tool. 3110 * The pressure generally ranges from 0 (no pressure at all) to 1 (normal pressure), 3111 * although values higher than 1 may be generated depending on the calibration of 3112 * the input device. 3113 * 3114 * @see MotionEvent#AXIS_PRESSURE 3115 */ 3116 public float pressure; 3117 3118 /** 3119 * A normalized value that describes the approximate size of the pointer touch area 3120 * in relation to the maximum detectable size of the device. 3121 * It represents some approximation of the area of the screen being 3122 * pressed; the actual value in pixels corresponding to the 3123 * touch is normalized with the device specific range of values 3124 * and scaled to a value between 0 and 1. The value of size can be used to 3125 * determine fat touch events. 3126 * 3127 * @see MotionEvent#AXIS_SIZE 3128 */ 3129 public float size; 3130 3131 /** 3132 * The length of the major axis of an ellipse that describes the touch area at 3133 * the point of contact. 3134 * If the device is a touch screen, the length is reported in pixels, otherwise it is 3135 * reported in device-specific units. 3136 * 3137 * @see MotionEvent#AXIS_TOUCH_MAJOR 3138 */ 3139 public float touchMajor; 3140 3141 /** 3142 * The length of the minor axis of an ellipse that describes the touch area at 3143 * the point of contact. 3144 * If the device is a touch screen, the length is reported in pixels, otherwise it is 3145 * reported in device-specific units. 3146 * 3147 * @see MotionEvent#AXIS_TOUCH_MINOR 3148 */ 3149 public float touchMinor; 3150 3151 /** 3152 * The length of the major axis of an ellipse that describes the size of 3153 * the approaching tool. 3154 * The tool area represents the estimated size of the finger or pen that is 3155 * touching the device independent of its actual touch area at the point of contact. 3156 * If the device is a touch screen, the length is reported in pixels, otherwise it is 3157 * reported in device-specific units. 3158 * 3159 * @see MotionEvent#AXIS_TOOL_MAJOR 3160 */ 3161 public float toolMajor; 3162 3163 /** 3164 * The length of the minor axis of an ellipse that describes the size of 3165 * the approaching tool. 3166 * The tool area represents the estimated size of the finger or pen that is 3167 * touching the device independent of its actual touch area at the point of contact. 3168 * If the device is a touch screen, the length is reported in pixels, otherwise it is 3169 * reported in device-specific units. 3170 * 3171 * @see MotionEvent#AXIS_TOOL_MINOR 3172 */ 3173 public float toolMinor; 3174 3175 /** 3176 * The orientation of the touch area and tool area in radians clockwise from vertical. 3177 * An angle of 0 radians indicates that the major axis of contact is oriented 3178 * upwards, is perfectly circular or is of unknown orientation. A positive angle 3179 * indicates that the major axis of contact is oriented to the right. A negative angle 3180 * indicates that the major axis of contact is oriented to the left. 3181 * The full range is from -PI/2 radians (finger pointing fully left) to PI/2 radians 3182 * (finger pointing fully right). 3183 * 3184 * @see MotionEvent#AXIS_ORIENTATION 3185 */ 3186 public float orientation; 3187 3188 /** 3189 * Clears the contents of this object. 3190 * Resets all axes to zero. 3191 */ 3192 public void clear() { 3193 mPackedAxisBits = 0; 3194 3195 x = 0; 3196 y = 0; 3197 pressure = 0; 3198 size = 0; 3199 touchMajor = 0; 3200 touchMinor = 0; 3201 toolMajor = 0; 3202 toolMinor = 0; 3203 orientation = 0; 3204 } 3205 3206 /** 3207 * Copies the contents of another pointer coords object. 3208 * 3209 * @param other The pointer coords object to copy. 3210 */ 3211 public void copyFrom(PointerCoords other) { 3212 final long bits = other.mPackedAxisBits; 3213 mPackedAxisBits = bits; 3214 if (bits != 0) { 3215 final float[] otherValues = other.mPackedAxisValues; 3216 final int count = Long.bitCount(bits); 3217 float[] values = mPackedAxisValues; 3218 if (values == null || count > values.length) { 3219 values = new float[otherValues.length]; 3220 mPackedAxisValues = values; 3221 } 3222 System.arraycopy(otherValues, 0, values, 0, count); 3223 } 3224 3225 x = other.x; 3226 y = other.y; 3227 pressure = other.pressure; 3228 size = other.size; 3229 touchMajor = other.touchMajor; 3230 touchMinor = other.touchMinor; 3231 toolMajor = other.toolMajor; 3232 toolMinor = other.toolMinor; 3233 orientation = other.orientation; 3234 } 3235 3236 /** 3237 * Gets the value associated with the specified axis. 3238 * 3239 * @param axis The axis identifier for the axis value to retrieve. 3240 * @return The value associated with the axis, or 0 if none. 3241 * 3242 * @see MotionEvent#AXIS_X 3243 * @see MotionEvent#AXIS_Y 3244 */ 3245 public float getAxisValue(int axis) { 3246 switch (axis) { 3247 case AXIS_X: 3248 return x; 3249 case AXIS_Y: 3250 return y; 3251 case AXIS_PRESSURE: 3252 return pressure; 3253 case AXIS_SIZE: 3254 return size; 3255 case AXIS_TOUCH_MAJOR: 3256 return touchMajor; 3257 case AXIS_TOUCH_MINOR: 3258 return touchMinor; 3259 case AXIS_TOOL_MAJOR: 3260 return toolMajor; 3261 case AXIS_TOOL_MINOR: 3262 return toolMinor; 3263 case AXIS_ORIENTATION: 3264 return orientation; 3265 default: { 3266 if (axis < 0 || axis > 63) { 3267 throw new IllegalArgumentException("Axis out of range."); 3268 } 3269 final long bits = mPackedAxisBits; 3270 final long axisBit = 1L << axis; 3271 if ((bits & axisBit) == 0) { 3272 return 0; 3273 } 3274 final int index = Long.bitCount(bits & (axisBit - 1L)); 3275 return mPackedAxisValues[index]; 3276 } 3277 } 3278 } 3279 3280 /** 3281 * Sets the value associated with the specified axis. 3282 * 3283 * @param axis The axis identifier for the axis value to assign. 3284 * @param value The value to set. 3285 * 3286 * @see MotionEvent#AXIS_X 3287 * @see MotionEvent#AXIS_Y 3288 */ 3289 public void setAxisValue(int axis, float value) { 3290 switch (axis) { 3291 case AXIS_X: 3292 x = value; 3293 break; 3294 case AXIS_Y: 3295 y = value; 3296 break; 3297 case AXIS_PRESSURE: 3298 pressure = value; 3299 break; 3300 case AXIS_SIZE: 3301 size = value; 3302 break; 3303 case AXIS_TOUCH_MAJOR: 3304 touchMajor = value; 3305 break; 3306 case AXIS_TOUCH_MINOR: 3307 touchMinor = value; 3308 break; 3309 case AXIS_TOOL_MAJOR: 3310 toolMajor = value; 3311 break; 3312 case AXIS_TOOL_MINOR: 3313 toolMinor = value; 3314 break; 3315 case AXIS_ORIENTATION: 3316 orientation = value; 3317 break; 3318 default: { 3319 if (axis < 0 || axis > 63) { 3320 throw new IllegalArgumentException("Axis out of range."); 3321 } 3322 final long bits = mPackedAxisBits; 3323 final long axisBit = 1L << axis; 3324 final int index = Long.bitCount(bits & (axisBit - 1L)); 3325 float[] values = mPackedAxisValues; 3326 if ((bits & axisBit) == 0) { 3327 if (values == null) { 3328 values = new float[INITIAL_PACKED_AXIS_VALUES]; 3329 mPackedAxisValues = values; 3330 } else { 3331 final int count = Long.bitCount(bits); 3332 if (count < values.length) { 3333 if (index != count) { 3334 System.arraycopy(values, index, values, index + 1, 3335 count - index); 3336 } 3337 } else { 3338 float[] newValues = new float[count * 2]; 3339 System.arraycopy(values, 0, newValues, 0, index); 3340 System.arraycopy(values, index, newValues, index + 1, 3341 count - index); 3342 values = newValues; 3343 mPackedAxisValues = values; 3344 } 3345 } 3346 mPackedAxisBits = bits | axisBit; 3347 } 3348 values[index] = value; 3349 } 3350 } 3351 } 3352 } 3353 3354 /** 3355 * Transfer object for pointer properties. 3356 * 3357 * Objects of this type can be used to specify the pointer id and tool type 3358 * when creating new {@link MotionEvent} objects and to query pointer properties in bulk. 3359 */ 3360 public static final class PointerProperties { 3361 /** 3362 * Creates a pointer properties object with an invalid pointer id. 3363 */ 3364 public PointerProperties() { 3365 clear(); 3366 } 3367 3368 /** 3369 * Creates a pointer properties object as a copy of the contents of 3370 * another pointer properties object. 3371 * @param other 3372 */ 3373 public PointerProperties(PointerProperties other) { 3374 copyFrom(other); 3375 } 3376 3377 /** @hide */ 3378 public static PointerProperties[] createArray(int size) { 3379 PointerProperties[] array = new PointerProperties[size]; 3380 for (int i = 0; i < size; i++) { 3381 array[i] = new PointerProperties(); 3382 } 3383 return array; 3384 } 3385 3386 /** 3387 * The pointer id. 3388 * Initially set to {@link #INVALID_POINTER_ID} (-1). 3389 * 3390 * @see MotionEvent#getPointerId(int) 3391 */ 3392 public int id; 3393 3394 /** 3395 * The pointer tool type. 3396 * Initially set to 0. 3397 * 3398 * @see MotionEvent#getToolType(int) 3399 */ 3400 public int toolType; 3401 3402 /** 3403 * Resets the pointer properties to their initial values. 3404 */ 3405 public void clear() { 3406 id = INVALID_POINTER_ID; 3407 toolType = TOOL_TYPE_UNKNOWN; 3408 } 3409 3410 /** 3411 * Copies the contents of another pointer properties object. 3412 * 3413 * @param other The pointer properties object to copy. 3414 */ 3415 public void copyFrom(PointerProperties other) { 3416 id = other.id; 3417 toolType = other.toolType; 3418 } 3419 } 3420} 3421