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