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