1page.title=Handling Multi-Touch Gestures
2parent.title=Using Touch Gestures
3parent.link=index.html
4
5trainingnavtop=true
6next.title=Dragging and Scaling
7next.link=scale.html
8
9@jd:body
10
11<div id="tb-wrapper">
12<div id="tb">
13
14<!-- table of contents -->
15<h2>This lesson teaches you to</h2>
16<ol>
17  <li><a href="#track">Track Multiple Pointers</a></li>
18  <li><a href="#action">Get a MotionEvent's Action</a></li>
19</ol>
20
21<!-- other docs (NOT javadocs) -->
22<h2>You should also read</h2>
23
24<ul>
25   <li><a href="http://developer.android.com/guide/topics/ui/ui-events.html">Input Events</a> API Guide
26    </li>
27    <li><a href="{@docRoot}guide/topics/sensors/sensors_overview.html">Sensors Overview</a></li>
28    <li><a href="{@docRoot}training/custom-views/making-interactive.html">Making the View Interactive</a> </li>
29    <li>Design Guide for <a href="{@docRoot}design/patterns/gestures.html">Gestures</a></li>
30    <li>Design Guide for <a href="{@docRoot}design/style/touch-feedback.html">Touch Feedback</a></li>
31</ul>
32
33<h2>Try it out</h2>
34
35<div class="download-box">
36  <a href="{@docRoot}shareables/training/InteractiveChart.zip"
37class="button">Download the sample</a>
38 <p class="filename">InteractiveChart.zip</p>
39</div>
40
41</div>
42</div>
43
44<p>A multi-touch gesture is when multiple pointers (fingers) touch the screen
45at the same time. This lesson describes how to detect gestures that involve
46multiple pointers.</p>
47
48<h2 id="track">Track Multiple Pointers</h2>
49
50<p>When multiple pointers touch the screen at the same time, the system generates the
51following touch events:</p>
52
53<ul>
54  <li>{@link android.view.MotionEvent#ACTION_DOWN}&mdash;For the first pointer that
55touches the screen. This starts the gesture. The pointer data for this pointer is
56always at index 0 in the {@link android.view.MotionEvent}.</li>
57  <li>{@link android.support.v4.view.MotionEventCompat#ACTION_POINTER_DOWN}&mdash;For
58extra pointers that enter the screen beyond the first. The pointer data for this
59pointer is at the index returned by {@link android.support.v4.view.MotionEventCompat#getActionIndex getActionIndex()}.</li>
60  <li>{@link android.view.MotionEvent#ACTION_MOVE}&mdash;A change has happened during a press gesture.</li>
61  <li>{@link android.support.v4.view.MotionEventCompat#ACTION_POINTER_UP}&mdash;Sent when a non-primary pointer goes up.</li>
62  <li>{@link android.view.MotionEvent#ACTION_UP}&mdash;Sent when the last pointer leaves the screen.</li>
63</ul>
64
65<p>You keep track of individual pointers within a {@link
66android.view.MotionEvent} via each pointer's index and ID:</p>
67
68<ul>
69<li><strong>Index</strong>: A {@link android.view.MotionEvent} effectively
70stores information about each pointer in an array. The index of a pointer is its position
71within this array. Most of the {@link
72android.view.MotionEvent} methods you use to interact with pointers take the
73pointer index as a parameter, not the pointer ID. </li>
74
75
76  <li><strong>ID</strong>: Each pointer also has an ID mapping that stays
77persistent across touch events to allow tracking an individual pointer across
78the entire gesture.</li>
79
80</ul>
81
82<p>The  order in which individual pointers appear within a motion event is
83undefined. Thus the index of a pointer can change from one event to the
84next, but the pointer ID of a pointer is guaranteed to remain  constant as long
85as the pointer remains active. Use the  {@link
86android.view.MotionEvent#getPointerId getPointerId()} method to obtain a
87pointer's ID to track the pointer across all subsequent motion events in a
88gesture. Then for successive  motion events, use the {@link
89android.view.MotionEvent#findPointerIndex findPointerIndex()} method to obtain
90the pointer index for a given pointer ID in that motion event. For example:</p>
91
92
93<pre>private int mActivePointerId;
94
95public boolean onTouchEvent(MotionEvent event) {
96    ....
97    // Get the pointer ID
98    mActivePointerId = event.getPointerId(0);
99
100    // ... Many touch events later...
101
102    // Use the pointer ID to find the index of the active pointer
103    // and fetch its position
104    int pointerIndex = event.findPointerIndex(mActivePointerId);
105    // Get the pointer's current position
106    float x = event.getX(pointerIndex);
107    float y = event.getY(pointerIndex);
108}</pre>
109
110<h2 id="action">Get a MotionEvent's Action</h2>
111
112<p>You should always use the method
113{@link android.view.MotionEvent#getActionMasked getActionMasked()} (or better yet, the compatability version
114{@link android.support.v4.view.MotionEventCompat#getActionMasked MotionEventCompat.getActionMasked()}) to retrieve
115the action of a
116{@link android.view.MotionEvent}. Unlike the older {@link android.view.MotionEvent#getAction getAction()}
117method, {@link android.support.v4.view.MotionEventCompat#getActionMasked getActionMasked()} is designed to work with
118multiple pointers. It returns the masked action
119being performed, without including the pointer index bits. You can then use
120{@link android.support.v4.view.MotionEventCompat#getActionIndex getActionIndex()} to return the index of
121the pointer associated with the action. This is illustrated in the snippet below.</p>
122
123<p class="note"><strong>Note:</strong> This example uses the
124{@link android.support.v4.view.MotionEventCompat}
125class. This class is in the
126<a href="{@docRoot}tools/support-library/index.html">Support Library</a>. You should use
127{@link android.support.v4.view.MotionEventCompat} to provide the best support for a wide range of
128platforms. Note that {@link android.support.v4.view.MotionEventCompat} is <em>not</em> a
129replacement for the {@link android.view.MotionEvent} class. Rather, it provides static utility
130methods to which you pass your {@link android.view.MotionEvent} object in order to receive
131the desired action associated with that event.</p>
132
133<pre>int action = MotionEventCompat.getActionMasked(event);
134// Get the index of the pointer associated with the action.
135int index = MotionEventCompat.getActionIndex(event);
136int xPos = -1;
137int yPos = -1;
138
139Log.d(DEBUG_TAG,"The action is " + actionToString(action));
140
141if (event.getPointerCount() > 1) {
142    Log.d(DEBUG_TAG,"Multitouch event");
143    // The coordinates of the current screen contact, relative to
144    // the responding View or Activity.
145    xPos = (int)MotionEventCompat.getX(event, index);
146    yPos = (int)MotionEventCompat.getY(event, index);
147
148} else {
149    // Single touch event
150    Log.d(DEBUG_TAG,"Single touch event");
151    xPos = (int)MotionEventCompat.getX(event, index);
152    yPos = (int)MotionEventCompat.getY(event, index);
153}
154...
155
156// Given an action int, returns a string description
157public static String actionToString(int action) {
158    switch (action) {
159
160        case MotionEvent.ACTION_DOWN: return "Down";
161	case MotionEvent.ACTION_MOVE: return "Move";
162	case MotionEvent.ACTION_POINTER_DOWN: return "Pointer Down";
163	case MotionEvent.ACTION_UP: return "Up";
164	case MotionEvent.ACTION_POINTER_UP: return "Pointer Up";
165	case MotionEvent.ACTION_OUTSIDE: return "Outside";
166	case MotionEvent.ACTION_CANCEL: return "Cancel";
167    }
168    return "";
169}</pre>
170
171
172
173
174<p>For more discussion of multi-touch and some examples, see the lesson <a href="scale.html">Dragging and Scaling</a>.
175