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 
17 package android.view;
18 
19 import android.annotation.TestApi;
20 import android.graphics.Matrix;
21 import android.os.Parcel;
22 import android.os.Parcelable;
23 import android.os.SystemClock;
24 import android.util.SparseArray;
25 
26 import dalvik.annotation.optimization.CriticalNative;
27 import dalvik.annotation.optimization.FastNative;
28 
29 import java.util.Objects;
30 
31 /**
32  * Object used to report movement (mouse, pen, finger, trackball) events.
33  * Motion events may hold either absolute or relative movements and other data,
34  * depending on the type of device.
35  *
36  * <h3>Overview</h3>
37  * <p>
38  * Motion events describe movements in terms of an action code and a set of axis values.
39  * The action code specifies the state change that occurred such as a pointer going
40  * down or up.  The axis values describe the position and other movement properties.
41  * </p><p>
42  * For example, when the user first touches the screen, the system delivers a touch
43  * event to the appropriate {@link View} with the action code {@link #ACTION_DOWN}
44  * and a set of axis values that include the X and Y coordinates of the touch and
45  * information about the pressure, size and orientation of the contact area.
46  * </p><p>
47  * Some devices can report multiple movement traces at the same time.  Multi-touch
48  * screens emit one movement trace for each finger.  The individual fingers or
49  * other objects that generate movement traces are referred to as <em>pointers</em>.
50  * Motion events contain information about all of the pointers that are currently active
51  * even if some of them have not moved since the last event was delivered.
52  * </p><p>
53  * The number of pointers only ever changes by one as individual pointers go up and down,
54  * except when the gesture is canceled.
55  * </p><p>
56  * Each pointer has a unique id that is assigned when it first goes down
57  * (indicated by {@link #ACTION_DOWN} or {@link #ACTION_POINTER_DOWN}).  A pointer id
58  * remains valid until the pointer eventually goes up (indicated by {@link #ACTION_UP}
59  * or {@link #ACTION_POINTER_UP}) or when the gesture is canceled (indicated by
60  * {@link #ACTION_CANCEL}).
61  * </p><p>
62  * The MotionEvent class provides many methods to query the position and other properties of
63  * pointers, such as {@link #getX(int)}, {@link #getY(int)}, {@link #getAxisValue},
64  * {@link #getPointerId(int)}, {@link #getToolType(int)}, and many others.  Most of these
65  * methods accept the pointer index as a parameter rather than the pointer id.
66  * The pointer index of each pointer in the event ranges from 0 to one less than the value
67  * returned by {@link #getPointerCount()}.
68  * </p><p>
69  * The order in which individual pointers appear within a motion event is undefined.
70  * Thus the pointer index of a pointer can change from one event to the next but
71  * the pointer id of a pointer is guaranteed to remain constant as long as the pointer
72  * remains active.  Use the {@link #getPointerId(int)} method to obtain the
73  * pointer id of a pointer to track it across all subsequent motion events in a gesture.
74  * Then for successive motion events, use the {@link #findPointerIndex(int)} method
75  * to obtain the pointer index for a given pointer id in that motion event.
76  * </p><p>
77  * Mouse and stylus buttons can be retrieved using {@link #getButtonState()}.  It is a
78  * good idea to check the button state while handling {@link #ACTION_DOWN} as part
79  * of a touch event.  The application may choose to perform some different action
80  * if the touch event starts due to a secondary button click, such as presenting a
81  * context menu.
82  * </p>
83  *
84  * <h3>Batching</h3>
85  * <p>
86  * For efficiency, motion events with {@link #ACTION_MOVE} may batch together
87  * multiple movement samples within a single object.  The most current
88  * pointer coordinates are available using {@link #getX(int)} and {@link #getY(int)}.
89  * Earlier coordinates within the batch are accessed using {@link #getHistoricalX(int, int)}
90  * and {@link #getHistoricalY(int, int)}.  The coordinates are "historical" only
91  * insofar as they are older than the current coordinates in the batch; however,
92  * they are still distinct from any other coordinates reported in prior motion events.
93  * To process all coordinates in the batch in time order, first consume the historical
94  * coordinates then consume the current coordinates.
95  * </p><p>
96  * Example: Consuming all samples for all pointers in a motion event in time order.
97  * </p><p><pre><code>
98  * void printSamples(MotionEvent ev) {
99  *     final int historySize = ev.getHistorySize();
100  *     final int pointerCount = ev.getPointerCount();
101  *     for (int h = 0; h &lt; historySize; h++) {
102  *         System.out.printf("At time %d:", ev.getHistoricalEventTime(h));
103  *         for (int p = 0; p &lt; pointerCount; p++) {
104  *             System.out.printf("  pointer %d: (%f,%f)",
105  *                 ev.getPointerId(p), ev.getHistoricalX(p, h), ev.getHistoricalY(p, h));
106  *         }
107  *     }
108  *     System.out.printf("At time %d:", ev.getEventTime());
109  *     for (int p = 0; p &lt; pointerCount; p++) {
110  *         System.out.printf("  pointer %d: (%f,%f)",
111  *             ev.getPointerId(p), ev.getX(p), ev.getY(p));
112  *     }
113  * }
114  * </code></pre></p>
115  *
116  * <h3>Device Types</h3>
117  * <p>
118  * The interpretation of the contents of a MotionEvent varies significantly depending
119  * on the source class of the device.
120  * </p><p>
121  * On pointing devices with source class {@link InputDevice#SOURCE_CLASS_POINTER}
122  * such as touch screens, the pointer coordinates specify absolute
123  * positions such as view X/Y coordinates.  Each complete gesture is represented
124  * by a sequence of motion events with actions that describe pointer state transitions
125  * and movements.  A gesture starts with a motion event with {@link #ACTION_DOWN}
126  * that provides the location of the first pointer down.  As each additional
127  * pointer that goes down or up, the framework will generate a motion event with
128  * {@link #ACTION_POINTER_DOWN} or {@link #ACTION_POINTER_UP} accordingly.
129  * Pointer movements are described by motion events with {@link #ACTION_MOVE}.
130  * Finally, a gesture end either when the final pointer goes up as represented
131  * by a motion event with {@link #ACTION_UP} or when gesture is canceled
132  * with {@link #ACTION_CANCEL}.
133  * </p><p>
134  * Some pointing devices such as mice may support vertical and/or horizontal scrolling.
135  * A scroll event is reported as a generic motion event with {@link #ACTION_SCROLL} that
136  * includes the relative scroll offset in the {@link #AXIS_VSCROLL} and
137  * {@link #AXIS_HSCROLL} axes.  See {@link #getAxisValue(int)} for information
138  * about retrieving these additional axes.
139  * </p><p>
140  * On trackball devices with source class {@link InputDevice#SOURCE_CLASS_TRACKBALL},
141  * the pointer coordinates specify relative movements as X/Y deltas.
142  * A trackball gesture consists of a sequence of movements described by motion
143  * events with {@link #ACTION_MOVE} interspersed with occasional {@link #ACTION_DOWN}
144  * or {@link #ACTION_UP} motion events when the trackball button is pressed or released.
145  * </p><p>
146  * On joystick devices with source class {@link InputDevice#SOURCE_CLASS_JOYSTICK},
147  * the pointer coordinates specify the absolute position of the joystick axes.
148  * The joystick axis values are normalized to a range of -1.0 to 1.0 where 0.0 corresponds
149  * to the center position.  More information about the set of available axes and the
150  * range of motion can be obtained using {@link InputDevice#getMotionRange}.
151  * Some common joystick axes are {@link #AXIS_X}, {@link #AXIS_Y},
152  * {@link #AXIS_HAT_X}, {@link #AXIS_HAT_Y}, {@link #AXIS_Z} and {@link #AXIS_RZ}.
153  * </p><p>
154  * Refer to {@link InputDevice} for more information about how different kinds of
155  * input devices and sources represent pointer coordinates.
156  * </p>
157  *
158  * <h3>Consistency Guarantees</h3>
159  * <p>
160  * Motion events are always delivered to views as a consistent stream of events.
161  * What constitutes a consistent stream varies depending on the type of device.
162  * For touch events, consistency implies that pointers go down one at a time,
163  * move around as a group and then go up one at a time or are canceled.
164  * </p><p>
165  * While the framework tries to deliver consistent streams of motion events to
166  * views, it cannot guarantee it.  Some events may be dropped or modified by
167  * containing views in the application before they are delivered thereby making
168  * the stream of events inconsistent.  Views should always be prepared to
169  * handle {@link #ACTION_CANCEL} and should tolerate anomalous
170  * situations such as receiving a new {@link #ACTION_DOWN} without first having
171  * received an {@link #ACTION_UP} for the prior gesture.
172  * </p>
173  */
174 public final class MotionEvent extends InputEvent implements Parcelable {
175     private static final long NS_PER_MS = 1000000;
176     private static final String LABEL_PREFIX = "AXIS_";
177 
178     private static final boolean DEBUG_CONCISE_TOSTRING = false;
179 
180     /**
181      * An invalid pointer id.
182      *
183      * This value (-1) can be used as a placeholder to indicate that a pointer id
184      * has not been assigned or is not available.  It cannot appear as
185      * a pointer id inside a {@link MotionEvent}.
186      */
187     public static final int INVALID_POINTER_ID = -1;
188 
189     /**
190      * Bit mask of the parts of the action code that are the action itself.
191      */
192     public static final int ACTION_MASK             = 0xff;
193 
194     /**
195      * Constant for {@link #getActionMasked}: A pressed gesture has started, the
196      * motion contains the initial starting location.
197      * <p>
198      * This is also a good time to check the button state to distinguish
199      * secondary and tertiary button clicks and handle them appropriately.
200      * Use {@link #getButtonState} to retrieve the button state.
201      * </p>
202      */
203     public static final int ACTION_DOWN             = 0;
204 
205     /**
206      * Constant for {@link #getActionMasked}: A pressed gesture has finished, the
207      * motion contains the final release location as well as any intermediate
208      * points since the last down or move event.
209      */
210     public static final int ACTION_UP               = 1;
211 
212     /**
213      * Constant for {@link #getActionMasked}: A change has happened during a
214      * press gesture (between {@link #ACTION_DOWN} and {@link #ACTION_UP}).
215      * The motion contains the most recent point, as well as any intermediate
216      * points since the last down or move event.
217      */
218     public static final int ACTION_MOVE             = 2;
219 
220     /**
221      * Constant for {@link #getActionMasked}: The current gesture has been aborted.
222      * You will not receive any more points in it.  You should treat this as
223      * an up event, but not perform any action that you normally would.
224      */
225     public static final int ACTION_CANCEL           = 3;
226 
227     /**
228      * Constant for {@link #getActionMasked}: A movement has happened outside of the
229      * normal bounds of the UI element.  This does not provide a full gesture,
230      * but only the initial location of the movement/touch.
231      * <p>
232      * Note: Because the location of any event will be outside the
233      * bounds of the view hierarchy, it will not get dispatched to
234      * any children of a ViewGroup by default. Therefore,
235      * movements with ACTION_OUTSIDE should be handled in either the
236      * root {@link View} or in the appropriate {@link Window.Callback}
237      * (e.g. {@link android.app.Activity} or {@link android.app.Dialog}).
238      * </p>
239      */
240     public static final int ACTION_OUTSIDE          = 4;
241 
242     /**
243      * Constant for {@link #getActionMasked}: A non-primary pointer has gone down.
244      * <p>
245      * Use {@link #getActionIndex} to retrieve the index of the pointer that changed.
246      * </p><p>
247      * The index is encoded in the {@link #ACTION_POINTER_INDEX_MASK} bits of the
248      * unmasked action returned by {@link #getAction}.
249      * </p>
250      */
251     public static final int ACTION_POINTER_DOWN     = 5;
252 
253     /**
254      * Constant for {@link #getActionMasked}: A non-primary pointer has gone up.
255      * <p>
256      * Use {@link #getActionIndex} to retrieve the index of the pointer that changed.
257      * </p><p>
258      * The index is encoded in the {@link #ACTION_POINTER_INDEX_MASK} bits of the
259      * unmasked action returned by {@link #getAction}.
260      * </p>
261      */
262     public static final int ACTION_POINTER_UP       = 6;
263 
264     /**
265      * Constant for {@link #getActionMasked}: A change happened but the pointer
266      * is not down (unlike {@link #ACTION_MOVE}).  The motion contains the most
267      * recent point, as well as any intermediate points since the last
268      * hover move event.
269      * <p>
270      * This action is always delivered to the window or view under the pointer.
271      * </p><p>
272      * This action is not a touch event so it is delivered to
273      * {@link View#onGenericMotionEvent(MotionEvent)} rather than
274      * {@link View#onTouchEvent(MotionEvent)}.
275      * </p>
276      */
277     public static final int ACTION_HOVER_MOVE       = 7;
278 
279     /**
280      * Constant for {@link #getActionMasked}: The motion event contains relative
281      * vertical and/or horizontal scroll offsets.  Use {@link #getAxisValue(int)}
282      * to retrieve the information from {@link #AXIS_VSCROLL} and {@link #AXIS_HSCROLL}.
283      * The pointer may or may not be down when this event is dispatched.
284      * <p>
285      * This action is always delivered to the window or view under the pointer, which
286      * may not be the window or view currently touched.
287      * </p><p>
288      * This action is not a touch event so it is delivered to
289      * {@link View#onGenericMotionEvent(MotionEvent)} rather than
290      * {@link View#onTouchEvent(MotionEvent)}.
291      * </p>
292      */
293     public static final int ACTION_SCROLL           = 8;
294 
295     /**
296      * Constant for {@link #getActionMasked}: The pointer is not down but has entered the
297      * boundaries of a window or view.
298      * <p>
299      * This action is always delivered to the window or view under the pointer.
300      * </p><p>
301      * This action is not a touch event so it is delivered to
302      * {@link View#onGenericMotionEvent(MotionEvent)} rather than
303      * {@link View#onTouchEvent(MotionEvent)}.
304      * </p>
305      */
306     public static final int ACTION_HOVER_ENTER      = 9;
307 
308     /**
309      * Constant for {@link #getActionMasked}: The pointer is not down but has exited the
310      * boundaries of a window or view.
311      * <p>
312      * This action is always delivered to the window or view that was previously under the pointer.
313      * </p><p>
314      * This action is not a touch event so it is delivered to
315      * {@link View#onGenericMotionEvent(MotionEvent)} rather than
316      * {@link View#onTouchEvent(MotionEvent)}.
317      * </p>
318      */
319     public static final int ACTION_HOVER_EXIT       = 10;
320 
321     /**
322      * Constant for {@link #getActionMasked}: A button has been pressed.
323      *
324      * <p>
325      * Use {@link #getActionButton()} to get which button was pressed.
326      * </p><p>
327      * This action is not a touch event so it is delivered to
328      * {@link View#onGenericMotionEvent(MotionEvent)} rather than
329      * {@link View#onTouchEvent(MotionEvent)}.
330      * </p>
331      */
332     public static final int ACTION_BUTTON_PRESS   = 11;
333 
334     /**
335      * Constant for {@link #getActionMasked}: A button has been released.
336      *
337      * <p>
338      * Use {@link #getActionButton()} to get which button was released.
339      * </p><p>
340      * This action is not a touch event so it is delivered to
341      * {@link View#onGenericMotionEvent(MotionEvent)} rather than
342      * {@link View#onTouchEvent(MotionEvent)}.
343      * </p>
344      */
345     public static final int ACTION_BUTTON_RELEASE  = 12;
346 
347     /**
348      * Bits in the action code that represent a pointer index, used with
349      * {@link #ACTION_POINTER_DOWN} and {@link #ACTION_POINTER_UP}.  Shifting
350      * down by {@link #ACTION_POINTER_INDEX_SHIFT} provides the actual pointer
351      * index where the data for the pointer going up or down can be found; you can
352      * get its identifier with {@link #getPointerId(int)} and the actual
353      * data with {@link #getX(int)} etc.
354      *
355      * @see #getActionIndex
356      */
357     public static final int ACTION_POINTER_INDEX_MASK  = 0xff00;
358 
359     /**
360      * Bit shift for the action bits holding the pointer index as
361      * defined by {@link #ACTION_POINTER_INDEX_MASK}.
362      *
363      * @see #getActionIndex
364      */
365     public static final int ACTION_POINTER_INDEX_SHIFT = 8;
366 
367     /**
368      * @deprecated Use {@link #ACTION_POINTER_INDEX_MASK} to retrieve the
369      * data index associated with {@link #ACTION_POINTER_DOWN}.
370      */
371     @Deprecated
372     public static final int ACTION_POINTER_1_DOWN   = ACTION_POINTER_DOWN | 0x0000;
373 
374     /**
375      * @deprecated Use {@link #ACTION_POINTER_INDEX_MASK} to retrieve the
376      * data index associated with {@link #ACTION_POINTER_DOWN}.
377      */
378     @Deprecated
379     public static final int ACTION_POINTER_2_DOWN   = ACTION_POINTER_DOWN | 0x0100;
380 
381     /**
382      * @deprecated Use {@link #ACTION_POINTER_INDEX_MASK} to retrieve the
383      * data index associated with {@link #ACTION_POINTER_DOWN}.
384      */
385     @Deprecated
386     public static final int ACTION_POINTER_3_DOWN   = ACTION_POINTER_DOWN | 0x0200;
387 
388     /**
389      * @deprecated Use {@link #ACTION_POINTER_INDEX_MASK} to retrieve the
390      * data index associated with {@link #ACTION_POINTER_UP}.
391      */
392     @Deprecated
393     public static final int ACTION_POINTER_1_UP     = ACTION_POINTER_UP | 0x0000;
394 
395     /**
396      * @deprecated Use {@link #ACTION_POINTER_INDEX_MASK} to retrieve the
397      * data index associated with {@link #ACTION_POINTER_UP}.
398      */
399     @Deprecated
400     public static final int ACTION_POINTER_2_UP     = ACTION_POINTER_UP | 0x0100;
401 
402     /**
403      * @deprecated Use {@link #ACTION_POINTER_INDEX_MASK} to retrieve the
404      * data index associated with {@link #ACTION_POINTER_UP}.
405      */
406     @Deprecated
407     public static final int ACTION_POINTER_3_UP     = ACTION_POINTER_UP | 0x0200;
408 
409     /**
410      * @deprecated Renamed to {@link #ACTION_POINTER_INDEX_MASK} to match
411      * the actual data contained in these bits.
412      */
413     @Deprecated
414     public static final int ACTION_POINTER_ID_MASK  = 0xff00;
415 
416     /**
417      * @deprecated Renamed to {@link #ACTION_POINTER_INDEX_SHIFT} to match
418      * the actual data contained in these bits.
419      */
420     @Deprecated
421     public static final int ACTION_POINTER_ID_SHIFT = 8;
422 
423     /**
424      * This flag indicates that the window that received this motion event is partly
425      * or wholly obscured by another visible window above it.  This flag is set to true
426      * even if the event did not directly pass through the obscured area.
427      * A security sensitive application can check this flag to identify situations in which
428      * a malicious application may have covered up part of its content for the purpose
429      * of misleading the user or hijacking touches.  An appropriate response might be
430      * to drop the suspect touches or to take additional precautions to confirm the user's
431      * actual intent.
432      */
433     public static final int FLAG_WINDOW_IS_OBSCURED = 0x1;
434 
435     /**
436      * This flag indicates that the window that received this motion event is partly
437      * or wholly obscured by another visible window above it.  This flag is set to true
438      * even if the event did not directly pass through the obscured area.
439      * A security sensitive application can check this flag to identify situations in which
440      * a malicious application may have covered up part of its content for the purpose
441      * of misleading the user or hijacking touches.  An appropriate response might be
442      * to drop the suspect touches or to take additional precautions to confirm the user's
443      * actual intent.
444      *
445      * Unlike FLAG_WINDOW_IS_OBSCURED, this is actually true.
446      * @hide
447      */
448     public static final int FLAG_WINDOW_IS_PARTIALLY_OBSCURED = 0x2;
449 
450     /**
451      * This private flag is only set on {@link #ACTION_HOVER_MOVE} events and indicates that
452      * this event will be immediately followed by a {@link #ACTION_HOVER_EXIT}. It is used to
453      * prevent generating redundant {@link #ACTION_HOVER_ENTER} events.
454      * @hide
455      */
456     public static final int FLAG_HOVER_EXIT_PENDING = 0x4;
457 
458     /**
459      * This flag indicates that the event has been generated by a gesture generator. It
460      * provides a hint to the GestureDector to not apply any touch slop.
461      *
462      * @hide
463      */
464     public static final int FLAG_IS_GENERATED_GESTURE = 0x8;
465 
466     /**
467      * Private flag that indicates when the system has detected that this motion event
468      * may be inconsistent with respect to the sequence of previously delivered motion events,
469      * such as when a pointer move event is sent but the pointer is not down.
470      *
471      * @hide
472      * @see #isTainted
473      * @see #setTainted
474      */
475     public static final int FLAG_TAINTED = 0x80000000;
476 
477     /**
478      * Private flag indicating that this event was synthesized by the system and
479      * should be delivered to the accessibility focused view first. When being
480      * dispatched such an event is not handled by predecessors of the accessibility
481      * focused view and after the event reaches that view the flag is cleared and
482      * normal event dispatch is performed. This ensures that the platform can click
483      * on any view that has accessibility focus which is semantically equivalent to
484      * asking the view to perform a click accessibility action but more generic as
485      * views not implementing click action correctly can still be activated.
486      *
487      * @hide
488      * @see #isTargetAccessibilityFocus()
489      * @see #setTargetAccessibilityFocus(boolean)
490      */
491     public static final int FLAG_TARGET_ACCESSIBILITY_FOCUS = 0x40000000;
492 
493 
494     /**
495      * Flag indicating the motion event intersected the top edge of the screen.
496      */
497     public static final int EDGE_TOP = 0x00000001;
498 
499     /**
500      * Flag indicating the motion event intersected the bottom edge of the screen.
501      */
502     public static final int EDGE_BOTTOM = 0x00000002;
503 
504     /**
505      * Flag indicating the motion event intersected the left edge of the screen.
506      */
507     public static final int EDGE_LEFT = 0x00000004;
508 
509     /**
510      * Flag indicating the motion event intersected the right edge of the screen.
511      */
512     public static final int EDGE_RIGHT = 0x00000008;
513 
514     /**
515      * Axis constant: X axis of a motion event.
516      * <p>
517      * <ul>
518      * <li>For a touch screen, reports the absolute X screen position of the center of
519      * the touch contact area.  The units are display pixels.
520      * <li>For a touch pad, reports the absolute X surface position of the center of the touch
521      * contact area.  The units are device-dependent; use {@link InputDevice#getMotionRange(int)}
522      * to query the effective range of values.
523      * <li>For a mouse, reports the absolute X screen position of the mouse pointer.
524      * The units are display pixels.
525      * <li>For a trackball, reports the relative horizontal displacement of the trackball.
526      * The value is normalized to a range from -1.0 (left) to 1.0 (right).
527      * <li>For a joystick, reports the absolute X position of the joystick.
528      * The value is normalized to a range from -1.0 (left) to 1.0 (right).
529      * </ul>
530      * </p>
531      *
532      * @see #getX(int)
533      * @see #getHistoricalX(int, int)
534      * @see MotionEvent.PointerCoords#x
535      * @see InputDevice#getMotionRange
536      */
537     public static final int AXIS_X = 0;
538 
539     /**
540      * Axis constant: Y axis of a motion event.
541      * <p>
542      * <ul>
543      * <li>For a touch screen, reports the absolute Y screen position of the center of
544      * the touch contact area.  The units are display pixels.
545      * <li>For a touch pad, reports the absolute Y surface position of the center of the touch
546      * contact area.  The units are device-dependent; use {@link InputDevice#getMotionRange(int)}
547      * to query the effective range of values.
548      * <li>For a mouse, reports the absolute Y screen position of the mouse pointer.
549      * The units are display pixels.
550      * <li>For a trackball, reports the relative vertical displacement of the trackball.
551      * The value is normalized to a range from -1.0 (up) to 1.0 (down).
552      * <li>For a joystick, reports the absolute Y position of the joystick.
553      * The value is normalized to a range from -1.0 (up or far) to 1.0 (down or near).
554      * </ul>
555      * </p>
556      *
557      * @see #getY(int)
558      * @see #getHistoricalY(int, int)
559      * @see MotionEvent.PointerCoords#y
560      * @see InputDevice#getMotionRange
561      */
562     public static final int AXIS_Y = 1;
563 
564     /**
565      * Axis constant: Pressure axis of a motion event.
566      * <p>
567      * <ul>
568      * <li>For a touch screen or touch pad, reports the approximate pressure applied to the surface
569      * by a finger or other tool.  The value is normalized to a range from
570      * 0 (no pressure at all) to 1 (normal pressure), although values higher than 1
571      * may be generated depending on the calibration of the input device.
572      * <li>For a trackball, the value is set to 1 if the trackball button is pressed
573      * or 0 otherwise.
574      * <li>For a mouse, the value is set to 1 if the primary mouse button is pressed
575      * or 0 otherwise.
576      * </ul>
577      * </p>
578      *
579      * @see #getPressure(int)
580      * @see #getHistoricalPressure(int, int)
581      * @see MotionEvent.PointerCoords#pressure
582      * @see InputDevice#getMotionRange
583      */
584     public static final int AXIS_PRESSURE = 2;
585 
586     /**
587      * Axis constant: Size axis of a motion event.
588      * <p>
589      * <ul>
590      * <li>For a touch screen or touch pad, reports the approximate size of the contact area in
591      * relation to the maximum detectable size for the device.  The value is normalized
592      * to a range from 0 (smallest detectable size) to 1 (largest detectable size),
593      * although it is not a linear scale.  This value is of limited use.
594      * To obtain calibrated size information, use
595      * {@link #AXIS_TOUCH_MAJOR} or {@link #AXIS_TOOL_MAJOR}.
596      * </ul>
597      * </p>
598      *
599      * @see #getSize(int)
600      * @see #getHistoricalSize(int, int)
601      * @see MotionEvent.PointerCoords#size
602      * @see InputDevice#getMotionRange
603      */
604     public static final int AXIS_SIZE = 3;
605 
606     /**
607      * Axis constant: TouchMajor axis of a motion event.
608      * <p>
609      * <ul>
610      * <li>For a touch screen, reports the length of the major axis of an ellipse that
611      * represents the touch area at the point of contact.
612      * The units are display pixels.
613      * <li>For a touch pad, reports the length of the major axis of an ellipse that
614      * represents the touch area at the point of contact.
615      * The units are device-dependent; use {@link InputDevice#getMotionRange(int)}
616      * to query the effective range of values.
617      * </ul>
618      * </p>
619      *
620      * @see #getTouchMajor(int)
621      * @see #getHistoricalTouchMajor(int, int)
622      * @see MotionEvent.PointerCoords#touchMajor
623      * @see InputDevice#getMotionRange
624      */
625     public static final int AXIS_TOUCH_MAJOR = 4;
626 
627     /**
628      * Axis constant: TouchMinor axis of a motion event.
629      * <p>
630      * <ul>
631      * <li>For a touch screen, reports the length of the minor axis of an ellipse that
632      * represents the touch area at the point of contact.
633      * The units are display pixels.
634      * <li>For a touch pad, reports the length of the minor axis of an ellipse that
635      * represents the touch area at the point of contact.
636      * The units are device-dependent; use {@link InputDevice#getMotionRange(int)}
637      * to query the effective range of values.
638      * </ul>
639      * </p><p>
640      * When the touch is circular, the major and minor axis lengths will be equal to one another.
641      * </p>
642      *
643      * @see #getTouchMinor(int)
644      * @see #getHistoricalTouchMinor(int, int)
645      * @see MotionEvent.PointerCoords#touchMinor
646      * @see InputDevice#getMotionRange
647      */
648     public static final int AXIS_TOUCH_MINOR = 5;
649 
650     /**
651      * Axis constant: ToolMajor axis of a motion event.
652      * <p>
653      * <ul>
654      * <li>For a touch screen, reports the length of the major axis of an ellipse that
655      * represents the size of the approaching finger or tool used to make contact.
656      * <li>For a touch pad, reports the length of the major axis of an ellipse that
657      * represents the size of the approaching finger or tool used to make contact.
658      * The units are device-dependent; use {@link InputDevice#getMotionRange(int)}
659      * to query the effective range of values.
660      * </ul>
661      * </p><p>
662      * When the touch is circular, the major and minor axis lengths will be equal to one another.
663      * </p><p>
664      * The tool size may be larger than the touch size since the tool may not be fully
665      * in contact with the touch sensor.
666      * </p>
667      *
668      * @see #getToolMajor(int)
669      * @see #getHistoricalToolMajor(int, int)
670      * @see MotionEvent.PointerCoords#toolMajor
671      * @see InputDevice#getMotionRange
672      */
673     public static final int AXIS_TOOL_MAJOR = 6;
674 
675     /**
676      * Axis constant: ToolMinor axis of a motion event.
677      * <p>
678      * <ul>
679      * <li>For a touch screen, reports the length of the minor axis of an ellipse that
680      * represents the size of the approaching finger or tool used to make contact.
681      * <li>For a touch pad, reports the length of the minor axis of an ellipse that
682      * represents the size of the approaching finger or tool used to make contact.
683      * The units are device-dependent; use {@link InputDevice#getMotionRange(int)}
684      * to query the effective range of values.
685      * </ul>
686      * </p><p>
687      * When the touch is circular, the major and minor axis lengths will be equal to one another.
688      * </p><p>
689      * The tool size may be larger than the touch size since the tool may not be fully
690      * in contact with the touch sensor.
691      * </p>
692      *
693      * @see #getToolMinor(int)
694      * @see #getHistoricalToolMinor(int, int)
695      * @see MotionEvent.PointerCoords#toolMinor
696      * @see InputDevice#getMotionRange
697      */
698     public static final int AXIS_TOOL_MINOR = 7;
699 
700     /**
701      * Axis constant: Orientation axis of a motion event.
702      * <p>
703      * <ul>
704      * <li>For a touch screen or touch pad, reports the orientation of the finger
705      * or tool in radians relative to the vertical plane of the device.
706      * An angle of 0 radians indicates that the major axis of contact is oriented
707      * upwards, is perfectly circular or is of unknown orientation.  A positive angle
708      * indicates that the major axis of contact is oriented to the right.  A negative angle
709      * indicates that the major axis of contact is oriented to the left.
710      * The full range is from -PI/2 radians (finger pointing fully left) to PI/2 radians
711      * (finger pointing fully right).
712      * <li>For a stylus, the orientation indicates the direction in which the stylus
713      * is pointing in relation to the vertical axis of the current orientation of the screen.
714      * The range is from -PI radians to PI radians, where 0 is pointing up,
715      * -PI/2 radians is pointing left, -PI or PI radians is pointing down, and PI/2 radians
716      * is pointing right.  See also {@link #AXIS_TILT}.
717      * </ul>
718      * </p>
719      *
720      * @see #getOrientation(int)
721      * @see #getHistoricalOrientation(int, int)
722      * @see MotionEvent.PointerCoords#orientation
723      * @see InputDevice#getMotionRange
724      */
725     public static final int AXIS_ORIENTATION = 8;
726 
727     /**
728      * Axis constant: Vertical Scroll axis of a motion event.
729      * <p>
730      * <ul>
731      * <li>For a mouse, reports the relative movement of the vertical scroll wheel.
732      * The value is normalized to a range from -1.0 (down) to 1.0 (up).
733      * </ul>
734      * </p><p>
735      * This axis should be used to scroll views vertically.
736      * </p>
737      *
738      * @see #getAxisValue(int, int)
739      * @see #getHistoricalAxisValue(int, int, int)
740      * @see MotionEvent.PointerCoords#getAxisValue(int)
741      * @see InputDevice#getMotionRange
742      */
743     public static final int AXIS_VSCROLL = 9;
744 
745     /**
746      * Axis constant: Horizontal Scroll axis of a motion event.
747      * <p>
748      * <ul>
749      * <li>For a mouse, reports the relative movement of the horizontal scroll wheel.
750      * The value is normalized to a range from -1.0 (left) to 1.0 (right).
751      * </ul>
752      * </p><p>
753      * This axis should be used to scroll views horizontally.
754      * </p>
755      *
756      * @see #getAxisValue(int, int)
757      * @see #getHistoricalAxisValue(int, int, int)
758      * @see MotionEvent.PointerCoords#getAxisValue(int)
759      * @see InputDevice#getMotionRange
760      */
761     public static final int AXIS_HSCROLL = 10;
762 
763     /**
764      * Axis constant: Z axis of a motion event.
765      * <p>
766      * <ul>
767      * <li>For a joystick, reports the absolute Z position of the joystick.
768      * The value is normalized to a range from -1.0 (high) to 1.0 (low).
769      * <em>On game pads with two analog joysticks, this axis is often reinterpreted
770      * to report the absolute X position of the second joystick instead.</em>
771      * </ul>
772      * </p>
773      *
774      * @see #getAxisValue(int, int)
775      * @see #getHistoricalAxisValue(int, int, int)
776      * @see MotionEvent.PointerCoords#getAxisValue(int)
777      * @see InputDevice#getMotionRange
778      */
779     public static final int AXIS_Z = 11;
780 
781     /**
782      * Axis constant: X Rotation axis of a motion event.
783      * <p>
784      * <ul>
785      * <li>For a joystick, reports the absolute rotation angle about the X axis.
786      * The value is normalized to a range from -1.0 (counter-clockwise) to 1.0 (clockwise).
787      * </ul>
788      * </p>
789      *
790      * @see #getAxisValue(int, int)
791      * @see #getHistoricalAxisValue(int, int, int)
792      * @see MotionEvent.PointerCoords#getAxisValue(int)
793      * @see InputDevice#getMotionRange
794      */
795     public static final int AXIS_RX = 12;
796 
797     /**
798      * Axis constant: Y Rotation axis of a motion event.
799      * <p>
800      * <ul>
801      * <li>For a joystick, reports the absolute rotation angle about the Y axis.
802      * The value is normalized to a range from -1.0 (counter-clockwise) to 1.0 (clockwise).
803      * </ul>
804      * </p>
805      *
806      * @see #getAxisValue(int, int)
807      * @see #getHistoricalAxisValue(int, int, int)
808      * @see MotionEvent.PointerCoords#getAxisValue(int)
809      * @see InputDevice#getMotionRange
810      */
811     public static final int AXIS_RY = 13;
812 
813     /**
814      * Axis constant: Z Rotation axis of a motion event.
815      * <p>
816      * <ul>
817      * <li>For a joystick, reports the absolute rotation angle about the Z axis.
818      * The value is normalized to a range from -1.0 (counter-clockwise) to 1.0 (clockwise).
819      * <em>On game pads with two analog joysticks, this axis is often reinterpreted
820      * to report the absolute Y position of the second joystick instead.</em>
821      * </ul>
822      * </p>
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_RZ = 14;
830 
831     /**
832      * Axis constant: Hat X axis of a motion event.
833      * <p>
834      * <ul>
835      * <li>For a joystick, reports the absolute X position of the directional hat control.
836      * The value is normalized to a range from -1.0 (left) to 1.0 (right).
837      * </ul>
838      * </p>
839      *
840      * @see #getAxisValue(int, int)
841      * @see #getHistoricalAxisValue(int, int, int)
842      * @see MotionEvent.PointerCoords#getAxisValue(int)
843      * @see InputDevice#getMotionRange
844      */
845     public static final int AXIS_HAT_X = 15;
846 
847     /**
848      * Axis constant: Hat Y axis of a motion event.
849      * <p>
850      * <ul>
851      * <li>For a joystick, reports the absolute Y position of the directional hat control.
852      * The value is normalized to a range from -1.0 (up) to 1.0 (down).
853      * </ul>
854      * </p>
855      *
856      * @see #getAxisValue(int, int)
857      * @see #getHistoricalAxisValue(int, int, int)
858      * @see MotionEvent.PointerCoords#getAxisValue(int)
859      * @see InputDevice#getMotionRange
860      */
861     public static final int AXIS_HAT_Y = 16;
862 
863     /**
864      * Axis constant: Left Trigger axis of a motion event.
865      * <p>
866      * <ul>
867      * <li>For a joystick, reports the absolute position of the left trigger control.
868      * The value is normalized to a range from 0.0 (released) to 1.0 (fully pressed).
869      * </ul>
870      * </p>
871      *
872      * @see #getAxisValue(int, int)
873      * @see #getHistoricalAxisValue(int, int, int)
874      * @see MotionEvent.PointerCoords#getAxisValue(int)
875      * @see InputDevice#getMotionRange
876      */
877     public static final int AXIS_LTRIGGER = 17;
878 
879     /**
880      * Axis constant: Right Trigger axis of a motion event.
881      * <p>
882      * <ul>
883      * <li>For a joystick, reports the absolute position of the right trigger control.
884      * The value is normalized to a range from 0.0 (released) to 1.0 (fully pressed).
885      * </ul>
886      * </p>
887      *
888      * @see #getAxisValue(int, int)
889      * @see #getHistoricalAxisValue(int, int, int)
890      * @see MotionEvent.PointerCoords#getAxisValue(int)
891      * @see InputDevice#getMotionRange
892      */
893     public static final int AXIS_RTRIGGER = 18;
894 
895     /**
896      * Axis constant: Throttle axis of a motion event.
897      * <p>
898      * <ul>
899      * <li>For a joystick, reports the absolute position of the throttle control.
900      * The value is normalized to a range from 0.0 (fully open) to 1.0 (fully closed).
901      * </ul>
902      * </p>
903      *
904      * @see #getAxisValue(int, int)
905      * @see #getHistoricalAxisValue(int, int, int)
906      * @see MotionEvent.PointerCoords#getAxisValue(int)
907      * @see InputDevice#getMotionRange
908      */
909     public static final int AXIS_THROTTLE = 19;
910 
911     /**
912      * Axis constant: Rudder axis of a motion event.
913      * <p>
914      * <ul>
915      * <li>For a joystick, reports the absolute position of the rudder control.
916      * The value is normalized to a range from -1.0 (turn left) to 1.0 (turn right).
917      * </ul>
918      * </p>
919      *
920      * @see #getAxisValue(int, int)
921      * @see #getHistoricalAxisValue(int, int, int)
922      * @see MotionEvent.PointerCoords#getAxisValue(int)
923      * @see InputDevice#getMotionRange
924      */
925     public static final int AXIS_RUDDER = 20;
926 
927     /**
928      * Axis constant: Wheel axis of a motion event.
929      * <p>
930      * <ul>
931      * <li>For a joystick, reports the absolute position of the steering wheel control.
932      * The value is normalized to a range from -1.0 (turn left) to 1.0 (turn right).
933      * </ul>
934      * </p>
935      *
936      * @see #getAxisValue(int, int)
937      * @see #getHistoricalAxisValue(int, int, int)
938      * @see MotionEvent.PointerCoords#getAxisValue(int)
939      * @see InputDevice#getMotionRange
940      */
941     public static final int AXIS_WHEEL = 21;
942 
943     /**
944      * Axis constant: Gas axis of a motion event.
945      * <p>
946      * <ul>
947      * <li>For a joystick, reports the absolute position of the gas (accelerator) control.
948      * The value is normalized to a range from 0.0 (no acceleration)
949      * to 1.0 (maximum acceleration).
950      * </ul>
951      * </p>
952      *
953      * @see #getAxisValue(int, int)
954      * @see #getHistoricalAxisValue(int, int, int)
955      * @see MotionEvent.PointerCoords#getAxisValue(int)
956      * @see InputDevice#getMotionRange
957      */
958     public static final int AXIS_GAS = 22;
959 
960     /**
961      * Axis constant: Brake axis of a motion event.
962      * <p>
963      * <ul>
964      * <li>For a joystick, reports the absolute position of the brake control.
965      * The value is normalized to a range from 0.0 (no braking) to 1.0 (maximum braking).
966      * </ul>
967      * </p>
968      *
969      * @see #getAxisValue(int, int)
970      * @see #getHistoricalAxisValue(int, int, int)
971      * @see MotionEvent.PointerCoords#getAxisValue(int)
972      * @see InputDevice#getMotionRange
973      */
974     public static final int AXIS_BRAKE = 23;
975 
976     /**
977      * Axis constant: Distance axis of a motion event.
978      * <p>
979      * <ul>
980      * <li>For a stylus, reports the distance of the stylus from the screen.
981      * A value of 0.0 indicates direct contact and larger values indicate increasing
982      * distance from the surface.
983      * </ul>
984      * </p>
985      *
986      * @see #getAxisValue(int, int)
987      * @see #getHistoricalAxisValue(int, int, int)
988      * @see MotionEvent.PointerCoords#getAxisValue(int)
989      * @see InputDevice#getMotionRange
990      */
991     public static final int AXIS_DISTANCE = 24;
992 
993     /**
994      * Axis constant: Tilt axis of a motion event.
995      * <p>
996      * <ul>
997      * <li>For a stylus, reports the tilt angle of the stylus in radians where
998      * 0 radians indicates that the stylus is being held perpendicular to the
999      * surface, and PI/2 radians indicates that the stylus is being held flat
1000      * against the surface.
1001      * </ul>
1002      * </p>
1003      *
1004      * @see #getAxisValue(int, int)
1005      * @see #getHistoricalAxisValue(int, int, int)
1006      * @see MotionEvent.PointerCoords#getAxisValue(int, int)
1007      * @see InputDevice#getMotionRange
1008      */
1009     public static final int AXIS_TILT = 25;
1010 
1011     /**
1012      * Axis constant: Generic scroll axis of a motion event.
1013      * <p>
1014      * <ul>
1015      * <li>Reports the relative movement of the generic scrolling device.
1016      * </ul>
1017      * </p><p>
1018      * This axis should be used for scroll events that are neither strictly vertical nor horizontal.
1019      * A good example would be the rotation of a rotary encoder input device.
1020      * </p>
1021      *
1022      * @see #getAxisValue(int, int)
1023      */
1024     public static final int AXIS_SCROLL = 26;
1025 
1026     /**
1027      * Axis constant: The movement of x position of a motion event.
1028      * <p>
1029      * <ul>
1030      * <li>For a mouse, reports a difference of x position between the previous position.
1031      * This is useful when pointer is captured, in that case the mouse pointer doesn't change
1032      * the location but this axis reports the difference which allows the app to see
1033      * how the mouse is moved.
1034      * </ul>
1035      * </p>
1036      *
1037      * @see #getAxisValue(int, int)
1038      * @see #getHistoricalAxisValue(int, int, int)
1039      * @see MotionEvent.PointerCoords#getAxisValue(int, int)
1040      * @see InputDevice#getMotionRange
1041      */
1042     public static final int AXIS_RELATIVE_X = 27;
1043 
1044     /**
1045      * Axis constant: The movement of y position of a motion event.
1046      * <p>
1047      * This is similar to {@link #AXIS_RELATIVE_X} but for y-axis.
1048      * </p>
1049      *
1050      * @see #getAxisValue(int, int)
1051      * @see #getHistoricalAxisValue(int, int, int)
1052      * @see MotionEvent.PointerCoords#getAxisValue(int, int)
1053      * @see InputDevice#getMotionRange
1054      */
1055     public static final int AXIS_RELATIVE_Y = 28;
1056 
1057     /**
1058      * Axis constant: Generic 1 axis of a motion event.
1059      * The interpretation of a generic axis is device-specific.
1060      *
1061      * @see #getAxisValue(int, int)
1062      * @see #getHistoricalAxisValue(int, int, int)
1063      * @see MotionEvent.PointerCoords#getAxisValue(int)
1064      * @see InputDevice#getMotionRange
1065      */
1066     public static final int AXIS_GENERIC_1 = 32;
1067 
1068     /**
1069      * Axis constant: Generic 2 axis of a motion event.
1070      * The interpretation of a generic axis is device-specific.
1071      *
1072      * @see #getAxisValue(int, int)
1073      * @see #getHistoricalAxisValue(int, int, int)
1074      * @see MotionEvent.PointerCoords#getAxisValue(int)
1075      * @see InputDevice#getMotionRange
1076      */
1077     public static final int AXIS_GENERIC_2 = 33;
1078 
1079     /**
1080      * Axis constant: Generic 3 axis of a motion event.
1081      * The interpretation of a generic axis is device-specific.
1082      *
1083      * @see #getAxisValue(int, int)
1084      * @see #getHistoricalAxisValue(int, int, int)
1085      * @see MotionEvent.PointerCoords#getAxisValue(int)
1086      * @see InputDevice#getMotionRange
1087      */
1088     public static final int AXIS_GENERIC_3 = 34;
1089 
1090     /**
1091      * Axis constant: Generic 4 axis of a motion event.
1092      * The interpretation of a generic axis is device-specific.
1093      *
1094      * @see #getAxisValue(int, int)
1095      * @see #getHistoricalAxisValue(int, int, int)
1096      * @see MotionEvent.PointerCoords#getAxisValue(int)
1097      * @see InputDevice#getMotionRange
1098      */
1099     public static final int AXIS_GENERIC_4 = 35;
1100 
1101     /**
1102      * Axis constant: Generic 5 axis of a motion event.
1103      * The interpretation of a generic axis is device-specific.
1104      *
1105      * @see #getAxisValue(int, int)
1106      * @see #getHistoricalAxisValue(int, int, int)
1107      * @see MotionEvent.PointerCoords#getAxisValue(int)
1108      * @see InputDevice#getMotionRange
1109      */
1110     public static final int AXIS_GENERIC_5 = 36;
1111 
1112     /**
1113      * Axis constant: Generic 6 axis of a motion event.
1114      * The interpretation of a generic axis is device-specific.
1115      *
1116      * @see #getAxisValue(int, int)
1117      * @see #getHistoricalAxisValue(int, int, int)
1118      * @see MotionEvent.PointerCoords#getAxisValue(int)
1119      * @see InputDevice#getMotionRange
1120      */
1121     public static final int AXIS_GENERIC_6 = 37;
1122 
1123     /**
1124      * Axis constant: Generic 7 axis of a motion event.
1125      * The interpretation of a generic axis is device-specific.
1126      *
1127      * @see #getAxisValue(int, int)
1128      * @see #getHistoricalAxisValue(int, int, int)
1129      * @see MotionEvent.PointerCoords#getAxisValue(int)
1130      * @see InputDevice#getMotionRange
1131      */
1132     public static final int AXIS_GENERIC_7 = 38;
1133 
1134     /**
1135      * Axis constant: Generic 8 axis of a motion event.
1136      * The interpretation of a generic axis is device-specific.
1137      *
1138      * @see #getAxisValue(int, int)
1139      * @see #getHistoricalAxisValue(int, int, int)
1140      * @see MotionEvent.PointerCoords#getAxisValue(int)
1141      * @see InputDevice#getMotionRange
1142      */
1143     public static final int AXIS_GENERIC_8 = 39;
1144 
1145     /**
1146      * Axis constant: Generic 9 axis of a motion event.
1147      * The interpretation of a generic axis is device-specific.
1148      *
1149      * @see #getAxisValue(int, int)
1150      * @see #getHistoricalAxisValue(int, int, int)
1151      * @see MotionEvent.PointerCoords#getAxisValue(int)
1152      * @see InputDevice#getMotionRange
1153      */
1154     public static final int AXIS_GENERIC_9 = 40;
1155 
1156     /**
1157      * Axis constant: Generic 10 axis of a motion event.
1158      * The interpretation of a generic axis is device-specific.
1159      *
1160      * @see #getAxisValue(int, int)
1161      * @see #getHistoricalAxisValue(int, int, int)
1162      * @see MotionEvent.PointerCoords#getAxisValue(int)
1163      * @see InputDevice#getMotionRange
1164      */
1165     public static final int AXIS_GENERIC_10 = 41;
1166 
1167     /**
1168      * Axis constant: Generic 11 axis of a motion event.
1169      * The interpretation of a generic axis is device-specific.
1170      *
1171      * @see #getAxisValue(int, int)
1172      * @see #getHistoricalAxisValue(int, int, int)
1173      * @see MotionEvent.PointerCoords#getAxisValue(int)
1174      * @see InputDevice#getMotionRange
1175      */
1176     public static final int AXIS_GENERIC_11 = 42;
1177 
1178     /**
1179      * Axis constant: Generic 12 axis of a motion event.
1180      * The interpretation of a generic axis is device-specific.
1181      *
1182      * @see #getAxisValue(int, int)
1183      * @see #getHistoricalAxisValue(int, int, int)
1184      * @see MotionEvent.PointerCoords#getAxisValue(int)
1185      * @see InputDevice#getMotionRange
1186      */
1187     public static final int AXIS_GENERIC_12 = 43;
1188 
1189     /**
1190      * Axis constant: Generic 13 axis of a motion event.
1191      * The interpretation of a generic axis is device-specific.
1192      *
1193      * @see #getAxisValue(int, int)
1194      * @see #getHistoricalAxisValue(int, int, int)
1195      * @see MotionEvent.PointerCoords#getAxisValue(int)
1196      * @see InputDevice#getMotionRange
1197      */
1198     public static final int AXIS_GENERIC_13 = 44;
1199 
1200     /**
1201      * Axis constant: Generic 14 axis of a motion event.
1202      * The interpretation of a generic axis is device-specific.
1203      *
1204      * @see #getAxisValue(int, int)
1205      * @see #getHistoricalAxisValue(int, int, int)
1206      * @see MotionEvent.PointerCoords#getAxisValue(int)
1207      * @see InputDevice#getMotionRange
1208      */
1209     public static final int AXIS_GENERIC_14 = 45;
1210 
1211     /**
1212      * Axis constant: Generic 15 axis of a motion event.
1213      * The interpretation of a generic axis is device-specific.
1214      *
1215      * @see #getAxisValue(int, int)
1216      * @see #getHistoricalAxisValue(int, int, int)
1217      * @see MotionEvent.PointerCoords#getAxisValue(int)
1218      * @see InputDevice#getMotionRange
1219      */
1220     public static final int AXIS_GENERIC_15 = 46;
1221 
1222     /**
1223      * Axis constant: Generic 16 axis of a motion event.
1224      * The interpretation of a generic axis is device-specific.
1225      *
1226      * @see #getAxisValue(int, int)
1227      * @see #getHistoricalAxisValue(int, int, int)
1228      * @see MotionEvent.PointerCoords#getAxisValue(int)
1229      * @see InputDevice#getMotionRange
1230      */
1231     public static final int AXIS_GENERIC_16 = 47;
1232 
1233     // NOTE: If you add a new axis here you must also add it to:
1234     //  native/include/android/input.h
1235     //  frameworks/base/include/ui/KeycodeLabels.h
1236 
1237     // Symbolic names of all axes.
1238     private static final SparseArray<String> AXIS_SYMBOLIC_NAMES = new SparseArray<String>();
1239     static {
1240         SparseArray<String> names = AXIS_SYMBOLIC_NAMES;
names.append(AXIS_X, "AXIS_X")1241         names.append(AXIS_X, "AXIS_X");
names.append(AXIS_Y, "AXIS_Y")1242         names.append(AXIS_Y, "AXIS_Y");
names.append(AXIS_PRESSURE, "AXIS_PRESSURE")1243         names.append(AXIS_PRESSURE, "AXIS_PRESSURE");
names.append(AXIS_SIZE, "AXIS_SIZE")1244         names.append(AXIS_SIZE, "AXIS_SIZE");
names.append(AXIS_TOUCH_MAJOR, "AXIS_TOUCH_MAJOR")1245         names.append(AXIS_TOUCH_MAJOR, "AXIS_TOUCH_MAJOR");
names.append(AXIS_TOUCH_MINOR, "AXIS_TOUCH_MINOR")1246         names.append(AXIS_TOUCH_MINOR, "AXIS_TOUCH_MINOR");
names.append(AXIS_TOOL_MAJOR, "AXIS_TOOL_MAJOR")1247         names.append(AXIS_TOOL_MAJOR, "AXIS_TOOL_MAJOR");
names.append(AXIS_TOOL_MINOR, "AXIS_TOOL_MINOR")1248         names.append(AXIS_TOOL_MINOR, "AXIS_TOOL_MINOR");
names.append(AXIS_ORIENTATION, "AXIS_ORIENTATION")1249         names.append(AXIS_ORIENTATION, "AXIS_ORIENTATION");
names.append(AXIS_VSCROLL, "AXIS_VSCROLL")1250         names.append(AXIS_VSCROLL, "AXIS_VSCROLL");
names.append(AXIS_HSCROLL, "AXIS_HSCROLL")1251         names.append(AXIS_HSCROLL, "AXIS_HSCROLL");
names.append(AXIS_Z, "AXIS_Z")1252         names.append(AXIS_Z, "AXIS_Z");
names.append(AXIS_RX, "AXIS_RX")1253         names.append(AXIS_RX, "AXIS_RX");
names.append(AXIS_RY, "AXIS_RY")1254         names.append(AXIS_RY, "AXIS_RY");
names.append(AXIS_RZ, "AXIS_RZ")1255         names.append(AXIS_RZ, "AXIS_RZ");
names.append(AXIS_HAT_X, "AXIS_HAT_X")1256         names.append(AXIS_HAT_X, "AXIS_HAT_X");
names.append(AXIS_HAT_Y, "AXIS_HAT_Y")1257         names.append(AXIS_HAT_Y, "AXIS_HAT_Y");
names.append(AXIS_LTRIGGER, "AXIS_LTRIGGER")1258         names.append(AXIS_LTRIGGER, "AXIS_LTRIGGER");
names.append(AXIS_RTRIGGER, "AXIS_RTRIGGER")1259         names.append(AXIS_RTRIGGER, "AXIS_RTRIGGER");
names.append(AXIS_THROTTLE, "AXIS_THROTTLE")1260         names.append(AXIS_THROTTLE, "AXIS_THROTTLE");
names.append(AXIS_RUDDER, "AXIS_RUDDER")1261         names.append(AXIS_RUDDER, "AXIS_RUDDER");
names.append(AXIS_WHEEL, "AXIS_WHEEL")1262         names.append(AXIS_WHEEL, "AXIS_WHEEL");
names.append(AXIS_GAS, "AXIS_GAS")1263         names.append(AXIS_GAS, "AXIS_GAS");
names.append(AXIS_BRAKE, "AXIS_BRAKE")1264         names.append(AXIS_BRAKE, "AXIS_BRAKE");
names.append(AXIS_DISTANCE, "AXIS_DISTANCE")1265         names.append(AXIS_DISTANCE, "AXIS_DISTANCE");
names.append(AXIS_TILT, "AXIS_TILT")1266         names.append(AXIS_TILT, "AXIS_TILT");
names.append(AXIS_SCROLL, "AXIS_SCROLL")1267         names.append(AXIS_SCROLL, "AXIS_SCROLL");
names.append(AXIS_RELATIVE_X, "AXIS_REALTIVE_X")1268         names.append(AXIS_RELATIVE_X, "AXIS_REALTIVE_X");
names.append(AXIS_RELATIVE_Y, "AXIS_REALTIVE_Y")1269         names.append(AXIS_RELATIVE_Y, "AXIS_REALTIVE_Y");
names.append(AXIS_GENERIC_1, "AXIS_GENERIC_1")1270         names.append(AXIS_GENERIC_1, "AXIS_GENERIC_1");
names.append(AXIS_GENERIC_2, "AXIS_GENERIC_2")1271         names.append(AXIS_GENERIC_2, "AXIS_GENERIC_2");
names.append(AXIS_GENERIC_3, "AXIS_GENERIC_3")1272         names.append(AXIS_GENERIC_3, "AXIS_GENERIC_3");
names.append(AXIS_GENERIC_4, "AXIS_GENERIC_4")1273         names.append(AXIS_GENERIC_4, "AXIS_GENERIC_4");
names.append(AXIS_GENERIC_5, "AXIS_GENERIC_5")1274         names.append(AXIS_GENERIC_5, "AXIS_GENERIC_5");
names.append(AXIS_GENERIC_6, "AXIS_GENERIC_6")1275         names.append(AXIS_GENERIC_6, "AXIS_GENERIC_6");
names.append(AXIS_GENERIC_7, "AXIS_GENERIC_7")1276         names.append(AXIS_GENERIC_7, "AXIS_GENERIC_7");
names.append(AXIS_GENERIC_8, "AXIS_GENERIC_8")1277         names.append(AXIS_GENERIC_8, "AXIS_GENERIC_8");
names.append(AXIS_GENERIC_9, "AXIS_GENERIC_9")1278         names.append(AXIS_GENERIC_9, "AXIS_GENERIC_9");
names.append(AXIS_GENERIC_10, "AXIS_GENERIC_10")1279         names.append(AXIS_GENERIC_10, "AXIS_GENERIC_10");
names.append(AXIS_GENERIC_11, "AXIS_GENERIC_11")1280         names.append(AXIS_GENERIC_11, "AXIS_GENERIC_11");
names.append(AXIS_GENERIC_12, "AXIS_GENERIC_12")1281         names.append(AXIS_GENERIC_12, "AXIS_GENERIC_12");
names.append(AXIS_GENERIC_13, "AXIS_GENERIC_13")1282         names.append(AXIS_GENERIC_13, "AXIS_GENERIC_13");
names.append(AXIS_GENERIC_14, "AXIS_GENERIC_14")1283         names.append(AXIS_GENERIC_14, "AXIS_GENERIC_14");
names.append(AXIS_GENERIC_15, "AXIS_GENERIC_15")1284         names.append(AXIS_GENERIC_15, "AXIS_GENERIC_15");
names.append(AXIS_GENERIC_16, "AXIS_GENERIC_16")1285         names.append(AXIS_GENERIC_16, "AXIS_GENERIC_16");
1286     }
1287 
1288     /**
1289      * Button constant: Primary button (left mouse button).
1290      *
1291      * This button constant is not set in response to simple touches with a finger
1292      * or stylus tip.  The user must actually push a button.
1293      *
1294      * @see #getButtonState
1295      */
1296     public static final int BUTTON_PRIMARY = 1 << 0;
1297 
1298     /**
1299      * Button constant: Secondary button (right mouse button).
1300      *
1301      * @see #getButtonState
1302      */
1303     public static final int BUTTON_SECONDARY = 1 << 1;
1304 
1305     /**
1306      * Button constant: Tertiary button (middle mouse button).
1307      *
1308      * @see #getButtonState
1309      */
1310     public static final int BUTTON_TERTIARY = 1 << 2;
1311 
1312     /**
1313      * Button constant: Back button pressed (mouse back button).
1314      * <p>
1315      * The system may send a {@link KeyEvent#KEYCODE_BACK} key press to the application
1316      * when this button is pressed.
1317      * </p>
1318      *
1319      * @see #getButtonState
1320      */
1321     public static final int BUTTON_BACK = 1 << 3;
1322 
1323     /**
1324      * Button constant: Forward button pressed (mouse forward button).
1325      * <p>
1326      * The system may send a {@link KeyEvent#KEYCODE_FORWARD} key press to the application
1327      * when this button is pressed.
1328      * </p>
1329      *
1330      * @see #getButtonState
1331      */
1332     public static final int BUTTON_FORWARD = 1 << 4;
1333 
1334     /**
1335      * Button constant: Primary stylus button pressed.
1336      *
1337      * @see #getButtonState
1338      */
1339     public static final int BUTTON_STYLUS_PRIMARY = 1 << 5;
1340 
1341     /**
1342      * Button constant: Secondary stylus button pressed.
1343      *
1344      * @see #getButtonState
1345      */
1346     public static final int BUTTON_STYLUS_SECONDARY = 1 << 6;
1347 
1348     // NOTE: If you add a new axis here you must also add it to:
1349     //  native/include/android/input.h
1350 
1351     // Symbolic names of all button states in bit order from least significant
1352     // to most significant.
1353     private static final String[] BUTTON_SYMBOLIC_NAMES = new String[] {
1354         "BUTTON_PRIMARY",
1355         "BUTTON_SECONDARY",
1356         "BUTTON_TERTIARY",
1357         "BUTTON_BACK",
1358         "BUTTON_FORWARD",
1359         "BUTTON_STYLUS_PRIMARY",
1360         "BUTTON_STYLUS_SECONDARY",
1361         "0x00000080",
1362         "0x00000100",
1363         "0x00000200",
1364         "0x00000400",
1365         "0x00000800",
1366         "0x00001000",
1367         "0x00002000",
1368         "0x00004000",
1369         "0x00008000",
1370         "0x00010000",
1371         "0x00020000",
1372         "0x00040000",
1373         "0x00080000",
1374         "0x00100000",
1375         "0x00200000",
1376         "0x00400000",
1377         "0x00800000",
1378         "0x01000000",
1379         "0x02000000",
1380         "0x04000000",
1381         "0x08000000",
1382         "0x10000000",
1383         "0x20000000",
1384         "0x40000000",
1385         "0x80000000",
1386     };
1387 
1388     /**
1389      * Tool type constant: Unknown tool type.
1390      * This constant is used when the tool type is not known or is not relevant,
1391      * such as for a trackball or other non-pointing device.
1392      *
1393      * @see #getToolType
1394      */
1395     public static final int TOOL_TYPE_UNKNOWN = 0;
1396 
1397     /**
1398      * Tool type constant: The tool is a finger.
1399      *
1400      * @see #getToolType
1401      */
1402     public static final int TOOL_TYPE_FINGER = 1;
1403 
1404     /**
1405      * Tool type constant: The tool is a stylus.
1406      *
1407      * @see #getToolType
1408      */
1409     public static final int TOOL_TYPE_STYLUS = 2;
1410 
1411     /**
1412      * Tool type constant: The tool is a mouse or trackpad.
1413      *
1414      * @see #getToolType
1415      */
1416     public static final int TOOL_TYPE_MOUSE = 3;
1417 
1418     /**
1419      * Tool type constant: The tool is an eraser or a stylus being used in an inverted posture.
1420      *
1421      * @see #getToolType
1422      */
1423     public static final int TOOL_TYPE_ERASER = 4;
1424 
1425     // NOTE: If you add a new tool type here you must also add it to:
1426     //  native/include/android/input.h
1427 
1428     // Symbolic names of all tool types.
1429     private static final SparseArray<String> TOOL_TYPE_SYMBOLIC_NAMES = new SparseArray<String>();
1430     static {
1431         SparseArray<String> names = TOOL_TYPE_SYMBOLIC_NAMES;
names.append(TOOL_TYPE_UNKNOWN, "TOOL_TYPE_UNKNOWN")1432         names.append(TOOL_TYPE_UNKNOWN, "TOOL_TYPE_UNKNOWN");
names.append(TOOL_TYPE_FINGER, "TOOL_TYPE_FINGER")1433         names.append(TOOL_TYPE_FINGER, "TOOL_TYPE_FINGER");
names.append(TOOL_TYPE_STYLUS, "TOOL_TYPE_STYLUS")1434         names.append(TOOL_TYPE_STYLUS, "TOOL_TYPE_STYLUS");
names.append(TOOL_TYPE_MOUSE, "TOOL_TYPE_MOUSE")1435         names.append(TOOL_TYPE_MOUSE, "TOOL_TYPE_MOUSE");
names.append(TOOL_TYPE_ERASER, "TOOL_TYPE_ERASER")1436         names.append(TOOL_TYPE_ERASER, "TOOL_TYPE_ERASER");
1437     }
1438 
1439     // Private value for history pos that obtains the current sample.
1440     private static final int HISTORY_CURRENT = -0x80000000;
1441 
1442     private static final int MAX_RECYCLED = 10;
1443     private static final Object gRecyclerLock = new Object();
1444     private static int gRecyclerUsed;
1445     private static MotionEvent gRecyclerTop;
1446 
1447     // Shared temporary objects used when translating coordinates supplied by
1448     // the caller into single element PointerCoords and pointer id arrays.
1449     private static final Object gSharedTempLock = new Object();
1450     private static PointerCoords[] gSharedTempPointerCoords;
1451     private static PointerProperties[] gSharedTempPointerProperties;
1452     private static int[] gSharedTempPointerIndexMap;
1453 
ensureSharedTempPointerCapacity(int desiredCapacity)1454     private static final void ensureSharedTempPointerCapacity(int desiredCapacity) {
1455         if (gSharedTempPointerCoords == null
1456                 || gSharedTempPointerCoords.length < desiredCapacity) {
1457             int capacity = gSharedTempPointerCoords != null ? gSharedTempPointerCoords.length : 8;
1458             while (capacity < desiredCapacity) {
1459                 capacity *= 2;
1460             }
1461             gSharedTempPointerCoords = PointerCoords.createArray(capacity);
1462             gSharedTempPointerProperties = PointerProperties.createArray(capacity);
1463             gSharedTempPointerIndexMap = new int[capacity];
1464         }
1465     }
1466 
1467     // Pointer to the native MotionEvent object that contains the actual data.
1468     private long mNativePtr;
1469 
1470     private MotionEvent mNext;
1471 
nativeInitialize(long nativePtr, int deviceId, int source, int action, int flags, int edgeFlags, int metaState, int buttonState, float xOffset, float yOffset, float xPrecision, float yPrecision, long downTimeNanos, long eventTimeNanos, int pointerCount, PointerProperties[] pointerIds, PointerCoords[] pointerCoords)1472     private static native long nativeInitialize(long nativePtr,
1473             int deviceId, int source, int action, int flags, int edgeFlags,
1474             int metaState, int buttonState,
1475             float xOffset, float yOffset, float xPrecision, float yPrecision,
1476             long downTimeNanos, long eventTimeNanos,
1477             int pointerCount, PointerProperties[] pointerIds, PointerCoords[] pointerCoords);
nativeDispose(long nativePtr)1478     private static native void nativeDispose(long nativePtr);
nativeAddBatch(long nativePtr, long eventTimeNanos, PointerCoords[] pointerCoords, int metaState)1479     private static native void nativeAddBatch(long nativePtr, long eventTimeNanos,
1480             PointerCoords[] pointerCoords, int metaState);
nativeGetPointerCoords(long nativePtr, int pointerIndex, int historyPos, PointerCoords outPointerCoords)1481     private static native void nativeGetPointerCoords(long nativePtr,
1482             int pointerIndex, int historyPos, PointerCoords outPointerCoords);
nativeGetPointerProperties(long nativePtr, int pointerIndex, PointerProperties outPointerProperties)1483     private static native void nativeGetPointerProperties(long nativePtr,
1484             int pointerIndex, PointerProperties outPointerProperties);
1485 
nativeReadFromParcel(long nativePtr, Parcel parcel)1486     private static native long nativeReadFromParcel(long nativePtr, Parcel parcel);
nativeWriteToParcel(long nativePtr, Parcel parcel)1487     private static native void nativeWriteToParcel(long nativePtr, Parcel parcel);
1488 
nativeAxisToString(int axis)1489     private static native String nativeAxisToString(int axis);
nativeAxisFromString(String label)1490     private static native int nativeAxisFromString(String label);
1491 
1492     // -------------- @FastNative -------------------------
1493 
1494     @FastNative
nativeGetPointerId(long nativePtr, int pointerIndex)1495     private static native int nativeGetPointerId(long nativePtr, int pointerIndex);
1496     @FastNative
nativeGetToolType(long nativePtr, int pointerIndex)1497     private static native int nativeGetToolType(long nativePtr, int pointerIndex);
1498     @FastNative
nativeGetEventTimeNanos(long nativePtr, int historyPos)1499     private static native long nativeGetEventTimeNanos(long nativePtr, int historyPos);
1500     @FastNative
nativeGetRawAxisValue(long nativePtr, int axis, int pointerIndex, int historyPos)1501     private static native float nativeGetRawAxisValue(long nativePtr,
1502             int axis, int pointerIndex, int historyPos);
1503     @FastNative
nativeGetAxisValue(long nativePtr, int axis, int pointerIndex, int historyPos)1504     private static native float nativeGetAxisValue(long nativePtr,
1505             int axis, int pointerIndex, int historyPos);
1506 
1507     // -------------- @CriticalNative ----------------------
1508 
1509     @CriticalNative
nativeCopy(long destNativePtr, long sourceNativePtr, boolean keepHistory)1510     private static native long nativeCopy(long destNativePtr, long sourceNativePtr,
1511             boolean keepHistory);
1512     @CriticalNative
nativeGetDeviceId(long nativePtr)1513     private static native int nativeGetDeviceId(long nativePtr);
1514     @CriticalNative
nativeGetSource(long nativePtr)1515     private static native int nativeGetSource(long nativePtr);
1516     @CriticalNative
nativeSetSource(long nativePtr, int source)1517     private static native int nativeSetSource(long nativePtr, int source);
1518     @CriticalNative
nativeGetAction(long nativePtr)1519     private static native int nativeGetAction(long nativePtr);
1520     @CriticalNative
nativeSetAction(long nativePtr, int action)1521     private static native void nativeSetAction(long nativePtr, int action);
1522     @CriticalNative
nativeIsTouchEvent(long nativePtr)1523     private static native boolean nativeIsTouchEvent(long nativePtr);
1524     @CriticalNative
nativeGetFlags(long nativePtr)1525     private static native int nativeGetFlags(long nativePtr);
1526     @CriticalNative
nativeSetFlags(long nativePtr, int flags)1527     private static native void nativeSetFlags(long nativePtr, int flags);
1528     @CriticalNative
nativeGetEdgeFlags(long nativePtr)1529     private static native int nativeGetEdgeFlags(long nativePtr);
1530     @CriticalNative
nativeSetEdgeFlags(long nativePtr, int action)1531     private static native void nativeSetEdgeFlags(long nativePtr, int action);
1532     @CriticalNative
nativeGetMetaState(long nativePtr)1533     private static native int nativeGetMetaState(long nativePtr);
1534     @CriticalNative
nativeGetButtonState(long nativePtr)1535     private static native int nativeGetButtonState(long nativePtr);
1536     @CriticalNative
nativeSetButtonState(long nativePtr, int buttonState)1537     private static native void nativeSetButtonState(long nativePtr, int buttonState);
1538     @CriticalNative
nativeGetActionButton(long nativePtr)1539     private static native int nativeGetActionButton(long nativePtr);
1540     @CriticalNative
nativeSetActionButton(long nativePtr, int actionButton)1541     private static native void nativeSetActionButton(long nativePtr, int actionButton);
1542     @CriticalNative
nativeOffsetLocation(long nativePtr, float deltaX, float deltaY)1543     private static native void nativeOffsetLocation(long nativePtr, float deltaX, float deltaY);
1544     @CriticalNative
nativeGetXOffset(long nativePtr)1545     private static native float nativeGetXOffset(long nativePtr);
1546     @CriticalNative
nativeGetYOffset(long nativePtr)1547     private static native float nativeGetYOffset(long nativePtr);
1548     @CriticalNative
nativeGetXPrecision(long nativePtr)1549     private static native float nativeGetXPrecision(long nativePtr);
1550     @CriticalNative
nativeGetYPrecision(long nativePtr)1551     private static native float nativeGetYPrecision(long nativePtr);
1552     @CriticalNative
nativeGetDownTimeNanos(long nativePtr)1553     private static native long nativeGetDownTimeNanos(long nativePtr);
1554     @CriticalNative
nativeSetDownTimeNanos(long nativePtr, long downTime)1555     private static native void nativeSetDownTimeNanos(long nativePtr, long downTime);
1556 
1557     @CriticalNative
nativeGetPointerCount(long nativePtr)1558     private static native int nativeGetPointerCount(long nativePtr);
1559     @CriticalNative
nativeFindPointerIndex(long nativePtr, int pointerId)1560     private static native int nativeFindPointerIndex(long nativePtr, int pointerId);
1561 
1562     @CriticalNative
nativeGetHistorySize(long nativePtr)1563     private static native int nativeGetHistorySize(long nativePtr);
1564 
1565     @CriticalNative
nativeScale(long nativePtr, float scale)1566     private static native void nativeScale(long nativePtr, float scale);
1567     @CriticalNative
nativeTransform(long nativePtr, long matrix)1568     private static native void nativeTransform(long nativePtr, long matrix);
1569 
MotionEvent()1570     private MotionEvent() {
1571     }
1572 
1573     @Override
finalize()1574     protected void finalize() throws Throwable {
1575         try {
1576             if (mNativePtr != 0) {
1577                 nativeDispose(mNativePtr);
1578                 mNativePtr = 0;
1579             }
1580         } finally {
1581             super.finalize();
1582         }
1583     }
1584 
obtain()1585     static private MotionEvent obtain() {
1586         final MotionEvent ev;
1587         synchronized (gRecyclerLock) {
1588             ev = gRecyclerTop;
1589             if (ev == null) {
1590                 return new MotionEvent();
1591             }
1592             gRecyclerTop = ev.mNext;
1593             gRecyclerUsed -= 1;
1594         }
1595         ev.mNext = null;
1596         ev.prepareForReuse();
1597         return ev;
1598     }
1599 
1600     /**
1601      * Create a new MotionEvent, filling in all of the basic values that
1602      * define the motion.
1603      *
1604      * @param downTime The time (in ms) when the user originally pressed down to start
1605      * a stream of position events.  This must be obtained from {@link SystemClock#uptimeMillis()}.
1606      * @param eventTime The the time (in ms) when this specific event was generated.  This
1607      * must be obtained from {@link SystemClock#uptimeMillis()}.
1608      * @param action The kind of action being performed, such as {@link #ACTION_DOWN}.
1609      * @param pointerCount The number of pointers that will be in this event.
1610      * @param pointerProperties An array of <em>pointerCount</em> values providing
1611      * a {@link PointerProperties} property object for each pointer, which must
1612      * include the pointer identifier.
1613      * @param pointerCoords An array of <em>pointerCount</em> values providing
1614      * a {@link PointerCoords} coordinate object for each pointer.
1615      * @param metaState The state of any meta / modifier keys that were in effect when
1616      * the event was generated.
1617      * @param buttonState The state of buttons that are pressed.
1618      * @param xPrecision The precision of the X coordinate being reported.
1619      * @param yPrecision The precision of the Y coordinate being reported.
1620      * @param deviceId The id for the device that this event came from.  An id of
1621      * zero indicates that the event didn't come from a physical device; other
1622      * numbers are arbitrary and you shouldn't depend on the values.
1623      * @param edgeFlags A bitfield indicating which edges, if any, were touched by this
1624      * MotionEvent.
1625      * @param source The source of this event.
1626      * @param flags The motion event flags.
1627      */
obtain(long downTime, long eventTime, int action, int pointerCount, PointerProperties[] pointerProperties, PointerCoords[] pointerCoords, int metaState, int buttonState, float xPrecision, float yPrecision, int deviceId, int edgeFlags, int source, int flags)1628     static public MotionEvent obtain(long downTime, long eventTime,
1629             int action, int pointerCount, PointerProperties[] pointerProperties,
1630             PointerCoords[] pointerCoords, int metaState, int buttonState,
1631             float xPrecision, float yPrecision, int deviceId,
1632             int edgeFlags, int source, int flags) {
1633         MotionEvent ev = obtain();
1634         ev.mNativePtr = nativeInitialize(ev.mNativePtr,
1635                 deviceId, source, action, flags, edgeFlags, metaState, buttonState,
1636                 0, 0, xPrecision, yPrecision,
1637                 downTime * NS_PER_MS, eventTime * NS_PER_MS,
1638                 pointerCount, pointerProperties, pointerCoords);
1639         return ev;
1640     }
1641 
1642     /**
1643      * Create a new MotionEvent, filling in all of the basic values that
1644      * define the motion.
1645      *
1646      * @param downTime The time (in ms) when the user originally pressed down to start
1647      * a stream of position events.  This must be obtained from {@link SystemClock#uptimeMillis()}.
1648      * @param eventTime The the time (in ms) when this specific event was generated.  This
1649      * must be obtained from {@link SystemClock#uptimeMillis()}.
1650      * @param action The kind of action being performed, such as {@link #ACTION_DOWN}.
1651      * @param pointerCount The number of pointers that will be in this event.
1652      * @param pointerIds An array of <em>pointerCount</em> values providing
1653      * an identifier for each pointer.
1654      * @param pointerCoords An array of <em>pointerCount</em> values providing
1655      * a {@link PointerCoords} coordinate object for each pointer.
1656      * @param metaState The state of any meta / modifier keys that were in effect when
1657      * the event was generated.
1658      * @param xPrecision The precision of the X coordinate being reported.
1659      * @param yPrecision The precision of the Y coordinate being reported.
1660      * @param deviceId The id for the device that this event came from.  An id of
1661      * zero indicates that the event didn't come from a physical device; other
1662      * numbers are arbitrary and you shouldn't depend on the values.
1663      * @param edgeFlags A bitfield indicating which edges, if any, were touched by this
1664      * MotionEvent.
1665      * @param source The source of this event.
1666      * @param flags The motion event flags.
1667      *
1668      * @deprecated Use {@link #obtain(long, long, int, int, PointerProperties[], PointerCoords[], int, int, float, float, int, int, int, int)}
1669      * instead.
1670      */
1671     @Deprecated
obtain(long downTime, long eventTime, int action, int pointerCount, int[] pointerIds, PointerCoords[] pointerCoords, int metaState, float xPrecision, float yPrecision, int deviceId, int edgeFlags, int source, int flags)1672     static public MotionEvent obtain(long downTime, long eventTime,
1673             int action, int pointerCount, int[] pointerIds, PointerCoords[] pointerCoords,
1674             int metaState, float xPrecision, float yPrecision, int deviceId,
1675             int edgeFlags, int source, int flags) {
1676         synchronized (gSharedTempLock) {
1677             ensureSharedTempPointerCapacity(pointerCount);
1678             final PointerProperties[] pp = gSharedTempPointerProperties;
1679             for (int i = 0; i < pointerCount; i++) {
1680                 pp[i].clear();
1681                 pp[i].id = pointerIds[i];
1682             }
1683             return obtain(downTime, eventTime, action, pointerCount, pp,
1684                     pointerCoords, metaState, 0, xPrecision, yPrecision, deviceId,
1685                     edgeFlags, source, flags);
1686         }
1687     }
1688 
1689     /**
1690      * Create a new MotionEvent, filling in all of the basic values that
1691      * define the motion.
1692      *
1693      * @param downTime The time (in ms) when the user originally pressed down to start
1694      * a stream of position events.  This must be obtained from {@link SystemClock#uptimeMillis()}.
1695      * @param eventTime  The the time (in ms) when this specific event was generated.  This
1696      * must be obtained from {@link SystemClock#uptimeMillis()}.
1697      * @param action The kind of action being performed, such as {@link #ACTION_DOWN}.
1698      * @param x The X coordinate of this event.
1699      * @param y The Y coordinate of this event.
1700      * @param pressure The current pressure of this event.  The pressure generally
1701      * ranges from 0 (no pressure at all) to 1 (normal pressure), however
1702      * values higher than 1 may be generated depending on the calibration of
1703      * the input device.
1704      * @param size A scaled value of the approximate size of the area being pressed when
1705      * touched with the finger. The actual value in pixels corresponding to the finger
1706      * touch is normalized with a device specific range of values
1707      * and scaled to a value between 0 and 1.
1708      * @param metaState The state of any meta / modifier keys that were in effect when
1709      * the event was generated.
1710      * @param xPrecision The precision of the X coordinate being reported.
1711      * @param yPrecision The precision of the Y coordinate being reported.
1712      * @param deviceId The id for the device that this event came from.  An id of
1713      * zero indicates that the event didn't come from a physical device; other
1714      * numbers are arbitrary and you shouldn't depend on the values.
1715      * @param edgeFlags A bitfield indicating which edges, if any, were touched by this
1716      * MotionEvent.
1717      */
obtain(long downTime, long eventTime, int action, float x, float y, float pressure, float size, int metaState, float xPrecision, float yPrecision, int deviceId, int edgeFlags)1718     static public MotionEvent obtain(long downTime, long eventTime, int action,
1719             float x, float y, float pressure, float size, int metaState,
1720             float xPrecision, float yPrecision, int deviceId, int edgeFlags) {
1721         MotionEvent ev = obtain();
1722         synchronized (gSharedTempLock) {
1723             ensureSharedTempPointerCapacity(1);
1724             final PointerProperties[] pp = gSharedTempPointerProperties;
1725             pp[0].clear();
1726             pp[0].id = 0;
1727 
1728             final PointerCoords pc[] = gSharedTempPointerCoords;
1729             pc[0].clear();
1730             pc[0].x = x;
1731             pc[0].y = y;
1732             pc[0].pressure = pressure;
1733             pc[0].size = size;
1734 
1735             ev.mNativePtr = nativeInitialize(ev.mNativePtr,
1736                     deviceId, InputDevice.SOURCE_UNKNOWN, action, 0, edgeFlags, metaState, 0,
1737                     0, 0, xPrecision, yPrecision,
1738                     downTime * NS_PER_MS, eventTime * NS_PER_MS,
1739                     1, pp, pc);
1740             return ev;
1741         }
1742     }
1743 
1744     /**
1745      * Create a new MotionEvent, filling in all of the basic values that
1746      * define the motion.
1747      *
1748      * @param downTime The time (in ms) when the user originally pressed down to start
1749      * a stream of position events.  This must be obtained from {@link SystemClock#uptimeMillis()}.
1750      * @param eventTime  The the time (in ms) when this specific event was generated.  This
1751      * must be obtained from {@link SystemClock#uptimeMillis()}.
1752      * @param action The kind of action being performed, such as {@link #ACTION_DOWN}.
1753      * @param pointerCount The number of pointers that are active in this event.
1754      * @param x The X coordinate of this event.
1755      * @param y The Y coordinate of this event.
1756      * @param pressure The current pressure of this event.  The pressure generally
1757      * ranges from 0 (no pressure at all) to 1 (normal pressure), however
1758      * values higher than 1 may be generated depending on the calibration of
1759      * the input device.
1760      * @param size A scaled value of the approximate size of the area being pressed when
1761      * touched with the finger. The actual value in pixels corresponding to the finger
1762      * touch is normalized with a device specific range of values
1763      * and scaled to a value between 0 and 1.
1764      * @param metaState The state of any meta / modifier keys that were in effect when
1765      * the event was generated.
1766      * @param xPrecision The precision of the X coordinate being reported.
1767      * @param yPrecision The precision of the Y coordinate being reported.
1768      * @param deviceId The id for the device that this event came from.  An id of
1769      * zero indicates that the event didn't come from a physical device; other
1770      * numbers are arbitrary and you shouldn't depend on the values.
1771      * @param edgeFlags A bitfield indicating which edges, if any, were touched by this
1772      * MotionEvent.
1773      *
1774      * @deprecated Use {@link #obtain(long, long, int, float, float, float, float, int, float, float, int, int)}
1775      * instead.
1776      */
1777     @Deprecated
obtain(long downTime, long eventTime, int action, int pointerCount, float x, float y, float pressure, float size, int metaState, float xPrecision, float yPrecision, int deviceId, int edgeFlags)1778     static public MotionEvent obtain(long downTime, long eventTime, int action,
1779             int pointerCount, float x, float y, float pressure, float size, int metaState,
1780             float xPrecision, float yPrecision, int deviceId, int edgeFlags) {
1781         return obtain(downTime, eventTime, action, x, y, pressure, size,
1782                 metaState, xPrecision, yPrecision, deviceId, edgeFlags);
1783     }
1784 
1785     /**
1786      * Create a new MotionEvent, filling in a subset of the basic motion
1787      * values.  Those not specified here are: device id (always 0), pressure
1788      * and size (always 1), x and y precision (always 1), and edgeFlags (always 0).
1789      *
1790      * @param downTime The time (in ms) when the user originally pressed down to start
1791      * a stream of position events.  This must be obtained from {@link SystemClock#uptimeMillis()}.
1792      * @param eventTime  The the time (in ms) when this specific event was generated.  This
1793      * must be obtained from {@link SystemClock#uptimeMillis()}.
1794      * @param action The kind of action being performed, such as {@link #ACTION_DOWN}.
1795      * @param x The X coordinate of this event.
1796      * @param y The Y coordinate of this event.
1797      * @param metaState The state of any meta / modifier keys that were in effect when
1798      * the event was generated.
1799      */
obtain(long downTime, long eventTime, int action, float x, float y, int metaState)1800     static public MotionEvent obtain(long downTime, long eventTime, int action,
1801             float x, float y, int metaState) {
1802         return obtain(downTime, eventTime, action, x, y, 1.0f, 1.0f,
1803                 metaState, 1.0f, 1.0f, 0, 0);
1804     }
1805 
1806     /**
1807      * Create a new MotionEvent, copying from an existing one.
1808      */
obtain(MotionEvent other)1809     static public MotionEvent obtain(MotionEvent other) {
1810         if (other == null) {
1811             throw new IllegalArgumentException("other motion event must not be null");
1812         }
1813 
1814         MotionEvent ev = obtain();
1815         ev.mNativePtr = nativeCopy(ev.mNativePtr, other.mNativePtr, true /*keepHistory*/);
1816         return ev;
1817     }
1818 
1819     /**
1820      * Create a new MotionEvent, copying from an existing one, but not including
1821      * any historical point information.
1822      */
obtainNoHistory(MotionEvent other)1823     static public MotionEvent obtainNoHistory(MotionEvent other) {
1824         if (other == null) {
1825             throw new IllegalArgumentException("other motion event must not be null");
1826         }
1827 
1828         MotionEvent ev = obtain();
1829         ev.mNativePtr = nativeCopy(ev.mNativePtr, other.mNativePtr, false /*keepHistory*/);
1830         return ev;
1831     }
1832 
1833     /** @hide */
1834     @Override
copy()1835     public MotionEvent copy() {
1836         return obtain(this);
1837     }
1838 
1839     /**
1840      * Recycle the MotionEvent, to be re-used by a later caller.  After calling
1841      * this function you must not ever touch the event again.
1842      */
1843     @Override
recycle()1844     public final void recycle() {
1845         super.recycle();
1846 
1847         synchronized (gRecyclerLock) {
1848             if (gRecyclerUsed < MAX_RECYCLED) {
1849                 gRecyclerUsed++;
1850                 mNext = gRecyclerTop;
1851                 gRecyclerTop = this;
1852             }
1853         }
1854     }
1855 
1856     /**
1857      * Applies a scale factor to all points within this event.
1858      *
1859      * This method is used to adjust touch events to simulate different density
1860      * displays for compatibility mode.  The values returned by {@link #getRawX()},
1861      * {@link #getRawY()}, {@link #getXPrecision()} and {@link #getYPrecision()}
1862      * are also affected by the scale factor.
1863      *
1864      * @param scale The scale factor to apply.
1865      * @hide
1866      */
scale(float scale)1867     public final void scale(float scale) {
1868         if (scale != 1.0f) {
1869             nativeScale(mNativePtr, scale);
1870         }
1871     }
1872 
1873     /** {@inheritDoc} */
1874     @Override
getDeviceId()1875     public final int getDeviceId() {
1876         return nativeGetDeviceId(mNativePtr);
1877     }
1878 
1879     /** {@inheritDoc} */
1880     @Override
getSource()1881     public final int getSource() {
1882         return nativeGetSource(mNativePtr);
1883     }
1884 
1885     /** {@inheritDoc} */
1886     @Override
setSource(int source)1887     public final void setSource(int source) {
1888         nativeSetSource(mNativePtr, source);
1889     }
1890 
1891     /**
1892      * Return the kind of action being performed.
1893      * Consider using {@link #getActionMasked} and {@link #getActionIndex} to retrieve
1894      * the separate masked action and pointer index.
1895      * @return The action, such as {@link #ACTION_DOWN} or
1896      * the combination of {@link #ACTION_POINTER_DOWN} with a shifted pointer index.
1897      */
getAction()1898     public final int getAction() {
1899         return nativeGetAction(mNativePtr);
1900     }
1901 
1902     /**
1903      * Return the masked action being performed, without pointer index information.
1904      * Use {@link #getActionIndex} to return the index associated with pointer actions.
1905      * @return The action, such as {@link #ACTION_DOWN} or {@link #ACTION_POINTER_DOWN}.
1906      */
getActionMasked()1907     public final int getActionMasked() {
1908         return nativeGetAction(mNativePtr) & ACTION_MASK;
1909     }
1910 
1911     /**
1912      * For {@link #ACTION_POINTER_DOWN} or {@link #ACTION_POINTER_UP}
1913      * as returned by {@link #getActionMasked}, this returns the associated
1914      * pointer index.
1915      * The index may be used with {@link #getPointerId(int)},
1916      * {@link #getX(int)}, {@link #getY(int)}, {@link #getPressure(int)},
1917      * and {@link #getSize(int)} to get information about the pointer that has
1918      * gone down or up.
1919      * @return The index associated with the action.
1920      */
getActionIndex()1921     public final int getActionIndex() {
1922         return (nativeGetAction(mNativePtr) & ACTION_POINTER_INDEX_MASK)
1923                 >> ACTION_POINTER_INDEX_SHIFT;
1924     }
1925 
1926     /**
1927      * Returns true if this motion event is a touch event.
1928      * <p>
1929      * Specifically excludes pointer events with action {@link #ACTION_HOVER_MOVE},
1930      * {@link #ACTION_HOVER_ENTER}, {@link #ACTION_HOVER_EXIT}, or {@link #ACTION_SCROLL}
1931      * because they are not actually touch events (the pointer is not down).
1932      * </p>
1933      * @return True if this motion event is a touch event.
1934      * @hide
1935      */
isTouchEvent()1936     public final boolean isTouchEvent() {
1937         return nativeIsTouchEvent(mNativePtr);
1938     }
1939 
1940     /**
1941      * Gets the motion event flags.
1942      *
1943      * @see #FLAG_WINDOW_IS_OBSCURED
1944      */
getFlags()1945     public final int getFlags() {
1946         return nativeGetFlags(mNativePtr);
1947     }
1948 
1949     /** @hide */
1950     @Override
isTainted()1951     public final boolean isTainted() {
1952         final int flags = getFlags();
1953         return (flags & FLAG_TAINTED) != 0;
1954     }
1955 
1956     /** @hide */
1957     @Override
setTainted(boolean tainted)1958     public final void setTainted(boolean tainted) {
1959         final int flags = getFlags();
1960         nativeSetFlags(mNativePtr, tainted ? flags | FLAG_TAINTED : flags & ~FLAG_TAINTED);
1961     }
1962 
1963     /** @hide */
isTargetAccessibilityFocus()1964     public final boolean isTargetAccessibilityFocus() {
1965         final int flags = getFlags();
1966         return (flags & FLAG_TARGET_ACCESSIBILITY_FOCUS) != 0;
1967     }
1968 
1969     /** @hide */
setTargetAccessibilityFocus(boolean targetsFocus)1970     public final void setTargetAccessibilityFocus(boolean targetsFocus) {
1971         final int flags = getFlags();
1972         nativeSetFlags(mNativePtr, targetsFocus
1973                 ? flags | FLAG_TARGET_ACCESSIBILITY_FOCUS
1974                 : flags & ~FLAG_TARGET_ACCESSIBILITY_FOCUS);
1975     }
1976 
1977     /** @hide */
isHoverExitPending()1978     public final boolean isHoverExitPending() {
1979         final int flags = getFlags();
1980         return (flags & FLAG_HOVER_EXIT_PENDING) != 0;
1981     }
1982 
1983     /** @hide */
setHoverExitPending(boolean hoverExitPending)1984     public void setHoverExitPending(boolean hoverExitPending) {
1985         final int flags = getFlags();
1986         nativeSetFlags(mNativePtr, hoverExitPending
1987                 ? flags | FLAG_HOVER_EXIT_PENDING
1988                 : flags & ~FLAG_HOVER_EXIT_PENDING);
1989     }
1990 
1991     /**
1992      * Returns the time (in ms) when the user originally pressed down to start
1993      * a stream of position events.
1994      */
getDownTime()1995     public final long getDownTime() {
1996         return nativeGetDownTimeNanos(mNativePtr) / NS_PER_MS;
1997     }
1998 
1999     /**
2000      * Sets the time (in ms) when the user originally pressed down to start
2001      * a stream of position events.
2002      *
2003      * @hide
2004      */
setDownTime(long downTime)2005     public final void setDownTime(long downTime) {
2006         nativeSetDownTimeNanos(mNativePtr, downTime * NS_PER_MS);
2007     }
2008 
2009     /**
2010      * Retrieve the time this event occurred,
2011      * in the {@link android.os.SystemClock#uptimeMillis} time base.
2012      *
2013      * @return Returns the time this event occurred,
2014      * in the {@link android.os.SystemClock#uptimeMillis} time base.
2015      */
2016     @Override
getEventTime()2017     public final long getEventTime() {
2018         return nativeGetEventTimeNanos(mNativePtr, HISTORY_CURRENT) / NS_PER_MS;
2019     }
2020 
2021     /**
2022      * Retrieve the time this event occurred,
2023      * in the {@link android.os.SystemClock#uptimeMillis} time base but with
2024      * nanosecond precision.
2025      * <p>
2026      * The value is in nanosecond precision but it may not have nanosecond accuracy.
2027      * </p>
2028      *
2029      * @return Returns the time this event occurred,
2030      * in the {@link android.os.SystemClock#uptimeMillis} time base but with
2031      * nanosecond precision.
2032      *
2033      * @hide
2034      */
2035     @Override
getEventTimeNano()2036     public final long getEventTimeNano() {
2037         return nativeGetEventTimeNanos(mNativePtr, HISTORY_CURRENT);
2038     }
2039 
2040     /**
2041      * {@link #getX(int)} for the first pointer index (may be an
2042      * arbitrary pointer identifier).
2043      *
2044      * @see #AXIS_X
2045      */
getX()2046     public final float getX() {
2047         return nativeGetAxisValue(mNativePtr, AXIS_X, 0, HISTORY_CURRENT);
2048     }
2049 
2050     /**
2051      * {@link #getY(int)} for the first pointer index (may be an
2052      * arbitrary pointer identifier).
2053      *
2054      * @see #AXIS_Y
2055      */
getY()2056     public final float getY() {
2057         return nativeGetAxisValue(mNativePtr, AXIS_Y, 0, HISTORY_CURRENT);
2058     }
2059 
2060     /**
2061      * {@link #getPressure(int)} for the first pointer index (may be an
2062      * arbitrary pointer identifier).
2063      *
2064      * @see #AXIS_PRESSURE
2065      */
getPressure()2066     public final float getPressure() {
2067         return nativeGetAxisValue(mNativePtr, AXIS_PRESSURE, 0, HISTORY_CURRENT);
2068     }
2069 
2070     /**
2071      * {@link #getSize(int)} for the first pointer index (may be an
2072      * arbitrary pointer identifier).
2073      *
2074      * @see #AXIS_SIZE
2075      */
getSize()2076     public final float getSize() {
2077         return nativeGetAxisValue(mNativePtr, AXIS_SIZE, 0, HISTORY_CURRENT);
2078     }
2079 
2080     /**
2081      * {@link #getTouchMajor(int)} for the first pointer index (may be an
2082      * arbitrary pointer identifier).
2083      *
2084      * @see #AXIS_TOUCH_MAJOR
2085      */
getTouchMajor()2086     public final float getTouchMajor() {
2087         return nativeGetAxisValue(mNativePtr, AXIS_TOUCH_MAJOR, 0, HISTORY_CURRENT);
2088     }
2089 
2090     /**
2091      * {@link #getTouchMinor(int)} for the first pointer index (may be an
2092      * arbitrary pointer identifier).
2093      *
2094      * @see #AXIS_TOUCH_MINOR
2095      */
getTouchMinor()2096     public final float getTouchMinor() {
2097         return nativeGetAxisValue(mNativePtr, AXIS_TOUCH_MINOR, 0, HISTORY_CURRENT);
2098     }
2099 
2100     /**
2101      * {@link #getToolMajor(int)} for the first pointer index (may be an
2102      * arbitrary pointer identifier).
2103      *
2104      * @see #AXIS_TOOL_MAJOR
2105      */
getToolMajor()2106     public final float getToolMajor() {
2107         return nativeGetAxisValue(mNativePtr, AXIS_TOOL_MAJOR, 0, HISTORY_CURRENT);
2108     }
2109 
2110     /**
2111      * {@link #getToolMinor(int)} for the first pointer index (may be an
2112      * arbitrary pointer identifier).
2113      *
2114      * @see #AXIS_TOOL_MINOR
2115      */
getToolMinor()2116     public final float getToolMinor() {
2117         return nativeGetAxisValue(mNativePtr, AXIS_TOOL_MINOR, 0, HISTORY_CURRENT);
2118     }
2119 
2120     /**
2121      * {@link #getOrientation(int)} for the first pointer index (may be an
2122      * arbitrary pointer identifier).
2123      *
2124      * @see #AXIS_ORIENTATION
2125      */
getOrientation()2126     public final float getOrientation() {
2127         return nativeGetAxisValue(mNativePtr, AXIS_ORIENTATION, 0, HISTORY_CURRENT);
2128     }
2129 
2130     /**
2131      * {@link #getAxisValue(int)} for the first pointer index (may be an
2132      * arbitrary pointer identifier).
2133      *
2134      * @param axis The axis identifier for the axis value to retrieve.
2135      *
2136      * @see #AXIS_X
2137      * @see #AXIS_Y
2138      */
getAxisValue(int axis)2139     public final float getAxisValue(int axis) {
2140         return nativeGetAxisValue(mNativePtr, axis, 0, HISTORY_CURRENT);
2141     }
2142 
2143     /**
2144      * The number of pointers of data contained in this event.  Always
2145      * >= 1.
2146      */
getPointerCount()2147     public final int getPointerCount() {
2148         return nativeGetPointerCount(mNativePtr);
2149     }
2150 
2151     /**
2152      * Return the pointer identifier associated with a particular pointer
2153      * data index in this event.  The identifier tells you the actual pointer
2154      * number associated with the data, accounting for individual pointers
2155      * going up and down since the start of the current gesture.
2156      * @param pointerIndex Raw index of pointer to retrieve.  Value may be from 0
2157      * (the first pointer that is down) to {@link #getPointerCount()}-1.
2158      */
getPointerId(int pointerIndex)2159     public final int getPointerId(int pointerIndex) {
2160         return nativeGetPointerId(mNativePtr, pointerIndex);
2161     }
2162 
2163     /**
2164      * Gets the tool type of a pointer for the given pointer index.
2165      * The tool type indicates the type of tool used to make contact such
2166      * as a finger or stylus, if known.
2167      *
2168      * @param pointerIndex Raw index of pointer to retrieve.  Value may be from 0
2169      * (the first pointer that is down) to {@link #getPointerCount()}-1.
2170      * @return The tool type of the pointer.
2171      *
2172      * @see #TOOL_TYPE_UNKNOWN
2173      * @see #TOOL_TYPE_FINGER
2174      * @see #TOOL_TYPE_STYLUS
2175      * @see #TOOL_TYPE_MOUSE
2176      */
getToolType(int pointerIndex)2177     public final int getToolType(int pointerIndex) {
2178         return nativeGetToolType(mNativePtr, pointerIndex);
2179     }
2180 
2181     /**
2182      * Given a pointer identifier, find the index of its data in the event.
2183      *
2184      * @param pointerId The identifier of the pointer to be found.
2185      * @return Returns either the index of the pointer (for use with
2186      * {@link #getX(int)} et al.), or -1 if there is no data available for
2187      * that pointer identifier.
2188      */
findPointerIndex(int pointerId)2189     public final int findPointerIndex(int pointerId) {
2190         return nativeFindPointerIndex(mNativePtr, pointerId);
2191     }
2192 
2193     /**
2194      * Returns the X coordinate of this event for the given pointer
2195      * <em>index</em> (use {@link #getPointerId(int)} to find the pointer
2196      * identifier for this index).
2197      * Whole numbers are pixels; the
2198      * value may have a fraction for input devices that are sub-pixel precise.
2199      * @param pointerIndex Raw index of pointer to retrieve.  Value may be from 0
2200      * (the first pointer that is down) to {@link #getPointerCount()}-1.
2201      *
2202      * @see #AXIS_X
2203      */
getX(int pointerIndex)2204     public final float getX(int pointerIndex) {
2205         return nativeGetAxisValue(mNativePtr, AXIS_X, pointerIndex, HISTORY_CURRENT);
2206     }
2207 
2208     /**
2209      * Returns the Y coordinate of this event for the given pointer
2210      * <em>index</em> (use {@link #getPointerId(int)} to find the pointer
2211      * identifier for this index).
2212      * Whole numbers are pixels; the
2213      * value may have a fraction for input devices that are sub-pixel precise.
2214      * @param pointerIndex Raw index of pointer to retrieve.  Value may be from 0
2215      * (the first pointer that is down) to {@link #getPointerCount()}-1.
2216      *
2217      * @see #AXIS_Y
2218      */
getY(int pointerIndex)2219     public final float getY(int pointerIndex) {
2220         return nativeGetAxisValue(mNativePtr, AXIS_Y, pointerIndex, HISTORY_CURRENT);
2221     }
2222 
2223     /**
2224      * Returns the current pressure of this event for the given pointer
2225      * <em>index</em> (use {@link #getPointerId(int)} to find the pointer
2226      * identifier for this index).
2227      * The pressure generally
2228      * ranges from 0 (no pressure at all) to 1 (normal pressure), however
2229      * values higher than 1 may be generated depending on the calibration of
2230      * the input device.
2231      * @param pointerIndex Raw index of pointer to retrieve.  Value may be from 0
2232      * (the first pointer that is down) to {@link #getPointerCount()}-1.
2233      *
2234      * @see #AXIS_PRESSURE
2235      */
getPressure(int pointerIndex)2236     public final float getPressure(int pointerIndex) {
2237         return nativeGetAxisValue(mNativePtr, AXIS_PRESSURE, pointerIndex, HISTORY_CURRENT);
2238     }
2239 
2240     /**
2241      * Returns a scaled value of the approximate size for the given pointer
2242      * <em>index</em> (use {@link #getPointerId(int)} to find the pointer
2243      * identifier for this index).
2244      * This represents some approximation of the area of the screen being
2245      * pressed; the actual value in pixels corresponding to the
2246      * touch is normalized with the device specific range of values
2247      * and scaled to a value between 0 and 1. The value of size can be used to
2248      * determine fat touch events.
2249      * @param pointerIndex Raw index of pointer to retrieve.  Value may be from 0
2250      * (the first pointer that is down) to {@link #getPointerCount()}-1.
2251      *
2252      * @see #AXIS_SIZE
2253      */
getSize(int pointerIndex)2254     public final float getSize(int pointerIndex) {
2255         return nativeGetAxisValue(mNativePtr, AXIS_SIZE, pointerIndex, HISTORY_CURRENT);
2256     }
2257 
2258     /**
2259      * Returns the length of the major axis of an ellipse that describes the touch
2260      * area at the point of contact for the given pointer
2261      * <em>index</em> (use {@link #getPointerId(int)} to find the pointer
2262      * identifier for this index).
2263      * @param pointerIndex Raw index of pointer to retrieve.  Value may be from 0
2264      * (the first pointer that is down) to {@link #getPointerCount()}-1.
2265      *
2266      * @see #AXIS_TOUCH_MAJOR
2267      */
getTouchMajor(int pointerIndex)2268     public final float getTouchMajor(int pointerIndex) {
2269         return nativeGetAxisValue(mNativePtr, AXIS_TOUCH_MAJOR, pointerIndex, HISTORY_CURRENT);
2270     }
2271 
2272     /**
2273      * Returns the length of the minor axis of an ellipse that describes the touch
2274      * area at the point of contact for the given pointer
2275      * <em>index</em> (use {@link #getPointerId(int)} to find the pointer
2276      * identifier for this index).
2277      * @param pointerIndex Raw index of pointer to retrieve.  Value may be from 0
2278      * (the first pointer that is down) to {@link #getPointerCount()}-1.
2279      *
2280      * @see #AXIS_TOUCH_MINOR
2281      */
getTouchMinor(int pointerIndex)2282     public final float getTouchMinor(int pointerIndex) {
2283         return nativeGetAxisValue(mNativePtr, AXIS_TOUCH_MINOR, pointerIndex, HISTORY_CURRENT);
2284     }
2285 
2286     /**
2287      * Returns the length of the major axis of an ellipse that describes the size of
2288      * the approaching tool for the given pointer
2289      * <em>index</em> (use {@link #getPointerId(int)} to find the pointer
2290      * identifier for this index).
2291      * The tool area represents the estimated size of the finger or pen that is
2292      * touching the device independent of its actual touch area at the point of contact.
2293      * @param pointerIndex Raw index of pointer to retrieve.  Value may be from 0
2294      * (the first pointer that is down) to {@link #getPointerCount()}-1.
2295      *
2296      * @see #AXIS_TOOL_MAJOR
2297      */
getToolMajor(int pointerIndex)2298     public final float getToolMajor(int pointerIndex) {
2299         return nativeGetAxisValue(mNativePtr, AXIS_TOOL_MAJOR, pointerIndex, HISTORY_CURRENT);
2300     }
2301 
2302     /**
2303      * Returns the length of the minor axis of an ellipse that describes the size of
2304      * the approaching tool for the given pointer
2305      * <em>index</em> (use {@link #getPointerId(int)} to find the pointer
2306      * identifier for this index).
2307      * The tool area represents the estimated size of the finger or pen that is
2308      * touching the device independent of its actual touch area at the point of contact.
2309      * @param pointerIndex Raw index of pointer to retrieve.  Value may be from 0
2310      * (the first pointer that is down) to {@link #getPointerCount()}-1.
2311      *
2312      * @see #AXIS_TOOL_MINOR
2313      */
getToolMinor(int pointerIndex)2314     public final float getToolMinor(int pointerIndex) {
2315         return nativeGetAxisValue(mNativePtr, AXIS_TOOL_MINOR, pointerIndex, HISTORY_CURRENT);
2316     }
2317 
2318     /**
2319      * Returns the orientation of the touch area and tool area in radians clockwise from vertical
2320      * for the given pointer <em>index</em> (use {@link #getPointerId(int)} to find the pointer
2321      * identifier for this index).
2322      * An angle of 0 radians indicates that the major axis of contact is oriented
2323      * upwards, is perfectly circular or is of unknown orientation.  A positive angle
2324      * indicates that the major axis of contact is oriented to the right.  A negative angle
2325      * indicates that the major axis of contact is oriented to the left.
2326      * The full range is from -PI/2 radians (finger pointing fully left) to PI/2 radians
2327      * (finger pointing fully right).
2328      * @param pointerIndex Raw index of pointer to retrieve.  Value may be from 0
2329      * (the first pointer that is down) to {@link #getPointerCount()}-1.
2330      *
2331      * @see #AXIS_ORIENTATION
2332      */
getOrientation(int pointerIndex)2333     public final float getOrientation(int pointerIndex) {
2334         return nativeGetAxisValue(mNativePtr, AXIS_ORIENTATION, pointerIndex, HISTORY_CURRENT);
2335     }
2336 
2337     /**
2338      * Returns the value of the requested axis for the given pointer <em>index</em>
2339      * (use {@link #getPointerId(int)} to find the pointer identifier for this index).
2340      *
2341      * @param axis The axis identifier for the axis value to retrieve.
2342      * @param pointerIndex Raw index of pointer to retrieve.  Value may be from 0
2343      * (the first pointer that is down) to {@link #getPointerCount()}-1.
2344      * @return The value of the axis, or 0 if the axis is not available.
2345      *
2346      * @see #AXIS_X
2347      * @see #AXIS_Y
2348      */
getAxisValue(int axis, int pointerIndex)2349     public final float getAxisValue(int axis, int pointerIndex) {
2350         return nativeGetAxisValue(mNativePtr, axis, pointerIndex, HISTORY_CURRENT);
2351     }
2352 
2353     /**
2354      * Populates a {@link PointerCoords} object with pointer coordinate data for
2355      * the specified pointer index.
2356      *
2357      * @param pointerIndex Raw index of pointer to retrieve.  Value may be from 0
2358      * (the first pointer that is down) to {@link #getPointerCount()}-1.
2359      * @param outPointerCoords The pointer coordinate object to populate.
2360      *
2361      * @see PointerCoords
2362      */
getPointerCoords(int pointerIndex, PointerCoords outPointerCoords)2363     public final void getPointerCoords(int pointerIndex, PointerCoords outPointerCoords) {
2364         nativeGetPointerCoords(mNativePtr, pointerIndex, HISTORY_CURRENT, outPointerCoords);
2365     }
2366 
2367     /**
2368      * Populates a {@link PointerProperties} object with pointer properties for
2369      * the specified pointer index.
2370      *
2371      * @param pointerIndex Raw index of pointer to retrieve.  Value may be from 0
2372      * (the first pointer that is down) to {@link #getPointerCount()}-1.
2373      * @param outPointerProperties The pointer properties object to populate.
2374      *
2375      * @see PointerProperties
2376      */
getPointerProperties(int pointerIndex, PointerProperties outPointerProperties)2377     public final void getPointerProperties(int pointerIndex,
2378             PointerProperties outPointerProperties) {
2379         nativeGetPointerProperties(mNativePtr, pointerIndex, outPointerProperties);
2380     }
2381 
2382     /**
2383      * Returns the state of any meta / modifier keys that were in effect when
2384      * the event was generated.  This is the same values as those
2385      * returned by {@link KeyEvent#getMetaState() KeyEvent.getMetaState}.
2386      *
2387      * @return an integer in which each bit set to 1 represents a pressed
2388      *         meta key
2389      *
2390      * @see KeyEvent#getMetaState()
2391      */
getMetaState()2392     public final int getMetaState() {
2393         return nativeGetMetaState(mNativePtr);
2394     }
2395 
2396     /**
2397      * Gets the state of all buttons that are pressed such as a mouse or stylus button.
2398      *
2399      * @return The button state.
2400      *
2401      * @see #BUTTON_PRIMARY
2402      * @see #BUTTON_SECONDARY
2403      * @see #BUTTON_TERTIARY
2404      * @see #BUTTON_FORWARD
2405      * @see #BUTTON_BACK
2406      * @see #BUTTON_STYLUS_PRIMARY
2407      * @see #BUTTON_STYLUS_SECONDARY
2408      */
getButtonState()2409     public final int getButtonState() {
2410         return nativeGetButtonState(mNativePtr);
2411     }
2412 
2413     /**
2414      * Sets the bitfield indicating which buttons are pressed.
2415      *
2416      * @see #getButtonState()
2417      * @hide
2418      */
2419     @TestApi
setButtonState(int buttonState)2420     public final void setButtonState(int buttonState) {
2421         nativeSetButtonState(mNativePtr, buttonState);
2422     }
2423 
2424     /**
2425      * Gets which button has been modified during a press or release action.
2426      *
2427      * For actions other than {@link #ACTION_BUTTON_PRESS} and {@link #ACTION_BUTTON_RELEASE}
2428      * the returned value is undefined.
2429      *
2430      * @see #getButtonState()
2431      */
getActionButton()2432     public final int getActionButton() {
2433         return nativeGetActionButton(mNativePtr);
2434     }
2435 
2436     /**
2437      * Sets the action button for the event.
2438      *
2439      * @see #getActionButton()
2440      * @hide
2441      */
2442     @TestApi
setActionButton(int button)2443     public final void setActionButton(int button) {
2444         nativeSetActionButton(mNativePtr, button);
2445     }
2446 
2447     /**
2448      * Returns the original raw X coordinate of this event.  For touch
2449      * events on the screen, this is the original location of the event
2450      * on the screen, before it had been adjusted for the containing window
2451      * and views.
2452      *
2453      * @see #getX(int)
2454      * @see #AXIS_X
2455      */
getRawX()2456     public final float getRawX() {
2457         return nativeGetRawAxisValue(mNativePtr, AXIS_X, 0, HISTORY_CURRENT);
2458     }
2459 
2460     /**
2461      * Returns the original raw Y coordinate of this event.  For touch
2462      * events on the screen, this is the original location of the event
2463      * on the screen, before it had been adjusted for the containing window
2464      * and views.
2465      *
2466      * @see #getY(int)
2467      * @see #AXIS_Y
2468      */
getRawY()2469     public final float getRawY() {
2470         return nativeGetRawAxisValue(mNativePtr, AXIS_Y, 0, HISTORY_CURRENT);
2471     }
2472 
2473     /**
2474      * Return the precision of the X coordinates being reported.  You can
2475      * multiply this number with {@link #getX} to find the actual hardware
2476      * value of the X coordinate.
2477      * @return Returns the precision of X coordinates being reported.
2478      *
2479      * @see #AXIS_X
2480      */
getXPrecision()2481     public final float getXPrecision() {
2482         return nativeGetXPrecision(mNativePtr);
2483     }
2484 
2485     /**
2486      * Return the precision of the Y coordinates being reported.  You can
2487      * multiply this number with {@link #getY} to find the actual hardware
2488      * value of the Y coordinate.
2489      * @return Returns the precision of Y coordinates being reported.
2490      *
2491      * @see #AXIS_Y
2492      */
getYPrecision()2493     public final float getYPrecision() {
2494         return nativeGetYPrecision(mNativePtr);
2495     }
2496 
2497     /**
2498      * Returns the number of historical points in this event.  These are
2499      * movements that have occurred between this event and the previous event.
2500      * This only applies to ACTION_MOVE events -- all other actions will have
2501      * a size of 0.
2502      *
2503      * @return Returns the number of historical points in the event.
2504      */
getHistorySize()2505     public final int getHistorySize() {
2506         return nativeGetHistorySize(mNativePtr);
2507     }
2508 
2509     /**
2510      * Returns the time that a historical movement occurred between this event
2511      * and the previous event, in the {@link android.os.SystemClock#uptimeMillis} time base.
2512      * <p>
2513      * This only applies to ACTION_MOVE events.
2514      * </p>
2515      *
2516      * @param pos Which historical value to return; must be less than
2517      * {@link #getHistorySize}
2518      * @return Returns the time that a historical movement occurred between this
2519      * event and the previous event,
2520      * in the {@link android.os.SystemClock#uptimeMillis} time base.
2521      *
2522      * @see #getHistorySize
2523      * @see #getEventTime
2524      */
getHistoricalEventTime(int pos)2525     public final long getHistoricalEventTime(int pos) {
2526         return nativeGetEventTimeNanos(mNativePtr, pos) / NS_PER_MS;
2527     }
2528 
2529     /**
2530      * Returns the time that a historical movement occurred between this event
2531      * and the previous event, in the {@link android.os.SystemClock#uptimeMillis} time base
2532      * but with nanosecond (instead of millisecond) precision.
2533      * <p>
2534      * This only applies to ACTION_MOVE events.
2535      * </p><p>
2536      * The value is in nanosecond precision but it may not have nanosecond accuracy.
2537      * </p>
2538      *
2539      * @param pos Which historical value to return; must be less than
2540      * {@link #getHistorySize}
2541      * @return Returns the time that a historical movement occurred between this
2542      * event and the previous event,
2543      * in the {@link android.os.SystemClock#uptimeMillis} time base but with
2544      * nanosecond (instead of millisecond) precision.
2545      *
2546      * @see #getHistorySize
2547      * @see #getEventTime
2548      *
2549      * @hide
2550      */
getHistoricalEventTimeNano(int pos)2551     public final long getHistoricalEventTimeNano(int pos) {
2552         return nativeGetEventTimeNanos(mNativePtr, pos);
2553     }
2554 
2555     /**
2556      * {@link #getHistoricalX(int, int)} for the first pointer index (may be an
2557      * arbitrary pointer identifier).
2558      *
2559      * @param pos Which historical value to return; must be less than
2560      * {@link #getHistorySize}
2561      *
2562      * @see #getHistorySize
2563      * @see #getX()
2564      * @see #AXIS_X
2565      */
getHistoricalX(int pos)2566     public final float getHistoricalX(int pos) {
2567         return nativeGetAxisValue(mNativePtr, AXIS_X, 0, pos);
2568     }
2569 
2570     /**
2571      * {@link #getHistoricalY(int, int)} for the first pointer index (may be an
2572      * arbitrary pointer identifier).
2573      *
2574      * @param pos Which historical value to return; must be less than
2575      * {@link #getHistorySize}
2576      *
2577      * @see #getHistorySize
2578      * @see #getY()
2579      * @see #AXIS_Y
2580      */
getHistoricalY(int pos)2581     public final float getHistoricalY(int pos) {
2582         return nativeGetAxisValue(mNativePtr, AXIS_Y, 0, pos);
2583     }
2584 
2585     /**
2586      * {@link #getHistoricalPressure(int, int)} for the first pointer index (may be an
2587      * arbitrary pointer identifier).
2588      *
2589      * @param pos Which historical value to return; must be less than
2590      * {@link #getHistorySize}
2591      *
2592      * @see #getHistorySize
2593      * @see #getPressure()
2594      * @see #AXIS_PRESSURE
2595      */
getHistoricalPressure(int pos)2596     public final float getHistoricalPressure(int pos) {
2597         return nativeGetAxisValue(mNativePtr, AXIS_PRESSURE, 0, pos);
2598     }
2599 
2600     /**
2601      * {@link #getHistoricalSize(int, int)} for the first pointer index (may be an
2602      * arbitrary pointer identifier).
2603      *
2604      * @param pos Which historical value to return; must be less than
2605      * {@link #getHistorySize}
2606      *
2607      * @see #getHistorySize
2608      * @see #getSize()
2609      * @see #AXIS_SIZE
2610      */
getHistoricalSize(int pos)2611     public final float getHistoricalSize(int pos) {
2612         return nativeGetAxisValue(mNativePtr, AXIS_SIZE, 0, pos);
2613     }
2614 
2615     /**
2616      * {@link #getHistoricalTouchMajor(int, int)} for the first pointer index (may be an
2617      * arbitrary pointer identifier).
2618      *
2619      * @param pos Which historical value to return; must be less than
2620      * {@link #getHistorySize}
2621      *
2622      * @see #getHistorySize
2623      * @see #getTouchMajor()
2624      * @see #AXIS_TOUCH_MAJOR
2625      */
getHistoricalTouchMajor(int pos)2626     public final float getHistoricalTouchMajor(int pos) {
2627         return nativeGetAxisValue(mNativePtr, AXIS_TOUCH_MAJOR, 0, pos);
2628     }
2629 
2630     /**
2631      * {@link #getHistoricalTouchMinor(int, int)} for the first pointer index (may be an
2632      * arbitrary pointer identifier).
2633      *
2634      * @param pos Which historical value to return; must be less than
2635      * {@link #getHistorySize}
2636      *
2637      * @see #getHistorySize
2638      * @see #getTouchMinor()
2639      * @see #AXIS_TOUCH_MINOR
2640      */
getHistoricalTouchMinor(int pos)2641     public final float getHistoricalTouchMinor(int pos) {
2642         return nativeGetAxisValue(mNativePtr, AXIS_TOUCH_MINOR, 0, pos);
2643     }
2644 
2645     /**
2646      * {@link #getHistoricalToolMajor(int, int)} for the first pointer index (may be an
2647      * arbitrary pointer identifier).
2648      *
2649      * @param pos Which historical value to return; must be less than
2650      * {@link #getHistorySize}
2651      *
2652      * @see #getHistorySize
2653      * @see #getToolMajor()
2654      * @see #AXIS_TOOL_MAJOR
2655      */
getHistoricalToolMajor(int pos)2656     public final float getHistoricalToolMajor(int pos) {
2657         return nativeGetAxisValue(mNativePtr, AXIS_TOOL_MAJOR, 0, pos);
2658     }
2659 
2660     /**
2661      * {@link #getHistoricalToolMinor(int, int)} for the first pointer index (may be an
2662      * arbitrary pointer identifier).
2663      *
2664      * @param pos Which historical value to return; must be less than
2665      * {@link #getHistorySize}
2666      *
2667      * @see #getHistorySize
2668      * @see #getToolMinor()
2669      * @see #AXIS_TOOL_MINOR
2670      */
getHistoricalToolMinor(int pos)2671     public final float getHistoricalToolMinor(int pos) {
2672         return nativeGetAxisValue(mNativePtr, AXIS_TOOL_MINOR, 0, pos);
2673     }
2674 
2675     /**
2676      * {@link #getHistoricalOrientation(int, int)} for the first pointer index (may be an
2677      * arbitrary pointer identifier).
2678      *
2679      * @param pos Which historical value to return; must be less than
2680      * {@link #getHistorySize}
2681      *
2682      * @see #getHistorySize
2683      * @see #getOrientation()
2684      * @see #AXIS_ORIENTATION
2685      */
getHistoricalOrientation(int pos)2686     public final float getHistoricalOrientation(int pos) {
2687         return nativeGetAxisValue(mNativePtr, AXIS_ORIENTATION, 0, pos);
2688     }
2689 
2690     /**
2691      * {@link #getHistoricalAxisValue(int, int, int)} for the first pointer index (may be an
2692      * arbitrary pointer identifier).
2693      *
2694      * @param axis The axis identifier for the axis value to retrieve.
2695      * @param pos Which historical value to return; must be less than
2696      * {@link #getHistorySize}
2697      *
2698      * @see #getHistorySize
2699      * @see #getAxisValue(int)
2700      * @see #AXIS_X
2701      * @see #AXIS_Y
2702      */
getHistoricalAxisValue(int axis, int pos)2703     public final float getHistoricalAxisValue(int axis, int pos) {
2704         return nativeGetAxisValue(mNativePtr, axis, 0, pos);
2705     }
2706 
2707     /**
2708      * Returns a historical X coordinate, as per {@link #getX(int)}, that
2709      * occurred between this event and the previous event for the given pointer.
2710      * Only applies to ACTION_MOVE events.
2711      *
2712      * @param pointerIndex Raw index of pointer to retrieve.  Value may be from 0
2713      * (the first pointer that is down) to {@link #getPointerCount()}-1.
2714      * @param pos Which historical value to return; must be less than
2715      * {@link #getHistorySize}
2716      *
2717      * @see #getHistorySize
2718      * @see #getX(int)
2719      * @see #AXIS_X
2720      */
getHistoricalX(int pointerIndex, int pos)2721     public final float getHistoricalX(int pointerIndex, int pos) {
2722         return nativeGetAxisValue(mNativePtr, AXIS_X, pointerIndex, pos);
2723     }
2724 
2725     /**
2726      * Returns a historical Y coordinate, as per {@link #getY(int)}, that
2727      * occurred between this event and the previous event for the given pointer.
2728      * Only applies to ACTION_MOVE events.
2729      *
2730      * @param pointerIndex Raw index of pointer to retrieve.  Value may be from 0
2731      * (the first pointer that is down) to {@link #getPointerCount()}-1.
2732      * @param pos Which historical value to return; must be less than
2733      * {@link #getHistorySize}
2734      *
2735      * @see #getHistorySize
2736      * @see #getY(int)
2737      * @see #AXIS_Y
2738      */
getHistoricalY(int pointerIndex, int pos)2739     public final float getHistoricalY(int pointerIndex, int pos) {
2740         return nativeGetAxisValue(mNativePtr, AXIS_Y, pointerIndex, pos);
2741     }
2742 
2743     /**
2744      * Returns a historical pressure coordinate, as per {@link #getPressure(int)},
2745      * that occurred between this event and the previous event for the given
2746      * pointer.  Only applies to ACTION_MOVE events.
2747      *
2748      * @param pointerIndex Raw index of pointer to retrieve.  Value may be from 0
2749      * (the first pointer that is down) to {@link #getPointerCount()}-1.
2750      * @param pos Which historical value to return; must be less than
2751      * {@link #getHistorySize}
2752      *
2753      * @see #getHistorySize
2754      * @see #getPressure(int)
2755      * @see #AXIS_PRESSURE
2756      */
getHistoricalPressure(int pointerIndex, int pos)2757     public final float getHistoricalPressure(int pointerIndex, int pos) {
2758         return nativeGetAxisValue(mNativePtr, AXIS_PRESSURE, pointerIndex, pos);
2759     }
2760 
2761     /**
2762      * Returns a historical size coordinate, as per {@link #getSize(int)}, that
2763      * occurred between this event and the previous event for the given pointer.
2764      * Only applies to ACTION_MOVE events.
2765      *
2766      * @param pointerIndex Raw index of pointer to retrieve.  Value may be from 0
2767      * (the first pointer that is down) to {@link #getPointerCount()}-1.
2768      * @param pos Which historical value to return; must be less than
2769      * {@link #getHistorySize}
2770      *
2771      * @see #getHistorySize
2772      * @see #getSize(int)
2773      * @see #AXIS_SIZE
2774      */
getHistoricalSize(int pointerIndex, int pos)2775     public final float getHistoricalSize(int pointerIndex, int pos) {
2776         return nativeGetAxisValue(mNativePtr, AXIS_SIZE, pointerIndex, pos);
2777     }
2778 
2779     /**
2780      * Returns a historical touch major axis coordinate, as per {@link #getTouchMajor(int)}, that
2781      * occurred between this event and the previous event for the given pointer.
2782      * Only applies to ACTION_MOVE events.
2783      *
2784      * @param pointerIndex Raw index of pointer to retrieve.  Value may be from 0
2785      * (the first pointer that is down) to {@link #getPointerCount()}-1.
2786      * @param pos Which historical value to return; must be less than
2787      * {@link #getHistorySize}
2788      *
2789      * @see #getHistorySize
2790      * @see #getTouchMajor(int)
2791      * @see #AXIS_TOUCH_MAJOR
2792      */
getHistoricalTouchMajor(int pointerIndex, int pos)2793     public final float getHistoricalTouchMajor(int pointerIndex, int pos) {
2794         return nativeGetAxisValue(mNativePtr, AXIS_TOUCH_MAJOR, pointerIndex, pos);
2795     }
2796 
2797     /**
2798      * Returns a historical touch minor axis coordinate, as per {@link #getTouchMinor(int)}, that
2799      * occurred between this event and the previous event for the given pointer.
2800      * Only applies to ACTION_MOVE events.
2801      *
2802      * @param pointerIndex Raw index of pointer to retrieve.  Value may be from 0
2803      * (the first pointer that is down) to {@link #getPointerCount()}-1.
2804      * @param pos Which historical value to return; must be less than
2805      * {@link #getHistorySize}
2806      *
2807      * @see #getHistorySize
2808      * @see #getTouchMinor(int)
2809      * @see #AXIS_TOUCH_MINOR
2810      */
getHistoricalTouchMinor(int pointerIndex, int pos)2811     public final float getHistoricalTouchMinor(int pointerIndex, int pos) {
2812         return nativeGetAxisValue(mNativePtr, AXIS_TOUCH_MINOR, pointerIndex, pos);
2813     }
2814 
2815     /**
2816      * Returns a historical tool major axis coordinate, as per {@link #getToolMajor(int)}, that
2817      * occurred between this event and the previous event for the given pointer.
2818      * Only applies to ACTION_MOVE events.
2819      *
2820      * @param pointerIndex Raw index of pointer to retrieve.  Value may be from 0
2821      * (the first pointer that is down) to {@link #getPointerCount()}-1.
2822      * @param pos Which historical value to return; must be less than
2823      * {@link #getHistorySize}
2824      *
2825      * @see #getHistorySize
2826      * @see #getToolMajor(int)
2827      * @see #AXIS_TOOL_MAJOR
2828      */
getHistoricalToolMajor(int pointerIndex, int pos)2829     public final float getHistoricalToolMajor(int pointerIndex, int pos) {
2830         return nativeGetAxisValue(mNativePtr, AXIS_TOOL_MAJOR, pointerIndex, pos);
2831     }
2832 
2833     /**
2834      * Returns a historical tool minor axis coordinate, as per {@link #getToolMinor(int)}, that
2835      * occurred between this event and the previous event for the given pointer.
2836      * Only applies to ACTION_MOVE events.
2837      *
2838      * @param pointerIndex Raw index of pointer to retrieve.  Value may be from 0
2839      * (the first pointer that is down) to {@link #getPointerCount()}-1.
2840      * @param pos Which historical value to return; must be less than
2841      * {@link #getHistorySize}
2842      *
2843      * @see #getHistorySize
2844      * @see #getToolMinor(int)
2845      * @see #AXIS_TOOL_MINOR
2846      */
getHistoricalToolMinor(int pointerIndex, int pos)2847     public final float getHistoricalToolMinor(int pointerIndex, int pos) {
2848         return nativeGetAxisValue(mNativePtr, AXIS_TOOL_MINOR, pointerIndex, pos);
2849     }
2850 
2851     /**
2852      * Returns a historical orientation coordinate, as per {@link #getOrientation(int)}, that
2853      * occurred between this event and the previous event for the given pointer.
2854      * Only applies to ACTION_MOVE events.
2855      *
2856      * @param pointerIndex Raw index of pointer to retrieve.  Value may be from 0
2857      * (the first pointer that is down) to {@link #getPointerCount()}-1.
2858      * @param pos Which historical value to return; must be less than
2859      * {@link #getHistorySize}
2860      *
2861      * @see #getHistorySize
2862      * @see #getOrientation(int)
2863      * @see #AXIS_ORIENTATION
2864      */
getHistoricalOrientation(int pointerIndex, int pos)2865     public final float getHistoricalOrientation(int pointerIndex, int pos) {
2866         return nativeGetAxisValue(mNativePtr, AXIS_ORIENTATION, pointerIndex, pos);
2867     }
2868 
2869     /**
2870      * Returns the historical value of the requested axis, as per {@link #getAxisValue(int, int)},
2871      * occurred between this event and the previous event for the given pointer.
2872      * Only applies to ACTION_MOVE events.
2873      *
2874      * @param axis The axis identifier for the axis value to retrieve.
2875      * @param pointerIndex Raw index of pointer to retrieve.  Value may be from 0
2876      * (the first pointer that is down) to {@link #getPointerCount()}-1.
2877      * @param pos Which historical value to return; must be less than
2878      * {@link #getHistorySize}
2879      * @return The value of the axis, or 0 if the axis is not available.
2880      *
2881      * @see #AXIS_X
2882      * @see #AXIS_Y
2883      */
getHistoricalAxisValue(int axis, int pointerIndex, int pos)2884     public final float getHistoricalAxisValue(int axis, int pointerIndex, int pos) {
2885         return nativeGetAxisValue(mNativePtr, axis, pointerIndex, pos);
2886     }
2887 
2888     /**
2889      * Populates a {@link PointerCoords} object with historical pointer coordinate data,
2890      * as per {@link #getPointerCoords}, that occurred between this event and the previous
2891      * event for the given pointer.
2892      * Only applies to ACTION_MOVE events.
2893      *
2894      * @param pointerIndex Raw index of pointer to retrieve.  Value may be from 0
2895      * (the first pointer that is down) to {@link #getPointerCount()}-1.
2896      * @param pos Which historical value to return; must be less than
2897      * {@link #getHistorySize}
2898      * @param outPointerCoords The pointer coordinate object to populate.
2899      *
2900      * @see #getHistorySize
2901      * @see #getPointerCoords
2902      * @see PointerCoords
2903      */
getHistoricalPointerCoords(int pointerIndex, int pos, PointerCoords outPointerCoords)2904     public final void getHistoricalPointerCoords(int pointerIndex, int pos,
2905             PointerCoords outPointerCoords) {
2906         nativeGetPointerCoords(mNativePtr, pointerIndex, pos, outPointerCoords);
2907     }
2908 
2909     /**
2910      * Returns a bitfield indicating which edges, if any, were touched by this
2911      * MotionEvent. For touch events, clients can use this to determine if the
2912      * user's finger was touching the edge of the display.
2913      *
2914      * This property is only set for {@link #ACTION_DOWN} events.
2915      *
2916      * @see #EDGE_LEFT
2917      * @see #EDGE_TOP
2918      * @see #EDGE_RIGHT
2919      * @see #EDGE_BOTTOM
2920      */
getEdgeFlags()2921     public final int getEdgeFlags() {
2922         return nativeGetEdgeFlags(mNativePtr);
2923     }
2924 
2925     /**
2926      * Sets the bitfield indicating which edges, if any, were touched by this
2927      * MotionEvent.
2928      *
2929      * @see #getEdgeFlags()
2930      */
setEdgeFlags(int flags)2931     public final void setEdgeFlags(int flags) {
2932         nativeSetEdgeFlags(mNativePtr, flags);
2933     }
2934 
2935     /**
2936      * Sets this event's action.
2937      */
setAction(int action)2938     public final void setAction(int action) {
2939         nativeSetAction(mNativePtr, action);
2940     }
2941 
2942     /**
2943      * Adjust this event's location.
2944      * @param deltaX Amount to add to the current X coordinate of the event.
2945      * @param deltaY Amount to add to the current Y coordinate of the event.
2946      */
offsetLocation(float deltaX, float deltaY)2947     public final void offsetLocation(float deltaX, float deltaY) {
2948         if (deltaX != 0.0f || deltaY != 0.0f) {
2949             nativeOffsetLocation(mNativePtr, deltaX, deltaY);
2950         }
2951     }
2952 
2953     /**
2954      * Set this event's location.  Applies {@link #offsetLocation} with a
2955      * delta from the current location to the given new location.
2956      *
2957      * @param x New absolute X location.
2958      * @param y New absolute Y location.
2959      */
setLocation(float x, float y)2960     public final void setLocation(float x, float y) {
2961         float oldX = getX();
2962         float oldY = getY();
2963         offsetLocation(x - oldX, y - oldY);
2964     }
2965 
2966     /**
2967      * Applies a transformation matrix to all of the points in the event.
2968      *
2969      * @param matrix The transformation matrix to apply.
2970      */
transform(Matrix matrix)2971     public final void transform(Matrix matrix) {
2972         if (matrix == null) {
2973             throw new IllegalArgumentException("matrix must not be null");
2974         }
2975 
2976         nativeTransform(mNativePtr, matrix.native_instance);
2977     }
2978 
2979     /**
2980      * Add a new movement to the batch of movements in this event.  The event's
2981      * current location, position and size is updated to the new values.
2982      * The current values in the event are added to a list of historical values.
2983      *
2984      * Only applies to {@link #ACTION_MOVE} or {@link #ACTION_HOVER_MOVE} events.
2985      *
2986      * @param eventTime The time stamp (in ms) for this data.
2987      * @param x The new X position.
2988      * @param y The new Y position.
2989      * @param pressure The new pressure.
2990      * @param size The new size.
2991      * @param metaState Meta key state.
2992      */
addBatch(long eventTime, float x, float y, float pressure, float size, int metaState)2993     public final void addBatch(long eventTime, float x, float y,
2994             float pressure, float size, int metaState) {
2995         synchronized (gSharedTempLock) {
2996             ensureSharedTempPointerCapacity(1);
2997             final PointerCoords[] pc = gSharedTempPointerCoords;
2998             pc[0].clear();
2999             pc[0].x = x;
3000             pc[0].y = y;
3001             pc[0].pressure = pressure;
3002             pc[0].size = size;
3003 
3004             nativeAddBatch(mNativePtr, eventTime * NS_PER_MS, pc, metaState);
3005         }
3006     }
3007 
3008     /**
3009      * Add a new movement to the batch of movements in this event.  The event's
3010      * current location, position and size is updated to the new values.
3011      * The current values in the event are added to a list of historical values.
3012      *
3013      * Only applies to {@link #ACTION_MOVE} or {@link #ACTION_HOVER_MOVE} events.
3014      *
3015      * @param eventTime The time stamp (in ms) for this data.
3016      * @param pointerCoords The new pointer coordinates.
3017      * @param metaState Meta key state.
3018      */
addBatch(long eventTime, PointerCoords[] pointerCoords, int metaState)3019     public final void addBatch(long eventTime, PointerCoords[] pointerCoords, int metaState) {
3020         nativeAddBatch(mNativePtr, eventTime * NS_PER_MS, pointerCoords, metaState);
3021     }
3022 
3023     /**
3024      * Adds all of the movement samples of the specified event to this one if
3025      * it is compatible.  To be compatible, the event must have the same device id,
3026      * source, action, flags, pointer count, pointer properties.
3027      *
3028      * Only applies to {@link #ACTION_MOVE} or {@link #ACTION_HOVER_MOVE} events.
3029      *
3030      * @param event The event whose movements samples should be added to this one
3031      * if possible.
3032      * @return True if batching was performed or false if batching was not possible.
3033      * @hide
3034      */
addBatch(MotionEvent event)3035     public final boolean addBatch(MotionEvent event) {
3036         final int action = nativeGetAction(mNativePtr);
3037         if (action != ACTION_MOVE && action != ACTION_HOVER_MOVE) {
3038             return false;
3039         }
3040         if (action != nativeGetAction(event.mNativePtr)) {
3041             return false;
3042         }
3043 
3044         if (nativeGetDeviceId(mNativePtr) != nativeGetDeviceId(event.mNativePtr)
3045                 || nativeGetSource(mNativePtr) != nativeGetSource(event.mNativePtr)
3046                 || nativeGetFlags(mNativePtr) != nativeGetFlags(event.mNativePtr)) {
3047             return false;
3048         }
3049 
3050         final int pointerCount = nativeGetPointerCount(mNativePtr);
3051         if (pointerCount != nativeGetPointerCount(event.mNativePtr)) {
3052             return false;
3053         }
3054 
3055         synchronized (gSharedTempLock) {
3056             ensureSharedTempPointerCapacity(Math.max(pointerCount, 2));
3057             final PointerProperties[] pp = gSharedTempPointerProperties;
3058             final PointerCoords[] pc = gSharedTempPointerCoords;
3059 
3060             for (int i = 0; i < pointerCount; i++) {
3061                 nativeGetPointerProperties(mNativePtr, i, pp[0]);
3062                 nativeGetPointerProperties(event.mNativePtr, i, pp[1]);
3063                 if (!pp[0].equals(pp[1])) {
3064                     return false;
3065                 }
3066             }
3067 
3068             final int metaState = nativeGetMetaState(event.mNativePtr);
3069             final int historySize = nativeGetHistorySize(event.mNativePtr);
3070             for (int h = 0; h <= historySize; h++) {
3071                 final int historyPos = (h == historySize ? HISTORY_CURRENT : h);
3072 
3073                 for (int i = 0; i < pointerCount; i++) {
3074                     nativeGetPointerCoords(event.mNativePtr, i, historyPos, pc[i]);
3075                 }
3076 
3077                 final long eventTimeNanos = nativeGetEventTimeNanos(event.mNativePtr, historyPos);
3078                 nativeAddBatch(mNativePtr, eventTimeNanos, pc, metaState);
3079             }
3080         }
3081         return true;
3082     }
3083 
3084     /**
3085      * Returns true if all points in the motion event are completely within the specified bounds.
3086      * @hide
3087      */
isWithinBoundsNoHistory(float left, float top, float right, float bottom)3088     public final boolean isWithinBoundsNoHistory(float left, float top,
3089             float right, float bottom) {
3090         final int pointerCount = nativeGetPointerCount(mNativePtr);
3091         for (int i = 0; i < pointerCount; i++) {
3092             final float x = nativeGetAxisValue(mNativePtr, AXIS_X, i, HISTORY_CURRENT);
3093             final float y = nativeGetAxisValue(mNativePtr, AXIS_Y, i, HISTORY_CURRENT);
3094             if (x < left || x > right || y < top || y > bottom) {
3095                 return false;
3096             }
3097         }
3098         return true;
3099     }
3100 
clamp(float value, float low, float high)3101     private static final float clamp(float value, float low, float high) {
3102         if (value < low) {
3103             return low;
3104         } else if (value > high) {
3105             return high;
3106         }
3107         return value;
3108     }
3109 
3110     /**
3111      * Returns a new motion events whose points have been clamped to the specified bounds.
3112      * @hide
3113      */
clampNoHistory(float left, float top, float right, float bottom)3114     public final MotionEvent clampNoHistory(float left, float top, float right, float bottom) {
3115         MotionEvent ev = obtain();
3116         synchronized (gSharedTempLock) {
3117             final int pointerCount = nativeGetPointerCount(mNativePtr);
3118 
3119             ensureSharedTempPointerCapacity(pointerCount);
3120             final PointerProperties[] pp = gSharedTempPointerProperties;
3121             final PointerCoords[] pc = gSharedTempPointerCoords;
3122 
3123             for (int i = 0; i < pointerCount; i++) {
3124                 nativeGetPointerProperties(mNativePtr, i, pp[i]);
3125                 nativeGetPointerCoords(mNativePtr, i, HISTORY_CURRENT, pc[i]);
3126                 pc[i].x = clamp(pc[i].x, left, right);
3127                 pc[i].y = clamp(pc[i].y, top, bottom);
3128             }
3129             ev.mNativePtr = nativeInitialize(ev.mNativePtr,
3130                     nativeGetDeviceId(mNativePtr), nativeGetSource(mNativePtr),
3131                     nativeGetAction(mNativePtr), nativeGetFlags(mNativePtr),
3132                     nativeGetEdgeFlags(mNativePtr), nativeGetMetaState(mNativePtr),
3133                     nativeGetButtonState(mNativePtr),
3134                     nativeGetXOffset(mNativePtr), nativeGetYOffset(mNativePtr),
3135                     nativeGetXPrecision(mNativePtr), nativeGetYPrecision(mNativePtr),
3136                     nativeGetDownTimeNanos(mNativePtr),
3137                     nativeGetEventTimeNanos(mNativePtr, HISTORY_CURRENT),
3138                     pointerCount, pp, pc);
3139             return ev;
3140         }
3141     }
3142 
3143     /**
3144      * Gets an integer where each pointer id present in the event is marked as a bit.
3145      * @hide
3146      */
getPointerIdBits()3147     public final int getPointerIdBits() {
3148         int idBits = 0;
3149         final int pointerCount = nativeGetPointerCount(mNativePtr);
3150         for (int i = 0; i < pointerCount; i++) {
3151             idBits |= 1 << nativeGetPointerId(mNativePtr, i);
3152         }
3153         return idBits;
3154     }
3155 
3156     /**
3157      * Splits a motion event such that it includes only a subset of pointer ids.
3158      * @hide
3159      */
split(int idBits)3160     public final MotionEvent split(int idBits) {
3161         MotionEvent ev = obtain();
3162         synchronized (gSharedTempLock) {
3163             final int oldPointerCount = nativeGetPointerCount(mNativePtr);
3164             ensureSharedTempPointerCapacity(oldPointerCount);
3165             final PointerProperties[] pp = gSharedTempPointerProperties;
3166             final PointerCoords[] pc = gSharedTempPointerCoords;
3167             final int[] map = gSharedTempPointerIndexMap;
3168 
3169             final int oldAction = nativeGetAction(mNativePtr);
3170             final int oldActionMasked = oldAction & ACTION_MASK;
3171             final int oldActionPointerIndex = (oldAction & ACTION_POINTER_INDEX_MASK)
3172                     >> ACTION_POINTER_INDEX_SHIFT;
3173             int newActionPointerIndex = -1;
3174             int newPointerCount = 0;
3175             int newIdBits = 0;
3176             for (int i = 0; i < oldPointerCount; i++) {
3177                 nativeGetPointerProperties(mNativePtr, i, pp[newPointerCount]);
3178                 final int idBit = 1 << pp[newPointerCount].id;
3179                 if ((idBit & idBits) != 0) {
3180                     if (i == oldActionPointerIndex) {
3181                         newActionPointerIndex = newPointerCount;
3182                     }
3183                     map[newPointerCount] = i;
3184                     newPointerCount += 1;
3185                     newIdBits |= idBit;
3186                 }
3187             }
3188 
3189             if (newPointerCount == 0) {
3190                 throw new IllegalArgumentException("idBits did not match any ids in the event");
3191             }
3192 
3193             final int newAction;
3194             if (oldActionMasked == ACTION_POINTER_DOWN || oldActionMasked == ACTION_POINTER_UP) {
3195                 if (newActionPointerIndex < 0) {
3196                     // An unrelated pointer changed.
3197                     newAction = ACTION_MOVE;
3198                 } else if (newPointerCount == 1) {
3199                     // The first/last pointer went down/up.
3200                     newAction = oldActionMasked == ACTION_POINTER_DOWN
3201                             ? ACTION_DOWN : ACTION_UP;
3202                 } else {
3203                     // A secondary pointer went down/up.
3204                     newAction = oldActionMasked
3205                             | (newActionPointerIndex << ACTION_POINTER_INDEX_SHIFT);
3206                 }
3207             } else {
3208                 // Simple up/down/cancel/move or other motion action.
3209                 newAction = oldAction;
3210             }
3211 
3212             final int historySize = nativeGetHistorySize(mNativePtr);
3213             for (int h = 0; h <= historySize; h++) {
3214                 final int historyPos = h == historySize ? HISTORY_CURRENT : h;
3215 
3216                 for (int i = 0; i < newPointerCount; i++) {
3217                     nativeGetPointerCoords(mNativePtr, map[i], historyPos, pc[i]);
3218                 }
3219 
3220                 final long eventTimeNanos = nativeGetEventTimeNanos(mNativePtr, historyPos);
3221                 if (h == 0) {
3222                     ev.mNativePtr = nativeInitialize(ev.mNativePtr,
3223                             nativeGetDeviceId(mNativePtr), nativeGetSource(mNativePtr),
3224                             newAction, nativeGetFlags(mNativePtr),
3225                             nativeGetEdgeFlags(mNativePtr), nativeGetMetaState(mNativePtr),
3226                             nativeGetButtonState(mNativePtr),
3227                             nativeGetXOffset(mNativePtr), nativeGetYOffset(mNativePtr),
3228                             nativeGetXPrecision(mNativePtr), nativeGetYPrecision(mNativePtr),
3229                             nativeGetDownTimeNanos(mNativePtr), eventTimeNanos,
3230                             newPointerCount, pp, pc);
3231                 } else {
3232                     nativeAddBatch(ev.mNativePtr, eventTimeNanos, pc, 0);
3233                 }
3234             }
3235             return ev;
3236         }
3237     }
3238 
3239     @Override
toString()3240     public String toString() {
3241         StringBuilder msg = new StringBuilder();
3242         msg.append("MotionEvent { action=").append(actionToString(getAction()));
3243         appendUnless("0", msg, ", actionButton=", buttonStateToString(getActionButton()));
3244 
3245         final int pointerCount = getPointerCount();
3246         for (int i = 0; i < pointerCount; i++) {
3247             appendUnless(i, msg, ", id[" + i + "]=", getPointerId(i));
3248             float x = getX(i);
3249             float y = getY(i);
3250             if (!DEBUG_CONCISE_TOSTRING || x != 0f || y != 0f) {
3251                 msg.append(", x[").append(i).append("]=").append(x);
3252                 msg.append(", y[").append(i).append("]=").append(y);
3253             }
3254             appendUnless(TOOL_TYPE_SYMBOLIC_NAMES.get(TOOL_TYPE_FINGER),
3255                     msg, ", toolType[" + i + "]=", toolTypeToString(getToolType(i)));
3256         }
3257 
3258         appendUnless("0", msg, ", buttonState=", MotionEvent.buttonStateToString(getButtonState()));
3259         appendUnless("0", msg, ", metaState=", KeyEvent.metaStateToString(getMetaState()));
3260         appendUnless("0", msg, ", flags=0x", Integer.toHexString(getFlags()));
3261         appendUnless("0", msg, ", edgeFlags=0x", Integer.toHexString(getEdgeFlags()));
3262         appendUnless(1, msg, ", pointerCount=", pointerCount);
3263         appendUnless(0, msg, ", historySize=", getHistorySize());
3264         msg.append(", eventTime=").append(getEventTime());
3265         if (!DEBUG_CONCISE_TOSTRING) {
3266             msg.append(", downTime=").append(getDownTime());
3267             msg.append(", deviceId=").append(getDeviceId());
3268             msg.append(", source=0x").append(Integer.toHexString(getSource()));
3269         }
3270         msg.append(" }");
3271         return msg.toString();
3272     }
3273 
appendUnless(T defValue, StringBuilder sb, String key, T value)3274     private static <T> void appendUnless(T defValue, StringBuilder sb, String key, T value) {
3275         if (DEBUG_CONCISE_TOSTRING && Objects.equals(defValue, value)) return;
3276         sb.append(key).append(value);
3277     }
3278 
3279     /**
3280      * Returns a string that represents the symbolic name of the specified unmasked action
3281      * such as "ACTION_DOWN", "ACTION_POINTER_DOWN(3)" or an equivalent numeric constant
3282      * such as "35" if unknown.
3283      *
3284      * @param action The unmasked action.
3285      * @return The symbolic name of the specified action.
3286      * @see #getAction()
3287      */
actionToString(int action)3288     public static String actionToString(int action) {
3289         switch (action) {
3290             case ACTION_DOWN:
3291                 return "ACTION_DOWN";
3292             case ACTION_UP:
3293                 return "ACTION_UP";
3294             case ACTION_CANCEL:
3295                 return "ACTION_CANCEL";
3296             case ACTION_OUTSIDE:
3297                 return "ACTION_OUTSIDE";
3298             case ACTION_MOVE:
3299                 return "ACTION_MOVE";
3300             case ACTION_HOVER_MOVE:
3301                 return "ACTION_HOVER_MOVE";
3302             case ACTION_SCROLL:
3303                 return "ACTION_SCROLL";
3304             case ACTION_HOVER_ENTER:
3305                 return "ACTION_HOVER_ENTER";
3306             case ACTION_HOVER_EXIT:
3307                 return "ACTION_HOVER_EXIT";
3308             case ACTION_BUTTON_PRESS:
3309                 return "ACTION_BUTTON_PRESS";
3310             case ACTION_BUTTON_RELEASE:
3311                 return "ACTION_BUTTON_RELEASE";
3312         }
3313         int index = (action & ACTION_POINTER_INDEX_MASK) >> ACTION_POINTER_INDEX_SHIFT;
3314         switch (action & ACTION_MASK) {
3315             case ACTION_POINTER_DOWN:
3316                 return "ACTION_POINTER_DOWN(" + index + ")";
3317             case ACTION_POINTER_UP:
3318                 return "ACTION_POINTER_UP(" + index + ")";
3319             default:
3320                 return Integer.toString(action);
3321         }
3322     }
3323 
3324     /**
3325      * Returns a string that represents the symbolic name of the specified axis
3326      * such as "AXIS_X" or an equivalent numeric constant such as "42" if unknown.
3327      *
3328      * @param axis The axis.
3329      * @return The symbolic name of the specified axis.
3330      */
axisToString(int axis)3331     public static String axisToString(int axis) {
3332         String symbolicName = nativeAxisToString(axis);
3333         return symbolicName != null ? LABEL_PREFIX + symbolicName : Integer.toString(axis);
3334     }
3335 
3336     /**
3337      * Gets an axis by its symbolic name such as "AXIS_X" or an
3338      * equivalent numeric constant such as "42".
3339      *
3340      * @param symbolicName The symbolic name of the axis.
3341      * @return The axis or -1 if not found.
3342      * @see KeyEvent#keyCodeToString(int)
3343      */
axisFromString(String symbolicName)3344     public static int axisFromString(String symbolicName) {
3345         if (symbolicName.startsWith(LABEL_PREFIX)) {
3346             symbolicName = symbolicName.substring(LABEL_PREFIX.length());
3347             int axis = nativeAxisFromString(symbolicName);
3348             if (axis >= 0) {
3349                 return axis;
3350             }
3351         }
3352         try {
3353             return Integer.parseInt(symbolicName, 10);
3354         } catch (NumberFormatException ex) {
3355             return -1;
3356         }
3357     }
3358 
3359     /**
3360      * Returns a string that represents the symbolic name of the specified combined
3361      * button state flags such as "0", "BUTTON_PRIMARY",
3362      * "BUTTON_PRIMARY|BUTTON_SECONDARY" or an equivalent numeric constant such as "0x10000000"
3363      * if unknown.
3364      *
3365      * @param buttonState The button state.
3366      * @return The symbolic name of the specified combined button state flags.
3367      * @hide
3368      */
buttonStateToString(int buttonState)3369     public static String buttonStateToString(int buttonState) {
3370         if (buttonState == 0) {
3371             return "0";
3372         }
3373         StringBuilder result = null;
3374         int i = 0;
3375         while (buttonState != 0) {
3376             final boolean isSet = (buttonState & 1) != 0;
3377             buttonState >>>= 1; // unsigned shift!
3378             if (isSet) {
3379                 final String name = BUTTON_SYMBOLIC_NAMES[i];
3380                 if (result == null) {
3381                     if (buttonState == 0) {
3382                         return name;
3383                     }
3384                     result = new StringBuilder(name);
3385                 } else {
3386                     result.append('|');
3387                     result.append(name);
3388                 }
3389             }
3390             i += 1;
3391         }
3392         return result.toString();
3393     }
3394 
3395     /**
3396      * Returns a string that represents the symbolic name of the specified tool type
3397      * such as "TOOL_TYPE_FINGER" or an equivalent numeric constant such as "42" if unknown.
3398      *
3399      * @param toolType The tool type.
3400      * @return The symbolic name of the specified tool type.
3401      * @hide
3402      */
toolTypeToString(int toolType)3403     public static String toolTypeToString(int toolType) {
3404         String symbolicName = TOOL_TYPE_SYMBOLIC_NAMES.get(toolType);
3405         return symbolicName != null ? symbolicName : Integer.toString(toolType);
3406     }
3407 
3408     /**
3409      * Checks if a mouse or stylus button (or combination of buttons) is pressed.
3410      * @param button Button (or combination of buttons).
3411      * @return True if specified buttons are pressed.
3412      *
3413      * @see #BUTTON_PRIMARY
3414      * @see #BUTTON_SECONDARY
3415      * @see #BUTTON_TERTIARY
3416      * @see #BUTTON_FORWARD
3417      * @see #BUTTON_BACK
3418      * @see #BUTTON_STYLUS_PRIMARY
3419      * @see #BUTTON_STYLUS_SECONDARY
3420      */
isButtonPressed(int button)3421     public final boolean isButtonPressed(int button) {
3422         if (button == 0) {
3423             return false;
3424         }
3425         return (getButtonState() & button) == button;
3426     }
3427 
3428     public static final Parcelable.Creator<MotionEvent> CREATOR
3429             = new Parcelable.Creator<MotionEvent>() {
3430         public MotionEvent createFromParcel(Parcel in) {
3431             in.readInt(); // skip token, we already know this is a MotionEvent
3432             return MotionEvent.createFromParcelBody(in);
3433         }
3434 
3435         public MotionEvent[] newArray(int size) {
3436             return new MotionEvent[size];
3437         }
3438     };
3439 
3440     /** @hide */
createFromParcelBody(Parcel in)3441     public static MotionEvent createFromParcelBody(Parcel in) {
3442         MotionEvent ev = obtain();
3443         ev.mNativePtr = nativeReadFromParcel(ev.mNativePtr, in);
3444         return ev;
3445     }
3446 
3447     /** @hide */
3448     @Override
cancel()3449     public final void cancel() {
3450         setAction(ACTION_CANCEL);
3451     }
3452 
writeToParcel(Parcel out, int flags)3453     public void writeToParcel(Parcel out, int flags) {
3454         out.writeInt(PARCEL_TOKEN_MOTION_EVENT);
3455         nativeWriteToParcel(mNativePtr, out);
3456     }
3457 
3458     /**
3459      * Transfer object for pointer coordinates.
3460      *
3461      * Objects of this type can be used to specify the pointer coordinates when
3462      * creating new {@link MotionEvent} objects and to query pointer coordinates
3463      * in bulk.
3464      *
3465      * Refer to {@link InputDevice} for information about how different kinds of
3466      * input devices and sources represent pointer coordinates.
3467      */
3468     public static final class PointerCoords {
3469         private static final int INITIAL_PACKED_AXIS_VALUES = 8;
3470         private long mPackedAxisBits;
3471         private float[] mPackedAxisValues;
3472 
3473         /**
3474          * Creates a pointer coords object with all axes initialized to zero.
3475          */
PointerCoords()3476         public PointerCoords() {
3477         }
3478 
3479         /**
3480          * Creates a pointer coords object as a copy of the
3481          * contents of another pointer coords object.
3482          *
3483          * @param other The pointer coords object to copy.
3484          */
PointerCoords(PointerCoords other)3485         public PointerCoords(PointerCoords other) {
3486             copyFrom(other);
3487         }
3488 
3489         /** @hide */
createArray(int size)3490         public static PointerCoords[] createArray(int size) {
3491             PointerCoords[] array = new PointerCoords[size];
3492             for (int i = 0; i < size; i++) {
3493                 array[i] = new PointerCoords();
3494             }
3495             return array;
3496         }
3497 
3498         /**
3499          * The X component of the pointer movement.
3500          *
3501          * @see MotionEvent#AXIS_X
3502          */
3503         public float x;
3504 
3505         /**
3506          * The Y component of the pointer movement.
3507          *
3508          * @see MotionEvent#AXIS_Y
3509          */
3510         public float y;
3511 
3512         /**
3513          * A normalized value that describes the pressure applied to the device
3514          * by a finger or other tool.
3515          * The pressure generally ranges from 0 (no pressure at all) to 1 (normal pressure),
3516          * although values higher than 1 may be generated depending on the calibration of
3517          * the input device.
3518          *
3519          * @see MotionEvent#AXIS_PRESSURE
3520          */
3521         public float pressure;
3522 
3523         /**
3524          * A normalized value that describes the approximate size of the pointer touch area
3525          * in relation to the maximum detectable size of the device.
3526          * It represents some approximation of the area of the screen being
3527          * pressed; the actual value in pixels corresponding to the
3528          * touch is normalized with the device specific range of values
3529          * and scaled to a value between 0 and 1. The value of size can be used to
3530          * determine fat touch events.
3531          *
3532          * @see MotionEvent#AXIS_SIZE
3533          */
3534         public float size;
3535 
3536         /**
3537          * The length of the major axis of an ellipse that describes the touch area at
3538          * the point of contact.
3539          * If the device is a touch screen, the length is reported in pixels, otherwise it is
3540          * reported in device-specific units.
3541          *
3542          * @see MotionEvent#AXIS_TOUCH_MAJOR
3543          */
3544         public float touchMajor;
3545 
3546         /**
3547          * The length of the minor axis of an ellipse that describes the touch area at
3548          * the point of contact.
3549          * If the device is a touch screen, the length is reported in pixels, otherwise it is
3550          * reported in device-specific units.
3551          *
3552          * @see MotionEvent#AXIS_TOUCH_MINOR
3553          */
3554         public float touchMinor;
3555 
3556         /**
3557          * The length of the major axis of an ellipse that describes the size of
3558          * the approaching tool.
3559          * The tool area represents the estimated size of the finger or pen that is
3560          * touching the device independent of its actual touch area at the point of contact.
3561          * If the device is a touch screen, the length is reported in pixels, otherwise it is
3562          * reported in device-specific units.
3563          *
3564          * @see MotionEvent#AXIS_TOOL_MAJOR
3565          */
3566         public float toolMajor;
3567 
3568         /**
3569          * The length of the minor axis of an ellipse that describes the size of
3570          * the approaching tool.
3571          * The tool area represents the estimated size of the finger or pen that is
3572          * touching the device independent of its actual touch area at the point of contact.
3573          * If the device is a touch screen, the length is reported in pixels, otherwise it is
3574          * reported in device-specific units.
3575          *
3576          * @see MotionEvent#AXIS_TOOL_MINOR
3577          */
3578         public float toolMinor;
3579 
3580         /**
3581          * The orientation of the touch area and tool area in radians clockwise from vertical.
3582          * An angle of 0 radians indicates that the major axis of contact is oriented
3583          * upwards, is perfectly circular or is of unknown orientation.  A positive angle
3584          * indicates that the major axis of contact is oriented to the right.  A negative angle
3585          * indicates that the major axis of contact is oriented to the left.
3586          * The full range is from -PI/2 radians (finger pointing fully left) to PI/2 radians
3587          * (finger pointing fully right).
3588          *
3589          * @see MotionEvent#AXIS_ORIENTATION
3590          */
3591         public float orientation;
3592 
3593         /**
3594          * Clears the contents of this object.
3595          * Resets all axes to zero.
3596          */
clear()3597         public void clear() {
3598             mPackedAxisBits = 0;
3599 
3600             x = 0;
3601             y = 0;
3602             pressure = 0;
3603             size = 0;
3604             touchMajor = 0;
3605             touchMinor = 0;
3606             toolMajor = 0;
3607             toolMinor = 0;
3608             orientation = 0;
3609         }
3610 
3611         /**
3612          * Copies the contents of another pointer coords object.
3613          *
3614          * @param other The pointer coords object to copy.
3615          */
copyFrom(PointerCoords other)3616         public void copyFrom(PointerCoords other) {
3617             final long bits = other.mPackedAxisBits;
3618             mPackedAxisBits = bits;
3619             if (bits != 0) {
3620                 final float[] otherValues = other.mPackedAxisValues;
3621                 final int count = Long.bitCount(bits);
3622                 float[] values = mPackedAxisValues;
3623                 if (values == null || count > values.length) {
3624                     values = new float[otherValues.length];
3625                     mPackedAxisValues = values;
3626                 }
3627                 System.arraycopy(otherValues, 0, values, 0, count);
3628             }
3629 
3630             x = other.x;
3631             y = other.y;
3632             pressure = other.pressure;
3633             size = other.size;
3634             touchMajor = other.touchMajor;
3635             touchMinor = other.touchMinor;
3636             toolMajor = other.toolMajor;
3637             toolMinor = other.toolMinor;
3638             orientation = other.orientation;
3639         }
3640 
3641         /**
3642          * Gets the value associated with the specified axis.
3643          *
3644          * @param axis The axis identifier for the axis value to retrieve.
3645          * @return The value associated with the axis, or 0 if none.
3646          *
3647          * @see MotionEvent#AXIS_X
3648          * @see MotionEvent#AXIS_Y
3649          */
getAxisValue(int axis)3650         public float getAxisValue(int axis) {
3651             switch (axis) {
3652                 case AXIS_X:
3653                     return x;
3654                 case AXIS_Y:
3655                     return y;
3656                 case AXIS_PRESSURE:
3657                     return pressure;
3658                 case AXIS_SIZE:
3659                     return size;
3660                 case AXIS_TOUCH_MAJOR:
3661                     return touchMajor;
3662                 case AXIS_TOUCH_MINOR:
3663                     return touchMinor;
3664                 case AXIS_TOOL_MAJOR:
3665                     return toolMajor;
3666                 case AXIS_TOOL_MINOR:
3667                     return toolMinor;
3668                 case AXIS_ORIENTATION:
3669                     return orientation;
3670                 default: {
3671                     if (axis < 0 || axis > 63) {
3672                         throw new IllegalArgumentException("Axis out of range.");
3673                     }
3674                     final long bits = mPackedAxisBits;
3675                     final long axisBit = 0x8000000000000000L >>> axis;
3676                     if ((bits & axisBit) == 0) {
3677                         return 0;
3678                     }
3679                     final int index = Long.bitCount(bits & ~(0xFFFFFFFFFFFFFFFFL >>> axis));
3680                     return mPackedAxisValues[index];
3681                 }
3682             }
3683         }
3684 
3685         /**
3686          * Sets the value associated with the specified axis.
3687          *
3688          * @param axis The axis identifier for the axis value to assign.
3689          * @param value The value to set.
3690          *
3691          * @see MotionEvent#AXIS_X
3692          * @see MotionEvent#AXIS_Y
3693          */
setAxisValue(int axis, float value)3694         public void setAxisValue(int axis, float value) {
3695             switch (axis) {
3696                 case AXIS_X:
3697                     x = value;
3698                     break;
3699                 case AXIS_Y:
3700                     y = value;
3701                     break;
3702                 case AXIS_PRESSURE:
3703                     pressure = value;
3704                     break;
3705                 case AXIS_SIZE:
3706                     size = value;
3707                     break;
3708                 case AXIS_TOUCH_MAJOR:
3709                     touchMajor = value;
3710                     break;
3711                 case AXIS_TOUCH_MINOR:
3712                     touchMinor = value;
3713                     break;
3714                 case AXIS_TOOL_MAJOR:
3715                     toolMajor = value;
3716                     break;
3717                 case AXIS_TOOL_MINOR:
3718                     toolMinor = value;
3719                     break;
3720                 case AXIS_ORIENTATION:
3721                     orientation = value;
3722                     break;
3723                 default: {
3724                     if (axis < 0 || axis > 63) {
3725                         throw new IllegalArgumentException("Axis out of range.");
3726                     }
3727                     final long bits = mPackedAxisBits;
3728                     final long axisBit = 0x8000000000000000L >>> axis;
3729                     final int index = Long.bitCount(bits & ~(0xFFFFFFFFFFFFFFFFL >>> axis));
3730                     float[] values = mPackedAxisValues;
3731                     if ((bits & axisBit) == 0) {
3732                         if (values == null) {
3733                             values = new float[INITIAL_PACKED_AXIS_VALUES];
3734                             mPackedAxisValues = values;
3735                         } else {
3736                             final int count = Long.bitCount(bits);
3737                             if (count < values.length) {
3738                                 if (index != count) {
3739                                     System.arraycopy(values, index, values, index + 1,
3740                                             count - index);
3741                                 }
3742                             } else {
3743                                 float[] newValues = new float[count * 2];
3744                                 System.arraycopy(values, 0, newValues, 0, index);
3745                                 System.arraycopy(values, index, newValues, index + 1,
3746                                         count - index);
3747                                 values = newValues;
3748                                 mPackedAxisValues = values;
3749                             }
3750                         }
3751                         mPackedAxisBits = bits | axisBit;
3752                     }
3753                     values[index] = value;
3754                 }
3755             }
3756         }
3757     }
3758 
3759     /**
3760      * Transfer object for pointer properties.
3761      *
3762      * Objects of this type can be used to specify the pointer id and tool type
3763      * when creating new {@link MotionEvent} objects and to query pointer properties in bulk.
3764      */
3765     public static final class PointerProperties {
3766         /**
3767          * Creates a pointer properties object with an invalid pointer id.
3768          */
PointerProperties()3769         public PointerProperties() {
3770             clear();
3771         }
3772 
3773         /**
3774          * Creates a pointer properties object as a copy of the contents of
3775          * another pointer properties object.
3776          * @param other
3777          */
PointerProperties(PointerProperties other)3778         public PointerProperties(PointerProperties other) {
3779             copyFrom(other);
3780         }
3781 
3782         /** @hide */
createArray(int size)3783         public static PointerProperties[] createArray(int size) {
3784             PointerProperties[] array = new PointerProperties[size];
3785             for (int i = 0; i < size; i++) {
3786                 array[i] = new PointerProperties();
3787             }
3788             return array;
3789         }
3790 
3791         /**
3792          * The pointer id.
3793          * Initially set to {@link #INVALID_POINTER_ID} (-1).
3794          *
3795          * @see MotionEvent#getPointerId(int)
3796          */
3797         public int id;
3798 
3799         /**
3800          * The pointer tool type.
3801          * Initially set to 0.
3802          *
3803          * @see MotionEvent#getToolType(int)
3804          */
3805         public int toolType;
3806 
3807         /**
3808          * Resets the pointer properties to their initial values.
3809          */
clear()3810         public void clear() {
3811             id = INVALID_POINTER_ID;
3812             toolType = TOOL_TYPE_UNKNOWN;
3813         }
3814 
3815         /**
3816          * Copies the contents of another pointer properties object.
3817          *
3818          * @param other The pointer properties object to copy.
3819          */
copyFrom(PointerProperties other)3820         public void copyFrom(PointerProperties other) {
3821             id = other.id;
3822             toolType = other.toolType;
3823         }
3824 
3825         @Override
equals(Object other)3826         public boolean equals(Object other) {
3827             if (other instanceof PointerProperties) {
3828                 return equals((PointerProperties)other);
3829             }
3830             return false;
3831         }
3832 
equals(PointerProperties other)3833         private boolean equals(PointerProperties other) {
3834             return other != null && id == other.id && toolType == other.toolType;
3835         }
3836 
3837         @Override
hashCode()3838         public int hashCode() {
3839             return id | (toolType << 8);
3840         }
3841     }
3842 }
3843