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