Android Guides | Samples

Android.Views.MotionEvent Class

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

See Also: MotionEvent

Syntax

[Android.Runtime.Register("android/view/MotionEvent", DoNotGenerateAcw=true)]
public sealed class MotionEvent : InputEvent, 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.

Overview

Batching

Device Types

Consistency Guarantees

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 MotionEventCompat.ActionPointerDown 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 MotionEventCompat.ActionPointerDown 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(Int32), MotionEvent.GetY(Int32), MotionEvent.GetAxisValue(Axis), MotionEvent.GetPointerId(Int32), MotionEvent.GetToolType(Int32), 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(Int32) 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(Int32) 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 MotionEventCompat.ActionPointerDown 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(Int32) and MotionEvent.GetY(Int32). Earlier coordinates within the batch are accessed using MotionEvent.GetHistoricalX(Int32,Int32) and MotionEvent.GetHistoricalY(Int32,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 MotionEventCompat.ActionPointerDown 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 MotionEventCompat.ActionPointerDown 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 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 MotionEventCompat.ActionPointerDown without first having received an MotionEvent.ACTION_UP for the prior gesture.

[Android Documentation]

Requirements

Namespace: Android.Views
Assembly: Mono.Android (in Mono.Android.dll)
Assembly Versions: 0.0.0.0
Since: Added in API level 1

The members of Android.Views.MotionEvent are listed below.

See Also: InputEvent

Public Fields

const
ButtonBackMotionEventButtonState (8). Button constant: Back button pressed (mouse back button).
const
ButtonForwardMotionEventButtonState (16). Button constant: Forward button pressed (mouse forward button).
const
ButtonPrimaryMotionEventButtonState (1). Button constant: Primary button (left mouse button).
const
ButtonSecondaryMotionEventButtonState (2). Button constant: Secondary button (right mouse button).
const
ButtonTertiaryMotionEventButtonState (4). Button constant: Tertiary button (middle mouse button).
const
FlagWindowIsObscuredMotionEventFlags (1). This flag indicates that the window that received this motion event is partly or wholly obscured by another visible window above it.
const
InvalidPointerIdInt32 (-1). An invalid pointer id.
const
ToolTypeEraserMotionEventToolType (4). Tool type constant: The tool is an eraser or a stylus being used in an inverted posture.
const
ToolTypeFingerMotionEventToolType (1). Tool type constant: The tool is a finger.
const
ToolTypeMouseMotionEventToolType (3). Tool type constant: The tool is a mouse or trackpad.
const
ToolTypeStylusMotionEventToolType (2). Tool type constant: The tool is a stylus.
const
ToolTypeUnknownMotionEventToolType (0). Tool type constant: Unknown tool type.

Public Properties

ActionMotionEventActions. Return the kind of action being performed.
[read-only]
ActionIndexInt32. For MotionEvent.ACTION_POINTER_DOWN or MotionEvent.ACTION_POINTER_UP as returned by MotionEvent.ActionMasked, this returns the associated pointer index.
[read-only]
ActionMaskedMotionEventActions. Return the masked action being performed, without pointer index information.
[read-only]
ButtonStateMotionEventButtonState. Gets the state of all buttons that are pressed such as a mouse or stylus button.
[read-only]
static
CreatorIParcelableCreator.
[read-only]
override
DeviceIdInt32. Gets the id for the device that this event came from.
[read-only]
DownTimeInt64. Returns the time (in ms) when the user originally pressed down to start a stream of position events.
EdgeFlagsEdge. Returns a bitfield indicating which edges, if any, were touched by this MotionEvent.
[read-only]
override
EventTimeInt64. Retrieve the time this event occurred, in the SystemClock.UptimeMillis time base.
[read-only]
FlagsMotionEventFlags. Gets the motion event flags.
[read-only]
HistorySizeInt32. Returns the number of historical points in this event.
[read-only]
MetaStateMetaKeyStates. Returns the state of any meta / modifier keys that were in effect when the event was generated.
[read-only]
OrientationSingle. MotionEvent.GetOrientation(Int32) for the first pointer index (may be an arbitrary pointer identifier).
[read-only]
PointerCountInt32. The number of pointers of data contained in this event.
[read-only]
PressureSingle. MotionEvent.GetPressure(Int32) for the first pointer index (may be an arbitrary pointer identifier).
[read-only]
RawXSingle. Returns the original raw X coordinate of this event.
[read-only]
RawYSingle. Returns the original raw Y coordinate of this event.
[read-only]
SizeSingle. MotionEvent.GetSize(Int32) for the first pointer index (may be an arbitrary pointer identifier).
[read-only]
override
SourceInputSourceType. Gets the source of the event.
[read-only]
ToolMajorSingle. MotionEvent.GetToolMajor(Int32) for the first pointer index (may be an arbitrary pointer identifier).
[read-only]
ToolMinorSingle. MotionEvent.GetToolMinor(Int32) for the first pointer index (may be an arbitrary pointer identifier).
[read-only]
TouchMajorSingle. MotionEvent.GetTouchMajor(Int32) for the first pointer index (may be an arbitrary pointer identifier).
[read-only]
TouchMinorSingle. MotionEvent.GetTouchMinor(Int32) for the first pointer index (may be an arbitrary pointer identifier).
[read-only]
XPrecisionSingle. Return the precision of the X coordinates being reported.
[read-only]
YPrecisionSingle. Return the precision of the Y coordinates being reported.

Protected Properties

[read-only]
override
ThresholdClassIntPtr. This API supports the Mono for Android infrastructure and is not intended to be used directly from your code.
[read-only]
override
ThresholdTypeType. This API supports the Mono for Android infrastructure and is not intended to be used directly from your code.

Public Methods

static
ActionToString(MotionEventActions) : String
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.
static
AxisFromString(String) : Axis
Gets an axis by its symbolic name such as "AXIS_X" or an equivalent numeric constant such as "42".
static
AxisToString(Axis) : String
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.
override
DescribeContents() : Int32
FindPointerIndex(Int32) : Int32
Given a pointer identifier, find the index of its data in the event.
GetAxisValue(Axis) : Single
MotionEvent.GetAxisValue(Axis) for the first pointer index (may be an arbitrary pointer identifier).
GetAxisValue(Axis, Int32) : Single
Returns the value of the requested axis for the given pointer index (use MotionEvent.GetPointerId(Int32) to find the pointer identifier for this index).
GetHistoricalAxisValue(Axis, Int32) : Single
MotionEvent.GetHistoricalAxisValue(Axis,Int32,Int32) for the first pointer index (may be an arbitrary pointer identifier).
GetHistoricalAxisValue(Axis, Int32, Int32) : Single
Returns the historical value of the requested axis, as per MotionEvent.GetAxisValue(Axis,Int32), occurred between this event and the previous event for the given pointer.
GetHistoricalEventTime(Int32) : Int64
Returns the time that a historical movement occurred between this event and the previous event, in the SystemClock.UptimeMillis time base.
GetHistoricalOrientation(Int32) : Single
MotionEvent.GetHistoricalOrientation(Int32,Int32) for the first pointer index (may be an arbitrary pointer identifier).
GetHistoricalOrientation(Int32, Int32) : Single
Returns a historical orientation coordinate, as per MotionEvent.GetOrientation(Int32), that occurred between this event and the previous event for the given pointer.
GetHistoricalPointerCoords(Int32, Int32, MotionEvent+PointerCoords)
Populates a NoType:android/view/MotionEvent$PointerCoords;Href=../../../reference/android/view/MotionEvent.PointerCoords.html object with historical pointer coordinate data, as per MotionEvent.GetPointerCoords(int, .PointerCoords), that occurred between this event and the previous event for the given pointer.
GetHistoricalPressure(Int32) : Single
MotionEvent.GetHistoricalPressure(Int32,Int32) for the first pointer index (may be an arbitrary pointer identifier).
GetHistoricalPressure(Int32, Int32) : Single
Returns a historical pressure coordinate, as per MotionEvent.GetPressure(Int32), that occurred between this event and the previous event for the given pointer.
GetHistoricalSize(Int32) : Single
MotionEvent.GetHistoricalSize(Int32,Int32) for the first pointer index (may be an arbitrary pointer identifier).
GetHistoricalSize(Int32, Int32) : Single
Returns a historical size coordinate, as per MotionEvent.GetSize(Int32), that occurred between this event and the previous event for the given pointer.
GetHistoricalToolMajor(Int32) : Single
MotionEvent.GetHistoricalToolMajor(Int32,Int32) for the first pointer index (may be an arbitrary pointer identifier).
GetHistoricalToolMajor(Int32, Int32) : Single
Returns a historical tool major axis coordinate, as per MotionEvent.GetToolMajor(Int32), that occurred between this event and the previous event for the given pointer.
GetHistoricalToolMinor(Int32) : Single
MotionEvent.GetHistoricalToolMinor(Int32,Int32) for the first pointer index (may be an arbitrary pointer identifier).
GetHistoricalToolMinor(Int32, Int32) : Single
Returns a historical tool minor axis coordinate, as per MotionEvent.GetToolMinor(Int32), that occurred between this event and the previous event for the given pointer.
GetHistoricalTouchMajor(Int32) : Single
MotionEvent.GetHistoricalTouchMajor(Int32,Int32) for the first pointer index (may be an arbitrary pointer identifier).
GetHistoricalTouchMajor(Int32, Int32) : Single
Returns a historical touch major axis coordinate, as per MotionEvent.GetTouchMajor(Int32), that occurred between this event and the previous event for the given pointer.
GetHistoricalTouchMinor(Int32) : Single
MotionEvent.GetHistoricalTouchMinor(Int32,Int32) for the first pointer index (may be an arbitrary pointer identifier).
GetHistoricalTouchMinor(Int32, Int32) : Single
Returns a historical touch minor axis coordinate, as per MotionEvent.GetTouchMinor(Int32), that occurred between this event and the previous event for the given pointer.
GetHistoricalX(Int32) : Single
MotionEvent.GetHistoricalX(Int32,Int32) for the first pointer index (may be an arbitrary pointer identifier).
GetHistoricalX(Int32, Int32) : Single
Returns a historical X coordinate, as per MotionEvent.GetX(Int32), that occurred between this event and the previous event for the given pointer.
GetHistoricalY(Int32) : Single
MotionEvent.GetHistoricalY(Int32,Int32) for the first pointer index (may be an arbitrary pointer identifier).
GetHistoricalY(Int32, Int32) : Single
Returns a historical Y coordinate, as per MotionEvent.GetY(Int32), that occurred between this event and the previous event for the given pointer.
GetOrientation(Int32) : Single
Returns the orientation of the touch area and tool area in radians clockwise from vertical for the given pointer index (use MotionEvent.GetPointerId(Int32) to find the pointer identifier for this index).
GetPointerCoords(Int32, MotionEvent+PointerCoords)
Populates a NoType:android/view/MotionEvent$PointerCoords;Href=../../../reference/android/view/MotionEvent.PointerCoords.html object with pointer coordinate data for the specified pointer index.
GetPointerId(Int32) : Int32
Return the pointer identifier associated with a particular pointer data index is this event.
GetPointerProperties(Int32, MotionEvent+PointerProperties)
Populates a NoType:android/view/MotionEvent$PointerProperties;Href=../../../reference/android/view/MotionEvent.PointerProperties.html object with pointer properties for the specified pointer index.
GetPressure(Int32) : Single
Returns the current pressure of this event for the given pointer index (use MotionEvent.GetPointerId(Int32) to find the pointer identifier for this index).
GetSize(Int32) : Single
Returns a scaled value of the approximate size for the given pointer index (use MotionEvent.GetPointerId(Int32) to find the pointer identifier for this index).
GetToolMajor(Int32) : Single
Returns the length of the major axis of an ellipse that describes the size of the approaching tool for the given pointer index (use MotionEvent.GetPointerId(Int32) to find the pointer identifier for this index).
GetToolMinor(Int32) : Single
Returns the length of the minor axis of an ellipse that describes the size of the approaching tool for the given pointer index (use MotionEvent.GetPointerId(Int32) to find the pointer identifier for this index).
GetToolType(Int32) : MotionEventToolType
Gets the tool type of a pointer for the given pointer index.
GetTouchMajor(Int32) : Single
Returns the length of the major axis of an ellipse that describes the touch area at the point of contact for the given pointer index (use MotionEvent.GetPointerId(Int32) to find the pointer identifier for this index).
GetTouchMinor(Int32) : Single
Returns the length of the minor axis of an ellipse that describes the touch area at the point of contact for the given pointer index (use MotionEvent.GetPointerId(Int32) to find the pointer identifier for this index).
GetX() : Single
MotionEvent.GetX(Int32) for the first pointer index (may be an arbitrary pointer identifier).
GetX(Int32) : Single
Returns the X coordinate of this event for the given pointer index (use MotionEvent.GetPointerId(Int32) to find the pointer identifier for this index).
GetY() : Single
MotionEvent.GetY(Int32) for the first pointer index (may be an arbitrary pointer identifier).
GetY(Int32) : Single
Returns the Y coordinate of this event for the given pointer index (use MotionEvent.GetPointerId(Int32) to find the pointer identifier for this index).
IsButtonPressed(MotionEventButtonState) : Boolean
Checks if a mouse or stylus button (or combination of buttons) is pressed.
static
Obtain(MotionEvent) : MotionEvent
Create a new MotionEvent, copying from an existing one.
static
Obtain(Int64, Int64, MotionEventActions, Single, Single, Single, Single, MetaKeyStates, Single, Single, Int32, Edge) : MotionEvent
Create a new MotionEvent, filling in all of the basic values that define the motion.
static
Obtain(Int64, Int64, Int32, Single, Single, Single, Single, MetaKeyStates, Single, Single, Int32, Edge) : MotionEvent
static
Obtain(Int64, Int64, MotionEventActions, Int32, Int32[], MotionEvent+PointerCoords[], MetaKeyStates, Single, Single, Int32, Edge, InputSourceType, MotionEventFlags) : MotionEvent
Create a new MotionEvent, filling in all of the basic values that define the motion.
static
Obtain(Int64, Int64, MotionEventActions, Int32, Single, Single, Single, Single, MetaKeyStates, Single, Single, Int32, Edge) : MotionEvent
Create a new MotionEvent, filling in all of the basic values that define the motion.
static
Obtain(Int64, Int64, Int32, Int32, Int32[], MotionEvent+PointerCoords[], MetaKeyStates, Single, Single, Int32, Edge, Int32, Int32) : MotionEvent
static
Obtain(Int64, Int64, Int32, Int32, Single, Single, Single, Single, MetaKeyStates, Single, Single, Int32, Edge) : MotionEvent
static
Obtain(Int64, Int64, MotionEventActions, Int32, MotionEvent+PointerProperties[], MotionEvent+PointerCoords[], MetaKeyStates, MotionEventButtonState, Single, Single, Int32, Edge, InputSourceType, MotionEventFlags) : MotionEvent
Create a new MotionEvent, filling in all of the basic values that define the motion.
static
Obtain(Int64, Int64, MotionEventActions, Single, Single, MetaKeyStates) : MotionEvent
Create a new MotionEvent, filling in a subset of the basic motion values.
static
Obtain(Int64, Int64, Int32, Single, Single, MetaKeyStates) : MotionEvent
static
ObtainNoHistory(MotionEvent) : 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.
SetLocation(Single, Single)
Set this event's location.
SetSource(InputSourceType)
Modifies the source of the event.
Transform(Matrix)
Applies a transformation matrix to all of the points in the event.
override
WriteToParcel(Parcel, ParcelableWriteFlags)
Flatten this object in to a Parcel.