See Also: MotionEvent Members
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.
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.
For example, when the user first touches the screen, the system delivers a touch event to the appropriate Android.Views.View with the action code MotionEvent.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.
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.
The number of pointers only ever changes by one as individual pointers go up and down, except when the gesture is canceled.
Each pointer has a unique id that is assigned when it first goes down (indicated by MotionEvent.ACTION_DOWN or MotionEvent.ACTION_POINTER_DOWN). A pointer id remains valid until the pointer eventually goes up (indicated by MotionEvent.ACTION_UP or MotionEvent.ACTION_POINTER_UP) or when the gesture is canceled (indicated by MotionEvent.ACTION_CANCEL).
The MotionEvent class provides many methods to query the position and other properties of pointers, such as MotionEvent.GetX(int), MotionEvent.GetY(int), MotionEvent.GetAxisValue(Axis), MotionEvent.GetPointerId(int), MotionEvent.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 MotionEvent.PointerCount.
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 MotionEvent.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 MotionEvent.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 MotionEvent.ButtonState. It is a good idea to check the button state while handling MotionEvent.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.
For efficiency, motion events with MotionEvent.ACTION_MOVE may batch together multiple movement samples within a single object. The most current pointer coordinates are available using MotionEvent.GetX(int) and MotionEvent.GetY(int). Earlier coordinates within the batch are accessed using MotionEvent.GetHistoricalX(int, System.Int32) and MotionEvent.GetHistoricalY(int, System.Int32). The coordinates are "historical" only insofar as they are older than the current coordinates in the batch; however, they are still distinct from any other coordinates reported in prior motion events. To process all coordinates in the batch in time order, first consume the historical coordinates then consume the current coordinates.
Example: Consuming all samples for all pointers in a motion event in time order.
java Example
void printSamples(MotionEvent ev) {
final int historySize = ev.getHistorySize();
final int pointerCount = ev.getPointerCount();
for (int h = 0; h < historySize; h++) {
System.out.printf("At time %d:", ev.getHistoricalEventTime(h));
for (int p = 0; p < pointerCount; p++) {
System.out.printf(" pointer %d: (%f,%f)",
ev.getPointerId(p), ev.getHistoricalX(p, h), ev.getHistoricalY(p, h));
}
}
System.out.printf("At time %d:", ev.getEventTime());
for (int p = 0; p < pointerCount; p++) {
System.out.printf(" pointer %d: (%f,%f)",
ev.getPointerId(p), ev.getX(p), ev.getY(p));
}
}
The interpretation of the contents of a MotionEvent varies significantly depending on the source class of the device.
On pointing devices with source class InputDevice.SourceClassPointer 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 MotionEvent.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 MotionEvent.ACTION_POINTER_DOWN or MotionEvent.ACTION_POINTER_UP accordingly. Pointer movements are described by motion events with MotionEvent.ACTION_MOVE. Finally, a gesture end either when the final pointer goes up as represented by a motion event with MotionEvent.ACTION_UP or when gesture is canceled with MotionEvent.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 MotionEvent.ACTION_SCROLL that includes the relative scroll offset in the MotionEvent.AXIS_VSCROLL and MotionEvent.AXIS_HSCROLL axes. See MotionEvent.GetAxisValue(Axis) for information about retrieving these additional axes.
On trackball devices with source class InputDevice.SourceClassTrackball, the pointer coordinates specify relative movements as X/Y deltas. A trackball gesture consists of a sequence of movements described by motion events with MotionEvent.ACTION_MOVE interspersed with occasional MotionEvent.ACTION_DOWN or MotionEvent.ACTION_UP motion events when the trackball button is pressed or released.
On joystick devices with source class InputDevice.SourceClassJoystick, 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 InputDevice.GetMotionRange(Axis). Some common joystick axes are MotionEvent.AXIS_X, MotionEvent.AXIS_Y, MotionEvent.AXIS_HAT_X, MotionEvent.AXIS_HAT_Y, MotionEvent.AXIS_Z and MotionEvent.AXIS_RZ.
Refer to Android.Views.InputDevice for more information about how different kinds of input devices and sources represent pointer coordinates.
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 MotionEvent.ACTION_CANCEL and should tolerate anomalous situations such as receiving a new MotionEvent.ACTION_DOWN without first having received an MotionEvent.ACTION_UP for the prior gesture.