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