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