MotionEvent.java revision 6f2fba428ca5e77a26d991ad728e346cc47609ee
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. This 27 * class may hold either absolute or relative movements, depending on what 28 * it is being used for. 29 * <p> 30 * On pointing devices with source class {@link InputDevice#SOURCE_CLASS_POINTER} 31 * such as touch screens, the pointer coordinates specify absolute 32 * positions such as view X/Y coordinates. Each complete gesture is represented 33 * by a sequence of motion events with actions that describe pointer state transitions 34 * and movements. A gesture starts with a motion event with {@link #ACTION_DOWN} 35 * that provides the location of the first pointer down. As each additional 36 * pointer that goes down or up, the framework will generate a motion event with 37 * {@link #ACTION_POINTER_DOWN} or {@link #ACTION_POINTER_UP} accordingly. 38 * Pointer movements are described by motion events with {@link #ACTION_MOVE}. 39 * Finally, a gesture end either when the final pointer goes up as represented 40 * by a motion event with {@link #ACTION_UP} or when gesture is canceled 41 * with {@link #ACTION_CANCEL}. 42 * </p><p> 43 * On trackball devices with source class {@link InputDevice#SOURCE_CLASS_TRACKBALL}, 44 * the pointer coordinates specify relative movements as X/Y deltas. 45 * A trackball gesture consists of a sequence of movements described by motion 46 * events with {@link #ACTION_MOVE} interspersed with occasional {@link #ACTION_DOWN} 47 * or {@link #ACTION_UP} motion events when the trackball button is pressed or released. 48 * </p><p> 49 * On joystick devices with source class {@link InputDevice#SOURCE_CLASS_JOYSTICK}, 50 * the pointer coordinates specify the absolute position of the joystick axes. 51 * The joystick axis values are normalized to a range of -1.0 to 1.0 where 0.0 corresponds 52 * to the center position. More information about the set of available axes and the 53 * range of motion can be obtained using {@link InputDevice#getMotionRange}. 54 * </p><p> 55 * Motion events always report movements for all pointers at once. The number 56 * of pointers only ever changes by one as individual pointers go up and down, 57 * except when the gesture is canceled. 58 * </p><p> 59 * The order in which individual pointers appear within a motion event can change 60 * from one event to the next. Use the {@link #getPointerId(int)} method to obtain a 61 * pointer id to track pointers across motion events in a gesture. Then for 62 * successive motion events, use the {@link #findPointerIndex(int)} method to obtain 63 * the pointer index for a given pointer id in that motion event. 64 * </p><p> 65 * For efficiency, motion events with {@link #ACTION_MOVE} may batch together 66 * multiple movement samples within a single object. The most current 67 * pointer coordinates are available using {@link #getX(int)} and {@link #getY(int)}. 68 * Earlier coordinates within the batch are accessed using {@link #getHistoricalX(int, int)} 69 * and {@link #getHistoricalY(int, int)}. The coordinates are "historical" only 70 * insofar as they are older than the current coordinates in the batch; however, 71 * they are still distinct from any other coordinates reported in prior motion events. 72 * To process all coordinates in the batch in time order, first consume the historical 73 * coordinates then consume the current coordinates. 74 * </p><p> 75 * Example: Consuming all samples for all pointers in a motion event in time order. 76 * </p><p><pre><code> 77 * void printSamples(MotionEvent ev) { 78 * final int historySize = ev.getHistorySize(); 79 * final int pointerCount = ev.getPointerCount(); 80 * for (int h = 0; h < historySize; h++) { 81 * System.out.printf("At time %d:", ev.getHistoricalEventTime(h)); 82 * for (int p = 0; p < pointerCount; p++) { 83 * System.out.printf(" pointer %d: (%f,%f)", 84 * ev.getPointerId(p), ev.getHistoricalX(p, h), ev.getHistoricalY(p, h)); 85 * } 86 * } 87 * System.out.printf("At time %d:", ev.getEventTime()); 88 * for (int p = 0; p < pointerCount; p++) { 89 * System.out.printf(" pointer %d: (%f,%f)", 90 * ev.getPointerId(p), ev.getX(p), ev.getY(p)); 91 * } 92 * } 93 * </code></pre></p><p> 94 * In general, the framework cannot guarantee that the motion events it delivers 95 * to a view always constitute a complete motion sequences since some events may be dropped 96 * or modified by containing views before they are delivered. The view implementation 97 * should be prepared to handle {@link #ACTION_CANCEL} and should tolerate anomalous 98 * situations such as receiving a new {@link #ACTION_DOWN} without first having 99 * received an {@link #ACTION_UP} for the prior gesture. 100 * </p><p> 101 * Refer to {@link InputDevice} for more information about how different kinds of 102 * input devices and sources represent pointer coordinates. 103 * </p> 104 */ 105public final class MotionEvent extends InputEvent implements Parcelable { 106 private static final long NS_PER_MS = 1000000; 107 private static final boolean TRACK_RECYCLED_LOCATION = false; 108 109 /** 110 * Bit mask of the parts of the action code that are the action itself. 111 */ 112 public static final int ACTION_MASK = 0xff; 113 114 /** 115 * Constant for {@link #getAction}: A pressed gesture has started, the 116 * motion contains the initial starting location. 117 */ 118 public static final int ACTION_DOWN = 0; 119 120 /** 121 * Constant for {@link #getAction}: A pressed gesture has finished, the 122 * motion contains the final release location as well as any intermediate 123 * points since the last down or move event. 124 */ 125 public static final int ACTION_UP = 1; 126 127 /** 128 * Constant for {@link #getAction}: A change has happened during a 129 * press gesture (between {@link #ACTION_DOWN} and {@link #ACTION_UP}). 130 * The motion contains the most recent point, as well as any intermediate 131 * points since the last down or move event. 132 */ 133 public static final int ACTION_MOVE = 2; 134 135 /** 136 * Constant for {@link #getAction}: The current gesture has been aborted. 137 * You will not receive any more points in it. You should treat this as 138 * an up event, but not perform any action that you normally would. 139 */ 140 public static final int ACTION_CANCEL = 3; 141 142 /** 143 * Constant for {@link #getAction}: A movement has happened outside of the 144 * normal bounds of the UI element. This does not provide a full gesture, 145 * but only the initial location of the movement/touch. 146 */ 147 public static final int ACTION_OUTSIDE = 4; 148 149 /** 150 * A non-primary pointer has gone down. The bits in 151 * {@link #ACTION_POINTER_ID_MASK} indicate which pointer changed. 152 */ 153 public static final int ACTION_POINTER_DOWN = 5; 154 155 /** 156 * A non-primary pointer has gone up. The bits in 157 * {@link #ACTION_POINTER_ID_MASK} indicate which pointer changed. 158 */ 159 public static final int ACTION_POINTER_UP = 6; 160 161 /** 162 * Bits in the action code that represent a pointer index, used with 163 * {@link #ACTION_POINTER_DOWN} and {@link #ACTION_POINTER_UP}. Shifting 164 * down by {@link #ACTION_POINTER_INDEX_SHIFT} provides the actual pointer 165 * index where the data for the pointer going up or down can be found; you can 166 * get its identifier with {@link #getPointerId(int)} and the actual 167 * data with {@link #getX(int)} etc. 168 */ 169 public static final int ACTION_POINTER_INDEX_MASK = 0xff00; 170 171 /** 172 * Bit shift for the action bits holding the pointer index as 173 * defined by {@link #ACTION_POINTER_INDEX_MASK}. 174 */ 175 public static final int ACTION_POINTER_INDEX_SHIFT = 8; 176 177 /** 178 * @deprecated Use {@link #ACTION_POINTER_INDEX_MASK} to retrieve the 179 * data index associated with {@link #ACTION_POINTER_DOWN}. 180 */ 181 @Deprecated 182 public static final int ACTION_POINTER_1_DOWN = ACTION_POINTER_DOWN | 0x0000; 183 184 /** 185 * @deprecated Use {@link #ACTION_POINTER_INDEX_MASK} to retrieve the 186 * data index associated with {@link #ACTION_POINTER_DOWN}. 187 */ 188 @Deprecated 189 public static final int ACTION_POINTER_2_DOWN = ACTION_POINTER_DOWN | 0x0100; 190 191 /** 192 * @deprecated Use {@link #ACTION_POINTER_INDEX_MASK} to retrieve the 193 * data index associated with {@link #ACTION_POINTER_DOWN}. 194 */ 195 @Deprecated 196 public static final int ACTION_POINTER_3_DOWN = ACTION_POINTER_DOWN | 0x0200; 197 198 /** 199 * @deprecated Use {@link #ACTION_POINTER_INDEX_MASK} to retrieve the 200 * data index associated with {@link #ACTION_POINTER_UP}. 201 */ 202 @Deprecated 203 public static final int ACTION_POINTER_1_UP = ACTION_POINTER_UP | 0x0000; 204 205 /** 206 * @deprecated Use {@link #ACTION_POINTER_INDEX_MASK} to retrieve the 207 * data index associated with {@link #ACTION_POINTER_UP}. 208 */ 209 @Deprecated 210 public static final int ACTION_POINTER_2_UP = ACTION_POINTER_UP | 0x0100; 211 212 /** 213 * @deprecated Use {@link #ACTION_POINTER_INDEX_MASK} to retrieve the 214 * data index associated with {@link #ACTION_POINTER_UP}. 215 */ 216 @Deprecated 217 public static final int ACTION_POINTER_3_UP = ACTION_POINTER_UP | 0x0200; 218 219 /** 220 * @deprecated Renamed to {@link #ACTION_POINTER_INDEX_MASK} to match 221 * the actual data contained in these bits. 222 */ 223 @Deprecated 224 public static final int ACTION_POINTER_ID_MASK = 0xff00; 225 226 /** 227 * @deprecated Renamed to {@link #ACTION_POINTER_INDEX_SHIFT} to match 228 * the actual data contained in these bits. 229 */ 230 @Deprecated 231 public static final int ACTION_POINTER_ID_SHIFT = 8; 232 233 /** 234 * This flag indicates that the window that received this motion event is partly 235 * or wholly obscured by another visible window above it. This flag is set to true 236 * even if the event did not directly pass through the obscured area. 237 * A security sensitive application can check this flag to identify situations in which 238 * a malicious application may have covered up part of its content for the purpose 239 * of misleading the user or hijacking touches. An appropriate response might be 240 * to drop the suspect touches or to take additional precautions to confirm the user's 241 * actual intent. 242 */ 243 public static final int FLAG_WINDOW_IS_OBSCURED = 0x1; 244 245 /** 246 * Flag indicating the motion event intersected the top edge of the screen. 247 */ 248 public static final int EDGE_TOP = 0x00000001; 249 250 /** 251 * Flag indicating the motion event intersected the bottom edge of the screen. 252 */ 253 public static final int EDGE_BOTTOM = 0x00000002; 254 255 /** 256 * Flag indicating the motion event intersected the left edge of the screen. 257 */ 258 public static final int EDGE_LEFT = 0x00000004; 259 260 /** 261 * Flag indicating the motion event intersected the right edge of the screen. 262 */ 263 public static final int EDGE_RIGHT = 0x00000008; 264 265 /** 266 * Constant used to identify the X axis of a motion event. 267 * <p> 268 * <ul> 269 * <li>For a touch screen, reports the absolute X screen position of the center of 270 * the touch contact area. The units are display pixels. 271 * <li>For a touch pad, reports the absolute X surface position of the center of the touch 272 * contact area. The units are device-specific because the touch pad is not necessarily 273 * associated with a display. Use {@link InputDevice#getMotionRange(int)} to query 274 * the effective range of values. 275 * <li>For a mouse, reports the absolute X screen position of the mouse pointer. 276 * The units are display pixels. 277 * <li>For a trackball, reports the relative horizontal displacement of the trackball. 278 * The value is normalized to a range from -1.0 (left) to 1.0 (right). 279 * <li>For a joystick, reports the absolute X position of the joystick. 280 * The value is normalized to a range from -1.0 (left) to 1.0 (right). 281 * </ul> 282 * </p> 283 * 284 * @see #getX(int) 285 * @see #getHistoricalX(int, int) 286 * @see MotionEvent.PointerCoords#x 287 * @see InputDevice#getMotionRange 288 */ 289 public static final int AXIS_X = 0; 290 291 /** 292 * Constant used to identify the Y axis of a motion event. 293 * <p> 294 * <ul> 295 * <li>For a touch screen, reports the absolute Y screen position of the center of 296 * the touch contact area. The units are display pixels. 297 * <li>For a touch pad, reports the absolute Y surface position of the center of the touch 298 * contact area. The units are device-dependent; use {@link InputDevice#getMotionRange(int)} 299 * to query the effective range of values. 300 * <li>For a mouse, reports the absolute Y screen position of the mouse pointer. 301 * The units are display pixels. 302 * <li>For a trackball, reports the relative vertical displacement of the trackball. 303 * The value is normalized to a range from -1.0 (up) to 1.0 (down). 304 * <li>For a joystick, reports the absolute Y position of the joystick. 305 * The value is normalized to a range from -1.0 (up or far) to 1.0 (down or near). 306 * </ul> 307 * </p> 308 * 309 * @see #getY(int) 310 * @see #getHistoricalY(int, int) 311 * @see MotionEvent.PointerCoords#y 312 * @see InputDevice#getMotionRange 313 */ 314 public static final int AXIS_Y = 1; 315 316 /** 317 * Constant used to identify the Pressure axis of a motion event. 318 * <p> 319 * <ul> 320 * <li>For a touch screen or touch pad, reports the approximate pressure applied to the device 321 * by a finger or other tool. The value is normalized to a range from 322 * 0 (no pressure at all) to 1 (normal pressure), although values higher than 1 323 * may be generated depending on the calibration of the input device. 324 * <li>For a trackball, the value is set to 1 if the trackball button is pressed 325 * or 0 otherwise. 326 * <li>For a mouse, the value is set to 1 if the primary mouse button is pressed 327 * or 0 otherwise. 328 * </ul> 329 * </p> 330 * 331 * @see #getPressure(int) 332 * @see #getHistoricalPressure(int, int) 333 * @see MotionEvent.PointerCoords#pressure 334 * @see InputDevice#getMotionRange 335 */ 336 public static final int AXIS_PRESSURE = 2; 337 338 /** 339 * Constant used to identify the Size axis of a motion event. 340 * <p> 341 * <ul> 342 * <li>For a touch screen or touch pad, reports the approximate size of the contact area in 343 * relation to the maximum detectable size for the device. The value is normalized 344 * to a range from 0 (smallest detectable size) to 1 (largest detectable size), 345 * although it is not a linear scale. This value is of very limited use. 346 * To obtain calibrated size information, use 347 * {@link #AXIS_TOUCH_MAJOR} or {@link #AXIS_TOOL_MAJOR}. 348 * </ul> 349 * </p> 350 * 351 * @see #getSize(int) 352 * @see #getHistoricalSize(int, int) 353 * @see MotionEvent.PointerCoords#size 354 * @see InputDevice#getMotionRange 355 */ 356 public static final int AXIS_SIZE = 3; 357 358 /** 359 * Constant used to identify the TouchMajor axis of a motion event. 360 * <p> 361 * <ul> 362 * <li>For a touch screen, reports the length of the major axis of an ellipse that 363 * represents the touch area at the point of contact. 364 * The units are display pixels. 365 * <li>For a touch pad, reports the length of the major axis of an ellipse that 366 * represents the touch area at the point of contact. 367 * The units are device-dependent; use {@link InputDevice#getMotionRange(int)} 368 * to query the effective range of values. 369 * </ul> 370 * </p> 371 * 372 * @see #getTouchMajor(int) 373 * @see #getHistoricalTouchMajor(int, int) 374 * @see MotionEvent.PointerCoords#touchMajor 375 * @see InputDevice#getMotionRange 376 */ 377 public static final int AXIS_TOUCH_MAJOR = 4; 378 379 /** 380 * Constant used to identify the TouchMinor axis of a motion event. 381 * <p> 382 * <ul> 383 * <li>For a touch screen, reports the length of the minor axis of an ellipse that 384 * represents the touch area at the point of contact. 385 * The units are display pixels. 386 * <li>For a touch pad, reports the length of the minor axis of an ellipse that 387 * represents the touch area at the point of contact. 388 * The units are device-dependent; use {@link InputDevice#getMotionRange(int)} 389 * to query the effective range of values. 390 * </ul> 391 * </p><p> 392 * When the touch is circular, the major and minor axis lengths will be equal to one another. 393 * </p> 394 * 395 * @see #getTouchMinor(int) 396 * @see #getHistoricalTouchMinor(int, int) 397 * @see MotionEvent.PointerCoords#touchMinor 398 * @see InputDevice#getMotionRange 399 */ 400 public static final int AXIS_TOUCH_MINOR = 5; 401 402 /** 403 * Constant used to identify the ToolMajor axis of a motion event. 404 * <p> 405 * <ul> 406 * <li>For a touch screen, reports the length of the major axis of an ellipse that 407 * represents the size of the approaching finger or tool used to make contact. 408 * <li>For a touch pad, reports the length of the major axis of an ellipse that 409 * represents the size of the approaching finger or tool used to make contact. 410 * The units are device-dependent; use {@link InputDevice#getMotionRange(int)} 411 * to query the effective range of values. 412 * </ul> 413 * </p><p> 414 * When the touch is circular, the major and minor axis lengths will be equal to one another. 415 * </p><p> 416 * The tool size may be larger than the touch size since the tool may not be fully 417 * in contact with the touch sensor. 418 * </p> 419 * 420 * @see #getToolMajor(int) 421 * @see #getHistoricalToolMajor(int, int) 422 * @see MotionEvent.PointerCoords#toolMajor 423 * @see InputDevice#getMotionRange 424 */ 425 public static final int AXIS_TOOL_MAJOR = 6; 426 427 /** 428 * Constant used to identify the ToolMinor axis of a motion event. 429 * <p> 430 * <ul> 431 * <li>For a touch screen, reports the length of the minor axis of an ellipse that 432 * represents the size of the approaching finger or tool used to make contact. 433 * <li>For a touch pad, reports the length of the minor axis of an ellipse that 434 * represents the size of the approaching finger or tool used to make contact. 435 * The units are device-dependent; use {@link InputDevice#getMotionRange(int)} 436 * to query the effective range of values. 437 * </ul> 438 * </p><p> 439 * When the touch is circular, the major and minor axis lengths will be equal to one another. 440 * </p><p> 441 * The tool size may be larger than the touch size since the tool may not be fully 442 * in contact with the touch sensor. 443 * </p> 444 * 445 * @see #getToolMinor(int) 446 * @see #getHistoricalToolMinor(int, int) 447 * @see MotionEvent.PointerCoords#toolMinor 448 * @see InputDevice#getMotionRange 449 */ 450 public static final int AXIS_TOOL_MINOR = 7; 451 452 /** 453 * Constant used to identify the Orientation axis of a motion event. 454 * <p> 455 * <ul> 456 * <li>For a touch screen or touch pad, reports the orientation of the finger 457 * or tool in radians relative to the vertical plane of the device. 458 * An angle of 0 radians indicates that the major axis of contact is oriented 459 * upwards, is perfectly circular or is of unknown orientation. A positive angle 460 * indicates that the major axis of contact is oriented to the right. A negative angle 461 * indicates that the major axis of contact is oriented to the left. 462 * The full range is from -PI/2 radians (finger pointing fully left) to PI/2 radians 463 * (finger pointing fully right). 464 * </ul> 465 * </p> 466 * 467 * @see #getOrientation(int) 468 * @see #getHistoricalOrientation(int, int) 469 * @see MotionEvent.PointerCoords#orientation 470 * @see InputDevice#getMotionRange 471 */ 472 public static final int AXIS_ORIENTATION = 8; 473 474 /** 475 * Constant used to identify the Vertical Scroll axis of a motion event. 476 * <p> 477 * <ul> 478 * <li>For a mouse, reports the relative movement of vertical scroll wheel. 479 * The value is normalized to a range from -1.0 (up) to 1.0 (down). 480 * </ul> 481 * </p><p> 482 * This axis should be used to scroll views vertically. 483 * </p> 484 * 485 * @see #getAxisValue(int, int) 486 * @see #getHistoricalAxisValue(int, int, int) 487 * @see MotionEvent.PointerCoords#getAxisValue(int) 488 * @see InputDevice#getMotionRange 489 */ 490 public static final int AXIS_VSCROLL = 9; 491 492 /** 493 * Constant used to identify the Horizontal Scroll axis of a motion event. 494 * <p> 495 * <ul> 496 * <li>For a mouse, reports the relative movement of horizontal scroll wheel. 497 * The value is normalized to a range from -1.0 (left) to 1.0 (right). 498 * </ul> 499 * </p><p> 500 * This axis should be used to scroll views horizontally. 501 * </p> 502 * 503 * @see #getAxisValue(int, int) 504 * @see #getHistoricalAxisValue(int, int, int) 505 * @see MotionEvent.PointerCoords#getAxisValue(int) 506 * @see InputDevice#getMotionRange 507 */ 508 public static final int AXIS_HSCROLL = 10; 509 510 /** 511 * Constant used to identify the Z axis of a motion event. 512 * <p> 513 * <ul> 514 * <li>For a joystick, reports the absolute Z position of the joystick. 515 * The value is normalized to a range from -1.0 (high) to 1.0 (low). 516 * <em>On game pads with two analog joysticks, this axis is often reinterpreted 517 * to report the absolute X position of the second joystick instead.</em> 518 * </ul> 519 * </p> 520 * 521 * @see #getAxisValue(int, int) 522 * @see #getHistoricalAxisValue(int, int, int) 523 * @see MotionEvent.PointerCoords#getAxisValue(int) 524 * @see InputDevice#getMotionRange 525 */ 526 public static final int AXIS_Z = 11; 527 528 /** 529 * Constant used to identify the X Rotation axis of a motion event. 530 * <p> 531 * <ul> 532 * <li>For a joystick, reports the absolute rotation angle about the X axis. 533 * The value is normalized to a range from -1.0 (counter-clockwise) to 1.0 (clockwise). 534 * </ul> 535 * </p> 536 * 537 * @see #getAxisValue(int, int) 538 * @see #getHistoricalAxisValue(int, int, int) 539 * @see MotionEvent.PointerCoords#getAxisValue(int) 540 * @see InputDevice#getMotionRange 541 */ 542 public static final int AXIS_RX = 12; 543 544 /** 545 * Constant used to identify the Y Rotation axis of a motion event. 546 * <p> 547 * <ul> 548 * <li>For a joystick, reports the absolute rotation angle about the Y axis. 549 * The value is normalized to a range from -1.0 (counter-clockwise) to 1.0 (clockwise). 550 * </ul> 551 * </p> 552 * 553 * @see #getAxisValue(int, int) 554 * @see #getHistoricalAxisValue(int, int, int) 555 * @see MotionEvent.PointerCoords#getAxisValue(int) 556 * @see InputDevice#getMotionRange 557 */ 558 public static final int AXIS_RY = 13; 559 560 /** 561 * Constant used to identify the Z Rotation axis of a motion event. 562 * <p> 563 * <ul> 564 * <li>For a joystick, reports the absolute rotation angle about the Z axis. 565 * The value is normalized to a range from -1.0 (counter-clockwise) to 1.0 (clockwise). 566 * <em>On game pads with two analog joysticks, this axis is often reinterpreted 567 * to report the absolute Y position of the second joystick instead.</em> 568 * </ul> 569 * </p> 570 * 571 * @see #getAxisValue(int, int) 572 * @see #getHistoricalAxisValue(int, int, int) 573 * @see MotionEvent.PointerCoords#getAxisValue(int) 574 * @see InputDevice#getMotionRange 575 */ 576 public static final int AXIS_RZ = 14; 577 578 /** 579 * Constant used to identify the Hat X axis of a motion event. 580 * <p> 581 * <ul> 582 * <li>For a joystick, reports the absolute X position of the directional hat control. 583 * The value is normalized to a range from -1.0 (left) to 1.0 (right). 584 * </ul> 585 * </p> 586 * 587 * @see #getAxisValue(int, int) 588 * @see #getHistoricalAxisValue(int, int, int) 589 * @see MotionEvent.PointerCoords#getAxisValue(int) 590 * @see InputDevice#getMotionRange 591 */ 592 public static final int AXIS_HAT_X = 15; 593 594 /** 595 * Constant used to identify the Hat Y axis of a motion event. 596 * <p> 597 * <ul> 598 * <li>For a joystick, reports the absolute Y position of the directional hat control. 599 * The value is normalized to a range from -1.0 (up) to 1.0 (down). 600 * </ul> 601 * </p> 602 * 603 * @see #getAxisValue(int, int) 604 * @see #getHistoricalAxisValue(int, int, int) 605 * @see MotionEvent.PointerCoords#getAxisValue(int) 606 * @see InputDevice#getMotionRange 607 */ 608 public static final int AXIS_HAT_Y = 16; 609 610 /** 611 * Constant used to identify the Left Trigger axis of a motion event. 612 * <p> 613 * <ul> 614 * <li>For a joystick, reports the absolute position of the left trigger control. 615 * The value is normalized to a range from 0.0 (released) to 1.0 (fully pressed). 616 * </ul> 617 * </p> 618 * 619 * @see #getAxisValue(int, int) 620 * @see #getHistoricalAxisValue(int, int, int) 621 * @see MotionEvent.PointerCoords#getAxisValue(int) 622 * @see InputDevice#getMotionRange 623 */ 624 public static final int AXIS_LTRIGGER = 17; 625 626 /** 627 * Constant used to identify the Right Trigger axis of a motion event. 628 * <p> 629 * <ul> 630 * <li>For a joystick, reports the absolute position of the right trigger control. 631 * The value is normalized to a range from 0.0 (released) to 1.0 (fully pressed). 632 * </ul> 633 * </p> 634 * 635 * @see #getAxisValue(int, int) 636 * @see #getHistoricalAxisValue(int, int, int) 637 * @see MotionEvent.PointerCoords#getAxisValue(int) 638 * @see InputDevice#getMotionRange 639 */ 640 public static final int AXIS_RTRIGGER = 18; 641 642 /** 643 * Constant used to identify the Generic 1 axis of a motion event. 644 * The interpretation of a generic axis is device-specific. 645 * 646 * @see #getAxisValue(int, int) 647 * @see #getHistoricalAxisValue(int, int, int) 648 * @see MotionEvent.PointerCoords#getAxisValue(int) 649 * @see InputDevice#getMotionRange 650 */ 651 public static final int AXIS_GENERIC_1 = 32; 652 653 /** 654 * Constant used to identify the Generic 2 axis of a motion event. 655 * The interpretation of a generic axis is device-specific. 656 * 657 * @see #getAxisValue(int, int) 658 * @see #getHistoricalAxisValue(int, int, int) 659 * @see MotionEvent.PointerCoords#getAxisValue(int) 660 * @see InputDevice#getMotionRange 661 */ 662 public static final int AXIS_GENERIC_2 = 33; 663 664 /** 665 * Constant used to identify the Generic 3 axis of a motion event. 666 * The interpretation of a generic axis is device-specific. 667 * 668 * @see #getAxisValue(int, int) 669 * @see #getHistoricalAxisValue(int, int, int) 670 * @see MotionEvent.PointerCoords#getAxisValue(int) 671 * @see InputDevice#getMotionRange 672 */ 673 public static final int AXIS_GENERIC_3 = 34; 674 675 /** 676 * Constant used to identify the Generic 4 axis of a motion event. 677 * The interpretation of a generic axis is device-specific. 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_GENERIC_4 = 35; 685 686 /** 687 * Constant used to identify the Generic 5 axis of a motion event. 688 * The interpretation of a generic axis is device-specific. 689 * 690 * @see #getAxisValue(int, int) 691 * @see #getHistoricalAxisValue(int, int, int) 692 * @see MotionEvent.PointerCoords#getAxisValue(int) 693 * @see InputDevice#getMotionRange 694 */ 695 public static final int AXIS_GENERIC_5 = 36; 696 697 /** 698 * Constant used to identify the Generic 6 axis of a motion event. 699 * The interpretation of a generic axis is device-specific. 700 * 701 * @see #getAxisValue(int, int) 702 * @see #getHistoricalAxisValue(int, int, int) 703 * @see MotionEvent.PointerCoords#getAxisValue(int) 704 * @see InputDevice#getMotionRange 705 */ 706 public static final int AXIS_GENERIC_6 = 37; 707 708 /** 709 * Constant used to identify the Generic 7 axis of a motion event. 710 * The interpretation of a generic axis is device-specific. 711 * 712 * @see #getAxisValue(int, int) 713 * @see #getHistoricalAxisValue(int, int, int) 714 * @see MotionEvent.PointerCoords#getAxisValue(int) 715 * @see InputDevice#getMotionRange 716 */ 717 public static final int AXIS_GENERIC_7 = 38; 718 719 /** 720 * Constant used to identify the Generic 8 axis of a motion event. 721 * The interpretation of a generic axis is device-specific. 722 * 723 * @see #getAxisValue(int, int) 724 * @see #getHistoricalAxisValue(int, int, int) 725 * @see MotionEvent.PointerCoords#getAxisValue(int) 726 * @see InputDevice#getMotionRange 727 */ 728 public static final int AXIS_GENERIC_8 = 39; 729 730 /** 731 * Constant used to identify the Generic 9 axis of a motion event. 732 * The interpretation of a generic axis is device-specific. 733 * 734 * @see #getAxisValue(int, int) 735 * @see #getHistoricalAxisValue(int, int, int) 736 * @see MotionEvent.PointerCoords#getAxisValue(int) 737 * @see InputDevice#getMotionRange 738 */ 739 public static final int AXIS_GENERIC_9 = 40; 740 741 /** 742 * Constant used to identify the Generic 10 axis of a motion event. 743 * The interpretation of a generic axis is device-specific. 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_GENERIC_10 = 41; 751 752 /** 753 * Constant used to identify the Generic 11 axis of a motion event. 754 * The interpretation of a generic axis is device-specific. 755 * 756 * @see #getAxisValue(int, int) 757 * @see #getHistoricalAxisValue(int, int, int) 758 * @see MotionEvent.PointerCoords#getAxisValue(int) 759 * @see InputDevice#getMotionRange 760 */ 761 public static final int AXIS_GENERIC_11 = 42; 762 763 /** 764 * Constant used to identify the Generic 12 axis of a motion event. 765 * The interpretation of a generic axis is device-specific. 766 * 767 * @see #getAxisValue(int, int) 768 * @see #getHistoricalAxisValue(int, int, int) 769 * @see MotionEvent.PointerCoords#getAxisValue(int) 770 * @see InputDevice#getMotionRange 771 */ 772 public static final int AXIS_GENERIC_12 = 43; 773 774 /** 775 * Constant used to identify the Generic 13 axis of a motion event. 776 * The interpretation of a generic axis is device-specific. 777 * 778 * @see #getAxisValue(int, int) 779 * @see #getHistoricalAxisValue(int, int, int) 780 * @see MotionEvent.PointerCoords#getAxisValue(int) 781 * @see InputDevice#getMotionRange 782 */ 783 public static final int AXIS_GENERIC_13 = 44; 784 785 /** 786 * Constant used to identify the Generic 14 axis of a motion event. 787 * The interpretation of a generic axis is device-specific. 788 * 789 * @see #getAxisValue(int, int) 790 * @see #getHistoricalAxisValue(int, int, int) 791 * @see MotionEvent.PointerCoords#getAxisValue(int) 792 * @see InputDevice#getMotionRange 793 */ 794 public static final int AXIS_GENERIC_14 = 45; 795 796 /** 797 * Constant used to identify the Generic 15 axis of a motion event. 798 * The interpretation of a generic axis is device-specific. 799 * 800 * @see #getAxisValue(int, int) 801 * @see #getHistoricalAxisValue(int, int, int) 802 * @see MotionEvent.PointerCoords#getAxisValue(int) 803 * @see InputDevice#getMotionRange 804 */ 805 public static final int AXIS_GENERIC_15 = 46; 806 807 /** 808 * Constant used to identify the Generic 16 axis of a motion event. 809 * The interpretation of a generic axis is device-specific. 810 * 811 * @see #getAxisValue(int, int) 812 * @see #getHistoricalAxisValue(int, int, int) 813 * @see MotionEvent.PointerCoords#getAxisValue(int) 814 * @see InputDevice#getMotionRange 815 */ 816 public static final int AXIS_GENERIC_16 = 47; 817 818 // NOTE: If you add a new axis here you must also add it to: 819 // native/include/android/input.h 820 // frameworks/base/include/ui/KeycodeLabels.h 821 822 // Symbolic names of all axes. 823 private static final SparseArray<String> AXIS_SYMBOLIC_NAMES = new SparseArray<String>(); 824 private static void populateAxisSymbolicNames() { 825 SparseArray<String> names = AXIS_SYMBOLIC_NAMES; 826 names.append(AXIS_X, "AXIS_X"); 827 names.append(AXIS_Y, "AXIS_Y"); 828 names.append(AXIS_PRESSURE, "AXIS_PRESSURE"); 829 names.append(AXIS_SIZE, "AXIS_SIZE"); 830 names.append(AXIS_TOUCH_MAJOR, "AXIS_TOUCH_MAJOR"); 831 names.append(AXIS_TOUCH_MINOR, "AXIS_TOUCH_MINOR"); 832 names.append(AXIS_TOOL_MAJOR, "AXIS_TOOL_MAJOR"); 833 names.append(AXIS_TOOL_MINOR, "AXIS_TOOL_MINOR"); 834 names.append(AXIS_ORIENTATION, "AXIS_ORIENTATION"); 835 names.append(AXIS_VSCROLL, "AXIS_VSCROLL"); 836 names.append(AXIS_HSCROLL, "AXIS_HSCROLL"); 837 names.append(AXIS_Z, "AXIS_Z"); 838 names.append(AXIS_RX, "AXIS_RX"); 839 names.append(AXIS_RY, "AXIS_RY"); 840 names.append(AXIS_RZ, "AXIS_RZ"); 841 names.append(AXIS_HAT_X, "AXIS_HAT_X"); 842 names.append(AXIS_HAT_Y, "AXIS_HAT_Y"); 843 names.append(AXIS_LTRIGGER, "AXIS_LTRIGGER"); 844 names.append(AXIS_RTRIGGER, "AXIS_RTRIGGER"); 845 names.append(AXIS_GENERIC_1, "AXIS_GENERIC_1"); 846 names.append(AXIS_GENERIC_2, "AXIS_GENERIC_2"); 847 names.append(AXIS_GENERIC_3, "AXIS_GENERIC_3"); 848 names.append(AXIS_GENERIC_4, "AXIS_GENERIC_4"); 849 names.append(AXIS_GENERIC_5, "AXIS_GENERIC_5"); 850 names.append(AXIS_GENERIC_6, "AXIS_GENERIC_6"); 851 names.append(AXIS_GENERIC_7, "AXIS_GENERIC_7"); 852 names.append(AXIS_GENERIC_8, "AXIS_GENERIC_8"); 853 names.append(AXIS_GENERIC_9, "AXIS_GENERIC_9"); 854 names.append(AXIS_GENERIC_10, "AXIS_GENERIC_10"); 855 names.append(AXIS_GENERIC_11, "AXIS_GENERIC_11"); 856 names.append(AXIS_GENERIC_12, "AXIS_GENERIC_12"); 857 names.append(AXIS_GENERIC_13, "AXIS_GENERIC_13"); 858 names.append(AXIS_GENERIC_14, "AXIS_GENERIC_14"); 859 names.append(AXIS_GENERIC_15, "AXIS_GENERIC_15"); 860 names.append(AXIS_GENERIC_16, "AXIS_GENERIC_16"); 861 } 862 863 static { 864 populateAxisSymbolicNames(); 865 } 866 867 // Private value for history pos that obtains the current sample. 868 private static final int HISTORY_CURRENT = -0x80000000; 869 870 private static final int MAX_RECYCLED = 10; 871 private static final Object gRecyclerLock = new Object(); 872 private static int gRecyclerUsed; 873 private static MotionEvent gRecyclerTop; 874 875 // Shared temporary objects used when translating coordinates supplied by 876 // the caller into single element PointerCoords and pointer id arrays. 877 // Must lock gTmpPointerCoords prior to use. 878 private static final PointerCoords[] gTmpPointerCoords = 879 new PointerCoords[] { new PointerCoords() }; 880 private static final int[] gTmpPointerIds = new int[] { 0 /*always 0*/ }; 881 882 // Pointer to the native MotionEvent object that contains the actual data. 883 private int mNativePtr; 884 885 private MotionEvent mNext; 886 private RuntimeException mRecycledLocation; 887 private boolean mRecycled; 888 889 private static native int nativeInitialize(int nativePtr, 890 int deviceId, int source, int action, int flags, int edgeFlags, int metaState, 891 float xOffset, float yOffset, float xPrecision, float yPrecision, 892 long downTimeNanos, long eventTimeNanos, 893 int pointerCount, int[] pointerIds, PointerCoords[] pointerCoords); 894 private static native int nativeCopy(int destNativePtr, int sourceNativePtr, 895 boolean keepHistory); 896 private static native void nativeDispose(int nativePtr); 897 private static native void nativeAddBatch(int nativePtr, long eventTimeNanos, 898 PointerCoords[] pointerCoords, int metaState); 899 900 private static native int nativeGetDeviceId(int nativePtr); 901 private static native int nativeGetSource(int nativePtr); 902 private static native int nativeSetSource(int nativePtr, int source); 903 private static native int nativeGetAction(int nativePtr); 904 private static native void nativeSetAction(int nativePtr, int action); 905 private static native int nativeGetFlags(int nativePtr); 906 private static native int nativeGetEdgeFlags(int nativePtr); 907 private static native void nativeSetEdgeFlags(int nativePtr, int action); 908 private static native int nativeGetMetaState(int nativePtr); 909 private static native void nativeOffsetLocation(int nativePtr, float deltaX, float deltaY); 910 private static native float nativeGetXPrecision(int nativePtr); 911 private static native float nativeGetYPrecision(int nativePtr); 912 private static native long nativeGetDownTimeNanos(int nativePtr); 913 914 private static native int nativeGetPointerCount(int nativePtr); 915 private static native int nativeGetPointerId(int nativePtr, int pointerIndex); 916 private static native int nativeFindPointerIndex(int nativePtr, int pointerId); 917 918 private static native int nativeGetHistorySize(int nativePtr); 919 private static native long nativeGetEventTimeNanos(int nativePtr, int historyPos); 920 private static native float nativeGetRawAxisValue(int nativePtr, 921 int axis, int pointerIndex, int historyPos); 922 private static native float nativeGetAxisValue(int nativePtr, 923 int axis, int pointerIndex, int historyPos); 924 private static native void nativeGetPointerCoords(int nativePtr, 925 int pointerIndex, int historyPos, PointerCoords outPointerCoords); 926 927 private static native void nativeScale(int nativePtr, float scale); 928 private static native void nativeTransform(int nativePtr, Matrix matrix); 929 930 private static native int nativeReadFromParcel(int nativePtr, Parcel parcel); 931 private static native void nativeWriteToParcel(int nativePtr, Parcel parcel); 932 933 private MotionEvent() { 934 } 935 936 @Override 937 protected void finalize() throws Throwable { 938 try { 939 if (mNativePtr != 0) { 940 nativeDispose(mNativePtr); 941 mNativePtr = 0; 942 } 943 } finally { 944 super.finalize(); 945 } 946 } 947 948 static private MotionEvent obtain() { 949 final MotionEvent ev; 950 synchronized (gRecyclerLock) { 951 ev = gRecyclerTop; 952 if (ev == null) { 953 return new MotionEvent(); 954 } 955 gRecyclerTop = ev.mNext; 956 gRecyclerUsed -= 1; 957 } 958 ev.mRecycledLocation = null; 959 ev.mRecycled = false; 960 ev.mNext = null; 961 return ev; 962 } 963 964 /** 965 * Create a new MotionEvent, filling in all of the basic values that 966 * define the motion. 967 * 968 * @param downTime The time (in ms) when the user originally pressed down to start 969 * a stream of position events. This must be obtained from {@link SystemClock#uptimeMillis()}. 970 * @param eventTime The the time (in ms) when this specific event was generated. This 971 * must be obtained from {@link SystemClock#uptimeMillis()}. 972 * @param action The kind of action being performed -- one of either 973 * {@link #ACTION_DOWN}, {@link #ACTION_MOVE}, {@link #ACTION_UP}, or 974 * {@link #ACTION_CANCEL}. 975 * @param pointers The number of points that will be in this event. 976 * @param pointerIds An array of <em>pointers</em> values providing 977 * an identifier for each pointer. 978 * @param pointerCoords An array of <em>pointers</em> values providing 979 * a {@link PointerCoords} coordinate object for each pointer. 980 * @param metaState The state of any meta / modifier keys that were in effect when 981 * the event was generated. 982 * @param xPrecision The precision of the X coordinate being reported. 983 * @param yPrecision The precision of the Y coordinate being reported. 984 * @param deviceId The id for the device that this event came from. An id of 985 * zero indicates that the event didn't come from a physical device; other 986 * numbers are arbitrary and you shouldn't depend on the values. 987 * @param edgeFlags A bitfield indicating which edges, if any, were touched by this 988 * MotionEvent. 989 * @param source The source of this event. 990 * @param flags The motion event flags. 991 */ 992 static public MotionEvent obtain(long downTime, long eventTime, 993 int action, int pointers, int[] pointerIds, PointerCoords[] pointerCoords, 994 int metaState, float xPrecision, float yPrecision, int deviceId, 995 int edgeFlags, int source, int flags) { 996 MotionEvent ev = obtain(); 997 ev.mNativePtr = nativeInitialize(ev.mNativePtr, 998 deviceId, source, action, flags, edgeFlags, metaState, 999 0, 0, xPrecision, yPrecision, 1000 downTime * NS_PER_MS, eventTime * NS_PER_MS, 1001 pointers, pointerIds, pointerCoords); 1002 return ev; 1003 } 1004 1005 /** 1006 * Create a new MotionEvent, filling in all of the basic values that 1007 * define the motion. 1008 * 1009 * @param downTime The time (in ms) when the user originally pressed down to start 1010 * a stream of position events. This must be obtained from {@link SystemClock#uptimeMillis()}. 1011 * @param eventTime The the time (in ms) when this specific event was generated. This 1012 * must be obtained from {@link SystemClock#uptimeMillis()}. 1013 * @param action The kind of action being performed -- one of either 1014 * {@link #ACTION_DOWN}, {@link #ACTION_MOVE}, {@link #ACTION_UP}, or 1015 * {@link #ACTION_CANCEL}. 1016 * @param x The X coordinate of this event. 1017 * @param y The Y coordinate of this event. 1018 * @param pressure The current pressure of this event. The pressure generally 1019 * ranges from 0 (no pressure at all) to 1 (normal pressure), however 1020 * values higher than 1 may be generated depending on the calibration of 1021 * the input device. 1022 * @param size A scaled value of the approximate size of the area being pressed when 1023 * touched with the finger. The actual value in pixels corresponding to the finger 1024 * touch is normalized with a device specific range of values 1025 * and scaled to a value between 0 and 1. 1026 * @param metaState The state of any meta / modifier keys that were in effect when 1027 * the event was generated. 1028 * @param xPrecision The precision of the X coordinate being reported. 1029 * @param yPrecision The precision of the Y coordinate being reported. 1030 * @param deviceId The id for the device that this event came from. An id of 1031 * zero indicates that the event didn't come from a physical device; other 1032 * numbers are arbitrary and you shouldn't depend on the values. 1033 * @param edgeFlags A bitfield indicating which edges, if any, were touched by this 1034 * MotionEvent. 1035 */ 1036 static public MotionEvent obtain(long downTime, long eventTime, int action, 1037 float x, float y, float pressure, float size, int metaState, 1038 float xPrecision, float yPrecision, int deviceId, int edgeFlags) { 1039 synchronized (gTmpPointerCoords) { 1040 final PointerCoords pc = gTmpPointerCoords[0]; 1041 pc.clear(); 1042 pc.x = x; 1043 pc.y = y; 1044 pc.pressure = pressure; 1045 pc.size = size; 1046 1047 MotionEvent ev = obtain(); 1048 ev.mNativePtr = nativeInitialize(ev.mNativePtr, 1049 deviceId, InputDevice.SOURCE_UNKNOWN, action, 0, edgeFlags, metaState, 1050 0, 0, xPrecision, yPrecision, 1051 downTime * NS_PER_MS, eventTime * NS_PER_MS, 1052 1, gTmpPointerIds, gTmpPointerCoords); 1053 return ev; 1054 } 1055 } 1056 1057 /** 1058 * Create a new MotionEvent, filling in all of the basic values that 1059 * define the motion. 1060 * 1061 * @param downTime The time (in ms) when the user originally pressed down to start 1062 * a stream of position events. This must be obtained from {@link SystemClock#uptimeMillis()}. 1063 * @param eventTime The the time (in ms) when this specific event was generated. This 1064 * must be obtained from {@link SystemClock#uptimeMillis()}. 1065 * @param action The kind of action being performed -- one of either 1066 * {@link #ACTION_DOWN}, {@link #ACTION_MOVE}, {@link #ACTION_UP}, or 1067 * {@link #ACTION_CANCEL}. 1068 * @param pointers The number of pointers that are active in this event. 1069 * @param x The X coordinate of this event. 1070 * @param y The Y coordinate of this event. 1071 * @param pressure The current pressure of this event. The pressure generally 1072 * ranges from 0 (no pressure at all) to 1 (normal pressure), however 1073 * values higher than 1 may be generated depending on the calibration of 1074 * the input device. 1075 * @param size A scaled value of the approximate size of the area being pressed when 1076 * touched with the finger. The actual value in pixels corresponding to the finger 1077 * touch is normalized with a device specific range of values 1078 * and scaled to a value between 0 and 1. 1079 * @param metaState The state of any meta / modifier keys that were in effect when 1080 * the event was generated. 1081 * @param xPrecision The precision of the X coordinate being reported. 1082 * @param yPrecision The precision of the Y coordinate being reported. 1083 * @param deviceId The id for the device that this event came from. An id of 1084 * zero indicates that the event didn't come from a physical device; other 1085 * numbers are arbitrary and you shouldn't depend on the values. 1086 * @param edgeFlags A bitfield indicating which edges, if any, were touched by this 1087 * MotionEvent. 1088 * 1089 * @deprecated Use {@link #obtain(long, long, int, float, float, float, float, int, float, float, int, int)} 1090 * instead. 1091 */ 1092 @Deprecated 1093 static public MotionEvent obtain(long downTime, long eventTime, int action, 1094 int pointers, float x, float y, float pressure, float size, int metaState, 1095 float xPrecision, float yPrecision, int deviceId, int edgeFlags) { 1096 return obtain(downTime, eventTime, action, x, y, pressure, size, 1097 metaState, xPrecision, yPrecision, deviceId, edgeFlags); 1098 } 1099 1100 /** 1101 * Create a new MotionEvent, filling in a subset of the basic motion 1102 * values. Those not specified here are: device id (always 0), pressure 1103 * and size (always 1), x and y precision (always 1), and edgeFlags (always 0). 1104 * 1105 * @param downTime The time (in ms) when the user originally pressed down to start 1106 * a stream of position events. This must be obtained from {@link SystemClock#uptimeMillis()}. 1107 * @param eventTime The the time (in ms) when this specific event was generated. This 1108 * must be obtained from {@link SystemClock#uptimeMillis()}. 1109 * @param action The kind of action being performed -- one of either 1110 * {@link #ACTION_DOWN}, {@link #ACTION_MOVE}, {@link #ACTION_UP}, or 1111 * {@link #ACTION_CANCEL}. 1112 * @param x The X coordinate of this event. 1113 * @param y The Y coordinate of this event. 1114 * @param metaState The state of any meta / modifier keys that were in effect when 1115 * the event was generated. 1116 */ 1117 static public MotionEvent obtain(long downTime, long eventTime, int action, 1118 float x, float y, int metaState) { 1119 return obtain(downTime, eventTime, action, x, y, 1.0f, 1.0f, 1120 metaState, 1.0f, 1.0f, 0, 0); 1121 } 1122 1123 /** 1124 * Create a new MotionEvent, copying from an existing one. 1125 */ 1126 static public MotionEvent obtain(MotionEvent other) { 1127 if (other == null) { 1128 throw new IllegalArgumentException("other motion event must not be null"); 1129 } 1130 1131 MotionEvent ev = obtain(); 1132 ev.mNativePtr = nativeCopy(ev.mNativePtr, other.mNativePtr, true /*keepHistory*/); 1133 return ev; 1134 } 1135 1136 /** 1137 * Create a new MotionEvent, copying from an existing one, but not including 1138 * any historical point information. 1139 */ 1140 static public MotionEvent obtainNoHistory(MotionEvent other) { 1141 if (other == null) { 1142 throw new IllegalArgumentException("other motion event must not be null"); 1143 } 1144 1145 MotionEvent ev = obtain(); 1146 ev.mNativePtr = nativeCopy(ev.mNativePtr, other.mNativePtr, false /*keepHistory*/); 1147 return ev; 1148 } 1149 1150 /** 1151 * Recycle the MotionEvent, to be re-used by a later caller. After calling 1152 * this function you must not ever touch the event again. 1153 */ 1154 public final void recycle() { 1155 // Ensure recycle is only called once! 1156 if (TRACK_RECYCLED_LOCATION) { 1157 if (mRecycledLocation != null) { 1158 throw new RuntimeException(toString() + " recycled twice!", mRecycledLocation); 1159 } 1160 mRecycledLocation = new RuntimeException("Last recycled here"); 1161 //Log.w("MotionEvent", "Recycling event " + this, mRecycledLocation); 1162 } else { 1163 if (mRecycled) { 1164 throw new RuntimeException(toString() + " recycled twice!"); 1165 } 1166 mRecycled = true; 1167 } 1168 1169 synchronized (gRecyclerLock) { 1170 if (gRecyclerUsed < MAX_RECYCLED) { 1171 gRecyclerUsed++; 1172 mNext = gRecyclerTop; 1173 gRecyclerTop = this; 1174 } 1175 } 1176 } 1177 1178 /** 1179 * Scales down the coordination of this event by the given scale. 1180 * 1181 * @hide 1182 */ 1183 public final void scale(float scale) { 1184 nativeScale(mNativePtr, scale); 1185 } 1186 1187 /** {@inheritDoc} */ 1188 @Override 1189 public final int getDeviceId() { 1190 return nativeGetDeviceId(mNativePtr); 1191 } 1192 1193 /** {@inheritDoc} */ 1194 @Override 1195 public final int getSource() { 1196 return nativeGetSource(mNativePtr); 1197 } 1198 1199 /** {@inheritDoc} */ 1200 @Override 1201 public final void setSource(int source) { 1202 nativeSetSource(mNativePtr, source); 1203 } 1204 1205 /** 1206 * Return the kind of action being performed -- one of either 1207 * {@link #ACTION_DOWN}, {@link #ACTION_MOVE}, {@link #ACTION_UP}, or 1208 * {@link #ACTION_CANCEL}. Consider using {@link #getActionMasked} 1209 * and {@link #getActionIndex} to retrieve the separate masked action 1210 * and pointer index. 1211 */ 1212 public final int getAction() { 1213 return nativeGetAction(mNativePtr); 1214 } 1215 1216 /** 1217 * Return the masked action being performed, without pointer index 1218 * information. May be any of the actions: {@link #ACTION_DOWN}, 1219 * {@link #ACTION_MOVE}, {@link #ACTION_UP}, {@link #ACTION_CANCEL}, 1220 * {@link #ACTION_POINTER_DOWN}, or {@link #ACTION_POINTER_UP}. 1221 * Use {@link #getActionIndex} to return the index associated with 1222 * pointer actions. 1223 */ 1224 public final int getActionMasked() { 1225 return nativeGetAction(mNativePtr) & ACTION_MASK; 1226 } 1227 1228 /** 1229 * For {@link #ACTION_POINTER_DOWN} or {@link #ACTION_POINTER_UP} 1230 * as returned by {@link #getActionMasked}, this returns the associated 1231 * pointer index. The index may be used with {@link #getPointerId(int)}, 1232 * {@link #getX(int)}, {@link #getY(int)}, {@link #getPressure(int)}, 1233 * and {@link #getSize(int)} to get information about the pointer that has 1234 * gone down or up. 1235 */ 1236 public final int getActionIndex() { 1237 return (nativeGetAction(mNativePtr) & ACTION_POINTER_INDEX_MASK) 1238 >> ACTION_POINTER_INDEX_SHIFT; 1239 } 1240 1241 /** 1242 * Gets the motion event flags. 1243 * 1244 * @see #FLAG_WINDOW_IS_OBSCURED 1245 */ 1246 public final int getFlags() { 1247 return nativeGetFlags(mNativePtr); 1248 } 1249 1250 /** 1251 * Returns the time (in ms) when the user originally pressed down to start 1252 * a stream of position events. 1253 */ 1254 public final long getDownTime() { 1255 return nativeGetDownTimeNanos(mNativePtr) / NS_PER_MS; 1256 } 1257 1258 /** 1259 * Returns the time (in ms) when this specific event was generated. 1260 */ 1261 public final long getEventTime() { 1262 return nativeGetEventTimeNanos(mNativePtr, HISTORY_CURRENT) / NS_PER_MS; 1263 } 1264 1265 /** 1266 * Returns the time (in ns) when this specific event was generated. 1267 * The value is in nanosecond precision but it may not have nanosecond accuracy. 1268 * 1269 * @hide 1270 */ 1271 public final long getEventTimeNano() { 1272 return nativeGetEventTimeNanos(mNativePtr, HISTORY_CURRENT); 1273 } 1274 1275 /** 1276 * {@link #getX(int)} for the first pointer index (may be an 1277 * arbitrary pointer identifier). 1278 * 1279 * @see #AXIS_X 1280 */ 1281 public final float getX() { 1282 return nativeGetAxisValue(mNativePtr, AXIS_X, 0, HISTORY_CURRENT); 1283 } 1284 1285 /** 1286 * {@link #getY(int)} for the first pointer index (may be an 1287 * arbitrary pointer identifier). 1288 * 1289 * @see #AXIS_Y 1290 */ 1291 public final float getY() { 1292 return nativeGetAxisValue(mNativePtr, AXIS_Y, 0, HISTORY_CURRENT); 1293 } 1294 1295 /** 1296 * {@link #getPressure(int)} for the first pointer index (may be an 1297 * arbitrary pointer identifier). 1298 * 1299 * @see #AXIS_PRESSURE 1300 */ 1301 public final float getPressure() { 1302 return nativeGetAxisValue(mNativePtr, AXIS_PRESSURE, 0, HISTORY_CURRENT); 1303 } 1304 1305 /** 1306 * {@link #getSize(int)} for the first pointer index (may be an 1307 * arbitrary pointer identifier). 1308 * 1309 * @see #AXIS_SIZE 1310 */ 1311 public final float getSize() { 1312 return nativeGetAxisValue(mNativePtr, AXIS_SIZE, 0, HISTORY_CURRENT); 1313 } 1314 1315 /** 1316 * {@link #getTouchMajor(int)} for the first pointer index (may be an 1317 * arbitrary pointer identifier). 1318 * 1319 * @see #AXIS_TOUCH_MAJOR 1320 */ 1321 public final float getTouchMajor() { 1322 return nativeGetAxisValue(mNativePtr, AXIS_TOUCH_MAJOR, 0, HISTORY_CURRENT); 1323 } 1324 1325 /** 1326 * {@link #getTouchMinor(int)} for the first pointer index (may be an 1327 * arbitrary pointer identifier). 1328 * 1329 * @see #AXIS_TOUCH_MINOR 1330 */ 1331 public final float getTouchMinor() { 1332 return nativeGetAxisValue(mNativePtr, AXIS_TOUCH_MINOR, 0, HISTORY_CURRENT); 1333 } 1334 1335 /** 1336 * {@link #getToolMajor(int)} for the first pointer index (may be an 1337 * arbitrary pointer identifier). 1338 * 1339 * @see #AXIS_TOOL_MAJOR 1340 */ 1341 public final float getToolMajor() { 1342 return nativeGetAxisValue(mNativePtr, AXIS_TOOL_MAJOR, 0, HISTORY_CURRENT); 1343 } 1344 1345 /** 1346 * {@link #getToolMinor(int)} for the first pointer index (may be an 1347 * arbitrary pointer identifier). 1348 * 1349 * @see #AXIS_TOOL_MINOR 1350 */ 1351 public final float getToolMinor() { 1352 return nativeGetAxisValue(mNativePtr, AXIS_TOOL_MINOR, 0, HISTORY_CURRENT); 1353 } 1354 1355 /** 1356 * {@link #getOrientation(int)} for the first pointer index (may be an 1357 * arbitrary pointer identifier). 1358 * 1359 * @see #AXIS_ORIENTATION 1360 */ 1361 public final float getOrientation() { 1362 return nativeGetAxisValue(mNativePtr, AXIS_ORIENTATION, 0, HISTORY_CURRENT); 1363 } 1364 1365 /** 1366 * {@link #getAxisValue(int)} for the first pointer index (may be an 1367 * arbitrary pointer identifier). 1368 * 1369 * @param axis The axis identifier for the axis value to retrieve. 1370 * 1371 * @see #AXIS_X 1372 * @see #AXIS_Y 1373 */ 1374 public final float getAxisValue(int axis) { 1375 return nativeGetAxisValue(mNativePtr, axis, 0, HISTORY_CURRENT); 1376 } 1377 1378 /** 1379 * The number of pointers of data contained in this event. Always 1380 * >= 1. 1381 */ 1382 public final int getPointerCount() { 1383 return nativeGetPointerCount(mNativePtr); 1384 } 1385 1386 /** 1387 * Return the pointer identifier associated with a particular pointer 1388 * data index is this event. The identifier tells you the actual pointer 1389 * number associated with the data, accounting for individual pointers 1390 * going up and down since the start of the current gesture. 1391 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 1392 * (the first pointer that is down) to {@link #getPointerCount()}-1. 1393 */ 1394 public final int getPointerId(int pointerIndex) { 1395 return nativeGetPointerId(mNativePtr, pointerIndex); 1396 } 1397 1398 /** 1399 * Given a pointer identifier, find the index of its data in the event. 1400 * 1401 * @param pointerId The identifier of the pointer to be found. 1402 * @return Returns either the index of the pointer (for use with 1403 * {@link #getX(int)} et al.), or -1 if there is no data available for 1404 * that pointer identifier. 1405 */ 1406 public final int findPointerIndex(int pointerId) { 1407 return nativeFindPointerIndex(mNativePtr, pointerId); 1408 } 1409 1410 /** 1411 * Returns the X coordinate of this event for the given pointer 1412 * <em>index</em> (use {@link #getPointerId(int)} to find the pointer 1413 * identifier for this index). 1414 * Whole numbers are pixels; the 1415 * value may have a fraction for input devices that are sub-pixel precise. 1416 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 1417 * (the first pointer that is down) to {@link #getPointerCount()}-1. 1418 * 1419 * @see #AXIS_X 1420 */ 1421 public final float getX(int pointerIndex) { 1422 return nativeGetAxisValue(mNativePtr, AXIS_X, pointerIndex, HISTORY_CURRENT); 1423 } 1424 1425 /** 1426 * Returns the Y coordinate of this event for the given pointer 1427 * <em>index</em> (use {@link #getPointerId(int)} to find the pointer 1428 * identifier for this index). 1429 * Whole numbers are pixels; the 1430 * value may have a fraction for input devices that are sub-pixel precise. 1431 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 1432 * (the first pointer that is down) to {@link #getPointerCount()}-1. 1433 * 1434 * @see #AXIS_Y 1435 */ 1436 public final float getY(int pointerIndex) { 1437 return nativeGetAxisValue(mNativePtr, AXIS_Y, pointerIndex, HISTORY_CURRENT); 1438 } 1439 1440 /** 1441 * Returns the current pressure of this event for the given pointer 1442 * <em>index</em> (use {@link #getPointerId(int)} to find the pointer 1443 * identifier for this index). 1444 * The pressure generally 1445 * ranges from 0 (no pressure at all) to 1 (normal pressure), however 1446 * values higher than 1 may be generated depending on the calibration of 1447 * the input device. 1448 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 1449 * (the first pointer that is down) to {@link #getPointerCount()}-1. 1450 * 1451 * @see #AXIS_PRESSURE 1452 */ 1453 public final float getPressure(int pointerIndex) { 1454 return nativeGetAxisValue(mNativePtr, AXIS_PRESSURE, pointerIndex, HISTORY_CURRENT); 1455 } 1456 1457 /** 1458 * Returns a scaled value of the approximate size for the given pointer 1459 * <em>index</em> (use {@link #getPointerId(int)} to find the pointer 1460 * identifier for this index). 1461 * This represents some approximation of the area of the screen being 1462 * pressed; the actual value in pixels corresponding to the 1463 * touch is normalized with the device specific range of values 1464 * and scaled to a value between 0 and 1. The value of size can be used to 1465 * determine fat touch events. 1466 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 1467 * (the first pointer that is down) to {@link #getPointerCount()}-1. 1468 * 1469 * @see #AXIS_SIZE 1470 */ 1471 public final float getSize(int pointerIndex) { 1472 return nativeGetAxisValue(mNativePtr, AXIS_SIZE, pointerIndex, HISTORY_CURRENT); 1473 } 1474 1475 /** 1476 * Returns the length of the major axis of an ellipse that describes the touch 1477 * area at the point of contact for the given pointer 1478 * <em>index</em> (use {@link #getPointerId(int)} to find the pointer 1479 * identifier for this index). 1480 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 1481 * (the first pointer that is down) to {@link #getPointerCount()}-1. 1482 * 1483 * @see #AXIS_TOUCH_MAJOR 1484 */ 1485 public final float getTouchMajor(int pointerIndex) { 1486 return nativeGetAxisValue(mNativePtr, AXIS_TOUCH_MAJOR, pointerIndex, HISTORY_CURRENT); 1487 } 1488 1489 /** 1490 * Returns the length of the minor axis of an ellipse that describes the touch 1491 * area at the point of contact for the given pointer 1492 * <em>index</em> (use {@link #getPointerId(int)} to find the pointer 1493 * identifier for this index). 1494 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 1495 * (the first pointer that is down) to {@link #getPointerCount()}-1. 1496 * 1497 * @see #AXIS_TOUCH_MINOR 1498 */ 1499 public final float getTouchMinor(int pointerIndex) { 1500 return nativeGetAxisValue(mNativePtr, AXIS_TOUCH_MINOR, pointerIndex, HISTORY_CURRENT); 1501 } 1502 1503 /** 1504 * Returns the length of the major axis of an ellipse that describes the size of 1505 * the approaching tool for the given pointer 1506 * <em>index</em> (use {@link #getPointerId(int)} to find the pointer 1507 * identifier for this index). 1508 * The tool area represents the estimated size of the finger or pen that is 1509 * touching the device independent of its actual touch area at the point of contact. 1510 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 1511 * (the first pointer that is down) to {@link #getPointerCount()}-1. 1512 * 1513 * @see #AXIS_TOOL_MAJOR 1514 */ 1515 public final float getToolMajor(int pointerIndex) { 1516 return nativeGetAxisValue(mNativePtr, AXIS_TOOL_MAJOR, pointerIndex, HISTORY_CURRENT); 1517 } 1518 1519 /** 1520 * Returns the length of the minor axis of an ellipse that describes the size of 1521 * the approaching tool for the given pointer 1522 * <em>index</em> (use {@link #getPointerId(int)} to find the pointer 1523 * identifier for this index). 1524 * The tool area represents the estimated size of the finger or pen that is 1525 * touching the device independent of its actual touch area at the point of contact. 1526 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 1527 * (the first pointer that is down) to {@link #getPointerCount()}-1. 1528 * 1529 * @see #AXIS_TOOL_MINOR 1530 */ 1531 public final float getToolMinor(int pointerIndex) { 1532 return nativeGetAxisValue(mNativePtr, AXIS_TOOL_MINOR, pointerIndex, HISTORY_CURRENT); 1533 } 1534 1535 /** 1536 * Returns the orientation of the touch area and tool area in radians clockwise from vertical 1537 * for the given pointer <em>index</em> (use {@link #getPointerId(int)} to find the pointer 1538 * identifier for this index). 1539 * An angle of 0 radians indicates that the major axis of contact is oriented 1540 * upwards, is perfectly circular or is of unknown orientation. A positive angle 1541 * indicates that the major axis of contact is oriented to the right. A negative angle 1542 * indicates that the major axis of contact is oriented to the left. 1543 * The full range is from -PI/2 radians (finger pointing fully left) to PI/2 radians 1544 * (finger pointing fully right). 1545 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 1546 * (the first pointer that is down) to {@link #getPointerCount()}-1. 1547 * 1548 * @see #AXIS_ORIENTATION 1549 */ 1550 public final float getOrientation(int pointerIndex) { 1551 return nativeGetAxisValue(mNativePtr, AXIS_ORIENTATION, pointerIndex, HISTORY_CURRENT); 1552 } 1553 1554 /** 1555 * Returns the value of the requested axis for the given pointer <em>index</em> 1556 * (use {@link #getPointerId(int)} to find the pointer identifier for this index). 1557 * 1558 * @param axis The axis identifier for the axis value to retrieve. 1559 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 1560 * (the first pointer that is down) to {@link #getPointerCount()}-1. 1561 * @return The value of the axis, or 0 if the axis is not available. 1562 * 1563 * @see #AXIS_X 1564 * @see #AXIS_Y 1565 */ 1566 public final float getAxisValue(int axis, int pointerIndex) { 1567 return nativeGetAxisValue(mNativePtr, axis, pointerIndex, HISTORY_CURRENT); 1568 } 1569 1570 /** 1571 * Populates a {@link PointerCoords} object with pointer coordinate data for 1572 * the specified pointer index. 1573 * 1574 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 1575 * (the first pointer that is down) to {@link #getPointerCount()}-1. 1576 * @param outPointerCoords The pointer coordinate object to populate. 1577 * 1578 * @see PointerCoords 1579 */ 1580 public final void getPointerCoords(int pointerIndex, PointerCoords outPointerCoords) { 1581 nativeGetPointerCoords(mNativePtr, pointerIndex, HISTORY_CURRENT, outPointerCoords); 1582 } 1583 1584 /** 1585 * Returns the state of any meta / modifier keys that were in effect when 1586 * the event was generated. This is the same values as those 1587 * returned by {@link KeyEvent#getMetaState() KeyEvent.getMetaState}. 1588 * 1589 * @return an integer in which each bit set to 1 represents a pressed 1590 * meta key 1591 * 1592 * @see KeyEvent#getMetaState() 1593 */ 1594 public final int getMetaState() { 1595 return nativeGetMetaState(mNativePtr); 1596 } 1597 1598 /** 1599 * Returns the original raw X coordinate of this event. For touch 1600 * events on the screen, this is the original location of the event 1601 * on the screen, before it had been adjusted for the containing window 1602 * and views. 1603 * 1604 * @see getX() 1605 * @see #AXIS_X 1606 */ 1607 public final float getRawX() { 1608 return nativeGetRawAxisValue(mNativePtr, AXIS_X, 0, HISTORY_CURRENT); 1609 } 1610 1611 /** 1612 * Returns the original raw Y coordinate of this event. For touch 1613 * events on the screen, this is the original location of the event 1614 * on the screen, before it had been adjusted for the containing window 1615 * and views. 1616 * 1617 * @see getY() 1618 * @see #AXIS_Y 1619 */ 1620 public final float getRawY() { 1621 return nativeGetRawAxisValue(mNativePtr, AXIS_Y, 0, HISTORY_CURRENT); 1622 } 1623 1624 /** 1625 * Return the precision of the X coordinates being reported. You can 1626 * multiply this number with {@link #getX} to find the actual hardware 1627 * value of the X coordinate. 1628 * @return Returns the precision of X coordinates being reported. 1629 * 1630 * @see #AXIS_X 1631 */ 1632 public final float getXPrecision() { 1633 return nativeGetXPrecision(mNativePtr); 1634 } 1635 1636 /** 1637 * Return the precision of the Y coordinates being reported. You can 1638 * multiply this number with {@link #getY} to find the actual hardware 1639 * value of the Y coordinate. 1640 * @return Returns the precision of Y coordinates being reported. 1641 * 1642 * @see #AXIS_Y 1643 */ 1644 public final float getYPrecision() { 1645 return nativeGetYPrecision(mNativePtr); 1646 } 1647 1648 /** 1649 * Returns the number of historical points in this event. These are 1650 * movements that have occurred between this event and the previous event. 1651 * This only applies to ACTION_MOVE events -- all other actions will have 1652 * a size of 0. 1653 * 1654 * @return Returns the number of historical points in the event. 1655 */ 1656 public final int getHistorySize() { 1657 return nativeGetHistorySize(mNativePtr); 1658 } 1659 1660 /** 1661 * Returns the time that a historical movement occurred between this event 1662 * and the previous event. Only applies to ACTION_MOVE events. 1663 * 1664 * @param pos Which historical value to return; must be less than 1665 * {@link #getHistorySize} 1666 * 1667 * @see #getHistorySize 1668 * @see #getEventTime 1669 */ 1670 public final long getHistoricalEventTime(int pos) { 1671 return nativeGetEventTimeNanos(mNativePtr, pos) / NS_PER_MS; 1672 } 1673 1674 /** 1675 * {@link #getHistoricalX(int, int)} for the first pointer index (may be an 1676 * arbitrary pointer identifier). 1677 * 1678 * @param pos Which historical value to return; must be less than 1679 * {@link #getHistorySize} 1680 * 1681 * @see #getHistorySize 1682 * @see #getX() 1683 * @see #AXIS_X 1684 */ 1685 public final float getHistoricalX(int pos) { 1686 return nativeGetAxisValue(mNativePtr, AXIS_X, 0, pos); 1687 } 1688 1689 /** 1690 * {@link #getHistoricalY(int, int)} for the first pointer index (may be an 1691 * arbitrary pointer identifier). 1692 * 1693 * @param pos Which historical value to return; must be less than 1694 * {@link #getHistorySize} 1695 * 1696 * @see #getHistorySize 1697 * @see #getY() 1698 * @see #AXIS_Y 1699 */ 1700 public final float getHistoricalY(int pos) { 1701 return nativeGetAxisValue(mNativePtr, AXIS_Y, 0, pos); 1702 } 1703 1704 /** 1705 * {@link #getHistoricalPressure(int, int)} for the first pointer index (may be an 1706 * arbitrary pointer identifier). 1707 * 1708 * @param pos Which historical value to return; must be less than 1709 * {@link #getHistorySize} 1710 * 1711 * @see #getHistorySize 1712 * @see #getPressure() 1713 * @see #AXIS_PRESSURE 1714 */ 1715 public final float getHistoricalPressure(int pos) { 1716 return nativeGetAxisValue(mNativePtr, AXIS_PRESSURE, 0, pos); 1717 } 1718 1719 /** 1720 * {@link #getHistoricalSize(int, int)} for the first pointer index (may be an 1721 * arbitrary pointer identifier). 1722 * 1723 * @param pos Which historical value to return; must be less than 1724 * {@link #getHistorySize} 1725 * 1726 * @see #getHistorySize 1727 * @see #getSize() 1728 * @see #AXIS_SIZE 1729 */ 1730 public final float getHistoricalSize(int pos) { 1731 return nativeGetAxisValue(mNativePtr, AXIS_SIZE, 0, pos); 1732 } 1733 1734 /** 1735 * {@link #getHistoricalTouchMajor(int, int)} for the first pointer index (may be an 1736 * arbitrary pointer identifier). 1737 * 1738 * @param pos Which historical value to return; must be less than 1739 * {@link #getHistorySize} 1740 * 1741 * @see #getHistorySize 1742 * @see #getTouchMajor() 1743 * @see #AXIS_TOUCH_MAJOR 1744 */ 1745 public final float getHistoricalTouchMajor(int pos) { 1746 return nativeGetAxisValue(mNativePtr, AXIS_TOUCH_MAJOR, 0, pos); 1747 } 1748 1749 /** 1750 * {@link #getHistoricalTouchMinor(int, int)} for the first pointer index (may be an 1751 * arbitrary pointer identifier). 1752 * 1753 * @param pos Which historical value to return; must be less than 1754 * {@link #getHistorySize} 1755 * 1756 * @see #getHistorySize 1757 * @see #getTouchMinor() 1758 * @see #AXIS_TOUCH_MINOR 1759 */ 1760 public final float getHistoricalTouchMinor(int pos) { 1761 return nativeGetAxisValue(mNativePtr, AXIS_TOUCH_MINOR, 0, pos); 1762 } 1763 1764 /** 1765 * {@link #getHistoricalToolMajor(int, int)} for the first pointer index (may be an 1766 * arbitrary pointer identifier). 1767 * 1768 * @param pos Which historical value to return; must be less than 1769 * {@link #getHistorySize} 1770 * 1771 * @see #getHistorySize 1772 * @see #getToolMajor() 1773 * @see #AXIS_TOOL_MAJOR 1774 */ 1775 public final float getHistoricalToolMajor(int pos) { 1776 return nativeGetAxisValue(mNativePtr, AXIS_TOOL_MAJOR, 0, pos); 1777 } 1778 1779 /** 1780 * {@link #getHistoricalToolMinor(int, int)} for the first pointer index (may be an 1781 * arbitrary pointer identifier). 1782 * 1783 * @param pos Which historical value to return; must be less than 1784 * {@link #getHistorySize} 1785 * 1786 * @see #getHistorySize 1787 * @see #getToolMinor() 1788 * @see #AXIS_TOOL_MINOR 1789 */ 1790 public final float getHistoricalToolMinor(int pos) { 1791 return nativeGetAxisValue(mNativePtr, AXIS_TOOL_MINOR, 0, pos); 1792 } 1793 1794 /** 1795 * {@link #getHistoricalOrientation(int, int)} for the first pointer index (may be an 1796 * arbitrary pointer identifier). 1797 * 1798 * @param pos Which historical value to return; must be less than 1799 * {@link #getHistorySize} 1800 * 1801 * @see #getHistorySize 1802 * @see #getOrientation() 1803 * @see #AXIS_ORIENTATION 1804 */ 1805 public final float getHistoricalOrientation(int pos) { 1806 return nativeGetAxisValue(mNativePtr, AXIS_ORIENTATION, 0, pos); 1807 } 1808 1809 /** 1810 * {@link #getHistoricalAxisValue(int, int, int)} for the first pointer index (may be an 1811 * arbitrary pointer identifier). 1812 * 1813 * @param axis The axis identifier for the axis value to retrieve. 1814 * @param pos Which historical value to return; must be less than 1815 * {@link #getHistorySize} 1816 * 1817 * @see #getHistorySize 1818 * @see #getAxisValue(int) 1819 * @see #AXIS_X 1820 * @see #AXIS_Y 1821 */ 1822 public final float getHistoricalAxisValue(int axis, int pos) { 1823 return nativeGetAxisValue(mNativePtr, axis, 0, pos); 1824 } 1825 1826 /** 1827 * Returns a historical X coordinate, as per {@link #getX(int)}, that 1828 * occurred between this event and the previous event for the given pointer. 1829 * Only applies to ACTION_MOVE events. 1830 * 1831 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 1832 * (the first pointer that is down) to {@link #getPointerCount()}-1. 1833 * @param pos Which historical value to return; must be less than 1834 * {@link #getHistorySize} 1835 * 1836 * @see #getHistorySize 1837 * @see #getX(int) 1838 * @see #AXIS_X 1839 */ 1840 public final float getHistoricalX(int pointerIndex, int pos) { 1841 return nativeGetAxisValue(mNativePtr, AXIS_X, pointerIndex, pos); 1842 } 1843 1844 /** 1845 * Returns a historical Y coordinate, as per {@link #getY(int)}, that 1846 * occurred between this event and the previous event for the given pointer. 1847 * Only applies to ACTION_MOVE events. 1848 * 1849 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 1850 * (the first pointer that is down) to {@link #getPointerCount()}-1. 1851 * @param pos Which historical value to return; must be less than 1852 * {@link #getHistorySize} 1853 * 1854 * @see #getHistorySize 1855 * @see #getY(int) 1856 * @see #AXIS_Y 1857 */ 1858 public final float getHistoricalY(int pointerIndex, int pos) { 1859 return nativeGetAxisValue(mNativePtr, AXIS_Y, pointerIndex, pos); 1860 } 1861 1862 /** 1863 * Returns a historical pressure coordinate, as per {@link #getPressure(int)}, 1864 * that occurred between this event and the previous event for the given 1865 * pointer. Only applies to ACTION_MOVE events. 1866 * 1867 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 1868 * (the first pointer that is down) to {@link #getPointerCount()}-1. 1869 * @param pos Which historical value to return; must be less than 1870 * {@link #getHistorySize} 1871 * 1872 * @see #getHistorySize 1873 * @see #getPressure(int) 1874 * @see #AXIS_PRESSURE 1875 */ 1876 public final float getHistoricalPressure(int pointerIndex, int pos) { 1877 return nativeGetAxisValue(mNativePtr, AXIS_PRESSURE, pointerIndex, pos); 1878 } 1879 1880 /** 1881 * Returns a historical size coordinate, as per {@link #getSize(int)}, that 1882 * occurred between this event and the previous event for the given pointer. 1883 * Only applies to ACTION_MOVE events. 1884 * 1885 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 1886 * (the first pointer that is down) to {@link #getPointerCount()}-1. 1887 * @param pos Which historical value to return; must be less than 1888 * {@link #getHistorySize} 1889 * 1890 * @see #getHistorySize 1891 * @see #getSize(int) 1892 * @see #AXIS_SIZE 1893 */ 1894 public final float getHistoricalSize(int pointerIndex, int pos) { 1895 return nativeGetAxisValue(mNativePtr, AXIS_SIZE, pointerIndex, pos); 1896 } 1897 1898 /** 1899 * Returns a historical touch major axis coordinate, as per {@link #getTouchMajor(int)}, that 1900 * occurred between this event and the previous event for the given pointer. 1901 * Only applies to ACTION_MOVE events. 1902 * 1903 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 1904 * (the first pointer that is down) to {@link #getPointerCount()}-1. 1905 * @param pos Which historical value to return; must be less than 1906 * {@link #getHistorySize} 1907 * 1908 * @see #getHistorySize 1909 * @see #getTouchMajor(int) 1910 * @see #AXIS_TOUCH_MAJOR 1911 */ 1912 public final float getHistoricalTouchMajor(int pointerIndex, int pos) { 1913 return nativeGetAxisValue(mNativePtr, AXIS_TOUCH_MAJOR, pointerIndex, pos); 1914 } 1915 1916 /** 1917 * Returns a historical touch minor axis coordinate, as per {@link #getTouchMinor(int)}, that 1918 * occurred between this event and the previous event for the given pointer. 1919 * Only applies to ACTION_MOVE events. 1920 * 1921 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 1922 * (the first pointer that is down) to {@link #getPointerCount()}-1. 1923 * @param pos Which historical value to return; must be less than 1924 * {@link #getHistorySize} 1925 * 1926 * @see #getHistorySize 1927 * @see #getTouchMinor(int) 1928 * @see #AXIS_TOUCH_MINOR 1929 */ 1930 public final float getHistoricalTouchMinor(int pointerIndex, int pos) { 1931 return nativeGetAxisValue(mNativePtr, AXIS_TOUCH_MINOR, pointerIndex, pos); 1932 } 1933 1934 /** 1935 * Returns a historical tool major axis coordinate, as per {@link #getToolMajor(int)}, that 1936 * occurred between this event and the previous event for the given pointer. 1937 * Only applies to ACTION_MOVE events. 1938 * 1939 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 1940 * (the first pointer that is down) to {@link #getPointerCount()}-1. 1941 * @param pos Which historical value to return; must be less than 1942 * {@link #getHistorySize} 1943 * 1944 * @see #getHistorySize 1945 * @see #getToolMajor(int) 1946 * @see #AXIS_TOOL_MAJOR 1947 */ 1948 public final float getHistoricalToolMajor(int pointerIndex, int pos) { 1949 return nativeGetAxisValue(mNativePtr, AXIS_TOOL_MAJOR, pointerIndex, pos); 1950 } 1951 1952 /** 1953 * Returns a historical tool minor axis coordinate, as per {@link #getToolMinor(int)}, that 1954 * occurred between this event and the previous event for the given pointer. 1955 * Only applies to ACTION_MOVE events. 1956 * 1957 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 1958 * (the first pointer that is down) to {@link #getPointerCount()}-1. 1959 * @param pos Which historical value to return; must be less than 1960 * {@link #getHistorySize} 1961 * 1962 * @see #getHistorySize 1963 * @see #getToolMinor(int) 1964 * @see #AXIS_TOOL_MINOR 1965 */ 1966 public final float getHistoricalToolMinor(int pointerIndex, int pos) { 1967 return nativeGetAxisValue(mNativePtr, AXIS_TOOL_MINOR, pointerIndex, pos); 1968 } 1969 1970 /** 1971 * Returns a historical orientation coordinate, as per {@link #getOrientation(int)}, that 1972 * occurred between this event and the previous event for the given pointer. 1973 * Only applies to ACTION_MOVE events. 1974 * 1975 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 1976 * (the first pointer that is down) to {@link #getPointerCount()}-1. 1977 * @param pos Which historical value to return; must be less than 1978 * {@link #getHistorySize} 1979 * 1980 * @see #getHistorySize 1981 * @see #getOrientation(int) 1982 * @see #AXIS_ORIENTATION 1983 */ 1984 public final float getHistoricalOrientation(int pointerIndex, int pos) { 1985 return nativeGetAxisValue(mNativePtr, AXIS_ORIENTATION, pointerIndex, pos); 1986 } 1987 1988 /** 1989 * Returns the historical value of the requested axis, as per {@link #getAxisValue(int, int)}, 1990 * occurred between this event and the previous event for the given pointer. 1991 * Only applies to ACTION_MOVE events. 1992 * 1993 * @param axis The axis identifier for the axis value to retrieve. 1994 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 1995 * (the first pointer that is down) to {@link #getPointerCount()}-1. 1996 * @param pos Which historical value to return; must be less than 1997 * {@link #getHistorySize} 1998 * @return The value of the axis, or 0 if the axis is not available. 1999 * 2000 * @see #AXIS_X 2001 * @see #AXIS_Y 2002 */ 2003 public final float getHistoricalAxisValue(int axis, int pointerIndex, int pos) { 2004 return nativeGetAxisValue(mNativePtr, axis, pointerIndex, pos); 2005 } 2006 2007 /** 2008 * Populates a {@link PointerCoords} object with historical pointer coordinate data, 2009 * as per {@link #getPointerCoords}, that occurred between this event and the previous 2010 * event for the given pointer. 2011 * Only applies to ACTION_MOVE events. 2012 * 2013 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0 2014 * (the first pointer that is down) to {@link #getPointerCount()}-1. 2015 * @param pos Which historical value to return; must be less than 2016 * {@link #getHistorySize} 2017 * @param outPointerCoords The pointer coordinate object to populate. 2018 * 2019 * @see #getHistorySize 2020 * @see #getPointerCoords 2021 * @see PointerCoords 2022 */ 2023 public final void getHistoricalPointerCoords(int pointerIndex, int pos, 2024 PointerCoords outPointerCoords) { 2025 nativeGetPointerCoords(mNativePtr, pointerIndex, pos, outPointerCoords); 2026 } 2027 2028 /** 2029 * Returns a bitfield indicating which edges, if any, were touched by this 2030 * MotionEvent. For touch events, clients can use this to determine if the 2031 * user's finger was touching the edge of the display. 2032 * 2033 * @see #EDGE_LEFT 2034 * @see #EDGE_TOP 2035 * @see #EDGE_RIGHT 2036 * @see #EDGE_BOTTOM 2037 */ 2038 public final int getEdgeFlags() { 2039 return nativeGetEdgeFlags(mNativePtr); 2040 } 2041 2042 /** 2043 * Sets the bitfield indicating which edges, if any, were touched by this 2044 * MotionEvent. 2045 * 2046 * @see #getEdgeFlags() 2047 */ 2048 public final void setEdgeFlags(int flags) { 2049 nativeSetEdgeFlags(mNativePtr, flags); 2050 } 2051 2052 /** 2053 * Sets this event's action. 2054 */ 2055 public final void setAction(int action) { 2056 nativeSetAction(mNativePtr, action); 2057 } 2058 2059 /** 2060 * Adjust this event's location. 2061 * @param deltaX Amount to add to the current X coordinate of the event. 2062 * @param deltaY Amount to add to the current Y coordinate of the event. 2063 */ 2064 public final void offsetLocation(float deltaX, float deltaY) { 2065 nativeOffsetLocation(mNativePtr, deltaX, deltaY); 2066 } 2067 2068 /** 2069 * Set this event's location. Applies {@link #offsetLocation} with a 2070 * delta from the current location to the given new location. 2071 * 2072 * @param x New absolute X location. 2073 * @param y New absolute Y location. 2074 */ 2075 public final void setLocation(float x, float y) { 2076 float oldX = getX(); 2077 float oldY = getY(); 2078 nativeOffsetLocation(mNativePtr, x - oldX, y - oldY); 2079 } 2080 2081 /** 2082 * Applies a transformation matrix to all of the points in the event. 2083 * 2084 * @param matrix The transformation matrix to apply. 2085 */ 2086 public final void transform(Matrix matrix) { 2087 if (matrix == null) { 2088 throw new IllegalArgumentException("matrix must not be null"); 2089 } 2090 2091 nativeTransform(mNativePtr, matrix); 2092 } 2093 2094 /** 2095 * Add a new movement to the batch of movements in this event. The event's 2096 * current location, position and size is updated to the new values. 2097 * The current values in the event are added to a list of historical values. 2098 * 2099 * Only applies to {@link #ACTION_MOVE} events. 2100 * 2101 * @param eventTime The time stamp (in ms) for this data. 2102 * @param x The new X position. 2103 * @param y The new Y position. 2104 * @param pressure The new pressure. 2105 * @param size The new size. 2106 * @param metaState Meta key state. 2107 */ 2108 public final void addBatch(long eventTime, float x, float y, 2109 float pressure, float size, int metaState) { 2110 synchronized (gTmpPointerCoords) { 2111 final PointerCoords pc = gTmpPointerCoords[0]; 2112 pc.clear(); 2113 pc.x = x; 2114 pc.y = y; 2115 pc.pressure = pressure; 2116 pc.size = size; 2117 nativeAddBatch(mNativePtr, eventTime * NS_PER_MS, gTmpPointerCoords, metaState); 2118 } 2119 } 2120 2121 /** 2122 * Add a new movement to the batch of movements in this event. The event's 2123 * current location, position and size is updated to the new values. 2124 * The current values in the event are added to a list of historical values. 2125 * 2126 * Only applies to {@link #ACTION_MOVE} events. 2127 * 2128 * @param eventTime The time stamp (in ms) for this data. 2129 * @param pointerCoords The new pointer coordinates. 2130 * @param metaState Meta key state. 2131 */ 2132 public final void addBatch(long eventTime, PointerCoords[] pointerCoords, int metaState) { 2133 nativeAddBatch(mNativePtr, eventTime * NS_PER_MS, pointerCoords, metaState); 2134 } 2135 2136 @Override 2137 public String toString() { 2138 return "MotionEvent{" + Integer.toHexString(System.identityHashCode(this)) 2139 + " pointerId=" + getPointerId(0) 2140 + " action=" + actionToString(getAction()) 2141 + " x=" + getX() 2142 + " y=" + getY() 2143 + " pressure=" + getPressure() 2144 + " size=" + getSize() 2145 + " touchMajor=" + getTouchMajor() 2146 + " touchMinor=" + getTouchMinor() 2147 + " toolMajor=" + getToolMajor() 2148 + " toolMinor=" + getToolMinor() 2149 + " orientation=" + getOrientation() 2150 + " meta=" + KeyEvent.metaStateToString(getMetaState()) 2151 + " pointerCount=" + getPointerCount() 2152 + " historySize=" + getHistorySize() 2153 + " flags=0x" + Integer.toHexString(getFlags()) 2154 + " edgeFlags=0x" + Integer.toHexString(getEdgeFlags()) 2155 + " device=" + getDeviceId() 2156 + " source=0x" + Integer.toHexString(getSource()) 2157 + (getPointerCount() > 1 ? 2158 " pointerId2=" + getPointerId(1) + " x2=" + getX(1) + " y2=" + getY(1) : "") 2159 + "}"; 2160 } 2161 2162 /** 2163 * Returns a string that represents the symbolic name of the specified action 2164 * such as "ACTION_DOWN", "ACTION_POINTER_DOWN(3)" or an equivalent numeric constant 2165 * such as "35" if unknown. 2166 * 2167 * @param action The action. 2168 * @return The symbolic name of the specified action. 2169 * @hide 2170 */ 2171 public static String actionToString(int action) { 2172 switch (action) { 2173 case ACTION_DOWN: 2174 return "ACTION_DOWN"; 2175 case ACTION_UP: 2176 return "ACTION_UP"; 2177 case ACTION_CANCEL: 2178 return "ACTION_CANCEL"; 2179 case ACTION_MOVE: 2180 return "ACTION_MOVE"; 2181 } 2182 int index = (action & ACTION_POINTER_INDEX_MASK) >> ACTION_POINTER_INDEX_SHIFT; 2183 switch (action & ACTION_MASK) { 2184 case ACTION_POINTER_DOWN: 2185 return "ACTION_POINTER_DOWN(" + index + ")"; 2186 case ACTION_POINTER_UP: 2187 return "ACTION_POINTER_UP(" + index + ")"; 2188 default: 2189 return Integer.toString(action); 2190 } 2191 } 2192 2193 /** 2194 * Returns a string that represents the symbolic name of the specified axis 2195 * such as "AXIS_X" or an equivalent numeric constant such as "42" if unknown. 2196 * 2197 * @param axis The axis 2198 * @return The symbolic name of the specified axis. 2199 */ 2200 public static String axisToString(int axis) { 2201 String symbolicName = AXIS_SYMBOLIC_NAMES.get(axis); 2202 return symbolicName != null ? symbolicName : Integer.toString(axis); 2203 } 2204 2205 /** 2206 * Gets an axis by its symbolic name such as "KEYCODE_A" or an 2207 * equivalent numeric constant such as "1001". 2208 * 2209 * @param symbolicName The symbolic name of the axis. 2210 * @return The axis or -1 if not found. 2211 * @see #keycodeToString 2212 */ 2213 public static int axisFromString(String symbolicName) { 2214 if (symbolicName == null) { 2215 throw new IllegalArgumentException("symbolicName must not be null"); 2216 } 2217 2218 final int count = AXIS_SYMBOLIC_NAMES.size(); 2219 for (int i = 0; i < count; i++) { 2220 if (symbolicName.equals(AXIS_SYMBOLIC_NAMES.valueAt(i))) { 2221 return i; 2222 } 2223 } 2224 2225 try { 2226 return Integer.parseInt(symbolicName, 10); 2227 } catch (NumberFormatException ex) { 2228 return -1; 2229 } 2230 } 2231 2232 public static final Parcelable.Creator<MotionEvent> CREATOR 2233 = new Parcelable.Creator<MotionEvent>() { 2234 public MotionEvent createFromParcel(Parcel in) { 2235 in.readInt(); // skip token, we already know this is a MotionEvent 2236 return MotionEvent.createFromParcelBody(in); 2237 } 2238 2239 public MotionEvent[] newArray(int size) { 2240 return new MotionEvent[size]; 2241 } 2242 }; 2243 2244 /** @hide */ 2245 public static MotionEvent createFromParcelBody(Parcel in) { 2246 MotionEvent ev = obtain(); 2247 ev.mNativePtr = nativeReadFromParcel(ev.mNativePtr, in); 2248 return ev; 2249 } 2250 2251 public void writeToParcel(Parcel out, int flags) { 2252 out.writeInt(PARCEL_TOKEN_MOTION_EVENT); 2253 nativeWriteToParcel(mNativePtr, out); 2254 } 2255 2256 /** 2257 * Transfer object for pointer coordinates. 2258 * 2259 * Objects of this type can be used to manufacture new {@link MotionEvent} objects 2260 * and to query pointer coordinate information in bulk. 2261 * 2262 * Refer to {@link InputDevice} for information about how different kinds of 2263 * input devices and sources represent pointer coordinates. 2264 */ 2265 public static final class PointerCoords { 2266 private static final int INITIAL_PACKED_AXIS_VALUES = 8; 2267 private long mPackedAxisBits; 2268 private float[] mPackedAxisValues; 2269 2270 /** 2271 * Creates a pointer coords object with all axes initialized to zero. 2272 */ 2273 public PointerCoords() { 2274 } 2275 2276 /** 2277 * Creates a pointer coords object as a copy of the 2278 * contents of another pointer coords object. 2279 * 2280 * @param other The pointer coords object to copy. 2281 */ 2282 public PointerCoords(PointerCoords other) { 2283 copyFrom(other); 2284 } 2285 2286 /** 2287 * The X component of the pointer movement. 2288 * 2289 * @see MotionEvent#AXIS_X 2290 */ 2291 public float x; 2292 2293 /** 2294 * The Y component of the pointer movement. 2295 * 2296 * @see MotionEvent#AXIS_Y 2297 */ 2298 public float y; 2299 2300 /** 2301 * A normalized value that describes the pressure applied to the device 2302 * by a finger or other tool. 2303 * The pressure generally ranges from 0 (no pressure at all) to 1 (normal pressure), 2304 * although values higher than 1 may be generated depending on the calibration of 2305 * the input device. 2306 * 2307 * @see MotionEvent#AXIS_PRESSURE 2308 */ 2309 public float pressure; 2310 2311 /** 2312 * A normalized value that describes the approximate size of the pointer touch area 2313 * in relation to the maximum detectable size of the device. 2314 * It represents some approximation of the area of the screen being 2315 * pressed; the actual value in pixels corresponding to the 2316 * touch is normalized with the device specific range of values 2317 * and scaled to a value between 0 and 1. The value of size can be used to 2318 * determine fat touch events. 2319 * 2320 * @see MotionEvent#AXIS_SIZE 2321 */ 2322 public float size; 2323 2324 /** 2325 * The length of the major axis of an ellipse that describes the touch area at 2326 * the point of contact. 2327 * If the device is a touch screen, the length is reported in pixels, otherwise it is 2328 * reported in device-specific units. 2329 * 2330 * @see MotionEvent#AXIS_TOUCH_MAJOR 2331 */ 2332 public float touchMajor; 2333 2334 /** 2335 * The length of the minor axis of an ellipse that describes the touch area at 2336 * the point of contact. 2337 * If the device is a touch screen, the length is reported in pixels, otherwise it is 2338 * reported in device-specific units. 2339 * 2340 * @see MotionEvent#AXIS_TOUCH_MINOR 2341 */ 2342 public float touchMinor; 2343 2344 /** 2345 * The length of the major axis of an ellipse that describes the size of 2346 * the approaching tool. 2347 * The tool area represents the estimated size of the finger or pen that is 2348 * touching the device independent of its actual touch area at the point of contact. 2349 * If the device is a touch screen, the length is reported in pixels, otherwise it is 2350 * reported in device-specific units. 2351 * 2352 * @see MotionEvent#AXIS_TOOL_MAJOR 2353 */ 2354 public float toolMajor; 2355 2356 /** 2357 * The length of the minor axis of an ellipse that describes the size of 2358 * the approaching tool. 2359 * The tool area represents the estimated size of the finger or pen that is 2360 * touching the device independent of its actual touch area at the point of contact. 2361 * If the device is a touch screen, the length is reported in pixels, otherwise it is 2362 * reported in device-specific units. 2363 * 2364 * @see MotionEvent#AXIS_TOOL_MINOR 2365 */ 2366 public float toolMinor; 2367 2368 /** 2369 * The orientation of the touch area and tool area in radians clockwise from vertical. 2370 * An angle of 0 radians indicates that the major axis of contact is oriented 2371 * upwards, is perfectly circular or is of unknown orientation. A positive angle 2372 * indicates that the major axis of contact is oriented to the right. A negative angle 2373 * indicates that the major axis of contact is oriented to the left. 2374 * The full range is from -PI/2 radians (finger pointing fully left) to PI/2 radians 2375 * (finger pointing fully right). 2376 * 2377 * @see MotionEvent#AXIS_ORIENTATION 2378 */ 2379 public float orientation; 2380 2381 /** 2382 * Clears the contents of this object. 2383 * Resets all axes to zero. 2384 */ 2385 public void clear() { 2386 mPackedAxisBits = 0; 2387 2388 x = 0; 2389 y = 0; 2390 pressure = 0; 2391 size = 0; 2392 touchMajor = 0; 2393 touchMinor = 0; 2394 toolMajor = 0; 2395 toolMinor = 0; 2396 orientation = 0; 2397 } 2398 2399 /** 2400 * Copies the contents of another pointer coords object. 2401 * 2402 * @param other The pointer coords object to copy. 2403 */ 2404 public void copyFrom(PointerCoords other) { 2405 final long bits = other.mPackedAxisBits; 2406 mPackedAxisBits = bits; 2407 if (bits != 0) { 2408 final float[] otherValues = other.mPackedAxisValues; 2409 final int count = Long.bitCount(bits); 2410 float[] values = mPackedAxisValues; 2411 if (values == null || count > values.length) { 2412 values = new float[otherValues.length]; 2413 mPackedAxisValues = values; 2414 } 2415 System.arraycopy(otherValues, 0, values, 0, count); 2416 } 2417 2418 x = other.x; 2419 y = other.y; 2420 pressure = other.pressure; 2421 size = other.size; 2422 touchMajor = other.touchMajor; 2423 touchMinor = other.touchMinor; 2424 toolMajor = other.toolMajor; 2425 toolMinor = other.toolMinor; 2426 orientation = other.orientation; 2427 } 2428 2429 /** 2430 * Gets the value associated with the specified axis. 2431 * 2432 * @param axis The axis identifier for the axis value to retrieve. 2433 * @return The value associated with the axis, or 0 if none. 2434 * 2435 * @see MotionEvent#AXIS_X 2436 * @see MotionEvent#AXIS_Y 2437 */ 2438 public float getAxisValue(int axis) { 2439 switch (axis) { 2440 case AXIS_X: 2441 return x; 2442 case AXIS_Y: 2443 return y; 2444 case AXIS_PRESSURE: 2445 return pressure; 2446 case AXIS_SIZE: 2447 return size; 2448 case AXIS_TOUCH_MAJOR: 2449 return touchMajor; 2450 case AXIS_TOUCH_MINOR: 2451 return touchMinor; 2452 case AXIS_TOOL_MAJOR: 2453 return toolMajor; 2454 case AXIS_TOOL_MINOR: 2455 return toolMinor; 2456 case AXIS_ORIENTATION: 2457 return orientation; 2458 default: { 2459 if (axis < 0 || axis > 63) { 2460 throw new IllegalArgumentException("Axis out of range."); 2461 } 2462 final long bits = mPackedAxisBits; 2463 final long axisBit = 1L << axis; 2464 if ((bits & axisBit) == 0) { 2465 return 0; 2466 } 2467 final int index = Long.bitCount(bits & (axisBit - 1L)); 2468 return mPackedAxisValues[index]; 2469 } 2470 } 2471 } 2472 2473 /** 2474 * Sets the value associated with the specified axis. 2475 * 2476 * @param axis The axis identifier for the axis value to assign. 2477 * @param value The value to set. 2478 * 2479 * @see MotionEvent#AXIS_X 2480 * @see MotionEvent#AXIS_Y 2481 */ 2482 public void setAxisValue(int axis, float value) { 2483 switch (axis) { 2484 case AXIS_X: 2485 x = value; 2486 break; 2487 case AXIS_Y: 2488 y = value; 2489 break; 2490 case AXIS_PRESSURE: 2491 pressure = value; 2492 break; 2493 case AXIS_SIZE: 2494 size = value; 2495 break; 2496 case AXIS_TOUCH_MAJOR: 2497 touchMajor = value; 2498 break; 2499 case AXIS_TOUCH_MINOR: 2500 touchMinor = value; 2501 break; 2502 case AXIS_TOOL_MAJOR: 2503 toolMajor = value; 2504 break; 2505 case AXIS_TOOL_MINOR: 2506 toolMinor = value; 2507 break; 2508 case AXIS_ORIENTATION: 2509 orientation = value; 2510 break; 2511 default: { 2512 if (axis < 0 || axis > 63) { 2513 throw new IllegalArgumentException("Axis out of range."); 2514 } 2515 final long bits = mPackedAxisBits; 2516 final long axisBit = 1L << axis; 2517 final int index = Long.bitCount(bits & (axisBit - 1L)); 2518 float[] values = mPackedAxisValues; 2519 if ((bits & axisBit) == 0) { 2520 if (values == null) { 2521 values = new float[INITIAL_PACKED_AXIS_VALUES]; 2522 mPackedAxisValues = values; 2523 } else { 2524 final int count = Long.bitCount(bits); 2525 if (count < values.length) { 2526 if (index != count) { 2527 System.arraycopy(values, index, values, index + 1, 2528 count - index); 2529 } 2530 } else { 2531 float[] newValues = new float[count * 2]; 2532 System.arraycopy(values, 0, newValues, 0, index); 2533 System.arraycopy(values, index, newValues, index + 1, 2534 count - index); 2535 values = newValues; 2536 mPackedAxisValues = values; 2537 } 2538 } 2539 mPackedAxisBits = bits | axisBit; 2540 } 2541 values[index] = value; 2542 } 2543 } 2544 } 2545 } 2546} 2547