Basics

Introduction

This documentation is for application developers to add Wacom tablet support to their Android application. We discuss the Android functions that enable stylus and touch features in the following sections. Before diving into tablet-specific functions, we assume that the Android development environment has been fully setup with a Wacom tablet attached to the system.

Event Listeners

The View class provides methods that allow you to register event listeners that will be notified when a MotionEvent occurs. While all versions of Android support touch event listeners, support for hover event listeners was introduced with Android 3.1.

API	Purpose
public static interface View.OnTouchListener public void View.setOnTouchListener (View.OnTouchListener l)	Defines a callback that will be invoked when a touch event is sent to this View. Touch events are generated for active interactions: e.g. touching the touchscreen, or dragging the stylus/mouse.
public static interface View.OnGenericMotionListener public void View.onGenericMotionListener (View.OnOnGenericMotionListener l)	Defines a callback that will be invoked when a generic (non-touch) motion event is sent to this view. Hover events are no longer sent to generic motion listeners as of Ice Cream Sandwich.
public static interface View.OnHoverListener public void View.onHoverListener (View.OnHoverListener l)	Defines a callback that will be invoked when a hover event is sent to this view.

Event Actions

The MotionEvent class defines constants which describe the kind of action that is occurring. As with the event listeners, hover actions are only available in Android 3.1 and newer.

API	Purpose
public final int MotionEvent.getAction () public final int MotionEvent.getActionMasked ()	Returns the kind of action being performed. The first method returns the action, combined with the pointer index which performed the action. The second method returns just the action for easier comparison with the constants below.
public static final int ACTION_DOWN	"A pressed gesture has started, the motion contains the initial starting location."
public static final int ACTION_MOVE	"A change has happened during a press gesture (between ACTION_DOWN and ACTION_UP. The motion contains the most recent point, as well as any intermediate points since the last down or move event."
public static final int ACTION_UP	"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_HOVER_MOVE	"A change happened, but the pointer is not down (unlike ACTION_MOVE). The motion contains the most recent point, as well as any intermediate points since the last hover event."
public static final int ACTION_HOVER_ENTER	"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."
public static final int ACTION_HOVER_EXIT	"The pointer is not down but has exited the boundaries of a window or view."

Event Pointers

Android can track an arbitrary number of "pointers" (contacts/tools) from a single device, each with its own set of axis values and tool type information.

Indices

API	Purpose
public final int getPointerCount ()	"The number of pointers of data contained in this event. Always >= 1."
public final int getActionIndex ()	If an "interesting" action occurs (e.g. ACTION_POINTER_DOWN or ACTION_POINTER_UP), then this method will return the index of the pointer to pay attention to. For more mundane events (e.g. ACTION_MOVE) there is no need to call this method.
public final int getPointerId (int pointerIndex)	Returns the pointer identifier associated with a particular pointer data index. Unlike the pointer index, the pointer identifier is unique to the pointer throughout its life, and is safe to use for tracking purposes.

Types

API	Purpose
public static final int MotionEvent.getToolType (int pointerIndex)	"Gets the tool type of a pointer for the given pointer index. The tool type indicates the type of tool used to make contact, such as a finger or stylus, if known."
public static final int MotionEvent.TOOL_TYPE_STYLUS	"The tool is a stylus."
public static final int MotionEvent.TOOL_TYPE_ERASER	"The tool is an eraser or a stylus being used in an inverted posture."
public static final int MotionEvent.TOOL_TYPE_FINGER	"The tool is a finger."
public static final int MotionEvent.TOOL_TYPE_UNKNOWN	"This constant is used when the tool type is not known or is not relevant."

Event Axes

Android stores both the most-recent axis values reported by a tool, as well as a list of intermediate values that occurred since the last MotionEvent was delivered. The basic coordinate and pressure axes are supported by all Android versions, but other axes may depend on more recent releases.

There are generally several methods to obtain the data for any given axis. A bare method will provide the most-recent data for the first pointer index, while other variants may allow you to specify the index or age of data to be retrieved.

History

