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