This browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
Download Microsoft Edge
More info about Internet Explorer and Microsoft Edge
[Android.Runtime.Register("android/view/MotionEvent", DoNotGenerateAcw=true)]
public sealed class MotionEvent : Android.Views.InputEvent, IDisposable, Java.Interop.IJavaPeerable
[<Android.Runtime.Register("android/view/MotionEvent", DoNotGenerateAcw=true)>]
type MotionEvent = class
inherit InputEvent
interface IParcelable
interface IJavaObject
interface IDisposable
interface IJavaPeerable
Inheritance
MotionEvent
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.
<h3>Overview</h3>
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
View
with the action code
#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 <em>pointers</em>. 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
#ACTION_DOWN
or
#ACTION_POINTER_DOWN
). A pointer id remains valid until the pointer eventually goes up (indicated by
#ACTION_UP
or
#ACTION_POINTER_UP
) or when the gesture is canceled (indicated by
#ACTION_CANCEL
).
The MotionEvent class provides many methods to query the position and other properties of pointers, such as
#getX(int)
,
#getY(int)
,
#getAxisValue
,
#getPointerId(int)
,
#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
#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
#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
#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
#getButtonState()
. It is a good idea to check the button state while handling
#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.
<h3>Batching</h3>
For efficiency, motion events with
#ACTION_MOVE
may batch together multiple movement samples within a single object. The most current pointer coordinates are available using
#getX(int)
and
#getY(int)
. Earlier coordinates within the batch are accessed using
#getHistoricalX(int, int)
and
#getHistoricalY(int, int)
. 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.
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));
</code>
</p>
<h3>Device Types</h3>
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#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
#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
#ACTION_POINTER_DOWN
or
#ACTION_POINTER_UP
accordingly. Pointer movements are described by motion events with
#ACTION_MOVE
. Finally, a gesture end either when the final pointer goes up as represented by a motion event with
#ACTION_UP
or when gesture is canceled with
#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
#ACTION_SCROLL
that includes the relative scroll offset in the
#AXIS_VSCROLL
and
#AXIS_HSCROLL
axes. See
#getAxisValue(int)
for information about retrieving these additional axes.
On trackball devices with source class
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
#ACTION_MOVE
interspersed with occasional
#ACTION_DOWN
or
#ACTION_UP
motion events when the trackball button is pressed or released.
On joystick devices with source class
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
InputDevice#getMotionRange
. Some common joystick axes are
#AXIS_X
,
#AXIS_Y
,
#AXIS_HAT_X
,
#AXIS_HAT_Y
,
#AXIS_Z
and
#AXIS_RZ
.
Refer to
InputDevice
for more information about how different kinds of input devices and sources represent pointer coordinates.
<h3>Consistency Guarantees</h3>
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
#ACTION_CANCEL
and should tolerate anomalous situations such as receiving a new
#ACTION_DOWN
without first having received an
#ACTION_UP
for the prior gesture.
Java documentation for
android.view.MotionEvent
.
Portions of this page are modifications based on work created and shared by the
Android Open Source Project
and used according to terms described in the
Creative Commons 2.5 Attribution License.
This flag indicates that the window that received this motion event is partly
or wholly obscured by another visible window above it and the event directly passed through
the obscured area.
This flag indicates that the window that received this motion event is partly
or wholly obscured by another visible window above it and the event did not directly pass
through the obscured area.
For
#ACTION_POINTER_DOWN
or
#ACTION_POINTER_UP
as returned by
#getActionMasked
, this returns the associated
pointer index.
Returns a bitfield indicating which edges, if any, were touched by this
MotionEvent. -or- Sets the bitfield indicating which edges, if any, were touched by this
MotionEvent.
Retrieve the time this event occurred,
in the
android.os.SystemClock#uptimeMillis
time base but with
nanosecond precision.
This API supports the Mono for Android infrastructure and is not intended to be used directly from your code.
(Inherited from
InputEvent
)
This API supports the Mono for Android infrastructure and is not intended to be used directly from your code.
(Inherited from
InputEvent
)
Returns a string that represents the symbolic name of the specified unmasked action
such as "ACTION_DOWN", "ACTION_POINTER_DOWN(3)" or an equivalent numeric constant
such as "35" if unknown.
Describe the kinds of special objects contained in this Parcelable's
marshalled representation.
(Inherited from
InputEvent
)
Returns the time that a historical movement occurred between this event
and the previous event, in the
android.os.SystemClock#uptimeMillis
time base
but with nanosecond (instead of millisecond) precision.
Populates a
PointerCoords
object with historical pointer coordinate data,
as per
#getPointerCoords
, that occurred between this event and the previous
event for the given pointer.
Returns a historical pressure coordinate, as per
#getPressure(int)
,
that occurred between this event and the previous event for the given
pointer.
Returns the orientation of the touch area and tool area in radians clockwise from vertical
for the given pointer <em>index</em> (use
#getPointerId(int)
to find the pointer
identifier for this index).
Returns the current pressure of this event for the given pointer
<em>index</em> (use
#getPointerId(int)
to find the pointer
identifier for this index).
Returns a scaled value of the approximate size for the given pointer
<em>index</em> (use
#getPointerId(int)
to find the pointer
identifier for this index).
Returns the length of the major axis of an ellipse that describes the size of
the approaching tool for the given pointer
<em>index</em> (use
#getPointerId(int)
to find the pointer
identifier for this index).
Returns the length of the minor axis of an ellipse that describes the size of
the approaching tool for the given pointer
<em>index</em> (use
#getPointerId(int)
to find the pointer
identifier for this index).
Returns the length of the major axis of an ellipse that describes the touch
area at the point of contact for the given pointer
<em>index</em> (use
#getPointerId(int)
to find the pointer
identifier for this index).
Returns the length of the minor axis of an ellipse that describes the touch
area at the point of contact for the given pointer
<em>index</em> (use
#getPointerId(int)
to find the pointer
identifier for this index).
Called by the garbage collector on an object when garbage collection
determines that there are no more references to the object.
(Inherited from
Object
)
Obtain(Int64, Int64, MotionEventActions, Int32, Int32[], MotionEvent+PointerCoords[],
MetaKeyStates, Single, Single, Int32, Edge, InputSourceType,
MotionEventFlags)
Obtain(Int64, Int64, MotionEventActions, Int32, MotionEvent+PointerProperties[],
MotionEvent+PointerCoords[], MetaKeyStates, MotionEventButtonState,
Single, Single, Int32, Edge, InputSourceType, Int32, MotionEventFlags,
ClassificationMode)
Obtain(Int64, Int64, MotionEventActions, Int32, MotionEvent+PointerProperties[],
MotionEvent+PointerCoords[], MetaKeyStates, MotionEventButtonState,
Single, Single, Int32, Edge, InputSourceType, MotionEventFlags)
Create a new MotionEvent, filling in all of the basic values that
define the motion.
Causes the current thread to wait until it is awakened, typically
by being <em>notified</em> or <em>interrupted</em>.
(Inherited from
Object
)
Causes the current thread to wait until it is awakened, typically
by being <em>notified</em> or <em>interrupted</em>, or until a
certain amount of real time has elapsed.
(Inherited from
Object
)
Causes the current thread to wait until it is awakened, typically
by being <em>notified</em> or <em>interrupted</em>, or until a
certain amount of real time has elapsed.
(Inherited from
Object
)
