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}—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}—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}—A change has happened during a press gesture.</li> 61 <li>{@link android.support.v4.view.MotionEventCompat#ACTION_POINTER_UP}—Sent when a non-primary pointer goes up.</li> 62 <li>{@link android.view.MotionEvent#ACTION_UP}—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