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 17 package android.view; 18 19 import static android.os.IInputConstants.INPUT_EVENT_FLAG_IS_ACCESSIBILITY_EVENT; 20 import static android.view.Display.DEFAULT_DISPLAY; 21 22 import static java.lang.annotation.RetentionPolicy.SOURCE; 23 24 import android.annotation.IntDef; 25 import android.annotation.Nullable; 26 import android.annotation.TestApi; 27 import android.compat.annotation.UnsupportedAppUsage; 28 import android.graphics.Matrix; 29 import android.os.Build; 30 import android.os.Parcel; 31 import android.os.Parcelable; 32 import android.os.SystemClock; 33 import android.util.Log; 34 import android.util.SparseArray; 35 36 import dalvik.annotation.optimization.CriticalNative; 37 import dalvik.annotation.optimization.FastNative; 38 39 import java.lang.annotation.Retention; 40 import java.util.Objects; 41 42 /** 43 * Object used to report movement (mouse, pen, finger, trackball) events. 44 * Motion events may hold either absolute or relative movements and other data, 45 * depending on the type of device. 46 * 47 * <h3>Overview</h3> 48 * <p> 49 * Motion events describe movements in terms of an action code and a set of axis values. 50 * The action code specifies the state change that occurred such as a pointer going 51 * down or up. The axis values describe the position and other movement properties. 52 * </p><p> 53 * For example, when the user first touches the screen, the system delivers a touch 54 * event to the appropriate {@link View} with the action code {@link #ACTION_DOWN} 55 * and a set of axis values that include the X and Y coordinates of the touch and 56 * information about the pressure, size and orientation of the contact area. 57 * </p><p> 58 * Some devices can report multiple movement traces at the same time. Multi-touch 59 * screens emit one movement trace for each finger. The individual fingers or 60 * other objects that generate movement traces are referred to as <em>pointers</em>. 61 * Motion events contain information about all of the pointers that are currently active 62 * even if some of them have not moved since the last event was delivered. 63 * </p><p> 64 * The number of pointers only ever changes by one as individual pointers go up and down, 65 * except when the gesture is canceled. 66 * </p><p> 67 * Each pointer has a unique id that is assigned when it first goes down 68 * (indicated by {@link #ACTION_DOWN} or {@link #ACTION_POINTER_DOWN}). A pointer id 69 * remains valid until the pointer eventually goes up (indicated by {@link #ACTION_UP} 70 * or {@link #ACTION_POINTER_UP}) or when the gesture is canceled (indicated by 71 * {@link #ACTION_CANCEL}). 72 * </p><p> 73 * The MotionEvent class provides many methods to query the position and other properties of 74 * pointers, such as {@link #getX(int)}, {@link #getY(int)}, {@link #getAxisValue}, 75 * {@link #getPointerId(int)}, {@link #getToolType(int)}, and many others. Most of these 76 * methods accept the pointer index as a parameter rather than the pointer id. 77 * The pointer index of each pointer in the event ranges from 0 to one less than the value 78 * returned by {@link #getPointerCount()}. 79 * </p><p> 80 * The order in which individual pointers appear within a motion event is undefined. 81 * Thus the pointer index of a pointer can change from one event to the next but 82 * the pointer id of a pointer is guaranteed to remain constant as long as the pointer 83 * remains active. Use the {@link #getPointerId(int)} method to obtain the 84 * pointer id of a pointer to track it across all subsequent motion events in a gesture. 85 * Then for successive motion events, use the {@link #findPointerIndex(int)} method 86 * to obtain the pointer index for a given pointer id in that motion event. 87 * </p><p> 88 * Mouse and stylus buttons can be retrieved using {@link #getButtonState()}. It is a 89 * good idea to check the button state while handling {@link #ACTION_DOWN} as part 90 * of a touch event. The application may choose to perform some different action 91 * if the touch event starts due to a secondary button click, such as presenting a 92 * context menu. 93 * </p> 94 * 95 * <h3>Batching</h3> 96 * <p> 97 * For efficiency, motion events with {@link #ACTION_MOVE} may batch together 98 * multiple movement samples within a single object. The most current 99 * pointer coordinates are available using {@link #getX(int)} and {@link #getY(int)}. 100 * Earlier coordinates within the batch are accessed using {@link #getHistoricalX(int, int)} 101 * and {@link #getHistoricalY(int, int)}. The coordinates are "historical" only 102 * insofar as they are older than the current coordinates in the batch; however, 103 * they are still distinct from any other coordinates reported in prior motion events. 104 * To process all coordinates in the batch in time order, first consume the historical 105 * coordinates then consume the current coordinates. 106 * </p><p> 107 * Example: Consuming all samples for all pointers in a motion event in time order. 108 * </p><p><pre><code> 109 * void printSamples(MotionEvent ev) { 110 * final int historySize = ev.getHistorySize(); 111 * final int pointerCount = ev.getPointerCount(); 112 * for (int h = 0; h < historySize; h++) { 113 * System.out.printf("At time %d:", ev.getHistoricalEventTime(h)); 114 * for (int p = 0; p < pointerCount; p++) { 115 * System.out.printf(" pointer %d: (%f,%f)", 116 * ev.getPointerId(p), ev.getHistoricalX(p, h), ev.getHistoricalY(p, h)); 117 * } 118 * } 119 * System.out.printf("At time %d:", ev.getEventTime()); 120 * for (int p = 0; p < pointerCount; p++) { 121 * System.out.printf(" pointer %d: (%f,%f)", 122 * ev.getPointerId(p), ev.getX(p), ev.getY(p)); 123 * } 124 * } 125 * </code></pre></p> 126 * 127 * <h3>Device Types</h3> 128 * <p> 129 * The interpretation of the contents of a MotionEvent varies significantly depending 130 * on the source class of the device. 131 * </p><p> 132 * On pointing devices with source class {@link InputDevice#SOURCE_CLASS_POINTER} 133 * such as touch screens, the pointer coordinates specify absolute 134 * positions such as view X/Y coordinates. Each complete gesture is represented 135 * by a sequence of motion events with actions that describe pointer state transitions 136 * and movements. A gesture starts with a motion event with {@link #ACTION_DOWN} 137 * that provides the location of the first pointer down. As each additional 138 * pointer that goes down or up, the framework will generate a motion event with 139 * {@link #ACTION_POINTER_DOWN} or {@link #ACTION_POINTER_UP} accordingly. 140 * Pointer movements are described by motion events with {@link #ACTION_MOVE}. 141 * Finally, a gesture end either when the final pointer goes up as represented 142 * by a motion event with {@link #ACTION_UP} or when gesture is canceled 143 * with {@link #ACTION_CANCEL}. 144 * </p><p> 145 * Some pointing devices such as mice may support vertical and/or horizontal scrolling. 146 * A scroll event is reported as a generic motion event with {@link #ACTION_SCROLL} that 147 * includes the relative scroll offset in the {@link #AXIS_VSCROLL} and 148 * {@link #AXIS_HSCROLL} axes. See {@link #getAxisValue(int)} for information 149 * about retrieving these additional axes. 150 * </p><p> 151 * On trackball devices with source class {@link InputDevice#SOURCE_CLASS_TRACKBALL}, 152 * the pointer coordinates specify relative movements as X/Y deltas. 153 * A trackball gesture consists of a sequence of movements described by motion 154 * events with {@link #ACTION_MOVE} interspersed with occasional {@link #ACTION_DOWN} 155 * or {@link #ACTION_UP} motion events when the trackball button is pressed or released. 156 * </p><p> 157 * On joystick devices with source class {@link InputDevice#SOURCE_CLASS_JOYSTICK}, 158 * the pointer coordinates specify the absolute position of the joystick axes. 159 * The joystick axis values are normalized to a range of -1.0 to 1.0 where 0.0 corresponds 160 * to the center position. More information about the set of available axes and the 161 * range of motion can be obtained using {@link InputDevice#getMotionRange}. 162 * Some common joystick axes are {@link #AXIS_X}, {@link #AXIS_Y}, 163 * {@link #AXIS_HAT_X}, {@link #AXIS_HAT_Y}, {@link #AXIS_Z} and {@link #AXIS_RZ}. 164 * </p><p> 165 * Refer to {@link InputDevice} for more information about how different kinds of 166 * input devices and sources represent pointer coordinates. 167 * </p> 168 * 169 * <h3>Consistency Guarantees</h3> 170 * <p> 171 * Motion events are always delivered to views as a consistent stream of events. 172 * What constitutes a consistent stream varies depending on the type of device. 173 * For touch events, consistency implies that pointers go down one at a time, 174 * move around as a group and then go up one at a time or are canceled. 175 * </p><p> 176 * While the framework tries to deliver consistent streams of motion events to 177 * views, it cannot guarantee it. Some events may be dropped or modified by 178 * containing views in the application before they are delivered thereby making 179 * the stream of events inconsistent. Views should always be prepared to 180 * handle {@link #ACTION_CANCEL} and should tolerate anomalous 181 * situations such as receiving a new {@link #ACTION_DOWN} without first having 182 * received an {@link #ACTION_UP} for the prior gesture. 183 * </p> 184 */ 185 public final class MotionEvent extends InputEvent implements Parcelable { 186 private static final String TAG = "MotionEvent"; 187 private static final long NS_PER_MS = 1000000; 188 private static final String LABEL_PREFIX = "AXIS_"; 189 190 private static final boolean DEBUG_CONCISE_TOSTRING = false; 191 192 /** 193 * An invalid pointer id. 194 * 195 * This value (-1) can be used as a placeholder to indicate that a pointer id 196 * has not been assigned or is not available. It cannot appear as 197 * a pointer id inside a {@link MotionEvent}. 198 */ 199 public static final int INVALID_POINTER_ID = -1; 200 201 /** 202 * Bit mask of the parts of the action code that are the action itself. 203 */ 204 public static final int ACTION_MASK = 0xff; 205 206 /** 207 * Constant for {@link #getActionMasked}: A pressed gesture has started, the 208 * motion contains the initial starting location. 209 * <p> 210 * This is also a good time to check the button state to distinguish 211 * secondary and tertiary button clicks and handle them appropriately. 212 * Use {@link #getButtonState} to retrieve the button state. 213 * </p> 214 */ 215 public static final int ACTION_DOWN = 0; 216 217 /** 218 * Constant for {@link #getActionMasked}: A pressed gesture has finished, the 219 * motion contains the final release location as well as any intermediate 220 * points since the last down or move event. 221 */ 222 public static final int ACTION_UP = 1; 223 224 /** 225 * Constant for {@link #getActionMasked}: A change has happened during a 226 * press gesture (between {@link #ACTION_DOWN} and {@link #ACTION_UP}). 227 * The motion contains the most recent point, as well as any intermediate 228 * points since the last down or move event. 229 */ 230 public static final int ACTION_MOVE = 2; 231 232 /** 233 * Constant for {@link #getActionMasked}: The current gesture has been aborted. 234 * You will not receive any more points in it. You should treat this as 235 * an up event, but not perform any action that you normally would. 236 */ 237 public static final int ACTION_CANCEL = 3; 238 239 /** 240 * Constant for {@link #getActionMasked}: A movement has happened outside of the 241 * normal bounds of the UI element. This does not provide a full gesture, 242 * but only the initial location of the movement/touch. 243 * <p> 244 * Note: Because the location of any event will be outside the 245 * bounds of the view hierarchy, it will not get dispatched to 246 * any children of a ViewGroup by default. Therefore, 247 * movements with ACTION_OUTSIDE should be handled in either the 248 * root {@link View} or in the appropriate {@link Window.Callback} 249 * (e.g. {@link android.app.Activity} or {@link android.app.Dialog}). 250 * </p> 251 */ 252 public static final int ACTION_OUTSIDE = 4; 253 254 /** 255 * Constant for {@link #getActionMasked}: A non-primary pointer has gone down. 256 * <p> 257 * Use {@link #getActionIndex} to retrieve the index of the pointer that changed. 258 * </p><p> 259 * The index is encoded in the {@link #ACTION_POINTER_INDEX_MASK} bits of the 260 * unmasked action returned by {@link #getAction}. 261 * </p> 262 */ 263 public static final int ACTION_POINTER_DOWN = 5; 264 265 /** 266 * Constant for {@link #getActionMasked}: A non-primary pointer has gone up. 267 * <p> 268 * Use {@link #getActionIndex} to retrieve the index of the pointer that changed. 269 * </p><p> 270 * The index is encoded in the {@link #ACTION_POINTER_INDEX_MASK} bits of the 271 * unmasked action returned by {@link #getAction}. 272 * </p> 273 */ 274 public static final int ACTION_POINTER_UP = 6; 275 276 /** 277 * Constant for {@link #getActionMasked}: A change happened but the pointer 278 * is not down (unlike {@link #ACTION_MOVE}). The motion contains the most 279 * recent point, as well as any intermediate points since the last 280 * hover move event. 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_MOVE = 7; 290 291 /** 292 * Constant for {@link #getActionMasked}: The motion event contains relative 293 * vertical and/or horizontal scroll offsets. Use {@link #getAxisValue(int)} 294 * to retrieve the information from {@link #AXIS_VSCROLL} and {@link #AXIS_HSCROLL}. 295 * The pointer may or may not be down when this event is dispatched. 296 * <p> 297 * This action is always delivered to the window or view under the pointer, which 298 * may not be the window or view currently touched. 299 * </p><p> 300 * This action is not a touch event so it is delivered to 301 * {@link View#onGenericMotionEvent(MotionEvent)} rather than 302 * {@link View#onTouchEvent(MotionEvent)}. 303 * </p> 304 */ 305 public static final int ACTION_SCROLL = 8; 306 307 /** 308 * Constant for {@link #getActionMasked}: The pointer is not down but has entered the 309 * boundaries of a window or view. 310 * <p> 311 * This action is always delivered to the window or view under the pointer. 312 * </p><p> 313 * This action is not a touch event so it is delivered to 314 * {@link View#onGenericMotionEvent(MotionEvent)} rather than 315 * {@link View#onTouchEvent(MotionEvent)}. 316 * </p> 317 */ 318 public static final int ACTION_HOVER_ENTER = 9; 319 320 /** 321 * Constant for {@link #getActionMasked}: The pointer is not down but has exited the 322 * boundaries of a window or view. 323 * <p> 324 * This action is always delivered to the window or view that was previously under the pointer. 325 * </p><p> 326 * This action is not a touch event so it is delivered to 327 * {@link View#onGenericMotionEvent(MotionEvent)} rather than 328 * {@link View#onTouchEvent(MotionEvent)}. 329 * </p> 330 */ 331 public static final int ACTION_HOVER_EXIT = 10; 332 333 /** 334 * Constant for {@link #getActionMasked}: A button has been pressed. 335 * 336 * <p> 337 * Use {@link #getActionButton()} to get which button was pressed. 338 * </p><p> 339 * This action is not a touch event so it is delivered to 340 * {@link View#onGenericMotionEvent(MotionEvent)} rather than 341 * {@link View#onTouchEvent(MotionEvent)}. 342 * </p> 343 */ 344 public static final int ACTION_BUTTON_PRESS = 11; 345 346 /** 347 * Constant for {@link #getActionMasked}: A button has been released. 348 * 349 * <p> 350 * Use {@link #getActionButton()} to get which button was released. 351 * </p><p> 352 * This action is not a touch event so it is delivered to 353 * {@link View#onGenericMotionEvent(MotionEvent)} rather than 354 * {@link View#onTouchEvent(MotionEvent)}. 355 * </p> 356 */ 357 public static final int ACTION_BUTTON_RELEASE = 12; 358 359 /** 360 * Bits in the action code that represent a pointer index, used with 361 * {@link #ACTION_POINTER_DOWN} and {@link #ACTION_POINTER_UP}. Shifting 362 * down by {@link #ACTION_POINTER_INDEX_SHIFT} provides the actual pointer 363 * index where the data for the pointer going up or down can be found; you can 364 * get its identifier with {@link #getPointerId(int)} and the actual 365 * data with {@link #getX(int)} etc. 366 * 367 * @see #getActionIndex 368 */ 369 public static final int ACTION_POINTER_INDEX_MASK = 0xff00; 370 371 /** 372 * Bit shift for the action bits holding the pointer index as 373 * defined by {@link #ACTION_POINTER_INDEX_MASK}. 374 * 375 * @see #getActionIndex 376 */ 377 public static final int ACTION_POINTER_INDEX_SHIFT = 8; 378 379 /** 380 * @deprecated Use {@link #ACTION_POINTER_INDEX_MASK} to retrieve the 381 * data index associated with {@link #ACTION_POINTER_DOWN}. 382 */ 383 @Deprecated 384 public static final int ACTION_POINTER_1_DOWN = ACTION_POINTER_DOWN | 0x0000; 385 386 /** 387 * @deprecated Use {@link #ACTION_POINTER_INDEX_MASK} to retrieve the 388 * data index associated with {@link #ACTION_POINTER_DOWN}. 389 */ 390 @Deprecated 391 public static final int ACTION_POINTER_2_DOWN = ACTION_POINTER_DOWN | 0x0100; 392 393 /** 394 * @deprecated Use {@link #ACTION_POINTER_INDEX_MASK} to retrieve the 395 * data index associated with {@link #ACTION_POINTER_DOWN}. 396 */ 397 @Deprecated 398 public static final int ACTION_POINTER_3_DOWN = ACTION_POINTER_DOWN | 0x0200; 399 400 /** 401 * @deprecated Use {@link #ACTION_POINTER_INDEX_MASK} to retrieve the 402 * data index associated with {@link #ACTION_POINTER_UP}. 403 */ 404 @Deprecated 405 public static final int ACTION_POINTER_1_UP = ACTION_POINTER_UP | 0x0000; 406 407 /** 408 * @deprecated Use {@link #ACTION_POINTER_INDEX_MASK} to retrieve the 409 * data index associated with {@link #ACTION_POINTER_UP}. 410 */ 411 @Deprecated 412 public static final int ACTION_POINTER_2_UP = ACTION_POINTER_UP | 0x0100; 413 414 /** 415 * @deprecated Use {@link #ACTION_POINTER_INDEX_MASK} to retrieve the 416 * data index associated with {@link #ACTION_POINTER_UP}. 417 */ 418 @Deprecated 419 public static final int ACTION_POINTER_3_UP = ACTION_POINTER_UP | 0x0200; 420 421 /** 422 * @deprecated Renamed to {@link #ACTION_POINTER_INDEX_MASK} to match 423 * the actual data contained in these bits. 424 */ 425 @Deprecated 426 public static final int ACTION_POINTER_ID_MASK = 0xff00; 427 428 /** 429 * @deprecated Renamed to {@link #ACTION_POINTER_INDEX_SHIFT} to match 430 * the actual data contained in these bits. 431 */ 432 @Deprecated 433 public static final int ACTION_POINTER_ID_SHIFT = 8; 434 435 /** 436 * This flag indicates that the window that received this motion event is partly 437 * or wholly obscured by another visible window above it and the event directly passed through 438 * the obscured area. 439 * 440 * A security sensitive application can check this flag to identify situations in which 441 * a malicious application may have covered up part of its content for the purpose 442 * of misleading the user or hijacking touches. An appropriate response might be 443 * to drop the suspect touches or to take additional precautions to confirm the user's 444 * actual intent. 445 */ 446 public static final int FLAG_WINDOW_IS_OBSCURED = 0x1; 447 448 /** 449 * This flag indicates that the window that received this motion event is partly 450 * or wholly obscured by another visible window above it and the event did not directly pass 451 * through the obscured area. 452 * 453 * A security sensitive application can check this flag to identify situations in which 454 * a malicious application may have covered up part of its content for the purpose 455 * of misleading the user or hijacking touches. An appropriate response might be 456 * to drop the suspect touches or to take additional precautions to confirm the user's 457 * actual intent. 458 * 459 * Unlike FLAG_WINDOW_IS_OBSCURED, this is only true if the window that received this event is 460 * obstructed in areas other than the touched location. 461 */ 462 public static final int FLAG_WINDOW_IS_PARTIALLY_OBSCURED = 0x2; 463 464 /** 465 * This private flag is only set on {@link #ACTION_HOVER_MOVE} events and indicates that 466 * this event will be immediately followed by a {@link #ACTION_HOVER_EXIT}. It is used to 467 * prevent generating redundant {@link #ACTION_HOVER_ENTER} events. 468 * @hide 469 */ 470 public static final int FLAG_HOVER_EXIT_PENDING = 0x4; 471 472 /** 473 * This flag indicates that the event has been generated by a gesture generator. It 474 * provides a hint to the GestureDetector to not apply any touch slop. 475 * 476 * @hide 477 */ 478 public static final int FLAG_IS_GENERATED_GESTURE = 0x8; 479 480 /** 481 * This flag is only set for events with {@link #ACTION_POINTER_UP} and {@link #ACTION_CANCEL}. 482 * It indicates that the pointer going up was an unintentional user touch. When FLAG_CANCELED 483 * is set, the typical actions that occur in response for a pointer going up (such as click 484 * handlers, end of drawing) should be aborted. This flag is typically set when the user was 485 * accidentally touching the screen, such as by gripping the device, or placing the palm on the 486 * screen. 487 * 488 * @see #ACTION_POINTER_UP 489 * @see #ACTION_CANCEL 490 */ 491 public static final int FLAG_CANCELED = 0x20; 492 493 /** 494 * This flag indicates that the event will not cause a focus change if it is directed to an 495 * unfocused window, even if it an {@link #ACTION_DOWN}. This is typically used with pointer 496 * gestures to allow the user to direct gestures to an unfocused window without bringing the 497 * window into focus. 498 * @hide 499 */ 500 public static final int FLAG_NO_FOCUS_CHANGE = 0x40; 501 502 /** 503 * This flag indicates that this event was modified by or generated from an accessibility 504 * service. Value = 0x800 505 * @hide 506 */ 507 @TestApi 508 public static final int FLAG_IS_ACCESSIBILITY_EVENT = INPUT_EVENT_FLAG_IS_ACCESSIBILITY_EVENT; 509 510 /** 511 * Private flag that indicates when the system has detected that this motion event 512 * may be inconsistent with respect to the sequence of previously delivered motion events, 513 * such as when a pointer move event is sent but the pointer is not down. 514 * 515 * @hide 516 * @see #isTainted 517 * @see #setTainted 518 */ 519 public static final int FLAG_TAINTED = 0x80000000; 520 521 /** 522 * Private flag indicating that this event was synthesized by the system and should be delivered 523 * to the accessibility focused view first. When being dispatched such an event is not handled 524 * by predecessors of the accessibility focused view and after the event reaches that view the 525 * flag is cleared and normal event dispatch is performed. This ensures that the platform can 526 * click on any view that has accessibility focus which is semantically equivalent to asking the 527 * view to perform a click accessibility action but more generic as views not implementing click 528 * action correctly can still be activated. 529 * 530 * @hide 531 * @see #isTargetAccessibilityFocus() 532 * @see #setTargetAccessibilityFocus(boolean) 533 */ 534 public static final int FLAG_TARGET_ACCESSIBILITY_FOCUS = 0x40000000; 535 536 /** 537 * Flag indicating the motion event intersected the top edge of the screen. 538 */ 539 public static final int EDGE_TOP = 0x00000001; 540 541 /** 542 * Flag indicating the motion event intersected the bottom edge of the screen. 543 */ 544 public static final int EDGE_BOTTOM = 0x00000002; 545 546 /** 547 * Flag indicating the motion event intersected the left edge of the screen. 548 */ 549 public static final int EDGE_LEFT = 0x00000004; 550 551 /** 552 * Flag indicating the motion event intersected the right edge of the screen. 553 */ 554 public static final int EDGE_RIGHT = 0x00000008; 555 556 /** 557 * Axis constant: X axis of a motion event. 558 * <p> 559 * <ul> 560 * <li>For a touch screen, reports the absolute X screen position of the center of 561 * the touch contact area. The units are display pixels. 562 * <li>For a touch pad, reports the absolute X surface position of the center of the touch 563 * contact area. The units are device-dependent; use {@link InputDevice#getMotionRange(int)} 564 * to query the effective range of values. 565 * <li>For a mouse, reports the absolute X screen position of the mouse pointer. 566 * The units are display pixels. 567 * <li>For a trackball, reports the relative horizontal displacement of the trackball. 568 * The value is normalized to a range from -1.0 (left) to 1.0 (right). 569 * <li>For a joystick, reports the absolute X position of the joystick. 570 * The value is normalized to a range from -1.0 (left) to 1.0 (right). 571 * </ul> 572 * </p> 573 * 574 * @see #getX(int) 575 * @see #getHistoricalX(int, int) 576 * @see MotionEvent.PointerCoords#x 577 * @see InputDevice#getMotionRange 578 */ 579 public static final int AXIS_X = 0; 580 581 /** 582 * Axis constant: Y axis of a motion event. 583 * <p> 584 * <ul> 585 * <li>For a touch screen, reports the absolute Y screen position of the center of 586 * the touch contact area. The units are display pixels. 587 * <li>For a touch pad, reports the absolute Y surface position of the center of the touch 588 * contact area. The units are device-dependent; use {@link InputDevice#getMotionRange(int)} 589 * to query the effective range of values. 590 * <li>For a mouse, reports the absolute Y screen position of the mouse pointer. 591 * The units are display pixels. 592 * <li>For a trackball, reports the relative vertical displacement of the trackball. 593 * The value is normalized to a range from -1.0 (up) to 1.0 (down). 594 * <li>For a joystick, reports the absolute Y position of the joystick. 595 * The value is normalized to a range from -1.0 (up or far) to 1.0 (down or near). 596 * </ul> 597 * </p> 598 * 599 * @see #getY(int) 600 * @see #getHistoricalY(int, int) 601 * @see MotionEvent.PointerCoords#y 602 * @see InputDevice#getMotionRange 603 */ 604 public static final int AXIS_Y = 1; 605 606 /** 607 * Axis constant: Pressure axis of a motion event. 608 * <p> 609 * <ul> 610 * <li>For a touch screen or touch pad, reports the approximate pressure applied to the surface 611 * by a finger or other tool. The value is normalized to a range from 612 * 0 (no pressure at all) to 1 (normal pressure), although values higher than 1 613 * may be generated depending on the calibration of the input device. 614 * <li>For a trackball, the value is set to 1 if the trackball button is pressed 615 * or 0 otherwise. 616 * <li>For a mouse, the value is set to 1 if the primary mouse button is pressed 617 * or 0 otherwise. 618 * </ul> 619 * </p> 620 * 621 * @see #getPressure(int) 622 * @see #getHistoricalPressure(int, int) 623 * @see MotionEvent.PointerCoords#pressure 624 * @see InputDevice#getMotionRange 625 */ 626 public static final int AXIS_PRESSURE = 2; 627 628 /** 629 * Axis constant: Size axis of a motion event. 630 * <p> 631 * <ul> 632 * <li>For a touch screen or touch pad, reports the approximate size of the contact area in 633 * relation to the maximum detectable size for the device. The value is normalized 634 * to a range from 0 (smallest detectable size) to 1 (largest detectable size), 635 * although it is not a linear scale. This value is of limited use. 636 * To obtain calibrated size information, use 637 * {@link #AXIS_TOUCH_MAJOR} or {@link #AXIS_TOOL_MAJOR}. 638 * </ul> 639 * </p> 640 * 641 * @see #getSize(int) 642 * @see #getHistoricalSize(int, int) 643 * @see MotionEvent.PointerCoords#size 644 * @see InputDevice#getMotionRange 645 */ 646 public static final int AXIS_SIZE = 3; 647 648 /** 649 * Axis constant: TouchMajor axis of a motion event. 650 * <p> 651 * <ul> 652 * <li>For a touch screen, reports the length of the major axis of an ellipse that 653 * represents the touch area at the point of contact. 654 * The units are display pixels. 655 * <li>For a touch pad, reports the length of the major axis of an ellipse that 656 * represents the touch area at the point of contact. 657 * The units are device-dependent; use {@link InputDevice#getMotionRange(int)} 658 * to query the effective range of values. 659 * </ul> 660 * </p> 661 * 662 * @see #getTouchMajor(int) 663 * @see #getHistoricalTouchMajor(int, int) 664 * @see MotionEvent.PointerCoords#touchMajor 665 * @see InputDevice#getMotionRange 666 */ 667 public static final int AXIS_TOUCH_MAJOR = 4; 668 669 /** 670 * Axis constant: TouchMinor axis of a motion event. 671 * <p> 672 * <ul> 673 * <li>For a touch screen, reports the length of the minor axis of an ellipse that 674 * represents the touch area at the point of contact. 675 * The units are display pixels. 676 * <li>For a touch pad, reports the length of the minor axis of an ellipse that 677 * represents the touch area at the point of contact. 678 * The units are device-dependent; use {@link InputDevice#getMotionRange(int)} 679 * to query the effective range of values. 680 * </ul> 681 * </p><p> 682 * When the touch is circular, the major and minor axis lengths will be equal to one another. 683 * </p> 684 * 685 * @see #getTouchMinor(int) 686 * @see #getHistoricalTouchMinor(int, int) 687 * @see MotionEvent.PointerCoords#touchMinor 688 * @see InputDevice#getMotionRange 689 */ 690 public static final int AXIS_TOUCH_MINOR = 5; 691 692 /** 693 * Axis constant: ToolMajor axis of a motion event. 694 * <p> 695 * <ul> 696 * <li>For a touch screen, reports the length of the major axis of an ellipse that 697 * represents the size of the approaching finger or tool used to make contact. 698 * <li>For a touch pad, reports the length of the major axis of an ellipse that 699 * represents the size of the approaching finger or tool used to make contact. 700 * The units are device-dependent; use {@link InputDevice#getMotionRange(int)} 701 * to query the effective range of values. 702 * </ul> 703 * </p><p> 704 * When the touch is circular, the major and minor axis lengths will be equal to one another. 705 * </p><p> 706 * The tool size may be larger than the touch size since the tool may not be fully 707 * in contact with the touch sensor. 708 * </p> 709 * 710 * @see #getToolMajor(int) 711 * @see #getHistoricalToolMajor(int, int) 712 * @see MotionEvent.PointerCoords#toolMajor 713 * @see InputDevice#getMotionRange 714 */ 715 public static final int AXIS_TOOL_MAJOR = 6; 716 717 /** 718 * Axis constant: ToolMinor axis of a motion event. 719 * <p> 720 * <ul> 721 * <li>For a touch screen, reports the length of the minor axis of an ellipse that 722 * represents the size of the approaching finger or tool used to make contact. 723 * <li>For a touch pad, reports the length of the minor axis of an ellipse that 724 * represents the size of the approaching finger or tool used to make contact. 725 * The units are device-dependent; use {@link InputDevice#getMotionRange(int)} 726 * to query the effective range of values. 727 * </ul> 728 * </p><p> 729 * When the touch is circular, the major and minor axis lengths will be equal to one another. 730 * </p><p> 731 * The tool size may be larger than the touch size since the tool may not be fully 732 * in contact with the touch sensor. 733 * </p> 734 * 735 * @see #getToolMinor(int) 736 * @see #getHistoricalToolMinor(int, int) 737 * @see MotionEvent.PointerCoords#toolMinor 738 * @see InputDevice#getMotionRange 739 */ 740 public static final int AXIS_TOOL_MINOR = 7; 741 742 /** 743 * Axis constant: Orientation axis of a motion event. 744 * <p> 745 * <ul> 746 * <li>For a touch screen or touch pad, reports the orientation of the finger 747 * or tool in radians relative to the vertical plane of the device. 748 * An angle of 0 radians indicates that the major axis of contact is oriented 749 * upwards, is perfectly circular or is of unknown orientation. A positive angle 750 * indicates that the major axis of contact is oriented to the right. A negative angle 751 * indicates that the major axis of contact is oriented to the left. 752 * The full range is from -PI/2 radians (finger pointing fully left) to PI/2 radians 753 * (finger pointing fully right). 754 * <li>For a stylus, the orientation indicates the direction in which the stylus 755 * is pointing in relation to the vertical axis of the current orientation of the screen. 756 * The range is from -PI radians to PI radians, where 0 is pointing up, 757 * -PI/2 radians is pointing left, -PI or PI radians is pointing down, and PI/2 radians 758 * is pointing right. See also {@link #AXIS_TILT}. 759 * </ul> 760 * </p> 761 * 762 * @see #getOrientation(int) 763 * @see #getHistoricalOrientation(int, int) 764 * @see MotionEvent.PointerCoords#orientation 765 * @see InputDevice#getMotionRange 766 */ 767 public static final int AXIS_ORIENTATION = 8; 768 769 /** 770 * Axis constant: Vertical Scroll axis of a motion event. 771 * <p> 772 * <ul> 773 * <li>For a mouse, reports the relative movement of the vertical scroll wheel. 774 * The value is normalized to a range from -1.0 (down) to 1.0 (up). 775 * </ul> 776 * </p><p> 777 * This axis should be used to scroll views vertically. 778 * </p> 779 * 780 * @see #getAxisValue(int, int) 781 * @see #getHistoricalAxisValue(int, int, int) 782 * @see MotionEvent.PointerCoords#getAxisValue(int) 783 * @see InputDevice#getMotionRange 784 */ 785 public static final int AXIS_VSCROLL = 9; 786 787 /** 788 * Axis constant: Horizontal Scroll axis of a motion event. 789 * <p> 790 * <ul> 791 * <li>For a mouse, reports the relative movement of the horizontal scroll wheel. 792 * The value is normalized to a range from -1.0 (left) to 1.0 (right). 793 * </ul> 794 * </p><p> 795 * This axis should be used to scroll views horizontally. 796 * </p> 797 * 798 * @see #getAxisValue(int, int) 799 * @see #getHistoricalAxisValue(int, int, int) 800 * @see MotionEvent.PointerCoords#getAxisValue(int) 801 * @see InputDevice#getMotionRange 802 */ 803 public static final int AXIS_HSCROLL = 10; 804 805 /** 806 * Axis constant: Z axis of a motion event. 807 * <p> 808 * <ul> 809 * <li>For a joystick, reports the absolute Z position of the joystick. 810 * The value is normalized to a range from -1.0 (high) to 1.0 (low). 811 * <em>On game pads with two analog joysticks, this axis is often reinterpreted 812 * to report the absolute X position of the second joystick instead.</em> 813 * </ul> 814 * </p> 815 * 816 * @see #getAxisValue(int, int) 817 * @see #getHistoricalAxisValue(int, int, int) 818 * @see MotionEvent.PointerCoords#getAxisValue(int) 819 * @see InputDevice#getMotionRange 820 */ 821 public static final int AXIS_Z = 11; 822 823 /** 824 * Axis constant: X Rotation axis of a motion event. 825 * <p> 826 * <ul> 827 * <li>For a joystick, reports the absolute rotation angle about the X axis. 828 * The value is normalized to a range from -1.0 (counter-clockwise) to 1.0 (clockwise). 829 * </ul> 830 * </p> 831 * 832 * @see #getAxisValue(int, int) 833 * @see #getHistoricalAxisValue(int, int, int) 834 * @see MotionEvent.PointerCoords#getAxisValue(int) 835 * @see InputDevice#getMotionRange 836 */ 837 public static final int AXIS_RX = 12; 838 839 /** 840 * Axis constant: Y Rotation axis of a motion event. 841 * <p> 842 * <ul> 843 * <li>For a joystick, reports the absolute rotation angle about the Y axis. 844 * The value is normalized to a range from -1.0 (counter-clockwise) to 1.0 (clockwise). 845 * </ul> 846 * </p> 847 * 848 * @see #getAxisValue(int, int) 849 * @see #getHistoricalAxisValue(int, int, int) 850 * @see MotionEvent.PointerCoords#getAxisValue(int) 851 * @see InputDevice#getMotionRange 852 */ 853 public static final int AXIS_RY = 13; 854 855 /** 856 * Axis constant: Z Rotation axis of a motion event. 857 * <p> 858 * <ul> 859 * <li>For a joystick, reports the absolute rotation angle about the Z axis. 860 * The value is normalized to a range from -1.0 (counter-clockwise) to 1.0 (clockwise). 861 * <em>On game pads with two analog joysticks, this axis is often reinterpreted 862 * to report the absolute Y position of the second joystick instead.</em> 863 * </ul> 864 * </p> 865 * 866 * @see #getAxisValue(int, int) 867 * @see #getHistoricalAxisValue(int, int, int) 868 * @see MotionEvent.PointerCoords#getAxisValue(int) 869 * @see InputDevice#getMotionRange 870 */ 871 public static final int AXIS_RZ = 14; 872 873 /** 874 * Axis constant: Hat X axis of a motion event. 875 * <p> 876 * <ul> 877 * <li>For a joystick, reports the absolute X position of the directional hat control. 878 * The value is normalized to a range from -1.0 (left) to 1.0 (right). 879 * </ul> 880 * </p> 881 * 882 * @see #getAxisValue(int, int) 883 * @see #getHistoricalAxisValue(int, int, int) 884 * @see MotionEvent.PointerCoords#getAxisValue(int) 885 * @see InputDevice#getMotionRange 886 */ 887 public static final int AXIS_HAT_X = 15; 888 889 /** 890 * Axis constant: Hat Y axis of a motion event. 891 * <p> 892 * <ul> 893 * <li>For a joystick, reports the absolute Y position of the directional hat control. 894 * The value is normalized to a range from -1.0 (up) to 1.0 (down). 895 * </ul> 896 * </p> 897 * 898 * @see #getAxisValue(int, int) 899 * @see #getHistoricalAxisValue(int, int, int) 900 * @see MotionEvent.PointerCoords#getAxisValue(int) 901 * @see InputDevice#getMotionRange 902 */ 903 public static final int AXIS_HAT_Y = 16; 904 905 /** 906 * Axis constant: Left Trigger axis of a motion event. 907 * <p> 908 * <ul> 909 * <li>For a joystick, reports the absolute position of the left trigger control. 910 * The value is normalized to a range from 0.0 (released) to 1.0 (fully pressed). 911 * </ul> 912 * </p> 913 * 914 * @see #getAxisValue(int, int) 915 * @see #getHistoricalAxisValue(int, int, int) 916 * @see MotionEvent.PointerCoords#getAxisValue(int) 917 * @see InputDevice#getMotionRange 918 */ 919 public static final int AXIS_LTRIGGER = 17; 920 921 /** 922 * Axis constant: Right Trigger axis of a motion event. 923 * <p> 924 * <ul> 925 * <li>For a joystick, reports the absolute position of the right trigger control. 926 * The value is normalized to a range from 0.0 (released) to 1.0 (fully pressed). 927 * </ul> 928 * </p> 929 * 930 * @see #getAxisValue(int, int) 931 * @see #getHistoricalAxisValue(int, int, int) 932 * @see MotionEvent.PointerCoords#getAxisValue(int) 933 * @see InputDevice#getMotionRange 934 */ 935 public static final int AXIS_RTRIGGER = 18; 936 937 /** 938 * Axis constant: Throttle axis of a motion event. 939 * <p> 940 * <ul> 941 * <li>For a joystick, reports the absolute position of the throttle control. 942 * The value is normalized to a range from 0.0 (fully open) to 1.0 (fully closed). 943 * </ul> 944 * </p> 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_THROTTLE = 19; 952 953 /** 954 * Axis constant: Rudder axis of a motion event. 955 * <p> 956 * <ul> 957 * <li>For a joystick, reports the absolute position of the rudder control. 958 * The value is normalized to a range from -1.0 (turn left) to 1.0 (turn right). 959 * </ul> 960 * </p> 961 * 962 * @see #getAxisValue(int, int) 963 * @see #getHistoricalAxisValue(int, int, int) 964 * @see MotionEvent.PointerCoords#getAxisValue(int) 965 * @see InputDevice#getMotionRange 966 */ 967 public static final int AXIS_RUDDER = 20; 968 969 /** 970 * Axis constant: Wheel axis of a motion event. 971 * <p> 972 * <ul> 973 * <li>For a joystick, reports the absolute position of the steering wheel control. 974 * The value is normalized to a range from -1.0 (turn left) to 1.0 (turn right). 975 * </ul> 976 * </p> 977 * 978 * @see #getAxisValue(int, int) 979 * @see #getHistoricalAxisValue(int, int, int) 980 * @see MotionEvent.PointerCoords#getAxisValue(int) 981 * @see InputDevice#getMotionRange 982 */ 983 public static final int AXIS_WHEEL = 21; 984 985 /** 986 * Axis constant: Gas axis of a motion event. 987 * <p> 988 * <ul> 989 * <li>For a joystick, reports the absolute position of the gas (accelerator) control. 990 * The value is normalized to a range from 0.0 (no acceleration) 991 * to 1.0 (maximum acceleration). 992 * </ul> 993 * </p> 994 * 995 * @see #getAxisValue(int, int) 996 * @see #getHistoricalAxisValue(int, int, int) 997 * @see MotionEvent.PointerCoords#getAxisValue(int) 998 * @see InputDevice#getMotionRange 999 */ 1000 public static final int AXIS_GAS = 22; 1001 1002 /** 1003 * Axis constant: Brake axis of a motion event. 1004 * <p> 1005 * <ul> 1006 * <li>For a joystick, reports the absolute position of the brake control. 1007 * The value is normalized to a range from 0.0 (no braking) to 1.0 (maximum braking). 1008 * </ul> 1009 * </p> 1010 * 1011 * @see #getAxisValue(int, int) 1012 * @see #getHistoricalAxisValue(int, int, int) 1013 * @see MotionEvent.PointerCoords#getAxisValue(int) 1014 * @see InputDevice#getMotionRange 1015 */ 1016 public static final int AXIS_BRAKE = 23; 1017 1018 /** 1019 * Axis constant: Distance axis of a motion event. 1020 * <p> 1021 * <ul> 1022 * <li>For a stylus, reports the distance of the stylus from the screen. 1023 * A value of 0.0 indicates direct contact and larger values indicate increasing 1024 * distance from the surface. 1025 * </ul> 1026 * </p> 1027 * 1028 * @see #getAxisValue(int, int) 1029 * @see #getHistoricalAxisValue(int, int, int) 1030 * @see MotionEvent.PointerCoords#getAxisValue(int) 1031 * @see InputDevice#getMotionRange 1032 */ 1033 public static final int AXIS_DISTANCE = 24; 1034 1035 /** 1036 * Axis constant: Tilt axis of a motion event. 1037 * <p> 1038 * <ul> 1039 * <li>For a stylus, reports the tilt angle of the stylus in radians where 1040 * 0 radians indicates that the stylus is being held perpendicular to the 1041 * surface, and PI/2 radians indicates that the stylus is being held flat 1042 * against the surface. 1043 * </ul> 1044 * </p> 1045 * 1046 * @see #getAxisValue(int, int) 1047 * @see #getHistoricalAxisValue(int, int, int) 1048 * @see MotionEvent.PointerCoords#getAxisValue(int, int) 1049 * @see InputDevice#getMotionRange 1050 */ 1051 public static final int AXIS_TILT = 25; 1052 1053 /** 1054 * Axis constant: Generic scroll axis of a motion event. 1055 * <p> 1056 * <ul> 1057 * <li>Reports the relative movement of the generic scrolling device. 1058 * </ul> 1059 * </p><p> 1060 * This axis should be used for scroll events that are neither strictly vertical nor horizontal. 1061 * A good example would be the rotation of a rotary encoder input device. 1062 * </p> 1063 * 1064 * @see #getAxisValue(int, int) 1065 */ 1066 public static final int AXIS_SCROLL = 26; 1067 1068 /** 1069 * Axis constant: The movement of x position of a motion event. 1070 * <p> 1071 * <ul> 1072 * <li>For a mouse, reports a difference of x position between the previous position. 1073 * This is useful when pointer is captured, in that case the mouse pointer doesn't change 1074 * the location but this axis reports the difference which allows the app to see 1075 * how the mouse is moved. 1076 * </ul> 1077 * </p> 1078 * 1079 * @see #getAxisValue(int, int) 1080 * @see #getHistoricalAxisValue(int, int, int) 1081 * @see MotionEvent.PointerCoords#getAxisValue(int, int) 1082 * @see InputDevice#getMotionRange 1083 */ 1084 public static final int AXIS_RELATIVE_X = 27; 1085 1086 /** 1087 * Axis constant: The movement of y position of a motion event. 1088 * <p> 1089 * This is similar to {@link #AXIS_RELATIVE_X} but for y-axis. 1090 * </p> 1091 * 1092 * @see #getAxisValue(int, int) 1093 * @see #getHistoricalAxisValue(int, int, int) 1094 * @see MotionEvent.PointerCoords#getAxisValue(int, int) 1095 * @see InputDevice#getMotionRange 1096 */ 1097 public static final int AXIS_RELATIVE_Y = 28; 1098 1099 /** 1100 * Axis constant: Generic 1 axis of a motion event. 1101 * The interpretation of a generic axis is device-specific. 1102 * 1103 * @see #getAxisValue(int, int) 1104 * @see #getHistoricalAxisValue(int, int, int) 1105 * @see MotionEvent.PointerCoords#getAxisValue(int) 1106 * @see InputDevice#getMotionRange 1107 */ 1108 public static final int AXIS_GENERIC_1 = 32; 1109 1110 /** 1111 * Axis constant: Generic 2 axis of a motion event. 1112 * The interpretation of a generic axis is device-specific. 1113 * 1114 * @see #getAxisValue(int, int) 1115 * @see #getHistoricalAxisValue(int, int, int) 1116 * @see MotionEvent.PointerCoords#getAxisValue(int) 1117 * @see InputDevice#getMotionRange 1118 */ 1119 public static final int AXIS_GENERIC_2 = 33; 1120 1121 /** 1122 * Axis constant: Generic 3 axis of a motion event. 1123 * The interpretation of a generic axis is device-specific. 1124 * 1125 * @see #getAxisValue(int, int) 1126 * @see #getHistoricalAxisValue(int, int, int) 1127 * @see MotionEvent.PointerCoords#getAxisValue(int) 1128 * @see InputDevice#getMotionRange 1129 */ 1130 public static final int AXIS_GENERIC_3 = 34; 1131 1132 /** 1133 * Axis constant: Generic 4 axis of a motion event. 1134 * The interpretation of a generic axis is device-specific. 1135 * 1136 * @see #getAxisValue(int, int) 1137 * @see #getHistoricalAxisValue(int, int, int) 1138 * @see MotionEvent.PointerCoords#getAxisValue(int) 1139 * @see InputDevice#getMotionRange 1140 */ 1141 public static final int AXIS_GENERIC_4 = 35; 1142 1143 /** 1144 * Axis constant: Generic 5 axis of a motion event. 1145 * The interpretation of a generic axis is device-specific. 1146 * 1147 * @see #getAxisValue(int, int) 1148 * @see #getHistoricalAxisValue(int, int, int) 1149 * @see MotionEvent.PointerCoords#getAxisValue(int) 1150 * @see InputDevice#getMotionRange 1151 */ 1152 public static final int AXIS_GENERIC_5 = 36; 1153 1154 /** 1155 * Axis constant: Generic 6 axis of a motion event. 1156 * The interpretation of a generic axis is device-specific. 1157 * 1158 * @see #getAxisValue(int, int) 1159 * @see #getHistoricalAxisValue(int, int, int) 1160 * @see MotionEvent.PointerCoords#getAxisValue(int) 1161 * @see InputDevice#getMotionRange 1162 */ 1163 public static final int AXIS_GENERIC_6 = 37; 1164 1165 /** 1166 * Axis constant: Generic 7 axis of a motion event. 1167 * The interpretation of a generic axis is device-specific. 1168 * 1169 * @see #getAxisValue(int, int) 1170 * @see #getHistoricalAxisValue(int, int, int) 1171 * @see MotionEvent.PointerCoords#getAxisValue(int) 1172 * @see InputDevice#getMotionRange 1173 */ 1174 public static final int AXIS_GENERIC_7 = 38; 1175 1176 /** 1177 * Axis constant: Generic 8 axis of a motion event. 1178 * The interpretation of a generic axis is device-specific. 1179 * 1180 * @see #getAxisValue(int, int) 1181 * @see #getHistoricalAxisValue(int, int, int) 1182 * @see MotionEvent.PointerCoords#getAxisValue(int) 1183 * @see InputDevice#getMotionRange 1184 */ 1185 public static final int AXIS_GENERIC_8 = 39; 1186 1187 /** 1188 * Axis constant: Generic 9 axis of a motion event. 1189 * The interpretation of a generic axis is device-specific. 1190 * 1191 * @see #getAxisValue(int, int) 1192 * @see #getHistoricalAxisValue(int, int, int) 1193 * @see MotionEvent.PointerCoords#getAxisValue(int) 1194 * @see InputDevice#getMotionRange 1195 */ 1196 public static final int AXIS_GENERIC_9 = 40; 1197 1198 /** 1199 * Axis constant: Generic 10 axis of a motion event. 1200 * The interpretation of a generic axis is device-specific. 1201 * 1202 * @see #getAxisValue(int, int) 1203 * @see #getHistoricalAxisValue(int, int, int) 1204 * @see MotionEvent.PointerCoords#getAxisValue(int) 1205 * @see InputDevice#getMotionRange 1206 */ 1207 public static final int AXIS_GENERIC_10 = 41; 1208 1209 /** 1210 * Axis constant: Generic 11 axis of a motion event. 1211 * The interpretation of a generic axis is device-specific. 1212 * 1213 * @see #getAxisValue(int, int) 1214 * @see #getHistoricalAxisValue(int, int, int) 1215 * @see MotionEvent.PointerCoords#getAxisValue(int) 1216 * @see InputDevice#getMotionRange 1217 */ 1218 public static final int AXIS_GENERIC_11 = 42; 1219 1220 /** 1221 * Axis constant: Generic 12 axis of a motion event. 1222 * The interpretation of a generic axis is device-specific. 1223 * 1224 * @see #getAxisValue(int, int) 1225 * @see #getHistoricalAxisValue(int, int, int) 1226 * @see MotionEvent.PointerCoords#getAxisValue(int) 1227 * @see InputDevice#getMotionRange 1228 */ 1229 public static final int AXIS_GENERIC_12 = 43; 1230 1231 /** 1232 * Axis constant: Generic 13 axis of a motion event. 1233 * The interpretation of a generic axis is device-specific. 1234 * 1235 * @see #getAxisValue(int, int) 1236 * @see #getHistoricalAxisValue(int, int, int) 1237 * @see MotionEvent.PointerCoords#getAxisValue(int) 1238 * @see InputDevice#getMotionRange 1239 */ 1240 public static final int AXIS_GENERIC_13 = 44; 1241 1242 /** 1243 * Axis constant: Generic 14 axis of a motion event. 1244 * The interpretation of a generic axis is device-specific. 1245 * 1246 * @see #getAxisValue(int, int) 1247 * @see #getHistoricalAxisValue(int, int, int) 1248 * @see MotionEvent.PointerCoords#getAxisValue(int) 1249 * @see InputDevice#getMotionRange 1250 */ 1251 public static final int AXIS_GENERIC_14 = 45; 1252 1253 /** 1254 * Axis constant: Generic 15 axis of a motion event. 1255 * The interpretation of a generic axis is device-specific. 1256 * 1257 * @see #getAxisValue(int, int) 1258 * @see #getHistoricalAxisValue(int, int, int) 1259 * @see MotionEvent.PointerCoords#getAxisValue(int) 1260 * @see InputDevice#getMotionRange 1261 */ 1262 public static final int AXIS_GENERIC_15 = 46; 1263 1264 /** 1265 * Axis constant: Generic 16 axis of a motion event. 1266 * The interpretation of a generic axis is device-specific. 1267 * 1268 * @see #getAxisValue(int, int) 1269 * @see #getHistoricalAxisValue(int, int, int) 1270 * @see MotionEvent.PointerCoords#getAxisValue(int) 1271 * @see InputDevice#getMotionRange 1272 */ 1273 public static final int AXIS_GENERIC_16 = 47; 1274 1275 // NOTE: If you add a new axis here you must also add it to: 1276 // native/include/android/input.h 1277 // frameworks/base/include/ui/KeycodeLabels.h 1278 1279 // Symbolic names of all axes. 1280 private static final SparseArray<String> AXIS_SYMBOLIC_NAMES = new SparseArray<String>(); 1281 static { 1282 SparseArray<String> names = AXIS_SYMBOLIC_NAMES; names.append(AXIS_X, "AXIS_X")1283 names.append(AXIS_X, "AXIS_X"); names.append(AXIS_Y, "AXIS_Y")1284 names.append(AXIS_Y, "AXIS_Y"); names.append(AXIS_PRESSURE, "AXIS_PRESSURE")1285 names.append(AXIS_PRESSURE, "AXIS_PRESSURE"); names.append(AXIS_SIZE, "AXIS_SIZE")1286 names.append(AXIS_SIZE, "AXIS_SIZE"); names.append(AXIS_TOUCH_MAJOR, "AXIS_TOUCH_MAJOR")1287 names.append(AXIS_TOUCH_MAJOR, "AXIS_TOUCH_MAJOR"); names.append(AXIS_TOUCH_MINOR, "AXIS_TOUCH_MINOR")1288 names.append(AXIS_TOUCH_MINOR, "AXIS_TOUCH_MINOR"); names.append(AXIS_TOOL_MAJOR, "AXIS_TOOL_MAJOR")1289 names.append(AXIS_TOOL_MAJOR, "AXIS_TOOL_MAJOR"); names.append(AXIS_TOOL_MINOR, "AXIS_TOOL_MINOR")1290 names.append(AXIS_TOOL_MINOR, "AXIS_TOOL_MINOR"); names.append(AXIS_ORIENTATION, "AXIS_ORIENTATION")1291 names.append(AXIS_ORIENTATION, "AXIS_ORIENTATION"); names.append(AXIS_VSCROLL, "AXIS_VSCROLL")1292 names.append(AXIS_VSCROLL, "AXIS_VSCROLL"); names.append(AXIS_HSCROLL, "AXIS_HSCROLL")1293 names.append(AXIS_HSCROLL, "AXIS_HSCROLL"); names.append(AXIS_Z, "AXIS_Z")1294 names.append(AXIS_Z, "AXIS_Z"); names.append(AXIS_RX, "AXIS_RX")1295 names.append(AXIS_RX, "AXIS_RX"); names.append(AXIS_RY, "AXIS_RY")1296 names.append(AXIS_RY, "AXIS_RY"); names.append(AXIS_RZ, "AXIS_RZ")1297 names.append(AXIS_RZ, "AXIS_RZ"); names.append(AXIS_HAT_X, "AXIS_HAT_X")1298 names.append(AXIS_HAT_X, "AXIS_HAT_X"); names.append(AXIS_HAT_Y, "AXIS_HAT_Y")1299 names.append(AXIS_HAT_Y, "AXIS_HAT_Y"); names.append(AXIS_LTRIGGER, "AXIS_LTRIGGER")1300 names.append(AXIS_LTRIGGER, "AXIS_LTRIGGER"); names.append(AXIS_RTRIGGER, "AXIS_RTRIGGER")1301 names.append(AXIS_RTRIGGER, "AXIS_RTRIGGER"); names.append(AXIS_THROTTLE, "AXIS_THROTTLE")1302 names.append(AXIS_THROTTLE, "AXIS_THROTTLE"); names.append(AXIS_RUDDER, "AXIS_RUDDER")1303 names.append(AXIS_RUDDER, "AXIS_RUDDER"); names.append(AXIS_WHEEL, "AXIS_WHEEL")1304 names.append(AXIS_WHEEL, "AXIS_WHEEL"); names.append(AXIS_GAS, "AXIS_GAS")1305 names.append(AXIS_GAS, "AXIS_GAS"); names.append(AXIS_BRAKE, "AXIS_BRAKE")1306 names.append(AXIS_BRAKE, "AXIS_BRAKE"); names.append(AXIS_DISTANCE, "AXIS_DISTANCE")1307 names.append(AXIS_DISTANCE, "AXIS_DISTANCE"); names.append(AXIS_TILT, "AXIS_TILT")1308 names.append(AXIS_TILT, "AXIS_TILT"); names.append(AXIS_SCROLL, "AXIS_SCROLL")1309 names.append(AXIS_SCROLL, "AXIS_SCROLL"); names.append(AXIS_RELATIVE_X, "AXIS_REALTIVE_X")1310 names.append(AXIS_RELATIVE_X, "AXIS_REALTIVE_X"); names.append(AXIS_RELATIVE_Y, "AXIS_REALTIVE_Y")1311 names.append(AXIS_RELATIVE_Y, "AXIS_REALTIVE_Y"); names.append(AXIS_GENERIC_1, "AXIS_GENERIC_1")1312 names.append(AXIS_GENERIC_1, "AXIS_GENERIC_1"); names.append(AXIS_GENERIC_2, "AXIS_GENERIC_2")1313 names.append(AXIS_GENERIC_2, "AXIS_GENERIC_2"); names.append(AXIS_GENERIC_3, "AXIS_GENERIC_3")1314 names.append(AXIS_GENERIC_3, "AXIS_GENERIC_3"); names.append(AXIS_GENERIC_4, "AXIS_GENERIC_4")1315 names.append(AXIS_GENERIC_4, "AXIS_GENERIC_4"); names.append(AXIS_GENERIC_5, "AXIS_GENERIC_5")1316 names.append(AXIS_GENERIC_5, "AXIS_GENERIC_5"); names.append(AXIS_GENERIC_6, "AXIS_GENERIC_6")1317 names.append(AXIS_GENERIC_6, "AXIS_GENERIC_6"); names.append(AXIS_GENERIC_7, "AXIS_GENERIC_7")1318 names.append(AXIS_GENERIC_7, "AXIS_GENERIC_7"); names.append(AXIS_GENERIC_8, "AXIS_GENERIC_8")1319 names.append(AXIS_GENERIC_8, "AXIS_GENERIC_8"); names.append(AXIS_GENERIC_9, "AXIS_GENERIC_9")1320 names.append(AXIS_GENERIC_9, "AXIS_GENERIC_9"); names.append(AXIS_GENERIC_10, "AXIS_GENERIC_10")1321 names.append(AXIS_GENERIC_10, "AXIS_GENERIC_10"); names.append(AXIS_GENERIC_11, "AXIS_GENERIC_11")1322 names.append(AXIS_GENERIC_11, "AXIS_GENERIC_11"); names.append(AXIS_GENERIC_12, "AXIS_GENERIC_12")1323 names.append(AXIS_GENERIC_12, "AXIS_GENERIC_12"); names.append(AXIS_GENERIC_13, "AXIS_GENERIC_13")1324 names.append(AXIS_GENERIC_13, "AXIS_GENERIC_13"); names.append(AXIS_GENERIC_14, "AXIS_GENERIC_14")1325 names.append(AXIS_GENERIC_14, "AXIS_GENERIC_14"); names.append(AXIS_GENERIC_15, "AXIS_GENERIC_15")1326 names.append(AXIS_GENERIC_15, "AXIS_GENERIC_15"); names.append(AXIS_GENERIC_16, "AXIS_GENERIC_16")1327 names.append(AXIS_GENERIC_16, "AXIS_GENERIC_16"); 1328 } 1329 1330 /** 1331 * Button constant: Primary button (left mouse button). 1332 * 1333 * This button constant is not set in response to simple touches with a finger 1334 * or stylus tip. The user must actually push a button. 1335 * 1336 * @see #getButtonState 1337 */ 1338 public static final int BUTTON_PRIMARY = 1 << 0; 1339 1340 /** 1341 * Button constant: Secondary button (right mouse button). 1342 * 1343 * @see #getButtonState 1344 */ 1345 public static final int BUTTON_SECONDARY = 1 << 1; 1346 1347 /** 1348 * Button constant: Tertiary button (middle mouse button). 1349 * 1350 * @see #getButtonState 1351 */ 1352 public static final int BUTTON_TERTIARY = 1 << 2; 1353 1354 /** 1355 * Button constant: Back button pressed (mouse back button). 1356 * <p> 1357 * The system may send a {@link KeyEvent#KEYCODE_BACK} key press to the application 1358 * when this button is pressed. 1359 * </p> 1360 * 1361 * @see #getButtonState 1362 */ 1363 public static final int BUTTON_BACK = 1 << 3; 1364 1365 /** 1366 * Button constant: Forward button pressed (mouse forward button). 1367 * <p> 1368 * The system may send a {@link KeyEvent#KEYCODE_FORWARD} key press to the application 1369 * when this button is pressed. 1370 * </p> 1371 * 1372 * @see #getButtonState 1373 */ 1374 public static final int BUTTON_FORWARD = 1 << 4; 1375 1376 /** 1377 * Button constant: Primary stylus button pressed. 1378 * 1379 * @see #getButtonState 1380 */ 1381 public static final int BUTTON_STYLUS_PRIMARY = 1 << 5; 1382 1383 /** 1384 * Button constant: Secondary stylus button pressed. 1385 * 1386 * @see #getButtonState 1387 */ 1388 public static final int BUTTON_STYLUS_SECONDARY = 1 << 6; 1389 1390 // NOTE: If you add a new axis here you must also add it to: 1391 // native/include/android/input.h 1392 1393 // Symbolic names of all button states in bit order from least significant 1394 // to most significant. 1395 private static final String[] BUTTON_SYMBOLIC_NAMES = new String[] { 1396 "BUTTON_PRIMARY", 1397 "BUTTON_SECONDARY", 1398 "BUTTON_TERTIARY", 1399 "BUTTON_BACK", 1400 "BUTTON_FORWARD", 1401 "BUTTON_STYLUS_PRIMARY", 1402 "BUTTON_STYLUS_SECONDARY", 1403 "0x00000080", 1404 "0x00000100", 1405 "0x00000200", 1406 "0x00000400", 1407 "0x00000800", 1408 "0x00001000", 1409 "0x00002000", 1410 "0x00004000", 1411 "0x00008000", 1412 "0x00010000", 1413 "0x00020000", 1414 "0x00040000", 1415 "0x00080000", 1416 "0x00100000", 1417 "0x00200000", 1418 "0x00400000", 1419 "0x00800000", 1420 "0x01000000", 1421 "0x02000000", 1422 "0x04000000", 1423 "0x08000000", 1424 "0x10000000", 1425 "0x20000000", 1426 "0x40000000", 1427 "0x80000000", 1428 }; 1429 1430 /** 1431 * Classification constant: None. 1432 * 1433 * No additional information is available about the current motion event stream. 1434 * 1435 * @see #getClassification 1436 */ 1437 public static final int CLASSIFICATION_NONE = 0; 1438 1439 /** 1440 * Classification constant: Ambiguous gesture. 1441 * 1442 * The user's intent with respect to the current event stream is not yet determined. 1443 * Gestural actions, such as scrolling, should be inhibited until the classification resolves 1444 * to another value or the event stream ends. 1445 * 1446 * @see #getClassification 1447 */ 1448 public static final int CLASSIFICATION_AMBIGUOUS_GESTURE = 1; 1449 1450 /** 1451 * Classification constant: Deep press. 1452 * 1453 * The current event stream represents the user intentionally pressing harder on the screen. 1454 * This classification type should be used to accelerate the long press behaviour. 1455 * 1456 * @see #getClassification 1457 */ 1458 public static final int CLASSIFICATION_DEEP_PRESS = 2; 1459 1460 /** @hide */ 1461 @Retention(SOURCE) 1462 @IntDef(prefix = { "CLASSIFICATION" }, value = { 1463 CLASSIFICATION_NONE, CLASSIFICATION_AMBIGUOUS_GESTURE, CLASSIFICATION_DEEP_PRESS}) 1464 public @interface Classification {}; 1465 1466 /** 1467 * Tool type constant: Unknown tool type. 1468 * This constant is used when the tool type is not known or is not relevant, 1469 * such as for a trackball or other non-pointing device. 1470 * 1471 * @see #getToolType 1472 */ 1473 public static final int TOOL_TYPE_UNKNOWN = 0; 1474 1475 /** 1476 * Tool type constant: The tool is a finger. 1477 * 1478 * @see #getToolType 1479 */ 1480 public static final int TOOL_TYPE_FINGER = 1; 1481 1482 /** 1483 * Tool type constant: The tool is a stylus. 1484 * 1485 * @see #getToolType 1486 */ 1487 public static final int TOOL_TYPE_STYLUS = 2; 1488 1489 /** 1490 * Tool type constant: The tool is a mouse. 1491 * 1492 * @see #getToolType 1493 */ 1494 public static final int TOOL_TYPE_MOUSE = 3; 1495 1496 /** 1497 * Tool type constant: The tool is an eraser or a stylus being used in an inverted posture. 1498 * 1499 * @see #getToolType 1500 */ 1501 public static final int TOOL_TYPE_ERASER = 4; 1502 1503 /** 1504 * Tool type constant: The tool is a palm and should be rejected. 1505 * 1506 * @see #getToolType 1507 * 1508 * @hide 1509 */ 1510 public static final int TOOL_TYPE_PALM = 5; 1511 1512 // NOTE: If you add a new tool type here you must also add it to: 1513 // native/include/android/input.h 1514 1515 // Symbolic names of all tool types. 1516 private static final SparseArray<String> TOOL_TYPE_SYMBOLIC_NAMES = new SparseArray<String>(); 1517 static { 1518 SparseArray<String> names = TOOL_TYPE_SYMBOLIC_NAMES; names.append(TOOL_TYPE_UNKNOWN, "TOOL_TYPE_UNKNOWN")1519 names.append(TOOL_TYPE_UNKNOWN, "TOOL_TYPE_UNKNOWN"); names.append(TOOL_TYPE_FINGER, "TOOL_TYPE_FINGER")1520 names.append(TOOL_TYPE_FINGER, "TOOL_TYPE_FINGER"); names.append(TOOL_TYPE_STYLUS, "TOOL_TYPE_STYLUS")1521 names.append(TOOL_TYPE_STYLUS, "TOOL_TYPE_STYLUS"); names.append(TOOL_TYPE_MOUSE, "TOOL_TYPE_MOUSE")1522 names.append(TOOL_TYPE_MOUSE, "TOOL_TYPE_MOUSE"); names.append(TOOL_TYPE_ERASER, "TOOL_TYPE_ERASER")1523 names.append(TOOL_TYPE_ERASER, "TOOL_TYPE_ERASER"); 1524 } 1525 1526 // Private value for history pos that obtains the current sample. 1527 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) 1528 private static final int HISTORY_CURRENT = -0x80000000; 1529 1530 // This is essentially the same as native AMOTION_EVENT_INVALID_CURSOR_POSITION as they're all 1531 // NaN and we use isnan() everywhere to check validity. 1532 private static final float INVALID_CURSOR_POSITION = Float.NaN; 1533 1534 private static final int MAX_RECYCLED = 10; 1535 private static final Object gRecyclerLock = new Object(); 1536 private static int gRecyclerUsed; 1537 private static MotionEvent gRecyclerTop; 1538 1539 // Shared temporary objects used when translating coordinates supplied by 1540 // the caller into single element PointerCoords and pointer id arrays. 1541 private static final Object gSharedTempLock = new Object(); 1542 private static PointerCoords[] gSharedTempPointerCoords; 1543 private static PointerProperties[] gSharedTempPointerProperties; 1544 private static int[] gSharedTempPointerIndexMap; 1545 ensureSharedTempPointerCapacity(int desiredCapacity)1546 private static final void ensureSharedTempPointerCapacity(int desiredCapacity) { 1547 if (gSharedTempPointerCoords == null 1548 || gSharedTempPointerCoords.length < desiredCapacity) { 1549 int capacity = gSharedTempPointerCoords != null ? gSharedTempPointerCoords.length : 8; 1550 while (capacity < desiredCapacity) { 1551 capacity *= 2; 1552 } 1553 gSharedTempPointerCoords = PointerCoords.createArray(capacity); 1554 gSharedTempPointerProperties = PointerProperties.createArray(capacity); 1555 gSharedTempPointerIndexMap = new int[capacity]; 1556 } 1557 } 1558 1559 // Pointer to the native MotionEvent object that contains the actual data. 1560 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.P) 1561 private long mNativePtr; 1562 1563 private MotionEvent mNext; 1564 nativeInitialize(long nativePtr, int deviceId, int source, int displayId, int action, int flags, int edgeFlags, int metaState, int buttonState, @Classification int classification, float xOffset, float yOffset, float xPrecision, float yPrecision, long downTimeNanos, long eventTimeNanos, int pointerCount, PointerProperties[] pointerIds, PointerCoords[] pointerCoords)1565 private static native long nativeInitialize(long nativePtr, 1566 int deviceId, int source, int displayId, int action, int flags, int edgeFlags, 1567 int metaState, int buttonState, @Classification int classification, 1568 float xOffset, float yOffset, float xPrecision, float yPrecision, 1569 long downTimeNanos, long eventTimeNanos, 1570 int pointerCount, PointerProperties[] pointerIds, PointerCoords[] pointerCoords); nativeDispose(long nativePtr)1571 private static native void nativeDispose(long nativePtr); nativeAddBatch(long nativePtr, long eventTimeNanos, PointerCoords[] pointerCoords, int metaState)1572 private static native void nativeAddBatch(long nativePtr, long eventTimeNanos, 1573 PointerCoords[] pointerCoords, int metaState); nativeGetPointerCoords(long nativePtr, int pointerIndex, int historyPos, PointerCoords outPointerCoords)1574 private static native void nativeGetPointerCoords(long nativePtr, 1575 int pointerIndex, int historyPos, PointerCoords outPointerCoords); nativeGetPointerProperties(long nativePtr, int pointerIndex, PointerProperties outPointerProperties)1576 private static native void nativeGetPointerProperties(long nativePtr, 1577 int pointerIndex, PointerProperties outPointerProperties); 1578 nativeReadFromParcel(long nativePtr, Parcel parcel)1579 private static native long nativeReadFromParcel(long nativePtr, Parcel parcel); nativeWriteToParcel(long nativePtr, Parcel parcel)1580 private static native void nativeWriteToParcel(long nativePtr, Parcel parcel); 1581 nativeAxisToString(int axis)1582 private static native String nativeAxisToString(int axis); nativeAxisFromString(String label)1583 private static native int nativeAxisFromString(String label); 1584 1585 // -------------- @FastNative ------------------------- 1586 1587 @FastNative nativeGetPointerId(long nativePtr, int pointerIndex)1588 private static native int nativeGetPointerId(long nativePtr, int pointerIndex); 1589 @FastNative nativeGetToolType(long nativePtr, int pointerIndex)1590 private static native int nativeGetToolType(long nativePtr, int pointerIndex); 1591 @FastNative nativeGetEventTimeNanos(long nativePtr, int historyPos)1592 private static native long nativeGetEventTimeNanos(long nativePtr, int historyPos); 1593 @FastNative 1594 @UnsupportedAppUsage nativeGetRawAxisValue(long nativePtr, int axis, int pointerIndex, int historyPos)1595 private static native float nativeGetRawAxisValue(long nativePtr, 1596 int axis, int pointerIndex, int historyPos); 1597 @FastNative nativeGetAxisValue(long nativePtr, int axis, int pointerIndex, int historyPos)1598 private static native float nativeGetAxisValue(long nativePtr, 1599 int axis, int pointerIndex, int historyPos); 1600 @FastNative nativeTransform(long nativePtr, Matrix matrix)1601 private static native void nativeTransform(long nativePtr, Matrix matrix); 1602 @FastNative nativeApplyTransform(long nativePtr, Matrix matrix)1603 private static native void nativeApplyTransform(long nativePtr, Matrix matrix); 1604 1605 // -------------- @CriticalNative ---------------------- 1606 1607 @CriticalNative nativeCopy(long destNativePtr, long sourceNativePtr, boolean keepHistory)1608 private static native long nativeCopy(long destNativePtr, long sourceNativePtr, 1609 boolean keepHistory); 1610 @CriticalNative nativeGetId(long nativePtr)1611 private static native int nativeGetId(long nativePtr); 1612 @CriticalNative nativeGetDeviceId(long nativePtr)1613 private static native int nativeGetDeviceId(long nativePtr); 1614 @CriticalNative nativeGetSource(long nativePtr)1615 private static native int nativeGetSource(long nativePtr); 1616 @CriticalNative nativeSetSource(long nativePtr, int source)1617 private static native void nativeSetSource(long nativePtr, int source); 1618 @CriticalNative nativeGetDisplayId(long nativePtr)1619 private static native int nativeGetDisplayId(long nativePtr); 1620 @CriticalNative nativeSetDisplayId(long nativePtr, int displayId)1621 private static native void nativeSetDisplayId(long nativePtr, int displayId); 1622 @CriticalNative nativeGetAction(long nativePtr)1623 private static native int nativeGetAction(long nativePtr); 1624 @CriticalNative nativeSetAction(long nativePtr, int action)1625 private static native void nativeSetAction(long nativePtr, int action); 1626 @CriticalNative nativeIsTouchEvent(long nativePtr)1627 private static native boolean nativeIsTouchEvent(long nativePtr); 1628 @CriticalNative nativeGetFlags(long nativePtr)1629 private static native int nativeGetFlags(long nativePtr); 1630 @CriticalNative nativeSetFlags(long nativePtr, int flags)1631 private static native void nativeSetFlags(long nativePtr, int flags); 1632 @CriticalNative nativeGetEdgeFlags(long nativePtr)1633 private static native int nativeGetEdgeFlags(long nativePtr); 1634 @CriticalNative nativeSetEdgeFlags(long nativePtr, int action)1635 private static native void nativeSetEdgeFlags(long nativePtr, int action); 1636 @CriticalNative nativeGetMetaState(long nativePtr)1637 private static native int nativeGetMetaState(long nativePtr); 1638 @CriticalNative nativeGetButtonState(long nativePtr)1639 private static native int nativeGetButtonState(long nativePtr); 1640 @CriticalNative nativeSetButtonState(long nativePtr, int buttonState)1641 private static native void nativeSetButtonState(long nativePtr, int buttonState); 1642 @CriticalNative nativeGetClassification(long nativePtr)1643 private static native int nativeGetClassification(long nativePtr); 1644 @CriticalNative nativeGetActionButton(long nativePtr)1645 private static native int nativeGetActionButton(long nativePtr); 1646 @CriticalNative nativeSetActionButton(long nativePtr, int actionButton)1647 private static native void nativeSetActionButton(long nativePtr, int actionButton); 1648 @CriticalNative nativeOffsetLocation(long nativePtr, float deltaX, float deltaY)1649 private static native void nativeOffsetLocation(long nativePtr, float deltaX, float deltaY); 1650 @CriticalNative nativeGetXOffset(long nativePtr)1651 private static native float nativeGetXOffset(long nativePtr); 1652 @CriticalNative nativeGetYOffset(long nativePtr)1653 private static native float nativeGetYOffset(long nativePtr); 1654 @CriticalNative nativeGetXPrecision(long nativePtr)1655 private static native float nativeGetXPrecision(long nativePtr); 1656 @CriticalNative nativeGetYPrecision(long nativePtr)1657 private static native float nativeGetYPrecision(long nativePtr); 1658 @CriticalNative nativeGetXCursorPosition(long nativePtr)1659 private static native float nativeGetXCursorPosition(long nativePtr); 1660 @CriticalNative nativeGetYCursorPosition(long nativePtr)1661 private static native float nativeGetYCursorPosition(long nativePtr); 1662 @CriticalNative nativeSetCursorPosition(long nativePtr, float x, float y)1663 private static native void nativeSetCursorPosition(long nativePtr, float x, float y); 1664 @CriticalNative nativeGetDownTimeNanos(long nativePtr)1665 private static native long nativeGetDownTimeNanos(long nativePtr); 1666 @CriticalNative nativeSetDownTimeNanos(long nativePtr, long downTime)1667 private static native void nativeSetDownTimeNanos(long nativePtr, long downTime); 1668 1669 @CriticalNative nativeGetPointerCount(long nativePtr)1670 private static native int nativeGetPointerCount(long nativePtr); 1671 @CriticalNative nativeFindPointerIndex(long nativePtr, int pointerId)1672 private static native int nativeFindPointerIndex(long nativePtr, int pointerId); 1673 1674 @CriticalNative nativeGetHistorySize(long nativePtr)1675 private static native int nativeGetHistorySize(long nativePtr); 1676 1677 @CriticalNative nativeScale(long nativePtr, float scale)1678 private static native void nativeScale(long nativePtr, float scale); 1679 1680 @CriticalNative nativeGetSurfaceRotation(long nativePtr)1681 private static native int nativeGetSurfaceRotation(long nativePtr); 1682 MotionEvent()1683 private MotionEvent() { 1684 } 1685 1686 @Override finalize()1687 protected void finalize() throws Throwable { 1688 try { 1689 if (mNativePtr != 0) { 1690 nativeDispose(mNativePtr); 1691 mNativePtr = 0; 1692 } 1693 } finally { 1694 super.finalize(); 1695 } 1696 } 1697 1698 @UnsupportedAppUsage obtain()1699 static private MotionEvent obtain() { 1700 final MotionEvent ev; 1701 synchronized (gRecyclerLock) { 1702 ev = gRecyclerTop; 1703 if (ev == null) { 1704 return new MotionEvent(); 1705 } 1706 gRecyclerTop = ev.mNext; 1707 gRecyclerUsed -= 1; 1708 } 1709 ev.mNext = null; 1710 ev.prepareForReuse(); 1711 return ev; 1712 } 1713 1714 /** 1715 * Create a new MotionEvent, filling in all of the basic values that 1716 * define the motion. 1717 * 1718 * @param downTime The time (in ms) when the user originally pressed down to start 1719 * a stream of position events. This must be obtained from {@link SystemClock#uptimeMillis()}. 1720 * @param eventTime The the time (in ms) when this specific event was generated. This 1721 * must be obtained from {@link SystemClock#uptimeMillis()}. 1722 * @param action The kind of action being performed, such as {@link #ACTION_DOWN}. 1723 * @param pointerCount The number of pointers that will be in this event. 1724 * @param pointerProperties An array of <em>pointerCount</em> values providing 1725 * a {@link PointerProperties} property object for each pointer, which must 1726 * include the pointer identifier. 1727 * @param pointerCoords An array of <em>pointerCount</em> values providing 1728 * a {@link PointerCoords} coordinate object for each pointer. 1729 * @param metaState The state of any meta / modifier keys that were in effect when 1730 * the event was generated. 1731 * @param buttonState The state of buttons that are pressed. 1732 * @param xPrecision The precision of the X coordinate being reported. 1733 * @param yPrecision The precision of the Y coordinate being reported. 1734 * @param deviceId The id for the device that this event came from. An id of 1735 * zero indicates that the event didn't come from a physical device; other 1736 * numbers are arbitrary and you shouldn't depend on the values. 1737 * @param edgeFlags A bitfield indicating which edges, if any, were touched by this 1738 * MotionEvent. 1739 * @param source The source of this event. 1740 * @param displayId The display ID associated with this event. 1741 * @param flags The motion event flags. 1742 * @hide 1743 */ obtain(long downTime, long eventTime, int action, int pointerCount, PointerProperties[] pointerProperties, PointerCoords[] pointerCoords, int metaState, int buttonState, float xPrecision, float yPrecision, int deviceId, int edgeFlags, int source, int displayId, int flags)1744 static public MotionEvent obtain(long downTime, long eventTime, 1745 int action, int pointerCount, PointerProperties[] pointerProperties, 1746 PointerCoords[] pointerCoords, int metaState, int buttonState, 1747 float xPrecision, float yPrecision, int deviceId, 1748 int edgeFlags, int source, int displayId, int flags) { 1749 MotionEvent ev = obtain(); 1750 final boolean success = ev.initialize(deviceId, source, displayId, action, flags, edgeFlags, 1751 metaState, buttonState, CLASSIFICATION_NONE, 0, 0, xPrecision, yPrecision, 1752 downTime * NS_PER_MS, eventTime * NS_PER_MS, 1753 pointerCount, pointerProperties, pointerCoords); 1754 if (!success) { 1755 Log.e(TAG, "Could not initialize MotionEvent"); 1756 ev.recycle(); 1757 return null; 1758 } 1759 return ev; 1760 } 1761 1762 /** 1763 * Create a new MotionEvent, filling in all of the basic values that 1764 * define the motion. 1765 * 1766 * @param downTime The time (in ms) when the user originally pressed down to start 1767 * a stream of position events. This must be obtained from {@link SystemClock#uptimeMillis()}. 1768 * @param eventTime The the time (in ms) when this specific event was generated. This 1769 * must be obtained from {@link SystemClock#uptimeMillis()}. 1770 * @param action The kind of action being performed, such as {@link #ACTION_DOWN}. 1771 * @param pointerCount The number of pointers that will be in this event. 1772 * @param pointerProperties An array of <em>pointerCount</em> values providing 1773 * a {@link PointerProperties} property object for each pointer, which must 1774 * include the pointer identifier. 1775 * @param pointerCoords An array of <em>pointerCount</em> values providing 1776 * a {@link PointerCoords} coordinate object for each pointer. 1777 * @param metaState The state of any meta / modifier keys that were in effect when 1778 * the event was generated. 1779 * @param buttonState The state of buttons that are pressed. 1780 * @param xPrecision The precision of the X coordinate being reported. 1781 * @param yPrecision The precision of the Y coordinate being reported. 1782 * @param deviceId The id for the device that this event came from. An id of 1783 * zero indicates that the event didn't come from a physical device; other 1784 * numbers are arbitrary and you shouldn't depend on the values. 1785 * @param edgeFlags A bitfield indicating which edges, if any, were touched by this 1786 * MotionEvent. 1787 * @param source The source of this event. 1788 * @param flags The motion event flags. 1789 */ obtain(long downTime, long eventTime, int action, int pointerCount, PointerProperties[] pointerProperties, PointerCoords[] pointerCoords, int metaState, int buttonState, float xPrecision, float yPrecision, int deviceId, int edgeFlags, int source, int flags)1790 public static MotionEvent obtain(long downTime, long eventTime, 1791 int action, int pointerCount, PointerProperties[] pointerProperties, 1792 PointerCoords[] pointerCoords, int metaState, int buttonState, 1793 float xPrecision, float yPrecision, int deviceId, 1794 int edgeFlags, int source, int flags) { 1795 return obtain(downTime, eventTime, action, pointerCount, pointerProperties, pointerCoords, 1796 metaState, buttonState, xPrecision, yPrecision, deviceId, edgeFlags, source, 1797 DEFAULT_DISPLAY, flags); 1798 } 1799 1800 /** 1801 * Create a new MotionEvent, filling in all of the basic values that 1802 * define the motion. 1803 * 1804 * @param downTime The time (in ms) when the user originally pressed down to start 1805 * a stream of position events. This must be obtained from {@link SystemClock#uptimeMillis()}. 1806 * @param eventTime The the time (in ms) when this specific event was generated. This 1807 * must be obtained from {@link SystemClock#uptimeMillis()}. 1808 * @param action The kind of action being performed, such as {@link #ACTION_DOWN}. 1809 * @param pointerCount The number of pointers that will be in this event. 1810 * @param pointerIds An array of <em>pointerCount</em> values providing 1811 * an identifier for each pointer. 1812 * @param pointerCoords An array of <em>pointerCount</em> values providing 1813 * a {@link PointerCoords} coordinate object for each pointer. 1814 * @param metaState The state of any meta / modifier keys that were in effect when 1815 * the event was generated. 1816 * @param xPrecision The precision of the X coordinate being reported. 1817 * @param yPrecision The precision of the Y coordinate being reported. 1818 * @param deviceId The id for the device that this event came from. An id of 1819 * zero indicates that the event didn't come from a physical device; other 1820 * numbers are arbitrary and you shouldn't depend on the values. 1821 * @param edgeFlags A bitfield indicating which edges, if any, were touched by this 1822 * MotionEvent. 1823 * @param source The source of this event. 1824 * @param flags The motion event flags. 1825 * 1826 * @deprecated Use {@link #obtain(long, long, int, int, PointerProperties[], PointerCoords[], int, int, float, float, int, int, int, int)} 1827 * instead. 1828 */ 1829 @Deprecated obtain(long downTime, long eventTime, int action, int pointerCount, int[] pointerIds, PointerCoords[] pointerCoords, int metaState, float xPrecision, float yPrecision, int deviceId, int edgeFlags, int source, int flags)1830 static public MotionEvent obtain(long downTime, long eventTime, 1831 int action, int pointerCount, int[] pointerIds, PointerCoords[] pointerCoords, 1832 int metaState, float xPrecision, float yPrecision, int deviceId, 1833 int edgeFlags, int source, int flags) { 1834 synchronized (gSharedTempLock) { 1835 ensureSharedTempPointerCapacity(pointerCount); 1836 final PointerProperties[] pp = gSharedTempPointerProperties; 1837 for (int i = 0; i < pointerCount; i++) { 1838 pp[i].clear(); 1839 pp[i].id = pointerIds[i]; 1840 } 1841 return obtain(downTime, eventTime, action, pointerCount, pp, 1842 pointerCoords, metaState, 0, xPrecision, yPrecision, deviceId, 1843 edgeFlags, source, flags); 1844 } 1845 } 1846 1847 /** 1848 * Create a new MotionEvent, filling in all of the basic values that 1849 * define the motion. 1850 * 1851 * @param downTime The time (in ms) when the user originally pressed down to start 1852 * a stream of position events. This must be obtained from {@link SystemClock#uptimeMillis()}. 1853 * @param eventTime The the time (in ms) when this specific event was generated. This 1854 * must be obtained from {@link SystemClock#uptimeMillis()}. 1855 * @param action The kind of action being performed, such as {@link #ACTION_DOWN}. 1856 * @param x The X coordinate of this event. 1857 * @param y The Y coordinate of this event. 1858 * @param pressure The current pressure of this event. The pressure generally 1859 * ranges from 0 (no pressure at all) to 1 (normal pressure), however 1860 * values higher than 1 may be generated depending on the calibration of 1861 * the input device. 1862 * @param size A scaled value of the approximate size of the area being pressed when 1863 * touched with the finger. The actual value in pixels corresponding to the finger 1864 * touch is normalized with a device specific range of values 1865 * and scaled to a value between 0 and 1. 1866 * @param metaState The state of any meta / modifier keys that were in effect when 1867 * the event was generated. 1868 * @param xPrecision The precision of the X coordinate being reported. 1869 * @param yPrecision The precision of the Y coordinate being reported. 1870 * @param deviceId The id for the device that this event came from. An id of 1871 * zero indicates that the event didn't come from a physical device; other 1872 * numbers are arbitrary and you shouldn't depend on the values. 1873 * @param edgeFlags A bitfield indicating which edges, if any, were touched by this 1874 * MotionEvent. 1875 */ obtain(long downTime, long eventTime, int action, float x, float y, float pressure, float size, int metaState, float xPrecision, float yPrecision, int deviceId, int edgeFlags)1876 static public MotionEvent obtain(long downTime, long eventTime, int action, 1877 float x, float y, float pressure, float size, int metaState, 1878 float xPrecision, float yPrecision, int deviceId, int edgeFlags) { 1879 return obtain(downTime, eventTime, action, x, y, pressure, size, metaState, 1880 xPrecision, yPrecision, deviceId, edgeFlags, InputDevice.SOURCE_CLASS_POINTER, 1881 DEFAULT_DISPLAY); 1882 } 1883 1884 /** 1885 * Create a new MotionEvent, filling in all of the basic values that 1886 * define the motion. 1887 * 1888 * @param downTime The time (in ms) when the user originally pressed down to start 1889 * a stream of position events. This must be obtained from {@link SystemClock#uptimeMillis()}. 1890 * @param eventTime The the time (in ms) when this specific event was generated. This 1891 * must be obtained from {@link SystemClock#uptimeMillis()}. 1892 * @param action The kind of action being performed, such as {@link #ACTION_DOWN}. 1893 * @param x The X coordinate of this event. 1894 * @param y The Y coordinate of this event. 1895 * @param pressure The current pressure of this event. The pressure generally 1896 * ranges from 0 (no pressure at all) to 1 (normal pressure), however 1897 * values higher than 1 may be generated depending on the calibration of 1898 * the input device. 1899 * @param size A scaled value of the approximate size of the area being pressed when 1900 * touched with the finger. The actual value in pixels corresponding to the finger 1901 * touch is normalized with a device specific range of values 1902 * and scaled to a value between 0 and 1. 1903 * @param metaState The state of any meta / modifier keys that were in effect when 1904 * the event was generated. 1905 * @param xPrecision The precision of the X coordinate being reported. 1906 * @param yPrecision The precision of the Y coordinate being reported. 1907 * @param deviceId The id for the device that this event came from. An id of 1908 * zero indicates that the event didn't come from a physical device; other 1909 * numbers are arbitrary and you shouldn't depend on the values. 1910 * @param source The source of this event. 1911 * @param edgeFlags A bitfield indicating which edges, if any, were touched by this 1912 * MotionEvent. 1913 * @param displayId The display ID associated with this event. 1914 * @hide 1915 */ obtain(long downTime, long eventTime, int action, float x, float y, float pressure, float size, int metaState, float xPrecision, float yPrecision, int deviceId, int edgeFlags, int source, int displayId)1916 public static MotionEvent obtain(long downTime, long eventTime, int action, 1917 float x, float y, float pressure, float size, int metaState, 1918 float xPrecision, float yPrecision, int deviceId, int edgeFlags, int source, 1919 int displayId) { 1920 MotionEvent ev = obtain(); 1921 synchronized (gSharedTempLock) { 1922 ensureSharedTempPointerCapacity(1); 1923 final PointerProperties[] pp = gSharedTempPointerProperties; 1924 pp[0].clear(); 1925 pp[0].id = 0; 1926 1927 final PointerCoords pc[] = gSharedTempPointerCoords; 1928 pc[0].clear(); 1929 pc[0].x = x; 1930 pc[0].y = y; 1931 pc[0].pressure = pressure; 1932 pc[0].size = size; 1933 1934 ev.initialize(deviceId, source, displayId, 1935 action, 0, edgeFlags, metaState, 0 /*buttonState*/, CLASSIFICATION_NONE, 1936 0, 0, xPrecision, yPrecision, 1937 downTime * NS_PER_MS, eventTime * NS_PER_MS, 1938 1, pp, pc); 1939 return ev; 1940 } 1941 } 1942 1943 /** 1944 * Create a new MotionEvent, filling in all of the basic values that 1945 * define the motion. 1946 * 1947 * @param downTime The time (in ms) when the user originally pressed down to start 1948 * a stream of position events. This must be obtained from {@link SystemClock#uptimeMillis()}. 1949 * @param eventTime The the time (in ms) when this specific event was generated. This 1950 * must be obtained from {@link SystemClock#uptimeMillis()}. 1951 * @param action The kind of action being performed, such as {@link #ACTION_DOWN}. 1952 * @param pointerCount The number of pointers that are active in this event. 1953 * @param x The X coordinate of this event. 1954 * @param y The Y coordinate of this event. 1955 * @param pressure The current pressure of this event. The pressure generally 1956 * ranges from 0 (no pressure at all) to 1 (normal pressure), however 1957 * values higher than 1 may be generated depending on the calibration of 1958 * the input device. 1959 * @param size A scaled value of the approximate size of the area being pressed when 1960 * touched with the finger. The actual value in pixels corresponding to the finger 1961 * touch is normalized with a device specific range of values 1962 * and scaled to a value between 0 and 1. 1963 * @param metaState The state of any meta / modifier keys that were in effect when 1964 * the event was generated. 1965 * @param xPrecision The precision of the X coordinate being reported. 1966 * @param yPrecision The precision of the Y coordinate being reported. 1967 * @param deviceId The id for the device that this event came from. An id of 1968 * zero indicates that the event didn't come from a physical device; other 1969 * numbers are arbitrary and you shouldn't depend on the values. 1970 * @param edgeFlags A bitfield indicating which edges, if any, were touched by this 1971 * MotionEvent. 1972 * 1973 * @deprecated Use {@link #obtain(long, long, int, float, float, float, float, int, float, float, int, int)} 1974 * instead. 1975 */ 1976 @Deprecated obtain(long downTime, long eventTime, int action, int pointerCount, float x, float y, float pressure, float size, int metaState, float xPrecision, float yPrecision, int deviceId, int edgeFlags)1977 static public MotionEvent obtain(long downTime, long eventTime, int action, 1978 int pointerCount, float x, float y, float pressure, float size, int metaState, 1979 float xPrecision, float yPrecision, int deviceId, int edgeFlags) { 1980 return obtain(downTime, eventTime, action, x, y, pressure, size, 1981 metaState, xPrecision, yPrecision, deviceId, edgeFlags); 1982 } 1983 1984 /** 1985 * Create a new MotionEvent, filling in a subset of the basic motion 1986 * values. Those not specified here are: device id (always 0), pressure 1987 * and size (always 1), x and y precision (always 1), and edgeFlags (always 0). 1988 * 1989 * @param downTime The time (in ms) when the user originally pressed down to start 1990 * a stream of position events. This must be obtained from {@link SystemClock#uptimeMillis()}. 1991 * @param eventTime The the time (in ms) when this specific event was generated. This 1992 * must be obtained from {@link SystemClock#uptimeMillis()}. 1993 * @param action The kind of action being performed, such as {@link #ACTION_DOWN}. 1994 * @param x The X coordinate of this event. 1995 * @param y The Y coordinate of this event. 1996 * @param metaState The state of any meta / modifier keys that were in effect when 1997 * the event was generated. 1998 */ obtain(long downTime, long eventTime, int action, float x, float y, int metaState)1999 static public MotionEvent obtain(long downTime, long eventTime, int action, 2000 float x, float y, int metaState) { 2001 return obtain(downTime, eventTime, action, x, y, 1.0f, 1.0f, 2002 metaState, 1.0f, 1.0f, 0, 0); 2003 } 2004 2005 /** 2006 * Create a new MotionEvent, copying from an existing one. 2007 */ obtain(MotionEvent other)2008 static public MotionEvent obtain(MotionEvent other) { 2009 if (other == null) { 2010 throw new IllegalArgumentException("other motion event must not be null"); 2011 } 2012 2013 MotionEvent ev = obtain(); 2014 ev.mNativePtr = nativeCopy(ev.mNativePtr, other.mNativePtr, true /*keepHistory*/); 2015 return ev; 2016 } 2017 2018 /** 2019 * Create a new MotionEvent, copying from an existing one, but not including 2020 * any historical point information. 2021 */ obtainNoHistory(MotionEvent other)2022 static public MotionEvent obtainNoHistory(MotionEvent other) { 2023 if (other == null) { 2024 throw new IllegalArgumentException("other motion event must not be null"); 2025 } 2026 2027 MotionEvent ev = obtain(); 2028 ev.mNativePtr = nativeCopy(ev.mNativePtr, other.mNativePtr, false /*keepHistory*/); 2029 return ev; 2030 } 2031 initialize(int deviceId, int source, int displayId, int action, int flags, int edgeFlags, int metaState, int buttonState, @Classification int classification, float xOffset, float yOffset, float xPrecision, float yPrecision, long downTimeNanos, long eventTimeNanos, int pointerCount, PointerProperties[] pointerIds, PointerCoords[] pointerCoords)2032 private boolean initialize(int deviceId, int source, int displayId, int action, int flags, 2033 int edgeFlags, int metaState, int buttonState, @Classification int classification, 2034 float xOffset, float yOffset, float xPrecision, float yPrecision, 2035 long downTimeNanos, long eventTimeNanos, 2036 int pointerCount, PointerProperties[] pointerIds, PointerCoords[] pointerCoords) { 2037 mNativePtr = nativeInitialize(mNativePtr, deviceId, source, displayId, action, flags, 2038 edgeFlags, metaState, buttonState, classification, xOffset, yOffset, 2039 xPrecision, yPrecision, downTimeNanos, eventTimeNanos, pointerCount, pointerIds, 2040 pointerCoords); 2041 if (mNativePtr == 0) { 2042 return false; 2043 } 2044 updateCursorPosition(); 2045 return true; 2046 } 2047 2048 /** @hide */ 2049 @Override 2050 @UnsupportedAppUsage copy()2051 public MotionEvent copy() { 2052 return obtain(this); 2053 } 2054 2055 /** 2056 * Recycle the MotionEvent, to be re-used by a later caller. After calling 2057 * this function you must not ever touch the event again. 2058 */ 2059 @Override recycle()2060 public final void recycle() { 2061 super.recycle(); 2062 2063 synchronized (gRecyclerLock) { 2064 if (gRecyclerUsed < MAX_RECYCLED) { 2065 gRecyclerUsed++; 2066 mNext = gRecyclerTop; 2067 gRecyclerTop = this; 2068 } 2069 } 2070 } 2071 2072 /** 2073 * Applies a scale factor to all points within this event. 2074 * 2075 * This method is used to adjust touch events to simulate different density 2076 * displays for compatibility mode. The values returned by {@link #getRawX()}, 2077 * {@link #getRawY()}, {@link #getXPrecision()} and {@link #getYPrecision()} 2078 * are also affected by the scale factor. 2079 * 2080 * @param scale The scale factor to apply. 2081 * @hide 2082 */ 2083 @UnsupportedAppUsage scale(float scale)2084 public final void scale(float scale) { 2085 if (scale != 1.0f) { 2086 nativeScale(mNativePtr, scale); 2087 } 2088 } 2089 2090 /** @hide */ 2091 @Override getId()2092 public int getId() { 2093 return nativeGetId(mNativePtr); 2094 } 2095 2096 /** {@inheritDoc} */ 2097 @Override getDeviceId()2098 public final int getDeviceId() { 2099 return nativeGetDeviceId(mNativePtr); 2100 } 2101 2102 /** {@inheritDoc} */ 2103 @Override getSource()2104 public final int getSource() { 2105 return nativeGetSource(mNativePtr); 2106 } 2107 2108 /** {@inheritDoc} */ 2109 @Override setSource(int source)2110 public final void setSource(int source) { 2111 if (source == getSource()) { 2112 return; 2113 } 2114 nativeSetSource(mNativePtr, source); 2115 updateCursorPosition(); 2116 } 2117 2118 /** @hide */ 2119 @Override getDisplayId()2120 public int getDisplayId() { 2121 return nativeGetDisplayId(mNativePtr); 2122 } 2123 2124 /** @hide */ 2125 @TestApi 2126 @Override setDisplayId(int displayId)2127 public void setDisplayId(int displayId) { 2128 nativeSetDisplayId(mNativePtr, displayId); 2129 } 2130 2131 /** 2132 * Return the kind of action being performed. 2133 * Consider using {@link #getActionMasked} and {@link #getActionIndex} to retrieve 2134 * the separate masked action and pointer index. 2135 * @return The action, such as {@link #ACTION_DOWN} or 2136 * the combination of {@link #ACTION_POINTER_DOWN} with a shifted pointer index. 2137 */ getAction()2138 public final int getAction() { 2139 return nativeGetAction(mNativePtr); 2140 } 2141 2142 /** 2143 * Return the masked action being performed, without pointer index information. 2144 * Use {@link #getActionIndex} to return the index associated with pointer actions. 2145 * @return The action, such as {@link #ACTION_DOWN} or {@link #ACTION_POINTER_DOWN}. 2146 */ getActionMasked()2147 public final int getActionMasked() { 2148 return nativeGetAction(mNativePtr) & ACTION_MASK; 2149 } 2150 2151 /** 2152 * For {@link #ACTION_POINTER_DOWN} or {@link #ACTION_POINTER_UP} 2153 * as returned by {@link #getActionMasked}, this returns the associated 2154 * pointer index. 2155 * The index may be used with {@link #getPointerId(int)}, 2156 * {@link #getX(int)}, {@link #getY(int)}, {@link #getPressure(int)}, 2157 * and {@link #getSize(int)} to get information about the pointer that has 2158 * gone down or up. 2159 * @return The index associated with the action. 2160 */ getActionIndex()2161 public final int getActionIndex() { 2162 return (nativeGetAction(mNativePtr) & ACTION_POINTER_INDEX_MASK) 2163 >> ACTION_POINTER_INDEX_SHIFT; 2164 } 2165 2166 /** 2167 * Returns true if this motion event is a touch event. 2168 * <p> 2169 * Specifically excludes pointer events with action {@link #ACTION_HOVER_MOVE}, 2170 * {@link #ACTION_HOVER_ENTER}, {@link #ACTION_HOVER_EXIT}, or {@link #ACTION_SCROLL} 2171 * because they are not actually touch events (the pointer is not down). 2172 * </p> 2173 * @return True if this motion event is a touch event. 2174 * @hide 2175 */ isTouchEvent()2176 public final boolean isTouchEvent() { 2177 return nativeIsTouchEvent(mNativePtr); 2178 } 2179 2180 /** 2181 * Gets the motion event flags. 2182 * 2183 * @see #FLAG_WINDOW_IS_OBSCURED 2184 */ getFlags()2185 public final int getFlags() { 2186 return nativeGetFlags(mNativePtr); 2187 } 2188 2189 /** @hide */ 2190 @Override isTainted()2191 public final boolean isTainted() { 2192 final int flags = getFlags(); 2193 return (flags & FLAG_TAINTED) != 0; 2194 } 2195 2196 /** @hide */ 2197 @Override setTainted(boolean tainted)2198 public final void setTainted(boolean tainted) { 2199 final int flags = getFlags(); 2200 nativeSetFlags(mNativePtr, tainted ? flags | FLAG_TAINTED : flags & ~FLAG_TAINTED); 2201 } 2202 2203 /** @hide */ isTargetAccessibilityFocus()2204 public boolean isTargetAccessibilityFocus() { 2205 final int flags = getFlags(); 2206 return (flags & FLAG_TARGET_ACCESSIBILITY_FOCUS) != 0; 2207 } 2208 2209 /** @hide */ setTargetAccessibilityFocus(boolean targetsFocus)2210 public void setTargetAccessibilityFocus(boolean targetsFocus) { 2211 final int flags = getFlags(); 2212 nativeSetFlags(mNativePtr, targetsFocus 2213 ? flags | FLAG_TARGET_ACCESSIBILITY_FOCUS 2214 : flags & ~FLAG_TARGET_ACCESSIBILITY_FOCUS); 2215 } 2216 2217 /** @hide */ isHoverExitPending()2218 public final boolean isHoverExitPending() { 2219 final int flags = getFlags(); 2220 return (flags & FLAG_HOVER_EXIT_PENDING) != 0; 2221 } 2222 2223 /** @hide */ setHoverExitPending(boolean hoverExitPending)2224 public void setHoverExitPending(boolean hoverExitPending) { 2225 final int flags = getFlags(); 2226 nativeSetFlags(mNativePtr, hoverExitPending 2227 ? flags | FLAG_HOVER_EXIT_PENDING 2228 : flags & ~FLAG_HOVER_EXIT_PENDING); 2229 } 2230 2231 /** 2232 * Returns the time (in ms) when the user originally pressed down to start 2233 * a stream of position events. 2234 */ getDownTime()2235 public final long getDownTime() { 2236 return nativeGetDownTimeNanos(mNativePtr) / NS_PER_MS; 2237 } 2238 2239 /** 2240 * Sets the time (in ms) when the user originally pressed down to start 2241 * a stream of position events. 2242 * 2243 * @hide 2244 */ 2245 @UnsupportedAppUsage setDownTime(long downTime)2246 public final void setDownTime(long downTime) { 2247 nativeSetDownTimeNanos(mNativePtr, downTime * NS_PER_MS); 2248 } 2249 2250 /** 2251 * Retrieve the time this event occurred, 2252 * in the {@link android.os.SystemClock#uptimeMillis} time base. 2253 * 2254 * @return Returns the time this event occurred, 2255 * in the {@link android.os.SystemClock#uptimeMillis} time base. 2256 */ 2257 @Override getEventTime()2258 public final long getEventTime() { 2259 return nativeGetEventTimeNanos(mNativePtr, HISTORY_CURRENT) / NS_PER_MS; 2260 } 2261 2262 /** 2263 * Retrieve the time this event occurred, 2264 * in the {@link android.os.SystemClock#uptimeMillis} time base but with 2265 * nanosecond precision. 2266 * <p> 2267 * The value is in nanosecond precision but it may not have nanosecond accuracy. 2268 * </p> 2269 * 2270 * @return Returns the time this event occurred, 2271 * in the {@link android.os.SystemClock#uptimeMillis} time base but with 2272 * nanosecond precision. 2273 * 2274 * @hide 2275 */ 2276 @Override 2277 @UnsupportedAppUsage getEventTimeNano()2278 public final long getEventTimeNano() { 2279 return nativeGetEventTimeNanos(mNativePtr, HISTORY_CURRENT); 2280 } 2281 2282 /** 2283 * Equivalent to {@link #getX(int)} for pointer index 0 (regardless of the 2284 * pointer identifier). 2285 * 2286 * @return The X coordinate of the first pointer index in the coordinate 2287 * space of the view that received this motion event. 2288 * 2289 * @see #AXIS_X 2290 */ getX()2291 public final float getX() { 2292 return nativeGetAxisValue(mNativePtr, AXIS_X, 0, HISTORY_CURRENT); 2293 } 2294 2295 /** 2296 * Equivalent to {@link #getY(int)} for pointer index 0 (regardless of the 2297 * pointer identifier). 2298 * 2299 * @return The Y coordinate of the first pointer index in the coordinate 2300 * space of the view that received this motion event. 2301 * 2302 * @see #AXIS_Y 2303 */ getY()2304 public final float getY() { 2305 return nativeGetAxisValue(mNativePtr, AXIS_Y, 0, HISTORY_CURRENT); 2306 } 2307 2308 /** 2309 * {@link #getPressure(int)} for the first pointer index (may be an 2310 * arbitrary pointer identifier). 2311 * 2312 * @see #AXIS_PRESSURE 2313 */ getPressure()2314 public final float getPressure() { 2315 return nativeGetAxisValue(mNativePtr, AXIS_PRESSURE, 0, HISTORY_CURRENT); 2316 } 2317 2318 /** 2319 * {@link #getSize(int)} for the first pointer index (may be an 2320 * arbitrary pointer identifier). 2321 * 2322 * @see #AXIS_SIZE 2323 */ getSize()2324 public final float getSize() { 2325 return nativeGetAxisValue(mNativePtr, AXIS_SIZE, 0, HISTORY_CURRENT); 2326 } 2327 2328 /** 2329 * {@link #getTouchMajor(int)} for the first pointer index (may be an 2330 * arbitrary pointer identifier). 2331 * 2332 * @see #AXIS_TOUCH_MAJOR 2333 */ getTouchMajor()2334 public final float getTouchMajor() { 2335 return nativeGetAxisValue(mNativePtr, AXIS_TOUCH_MAJOR, 0, HISTORY_CURRENT); 2336 } 2337 2338 /** 2339 * {@link #getTouchMinor(int)} for the first pointer index (may be an 2340 * arbitrary pointer identifier). 2341 * 2342 * @see #AXIS_TOUCH_MINOR 2343 */ getTouchMinor()2344 public final float getTouchMinor() { 2345 return nativeGetAxisValue(mNativePtr, AXIS_TOUCH_MINOR, 0, HISTORY_CURRENT); 2346 } 2347 2348 /** 2349 * {@link #getToolMajor(int)} for the first pointer index (may be an 2350 * arbitrary pointer identifier). 2351 * 2352 * @see #AXIS_TOOL_MAJOR 2353 */ getToolMajor()2354 public final float getToolMajor() { 2355 return nativeGetAxisValue(mNativePtr, AXIS_TOOL_MAJOR, 0, HISTORY_CURRENT); 2356 } 2357 2358 /** 2359 * {@link #getToolMinor(int)} for the first pointer index (may be an 2360 * arbitrary pointer identifier). 2361 * 2362 * @see #AXIS_TOOL_MINOR 2363 */ getToolMinor()2364 public final float getToolMinor() { 2365 return nativeGetAxisValue(mNativePtr, AXIS_TOOL_MINOR, 0, HISTORY_CURRENT); 2366 } 2367 2368 /** 2369 * {@link #getOrientation(int)} for the first pointer index (may be an 2370 * arbitrary pointer identifier). 2371 * 2372 * @see #AXIS_ORIENTATION 2373 */ getOrientation()2374 public final float getOrientation() { 2375 return nativeGetAxisValue(mNativePtr, AXIS_ORIENTATION, 0, HISTORY_CURRENT); 2376 } 2377 2378 /** 2379 * {@link #getAxisValue(int)} for the first pointer index (may be an 2380 * arbitrary pointer identifier). 2381 * 2382 * @param axis The axis identifier for the axis value to retrieve. 2383 * 2384 * @see #AXIS_X 2385 * @see #AXIS_Y 2386 */ getAxisValue(int axis)2387 public final float getAxisValue(int axis) { 2388 return nativeGetAxisValue(mNativePtr, axis, 0, HISTORY_CURRENT); 2389 } 2390 2391 /** 2392 * The number of pointers of data contained in this event. Always 2393 * >= 1. 2394 */ getPointerCount()2395 public final int getPointerCount() { 2396 return nativeGetPointerCount(mNativePtr); 2397 } 2398 2399 /** 2400 * Return the pointer identifier associated with a particular pointer 2401 * data index in this event. The identifier tells you the actual pointer 2402 * number associated with the data, accounting for individual pointers 2403 * going up and down since the start of the current gesture. 2404 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 2405 * (the first pointer that is down) to {@link #getPointerCount()}-1. 2406 */ getPointerId(int pointerIndex)2407 public final int getPointerId(int pointerIndex) { 2408 return nativeGetPointerId(mNativePtr, pointerIndex); 2409 } 2410 2411 /** 2412 * Gets the tool type of a pointer for the given pointer index. 2413 * The tool type indicates the type of tool used to make contact such 2414 * as a finger or stylus, if known. 2415 * 2416 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 2417 * (the first pointer that is down) to {@link #getPointerCount()}-1. 2418 * @return The tool type of the pointer. 2419 * 2420 * @see #TOOL_TYPE_UNKNOWN 2421 * @see #TOOL_TYPE_FINGER 2422 * @see #TOOL_TYPE_STYLUS 2423 * @see #TOOL_TYPE_MOUSE 2424 */ getToolType(int pointerIndex)2425 public final int getToolType(int pointerIndex) { 2426 return nativeGetToolType(mNativePtr, pointerIndex); 2427 } 2428 2429 /** 2430 * Given a pointer identifier, find the index of its data in the event. 2431 * 2432 * @param pointerId The identifier of the pointer to be found. 2433 * @return Returns either the index of the pointer (for use with 2434 * {@link #getX(int)} et al.), or -1 if there is no data available for 2435 * that pointer identifier. 2436 */ findPointerIndex(int pointerId)2437 public final int findPointerIndex(int pointerId) { 2438 return nativeFindPointerIndex(mNativePtr, pointerId); 2439 } 2440 2441 /** 2442 * Returns the X coordinate of the pointer referenced by 2443 * {@code pointerIndex} for this motion event. The coordinate is in the 2444 * coordinate space of the view that received this motion event. 2445 * 2446 * <p>Use {@link #getPointerId(int)} to get the pointer identifier for the 2447 * pointer referenced by {@code pointerIndex}. 2448 * 2449 * @param pointerIndex Index of the pointer for which the X coordinate is 2450 * returned. May be a value in the range of 0 (the first pointer that 2451 * is down) to {@link #getPointerCount()} - 1. 2452 * @return The X coordinate of the pointer referenced by 2453 * {@code pointerIndex} for this motion event. The unit is pixels. The 2454 * value may contain a fractional portion for devices that are subpixel 2455 * precise. 2456 * 2457 * @see #AXIS_X 2458 */ getX(int pointerIndex)2459 public final float getX(int pointerIndex) { 2460 return nativeGetAxisValue(mNativePtr, AXIS_X, pointerIndex, HISTORY_CURRENT); 2461 } 2462 2463 /** 2464 * Returns the Y coordinate of the pointer referenced by 2465 * {@code pointerIndex} for this motion event. The coordinate is in the 2466 * coordinate space of the view that received this motion event. 2467 * 2468 * <p>Use {@link #getPointerId(int)} to get the pointer identifier for the 2469 * pointer referenced by {@code pointerIndex}. 2470 * 2471 * @param pointerIndex Index of the pointer for which the Y coordinate is 2472 * returned. May be a value in the range of 0 (the first pointer that 2473 * is down) to {@link #getPointerCount()} - 1. 2474 * @return The Y coordinate of the pointer referenced by 2475 * {@code pointerIndex} for this motion event. The unit is pixels. The 2476 * value may contain a fractional portion for devices that are subpixel 2477 * precise. 2478 * 2479 * @see #AXIS_Y 2480 */ getY(int pointerIndex)2481 public final float getY(int pointerIndex) { 2482 return nativeGetAxisValue(mNativePtr, AXIS_Y, pointerIndex, HISTORY_CURRENT); 2483 } 2484 2485 /** 2486 * Returns the current pressure of this event for the given pointer 2487 * <em>index</em> (use {@link #getPointerId(int)} to find the pointer 2488 * identifier for this index). 2489 * The pressure generally 2490 * ranges from 0 (no pressure at all) to 1 (normal pressure), however 2491 * values higher than 1 may be generated depending on the calibration of 2492 * the input device. 2493 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 2494 * (the first pointer that is down) to {@link #getPointerCount()}-1. 2495 * 2496 * @see #AXIS_PRESSURE 2497 */ getPressure(int pointerIndex)2498 public final float getPressure(int pointerIndex) { 2499 return nativeGetAxisValue(mNativePtr, AXIS_PRESSURE, pointerIndex, HISTORY_CURRENT); 2500 } 2501 2502 /** 2503 * Returns a scaled value of the approximate size for the given pointer 2504 * <em>index</em> (use {@link #getPointerId(int)} to find the pointer 2505 * identifier for this index). 2506 * This represents some approximation of the area of the screen being 2507 * pressed; the actual value in pixels corresponding to the 2508 * touch is normalized with the device specific range of values 2509 * and scaled to a value between 0 and 1. The value of size can be used to 2510 * determine fat touch events. 2511 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 2512 * (the first pointer that is down) to {@link #getPointerCount()}-1. 2513 * 2514 * @see #AXIS_SIZE 2515 */ getSize(int pointerIndex)2516 public final float getSize(int pointerIndex) { 2517 return nativeGetAxisValue(mNativePtr, AXIS_SIZE, pointerIndex, HISTORY_CURRENT); 2518 } 2519 2520 /** 2521 * Returns the length of the major axis of an ellipse that describes the touch 2522 * area at the point of contact for the given pointer 2523 * <em>index</em> (use {@link #getPointerId(int)} to find the pointer 2524 * identifier for this index). 2525 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 2526 * (the first pointer that is down) to {@link #getPointerCount()}-1. 2527 * 2528 * @see #AXIS_TOUCH_MAJOR 2529 */ getTouchMajor(int pointerIndex)2530 public final float getTouchMajor(int pointerIndex) { 2531 return nativeGetAxisValue(mNativePtr, AXIS_TOUCH_MAJOR, pointerIndex, HISTORY_CURRENT); 2532 } 2533 2534 /** 2535 * Returns the length of the minor axis of an ellipse that describes the touch 2536 * area at the point of contact for the given pointer 2537 * <em>index</em> (use {@link #getPointerId(int)} to find the pointer 2538 * identifier for this index). 2539 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 2540 * (the first pointer that is down) to {@link #getPointerCount()}-1. 2541 * 2542 * @see #AXIS_TOUCH_MINOR 2543 */ getTouchMinor(int pointerIndex)2544 public final float getTouchMinor(int pointerIndex) { 2545 return nativeGetAxisValue(mNativePtr, AXIS_TOUCH_MINOR, pointerIndex, HISTORY_CURRENT); 2546 } 2547 2548 /** 2549 * Returns the length of the major axis of an ellipse that describes the size of 2550 * the approaching tool for the given pointer 2551 * <em>index</em> (use {@link #getPointerId(int)} to find the pointer 2552 * identifier for this index). 2553 * The tool area represents the estimated size of the finger or pen that is 2554 * touching the device independent of its actual touch area at the point of contact. 2555 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 2556 * (the first pointer that is down) to {@link #getPointerCount()}-1. 2557 * 2558 * @see #AXIS_TOOL_MAJOR 2559 */ getToolMajor(int pointerIndex)2560 public final float getToolMajor(int pointerIndex) { 2561 return nativeGetAxisValue(mNativePtr, AXIS_TOOL_MAJOR, pointerIndex, HISTORY_CURRENT); 2562 } 2563 2564 /** 2565 * Returns the length of the minor axis of an ellipse that describes the size of 2566 * the approaching tool for the given pointer 2567 * <em>index</em> (use {@link #getPointerId(int)} to find the pointer 2568 * identifier for this index). 2569 * The tool area represents the estimated size of the finger or pen that is 2570 * touching the device independent of its actual touch area at the point of contact. 2571 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 2572 * (the first pointer that is down) to {@link #getPointerCount()}-1. 2573 * 2574 * @see #AXIS_TOOL_MINOR 2575 */ getToolMinor(int pointerIndex)2576 public final float getToolMinor(int pointerIndex) { 2577 return nativeGetAxisValue(mNativePtr, AXIS_TOOL_MINOR, pointerIndex, HISTORY_CURRENT); 2578 } 2579 2580 /** 2581 * Returns the orientation of the touch area and tool area in radians clockwise from vertical 2582 * for the given pointer <em>index</em> (use {@link #getPointerId(int)} to find the pointer 2583 * identifier for this index). 2584 * An angle of 0 radians indicates that the major axis of contact is oriented 2585 * upwards, is perfectly circular or is of unknown orientation. A positive angle 2586 * indicates that the major axis of contact is oriented to the right. A negative angle 2587 * indicates that the major axis of contact is oriented to the left. 2588 * The full range is from -PI/2 radians (finger pointing fully left) to PI/2 radians 2589 * (finger pointing fully right). 2590 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 2591 * (the first pointer that is down) to {@link #getPointerCount()}-1. 2592 * 2593 * @see #AXIS_ORIENTATION 2594 */ getOrientation(int pointerIndex)2595 public final float getOrientation(int pointerIndex) { 2596 return nativeGetAxisValue(mNativePtr, AXIS_ORIENTATION, pointerIndex, HISTORY_CURRENT); 2597 } 2598 2599 /** 2600 * Returns the value of the requested axis for the given pointer <em>index</em> 2601 * (use {@link #getPointerId(int)} to find the pointer identifier for this index). 2602 * 2603 * @param axis The axis identifier for the axis value to retrieve. 2604 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 2605 * (the first pointer that is down) to {@link #getPointerCount()}-1. 2606 * @return The value of the axis, or 0 if the axis is not available. 2607 * 2608 * @see #AXIS_X 2609 * @see #AXIS_Y 2610 */ getAxisValue(int axis, int pointerIndex)2611 public final float getAxisValue(int axis, int pointerIndex) { 2612 return nativeGetAxisValue(mNativePtr, axis, pointerIndex, HISTORY_CURRENT); 2613 } 2614 2615 /** 2616 * Populates a {@link PointerCoords} object with pointer coordinate data for 2617 * the specified pointer index. 2618 * 2619 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 2620 * (the first pointer that is down) to {@link #getPointerCount()}-1. 2621 * @param outPointerCoords The pointer coordinate object to populate. 2622 * 2623 * @see PointerCoords 2624 */ getPointerCoords(int pointerIndex, PointerCoords outPointerCoords)2625 public final void getPointerCoords(int pointerIndex, PointerCoords outPointerCoords) { 2626 nativeGetPointerCoords(mNativePtr, pointerIndex, HISTORY_CURRENT, outPointerCoords); 2627 } 2628 2629 /** 2630 * Populates a {@link PointerProperties} object with pointer properties for 2631 * the specified pointer index. 2632 * 2633 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 2634 * (the first pointer that is down) to {@link #getPointerCount()}-1. 2635 * @param outPointerProperties The pointer properties object to populate. 2636 * 2637 * @see PointerProperties 2638 */ getPointerProperties(int pointerIndex, PointerProperties outPointerProperties)2639 public final void getPointerProperties(int pointerIndex, 2640 PointerProperties outPointerProperties) { 2641 nativeGetPointerProperties(mNativePtr, pointerIndex, outPointerProperties); 2642 } 2643 2644 /** 2645 * Returns the state of any meta / modifier keys that were in effect when 2646 * the event was generated. This is the same values as those 2647 * returned by {@link KeyEvent#getMetaState() KeyEvent.getMetaState}. 2648 * 2649 * @return an integer in which each bit set to 1 represents a pressed 2650 * meta key 2651 * 2652 * @see KeyEvent#getMetaState() 2653 */ getMetaState()2654 public final int getMetaState() { 2655 return nativeGetMetaState(mNativePtr); 2656 } 2657 2658 /** 2659 * Gets the state of all buttons that are pressed such as a mouse or stylus button. 2660 * 2661 * @return The button state. 2662 * 2663 * @see #BUTTON_PRIMARY 2664 * @see #BUTTON_SECONDARY 2665 * @see #BUTTON_TERTIARY 2666 * @see #BUTTON_FORWARD 2667 * @see #BUTTON_BACK 2668 * @see #BUTTON_STYLUS_PRIMARY 2669 * @see #BUTTON_STYLUS_SECONDARY 2670 */ getButtonState()2671 public final int getButtonState() { 2672 return nativeGetButtonState(mNativePtr); 2673 } 2674 2675 /** 2676 * Sets the bitfield indicating which buttons are pressed. 2677 * 2678 * @see #getButtonState() 2679 * @hide 2680 */ 2681 @TestApi setButtonState(int buttonState)2682 public final void setButtonState(int buttonState) { 2683 nativeSetButtonState(mNativePtr, buttonState); 2684 } 2685 2686 /** 2687 * Returns the classification for the current gesture. 2688 * The classification may change as more events become available for the same gesture. 2689 * 2690 * @see #CLASSIFICATION_NONE 2691 * @see #CLASSIFICATION_AMBIGUOUS_GESTURE 2692 * @see #CLASSIFICATION_DEEP_PRESS 2693 */ getClassification()2694 public @Classification int getClassification() { 2695 return nativeGetClassification(mNativePtr); 2696 } 2697 2698 /** 2699 * Gets which button has been modified during a press or release action. 2700 * 2701 * For actions other than {@link #ACTION_BUTTON_PRESS} and {@link #ACTION_BUTTON_RELEASE} 2702 * the returned value is undefined. 2703 * 2704 * @see #getButtonState() 2705 */ getActionButton()2706 public final int getActionButton() { 2707 return nativeGetActionButton(mNativePtr); 2708 } 2709 2710 /** 2711 * Sets the action button for the event. 2712 * 2713 * @see #getActionButton() 2714 * @hide 2715 */ 2716 @UnsupportedAppUsage 2717 @TestApi setActionButton(int button)2718 public final void setActionButton(int button) { 2719 nativeSetActionButton(mNativePtr, button); 2720 } 2721 2722 /** 2723 * Equivalent to {@link #getRawX(int)} for pointer index 0 (regardless of 2724 * the pointer identifier). 2725 * 2726 * @return The X coordinate of the first pointer index in the coordinate 2727 * space of the device display. 2728 * 2729 * @see #getX() 2730 * @see #AXIS_X 2731 */ getRawX()2732 public final float getRawX() { 2733 return nativeGetRawAxisValue(mNativePtr, AXIS_X, 0, HISTORY_CURRENT); 2734 } 2735 2736 /** 2737 * Equivalent to {@link #getRawY(int)} for pointer index 0 (regardless of 2738 * the pointer identifier). 2739 * 2740 * @return The Y coordinate of the first pointer index in the coordinate 2741 * space of the device display. 2742 * 2743 * @see #getY() 2744 * @see #AXIS_Y 2745 */ getRawY()2746 public final float getRawY() { 2747 return nativeGetRawAxisValue(mNativePtr, AXIS_Y, 0, HISTORY_CURRENT); 2748 } 2749 2750 /** 2751 * Returns the X coordinate of the pointer referenced by 2752 * {@code pointerIndex} for this motion event. The coordinate is in the 2753 * coordinate space of the device display, irrespective of system 2754 * decorations and whether or not the system is in multi-window mode. If the 2755 * app spans multiple screens in a multiple-screen environment, the 2756 * coordinate space includes all of the spanned screens. 2757 * 2758 * <p>In multi-window mode, the coordinate space extends beyond the bounds 2759 * of the app window to encompass the entire display area. For example, if 2760 * the motion event occurs in the right-hand window of split-screen mode in 2761 * landscape orientation, the left edge of the screen—not the left 2762 * edge of the window—is the origin from which the X coordinate is 2763 * calculated. 2764 * 2765 * <p>In multiple-screen scenarios, the coordinate space can span screens. 2766 * For example, if the app is spanning both screens of a dual-screen device, 2767 * and the motion event occurs on the right-hand screen, the X coordinate is 2768 * calculated from the left edge of the left-hand screen to the point of the 2769 * motion event on the right-hand screen. When the app is restricted to a 2770 * single screen in a multiple-screen environment, the coordinate space 2771 * includes only the screen on which the app is running. 2772 * 2773 * <p>Use {@link #getPointerId(int)} to get the pointer identifier for the 2774 * pointer referenced by {@code pointerIndex}. 2775 * 2776 * @param pointerIndex Index of the pointer for which the X coordinate is 2777 * returned. May be a value in the range of 0 (the first pointer that 2778 * is down) to {@link #getPointerCount()} - 1. 2779 * @return The X coordinate of the pointer referenced by 2780 * {@code pointerIndex} for this motion event. The unit is pixels. The 2781 * value may contain a fractional portion for devices that are subpixel 2782 * precise. 2783 * 2784 * @see #getX(int) 2785 * @see #AXIS_X 2786 */ getRawX(int pointerIndex)2787 public float getRawX(int pointerIndex) { 2788 return nativeGetRawAxisValue(mNativePtr, AXIS_X, pointerIndex, HISTORY_CURRENT); 2789 } 2790 2791 /** 2792 * Returns the Y coordinate of the pointer referenced by 2793 * {@code pointerIndex} for this motion event. The coordinate is in the 2794 * coordinate space of the device display, irrespective of system 2795 * decorations and whether or not the system is in multi-window mode. If the 2796 * app spans multiple screens in a multiple-screen environment, the 2797 * coordinate space includes all of the spanned screens. 2798 * 2799 * <p>In multi-window mode, the coordinate space extends beyond the bounds 2800 * of the app window to encompass the entire device screen. For example, if 2801 * the motion event occurs in the lower window of split-screen mode in 2802 * portrait orientation, the top edge of the screen—not the top edge 2803 * of the window—is the origin from which the Y coordinate is 2804 * determined. 2805 * 2806 * <p>In multiple-screen scenarios, the coordinate space can span screens. 2807 * For example, if the app is spanning both screens of a dual-screen device 2808 * that's rotated 90 degrees, and the motion event occurs on the lower 2809 * screen, the Y coordinate is calculated from the top edge of the upper 2810 * screen to the point of the motion event on the lower screen. When the app 2811 * is restricted to a single screen in a multiple-screen environment, the 2812 * coordinate space includes only the screen on which the app is running. 2813 * 2814 * <p>Use {@link #getPointerId(int)} to get the pointer identifier for the 2815 * pointer referenced by {@code pointerIndex}. 2816 * 2817 * @param pointerIndex Index of the pointer for which the Y coordinate is 2818 * returned. May be a value in the range of 0 (the first pointer that 2819 * is down) to {@link #getPointerCount()} - 1. 2820 * @return The Y coordinate of the pointer referenced by 2821 * {@code pointerIndex} for this motion event. The unit is pixels. The 2822 * value may contain a fractional portion for devices that are subpixel 2823 * precise. 2824 * 2825 * @see #getY(int) 2826 * @see #AXIS_Y 2827 */ getRawY(int pointerIndex)2828 public float getRawY(int pointerIndex) { 2829 return nativeGetRawAxisValue(mNativePtr, AXIS_Y, pointerIndex, HISTORY_CURRENT); 2830 } 2831 2832 /** 2833 * Return the precision of the X coordinates being reported. You can 2834 * multiply this number with {@link #getX} to find the actual hardware 2835 * value of the X coordinate. 2836 * @return Returns the precision of X coordinates being reported. 2837 * 2838 * @see #AXIS_X 2839 */ getXPrecision()2840 public final float getXPrecision() { 2841 return nativeGetXPrecision(mNativePtr); 2842 } 2843 2844 /** 2845 * Return the precision of the Y coordinates being reported. You can 2846 * multiply this number with {@link #getY} to find the actual hardware 2847 * value of the Y coordinate. 2848 * @return Returns the precision of Y coordinates being reported. 2849 * 2850 * @see #AXIS_Y 2851 */ getYPrecision()2852 public final float getYPrecision() { 2853 return nativeGetYPrecision(mNativePtr); 2854 } 2855 2856 /** 2857 * Returns the x coordinate of mouse cursor position when this event is 2858 * reported. This value is only valid if {@link #getSource()} returns 2859 * {@link InputDevice#SOURCE_MOUSE}. 2860 * 2861 * @hide 2862 */ getXCursorPosition()2863 public float getXCursorPosition() { 2864 return nativeGetXCursorPosition(mNativePtr); 2865 } 2866 2867 /** 2868 * Returns the y coordinate of mouse cursor position when this event is 2869 * reported. This value is only valid if {@link #getSource()} returns 2870 * {@link InputDevice#SOURCE_MOUSE}. 2871 * 2872 * @hide 2873 */ getYCursorPosition()2874 public float getYCursorPosition() { 2875 return nativeGetYCursorPosition(mNativePtr); 2876 } 2877 2878 /** 2879 * Sets cursor position to given coordinates. The coordinate in parameters should be after 2880 * offsetting. In other words, the effect of this function is {@link #getXCursorPosition()} and 2881 * {@link #getYCursorPosition()} will return the same value passed in the parameters. 2882 * 2883 * @hide 2884 */ setCursorPosition(float x, float y)2885 private void setCursorPosition(float x, float y) { 2886 nativeSetCursorPosition(mNativePtr, x, y); 2887 } 2888 2889 /** 2890 * Returns the number of historical points in this event. These are 2891 * movements that have occurred between this event and the previous event. 2892 * This only applies to ACTION_MOVE events -- all other actions will have 2893 * a size of 0. 2894 * 2895 * @return Returns the number of historical points in the event. 2896 */ getHistorySize()2897 public final int getHistorySize() { 2898 return nativeGetHistorySize(mNativePtr); 2899 } 2900 2901 /** 2902 * Returns the time that a historical movement occurred between this event 2903 * and the previous event, in the {@link android.os.SystemClock#uptimeMillis} time base. 2904 * <p> 2905 * This only applies to ACTION_MOVE events. 2906 * </p> 2907 * 2908 * @param pos Which historical value to return; must be less than 2909 * {@link #getHistorySize} 2910 * @return Returns the time that a historical movement occurred between this 2911 * event and the previous event, 2912 * in the {@link android.os.SystemClock#uptimeMillis} time base. 2913 * 2914 * @see #getHistorySize 2915 * @see #getEventTime 2916 */ getHistoricalEventTime(int pos)2917 public final long getHistoricalEventTime(int pos) { 2918 return nativeGetEventTimeNanos(mNativePtr, pos) / NS_PER_MS; 2919 } 2920 2921 /** 2922 * Returns the time that a historical movement occurred between this event 2923 * and the previous event, in the {@link android.os.SystemClock#uptimeMillis} time base 2924 * but with nanosecond (instead of millisecond) precision. 2925 * <p> 2926 * This only applies to ACTION_MOVE events. 2927 * </p><p> 2928 * The value is in nanosecond precision but it may not have nanosecond accuracy. 2929 * </p> 2930 * 2931 * @param pos Which historical value to return; must be less than 2932 * {@link #getHistorySize} 2933 * @return Returns the time that a historical movement occurred between this 2934 * event and the previous event, 2935 * in the {@link android.os.SystemClock#uptimeMillis} time base but with 2936 * nanosecond (instead of millisecond) precision. 2937 * 2938 * @see #getHistorySize 2939 * @see #getEventTime 2940 * 2941 * @hide 2942 */ getHistoricalEventTimeNano(int pos)2943 public final long getHistoricalEventTimeNano(int pos) { 2944 return nativeGetEventTimeNanos(mNativePtr, pos); 2945 } 2946 2947 /** 2948 * {@link #getHistoricalX(int, int)} for the first pointer index (may be an 2949 * arbitrary pointer identifier). 2950 * 2951 * @param pos Which historical value to return; must be less than 2952 * {@link #getHistorySize} 2953 * 2954 * @see #getHistorySize 2955 * @see #getX() 2956 * @see #AXIS_X 2957 */ getHistoricalX(int pos)2958 public final float getHistoricalX(int pos) { 2959 return nativeGetAxisValue(mNativePtr, AXIS_X, 0, pos); 2960 } 2961 2962 /** 2963 * {@link #getHistoricalY(int, int)} for the first pointer index (may be an 2964 * arbitrary pointer identifier). 2965 * 2966 * @param pos Which historical value to return; must be less than 2967 * {@link #getHistorySize} 2968 * 2969 * @see #getHistorySize 2970 * @see #getY() 2971 * @see #AXIS_Y 2972 */ getHistoricalY(int pos)2973 public final float getHistoricalY(int pos) { 2974 return nativeGetAxisValue(mNativePtr, AXIS_Y, 0, pos); 2975 } 2976 2977 /** 2978 * {@link #getHistoricalPressure(int, int)} for the first pointer index (may be an 2979 * arbitrary pointer identifier). 2980 * 2981 * @param pos Which historical value to return; must be less than 2982 * {@link #getHistorySize} 2983 * 2984 * @see #getHistorySize 2985 * @see #getPressure() 2986 * @see #AXIS_PRESSURE 2987 */ getHistoricalPressure(int pos)2988 public final float getHistoricalPressure(int pos) { 2989 return nativeGetAxisValue(mNativePtr, AXIS_PRESSURE, 0, pos); 2990 } 2991 2992 /** 2993 * {@link #getHistoricalSize(int, int)} for the first pointer index (may be an 2994 * arbitrary pointer identifier). 2995 * 2996 * @param pos Which historical value to return; must be less than 2997 * {@link #getHistorySize} 2998 * 2999 * @see #getHistorySize 3000 * @see #getSize() 3001 * @see #AXIS_SIZE 3002 */ getHistoricalSize(int pos)3003 public final float getHistoricalSize(int pos) { 3004 return nativeGetAxisValue(mNativePtr, AXIS_SIZE, 0, pos); 3005 } 3006 3007 /** 3008 * {@link #getHistoricalTouchMajor(int, int)} for the first pointer index (may be an 3009 * arbitrary pointer identifier). 3010 * 3011 * @param pos Which historical value to return; must be less than 3012 * {@link #getHistorySize} 3013 * 3014 * @see #getHistorySize 3015 * @see #getTouchMajor() 3016 * @see #AXIS_TOUCH_MAJOR 3017 */ getHistoricalTouchMajor(int pos)3018 public final float getHistoricalTouchMajor(int pos) { 3019 return nativeGetAxisValue(mNativePtr, AXIS_TOUCH_MAJOR, 0, pos); 3020 } 3021 3022 /** 3023 * {@link #getHistoricalTouchMinor(int, int)} for the first pointer index (may be an 3024 * arbitrary pointer identifier). 3025 * 3026 * @param pos Which historical value to return; must be less than 3027 * {@link #getHistorySize} 3028 * 3029 * @see #getHistorySize 3030 * @see #getTouchMinor() 3031 * @see #AXIS_TOUCH_MINOR 3032 */ getHistoricalTouchMinor(int pos)3033 public final float getHistoricalTouchMinor(int pos) { 3034 return nativeGetAxisValue(mNativePtr, AXIS_TOUCH_MINOR, 0, pos); 3035 } 3036 3037 /** 3038 * {@link #getHistoricalToolMajor(int, int)} for the first pointer index (may be an 3039 * arbitrary pointer identifier). 3040 * 3041 * @param pos Which historical value to return; must be less than 3042 * {@link #getHistorySize} 3043 * 3044 * @see #getHistorySize 3045 * @see #getToolMajor() 3046 * @see #AXIS_TOOL_MAJOR 3047 */ getHistoricalToolMajor(int pos)3048 public final float getHistoricalToolMajor(int pos) { 3049 return nativeGetAxisValue(mNativePtr, AXIS_TOOL_MAJOR, 0, pos); 3050 } 3051 3052 /** 3053 * {@link #getHistoricalToolMinor(int, int)} for the first pointer index (may be an 3054 * arbitrary pointer identifier). 3055 * 3056 * @param pos Which historical value to return; must be less than 3057 * {@link #getHistorySize} 3058 * 3059 * @see #getHistorySize 3060 * @see #getToolMinor() 3061 * @see #AXIS_TOOL_MINOR 3062 */ getHistoricalToolMinor(int pos)3063 public final float getHistoricalToolMinor(int pos) { 3064 return nativeGetAxisValue(mNativePtr, AXIS_TOOL_MINOR, 0, pos); 3065 } 3066 3067 /** 3068 * {@link #getHistoricalOrientation(int, int)} for the first pointer index (may be an 3069 * arbitrary pointer identifier). 3070 * 3071 * @param pos Which historical value to return; must be less than 3072 * {@link #getHistorySize} 3073 * 3074 * @see #getHistorySize 3075 * @see #getOrientation() 3076 * @see #AXIS_ORIENTATION 3077 */ getHistoricalOrientation(int pos)3078 public final float getHistoricalOrientation(int pos) { 3079 return nativeGetAxisValue(mNativePtr, AXIS_ORIENTATION, 0, pos); 3080 } 3081 3082 /** 3083 * {@link #getHistoricalAxisValue(int, int, int)} for the first pointer index (may be an 3084 * arbitrary pointer identifier). 3085 * 3086 * @param axis The axis identifier for the axis value to retrieve. 3087 * @param pos Which historical value to return; must be less than 3088 * {@link #getHistorySize} 3089 * 3090 * @see #getHistorySize 3091 * @see #getAxisValue(int) 3092 * @see #AXIS_X 3093 * @see #AXIS_Y 3094 */ getHistoricalAxisValue(int axis, int pos)3095 public final float getHistoricalAxisValue(int axis, int pos) { 3096 return nativeGetAxisValue(mNativePtr, axis, 0, pos); 3097 } 3098 3099 /** 3100 * Returns a historical X coordinate, as per {@link #getX(int)}, that 3101 * occurred between this event and the previous event for the given pointer. 3102 * Only applies to ACTION_MOVE events. 3103 * 3104 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 3105 * (the first pointer that is down) to {@link #getPointerCount()}-1. 3106 * @param pos Which historical value to return; must be less than 3107 * {@link #getHistorySize} 3108 * 3109 * @see #getHistorySize 3110 * @see #getX(int) 3111 * @see #AXIS_X 3112 */ getHistoricalX(int pointerIndex, int pos)3113 public final float getHistoricalX(int pointerIndex, int pos) { 3114 return nativeGetAxisValue(mNativePtr, AXIS_X, pointerIndex, pos); 3115 } 3116 3117 /** 3118 * Returns a historical Y coordinate, as per {@link #getY(int)}, that 3119 * occurred between this event and the previous event for the given pointer. 3120 * Only applies to ACTION_MOVE events. 3121 * 3122 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 3123 * (the first pointer that is down) to {@link #getPointerCount()}-1. 3124 * @param pos Which historical value to return; must be less than 3125 * {@link #getHistorySize} 3126 * 3127 * @see #getHistorySize 3128 * @see #getY(int) 3129 * @see #AXIS_Y 3130 */ getHistoricalY(int pointerIndex, int pos)3131 public final float getHistoricalY(int pointerIndex, int pos) { 3132 return nativeGetAxisValue(mNativePtr, AXIS_Y, pointerIndex, pos); 3133 } 3134 3135 /** 3136 * Returns a historical pressure coordinate, as per {@link #getPressure(int)}, 3137 * that occurred between this event and the previous event for the given 3138 * pointer. Only applies to ACTION_MOVE events. 3139 * 3140 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 3141 * (the first pointer that is down) to {@link #getPointerCount()}-1. 3142 * @param pos Which historical value to return; must be less than 3143 * {@link #getHistorySize} 3144 * 3145 * @see #getHistorySize 3146 * @see #getPressure(int) 3147 * @see #AXIS_PRESSURE 3148 */ getHistoricalPressure(int pointerIndex, int pos)3149 public final float getHistoricalPressure(int pointerIndex, int pos) { 3150 return nativeGetAxisValue(mNativePtr, AXIS_PRESSURE, pointerIndex, pos); 3151 } 3152 3153 /** 3154 * Returns a historical size coordinate, as per {@link #getSize(int)}, that 3155 * occurred between this event and the previous event for the given pointer. 3156 * Only applies to ACTION_MOVE events. 3157 * 3158 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 3159 * (the first pointer that is down) to {@link #getPointerCount()}-1. 3160 * @param pos Which historical value to return; must be less than 3161 * {@link #getHistorySize} 3162 * 3163 * @see #getHistorySize 3164 * @see #getSize(int) 3165 * @see #AXIS_SIZE 3166 */ getHistoricalSize(int pointerIndex, int pos)3167 public final float getHistoricalSize(int pointerIndex, int pos) { 3168 return nativeGetAxisValue(mNativePtr, AXIS_SIZE, pointerIndex, pos); 3169 } 3170 3171 /** 3172 * Returns a historical touch major axis coordinate, as per {@link #getTouchMajor(int)}, that 3173 * occurred between this event and the previous event for the given pointer. 3174 * Only applies to ACTION_MOVE events. 3175 * 3176 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 3177 * (the first pointer that is down) to {@link #getPointerCount()}-1. 3178 * @param pos Which historical value to return; must be less than 3179 * {@link #getHistorySize} 3180 * 3181 * @see #getHistorySize 3182 * @see #getTouchMajor(int) 3183 * @see #AXIS_TOUCH_MAJOR 3184 */ getHistoricalTouchMajor(int pointerIndex, int pos)3185 public final float getHistoricalTouchMajor(int pointerIndex, int pos) { 3186 return nativeGetAxisValue(mNativePtr, AXIS_TOUCH_MAJOR, pointerIndex, pos); 3187 } 3188 3189 /** 3190 * Returns a historical touch minor axis coordinate, as per {@link #getTouchMinor(int)}, that 3191 * occurred between this event and the previous event for the given pointer. 3192 * Only applies to ACTION_MOVE events. 3193 * 3194 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 3195 * (the first pointer that is down) to {@link #getPointerCount()}-1. 3196 * @param pos Which historical value to return; must be less than 3197 * {@link #getHistorySize} 3198 * 3199 * @see #getHistorySize 3200 * @see #getTouchMinor(int) 3201 * @see #AXIS_TOUCH_MINOR 3202 */ getHistoricalTouchMinor(int pointerIndex, int pos)3203 public final float getHistoricalTouchMinor(int pointerIndex, int pos) { 3204 return nativeGetAxisValue(mNativePtr, AXIS_TOUCH_MINOR, pointerIndex, pos); 3205 } 3206 3207 /** 3208 * Returns a historical tool major axis coordinate, as per {@link #getToolMajor(int)}, that 3209 * occurred between this event and the previous event for the given pointer. 3210 * Only applies to ACTION_MOVE events. 3211 * 3212 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 3213 * (the first pointer that is down) to {@link #getPointerCount()}-1. 3214 * @param pos Which historical value to return; must be less than 3215 * {@link #getHistorySize} 3216 * 3217 * @see #getHistorySize 3218 * @see #getToolMajor(int) 3219 * @see #AXIS_TOOL_MAJOR 3220 */ getHistoricalToolMajor(int pointerIndex, int pos)3221 public final float getHistoricalToolMajor(int pointerIndex, int pos) { 3222 return nativeGetAxisValue(mNativePtr, AXIS_TOOL_MAJOR, pointerIndex, pos); 3223 } 3224 3225 /** 3226 * Returns a historical tool minor axis coordinate, as per {@link #getToolMinor(int)}, that 3227 * occurred between this event and the previous event for the given pointer. 3228 * Only applies to ACTION_MOVE events. 3229 * 3230 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 3231 * (the first pointer that is down) to {@link #getPointerCount()}-1. 3232 * @param pos Which historical value to return; must be less than 3233 * {@link #getHistorySize} 3234 * 3235 * @see #getHistorySize 3236 * @see #getToolMinor(int) 3237 * @see #AXIS_TOOL_MINOR 3238 */ getHistoricalToolMinor(int pointerIndex, int pos)3239 public final float getHistoricalToolMinor(int pointerIndex, int pos) { 3240 return nativeGetAxisValue(mNativePtr, AXIS_TOOL_MINOR, pointerIndex, pos); 3241 } 3242 3243 /** 3244 * Returns a historical orientation coordinate, as per {@link #getOrientation(int)}, that 3245 * occurred between this event and the previous event for the given pointer. 3246 * Only applies to ACTION_MOVE events. 3247 * 3248 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 3249 * (the first pointer that is down) to {@link #getPointerCount()}-1. 3250 * @param pos Which historical value to return; must be less than 3251 * {@link #getHistorySize} 3252 * 3253 * @see #getHistorySize 3254 * @see #getOrientation(int) 3255 * @see #AXIS_ORIENTATION 3256 */ getHistoricalOrientation(int pointerIndex, int pos)3257 public final float getHistoricalOrientation(int pointerIndex, int pos) { 3258 return nativeGetAxisValue(mNativePtr, AXIS_ORIENTATION, pointerIndex, pos); 3259 } 3260 3261 /** 3262 * Returns the historical value of the requested axis, as per {@link #getAxisValue(int, int)}, 3263 * occurred between this event and the previous event for the given pointer. 3264 * Only applies to ACTION_MOVE events. 3265 * 3266 * @param axis The axis identifier for the axis value to retrieve. 3267 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 3268 * (the first pointer that is down) to {@link #getPointerCount()}-1. 3269 * @param pos Which historical value to return; must be less than 3270 * {@link #getHistorySize} 3271 * @return The value of the axis, or 0 if the axis is not available. 3272 * 3273 * @see #AXIS_X 3274 * @see #AXIS_Y 3275 */ getHistoricalAxisValue(int axis, int pointerIndex, int pos)3276 public final float getHistoricalAxisValue(int axis, int pointerIndex, int pos) { 3277 return nativeGetAxisValue(mNativePtr, axis, pointerIndex, pos); 3278 } 3279 3280 /** 3281 * Populates a {@link PointerCoords} object with historical pointer coordinate data, 3282 * as per {@link #getPointerCoords}, that occurred between this event and the previous 3283 * event for the given pointer. 3284 * Only applies to ACTION_MOVE events. 3285 * 3286 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 3287 * (the first pointer that is down) to {@link #getPointerCount()}-1. 3288 * @param pos Which historical value to return; must be less than 3289 * {@link #getHistorySize} 3290 * @param outPointerCoords The pointer coordinate object to populate. 3291 * 3292 * @see #getHistorySize 3293 * @see #getPointerCoords 3294 * @see PointerCoords 3295 */ getHistoricalPointerCoords(int pointerIndex, int pos, PointerCoords outPointerCoords)3296 public final void getHistoricalPointerCoords(int pointerIndex, int pos, 3297 PointerCoords outPointerCoords) { 3298 nativeGetPointerCoords(mNativePtr, pointerIndex, pos, outPointerCoords); 3299 } 3300 3301 /** 3302 * Returns a bitfield indicating which edges, if any, were touched by this 3303 * MotionEvent. For touch events, clients can use this to determine if the 3304 * user's finger was touching the edge of the display. 3305 * 3306 * This property is only set for {@link #ACTION_DOWN} events. 3307 * 3308 * @see #EDGE_LEFT 3309 * @see #EDGE_TOP 3310 * @see #EDGE_RIGHT 3311 * @see #EDGE_BOTTOM 3312 */ getEdgeFlags()3313 public final int getEdgeFlags() { 3314 return nativeGetEdgeFlags(mNativePtr); 3315 } 3316 3317 /** 3318 * Sets the bitfield indicating which edges, if any, were touched by this 3319 * MotionEvent. 3320 * 3321 * @see #getEdgeFlags() 3322 */ setEdgeFlags(int flags)3323 public final void setEdgeFlags(int flags) { 3324 nativeSetEdgeFlags(mNativePtr, flags); 3325 } 3326 3327 /** 3328 * Sets this event's action. 3329 */ setAction(int action)3330 public final void setAction(int action) { 3331 nativeSetAction(mNativePtr, action); 3332 } 3333 3334 /** 3335 * Adjust this event's location. 3336 * @param deltaX Amount to add to the current X coordinate of the event. 3337 * @param deltaY Amount to add to the current Y coordinate of the event. 3338 */ offsetLocation(float deltaX, float deltaY)3339 public final void offsetLocation(float deltaX, float deltaY) { 3340 if (deltaX != 0.0f || deltaY != 0.0f) { 3341 nativeOffsetLocation(mNativePtr, deltaX, deltaY); 3342 } 3343 } 3344 3345 /** 3346 * Set this event's location. Applies {@link #offsetLocation} with a 3347 * delta from the current location to the given new location. 3348 * 3349 * @param x New absolute X location. 3350 * @param y New absolute Y location. 3351 */ setLocation(float x, float y)3352 public final void setLocation(float x, float y) { 3353 float oldX = getX(); 3354 float oldY = getY(); 3355 offsetLocation(x - oldX, y - oldY); 3356 } 3357 3358 /** 3359 * Applies a transformation matrix to all of the points in the event. 3360 * 3361 * @param matrix The transformation matrix to apply. 3362 */ transform(Matrix matrix)3363 public final void transform(Matrix matrix) { 3364 if (matrix == null) { 3365 throw new IllegalArgumentException("matrix must not be null"); 3366 } 3367 3368 nativeTransform(mNativePtr, matrix); 3369 } 3370 3371 /** 3372 * Transforms all of the points in the event directly instead of modifying the event's 3373 * internal transform. 3374 * 3375 * @param matrix The transformation matrix to apply. 3376 * @hide 3377 */ applyTransform(Matrix matrix)3378 public void applyTransform(Matrix matrix) { 3379 if (matrix == null) { 3380 throw new IllegalArgumentException("matrix must not be null"); 3381 } 3382 3383 nativeApplyTransform(mNativePtr, matrix); 3384 } 3385 3386 /** 3387 * Add a new movement to the batch of movements in this event. The event's 3388 * current location, position and size is updated to the new values. 3389 * The current values in the event are added to a list of historical values. 3390 * 3391 * Only applies to {@link #ACTION_MOVE} or {@link #ACTION_HOVER_MOVE} events. 3392 * 3393 * @param eventTime The time stamp (in ms) for this data. 3394 * @param x The new X position. 3395 * @param y The new Y position. 3396 * @param pressure The new pressure. 3397 * @param size The new size. 3398 * @param metaState Meta key state. 3399 */ addBatch(long eventTime, float x, float y, float pressure, float size, int metaState)3400 public final void addBatch(long eventTime, float x, float y, 3401 float pressure, float size, int metaState) { 3402 synchronized (gSharedTempLock) { 3403 ensureSharedTempPointerCapacity(1); 3404 final PointerCoords[] pc = gSharedTempPointerCoords; 3405 pc[0].clear(); 3406 pc[0].x = x; 3407 pc[0].y = y; 3408 pc[0].pressure = pressure; 3409 pc[0].size = size; 3410 3411 nativeAddBatch(mNativePtr, eventTime * NS_PER_MS, pc, metaState); 3412 } 3413 } 3414 3415 /** 3416 * Add a new movement to the batch of movements in this event. The event's 3417 * current location, position and size is updated to the new values. 3418 * The current values in the event are added to a list of historical values. 3419 * 3420 * Only applies to {@link #ACTION_MOVE} or {@link #ACTION_HOVER_MOVE} events. 3421 * 3422 * @param eventTime The time stamp (in ms) for this data. 3423 * @param pointerCoords The new pointer coordinates. 3424 * @param metaState Meta key state. 3425 */ addBatch(long eventTime, PointerCoords[] pointerCoords, int metaState)3426 public final void addBatch(long eventTime, PointerCoords[] pointerCoords, int metaState) { 3427 nativeAddBatch(mNativePtr, eventTime * NS_PER_MS, pointerCoords, metaState); 3428 } 3429 3430 /** 3431 * Adds all of the movement samples of the specified event to this one if 3432 * it is compatible. To be compatible, the event must have the same device id, 3433 * source, display id, action, flags, classification, pointer count, pointer properties. 3434 * 3435 * Only applies to {@link #ACTION_MOVE} or {@link #ACTION_HOVER_MOVE} events. 3436 * 3437 * @param event The event whose movements samples should be added to this one 3438 * if possible. 3439 * @return True if batching was performed or false if batching was not possible. 3440 * @hide 3441 */ 3442 @UnsupportedAppUsage addBatch(MotionEvent event)3443 public final boolean addBatch(MotionEvent event) { 3444 final int action = nativeGetAction(mNativePtr); 3445 if (action != ACTION_MOVE && action != ACTION_HOVER_MOVE) { 3446 return false; 3447 } 3448 if (action != nativeGetAction(event.mNativePtr)) { 3449 return false; 3450 } 3451 3452 if (nativeGetDeviceId(mNativePtr) != nativeGetDeviceId(event.mNativePtr) 3453 || nativeGetSource(mNativePtr) != nativeGetSource(event.mNativePtr) 3454 || nativeGetDisplayId(mNativePtr) != nativeGetDisplayId(event.mNativePtr) 3455 || nativeGetFlags(mNativePtr) != nativeGetFlags(event.mNativePtr) 3456 || nativeGetClassification(mNativePtr) 3457 != nativeGetClassification(event.mNativePtr)) { 3458 return false; 3459 } 3460 3461 final int pointerCount = nativeGetPointerCount(mNativePtr); 3462 if (pointerCount != nativeGetPointerCount(event.mNativePtr)) { 3463 return false; 3464 } 3465 3466 synchronized (gSharedTempLock) { 3467 ensureSharedTempPointerCapacity(Math.max(pointerCount, 2)); 3468 final PointerProperties[] pp = gSharedTempPointerProperties; 3469 final PointerCoords[] pc = gSharedTempPointerCoords; 3470 3471 for (int i = 0; i < pointerCount; i++) { 3472 nativeGetPointerProperties(mNativePtr, i, pp[0]); 3473 nativeGetPointerProperties(event.mNativePtr, i, pp[1]); 3474 if (!pp[0].equals(pp[1])) { 3475 return false; 3476 } 3477 } 3478 3479 final int metaState = nativeGetMetaState(event.mNativePtr); 3480 final int historySize = nativeGetHistorySize(event.mNativePtr); 3481 for (int h = 0; h <= historySize; h++) { 3482 final int historyPos = (h == historySize ? HISTORY_CURRENT : h); 3483 3484 for (int i = 0; i < pointerCount; i++) { 3485 nativeGetPointerCoords(event.mNativePtr, i, historyPos, pc[i]); 3486 } 3487 3488 final long eventTimeNanos = nativeGetEventTimeNanos(event.mNativePtr, historyPos); 3489 nativeAddBatch(mNativePtr, eventTimeNanos, pc, metaState); 3490 } 3491 } 3492 return true; 3493 } 3494 3495 /** 3496 * Returns true if all points in the motion event are completely within the specified bounds. 3497 * @hide 3498 */ isWithinBoundsNoHistory(float left, float top, float right, float bottom)3499 public final boolean isWithinBoundsNoHistory(float left, float top, 3500 float right, float bottom) { 3501 final int pointerCount = nativeGetPointerCount(mNativePtr); 3502 for (int i = 0; i < pointerCount; i++) { 3503 final float x = nativeGetAxisValue(mNativePtr, AXIS_X, i, HISTORY_CURRENT); 3504 final float y = nativeGetAxisValue(mNativePtr, AXIS_Y, i, HISTORY_CURRENT); 3505 if (x < left || x > right || y < top || y > bottom) { 3506 return false; 3507 } 3508 } 3509 return true; 3510 } 3511 clamp(float value, float low, float high)3512 private static final float clamp(float value, float low, float high) { 3513 if (value < low) { 3514 return low; 3515 } else if (value > high) { 3516 return high; 3517 } 3518 return value; 3519 } 3520 3521 /** 3522 * Returns a new motion events whose points have been clamped to the specified bounds. 3523 * @hide 3524 */ clampNoHistory(float left, float top, float right, float bottom)3525 public final MotionEvent clampNoHistory(float left, float top, float right, float bottom) { 3526 MotionEvent ev = obtain(); 3527 synchronized (gSharedTempLock) { 3528 final int pointerCount = nativeGetPointerCount(mNativePtr); 3529 3530 ensureSharedTempPointerCapacity(pointerCount); 3531 final PointerProperties[] pp = gSharedTempPointerProperties; 3532 final PointerCoords[] pc = gSharedTempPointerCoords; 3533 3534 for (int i = 0; i < pointerCount; i++) { 3535 nativeGetPointerProperties(mNativePtr, i, pp[i]); 3536 nativeGetPointerCoords(mNativePtr, i, HISTORY_CURRENT, pc[i]); 3537 pc[i].x = clamp(pc[i].x, left, right); 3538 pc[i].y = clamp(pc[i].y, top, bottom); 3539 } 3540 ev.initialize(nativeGetDeviceId(mNativePtr), nativeGetSource(mNativePtr), 3541 nativeGetDisplayId(mNativePtr), 3542 nativeGetAction(mNativePtr), nativeGetFlags(mNativePtr), 3543 nativeGetEdgeFlags(mNativePtr), nativeGetMetaState(mNativePtr), 3544 nativeGetButtonState(mNativePtr), nativeGetClassification(mNativePtr), 3545 nativeGetXOffset(mNativePtr), nativeGetYOffset(mNativePtr), 3546 nativeGetXPrecision(mNativePtr), nativeGetYPrecision(mNativePtr), 3547 nativeGetDownTimeNanos(mNativePtr), 3548 nativeGetEventTimeNanos(mNativePtr, HISTORY_CURRENT), 3549 pointerCount, pp, pc); 3550 return ev; 3551 } 3552 } 3553 3554 /** 3555 * Gets an integer where each pointer id present in the event is marked as a bit. 3556 * @hide 3557 */ 3558 @UnsupportedAppUsage getPointerIdBits()3559 public final int getPointerIdBits() { 3560 int idBits = 0; 3561 final int pointerCount = nativeGetPointerCount(mNativePtr); 3562 for (int i = 0; i < pointerCount; i++) { 3563 idBits |= 1 << nativeGetPointerId(mNativePtr, i); 3564 } 3565 return idBits; 3566 } 3567 3568 /** 3569 * Splits a motion event such that it includes only a subset of pointer ids. 3570 * @hide 3571 */ 3572 @UnsupportedAppUsage split(int idBits)3573 public final MotionEvent split(int idBits) { 3574 MotionEvent ev = obtain(); 3575 synchronized (gSharedTempLock) { 3576 final int oldPointerCount = nativeGetPointerCount(mNativePtr); 3577 ensureSharedTempPointerCapacity(oldPointerCount); 3578 final PointerProperties[] pp = gSharedTempPointerProperties; 3579 final PointerCoords[] pc = gSharedTempPointerCoords; 3580 final int[] map = gSharedTempPointerIndexMap; 3581 3582 final int oldAction = nativeGetAction(mNativePtr); 3583 final int oldActionMasked = oldAction & ACTION_MASK; 3584 final int oldActionPointerIndex = (oldAction & ACTION_POINTER_INDEX_MASK) 3585 >> ACTION_POINTER_INDEX_SHIFT; 3586 int newActionPointerIndex = -1; 3587 int newPointerCount = 0; 3588 for (int i = 0; i < oldPointerCount; i++) { 3589 nativeGetPointerProperties(mNativePtr, i, pp[newPointerCount]); 3590 final int idBit = 1 << pp[newPointerCount].id; 3591 if ((idBit & idBits) != 0) { 3592 if (i == oldActionPointerIndex) { 3593 newActionPointerIndex = newPointerCount; 3594 } 3595 map[newPointerCount] = i; 3596 newPointerCount += 1; 3597 } 3598 } 3599 3600 if (newPointerCount == 0) { 3601 throw new IllegalArgumentException("idBits did not match any ids in the event"); 3602 } 3603 3604 final int newAction; 3605 if (oldActionMasked == ACTION_POINTER_DOWN || oldActionMasked == ACTION_POINTER_UP) { 3606 if (newActionPointerIndex < 0) { 3607 // An unrelated pointer changed. 3608 newAction = ACTION_MOVE; 3609 } else if (newPointerCount == 1) { 3610 // The first/last pointer went down/up. 3611 newAction = oldActionMasked == ACTION_POINTER_DOWN 3612 ? ACTION_DOWN 3613 : (getFlags() & FLAG_CANCELED) == 0 ? ACTION_UP : ACTION_CANCEL; 3614 } else { 3615 // A secondary pointer went down/up. 3616 newAction = oldActionMasked 3617 | (newActionPointerIndex << ACTION_POINTER_INDEX_SHIFT); 3618 } 3619 } else { 3620 // Simple up/down/cancel/move or other motion action. 3621 newAction = oldAction; 3622 } 3623 3624 final int historySize = nativeGetHistorySize(mNativePtr); 3625 for (int h = 0; h <= historySize; h++) { 3626 final int historyPos = h == historySize ? HISTORY_CURRENT : h; 3627 3628 for (int i = 0; i < newPointerCount; i++) { 3629 nativeGetPointerCoords(mNativePtr, map[i], historyPos, pc[i]); 3630 } 3631 3632 final long eventTimeNanos = nativeGetEventTimeNanos(mNativePtr, historyPos); 3633 if (h == 0) { 3634 ev.initialize(nativeGetDeviceId(mNativePtr), nativeGetSource(mNativePtr), 3635 nativeGetDisplayId(mNativePtr), 3636 newAction, nativeGetFlags(mNativePtr), 3637 nativeGetEdgeFlags(mNativePtr), nativeGetMetaState(mNativePtr), 3638 nativeGetButtonState(mNativePtr), nativeGetClassification(mNativePtr), 3639 nativeGetXOffset(mNativePtr), nativeGetYOffset(mNativePtr), 3640 nativeGetXPrecision(mNativePtr), nativeGetYPrecision(mNativePtr), 3641 nativeGetDownTimeNanos(mNativePtr), eventTimeNanos, 3642 newPointerCount, pp, pc); 3643 } else { 3644 nativeAddBatch(ev.mNativePtr, eventTimeNanos, pc, 0); 3645 } 3646 } 3647 return ev; 3648 } 3649 } 3650 3651 /** 3652 * Calculate new cursor position for events from mouse. This is used to split, clamp and inject 3653 * events. 3654 * 3655 * <p>If the source is mouse, it sets cursor position to the centroid of all pointers because 3656 * InputReader maps multiple fingers on a touchpad to locations around cursor position in screen 3657 * coordinates so that the mouse cursor is at the centroid of all pointers. 3658 * 3659 * <p>If the source is not mouse it sets cursor position to NaN. 3660 */ updateCursorPosition()3661 private void updateCursorPosition() { 3662 if (getSource() != InputDevice.SOURCE_MOUSE) { 3663 setCursorPosition(INVALID_CURSOR_POSITION, INVALID_CURSOR_POSITION); 3664 return; 3665 } 3666 3667 float x = 0; 3668 float y = 0; 3669 3670 final int pointerCount = getPointerCount(); 3671 for (int i = 0; i < pointerCount; ++i) { 3672 x += getX(i); 3673 y += getY(i); 3674 } 3675 3676 // If pointer count is 0, divisions below yield NaN, which is an acceptable result for this 3677 // corner case. 3678 x /= pointerCount; 3679 y /= pointerCount; 3680 setCursorPosition(x, y); 3681 } 3682 3683 @Override toString()3684 public String toString() { 3685 StringBuilder msg = new StringBuilder(); 3686 msg.append("MotionEvent { action=").append(actionToString(getAction())); 3687 appendUnless("0", msg, ", actionButton=", buttonStateToString(getActionButton())); 3688 3689 final int pointerCount = getPointerCount(); 3690 for (int i = 0; i < pointerCount; i++) { 3691 appendUnless(i, msg, ", id[" + i + "]=", getPointerId(i)); 3692 float x = getX(i); 3693 float y = getY(i); 3694 if (!DEBUG_CONCISE_TOSTRING || x != 0f || y != 0f) { 3695 msg.append(", x[").append(i).append("]=").append(x); 3696 msg.append(", y[").append(i).append("]=").append(y); 3697 } 3698 appendUnless(TOOL_TYPE_SYMBOLIC_NAMES.get(TOOL_TYPE_FINGER), 3699 msg, ", toolType[" + i + "]=", toolTypeToString(getToolType(i))); 3700 } 3701 3702 appendUnless("0", msg, ", buttonState=", MotionEvent.buttonStateToString(getButtonState())); 3703 appendUnless(classificationToString(CLASSIFICATION_NONE), msg, ", classification=", 3704 classificationToString(getClassification())); 3705 appendUnless("0", msg, ", metaState=", KeyEvent.metaStateToString(getMetaState())); 3706 appendUnless("0", msg, ", flags=0x", Integer.toHexString(getFlags())); 3707 appendUnless("0", msg, ", edgeFlags=0x", Integer.toHexString(getEdgeFlags())); 3708 appendUnless(1, msg, ", pointerCount=", pointerCount); 3709 appendUnless(0, msg, ", historySize=", getHistorySize()); 3710 msg.append(", eventTime=").append(getEventTime()); 3711 if (!DEBUG_CONCISE_TOSTRING) { 3712 msg.append(", downTime=").append(getDownTime()); 3713 msg.append(", deviceId=").append(getDeviceId()); 3714 msg.append(", source=0x").append(Integer.toHexString(getSource())); 3715 msg.append(", displayId=").append(getDisplayId()); 3716 msg.append(", eventId=").append(getId()); 3717 } 3718 msg.append(" }"); 3719 return msg.toString(); 3720 } 3721 appendUnless(T defValue, StringBuilder sb, String key, T value)3722 private static <T> void appendUnless(T defValue, StringBuilder sb, String key, T value) { 3723 if (DEBUG_CONCISE_TOSTRING && Objects.equals(defValue, value)) return; 3724 sb.append(key).append(value); 3725 } 3726 3727 /** 3728 * Returns a string that represents the symbolic name of the specified unmasked action 3729 * such as "ACTION_DOWN", "ACTION_POINTER_DOWN(3)" or an equivalent numeric constant 3730 * such as "35" if unknown. 3731 * 3732 * @param action The unmasked action. 3733 * @return The symbolic name of the specified action. 3734 * @see #getAction() 3735 */ actionToString(int action)3736 public static String actionToString(int action) { 3737 switch (action) { 3738 case ACTION_DOWN: 3739 return "ACTION_DOWN"; 3740 case ACTION_UP: 3741 return "ACTION_UP"; 3742 case ACTION_CANCEL: 3743 return "ACTION_CANCEL"; 3744 case ACTION_OUTSIDE: 3745 return "ACTION_OUTSIDE"; 3746 case ACTION_MOVE: 3747 return "ACTION_MOVE"; 3748 case ACTION_HOVER_MOVE: 3749 return "ACTION_HOVER_MOVE"; 3750 case ACTION_SCROLL: 3751 return "ACTION_SCROLL"; 3752 case ACTION_HOVER_ENTER: 3753 return "ACTION_HOVER_ENTER"; 3754 case ACTION_HOVER_EXIT: 3755 return "ACTION_HOVER_EXIT"; 3756 case ACTION_BUTTON_PRESS: 3757 return "ACTION_BUTTON_PRESS"; 3758 case ACTION_BUTTON_RELEASE: 3759 return "ACTION_BUTTON_RELEASE"; 3760 } 3761 int index = (action & ACTION_POINTER_INDEX_MASK) >> ACTION_POINTER_INDEX_SHIFT; 3762 switch (action & ACTION_MASK) { 3763 case ACTION_POINTER_DOWN: 3764 return "ACTION_POINTER_DOWN(" + index + ")"; 3765 case ACTION_POINTER_UP: 3766 return "ACTION_POINTER_UP(" + index + ")"; 3767 default: 3768 return Integer.toString(action); 3769 } 3770 } 3771 3772 /** 3773 * Returns a string that represents the symbolic name of the specified axis 3774 * such as "AXIS_X" or an equivalent numeric constant such as "42" if unknown. 3775 * 3776 * @param axis The axis. 3777 * @return The symbolic name of the specified axis. 3778 */ axisToString(int axis)3779 public static String axisToString(int axis) { 3780 String symbolicName = nativeAxisToString(axis); 3781 return symbolicName != null ? LABEL_PREFIX + symbolicName : Integer.toString(axis); 3782 } 3783 3784 /** 3785 * Gets an axis by its symbolic name such as "AXIS_X" or an 3786 * equivalent numeric constant such as "42". 3787 * 3788 * @param symbolicName The symbolic name of the axis. 3789 * @return The axis or -1 if not found. 3790 * @see KeyEvent#keyCodeToString(int) 3791 */ axisFromString(String symbolicName)3792 public static int axisFromString(String symbolicName) { 3793 if (symbolicName.startsWith(LABEL_PREFIX)) { 3794 symbolicName = symbolicName.substring(LABEL_PREFIX.length()); 3795 int axis = nativeAxisFromString(symbolicName); 3796 if (axis >= 0) { 3797 return axis; 3798 } 3799 } 3800 try { 3801 return Integer.parseInt(symbolicName, 10); 3802 } catch (NumberFormatException ex) { 3803 return -1; 3804 } 3805 } 3806 3807 /** 3808 * Returns a string that represents the symbolic name of the specified combined 3809 * button state flags such as "0", "BUTTON_PRIMARY", 3810 * "BUTTON_PRIMARY|BUTTON_SECONDARY" or an equivalent numeric constant such as "0x10000000" 3811 * if unknown. 3812 * 3813 * @param buttonState The button state. 3814 * @return The symbolic name of the specified combined button state flags. 3815 * @hide 3816 */ buttonStateToString(int buttonState)3817 public static String buttonStateToString(int buttonState) { 3818 if (buttonState == 0) { 3819 return "0"; 3820 } 3821 StringBuilder result = null; 3822 int i = 0; 3823 while (buttonState != 0) { 3824 final boolean isSet = (buttonState & 1) != 0; 3825 buttonState >>>= 1; // unsigned shift! 3826 if (isSet) { 3827 final String name = BUTTON_SYMBOLIC_NAMES[i]; 3828 if (result == null) { 3829 if (buttonState == 0) { 3830 return name; 3831 } 3832 result = new StringBuilder(name); 3833 } else { 3834 result.append('|'); 3835 result.append(name); 3836 } 3837 } 3838 i += 1; 3839 } 3840 return result.toString(); 3841 } 3842 3843 /** 3844 * Returns a string that represents the symbolic name of the specified classification. 3845 * 3846 * @param classification The classification type. 3847 * @return The symbolic name of this classification. 3848 * @hide 3849 */ classificationToString(@lassification int classification)3850 public static String classificationToString(@Classification int classification) { 3851 switch (classification) { 3852 case CLASSIFICATION_NONE: 3853 return "NONE"; 3854 case CLASSIFICATION_AMBIGUOUS_GESTURE: 3855 return "AMBIGUOUS_GESTURE"; 3856 case CLASSIFICATION_DEEP_PRESS: 3857 return "DEEP_PRESS"; 3858 3859 } 3860 return "NONE"; 3861 } 3862 3863 /** 3864 * Returns a string that represents the symbolic name of the specified tool type 3865 * such as "TOOL_TYPE_FINGER" or an equivalent numeric constant such as "42" if unknown. 3866 * 3867 * @param toolType The tool type. 3868 * @return The symbolic name of the specified tool type. 3869 * @hide 3870 */ toolTypeToString(int toolType)3871 public static String toolTypeToString(int toolType) { 3872 String symbolicName = TOOL_TYPE_SYMBOLIC_NAMES.get(toolType); 3873 return symbolicName != null ? symbolicName : Integer.toString(toolType); 3874 } 3875 3876 /** 3877 * Checks if a mouse or stylus button (or combination of buttons) is pressed. 3878 * @param button Button (or combination of buttons). 3879 * @return True if specified buttons are pressed. 3880 * 3881 * @see #BUTTON_PRIMARY 3882 * @see #BUTTON_SECONDARY 3883 * @see #BUTTON_TERTIARY 3884 * @see #BUTTON_FORWARD 3885 * @see #BUTTON_BACK 3886 * @see #BUTTON_STYLUS_PRIMARY 3887 * @see #BUTTON_STYLUS_SECONDARY 3888 */ isButtonPressed(int button)3889 public final boolean isButtonPressed(int button) { 3890 if (button == 0) { 3891 return false; 3892 } 3893 return (getButtonState() & button) == button; 3894 } 3895 3896 /** 3897 * Gets the rotation value of the transform for this MotionEvent. 3898 * 3899 * This MotionEvent's rotation can be changed by passing a rotation matrix to 3900 * {@link #transform(Matrix)} to change the coordinate space of this event. 3901 * 3902 * @return the rotation value, or -1 if unknown or invalid. 3903 * @see Surface.Rotation 3904 * @see #createRotateMatrix(int, int, int) 3905 * 3906 * @hide 3907 */ getSurfaceRotation()3908 public @Surface.Rotation int getSurfaceRotation() { 3909 return nativeGetSurfaceRotation(mNativePtr); 3910 } 3911 3912 /** 3913 * Gets a rotation matrix that (when applied to a MotionEvent) will rotate that motion event 3914 * such that the result coordinates end up in the same physical location on a frame whose 3915 * coordinates are rotated by `rotation`. 3916 * 3917 * For example, rotating (0,0) by 90 degrees will move a point from the physical top-left to 3918 * the bottom-left of the 90-degree-rotated frame. 3919 * 3920 * @param rotation the surface rotation of the output matrix 3921 * @param rotatedFrameWidth the width of the rotated frame 3922 * @param rotatedFrameHeight the height of the rotated frame 3923 * 3924 * @see #transform(Matrix) 3925 * @see #getSurfaceRotation() 3926 * @hide 3927 */ createRotateMatrix( @urface.Rotation int rotation, int rotatedFrameWidth, int rotatedFrameHeight)3928 public static Matrix createRotateMatrix( 3929 @Surface.Rotation int rotation, int rotatedFrameWidth, int rotatedFrameHeight) { 3930 if (rotation == Surface.ROTATION_0) { 3931 return new Matrix(Matrix.IDENTITY_MATRIX); 3932 } 3933 // values is row-major 3934 float[] values = null; 3935 if (rotation == Surface.ROTATION_90) { 3936 values = new float[]{0, 1, 0, 3937 -1, 0, rotatedFrameHeight, 3938 0, 0, 1}; 3939 } else if (rotation == Surface.ROTATION_180) { 3940 values = new float[]{-1, 0, rotatedFrameWidth, 3941 0, -1, rotatedFrameHeight, 3942 0, 0, 1}; 3943 } else if (rotation == Surface.ROTATION_270) { 3944 values = new float[]{0, -1, rotatedFrameWidth, 3945 1, 0, 0, 3946 0, 0, 1}; 3947 } 3948 Matrix toOrient = new Matrix(); 3949 toOrient.setValues(values); 3950 return toOrient; 3951 } 3952 3953 public static final @android.annotation.NonNull Parcelable.Creator<MotionEvent> CREATOR 3954 = new Parcelable.Creator<MotionEvent>() { 3955 public MotionEvent createFromParcel(Parcel in) { 3956 in.readInt(); // skip token, we already know this is a MotionEvent 3957 return MotionEvent.createFromParcelBody(in); 3958 } 3959 3960 public MotionEvent[] newArray(int size) { 3961 return new MotionEvent[size]; 3962 } 3963 }; 3964 3965 /** @hide */ createFromParcelBody(Parcel in)3966 public static MotionEvent createFromParcelBody(Parcel in) { 3967 MotionEvent ev = obtain(); 3968 ev.mNativePtr = nativeReadFromParcel(ev.mNativePtr, in); 3969 return ev; 3970 } 3971 3972 /** @hide */ 3973 @Override cancel()3974 public final void cancel() { 3975 setAction(ACTION_CANCEL); 3976 } 3977 writeToParcel(Parcel out, int flags)3978 public void writeToParcel(Parcel out, int flags) { 3979 out.writeInt(PARCEL_TOKEN_MOTION_EVENT); 3980 nativeWriteToParcel(mNativePtr, out); 3981 } 3982 3983 /** 3984 * Transfer object for pointer coordinates. 3985 * 3986 * Objects of this type can be used to specify the pointer coordinates when 3987 * creating new {@link MotionEvent} objects and to query pointer coordinates 3988 * in bulk. 3989 * 3990 * Refer to {@link InputDevice} for information about how different kinds of 3991 * input devices and sources represent pointer coordinates. 3992 */ 3993 public static final class PointerCoords { 3994 private static final int INITIAL_PACKED_AXIS_VALUES = 8; 3995 @UnsupportedAppUsage 3996 private long mPackedAxisBits; 3997 @UnsupportedAppUsage 3998 private float[] mPackedAxisValues; 3999 4000 /** 4001 * Creates a pointer coords object with all axes initialized to zero. 4002 */ PointerCoords()4003 public PointerCoords() { 4004 } 4005 4006 /** 4007 * Creates a pointer coords object as a copy of the 4008 * contents of another pointer coords object. 4009 * 4010 * @param other The pointer coords object to copy. 4011 */ PointerCoords(PointerCoords other)4012 public PointerCoords(PointerCoords other) { 4013 copyFrom(other); 4014 } 4015 4016 /** @hide */ 4017 @UnsupportedAppUsage createArray(int size)4018 public static PointerCoords[] createArray(int size) { 4019 PointerCoords[] array = new PointerCoords[size]; 4020 for (int i = 0; i < size; i++) { 4021 array[i] = new PointerCoords(); 4022 } 4023 return array; 4024 } 4025 4026 /** 4027 * The X component of the pointer movement. 4028 * 4029 * @see MotionEvent#AXIS_X 4030 */ 4031 public float x; 4032 4033 /** 4034 * The Y component of the pointer movement. 4035 * 4036 * @see MotionEvent#AXIS_Y 4037 */ 4038 public float y; 4039 4040 /** 4041 * A normalized value that describes the pressure applied to the device 4042 * by a finger or other tool. 4043 * The pressure generally ranges from 0 (no pressure at all) to 1 (normal pressure), 4044 * although values higher than 1 may be generated depending on the calibration of 4045 * the input device. 4046 * 4047 * @see MotionEvent#AXIS_PRESSURE 4048 */ 4049 public float pressure; 4050 4051 /** 4052 * A normalized value that describes the approximate size of the pointer touch area 4053 * in relation to the maximum detectable size of the device. 4054 * It represents some approximation of the area of the screen being 4055 * pressed; the actual value in pixels corresponding to the 4056 * touch is normalized with the device specific range of values 4057 * and scaled to a value between 0 and 1. The value of size can be used to 4058 * determine fat touch events. 4059 * 4060 * @see MotionEvent#AXIS_SIZE 4061 */ 4062 public float size; 4063 4064 /** 4065 * The length of the major axis of an ellipse that describes the touch area at 4066 * the point of contact. 4067 * If the device is a touch screen, the length is reported in pixels, otherwise it is 4068 * reported in device-specific units. 4069 * 4070 * @see MotionEvent#AXIS_TOUCH_MAJOR 4071 */ 4072 public float touchMajor; 4073 4074 /** 4075 * The length of the minor axis of an ellipse that describes the touch area at 4076 * the point of contact. 4077 * If the device is a touch screen, the length is reported in pixels, otherwise it is 4078 * reported in device-specific units. 4079 * 4080 * @see MotionEvent#AXIS_TOUCH_MINOR 4081 */ 4082 public float touchMinor; 4083 4084 /** 4085 * The length of the major axis of an ellipse that describes the size of 4086 * the approaching tool. 4087 * The tool area represents the estimated size of the finger or pen that is 4088 * touching the device independent of its actual touch area at the point of contact. 4089 * If the device is a touch screen, the length is reported in pixels, otherwise it is 4090 * reported in device-specific units. 4091 * 4092 * @see MotionEvent#AXIS_TOOL_MAJOR 4093 */ 4094 public float toolMajor; 4095 4096 /** 4097 * The length of the minor axis of an ellipse that describes the size of 4098 * the approaching tool. 4099 * The tool area represents the estimated size of the finger or pen that is 4100 * touching the device independent of its actual touch area at the point of contact. 4101 * If the device is a touch screen, the length is reported in pixels, otherwise it is 4102 * reported in device-specific units. 4103 * 4104 * @see MotionEvent#AXIS_TOOL_MINOR 4105 */ 4106 public float toolMinor; 4107 4108 /** 4109 * The orientation of the touch area and tool area in radians clockwise from vertical. 4110 * An angle of 0 radians indicates that the major axis of contact is oriented 4111 * upwards, is perfectly circular or is of unknown orientation. A positive angle 4112 * indicates that the major axis of contact is oriented to the right. A negative angle 4113 * indicates that the major axis of contact is oriented to the left. 4114 * The full range is from -PI/2 radians (finger pointing fully left) to PI/2 radians 4115 * (finger pointing fully right). 4116 * 4117 * @see MotionEvent#AXIS_ORIENTATION 4118 */ 4119 public float orientation; 4120 4121 /** 4122 * The movement of x position of a motion event. 4123 * 4124 * @see MotionEvent#AXIS_RELATIVE_X 4125 * @hide 4126 */ 4127 public float relativeX; 4128 4129 /** 4130 * The movement of y position of a motion event. 4131 * 4132 * @see MotionEvent#AXIS_RELATIVE_Y 4133 * @hide 4134 */ 4135 public float relativeY; 4136 4137 /** 4138 * Clears the contents of this object. 4139 * Resets all axes to zero. 4140 */ clear()4141 public void clear() { 4142 mPackedAxisBits = 0; 4143 4144 x = 0; 4145 y = 0; 4146 pressure = 0; 4147 size = 0; 4148 touchMajor = 0; 4149 touchMinor = 0; 4150 toolMajor = 0; 4151 toolMinor = 0; 4152 orientation = 0; 4153 relativeX = 0; 4154 relativeY = 0; 4155 } 4156 4157 /** 4158 * Copies the contents of another pointer coords object. 4159 * 4160 * @param other The pointer coords object to copy. 4161 */ copyFrom(PointerCoords other)4162 public void copyFrom(PointerCoords other) { 4163 final long bits = other.mPackedAxisBits; 4164 mPackedAxisBits = bits; 4165 if (bits != 0) { 4166 final float[] otherValues = other.mPackedAxisValues; 4167 final int count = Long.bitCount(bits); 4168 float[] values = mPackedAxisValues; 4169 if (values == null || count > values.length) { 4170 values = new float[otherValues.length]; 4171 mPackedAxisValues = values; 4172 } 4173 System.arraycopy(otherValues, 0, values, 0, count); 4174 } 4175 4176 x = other.x; 4177 y = other.y; 4178 pressure = other.pressure; 4179 size = other.size; 4180 touchMajor = other.touchMajor; 4181 touchMinor = other.touchMinor; 4182 toolMajor = other.toolMajor; 4183 toolMinor = other.toolMinor; 4184 orientation = other.orientation; 4185 relativeX = other.relativeX; 4186 relativeY = other.relativeY; 4187 } 4188 4189 /** 4190 * Gets the value associated with the specified axis. 4191 * 4192 * @param axis The axis identifier for the axis value to retrieve. 4193 * @return The value associated with the axis, or 0 if none. 4194 * 4195 * @see MotionEvent#AXIS_X 4196 * @see MotionEvent#AXIS_Y 4197 */ getAxisValue(int axis)4198 public float getAxisValue(int axis) { 4199 switch (axis) { 4200 case AXIS_X: 4201 return x; 4202 case AXIS_Y: 4203 return y; 4204 case AXIS_PRESSURE: 4205 return pressure; 4206 case AXIS_SIZE: 4207 return size; 4208 case AXIS_TOUCH_MAJOR: 4209 return touchMajor; 4210 case AXIS_TOUCH_MINOR: 4211 return touchMinor; 4212 case AXIS_TOOL_MAJOR: 4213 return toolMajor; 4214 case AXIS_TOOL_MINOR: 4215 return toolMinor; 4216 case AXIS_ORIENTATION: 4217 return orientation; 4218 case AXIS_RELATIVE_X: 4219 return relativeX; 4220 case AXIS_RELATIVE_Y: 4221 return relativeY; 4222 default: { 4223 if (axis < 0 || axis > 63) { 4224 throw new IllegalArgumentException("Axis out of range."); 4225 } 4226 final long bits = mPackedAxisBits; 4227 final long axisBit = 0x8000000000000000L >>> axis; 4228 if ((bits & axisBit) == 0) { 4229 return 0; 4230 } 4231 final int index = Long.bitCount(bits & ~(0xFFFFFFFFFFFFFFFFL >>> axis)); 4232 return mPackedAxisValues[index]; 4233 } 4234 } 4235 } 4236 4237 /** 4238 * Sets the value associated with the specified axis. 4239 * 4240 * @param axis The axis identifier for the axis value to assign. 4241 * @param value The value to set. 4242 * 4243 * @see MotionEvent#AXIS_X 4244 * @see MotionEvent#AXIS_Y 4245 */ setAxisValue(int axis, float value)4246 public void setAxisValue(int axis, float value) { 4247 switch (axis) { 4248 case AXIS_X: 4249 x = value; 4250 break; 4251 case AXIS_Y: 4252 y = value; 4253 break; 4254 case AXIS_PRESSURE: 4255 pressure = value; 4256 break; 4257 case AXIS_SIZE: 4258 size = value; 4259 break; 4260 case AXIS_TOUCH_MAJOR: 4261 touchMajor = value; 4262 break; 4263 case AXIS_TOUCH_MINOR: 4264 touchMinor = value; 4265 break; 4266 case AXIS_TOOL_MAJOR: 4267 toolMajor = value; 4268 break; 4269 case AXIS_TOOL_MINOR: 4270 toolMinor = value; 4271 break; 4272 case AXIS_ORIENTATION: 4273 orientation = value; 4274 break; 4275 case AXIS_RELATIVE_X: 4276 relativeX = value; 4277 break; 4278 case AXIS_RELATIVE_Y: 4279 relativeY = value; 4280 break; 4281 default: { 4282 if (axis < 0 || axis > 63) { 4283 throw new IllegalArgumentException("Axis out of range."); 4284 } 4285 final long bits = mPackedAxisBits; 4286 final long axisBit = 0x8000000000000000L >>> axis; 4287 final int index = Long.bitCount(bits & ~(0xFFFFFFFFFFFFFFFFL >>> axis)); 4288 float[] values = mPackedAxisValues; 4289 if ((bits & axisBit) == 0) { 4290 if (values == null) { 4291 values = new float[INITIAL_PACKED_AXIS_VALUES]; 4292 mPackedAxisValues = values; 4293 } else { 4294 final int count = Long.bitCount(bits); 4295 if (count < values.length) { 4296 if (index != count) { 4297 System.arraycopy(values, index, values, index + 1, 4298 count - index); 4299 } 4300 } else { 4301 float[] newValues = new float[count * 2]; 4302 System.arraycopy(values, 0, newValues, 0, index); 4303 System.arraycopy(values, index, newValues, index + 1, 4304 count - index); 4305 values = newValues; 4306 mPackedAxisValues = values; 4307 } 4308 } 4309 mPackedAxisBits = bits | axisBit; 4310 } 4311 values[index] = value; 4312 } 4313 } 4314 } 4315 } 4316 4317 /** 4318 * Transfer object for pointer properties. 4319 * 4320 * Objects of this type can be used to specify the pointer id and tool type 4321 * when creating new {@link MotionEvent} objects and to query pointer properties in bulk. 4322 */ 4323 public static final class PointerProperties { 4324 /** 4325 * Creates a pointer properties object with an invalid pointer id. 4326 */ PointerProperties()4327 public PointerProperties() { 4328 clear(); 4329 } 4330 4331 /** 4332 * Creates a pointer properties object as a copy of the contents of 4333 * another pointer properties object. 4334 * @param other 4335 */ PointerProperties(PointerProperties other)4336 public PointerProperties(PointerProperties other) { 4337 copyFrom(other); 4338 } 4339 4340 /** @hide */ 4341 @UnsupportedAppUsage createArray(int size)4342 public static PointerProperties[] createArray(int size) { 4343 PointerProperties[] array = new PointerProperties[size]; 4344 for (int i = 0; i < size; i++) { 4345 array[i] = new PointerProperties(); 4346 } 4347 return array; 4348 } 4349 4350 /** 4351 * The pointer id. 4352 * Initially set to {@link #INVALID_POINTER_ID} (-1). 4353 * 4354 * @see MotionEvent#getPointerId(int) 4355 */ 4356 public int id; 4357 4358 /** 4359 * The pointer tool type. 4360 * Initially set to 0. 4361 * 4362 * @see MotionEvent#getToolType(int) 4363 */ 4364 public int toolType; 4365 4366 /** 4367 * Resets the pointer properties to their initial values. 4368 */ clear()4369 public void clear() { 4370 id = INVALID_POINTER_ID; 4371 toolType = TOOL_TYPE_UNKNOWN; 4372 } 4373 4374 /** 4375 * Copies the contents of another pointer properties object. 4376 * 4377 * @param other The pointer properties object to copy. 4378 */ copyFrom(PointerProperties other)4379 public void copyFrom(PointerProperties other) { 4380 id = other.id; 4381 toolType = other.toolType; 4382 } 4383 4384 @Override equals(@ullable Object other)4385 public boolean equals(@Nullable Object other) { 4386 if (other instanceof PointerProperties) { 4387 return equals((PointerProperties)other); 4388 } 4389 return false; 4390 } 4391 equals(PointerProperties other)4392 private boolean equals(PointerProperties other) { 4393 return other != null && id == other.id && toolType == other.toolType; 4394 } 4395 4396 @Override hashCode()4397 public int hashCode() { 4398 return id | (toolType << 8); 4399 } 4400 } 4401 } 4402