To minimize the processing overhead that would be incurred by immediately forwarding every input event from the kernel, Android buffers events for a short period of time before sending a single batched MotionEvent. For applications that demand smooth input, the intermediate input device states are available though various getHistoricalFoo(int pos) functions.

API	Purpose
public final int getHistorySize ()	"Returns the number of historical points in this event. These are movements that have occurred between this event and the previous event."
public final long getHistoricalEventTime (int pos)	"Returns the time that a historical movement occurred between this event and the previous event, in the uptimeMillis() time base."

Location

Android provides the location of events in screen units, with sub-pixel precision. If for some reason you find it necessary to convert a coordinate to device units, the functions getXPrecision() and getYPrecision() are also provided.

API	Purpose
public final float MotionEvent.getX () public final float MotionEvent.getX (int pointerIndex) public final float MotionEvent.getHistoricalX (int pos) public final float MotionEvent.getHistoricalX (int pos, int pointerIndex) public static final int MotionEvent.AXIS_X	"X axis of a motion event."
public final float MotionEvent.getY () public final float MotionEvent.getY (int pointerIndex) public final float MotionEvent.getHistoricalY (int pos) public final float MotionEvent.getHistoricalY (int pos, int pointerIndex) public static final int MotionEvent.AXIS_Y	"Y axis of a motion event."
public final float getRawX ()	"Returns the original raw X coordinate of this event. For touch events on the screen, this is the original location of the event on the screen, before it had been adjusted for the containing window and views."
public final float getRawY ()	"Returns the original raw Y coordinate of this event. For touch events on the screen, this is the original location of the event on the screen, before it had been adjusted for the containing window and views."

Force / Size

Devices can measure and report force through several different attributes. A stylus will report pen pressure, while touchscreens may report contact size or major/minor axis lengths.

API	Purpose
public final float MotionEvent.getPressure () public final float MotionEvent.getPressure (int pointerIndex) public final float MotionEvent.getHistoricalPressure (int pos) public final float MotionEvent.getHistoricalPressure (int pos, int pointerIndex) public static final int MotionEvent.AXIS_PRESSURE	Obtains the pressure the contact is exerting on the screen. This value is normalized from the range 0.0 - 1.0, but may exceed these bounds depending on the input driver.
public final float MotionEvent.getSize () public final float MotionEvent.getSize (int pointerIndex) public final float MotionEvent.getHistoricalSize (int pos) public final float MotionEvent.getHistoricalSize (int pos, int pointerIndex) public static final int MotionEvent.AXIS_SIZE	Obtains the size of the contact, relative to the maximum size that can be sensed.
public final float MotionEvent.getTouchMajor () public final float MotionEvent.getTouchMajor (int pointerIndex) public final float MotionEvent.getHistoricalTouchMajor (int pos) public final float MotionEvent.getHistoricalTouchMajor (int pos, int pointerIndex) public static final int MotionEvent.AXIS_TOUCH_MAJOR	"Returns the length of the major axis of an ellipse that describes the touch area at the point of contact."
public final float MotionEvent.getTouchMinor () public final float MotionEvent.getTouchMinor (int pointerIndex) public final float MotionEvent.getHistoricalTouchMinor (int pos) public final float MotionEvent.getHistoricalTouchMinor (int pos, int pointerIndex) public static final int MotionEvent.AXIS_TOUCH_MINOR	"Returns the length of the minor axis of an ellipse that describes the touch area at the point of contact."
public final float MotionEvent.getToolMajor () public final float MotionEvent.getToolMajor (int pointerIndex) public final float MotionEvent.getHistoricalToolMajor (int pos) public final float MotionEvent.getHistoricalToolMajor (int pos, int pointerIndex) public static final int MotionEvent.AXIS_TOOL_MAJOR	"Returns the length of the major axis of an ellipse that describes the size of the approaching tool. The tool area represents the estimated size of the finger or pen that is touching the device independent of its actual touch area at the point of contact."
public final float MotionEvent.getToolMinor () public final float MotionEvent.getToolMinor (int pointerIndex) public final float MotionEvent.getHistoricalToolMinor (int pos) public final float MotionEvent.getHistoricalToolMinor (int pos, int pointerIndex) public static final int MotionEvent.AXIS_TOOL_MINOR	"Returns the length of the minor axis of an ellipse that describes the size of the approaching tool. The tool area represents the estimated size of the finger or pen that is touching the device independent of its actual touch area at the point of contact."

