MotionEvent Class

Reference

Definition

Namespace:: Android.Views

Assembly:: Mono.Android.dll

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Object used to report movement (mouse, pen, finger, trackball) events.

[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: Object

Object

InputEvent
MotionEvent

Attributes: RegisterAttribute

Implements: IParcelable IJavaObject IJavaPeerable IDisposable

Remarks

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.

<code>
            void printSamples(MotionEvent ev) {
                final int historySize = ev.getHistorySize();
                final int pointerCount = ev.getPointerCount();
                for (int h = 0; h &lt; historySize; h++) {
                    System.out.printf("At time %d:", ev.getHistoricalEventTime(h));
                    for (int p = 0; p &lt; 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 &lt; 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.

Fields

AxisGesturePinchScaleFactor	Obsolete. Axis constant: pinch scale factor of a motion event.
AxisGestureScrollXDistance	Obsolete. Axis constant: X scroll distance axis of a motion event.
AxisGestureScrollYDistance	Obsolete. Axis constant: Y scroll distance axis of a motion event.
AxisGestureXOffset	Obsolete. Axis constant: X gesture offset axis of a motion event.
AxisGestureYOffset	Obsolete. Axis constant: Y gesture offset axis of a motion event.
ButtonBack	Obsolete. Button constant: Back button pressed (mouse back button).
ButtonForward	Obsolete. Button constant: Forward button pressed (mouse forward button).
ButtonPrimary	Obsolete. Button constant: Primary button (left mouse button).
ButtonSecondary	Obsolete. Button constant: Secondary button (right mouse button).
ButtonStylusPrimary	Obsolete. Button constant: Primary stylus button pressed.
ButtonStylusSecondary	Obsolete. Button constant: Secondary stylus button pressed.
ButtonTertiary	Obsolete. Button constant: Tertiary button (middle mouse button).
ClassificationAmbiguousGesture	Obsolete. Classification constant: Ambiguous gesture.
ClassificationDeepPress	Obsolete. Classification constant: Deep press.
ClassificationNone	Obsolete. Classification constant: None.
ClassificationPinch	Obsolete. Classification constant: touchpad pinch.
ClassificationTwoFingerSwipe	Obsolete. Classification constant: touchpad scroll.
FlagCanceled	This flag is only set for events with `#ACTION_POINTER_UP` and `#ACTION_CANCEL`.
FlagWindowIsObscured	Obsolete. 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.
FlagWindowIsPartiallyObscured	Obsolete. 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.
InvalidPointerId	An invalid pointer id.
ToolTypeEraser	Obsolete. Tool type constant: The tool is an eraser or a stylus being used in an inverted posture.
ToolTypeFinger	Obsolete. Tool type constant: The tool is a finger.
ToolTypeMouse	Obsolete. Tool type constant: The tool is a mouse.
ToolTypeStylus	Obsolete. Tool type constant: The tool is a stylus.
ToolTypeUnknown	Obsolete. Tool type constant: Unknown tool type.

Properties

Action	Return the kind of action being performed. -or- Sets this event's action.
ActionButton	Gets which button has been modified during a press or release action.
ActionIndex	For `#ACTION_POINTER_DOWN` or `#ACTION_POINTER_UP` as returned by `#getActionMasked`, this returns the associated pointer index.
ActionMasked	Return the masked action being performed, without pointer index information.
ButtonState	Gets the state of all buttons that are pressed such as a mouse or stylus button.
Class	Returns the runtime class of this `Object`. (Inherited from Object)
Classification	Returns the classification for the current gesture.
Creator
Device	Gets the device that this event came from. (Inherited from InputEvent)
DeviceId	To be added
DownTime	Returns the time (in ms) when the user originally pressed down to start a stream of position events.
EdgeFlags	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.
EventTime	Retrieve the time this event occurred, in the `android.os.SystemClock#uptimeMillis` time base.
EventTimeNanos	Retrieve the time this event occurred, in the `android.os.SystemClock#uptimeMillis` time base but with nanosecond precision.
Flags	Gets the motion event flags.
Handle	The handle to the underlying Android instance. (Inherited from Object)
HistorySize	Returns the number of historical points in this event.
JniIdentityHashCode	(Inherited from Object)
JniPeerMembers
MetaState	Returns the state of any meta / modifier keys that were in effect when the event was generated.
Orientation	`#getOrientation(int)` for the first pointer index (may be an arbitrary pointer identifier).
PeerReference	(Inherited from Object)
PointerCount	The number of pointers of data contained in this event.
Pressure	`#getPressure(int)` for the first pointer index (may be an arbitrary pointer identifier).
RawX	Equivalent to `#getRawX(int)` for pointer index 0 (regardless of the pointer identifier).
RawY	Equivalent to `#getRawY(int)` for pointer index 0 (regardless of the pointer identifier).
Size	`#getSize(int)` for the first pointer index (may be an arbitrary pointer identifier).
Source	To be added
ThresholdClass	This API supports the Mono for Android infrastructure and is not intended to be used directly from your code. (Inherited from InputEvent)
ThresholdType	This API supports the Mono for Android infrastructure and is not intended to be used directly from your code. (Inherited from InputEvent)
ToolMajor	`#getToolMajor(int)` for the first pointer index (may be an arbitrary pointer identifier).
ToolMinor	`#getToolMinor(int)` for the first pointer index (may be an arbitrary pointer identifier).
TouchMajor	`#getTouchMajor(int)` for the first pointer index (may be an arbitrary pointer identifier).
TouchMinor	`#getTouchMinor(int)` for the first pointer index (may be an arbitrary pointer identifier).
XPrecision	Return the precision of the X coordinates being reported.
YPrecision	Return the precision of the Y coordinates being reported.

Methods

ActionToString(MotionEventActions)	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.
AddBatch(Int64, MotionEvent+PointerCoords[], MetaKeyStates)	Add a new movement to the batch of movements in this event.
AddBatch(Int64, Single, Single, Single, Single, MetaKeyStates)	Add a new movement to the batch of movements in this event.
AxisFromString(String)	Gets an axis by its symbolic name such as "AXIS_X" or an equivalent numeric constant such as "42".
AxisToString(Axis)	Returns a string that represents the symbolic name of the specified axis such as "AXIS_X" or an equivalent numeric constant such as "42" if unknown.
Clone()	Creates and returns a copy of this object. (Inherited from Object)
DescribeContents()	Describe the kinds of special objects contained in this Parcelable's marshalled representation. (Inherited from InputEvent)
Dispose()	(Inherited from Object)
Dispose(Boolean)	(Inherited from Object)
Equals(Object)	Indicates whether some other object is "equal to" this one. (Inherited from Object)
FindPointerIndex(Int32)	Given a pointer identifier, find the index of its data in the event.
GetAxisValue(Axis, Int32)	Returns the value of the requested axis for the given pointer <em>index</em> (use `#getPointerId(int)` to find the pointer identifier for this index).
GetAxisValue(Axis)	`#getAxisValue(int)` for the first pointer index (may be an arbitrary pointer identifier).
GetHashCode()	Returns a hash code value for the object. (Inherited from Object)
GetHistoricalAxisValue(Axis, Int32, Int32)	Returns the historical value of the requested axis, as per `#getAxisValue(int, int)`, occurred between this event and the previous event for the given pointer.
GetHistoricalAxisValue(Axis, Int32)	`#getHistoricalAxisValue(int, int, int)` for the first pointer index (may be an arbitrary pointer identifier).
GetHistoricalEventTime(Int32)	Returns the time that a historical movement occurred between this event and the previous event, in the `android.os.SystemClock#uptimeMillis` time base.
GetHistoricalEventTimeNanos(Int32)	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.
GetHistoricalOrientation(Int32, Int32)	Returns a historical orientation coordinate, as per `#getOrientation(int)`, that occurred between this event and the previous event for the given pointer.
GetHistoricalOrientation(Int32)	`#getHistoricalOrientation(int, int)` for the first pointer index (may be an arbitrary pointer identifier).
GetHistoricalPointerCoords(Int32, Int32, MotionEvent+PointerCoords)	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.
GetHistoricalPressure(Int32, Int32)	Returns a historical pressure coordinate, as per `#getPressure(int)`, that occurred between this event and the previous event for the given pointer.
GetHistoricalPressure(Int32)	`#getHistoricalPressure(int, int)` for the first pointer index (may be an arbitrary pointer identifier).
GetHistoricalSize(Int32, Int32)	Returns a historical size coordinate, as per `#getSize(int)`, that occurred between this event and the previous event for the given pointer.
GetHistoricalSize(Int32)	`#getHistoricalSize(int, int)` for the first pointer index (may be an arbitrary pointer identifier).
GetHistoricalToolMajor(Int32, Int32)	Returns a historical tool major axis coordinate, as per `#getToolMajor(int)`, that occurred between this event and the previous event for the given pointer.
GetHistoricalToolMajor(Int32)	`#getHistoricalToolMajor(int, int)` for the first pointer index (may be an arbitrary pointer identifier).
GetHistoricalToolMinor(Int32, Int32)	Returns a historical tool minor axis coordinate, as per `#getToolMinor(int)`, that occurred between this event and the previous event for the given pointer.
GetHistoricalToolMinor(Int32)	`#getHistoricalToolMinor(int, int)` for the first pointer index (may be an arbitrary pointer identifier).
GetHistoricalTouchMajor(Int32, Int32)	Returns a historical touch major axis coordinate, as per `#getTouchMajor(int)`, that occurred between this event and the previous event for the given pointer.
GetHistoricalTouchMajor(Int32)	`#getHistoricalTouchMajor(int, int)` for the first pointer index (may be an arbitrary pointer identifier).
GetHistoricalTouchMinor(Int32, Int32)	Returns a historical touch minor axis coordinate, as per `#getTouchMinor(int)`, that occurred between this event and the previous event for the given pointer.
GetHistoricalTouchMinor(Int32)	`#getHistoricalTouchMinor(int, int)` for the first pointer index (may be an arbitrary pointer identifier).
GetHistoricalX(Int32, Int32)	Returns a historical X coordinate, as per `#getX(int)`, that occurred between this event and the previous event for the given pointer.
GetHistoricalX(Int32)	`#getHistoricalX(int, int)` for the first pointer index (may be an arbitrary pointer identifier).
GetHistoricalY(Int32, Int32)	Returns a historical Y coordinate, as per `#getY(int)`, that occurred between this event and the previous event for the given pointer.
GetHistoricalY(Int32)	`#getHistoricalY(int, int)` for the first pointer index (may be an arbitrary pointer identifier).
GetOrientation(Int32)	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).
GetPointerCoords(Int32, MotionEvent+PointerCoords)	Populates a `PointerCoords` object with pointer coordinate data for the specified pointer index.
GetPointerId(Int32)	Return the pointer identifier associated with a particular pointer data index in this event.
GetPointerProperties(Int32, MotionEvent+PointerProperties)	Populates a `PointerProperties` object with pointer properties for the specified pointer index.
GetPressure(Int32)	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).
GetRawX(Int32)	Returns the X coordinate of the pointer referenced by `pointerIndex` for this motion event.
GetRawY(Int32)	Returns the Y coordinate of the pointer referenced by `pointerIndex` for this motion event.
GetSize(Int32)	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).
GetToolMajor(Int32)	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).
GetToolMinor(Int32)	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).
GetToolType(Int32)	Gets the tool type of a pointer for the given pointer index.
GetTouchMajor(Int32)	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).
GetTouchMinor(Int32)	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).
GetX()	Equivalent to `#getX(int)` for pointer index 0 (regardless of the pointer identifier).
GetX(Int32)	Returns the X coordinate of the pointer referenced by `pointerIndex` for this motion event.
GetY()	Equivalent to `#getY(int)` for pointer index 0 (regardless of the pointer identifier).
GetY(Int32)	Returns the Y coordinate of the pointer referenced by `pointerIndex` for this motion event.
IsButtonPressed(MotionEventButtonState)	Checks if a mouse or stylus button (or combination of buttons) is pressed.
IsFromSource(InputSourceType)	Determines whether the event is from the given source. (Inherited from InputEvent)
JavaFinalize()	Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. (Inherited from Object)
Notify()	Wakes up a single thread that is waiting on this object's monitor. (Inherited from Object)
NotifyAll()	Wakes up all threads that are waiting on this object's monitor. (Inherited from Object)
Obtain(Int64, Int64, Int32, Int32, Int32[], MotionEvent+PointerCoords[], MetaKeyStates, Single, Single, Int32, Edge, Int32, Int32)
Obtain(Int64, Int64, Int32, Int32, Single, Single, Single, Single, MetaKeyStates, Single, Single, Int32, Edge)
Obtain(Int64, Int64, Int32, Single, Single, MetaKeyStates)
Obtain(Int64, Int64, Int32, Single, Single, Single, Single, MetaKeyStates, Single, Single, Int32, Edge)
Obtain(Int64, Int64, MotionEventActions, Int32, Int32[], MotionEvent+PointerCoords[], MetaKeyStates, Single, Single, Int32, Edge, InputSourceType, MotionEventFlags)	Obsolete. Create a new MotionEvent, filling in all of the basic values that define the motion.
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.
Obtain(Int64, Int64, MotionEventActions, Int32, Single, Single, Single, Single, MetaKeyStates, Single, Single, Int32, Edge)	Obsolete. Create a new MotionEvent, filling in all of the basic values that define the motion.
Obtain(Int64, Int64, MotionEventActions, Single, Single, MetaKeyStates)	Create a new MotionEvent, filling in a subset of the basic motion values.
Obtain(Int64, Int64, MotionEventActions, Single, Single, Single, Single, MetaKeyStates, Single, Single, Int32, Edge)	Create a new MotionEvent, filling in all of the basic values that define the motion.
Obtain(MotionEvent)	Create a new MotionEvent, copying from an existing one.
ObtainNoHistory(MotionEvent)	Create a new MotionEvent, copying from an existing one, but not including any historical point information.
OffsetLocation(Single, Single)	Adjust this event's location.
Recycle()	Recycle the MotionEvent, to be re-used by a later caller.
SetHandle(IntPtr, JniHandleOwnership)	Sets the Handle property. (Inherited from Object)
SetLocation(Single, Single)	Set this event's location.
SetSource(InputSourceType)	To be added
ToArray<T>()	(Inherited from Object)
ToString()	Returns a string representation of the object. (Inherited from Object)
Transform(Matrix)	Applies a transformation matrix to all of the points in the event.
UnregisterFromRuntime()	(Inherited from Object)
Wait()	Causes the current thread to wait until it is awakened, typically by being <em>notified</em> or <em>interrupted</em>. (Inherited from Object)
Wait(Int64, Int32)	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)
Wait(Int64)	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)
WriteToParcel(Parcel, ParcelableWriteFlags)	Flatten this object in to a Parcel.

Explicit Interface Implementations

IJavaPeerable.Disposed()	(Inherited from Object)
IJavaPeerable.DisposeUnlessReferenced()	(Inherited from Object)
IJavaPeerable.Finalized()	(Inherited from Object)
IJavaPeerable.JniManagedPeerState	(Inherited from Object)
IJavaPeerable.SetJniIdentityHashCode(Int32)	(Inherited from Object)
IJavaPeerable.SetJniManagedPeerState(JniManagedPeerStates)	(Inherited from Object)
IJavaPeerable.SetPeerReference(JniObjectReference)	(Inherited from Object)

Extension Methods

JavaCast<TResult>(IJavaObject)	Performs an Android runtime-checked type conversion.
JavaCast<TResult>(IJavaObject)
GetJniTypeName(IJavaPeerable)

Applies to

Share via