From fe9f8ab03a63b1037f07dd85799fbea80ec6adaa Mon Sep 17 00:00:00 2001 From: Jeff Brown Date: Fri, 6 May 2011 18:20:01 -0700 Subject: Add initial API for stylus and mouse buttons. Added the concept of pointer properties in a MotionEvent. This is currently used to track the pointer tool type to enable applications to distinguish finger touches from a stylus. Button states are also reported to application as part of touch events. There are no new actions for detecting changes in button states. The application should instead query the button state from the MotionEvent and take appropriate action as needed. A good time to check the button state is on ACTION_DOWN. As a side-effect, applications that do not support multiple buttons will treat primary, secondary and tertiary buttons identically for all touch events. The back button on the mouse is mapped to KEYCODE_BACK and the forward button is mapped to KEYCODE_FORWARD. Added basic plumbing for the secondary mouse button to invoke the context menu, particularly in lists. Added clamp and split methods on MotionEvent to take care of common filtering operations so we don't have them scattered in multiple places across the framework. Bug: 4260011 Change-Id: Ie992b4d4e00c8f2e76b961da0a902145b27f6d83 --- api/current.txt | 30 +- .../inputmethodservice/SoftInputWindow.java | 57 +- core/java/android/view/InputDevice.java | 10 +- core/java/android/view/KeyEvent.java | 25 +- core/java/android/view/MotionEvent.java | 1020 ++++++++++++++++---- core/java/android/view/View.java | 35 + core/java/android/view/ViewGroup.java | 174 +--- core/java/android/widget/AbsListView.java | 21 + .../internal/widget/PointerLocationView.java | 34 +- core/jni/android_view_MotionEvent.cpp | 150 ++- include/ui/Input.h | 59 +- include/ui/InputTransport.h | 6 +- libs/ui/Input.cpp | 45 +- libs/ui/InputTransport.cpp | 16 +- libs/ui/tests/InputEvent_test.cpp | 25 +- libs/ui/tests/InputPublisherAndConsumer_test.cpp | 72 +- native/android/input.cpp | 8 + native/include/android/input.h | 38 +- services/input/InputDispatcher.cpp | 385 ++++---- services/input/InputDispatcher.h | 25 +- services/input/InputReader.cpp | 275 ++++-- services/input/InputReader.h | 28 +- services/input/PointerController.cpp | 4 +- services/input/PointerController.h | 10 +- services/input/tests/InputDispatcher_test.cpp | 54 +- services/input/tests/InputReader_test.cpp | 159 ++- .../server/accessibility/TouchExplorer.java | 97 +- 27 files changed, 1989 insertions(+), 873 deletions(-) diff --git a/api/current.txt b/api/current.txt index 12fa844..86703ba 100644 --- a/api/current.txt +++ b/api/current.txt @@ -20158,6 +20158,7 @@ package android.view { field public static final int SOURCE_JOYSTICK = 16777232; // 0x1000010 field public static final int SOURCE_KEYBOARD = 257; // 0x101 field public static final int SOURCE_MOUSE = 8194; // 0x2002 + field public static final int SOURCE_STYLUS = 16386; // 0x4002 field public static final int SOURCE_TOUCHPAD = 1048584; // 0x100008 field public static final int SOURCE_TOUCHSCREEN = 4098; // 0x1002 field public static final int SOURCE_TRACKBALL = 65540; // 0x10004 @@ -20690,6 +20691,7 @@ package android.view { method public final int getActionMasked(); method public final float getAxisValue(int); method public final float getAxisValue(int, int); + method public final int getButtonState(); method public final int getDeviceId(); method public final long getDownTime(); method public final int getEdgeFlags(); @@ -20724,6 +20726,7 @@ package android.view { method public final void getPointerCoords(int, android.view.MotionEvent.PointerCoords); method public final int getPointerCount(); method public final int getPointerId(int); + method public final void getPointerProperties(int, android.view.MotionEvent.PointerProperties); method public final float getPressure(); method public final float getPressure(int); method public final float getRawX(); @@ -20735,6 +20738,7 @@ package android.view { method public final float getToolMajor(int); method public final float getToolMinor(); method public final float getToolMinor(int); + method public final int getToolType(int); method public final float getTouchMajor(); method public final float getTouchMajor(int); method public final float getTouchMinor(); @@ -20745,7 +20749,8 @@ package android.view { method public final float getY(); method public final float getY(int); method public final float getYPrecision(); - method public static android.view.MotionEvent obtain(long, long, int, int, int[], android.view.MotionEvent.PointerCoords[], int, float, float, int, int, int, int); + method public static android.view.MotionEvent obtain(long, long, int, int, android.view.MotionEvent.PointerProperties[], android.view.MotionEvent.PointerCoords[], int, int, float, float, int, int, int, int); + method public static deprecated android.view.MotionEvent obtain(long, long, int, int, int[], android.view.MotionEvent.PointerCoords[], int, float, float, int, int, int, int); method public static android.view.MotionEvent obtain(long, long, int, float, float, float, float, int, float, float, int, int); method public static deprecated android.view.MotionEvent obtain(long, long, int, int, float, float, float, float, int, float, float, int, int); method public static android.view.MotionEvent obtain(long, long, int, float, float, int); @@ -20782,6 +20787,7 @@ package android.view { field public static final int ACTION_SCROLL = 8; // 0x8 field public static final int ACTION_UP = 1; // 0x1 field public static final int AXIS_BRAKE = 23; // 0x17 + field public static final int AXIS_DISTANCE = 24; // 0x18 field public static final int AXIS_GAS = 22; // 0x16 field public static final int AXIS_GENERIC_1 = 32; // 0x20 field public static final int AXIS_GENERIC_10 = 41; // 0x29 @@ -20821,12 +20827,25 @@ package android.view { field public static final int AXIS_X = 0; // 0x0 field public static final int AXIS_Y = 1; // 0x1 field public static final int AXIS_Z = 11; // 0xb + field public static final int BUTTON_BACK = 8; // 0x8 + field public static final int BUTTON_ERASER = 32; // 0x20 + field public static final int BUTTON_FORWARD = 16; // 0x10 + field public static final int BUTTON_PRIMARY = 1; // 0x1 + field public static final int BUTTON_SECONDARY = 2; // 0x2 + field public static final int BUTTON_TERTIARY = 4; // 0x4 field public static final android.os.Parcelable.Creator CREATOR; field public static final int EDGE_BOTTOM = 2; // 0x2 field public static final int EDGE_LEFT = 4; // 0x4 field public static final int EDGE_RIGHT = 8; // 0x8 field public static final int EDGE_TOP = 1; // 0x1 field public static final int FLAG_WINDOW_IS_OBSCURED = 1; // 0x1 + field public static final int INVALID_POINTER_ID = -1; // 0xffffffff + field public static final int TOOL_TYPE_FINGER = 1; // 0x1 + field public static final int TOOL_TYPE_INDIRECT_FINGER = 4; // 0x4 + field public static final int TOOL_TYPE_INDIRECT_STYLUS = 5; // 0x5 + field public static final int TOOL_TYPE_MOUSE = 3; // 0x3 + field public static final int TOOL_TYPE_STYLUS = 2; // 0x2 + field public static final int TOOL_TYPE_UNKNOWN = 0; // 0x0 } public static final class MotionEvent.PointerCoords { @@ -20847,6 +20866,15 @@ package android.view { field public float y; } + public static final class MotionEvent.PointerProperties { + ctor public MotionEvent.PointerProperties(); + ctor public MotionEvent.PointerProperties(android.view.MotionEvent.PointerProperties); + method public void clear(); + method public void copyFrom(android.view.MotionEvent.PointerProperties); + field public int id; + field public int toolType; + } + public abstract class OrientationEventListener { ctor public OrientationEventListener(android.content.Context); ctor public OrientationEventListener(android.content.Context, int); diff --git a/core/java/android/inputmethodservice/SoftInputWindow.java b/core/java/android/inputmethodservice/SoftInputWindow.java index 343242e..7159260 100644 --- a/core/java/android/inputmethodservice/SoftInputWindow.java +++ b/core/java/android/inputmethodservice/SoftInputWindow.java @@ -73,8 +73,17 @@ class SoftInputWindow extends Dialog { @Override public boolean dispatchTouchEvent(MotionEvent ev) { getWindow().getDecorView().getHitRect(mBounds); - final MotionEvent event = clipMotionEvent(ev, mBounds); - return super.dispatchTouchEvent(event); + + if (ev.isWithinBoundsNoHistory(mBounds.left, mBounds.top, + mBounds.right - 1, mBounds.bottom - 1)) { + return super.dispatchTouchEvent(ev); + } else { + MotionEvent temp = ev.clampNoHistory(mBounds.left, mBounds.top, + mBounds.right - 1, mBounds.bottom - 1); + boolean handled = super.dispatchTouchEvent(temp); + temp.recycle(); + return handled; + } } /** @@ -163,48 +172,4 @@ class SoftInputWindow extends Dialog { WindowManager.LayoutParams.FLAG_NOT_FOCUSABLE | WindowManager.LayoutParams.FLAG_DIM_BEHIND); } - - private static MotionEvent clipMotionEvent(MotionEvent me, Rect bounds) { - final int pointerCount = me.getPointerCount(); - boolean shouldClip = false; - for (int pointerIndex = 0; pointerIndex < pointerCount; pointerIndex++) { - final int x = (int)me.getX(pointerIndex); - final int y = (int)me.getY(pointerIndex); - if (!bounds.contains(x, y)) { - shouldClip = true; - break; - } - } - if (!shouldClip) - return me; - - if (pointerCount == 1) { - final int x = (int)me.getX(); - final int y = (int)me.getY(); - me.setLocation( - Math.max(bounds.left, Math.min(x, bounds.right - 1)), - Math.max(bounds.top, Math.min(y, bounds.bottom - 1))); - return me; - } - - final int[] pointerIds = new int[pointerCount]; - final MotionEvent.PointerCoords[] pointerCoords = - new MotionEvent.PointerCoords[pointerCount]; - for (int pointerIndex = 0; pointerIndex < pointerCount; pointerIndex++) { - pointerIds[pointerIndex] = me.getPointerId(pointerIndex); - final MotionEvent.PointerCoords coords = new MotionEvent.PointerCoords(); - me.getPointerCoords(pointerIndex, coords); - pointerCoords[pointerIndex] = coords; - final int x = (int)coords.x; - final int y = (int)coords.y; - if (!bounds.contains(x, y)) { - coords.x = Math.max(bounds.left, Math.min(x, bounds.right - 1)); - coords.y = Math.max(bounds.top, Math.min(y, bounds.bottom - 1)); - } - } - return MotionEvent.obtain( - me.getDownTime(), me.getEventTime(), me.getAction(), pointerCount, pointerIds, - pointerCoords, me.getMetaState(), me.getXPrecision(), me.getYPrecision(), - me.getDeviceId(), me.getEdgeFlags(), me.getSource(), me.getFlags()); - } } diff --git a/core/java/android/view/InputDevice.java b/core/java/android/view/InputDevice.java index 8cb68f9..bfc7c31 100755 --- a/core/java/android/view/InputDevice.java +++ b/core/java/android/view/InputDevice.java @@ -153,7 +153,14 @@ public final class InputDevice implements Parcelable { * @see #SOURCE_CLASS_POINTER */ public static final int SOURCE_MOUSE = 0x00002000 | SOURCE_CLASS_POINTER; - + + /** + * The input source is a stylus pointing device. + * + * @see #SOURCE_CLASS_POINTER + */ + public static final int SOURCE_STYLUS = 0x00004000 | SOURCE_CLASS_POINTER; + /** * The input source is a trackball. * @@ -585,6 +592,7 @@ public final class InputDevice implements Parcelable { appendSourceDescriptionIfApplicable(description, SOURCE_DPAD, "dpad"); appendSourceDescriptionIfApplicable(description, SOURCE_TOUCHSCREEN, "touchscreen"); appendSourceDescriptionIfApplicable(description, SOURCE_MOUSE, "mouse"); + appendSourceDescriptionIfApplicable(description, SOURCE_STYLUS, "stylus"); appendSourceDescriptionIfApplicable(description, SOURCE_TRACKBALL, "trackball"); appendSourceDescriptionIfApplicable(description, SOURCE_TOUCHPAD, "touchpad"); appendSourceDescriptionIfApplicable(description, SOURCE_JOYSTICK, "joystick"); diff --git a/core/java/android/view/KeyEvent.java b/core/java/android/view/KeyEvent.java index 13d8809..5dbda90 100755 --- a/core/java/android/view/KeyEvent.java +++ b/core/java/android/view/KeyEvent.java @@ -2672,15 +2672,22 @@ public class KeyEvent extends InputEvent implements Parcelable { @Override public String toString() { - return "KeyEvent{action=" + actionToString(mAction) - + " keycode=" + keyCodeToString(mKeyCode) - + " scancode=" + mScanCode - + " metaState=" + metaStateToString(mMetaState) - + " flags=0x" + Integer.toHexString(mFlags) - + " repeat=" + mRepeatCount - + " device=" + mDeviceId - + " source=0x" + Integer.toHexString(mSource) - + "}"; + StringBuilder msg = new StringBuilder(); + msg.append("KeyEvent { action=").append(actionToString(mAction)); + msg.append(", keyCode=").append(keyCodeToString(mKeyCode)); + msg.append(", scanCode=").append(mScanCode); + if (mCharacters != null) { + msg.append(", characters=\"").append(mCharacters).append("\""); + } + msg.append(", metaState=").append(metaStateToString(mMetaState)); + msg.append(", flags=0x").append(Integer.toHexString(mFlags)); + msg.append(", repeatCount=").append(mRepeatCount); + msg.append(", eventTime=").append(mEventTime); + msg.append(", downTime=").append(mDownTime); + msg.append(", deviceId=").append(mDeviceId); + msg.append(", source=0x").append(Integer.toHexString(mSource)); + msg.append(" }"); + return msg.toString(); } /** diff --git a/core/java/android/view/MotionEvent.java b/core/java/android/view/MotionEvent.java index 7611b08..82fd581 100644 --- a/core/java/android/view/MotionEvent.java +++ b/core/java/android/view/MotionEvent.java @@ -23,53 +23,60 @@ import android.os.SystemClock; import android.util.SparseArray; /** - * Object used to report movement (mouse, pen, finger, trackball) events. This - * class may hold either absolute or relative movements, depending on what - * it is being used for. + * Object used to report movement (mouse, pen, finger, trackball) events. + * Motion events may hold either absolute or relative movements and other data, + * depending on the type of device. + * + *

