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