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.
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.
|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.|
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.
|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."|
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.
|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.|
|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."|
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.
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.
|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."|
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
getYPrecision() are also provided.
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.
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.
|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.|
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.
|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)."|
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
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.
|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.|
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.
|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."|
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.