Overview

*

- * On pointing devices with source class {@link InputDevice#SOURCE_CLASS_POINTER} - * such as touch screens, the pointer coordinates specify absolute - * positions such as view X/Y coordinates. Each complete gesture is represented - * by a sequence of motion events with actions that describe pointer state transitions - * and movements. A gesture starts with a motion event with {@link #ACTION_DOWN} - * that provides the location of the first pointer down. As each additional - * pointer that goes down or up, the framework will generate a motion event with - * {@link #ACTION_POINTER_DOWN} or {@link #ACTION_POINTER_UP} accordingly. - * Pointer movements are described by motion events with {@link #ACTION_MOVE}. - * Finally, a gesture end either when the final pointer goes up as represented - * by a motion event with {@link #ACTION_UP} or when gesture is canceled - * with {@link #ACTION_CANCEL}. + * Motion events describe movements in terms of an action code and a set of axis values. + * The action code specifies the state change that occurred such as a pointer going + * down or up. The axis values describe the position and other movement properties. *

- * Some pointing devices such as mice may support vertical and/or horizontal scrolling. - * A scroll event is reported as a generic motion event with {@link #ACTION_SCROLL} that - * includes the relative scroll offset in the {@link #AXIS_VSCROLL} and - * {@link #AXIS_HSCROLL} axes. See {@link #getAxisValue(int)} for information - * about retrieving these additional axes. + * For example, when the user first touches the screen, the system delivers a touch + * event to the appropriate {@link View} with the action code {@link #ACTION_DOWN} + * and a set of axis values that include the X and Y coordinates of the touch and + * information about the pressure, size and orientation of the contact area. *

- * On trackball devices with source class {@link InputDevice#SOURCE_CLASS_TRACKBALL}, - * the pointer coordinates specify relative movements as X/Y deltas. - * A trackball gesture consists of a sequence of movements described by motion - * events with {@link #ACTION_MOVE} interspersed with occasional {@link #ACTION_DOWN} - * or {@link #ACTION_UP} motion events when the trackball button is pressed or released. + * Some devices can report multiple movement traces at the same time. Multi-touch + * screens emit one movement trace for each finger. The individual fingers or + * other objects that generate movement traces are referred to as pointers. + * Motion events contain information about all of the pointers that are currently active + * even if some of them have not moved since the last event was delivered. *

- * On joystick devices with source class {@link InputDevice#SOURCE_CLASS_JOYSTICK}, - * the pointer coordinates specify the absolute position of the joystick axes. - * The joystick axis values are normalized to a range of -1.0 to 1.0 where 0.0 corresponds - * to the center position. More information about the set of available axes and the - * range of motion can be obtained using {@link InputDevice#getMotionRange}. - * Some common joystick axes are {@link #AXIS_X}, {@link #AXIS_Y}, - * {@link #AXIS_HAT_X}, {@link #AXIS_HAT_Y}, {@link #AXIS_Z} and {@link #AXIS_RZ}. - *

- * Motion events always report movements for all pointers at once. The number - * of pointers only ever changes by one as individual pointers go up and down, + * The number of pointers only ever changes by one as individual pointers go up and down, * except when the gesture is canceled. *

- * The order in which individual pointers appear within a motion event can change - * from one event to the next. Use the {@link #getPointerId(int)} method to obtain a - * pointer id to track pointers across motion events in a gesture. Then for - * successive motion events, use the {@link #findPointerIndex(int)} method to obtain - * the pointer index for a given pointer id in that motion event. + * Each pointer has a unique id that is assigned when it first goes down + * (indicated by {@link #ACTION_DOWN} or {@link #ACTION_POINTER_DOWN}). A pointer id + * remains valid until the pointer eventually goes up (indicated by {@link #ACTION_UP} + * or {@link #ACTION_POINTER_UP}) or when the gesture is canceled (indicated by + * {@link #ACTION_CANCEL}). + *

+ * The MotionEvent class provides many methods to query the position and other properties of + * pointers, such as {@link #getX(int)}, {@link #getY(int)}, {@link #getAxisValue}, + * {@link #getPointerId(int)}, {@link #getToolType(int)}, and many others. Most of these + * methods accept the pointer index as a parameter rather than the pointer id. + * The pointer index of each pointer in the event ranges from 0 to one less than the value + * returned by {@link #getPointerCount()}. *

+ * The order in which individual pointers appear within a motion event is undefined. + * Thus the pointer index of a pointer can change from one event to the next but + * the pointer id of a pointer is guaranteed to remain constant as long as the pointer + * remains active. Use the {@link #getPointerId(int)} method to obtain the + * pointer id of a pointer to track it across all subsequent motion events in a gesture. + * Then for successive motion events, use the {@link #findPointerIndex(int)} method + * to obtain the pointer index for a given pointer id in that motion event. + *

+ * Mouse and stylus buttons can be retrieved using {@link #getButtonState()}. It is a + * good idea to check the button state while handling {@link #ACTION_DOWN} as part + * of a touch event. The application may choose to perform some different action + * if the touch event starts due to a secondary button click, such as presenting a + * context menu. + *

+ * + *

Batching

+ *

* For efficiency, motion events with {@link #ACTION_MOVE} may batch together * multiple movement samples within a single object. The most current * pointer coordinates are available using {@link #getX(int)} and {@link #getY(int)}. @@ -98,42 +105,104 @@ import android.util.SparseArray; * ev.getPointerId(p), ev.getX(p), ev.getY(p)); * } * } - *

- * In general, the framework cannot guarantee that the motion events it delivers - * to a view always constitute a complete motion sequences since some events may be dropped - * or modified by containing views before they are delivered. The view implementation - * should be prepared to handle {@link #ACTION_CANCEL} and should tolerate anomalous - * situations such as receiving a new {@link #ACTION_DOWN} without first having - * received an {@link #ACTION_UP} for the prior gesture. + *

+ * + *

Device Types

+ *

+ * The interpretation of the contents of a MotionEvent varies significantly depending + * on the source class of the device. + *

+ * On pointing devices with source class {@link InputDevice#SOURCE_CLASS_POINTER} + * such as touch screens, the pointer coordinates specify absolute + * positions such as view X/Y coordinates. Each complete gesture is represented + * by a sequence of motion events with actions that describe pointer state transitions + * and movements. A gesture starts with a motion event with {@link #ACTION_DOWN} + * that provides the location of the first pointer down. As each additional + * pointer that goes down or up, the framework will generate a motion event with + * {@link #ACTION_POINTER_DOWN} or {@link #ACTION_POINTER_UP} accordingly. + * Pointer movements are described by motion events with {@link #ACTION_MOVE}. + * Finally, a gesture end either when the final pointer goes up as represented + * by a motion event with {@link #ACTION_UP} or when gesture is canceled + * with {@link #ACTION_CANCEL}. + *

+ * Some pointing devices such as mice may support vertical and/or horizontal scrolling. + * A scroll event is reported as a generic motion event with {@link #ACTION_SCROLL} that + * includes the relative scroll offset in the {@link #AXIS_VSCROLL} and + * {@link #AXIS_HSCROLL} axes. See {@link #getAxisValue(int)} for information + * about retrieving these additional axes. + *

+ * On trackball devices with source class {@link InputDevice#SOURCE_CLASS_TRACKBALL}, + * the pointer coordinates specify relative movements as X/Y deltas. + * A trackball gesture consists of a sequence of movements described by motion + * events with {@link #ACTION_MOVE} interspersed with occasional {@link #ACTION_DOWN} + * or {@link #ACTION_UP} motion events when the trackball button is pressed or released. + *

+ * On joystick devices with source class {@link InputDevice#SOURCE_CLASS_JOYSTICK}, + * the pointer coordinates specify the absolute position of the joystick axes. + * The joystick axis values are normalized to a range of -1.0 to 1.0 where 0.0 corresponds + * to the center position. More information about the set of available axes and the + * range of motion can be obtained using {@link InputDevice#getMotionRange}. + * Some common joystick axes are {@link #AXIS_X}, {@link #AXIS_Y}, + * {@link #AXIS_HAT_X}, {@link #AXIS_HAT_Y}, {@link #AXIS_Z} and {@link #AXIS_RZ}. *

* Refer to {@link InputDevice} for more information about how different kinds of * input devices and sources represent pointer coordinates. *

+ * + *

Consistency Guarantees

+ *

+ * Motion events are always delivered to views as a consistent stream of events. + * What constitutes a consistent stream varies depending on the type of device. + * For touch events, consistency implies that pointers go down one at a time, + * move around as a group and then go up one at a time or are canceled. + *

+ * While the framework tries to deliver consistent streams of motion events to + * views, it cannot guarantee it. Some events may be dropped or modified by + * containing views in the application before they are delivered thereby making + * the stream of events inconsistent. Views should always be prepared to + * handle {@link #ACTION_CANCEL} and should tolerate anomalous + * situations such as receiving a new {@link #ACTION_DOWN} without first having + * received an {@link #ACTION_UP} for the prior gesture. + *

*/ public final class MotionEvent extends InputEvent implements Parcelable { private static final long NS_PER_MS = 1000000; private static final boolean TRACK_RECYCLED_LOCATION = false; - + + /** + * An invalid pointer id. + * + * This value (-1) can be used as a placeholder to indicate that a pointer id + * has not been assigned or is not available. It cannot appear as + * a pointer id inside a {@link MotionEvent}. + */ + public static final int INVALID_POINTER_ID = -1; + /** * Bit mask of the parts of the action code that are the action itself. */ public static final int ACTION_MASK = 0xff; /** - * Constant for {@link #getAction}: A pressed gesture has started, the + * Constant for {@link #getActionMasked}: A pressed gesture has started, the * motion contains the initial starting location. + *

+ * This is also a good time to check the button state to distinguish + * secondary and tertiary button clicks and handle them appropriately. + * Use {@link #getButtonState} to retrieve the button state. + *

*/ public static final int ACTION_DOWN = 0; /** - * Constant for {@link #getAction}: A pressed gesture has finished, the + * Constant for {@link #getActionMasked}: A pressed gesture has finished, the * motion contains the final release location as well as any intermediate * points since the last down or move event. */ public static final int ACTION_UP = 1; /** - * Constant for {@link #getAction}: A change has happened during a + * Constant for {@link #getActionMasked}: A change has happened during a * press gesture (between {@link #ACTION_DOWN} and {@link #ACTION_UP}). * The motion contains the most recent point, as well as any intermediate * points since the last down or move event. @@ -141,33 +210,43 @@ public final class MotionEvent extends InputEvent implements Parcelable { public static final int ACTION_MOVE = 2; /** - * Constant for {@link #getAction}: The current gesture has been aborted. + * Constant for {@link #getActionMasked}: The current gesture has been aborted. * You will not receive any more points in it. You should treat this as * an up event, but not perform any action that you normally would. */ public static final int ACTION_CANCEL = 3; /** - * Constant for {@link #getAction}: A movement has happened outside of the + * Constant for {@link #getActionMasked}: A movement has happened outside of the * normal bounds of the UI element. This does not provide a full gesture, * but only the initial location of the movement/touch. */ public static final int ACTION_OUTSIDE = 4; /** - * A non-primary pointer has gone down. The bits in - * {@link #ACTION_POINTER_ID_MASK} indicate which pointer changed. + * Constant for {@link #getActionMasked}: A non-primary pointer has gone down. + *

+ * Use {@link #getActionIndex} to retrieve the index of the pointer that changed. + *

+ * The index is encoded in the {@link #ACTION_POINTER_INDEX_MASK} bits of the + * unmasked action returned by {@link #getAction}. + *

*/ public static final int ACTION_POINTER_DOWN = 5; /** - * A non-primary pointer has gone up. The bits in - * {@link #ACTION_POINTER_ID_MASK} indicate which pointer changed. + * Constant for {@link #getActionMasked}: A non-primary pointer has gone up. + *

+ * Use {@link #getActionIndex} to retrieve the index of the pointer that changed. + *

+ * The index is encoded in the {@link #ACTION_POINTER_INDEX_MASK} bits of the + * unmasked action returned by {@link #getAction}. + *

*/ public static final int ACTION_POINTER_UP = 6; /** - * Constant for {@link #getAction}: A change happened but the pointer + * Constant for {@link #getActionMasked}: A change happened but the pointer * is not down (unlike {@link #ACTION_MOVE}). The motion contains the most * recent point, as well as any intermediate points since the last * hover move event. @@ -182,14 +261,14 @@ public final class MotionEvent extends InputEvent implements Parcelable { public static final int ACTION_HOVER_MOVE = 7; /** - * Constant for {@link #getAction}: The motion event contains relative + * Constant for {@link #getActionMasked}: The motion event contains relative * vertical and/or horizontal scroll offsets. Use {@link #getAxisValue(int)} * to retrieve the information from {@link #AXIS_VSCROLL} and {@link #AXIS_HSCROLL}. * The pointer may or may not be down when this event is dispatched. - *

+ *

* This action is always delivered to the window or view under the pointer, which * may not be the window or view currently touched. - *

+ *

* This action is not a touch event so it is delivered to * {@link View#onGenericMotionEvent(MotionEvent)} rather than * {@link View#onTouchEvent(MotionEvent)}. @@ -198,7 +277,7 @@ public final class MotionEvent extends InputEvent implements Parcelable { public static final int ACTION_SCROLL = 8; /** - * Constant for {@link #getAction}: The pointer is not down but has entered the + * Constant for {@link #getActionMasked}: The pointer is not down but has entered the * boundaries of a window or view. *

* This action is always delivered to the window or view under the pointer. @@ -211,7 +290,7 @@ public final class MotionEvent extends InputEvent implements Parcelable { public static final int ACTION_HOVER_ENTER = 9; /** - * Constant for {@link #getAction}: The pointer is not down but has exited the + * Constant for {@link #getActionMasked}: The pointer is not down but has exited the * boundaries of a window or view. *

* This action is always delivered to the window or view that was previously under the pointer. @@ -230,15 +309,19 @@ public final class MotionEvent extends InputEvent implements Parcelable { * index where the data for the pointer going up or down can be found; you can * get its identifier with {@link #getPointerId(int)} and the actual * data with {@link #getX(int)} etc. + * + * @see #getActionIndex */ public static final int ACTION_POINTER_INDEX_MASK = 0xff00; /** * Bit shift for the action bits holding the pointer index as * defined by {@link #ACTION_POINTER_INDEX_MASK}. + * + * @see #getActionIndex */ public static final int ACTION_POINTER_INDEX_SHIFT = 8; - + /** * @deprecated Use {@link #ACTION_POINTER_INDEX_MASK} to retrieve the * data index associated with {@link #ACTION_POINTER_DOWN}. @@ -339,7 +422,7 @@ public final class MotionEvent extends InputEvent implements Parcelable { public static final int EDGE_RIGHT = 0x00000008; /** - * Constant used to identify the X axis of a motion event. + * Axis constant: X axis of a motion event. *

*