2 * Copyright (C) 2007 The Android Open Source Project
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
19 import android.os.Parcel;
20 import android.os.Parcelable;
21 import android.os.SystemClock;
24 * Object used to report movement (mouse, pen, finger, trackball) events. This
25 * class may hold either absolute or relative movements, depending on what
26 * it is being used for.
28 * On pointing devices such as touch screens, pointer coordinates specify absolute
29 * positions such as view X/Y coordinates. Each complete gesture is represented
30 * by a sequence of motion events with actions that describe pointer state transitions
31 * and movements. A gesture starts with a motion event with {@link #ACTION_DOWN}
32 * that provides the location of the first pointer down. As each additional
33 * pointer that goes down or up, the framework will generate a motion event with
34 * {@link #ACTION_POINTER_DOWN} or {@link #ACTION_POINTER_UP} accordingly.
35 * Pointer movements are described by motion events with {@link #ACTION_MOVE}.
36 * Finally, a gesture end either when the final pointer goes up as represented
37 * by a motion event with {@link #ACTION_UP} or when gesture is canceled
38 * with {@link #ACTION_CANCEL}.
40 * On trackballs, the pointer coordinates specify relative movements as X/Y deltas.
41 * A trackball gesture consists of a sequence of movements described by motion
42 * events with {@link #ACTION_MOVE} interspersed with occasional {@link #ACTION_DOWN}
43 * or {@link #ACTION_UP} motion events when the trackball button is pressed or released.
45 * Motion events always report movements for all pointers at once. The number
46 * of pointers only ever changes by one as individual pointers go up and down,
47 * except when the gesture is canceled.
49 * The order in which individual pointers appear within a motion event can change
50 * from one event to the next. Use the {@link #getPointerId(int)} method to obtain a
51 * pointer id to track pointers across motion events in a gesture. Then for
52 * successive motion events, use the {@link #findPointerIndex(int)} method to obtain
53 * the pointer index for a given pointer id in that motion event.
55 * For efficiency, motion events with {@link #ACTION_MOVE} may batch together
56 * multiple movement samples within a single object. The most current
57 * pointer coordinates are available using {@link #getX(int)} and {@link #getY(int)}.
58 * Earlier coordinates within the batch are accessed using {@link #getHistoricalX(int, int)}
59 * and {@link #getHistoricalY(int, int)}. The coordinates are "historical" only
60 * insofar as they are older than the current coordinates in the batch; however,
61 * they are still distinct from any other coordinates reported in prior motion events.
62 * To process all coordinates in the batch in time order, first consume the historical
63 * coordinates then consume the current coordinates.
65 * Example: Consuming all samples for all pointers in a motion event in time order.
67 * void printSamples(MotionEvent ev) {
68 * final int historySize = ev.getHistorySize();
69 * final int pointerCount = ev.getPointerCount();
70 * for (int h = 0; h < historySize; h++) {
71 * System.out.printf("At time %d:", ev.getHistoricalEventTime(h));
72 * for (int p = 0; p < pointerCount; p++) {
73 * System.out.printf(" pointer %d: (%f,%f)",
74 * ev.getPointerId(p), ev.getHistoricalX(p, h), ev.getHistoricalY(p, h));
77 * System.out.printf("At time %d:", ev.getEventTime());
78 * for (int p = 0; p < pointerCount; p++) {
79 * System.out.printf(" pointer %d: (%f,%f)",
80 * ev.getPointerId(p), ev.getX(p), ev.getY(p));
83 * </code></pre></p><p>
84 * In general, the framework cannot guarantee that the motion events it delivers
85 * to a view always constitute a complete motion sequences since some events may be dropped
86 * or modified by containing views before they are delivered. The view implementation
87 * should be prepared to handle {@link #ACTION_CANCEL} and should tolerate anomalous
88 * situations such as receiving a new {@link #ACTION_DOWN} without first having
89 * received an {@link #ACTION_UP} for the prior gesture.
91 * Refer to {@link InputDevice} for more information about how different kinds of
92 * input devices and sources represent pointer coordinates.
95 public final class MotionEvent extends InputEvent implements Parcelable {
96 private static final long MS_PER_NS = 1000000;
97 private static final boolean TRACK_RECYCLED_LOCATION = false;
100 * Bit mask of the parts of the action code that are the action itself.
102 public static final int ACTION_MASK = 0xff;
105 * Constant for {@link #getAction}: A pressed gesture has started, the
106 * motion contains the initial starting location.
108 public static final int ACTION_DOWN = 0;
111 * Constant for {@link #getAction}: A pressed gesture has finished, the
112 * motion contains the final release location as well as any intermediate
113 * points since the last down or move event.
115 public static final int ACTION_UP = 1;
118 * Constant for {@link #getAction}: A change has happened during a
119 * press gesture (between {@link #ACTION_DOWN} and {@link #ACTION_UP}).
120 * The motion contains the most recent point, as well as any intermediate
121 * points since the last down or move event.
123 public static final int ACTION_MOVE = 2;
126 * Constant for {@link #getAction}: The current gesture has been aborted.
127 * You will not receive any more points in it. You should treat this as
128 * an up event, but not perform any action that you normally would.
130 public static final int ACTION_CANCEL = 3;
133 * Constant for {@link #getAction}: A movement has happened outside of the
134 * normal bounds of the UI element. This does not provide a full gesture,
135 * but only the initial location of the movement/touch.
137 public static final int ACTION_OUTSIDE = 4;
140 * A non-primary pointer has gone down. The bits in
141 * {@link #ACTION_POINTER_ID_MASK} indicate which pointer changed.
143 public static final int ACTION_POINTER_DOWN = 5;
146 * A non-primary pointer has gone up. The bits in
147 * {@link #ACTION_POINTER_ID_MASK} indicate which pointer changed.
149 public static final int ACTION_POINTER_UP = 6;
152 * Bits in the action code that represent a pointer index, used with
153 * {@link #ACTION_POINTER_DOWN} and {@link #ACTION_POINTER_UP}. Shifting
154 * down by {@link #ACTION_POINTER_INDEX_SHIFT} provides the actual pointer
155 * index where the data for the pointer going up or down can be found; you can
156 * get its identifier with {@link #getPointerId(int)} and the actual
157 * data with {@link #getX(int)} etc.
159 public static final int ACTION_POINTER_INDEX_MASK = 0xff00;
162 * Bit shift for the action bits holding the pointer index as
163 * defined by {@link #ACTION_POINTER_INDEX_MASK}.
165 public static final int ACTION_POINTER_INDEX_SHIFT = 8;
168 * @deprecated Use {@link #ACTION_POINTER_INDEX_MASK} to retrieve the
169 * data index associated with {@link #ACTION_POINTER_DOWN}.
172 public static final int ACTION_POINTER_1_DOWN = ACTION_POINTER_DOWN | 0x0000;
175 * @deprecated Use {@link #ACTION_POINTER_INDEX_MASK} to retrieve the
176 * data index associated with {@link #ACTION_POINTER_DOWN}.
179 public static final int ACTION_POINTER_2_DOWN = ACTION_POINTER_DOWN | 0x0100;
182 * @deprecated Use {@link #ACTION_POINTER_INDEX_MASK} to retrieve the
183 * data index associated with {@link #ACTION_POINTER_DOWN}.
186 public static final int ACTION_POINTER_3_DOWN = ACTION_POINTER_DOWN | 0x0200;
189 * @deprecated Use {@link #ACTION_POINTER_INDEX_MASK} to retrieve the
190 * data index associated with {@link #ACTION_POINTER_UP}.
193 public static final int ACTION_POINTER_1_UP = ACTION_POINTER_UP | 0x0000;
196 * @deprecated Use {@link #ACTION_POINTER_INDEX_MASK} to retrieve the
197 * data index associated with {@link #ACTION_POINTER_UP}.
200 public static final int ACTION_POINTER_2_UP = ACTION_POINTER_UP | 0x0100;
203 * @deprecated Use {@link #ACTION_POINTER_INDEX_MASK} to retrieve the
204 * data index associated with {@link #ACTION_POINTER_UP}.
207 public static final int ACTION_POINTER_3_UP = ACTION_POINTER_UP | 0x0200;
210 * @deprecated Renamed to {@link #ACTION_POINTER_INDEX_MASK} to match
211 * the actual data contained in these bits.
214 public static final int ACTION_POINTER_ID_MASK = 0xff00;
217 * @deprecated Renamed to {@link #ACTION_POINTER_INDEX_SHIFT} to match
218 * the actual data contained in these bits.
221 public static final int ACTION_POINTER_ID_SHIFT = 8;
224 * This flag indicates that the window that received this motion event is partly
225 * or wholly obscured by another visible window above it. This flag is set to true
226 * even if the event did not directly pass through the obscured area.
227 * A security sensitive application can check this flag to identify situations in which
228 * a malicious application may have covered up part of its content for the purpose
229 * of misleading the user or hijacking touches. An appropriate response might be
230 * to drop the suspect touches or to take additional precautions to confirm the user's
233 public static final int FLAG_WINDOW_IS_OBSCURED = 0x1;
236 * Flag indicating the motion event intersected the top edge of the screen.
238 public static final int EDGE_TOP = 0x00000001;
241 * Flag indicating the motion event intersected the bottom edge of the screen.
243 public static final int EDGE_BOTTOM = 0x00000002;
246 * Flag indicating the motion event intersected the left edge of the screen.
248 public static final int EDGE_LEFT = 0x00000004;
251 * Flag indicating the motion event intersected the right edge of the screen.
253 public static final int EDGE_RIGHT = 0x00000008;
256 * Offset for the sample's X coordinate.
258 static private final int SAMPLE_X = 0;
261 * Offset for the sample's Y coordinate.
263 static private final int SAMPLE_Y = 1;
266 * Offset for the sample's pressure.
268 static private final int SAMPLE_PRESSURE = 2;
271 * Offset for the sample's size
273 static private final int SAMPLE_SIZE = 3;
276 * Offset for the sample's touch major axis length.
278 static private final int SAMPLE_TOUCH_MAJOR = 4;
281 * Offset for the sample's touch minor axis length.
283 static private final int SAMPLE_TOUCH_MINOR = 5;
286 * Offset for the sample's tool major axis length.
288 static private final int SAMPLE_TOOL_MAJOR = 6;
291 * Offset for the sample's tool minor axis length.
293 static private final int SAMPLE_TOOL_MINOR = 7;
296 * Offset for the sample's orientation.
298 static private final int SAMPLE_ORIENTATION = 8;
301 * Number of data items for each sample.
303 static private final int NUM_SAMPLE_DATA = 9;
306 * Minimum number of pointers for which to reserve space when allocating new
307 * motion events. This is explicitly not a bound on the maximum number of pointers.
309 static private final int BASE_AVAIL_POINTERS = 5;
312 * Minimum number of samples for which to reserve space when allocating new motion events.
314 static private final int BASE_AVAIL_SAMPLES = 8;
316 static private final int MAX_RECYCLED = 10;
317 static private Object gRecyclerLock = new Object();
318 static private int gRecyclerUsed = 0;
319 static private MotionEvent gRecyclerTop = null;
321 private long mDownTimeNano;
323 private float mXOffset;
324 private float mYOffset;
325 private float mXPrecision;
326 private float mYPrecision;
327 private int mEdgeFlags;
328 private int mMetaState;
331 private int mNumPointers;
332 private int mNumSamples;
334 private int mLastDataSampleIndex;
335 private int mLastEventTimeNanoSampleIndex;
337 // Array of mNumPointers size of identifiers for each pointer of data.
338 private int[] mPointerIdentifiers;
340 // Array of (mNumSamples * mNumPointers * NUM_SAMPLE_DATA) size of event data.
341 // Samples are ordered from oldest to newest.
342 private float[] mDataSamples;
344 // Array of mNumSamples size of event time stamps in nanoseconds.
345 // Samples are ordered from oldest to newest.
346 private long[] mEventTimeNanoSamples;
348 private MotionEvent mNext;
349 private RuntimeException mRecycledLocation;
350 private boolean mRecycled;
352 private MotionEvent(int pointerCount, int sampleCount) {
353 mPointerIdentifiers = new int[pointerCount];
354 mDataSamples = new float[pointerCount * sampleCount * NUM_SAMPLE_DATA];
355 mEventTimeNanoSamples = new long[sampleCount];
358 static private MotionEvent obtain(int pointerCount, int sampleCount) {
359 final MotionEvent ev;
360 synchronized (gRecyclerLock) {
361 if (gRecyclerTop == null) {
362 if (pointerCount < BASE_AVAIL_POINTERS) {
363 pointerCount = BASE_AVAIL_POINTERS;
365 if (sampleCount < BASE_AVAIL_SAMPLES) {
366 sampleCount = BASE_AVAIL_SAMPLES;
368 return new MotionEvent(pointerCount, sampleCount);
371 gRecyclerTop = ev.mNext;
374 ev.mRecycledLocation = null;
375 ev.mRecycled = false;
378 if (ev.mPointerIdentifiers.length < pointerCount) {
379 ev.mPointerIdentifiers = new int[pointerCount];
382 if (ev.mEventTimeNanoSamples.length < sampleCount) {
383 ev.mEventTimeNanoSamples = new long[sampleCount];
386 final int neededDataSamplesLength = pointerCount * sampleCount * NUM_SAMPLE_DATA;
387 if (ev.mDataSamples.length < neededDataSamplesLength) {
388 ev.mDataSamples = new float[neededDataSamplesLength];
395 * Create a new MotionEvent, filling in all of the basic values that
398 * @param downTime The time (in ms) when the user originally pressed down to start
399 * a stream of position events. This must be obtained from {@link SystemClock#uptimeMillis()}.
400 * @param eventTime The the time (in ms) when this specific event was generated. This
401 * must be obtained from {@link SystemClock#uptimeMillis()}.
402 * @param action The kind of action being performed -- one of either
403 * {@link #ACTION_DOWN}, {@link #ACTION_MOVE}, {@link #ACTION_UP}, or
404 * {@link #ACTION_CANCEL}.
405 * @param pointers The number of points that will be in this event.
406 * @param pointerIds An array of <em>pointers</em> values providing
407 * an identifier for each pointer.
408 * @param pointerCoords An array of <em>pointers</em> values providing
409 * a {@link PointerCoords} coordinate object for each pointer.
410 * @param metaState The state of any meta / modifier keys that were in effect when
411 * the event was generated.
412 * @param xPrecision The precision of the X coordinate being reported.
413 * @param yPrecision The precision of the Y coordinate being reported.
414 * @param deviceId The id for the device that this event came from. An id of
415 * zero indicates that the event didn't come from a physical device; other
416 * numbers are arbitrary and you shouldn't depend on the values.
417 * @param edgeFlags A bitfield indicating which edges, if any, were touched by this
419 * @param source The source of this event.
420 * @param flags The motion event flags.
422 static public MotionEvent obtain(long downTime, long eventTime,
423 int action, int pointers, int[] pointerIds, PointerCoords[] pointerCoords,
424 int metaState, float xPrecision, float yPrecision, int deviceId,
425 int edgeFlags, int source, int flags) {
426 MotionEvent ev = obtain(pointers, 1);
427 ev.mDeviceId = deviceId;
429 ev.mEdgeFlags = edgeFlags;
430 ev.mDownTimeNano = downTime * MS_PER_NS;
433 ev.mMetaState = metaState;
436 ev.mXPrecision = xPrecision;
437 ev.mYPrecision = yPrecision;
439 ev.mNumPointers = pointers;
442 ev.mLastDataSampleIndex = 0;
443 ev.mLastEventTimeNanoSampleIndex = 0;
445 System.arraycopy(pointerIds, 0, ev.mPointerIdentifiers, 0, pointers);
447 ev.mEventTimeNanoSamples[0] = eventTime * MS_PER_NS;
449 ev.setPointerCoordsAtSampleIndex(0, pointerCoords);
455 * Create a new MotionEvent, filling in all of the basic values that
458 * @param downTime The time (in ms) when the user originally pressed down to start
459 * a stream of position events. This must be obtained from {@link SystemClock#uptimeMillis()}.
460 * @param eventTime The the time (in ms) when this specific event was generated. This
461 * must be obtained from {@link SystemClock#uptimeMillis()}.
462 * @param action The kind of action being performed -- one of either
463 * {@link #ACTION_DOWN}, {@link #ACTION_MOVE}, {@link #ACTION_UP}, or
464 * {@link #ACTION_CANCEL}.
465 * @param x The X coordinate of this event.
466 * @param y The Y coordinate of this event.
467 * @param pressure The current pressure of this event. The pressure generally
468 * ranges from 0 (no pressure at all) to 1 (normal pressure), however
469 * values higher than 1 may be generated depending on the calibration of
471 * @param size A scaled value of the approximate size of the area being pressed when
472 * touched with the finger. The actual value in pixels corresponding to the finger
473 * touch is normalized with a device specific range of values
474 * and scaled to a value between 0 and 1.
475 * @param metaState The state of any meta / modifier keys that were in effect when
476 * the event was generated.
477 * @param xPrecision The precision of the X coordinate being reported.
478 * @param yPrecision The precision of the Y coordinate being reported.
479 * @param deviceId The id for the device that this event came from. An id of
480 * zero indicates that the event didn't come from a physical device; other
481 * numbers are arbitrary and you shouldn't depend on the values.
482 * @param edgeFlags A bitfield indicating which edges, if any, were touched by this
485 static public MotionEvent obtain(long downTime, long eventTime, int action,
486 float x, float y, float pressure, float size, int metaState,
487 float xPrecision, float yPrecision, int deviceId, int edgeFlags) {
488 MotionEvent ev = obtain(1, 1);
489 ev.mDeviceId = deviceId;
490 ev.mSource = InputDevice.SOURCE_UNKNOWN;
491 ev.mEdgeFlags = edgeFlags;
492 ev.mDownTimeNano = downTime * MS_PER_NS;
495 ev.mMetaState = metaState;
498 ev.mXPrecision = xPrecision;
499 ev.mYPrecision = yPrecision;
504 ev.mLastDataSampleIndex = 0;
505 ev.mLastEventTimeNanoSampleIndex = 0;
507 ev.mPointerIdentifiers[0] = 0;
509 ev.mEventTimeNanoSamples[0] = eventTime * MS_PER_NS;
511 ev.setPointerCoordsAtSampleIndex(0, x, y, pressure, size);
516 * Create a new MotionEvent, filling in all of the basic values that
519 * @param downTime The time (in ms) when the user originally pressed down to start
520 * a stream of position events. This must be obtained from {@link SystemClock#uptimeMillis()}.
521 * @param eventTime The the time (in ms) when this specific event was generated. This
522 * must be obtained from {@link SystemClock#uptimeMillis()}.
523 * @param action The kind of action being performed -- one of either
524 * {@link #ACTION_DOWN}, {@link #ACTION_MOVE}, {@link #ACTION_UP}, or
525 * {@link #ACTION_CANCEL}.
526 * @param pointers The number of pointers that are active in this event.
527 * @param x The X coordinate of this event.
528 * @param y The Y coordinate of this event.
529 * @param pressure The current pressure of this event. The pressure generally
530 * ranges from 0 (no pressure at all) to 1 (normal pressure), however
531 * values higher than 1 may be generated depending on the calibration of
533 * @param size A scaled value of the approximate size of the area being pressed when
534 * touched with the finger. The actual value in pixels corresponding to the finger
535 * touch is normalized with a device specific range of values
536 * and scaled to a value between 0 and 1.
537 * @param metaState The state of any meta / modifier keys that were in effect when
538 * the event was generated.
539 * @param xPrecision The precision of the X coordinate being reported.
540 * @param yPrecision The precision of the Y coordinate being reported.
541 * @param deviceId The id for the device that this event came from. An id of
542 * zero indicates that the event didn't come from a physical device; other
543 * numbers are arbitrary and you shouldn't depend on the values.
544 * @param edgeFlags A bitfield indicating which edges, if any, were touched by this
547 * @deprecated Use {@link #obtain(long, long, int, float, float, float, float, int, float, float, int, int)}
551 static public MotionEvent obtain(long downTime, long eventTime, int action,
552 int pointers, float x, float y, float pressure, float size, int metaState,
553 float xPrecision, float yPrecision, int deviceId, int edgeFlags) {
554 return obtain(downTime, eventTime, action, x, y, pressure, size,
555 metaState, xPrecision, yPrecision, deviceId, edgeFlags);
559 * Create a new MotionEvent, filling in a subset of the basic motion
560 * values. Those not specified here are: device id (always 0), pressure
561 * and size (always 1), x and y precision (always 1), and edgeFlags (always 0).
563 * @param downTime The time (in ms) when the user originally pressed down to start
564 * a stream of position events. This must be obtained from {@link SystemClock#uptimeMillis()}.
565 * @param eventTime The the time (in ms) when this specific event was generated. This
566 * must be obtained from {@link SystemClock#uptimeMillis()}.
567 * @param action The kind of action being performed -- one of either
568 * {@link #ACTION_DOWN}, {@link #ACTION_MOVE}, {@link #ACTION_UP}, or
569 * {@link #ACTION_CANCEL}.
570 * @param x The X coordinate of this event.
571 * @param y The Y coordinate of this event.
572 * @param metaState The state of any meta / modifier keys that were in effect when
573 * the event was generated.
575 static public MotionEvent obtain(long downTime, long eventTime, int action,
576 float x, float y, int metaState) {
577 return obtain(downTime, eventTime, action, x, y, 1.0f, 1.0f,
578 metaState, 1.0f, 1.0f, 0, 0);
582 * Create a new MotionEvent, copying from an existing one.
584 static public MotionEvent obtain(MotionEvent o) {
585 MotionEvent ev = obtain(o.mNumPointers, o.mNumSamples);
586 ev.mDeviceId = o.mDeviceId;
587 ev.mSource = o.mSource;
588 ev.mEdgeFlags = o.mEdgeFlags;
589 ev.mDownTimeNano = o.mDownTimeNano;
590 ev.mAction = o.mAction;
591 ev.mFlags = o.mFlags;
592 ev.mMetaState = o.mMetaState;
593 ev.mXOffset = o.mXOffset;
594 ev.mYOffset = o.mYOffset;
595 ev.mXPrecision = o.mXPrecision;
596 ev.mYPrecision = o.mYPrecision;
597 int numPointers = ev.mNumPointers = o.mNumPointers;
598 int numSamples = ev.mNumSamples = o.mNumSamples;
600 ev.mLastDataSampleIndex = o.mLastDataSampleIndex;
601 ev.mLastEventTimeNanoSampleIndex = o.mLastEventTimeNanoSampleIndex;
603 System.arraycopy(o.mPointerIdentifiers, 0, ev.mPointerIdentifiers, 0, numPointers);
605 System.arraycopy(o.mEventTimeNanoSamples, 0, ev.mEventTimeNanoSamples, 0, numSamples);
607 System.arraycopy(o.mDataSamples, 0, ev.mDataSamples, 0,
608 numPointers * numSamples * NUM_SAMPLE_DATA);
613 * Create a new MotionEvent, copying from an existing one, but not including
614 * any historical point information.
616 static public MotionEvent obtainNoHistory(MotionEvent o) {
617 MotionEvent ev = obtain(o.mNumPointers, 1);
618 ev.mDeviceId = o.mDeviceId;
619 ev.mSource = o.mSource;
620 ev.mEdgeFlags = o.mEdgeFlags;
621 ev.mDownTimeNano = o.mDownTimeNano;
622 ev.mAction = o.mAction;
624 ev.mMetaState = o.mMetaState;
625 ev.mXOffset = o.mXOffset;
626 ev.mYOffset = o.mYOffset;
627 ev.mXPrecision = o.mXPrecision;
628 ev.mYPrecision = o.mYPrecision;
630 int numPointers = ev.mNumPointers = o.mNumPointers;
633 ev.mLastDataSampleIndex = 0;
634 ev.mLastEventTimeNanoSampleIndex = 0;
636 System.arraycopy(o.mPointerIdentifiers, 0, ev.mPointerIdentifiers, 0, numPointers);
638 ev.mEventTimeNanoSamples[0] = o.mEventTimeNanoSamples[o.mLastEventTimeNanoSampleIndex];
640 System.arraycopy(o.mDataSamples, o.mLastDataSampleIndex, ev.mDataSamples, 0,
641 numPointers * NUM_SAMPLE_DATA);
646 * Recycle the MotionEvent, to be re-used by a later caller. After calling
647 * this function you must not ever touch the event again.
649 public final void recycle() {
650 // Ensure recycle is only called once!
651 if (TRACK_RECYCLED_LOCATION) {
652 if (mRecycledLocation != null) {
653 throw new RuntimeException(toString() + " recycled twice!", mRecycledLocation);
655 mRecycledLocation = new RuntimeException("Last recycled here");
656 //Log.w("MotionEvent", "Recycling event " + this, mRecycledLocation);
659 throw new RuntimeException(toString() + " recycled twice!");
664 synchronized (gRecyclerLock) {
665 if (gRecyclerUsed < MAX_RECYCLED) {
668 mNext = gRecyclerTop;
675 * Scales down the coordination of this event by the given scale.
679 public final void scale(float scale) {
682 mXPrecision *= scale;
683 mYPrecision *= scale;
685 float[] history = mDataSamples;
686 final int length = mNumPointers * mNumSamples * NUM_SAMPLE_DATA;
687 for (int i = 0; i < length; i += NUM_SAMPLE_DATA) {
688 history[i + SAMPLE_X] *= scale;
689 history[i + SAMPLE_Y] *= scale;
690 // no need to scale pressure
691 history[i + SAMPLE_SIZE] *= scale; // TODO: square this?
692 history[i + SAMPLE_TOUCH_MAJOR] *= scale;
693 history[i + SAMPLE_TOUCH_MINOR] *= scale;
694 history[i + SAMPLE_TOOL_MAJOR] *= scale;
695 history[i + SAMPLE_TOOL_MINOR] *= scale;
700 * Return the kind of action being performed -- one of either
701 * {@link #ACTION_DOWN}, {@link #ACTION_MOVE}, {@link #ACTION_UP}, or
702 * {@link #ACTION_CANCEL}. Consider using {@link #getActionMasked}
703 * and {@link #getActionIndex} to retrieve the separate masked action
706 public final int getAction() {
711 * Return the masked action being performed, without pointer index
712 * information. May be any of the actions: {@link #ACTION_DOWN},
713 * {@link #ACTION_MOVE}, {@link #ACTION_UP}, {@link #ACTION_CANCEL},
714 * {@link #ACTION_POINTER_DOWN}, or {@link #ACTION_POINTER_UP}.
715 * Use {@link #getActionIndex} to return the index associated with
718 public final int getActionMasked() {
719 return mAction & ACTION_MASK;
723 * For {@link #ACTION_POINTER_DOWN} or {@link #ACTION_POINTER_UP}
724 * as returned by {@link #getActionMasked}, this returns the associated
725 * pointer index. The index may be used with {@link #getPointerId(int)},
726 * {@link #getX(int)}, {@link #getY(int)}, {@link #getPressure(int)},
727 * and {@link #getSize(int)} to get information about the pointer that has
730 public final int getActionIndex() {
731 return (mAction & ACTION_POINTER_INDEX_MASK) >> ACTION_POINTER_INDEX_SHIFT;
735 * Gets the motion event flags.
737 * @see #FLAG_WINDOW_IS_OBSCURED
739 public final int getFlags() {
744 * Returns the time (in ms) when the user originally pressed down to start
745 * a stream of position events.
747 public final long getDownTime() {
748 return mDownTimeNano / MS_PER_NS;
752 * Returns the time (in ms) when this specific event was generated.
754 public final long getEventTime() {
755 return mEventTimeNanoSamples[mLastEventTimeNanoSampleIndex] / MS_PER_NS;
759 * Returns the time (in ns) when this specific event was generated.
760 * The value is in nanosecond precision but it may not have nanosecond accuracy.
764 public final long getEventTimeNano() {
765 return mEventTimeNanoSamples[mLastEventTimeNanoSampleIndex];
769 * {@link #getX(int)} for the first pointer index (may be an
770 * arbitrary pointer identifier).
772 public final float getX() {
773 return mDataSamples[mLastDataSampleIndex + SAMPLE_X] + mXOffset;
777 * {@link #getY(int)} for the first pointer index (may be an
778 * arbitrary pointer identifier).
780 public final float getY() {
781 return mDataSamples[mLastDataSampleIndex + SAMPLE_Y] + mYOffset;
785 * {@link #getPressure(int)} for the first pointer index (may be an
786 * arbitrary pointer identifier).
788 public final float getPressure() {
789 return mDataSamples[mLastDataSampleIndex + SAMPLE_PRESSURE];
793 * {@link #getSize(int)} for the first pointer index (may be an
794 * arbitrary pointer identifier).
796 public final float getSize() {
797 return mDataSamples[mLastDataSampleIndex + SAMPLE_SIZE];
801 * {@link #getTouchMajor(int)} for the first pointer index (may be an
802 * arbitrary pointer identifier).
804 public final float getTouchMajor() {
805 return mDataSamples[mLastDataSampleIndex + SAMPLE_TOUCH_MAJOR];
809 * {@link #getTouchMinor(int)} for the first pointer index (may be an
810 * arbitrary pointer identifier).
812 public final float getTouchMinor() {
813 return mDataSamples[mLastDataSampleIndex + SAMPLE_TOUCH_MINOR];
817 * {@link #getToolMajor(int)} for the first pointer index (may be an
818 * arbitrary pointer identifier).
820 public final float getToolMajor() {
821 return mDataSamples[mLastDataSampleIndex + SAMPLE_TOOL_MAJOR];
825 * {@link #getToolMinor(int)} for the first pointer index (may be an
826 * arbitrary pointer identifier).
828 public final float getToolMinor() {
829 return mDataSamples[mLastDataSampleIndex + SAMPLE_TOOL_MINOR];
833 * {@link #getOrientation(int)} for the first pointer index (may be an
834 * arbitrary pointer identifier).
836 public final float getOrientation() {
837 return mDataSamples[mLastDataSampleIndex + SAMPLE_ORIENTATION];
841 * The number of pointers of data contained in this event. Always
844 public final int getPointerCount() {
849 * Return the pointer identifier associated with a particular pointer
850 * data index is this event. The identifier tells you the actual pointer
851 * number associated with the data, accounting for individual pointers
852 * going up and down since the start of the current gesture.
853 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0
854 * (the first pointer that is down) to {@link #getPointerCount()}-1.
856 public final int getPointerId(int pointerIndex) {
857 return mPointerIdentifiers[pointerIndex];
861 * Given a pointer identifier, find the index of its data in the event.
863 * @param pointerId The identifier of the pointer to be found.
864 * @return Returns either the index of the pointer (for use with
865 * {@link #getX(int)} et al.), or -1 if there is no data available for
866 * that pointer identifier.
868 public final int findPointerIndex(int pointerId) {
869 int i = mNumPointers;
872 if (mPointerIdentifiers[i] == pointerId) {
880 * Returns the X coordinate of this event for the given pointer
881 * <em>index</em> (use {@link #getPointerId(int)} to find the pointer
882 * identifier for this index).
883 * Whole numbers are pixels; the
884 * value may have a fraction for input devices that are sub-pixel precise.
885 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0
886 * (the first pointer that is down) to {@link #getPointerCount()}-1.
888 public final float getX(int pointerIndex) {
889 return mDataSamples[mLastDataSampleIndex
890 + pointerIndex * NUM_SAMPLE_DATA + SAMPLE_X] + mXOffset;
894 * Returns the Y coordinate of this event for the given pointer
895 * <em>index</em> (use {@link #getPointerId(int)} to find the pointer
896 * identifier for this index).
897 * Whole numbers are pixels; the
898 * value may have a fraction for input devices that are sub-pixel precise.
899 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0
900 * (the first pointer that is down) to {@link #getPointerCount()}-1.
902 public final float getY(int pointerIndex) {
903 return mDataSamples[mLastDataSampleIndex
904 + pointerIndex * NUM_SAMPLE_DATA + SAMPLE_Y] + mYOffset;
908 * Returns the current pressure of this event for the given pointer
909 * <em>index</em> (use {@link #getPointerId(int)} to find the pointer
910 * identifier for this index).
911 * The pressure generally
912 * ranges from 0 (no pressure at all) to 1 (normal pressure), however
913 * values higher than 1 may be generated depending on the calibration of
915 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0
916 * (the first pointer that is down) to {@link #getPointerCount()}-1.
918 public final float getPressure(int pointerIndex) {
919 return mDataSamples[mLastDataSampleIndex
920 + pointerIndex * NUM_SAMPLE_DATA + SAMPLE_PRESSURE];
924 * Returns a scaled value of the approximate size for the given pointer
925 * <em>index</em> (use {@link #getPointerId(int)} to find the pointer
926 * identifier for this index).
927 * This represents some approximation of the area of the screen being
928 * pressed; the actual value in pixels corresponding to the
929 * touch is normalized with the device specific range of values
930 * and scaled to a value between 0 and 1. The value of size can be used to
931 * determine fat touch events.
932 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0
933 * (the first pointer that is down) to {@link #getPointerCount()}-1.
935 public final float getSize(int pointerIndex) {
936 return mDataSamples[mLastDataSampleIndex
937 + pointerIndex * NUM_SAMPLE_DATA + SAMPLE_SIZE];
941 * Returns the length of the major axis of an ellipse that describes the touch
942 * area at the point of contact for the given pointer
943 * <em>index</em> (use {@link #getPointerId(int)} to find the pointer
944 * identifier for this index).
945 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0
946 * (the first pointer that is down) to {@link #getPointerCount()}-1.
948 public final float getTouchMajor(int pointerIndex) {
949 return mDataSamples[mLastDataSampleIndex
950 + pointerIndex * NUM_SAMPLE_DATA + SAMPLE_TOUCH_MAJOR];
954 * Returns the length of the minor axis of an ellipse that describes the touch
955 * area at the point of contact for the given pointer
956 * <em>index</em> (use {@link #getPointerId(int)} to find the pointer
957 * identifier for this index).
958 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0
959 * (the first pointer that is down) to {@link #getPointerCount()}-1.
961 public final float getTouchMinor(int pointerIndex) {
962 return mDataSamples[mLastDataSampleIndex
963 + pointerIndex * NUM_SAMPLE_DATA + SAMPLE_TOUCH_MINOR];
967 * Returns the length of the major axis of an ellipse that describes the size of
968 * the approaching tool for the given pointer
969 * <em>index</em> (use {@link #getPointerId(int)} to find the pointer
970 * identifier for this index).
971 * The tool area represents the estimated size of the finger or pen that is
972 * touching the device independent of its actual touch area at the point of contact.
973 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0
974 * (the first pointer that is down) to {@link #getPointerCount()}-1.
976 public final float getToolMajor(int pointerIndex) {
977 return mDataSamples[mLastDataSampleIndex
978 + pointerIndex * NUM_SAMPLE_DATA + SAMPLE_TOOL_MAJOR];
982 * Returns the length of the minor axis of an ellipse that describes the size of
983 * the approaching tool for the given pointer
984 * <em>index</em> (use {@link #getPointerId(int)} to find the pointer
985 * identifier for this index).
986 * The tool area represents the estimated size of the finger or pen that is
987 * touching the device independent of its actual touch area at the point of contact.
988 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0
989 * (the first pointer that is down) to {@link #getPointerCount()}-1.
991 public final float getToolMinor(int pointerIndex) {
992 return mDataSamples[mLastDataSampleIndex
993 + pointerIndex * NUM_SAMPLE_DATA + SAMPLE_TOOL_MINOR];
997 * Returns the orientation of the touch area and tool area in radians clockwise from vertical
998 * for the given pointer <em>index</em> (use {@link #getPointerId(int)} to find the pointer
999 * identifier for this index).
1000 * An angle of 0 degrees indicates that the major axis of contact is oriented
1001 * upwards, is perfectly circular or is of unknown orientation. A positive angle
1002 * indicates that the major axis of contact is oriented to the right. A negative angle
1003 * indicates that the major axis of contact is oriented to the left.
1004 * The full range is from -PI/2 radians (finger pointing fully left) to PI/2 radians
1005 * (finger pointing fully right).
1006 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0
1007 * (the first pointer that is down) to {@link #getPointerCount()}-1.
1009 public final float getOrientation(int pointerIndex) {
1010 return mDataSamples[mLastDataSampleIndex
1011 + pointerIndex * NUM_SAMPLE_DATA + SAMPLE_ORIENTATION];
1015 * Populates a {@link PointerCoords} object with pointer coordinate data for
1016 * the specified pointer index.
1018 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0
1019 * (the first pointer that is down) to {@link #getPointerCount()}-1.
1020 * @param outPointerCoords The pointer coordinate object to populate.
1022 public final void getPointerCoords(int pointerIndex, PointerCoords outPointerCoords) {
1023 final int sampleIndex = mLastDataSampleIndex + pointerIndex * NUM_SAMPLE_DATA;
1024 getPointerCoordsAtSampleIndex(sampleIndex, outPointerCoords);
1028 * Returns the state of any meta / modifier keys that were in effect when
1029 * the event was generated. This is the same values as those
1030 * returned by {@link KeyEvent#getMetaState() KeyEvent.getMetaState}.
1032 * @return an integer in which each bit set to 1 represents a pressed
1035 * @see KeyEvent#getMetaState()
1037 public final int getMetaState() {
1042 * Returns the original raw X coordinate of this event. For touch
1043 * events on the screen, this is the original location of the event
1044 * on the screen, before it had been adjusted for the containing window
1047 public final float getRawX() {
1048 return mDataSamples[mLastDataSampleIndex + SAMPLE_X];
1052 * Returns the original raw Y coordinate of this event. For touch
1053 * events on the screen, this is the original location of the event
1054 * on the screen, before it had been adjusted for the containing window
1057 public final float getRawY() {
1058 return mDataSamples[mLastDataSampleIndex + SAMPLE_Y];
1062 * Return the precision of the X coordinates being reported. You can
1063 * multiple this number with {@link #getX} to find the actual hardware
1064 * value of the X coordinate.
1065 * @return Returns the precision of X coordinates being reported.
1067 public final float getXPrecision() {
1072 * Return the precision of the Y coordinates being reported. You can
1073 * multiple this number with {@link #getY} to find the actual hardware
1074 * value of the Y coordinate.
1075 * @return Returns the precision of Y coordinates being reported.
1077 public final float getYPrecision() {
1082 * Returns the number of historical points in this event. These are
1083 * movements that have occurred between this event and the previous event.
1084 * This only applies to ACTION_MOVE events -- all other actions will have
1087 * @return Returns the number of historical points in the event.
1089 public final int getHistorySize() {
1090 return mLastEventTimeNanoSampleIndex;
1094 * Returns the time that a historical movement occurred between this event
1095 * and the previous event. Only applies to ACTION_MOVE events.
1097 * @param pos Which historical value to return; must be less than
1098 * {@link #getHistorySize}
1100 * @see #getHistorySize
1101 * @see #getEventTime
1103 public final long getHistoricalEventTime(int pos) {
1104 return mEventTimeNanoSamples[pos] / MS_PER_NS;
1108 * {@link #getHistoricalX(int)} for the first pointer index (may be an
1109 * arbitrary pointer identifier).
1111 public final float getHistoricalX(int pos) {
1112 return mDataSamples[pos * mNumPointers * NUM_SAMPLE_DATA + SAMPLE_X] + mXOffset;
1116 * {@link #getHistoricalY(int)} for the first pointer index (may be an
1117 * arbitrary pointer identifier).
1119 public final float getHistoricalY(int pos) {
1120 return mDataSamples[pos * mNumPointers * NUM_SAMPLE_DATA + SAMPLE_Y] + mYOffset;
1124 * {@link #getHistoricalPressure(int)} for the first pointer index (may be an
1125 * arbitrary pointer identifier).
1127 public final float getHistoricalPressure(int pos) {
1128 return mDataSamples[pos * mNumPointers * NUM_SAMPLE_DATA + SAMPLE_PRESSURE];
1132 * {@link #getHistoricalSize(int)} for the first pointer index (may be an
1133 * arbitrary pointer identifier).
1135 public final float getHistoricalSize(int pos) {
1136 return mDataSamples[pos * mNumPointers * NUM_SAMPLE_DATA + SAMPLE_SIZE];
1140 * {@link #getHistoricalTouchMajor(int)} for the first pointer index (may be an
1141 * arbitrary pointer identifier).
1143 public final float getHistoricalTouchMajor(int pos) {
1144 return mDataSamples[pos * mNumPointers * NUM_SAMPLE_DATA + SAMPLE_TOUCH_MAJOR];
1148 * {@link #getHistoricalTouchMinor(int)} for the first pointer index (may be an
1149 * arbitrary pointer identifier).
1151 public final float getHistoricalTouchMinor(int pos) {
1152 return mDataSamples[pos * mNumPointers * NUM_SAMPLE_DATA + SAMPLE_TOUCH_MINOR];
1156 * {@link #getHistoricalToolMajor(int)} for the first pointer index (may be an
1157 * arbitrary pointer identifier).
1159 public final float getHistoricalToolMajor(int pos) {
1160 return mDataSamples[pos * mNumPointers * NUM_SAMPLE_DATA + SAMPLE_TOOL_MAJOR];
1164 * {@link #getHistoricalToolMinor(int)} for the first pointer index (may be an
1165 * arbitrary pointer identifier).
1167 public final float getHistoricalToolMinor(int pos) {
1168 return mDataSamples[pos * mNumPointers * NUM_SAMPLE_DATA + SAMPLE_TOOL_MINOR];
1172 * {@link #getHistoricalOrientation(int)} for the first pointer index (may be an
1173 * arbitrary pointer identifier).
1175 public final float getHistoricalOrientation(int pos) {
1176 return mDataSamples[pos * mNumPointers * NUM_SAMPLE_DATA + SAMPLE_ORIENTATION];
1180 * Returns a historical X coordinate, as per {@link #getX(int)}, that
1181 * occurred between this event and the previous event for the given pointer.
1182 * Only applies to ACTION_MOVE events.
1184 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0
1185 * (the first pointer that is down) to {@link #getPointerCount()}-1.
1186 * @param pos Which historical value to return; must be less than
1187 * {@link #getHistorySize}
1189 * @see #getHistorySize
1192 public final float getHistoricalX(int pointerIndex, int pos) {
1193 return mDataSamples[(pos * mNumPointers + pointerIndex)
1194 * NUM_SAMPLE_DATA + SAMPLE_X] + mXOffset;
1198 * Returns a historical Y coordinate, as per {@link #getY(int)}, that
1199 * occurred between this event and the previous event for the given pointer.
1200 * Only applies to ACTION_MOVE events.
1202 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0
1203 * (the first pointer that is down) to {@link #getPointerCount()}-1.
1204 * @param pos Which historical value to return; must be less than
1205 * {@link #getHistorySize}
1207 * @see #getHistorySize
1210 public final float getHistoricalY(int pointerIndex, int pos) {
1211 return mDataSamples[(pos * mNumPointers + pointerIndex)
1212 * NUM_SAMPLE_DATA + SAMPLE_Y] + mYOffset;
1216 * Returns a historical pressure coordinate, as per {@link #getPressure(int)},
1217 * that occurred between this event and the previous event for the given
1218 * pointer. Only applies to ACTION_MOVE events.
1220 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0
1221 * (the first pointer that is down) to {@link #getPointerCount()}-1.
1222 * @param pos Which historical value to return; must be less than
1223 * {@link #getHistorySize}
1225 * @see #getHistorySize
1228 public final float getHistoricalPressure(int pointerIndex, int pos) {
1229 return mDataSamples[(pos * mNumPointers + pointerIndex)
1230 * NUM_SAMPLE_DATA + SAMPLE_PRESSURE];
1234 * Returns a historical size coordinate, as per {@link #getSize(int)}, that
1235 * occurred between this event and the previous event for the given pointer.
1236 * Only applies to ACTION_MOVE events.
1238 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0
1239 * (the first pointer that is down) to {@link #getPointerCount()}-1.
1240 * @param pos Which historical value to return; must be less than
1241 * {@link #getHistorySize}
1243 * @see #getHistorySize
1246 public final float getHistoricalSize(int pointerIndex, int pos) {
1247 return mDataSamples[(pos * mNumPointers + pointerIndex)
1248 * NUM_SAMPLE_DATA + SAMPLE_SIZE];
1252 * Returns a historical touch major axis coordinate, as per {@link #getTouchMajor(int)}, that
1253 * occurred between this event and the previous event for the given pointer.
1254 * Only applies to ACTION_MOVE events.
1256 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0
1257 * (the first pointer that is down) to {@link #getPointerCount()}-1.
1258 * @param pos Which historical value to return; must be less than
1259 * {@link #getHistorySize}
1261 * @see #getHistorySize
1262 * @see #getTouchMajor
1264 public final float getHistoricalTouchMajor(int pointerIndex, int pos) {
1265 return mDataSamples[(pos * mNumPointers + pointerIndex)
1266 * NUM_SAMPLE_DATA + SAMPLE_TOUCH_MAJOR];
1270 * Returns a historical touch minor axis coordinate, as per {@link #getTouchMinor(int)}, that
1271 * occurred between this event and the previous event for the given pointer.
1272 * Only applies to ACTION_MOVE events.
1274 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0
1275 * (the first pointer that is down) to {@link #getPointerCount()}-1.
1276 * @param pos Which historical value to return; must be less than
1277 * {@link #getHistorySize}
1279 * @see #getHistorySize
1280 * @see #getTouchMinor
1282 public final float getHistoricalTouchMinor(int pointerIndex, int pos) {
1283 return mDataSamples[(pos * mNumPointers + pointerIndex)
1284 * NUM_SAMPLE_DATA + SAMPLE_TOUCH_MINOR];
1288 * Returns a historical tool major axis coordinate, as per {@link #getToolMajor(int)}, that
1289 * occurred between this event and the previous event for the given pointer.
1290 * Only applies to ACTION_MOVE events.
1292 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0
1293 * (the first pointer that is down) to {@link #getPointerCount()}-1.
1294 * @param pos Which historical value to return; must be less than
1295 * {@link #getHistorySize}
1297 * @see #getHistorySize
1298 * @see #getToolMajor
1300 public final float getHistoricalToolMajor(int pointerIndex, int pos) {
1301 return mDataSamples[(pos * mNumPointers + pointerIndex)
1302 * NUM_SAMPLE_DATA + SAMPLE_TOOL_MAJOR];
1306 * Returns a historical tool minor axis coordinate, as per {@link #getToolMinor(int)}, that
1307 * occurred between this event and the previous event for the given pointer.
1308 * Only applies to ACTION_MOVE events.
1310 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0
1311 * (the first pointer that is down) to {@link #getPointerCount()}-1.
1312 * @param pos Which historical value to return; must be less than
1313 * {@link #getHistorySize}
1315 * @see #getHistorySize
1316 * @see #getToolMinor
1318 public final float getHistoricalToolMinor(int pointerIndex, int pos) {
1319 return mDataSamples[(pos * mNumPointers + pointerIndex)
1320 * NUM_SAMPLE_DATA + SAMPLE_TOOL_MINOR];
1324 * Returns a historical orientation coordinate, as per {@link #getOrientation(int)}, that
1325 * occurred between this event and the previous event for the given pointer.
1326 * Only applies to ACTION_MOVE events.
1328 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0
1329 * (the first pointer that is down) to {@link #getPointerCount()}-1.
1330 * @param pos Which historical value to return; must be less than
1331 * {@link #getHistorySize}
1333 * @see #getHistorySize
1334 * @see #getOrientation
1336 public final float getHistoricalOrientation(int pointerIndex, int pos) {
1337 return mDataSamples[(pos * mNumPointers + pointerIndex)
1338 * NUM_SAMPLE_DATA + SAMPLE_ORIENTATION];
1342 * Populates a {@link PointerCoords} object with historical pointer coordinate data,
1343 * as per {@link #getPointerCoords}, that occurred between this event and the previous
1344 * event for the given pointer.
1345 * Only applies to ACTION_MOVE events.
1347 * @param pointerIndex Raw index of pointer to retrieve. Value may be from 0
1348 * (the first pointer that is down) to {@link #getPointerCount()}-1.
1349 * @param pos Which historical value to return; must be less than
1350 * {@link #getHistorySize}
1351 * @param outPointerCoords The pointer coordinate object to populate.
1353 * @see #getHistorySize
1354 * @see #getPointerCoords
1356 public final void getHistoricalPointerCoords(int pointerIndex, int pos,
1357 PointerCoords outPointerCoords) {
1358 final int sampleIndex = (pos * mNumPointers + pointerIndex) * NUM_SAMPLE_DATA;
1359 getPointerCoordsAtSampleIndex(sampleIndex, outPointerCoords);
1363 * Returns a bitfield indicating which edges, if any, were touched by this
1364 * MotionEvent. For touch events, clients can use this to determine if the
1365 * user's finger was touching the edge of the display.
1372 public final int getEdgeFlags() {
1378 * Sets the bitfield indicating which edges, if any, were touched by this
1381 * @see #getEdgeFlags()
1383 public final void setEdgeFlags(int flags) {
1388 * Sets this event's action.
1390 public final void setAction(int action) {
1395 * Adjust this event's location.
1396 * @param deltaX Amount to add to the current X coordinate of the event.
1397 * @param deltaY Amount to add to the current Y coordinate of the event.
1399 public final void offsetLocation(float deltaX, float deltaY) {
1405 * Set this event's location. Applies {@link #offsetLocation} with a
1406 * delta from the current location to the given new location.
1408 * @param x New absolute X location.
1409 * @param y New absolute Y location.
1411 public final void setLocation(float x, float y) {
1412 final float[] dataSamples = mDataSamples;
1413 final int lastDataSampleIndex = mLastDataSampleIndex;
1414 mXOffset = x - dataSamples[lastDataSampleIndex + SAMPLE_X];
1415 mYOffset = y - dataSamples[lastDataSampleIndex + SAMPLE_Y];
1418 private final void getPointerCoordsAtSampleIndex(int sampleIndex,
1419 PointerCoords outPointerCoords) {
1420 final float[] dataSamples = mDataSamples;
1421 outPointerCoords.x = dataSamples[sampleIndex + SAMPLE_X] + mXOffset;
1422 outPointerCoords.y = dataSamples[sampleIndex + SAMPLE_Y] + mYOffset;
1423 outPointerCoords.pressure = dataSamples[sampleIndex + SAMPLE_PRESSURE];
1424 outPointerCoords.size = dataSamples[sampleIndex + SAMPLE_SIZE];
1425 outPointerCoords.touchMajor = dataSamples[sampleIndex + SAMPLE_TOUCH_MAJOR];
1426 outPointerCoords.touchMinor = dataSamples[sampleIndex + SAMPLE_TOUCH_MINOR];
1427 outPointerCoords.toolMajor = dataSamples[sampleIndex + SAMPLE_TOOL_MAJOR];
1428 outPointerCoords.toolMinor = dataSamples[sampleIndex + SAMPLE_TOOL_MINOR];
1429 outPointerCoords.orientation = dataSamples[sampleIndex + SAMPLE_ORIENTATION];
1432 private final void setPointerCoordsAtSampleIndex(int sampleIndex,
1433 PointerCoords[] pointerCoords) {
1434 final int numPointers = mNumPointers;
1435 for (int i = 0; i < numPointers; i++) {
1436 setPointerCoordsAtSampleIndex(sampleIndex, pointerCoords[i]);
1437 sampleIndex += NUM_SAMPLE_DATA;
1441 private final void setPointerCoordsAtSampleIndex(int sampleIndex,
1442 PointerCoords pointerCoords) {
1443 final float[] dataSamples = mDataSamples;
1444 dataSamples[sampleIndex + SAMPLE_X] = pointerCoords.x - mXOffset;
1445 dataSamples[sampleIndex + SAMPLE_Y] = pointerCoords.y - mYOffset;
1446 dataSamples[sampleIndex + SAMPLE_PRESSURE] = pointerCoords.pressure;
1447 dataSamples[sampleIndex + SAMPLE_SIZE] = pointerCoords.size;
1448 dataSamples[sampleIndex + SAMPLE_TOUCH_MAJOR] = pointerCoords.touchMajor;
1449 dataSamples[sampleIndex + SAMPLE_TOUCH_MINOR] = pointerCoords.touchMinor;
1450 dataSamples[sampleIndex + SAMPLE_TOOL_MAJOR] = pointerCoords.toolMajor;
1451 dataSamples[sampleIndex + SAMPLE_TOOL_MINOR] = pointerCoords.toolMinor;
1452 dataSamples[sampleIndex + SAMPLE_ORIENTATION] = pointerCoords.orientation;
1455 private final void setPointerCoordsAtSampleIndex(int sampleIndex,
1456 float x, float y, float pressure, float size) {
1457 final float[] dataSamples = mDataSamples;
1458 dataSamples[sampleIndex + SAMPLE_X] = x - mXOffset;
1459 dataSamples[sampleIndex + SAMPLE_Y] = y - mYOffset;
1460 dataSamples[sampleIndex + SAMPLE_PRESSURE] = pressure;
1461 dataSamples[sampleIndex + SAMPLE_SIZE] = size;
1462 dataSamples[sampleIndex + SAMPLE_TOUCH_MAJOR] = pressure;
1463 dataSamples[sampleIndex + SAMPLE_TOUCH_MINOR] = pressure;
1464 dataSamples[sampleIndex + SAMPLE_TOOL_MAJOR] = size;
1465 dataSamples[sampleIndex + SAMPLE_TOOL_MINOR] = size;
1466 dataSamples[sampleIndex + SAMPLE_ORIENTATION] = 0;
1469 private final void incrementNumSamplesAndReserveStorage(int dataSampleStride) {
1470 if (mNumSamples == mEventTimeNanoSamples.length) {
1471 long[] newEventTimeNanoSamples = new long[mNumSamples + BASE_AVAIL_SAMPLES];
1472 System.arraycopy(mEventTimeNanoSamples, 0, newEventTimeNanoSamples, 0, mNumSamples);
1473 mEventTimeNanoSamples = newEventTimeNanoSamples;
1476 int nextDataSampleIndex = mLastDataSampleIndex + dataSampleStride;
1477 if (nextDataSampleIndex + dataSampleStride > mDataSamples.length) {
1478 float[] newDataSamples = new float[nextDataSampleIndex
1479 + BASE_AVAIL_SAMPLES * dataSampleStride];
1480 System.arraycopy(mDataSamples, 0, newDataSamples, 0, nextDataSampleIndex);
1481 mDataSamples = newDataSamples;
1484 mLastEventTimeNanoSampleIndex = mNumSamples;
1485 mLastDataSampleIndex = nextDataSampleIndex;
1490 * Add a new movement to the batch of movements in this event. The event's
1491 * current location, position and size is updated to the new values.
1492 * The current values in the event are added to a list of historical values.
1494 * Only applies to {@link #ACTION_MOVE} events.
1496 * @param eventTime The time stamp (in ms) for this data.
1497 * @param x The new X position.
1498 * @param y The new Y position.
1499 * @param pressure The new pressure.
1500 * @param size The new size.
1501 * @param metaState Meta key state.
1503 public final void addBatch(long eventTime, float x, float y,
1504 float pressure, float size, int metaState) {
1505 incrementNumSamplesAndReserveStorage(NUM_SAMPLE_DATA);
1507 mEventTimeNanoSamples[mLastEventTimeNanoSampleIndex] = eventTime * MS_PER_NS;
1508 setPointerCoordsAtSampleIndex(mLastDataSampleIndex, x, y, pressure, size);
1510 mMetaState |= metaState;
1514 * Add a new movement to the batch of movements in this event. The event's
1515 * current location, position and size is updated to the new values.
1516 * The current values in the event are added to a list of historical values.
1518 * Only applies to {@link #ACTION_MOVE} events.
1520 * @param eventTime The time stamp (in ms) for this data.
1521 * @param pointerCoords The new pointer coordinates.
1522 * @param metaState Meta key state.
1524 public final void addBatch(long eventTime, PointerCoords[] pointerCoords, int metaState) {
1525 final int dataSampleStride = mNumPointers * NUM_SAMPLE_DATA;
1526 incrementNumSamplesAndReserveStorage(dataSampleStride);
1528 mEventTimeNanoSamples[mLastEventTimeNanoSampleIndex] = eventTime * MS_PER_NS;
1529 setPointerCoordsAtSampleIndex(mLastDataSampleIndex, pointerCoords);
1531 mMetaState |= metaState;
1535 public String toString() {
1536 return "MotionEvent{" + Integer.toHexString(System.identityHashCode(this))
1537 + " action=" + mAction + " x=" + getX()
1538 + " y=" + getY() + " pressure=" + getPressure() + " size=" + getSize() + "}";
1541 public static final Parcelable.Creator<MotionEvent> CREATOR
1542 = new Parcelable.Creator<MotionEvent>() {
1543 public MotionEvent createFromParcel(Parcel in) {
1544 in.readInt(); // skip token, we already know this is a MotionEvent
1545 return MotionEvent.createFromParcelBody(in);
1548 public MotionEvent[] newArray(int size) {
1549 return new MotionEvent[size];
1554 public static MotionEvent createFromParcelBody(Parcel in) {
1555 final int NP = in.readInt();
1556 final int NS = in.readInt();
1557 final int NI = NP * NS * NUM_SAMPLE_DATA;
1559 MotionEvent ev = obtain(NP, NS);
1560 ev.mNumPointers = NP;
1561 ev.mNumSamples = NS;
1563 ev.readBaseFromParcel(in);
1565 ev.mDownTimeNano = in.readLong();
1566 ev.mAction = in.readInt();
1567 ev.mXOffset = in.readFloat();
1568 ev.mYOffset = in.readFloat();
1569 ev.mXPrecision = in.readFloat();
1570 ev.mYPrecision = in.readFloat();
1571 ev.mEdgeFlags = in.readInt();
1572 ev.mMetaState = in.readInt();
1573 ev.mFlags = in.readInt();
1575 final int[] pointerIdentifiers = ev.mPointerIdentifiers;
1576 for (int i = 0; i < NP; i++) {
1577 pointerIdentifiers[i] = in.readInt();
1580 final long[] eventTimeNanoSamples = ev.mEventTimeNanoSamples;
1581 for (int i = 0; i < NS; i++) {
1582 eventTimeNanoSamples[i] = in.readLong();
1585 final float[] dataSamples = ev.mDataSamples;
1586 for (int i = 0; i < NI; i++) {
1587 dataSamples[i] = in.readFloat();
1590 ev.mLastEventTimeNanoSampleIndex = NS - 1;
1591 ev.mLastDataSampleIndex = (NS - 1) * NP * NUM_SAMPLE_DATA;
1595 public void writeToParcel(Parcel out, int flags) {
1596 out.writeInt(PARCEL_TOKEN_MOTION_EVENT);
1598 final int NP = mNumPointers;
1599 final int NS = mNumSamples;
1600 final int NI = NP * NS * NUM_SAMPLE_DATA;
1605 writeBaseToParcel(out);
1607 out.writeLong(mDownTimeNano);
1608 out.writeInt(mAction);
1609 out.writeFloat(mXOffset);
1610 out.writeFloat(mYOffset);
1611 out.writeFloat(mXPrecision);
1612 out.writeFloat(mYPrecision);
1613 out.writeInt(mEdgeFlags);
1614 out.writeInt(mMetaState);
1615 out.writeInt(mFlags);
1617 final int[] pointerIdentifiers = mPointerIdentifiers;
1618 for (int i = 0; i < NP; i++) {
1619 out.writeInt(pointerIdentifiers[i]);
1622 final long[] eventTimeNanoSamples = mEventTimeNanoSamples;
1623 for (int i = 0; i < NS; i++) {
1624 out.writeLong(eventTimeNanoSamples[i]);
1627 final float[] dataSamples = mDataSamples;
1628 for (int i = 0; i < NI; i++) {
1629 out.writeFloat(dataSamples[i]);
1634 * Transfer object for pointer coordinates.
1636 * Objects of this type can be used to manufacture new {@link MotionEvent} objects
1637 * and to query pointer coordinate information in bulk.
1639 * Refer to {@link InputDevice} for information about how different kinds of
1640 * input devices and sources represent pointer coordinates.
1642 public static final class PointerCoords {
1644 * The X coordinate of the pointer movement.
1645 * The interpretation varies by input source and may represent the position of
1646 * the center of the contact area, a relative displacement in device-specific units
1647 * or something else.
1652 * The Y coordinate of the pointer movement.
1653 * The interpretation varies by input source and may represent the position of
1654 * the center of the contact area, a relative displacement in device-specific units
1655 * or something else.
1660 * A scaled value that describes the pressure applied to the pointer.
1661 * The pressure generally ranges from 0 (no pressure at all) to 1 (normal pressure),
1662 * however values higher than 1 may be generated depending on the calibration of
1665 public float pressure;
1668 * A scaled value of the approximate size of the pointer touch area.
1669 * This represents some approximation of the area of the screen being
1670 * pressed; the actual value in pixels corresponding to the
1671 * touch is normalized with the device specific range of values
1672 * and scaled to a value between 0 and 1. The value of size can be used to
1673 * determine fat touch events.
1678 * The length of the major axis of an ellipse that describes the touch area at
1679 * the point of contact.
1681 public float touchMajor;
1684 * The length of the minor axis of an ellipse that describes the touch area at
1685 * the point of contact.
1687 public float touchMinor;
1690 * The length of the major axis of an ellipse that describes the size of
1691 * the approaching tool.
1692 * The tool area represents the estimated size of the finger or pen that is
1693 * touching the device independent of its actual touch area at the point of contact.
1695 public float toolMajor;
1698 * The length of the minor axis of an ellipse that describes the size of
1699 * the approaching tool.
1700 * The tool area represents the estimated size of the finger or pen that is
1701 * touching the device independent of its actual touch area at the point of contact.
1703 public float toolMinor;
1706 * The orientation of the touch area and tool area in radians clockwise from vertical.
1707 * An angle of 0 degrees indicates that the major axis of contact is oriented
1708 * upwards, is perfectly circular or is of unknown orientation. A positive angle
1709 * indicates that the major axis of contact is oriented to the right. A negative angle
1710 * indicates that the major axis of contact is oriented to the left.
1711 * The full range is from -PI/2 radians (finger pointing fully left) to PI/2 radians
1712 * (finger pointing fully right).
1714 public float orientation;
1717 private static final float PI_4 = (float) (Math.PI / 4);
1719 public float getTouchWidth() {
1720 return Math.abs(orientation) > PI_4 ? touchMajor : touchMinor;
1723 public float getTouchHeight() {
1724 return Math.abs(orientation) > PI_4 ? touchMinor : touchMajor;
1727 public float getToolWidth() {
1728 return Math.abs(orientation) > PI_4 ? toolMajor : toolMinor;
1731 public float getToolHeight() {
1732 return Math.abs(orientation) > PI_4 ? toolMinor : toolMajor;