1 page.title=Handling Multi-Touch Gestures 2 parent.title=Using Touch Gestures 3 parent.link=index.html 4 5 trainingnavtop=true 6 next.title=Dragging and Scaling 7 next.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" 37 class="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 45 at the same time. This lesson describes how to detect gestures that involve 46 multiple 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 51 following touch events:</p> 52 53 <ul> 54 <li>{@link android.view.MotionEvent#ACTION_DOWN}—For the first pointer that 55 touches the screen. This starts the gesture. The pointer data for this pointer is 56 always at index 0 in the {@link android.view.MotionEvent}.</li> 57 <li>{@link android.support.v4.view.MotionEventCompat#ACTION_POINTER_DOWN}—For 58 extra pointers that enter the screen beyond the first. The pointer data for this 59 pointer 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 66 android.view.MotionEvent} via each pointer's index and ID:</p> 67 68 <ul> 69 <li><strong>Index</strong>: A {@link android.view.MotionEvent} effectively 70 stores information about each pointer in an array. The index of a pointer is its position 71 within this array. Most of the {@link 72 android.view.MotionEvent} methods you use to interact with pointers take the 73 pointer 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 77 persistent across touch events to allow tracking an individual pointer across 78 the entire gesture.</li> 79 80 </ul> 81 82 <p>The order in which individual pointers appear within a motion event is 83 undefined. Thus the index of a pointer can change from one event to the 84 next, but the pointer ID of a pointer is guaranteed to remain constant as long 85 as the pointer remains active. Use the {@link 86 android.view.MotionEvent#getPointerId getPointerId()} method to obtain a 87 pointer's ID to track the pointer across all subsequent motion events in a 88 gesture. Then for successive motion events, use the {@link 89 android.view.MotionEvent#findPointerIndex findPointerIndex()} method to obtain 90 the pointer index for a given pointer ID in that motion event. For example:</p> 91 92 93 <pre>private int mActivePointerId; 94 95 public 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 115 the action of a 116 {@link android.view.MotionEvent}. Unlike the older {@link android.view.MotionEvent#getAction getAction()} 117 method, {@link android.support.v4.view.MotionEventCompat#getActionMasked getActionMasked()} is designed to work with 118 multiple pointers. It returns the masked action 119 being 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 121 the 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} 125 class. 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 128 platforms. Note that {@link android.support.v4.view.MotionEventCompat} is <em>not</em> a 129 replacement for the {@link android.view.MotionEvent} class. Rather, it provides static utility 130 methods to which you pass your {@link android.view.MotionEvent} object in order to receive 131 the 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. 135 int index = MotionEventCompat.getActionIndex(event); 136 int xPos = -1; 137 int yPos = -1; 138 139 Log.d(DEBUG_TAG,"The action is " + actionToString(action)); 140 141 if (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 157 public 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
