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