Orientation

Recent versions of Android are capable of reporting three other tool axes if supported by the hardware. These provide additional information about the 3D orientation of the tool in space.

API	Purpose
public final float MotionEvent.getOrientation () public final float MotionEvent.getOrientation (int pointerIndex) public final float MotionEvent.getHistoricalOrientation (int pos) public final float MotionEvent.getHistoricalOrientation (int pos, int pointerIndex) public static final int MotionEvent.AXIS_ORIENTATION	Azimuth angle of contact, relative to the top of the screen.
public static final int MotionEvent.AXIS_TILT	Altitude angle of contact, relative to the screen’s perpendicular.
public static final int MotionEvent.AXIS_DISTANCE	Distance between the tool and the screen.

Event Buttons

If a motion event comes from a stylus or mouse, there may be button state information available. Unlike a tool axis, button state is not available per-pointer, and no historical data is provided.

API	Purpose
public final int MotionEvent.getButtonState ()	"Gets the state of all buttons that are pressed such as a mouse or stylus button." Historic button state information is not available.
public static final int MotionEvent.BUTTON_PRIMARY	"Primary button (left mouse button). This button constant is not set in response to simple touches with a finger or stylus tip. The user must actually push a button."
public static final int MotionEvent.BUTTON_SECONDARY	"Secondary button (right mouse button, stylus first button)."
public static final int MotionEvent.BUTTON_TERTIARY	"Tertiary button (middle mouse button, stylus second button)."

Device Information

Android provides apps with metadata about the devices and tools that are used to create motion events. This metadata includes contact IDs, tool types, and descriptions of the source itself. Data specific to a particular contact is typically hosted in the MotionEvent itself, while information about the underlying device is available through the InputDevice class.

Devices

Android tracks every input device that is attached the the system and assigns each an ID number that can be used both to distinguish motion events that come from different devices and to obtain information about the responsible device.

API	Purpose
public final int MotionEvent.getDeviceId ()	"Gets the ID for the device that this event came from. An ID of zero indicates that the event didn’t come from a physical device and maps to the default keymap. The other numbers are arbitrary and you shouldn’t depend on the values."
public static InputDevice InputDevice.getDevice (int id)	Returns the InputDevice associated with the specified ID.
public static int[] InputDevice.getDeviceIds ()	"Gets the IDs of all input devices in the system."
public String InputDevice.getName ()	"Gets the name of this input device."
public String InputDevice.getDescriptor ()	"Gets the input device descriptor which is a stable identifier for an input device." This descriptor can be used to safely store settings associated with an input device across application launches.

Event Sources

Each motion event may come tagged with information about the "source" of the event. This provides additional device type information that can be used to e.g. separate touchscreen events from stylus events.

API	Purpose
public final int MotionEvent.getSource ()	"Gets the source of the event."
public int InputDevice.getSources ()	"Gets the input sources supported by this input device as a combined bitfield." Note that a single input device may have multiple sources, so a simple equality test with the constants below is insufficient.
public static final int InputDevice.SOURCE_TOUCHSCREEN	"The input source is a touch screen pointing device."
public static final int InputDevice.SOURCE_STYLUS	"The input device is a stylus pointing device."
public static final int InputDevice.SOURCE_UNKNOWN	"The input source is unknown."

See Also

Overview – Information on the Android API

Reference – Links to the complete Android API packages and classes

FAQs – Useful Android programming tips

Sample Code – Full Android API demo sample

Where to get help

If you have questions about the Android API, please search Android API Reference page. If you have questions about Wacom tablet, please visit our Support page at: https://developer.wacom.com/developer-dashboard/support.