blob: 58404827682dde7d539c0a1683b7806ae087e20d [file] [log] [blame]
page.title=Handling Multi-Touch Gestures
parent.title=Using Touch Gestures
next.title=Dragging and Scaling
<div id="tb-wrapper">
<div id="tb">
<!-- table of contents -->
<h2>This lesson teaches you to</h2>
<li><a href="#track">Track Multiple Pointers</a></li>
<li><a href="#action">Get a MotionEvent's Action</a></li>
<!-- other docs (NOT javadocs) -->
<h2>You should also read</h2>
<li><a href="">Input Events</a> API Guide
<li><a href="{@docRoot}guide/topics/sensors/sensors_overview.html">Sensors Overview</a></li>
<li><a href="{@docRoot}training/custom-views/making-interactive.html">Making the View Interactive</a> </li>
<li>Design Guide for <a href="{@docRoot}design/patterns/gestures.html">Gestures</a></li>
<li>Design Guide for <a href="{@docRoot}design/style/touch-feedback.html">Touch Feedback</a></li>
<h2>Try it out</h2>
<div class="download-box">
<a href="{@docRoot}shareables/training/"
class="button">Download the sample</a>
<p class="filename"></p>
<p>A multi-touch gesture is when multiple pointers (fingers) touch the screen
at the same time. This lesson describes how to detect gestures that involve
multiple pointers.</p>
<h2 id="track">Track Multiple Pointers</h2>
<p>When multiple pointers touch the screen at the same time, the system generates the
following touch events:</p>
<li>{@link android.view.MotionEvent#ACTION_DOWN}&mdash;For the first pointer that
touches the screen. This starts the gesture. The pointer data for this pointer is
always at index 0 in the {@link android.view.MotionEvent}.</li>
extra pointers that enter the screen beyond the first. The pointer data for this
pointer is at the index returned by {@link getActionIndex()}.</li>
<li>{@link android.view.MotionEvent#ACTION_MOVE}&mdash;A change has happened during a press gesture.</li>
<li>{@link}&mdash;Sent when a non-primary pointer goes up.</li>
<li>{@link android.view.MotionEvent#ACTION_UP}&mdash;Sent when the last pointer leaves the screen.</li>
<p>You keep track of individual pointers within a {@link
android.view.MotionEvent} via each pointer's index and ID:</p>
<li><strong>Index</strong>: A {@link android.view.MotionEvent} effectively
stores information about each pointer in an array. The index of a pointer is its position
within this array. Most of the {@link
android.view.MotionEvent} methods you use to interact with pointers take the
pointer index as a parameter, not the pointer ID. </li>
<li><strong>ID</strong>: Each pointer also has an ID mapping that stays
persistent across touch events to allow tracking an individual pointer across
the entire gesture.</li>
<p>The order in which individual pointers appear within a motion event is
undefined. Thus the 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 {@link
android.view.MotionEvent#getPointerId getPointerId()} method to obtain a
pointer's ID to track the pointer across all subsequent motion events in a
gesture. Then for successive motion events, use the {@link
android.view.MotionEvent#findPointerIndex findPointerIndex()} method to obtain
the pointer index for a given pointer ID in that motion event. For example:</p>
<pre>private int mActivePointerId;
public boolean onTouchEvent(MotionEvent event) {
// Get the pointer ID
mActivePointerId = event.getPointerId(0);
// ... Many touch events later...
// Use the pointer ID to find the index of the active pointer
// and fetch its position
int pointerIndex = event.findPointerIndex(mActivePointerId);
// Get the pointer's current position
float x = event.getX(pointerIndex);
float y = event.getY(pointerIndex);
<h2 id="action">Get a MotionEvent's Action</h2>
<p>You should always use the method
{@link android.view.MotionEvent#getActionMasked getActionMasked()} (or better yet, the compatability version
{@link MotionEventCompat.getActionMasked()}) to retrieve
the action of a
{@link android.view.MotionEvent}. Unlike the older {@link android.view.MotionEvent#getAction getAction()}
method, {@link getActionMasked()} is designed to work with
multiple pointers. It returns the masked action
being performed, without including the pointer index bits. You can then use
{@link getActionIndex()} to return the index of
the pointer associated with the action. This is illustrated in the snippet below.</p>
<p class="note"><strong>Note:</strong> This example uses the
class. This class is in the
<a href="{@docRoot}tools/support-library/index.html">Support Library</a>. You should use
{@link} to provide the best support for a wide range of
platforms. Note that {@link} is <em>not</em> a
replacement for the {@link android.view.MotionEvent} class. Rather, it provides static utility
methods to which you pass your {@link android.view.MotionEvent} object in order to receive
the desired action associated with that event.</p>
<pre>int action = MotionEventCompat.getActionMasked(event);
// Get the index of the pointer associated with the action.
int index = MotionEventCompat.getActionIndex(event);
int xPos = -1;
int yPos = -1;
Log.d(DEBUG_TAG,"The action is " + actionToString(action));
if (event.getPointerCount() > 1) {
Log.d(DEBUG_TAG,"Multitouch event");
// The coordinates of the current screen contact, relative to
// the responding View or Activity.
xPos = (int)MotionEventCompat.getX(event, index);
yPos = (int)MotionEventCompat.getY(event, index);
} else {
// Single touch event
Log.d(DEBUG_TAG,"Single touch event");
xPos = (int)MotionEventCompat.getX(event, index);
yPos = (int)MotionEventCompat.getY(event, index);
// Given an action int, returns a string description
public static String actionToString(int action) {
switch (action) {
case MotionEvent.ACTION_DOWN: return "Down";
case MotionEvent.ACTION_MOVE: return "Move";
case MotionEvent.ACTION_POINTER_DOWN: return "Pointer Down";
case MotionEvent.ACTION_UP: return "Up";
case MotionEvent.ACTION_POINTER_UP: return "Pointer Up";
case MotionEvent.ACTION_OUTSIDE: return "Outside";
case MotionEvent.ACTION_CANCEL: return "Cancel";
return "";
<p>For more discussion of multi-touch and some examples, see the lesson <a href="scale.html">Dragging and Scaling</a>.