1page.title=Tracking Movement 2parent.title=Using Touch Gestures 3parent.link=index.html 4 5trainingnavtop=true 6next.title=Animating a Scroll Gesture 7next.link=scroll.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="#velocity">Track Velocity</a></li> 18</ol> 19 20<!-- other docs (NOT javadocs) --> 21<h2>You should also read</h2> 22 23<ul> 24 <li><a href="http://developer.android.com/guide/topics/ui/ui-events.html">Input Events</a> API Guide 25 </li> 26 <li><a href="{@docRoot}guide/topics/sensors/sensors_overview.html">Sensors Overview</a></li> 27 <li><a href="http://android-developers.blogspot.com/2010/06/making-sense-of-multitouch.html">Making Sense of Multitouch</a> blog post</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 34</div> 35</div> 36 37<p>This lesson describes how to track movement in touch events.</p> 38 39<p>A new {@link 40android.view.View#onTouchEvent onTouchEvent()} is triggered with an {@link 41android.view.MotionEvent#ACTION_MOVE} event whenever the current touch contact 42position, pressure, or size changes. As described in <a 43href="detector.html">Detecting Common Gestures</a>, all of these events are 44recorded in the {@link android.view.MotionEvent} parameter of {@link 45android.view.View#onTouchEvent onTouchEvent()}.</p> 46 47<p>Because finger-based touch isn't always the most precise form of interaction, 48detecting touch events is often based more on movement than on simple contact. 49To help apps distinguish between movement-based gestures (such as a swipe) and 50non-movement gestures (such as a single tap), Android includes the notion of 51"touch slop." Touch slop refers to the distance in pixels a user's touch can wander 52before the gesture is interpreted as a movement-based gesture. For more discussion of this 53topic, see <a href="viewgroup.html#vc">Managing Touch Events in a ViewGroup</a>.</p> 54 55 56 57<p>There are several different ways to track movement in a gesture, depending on 58the needs of your application. For example:</p> 59 60<ul> 61 62<li>The starting and ending position of a pointer (for example, move an 63on-screen object from point A to point B).</li> 64 65<li>The direction the pointer is traveling in, as determined by the x and y coordinates.</li> 66 67<li>History. You can find the size of a gesture's history by calling the {@link 68android.view.MotionEvent} method {@link android.view.MotionEvent#getHistorySize 69getHistorySize()}. You can then obtain the positions, sizes, time, and pressures 70of each of the historical events by using the motion event's {@code 71getHistorical<em><Value></em>} methods. History is useful when rendering a trail of the user's finger, 72such as for touch drawing. See the {@link android.view.MotionEvent} reference for 73details.</li> 74 75<li>The velocity of the pointer as it moves across the touch screen.</li> 76 77</ul> 78 79 80 81<h2 id="velocity">Track Velocity</h2> 82 83<p> You could have a movement-based gesture that is simply based on the distance and/or direction the pointer traveled. But velocity often is a 84determining factor in tracking a gesture's characteristics or even deciding 85whether the gesture occurred. To make velocity calculation easier, Android 86provides the {@link android.view.VelocityTracker} class and the 87{@link android.support.v4.view.VelocityTrackerCompat} class in the 88<a href="{@docRoot}tools/extras/support-library.html">Support Library</a>. 89{@link 90android.view.VelocityTracker} helps you track the velocity of touch events. This 91is useful for gestures in which velocity is part of the criteria for the 92gesture, such as a fling.</p> 93 94 95<p>Here is a simple example that illustrates the purpose of the methods in the 96{@link android.view.VelocityTracker} API:</p> 97 98<pre>public class MainActivity extends Activity { 99 private static final String DEBUG_TAG = "Velocity"; 100 ... 101 private VelocityTracker mVelocityTracker = null; 102 @Override 103 public boolean onTouchEvent(MotionEvent event) { 104 int index = event.getActionIndex(); 105 int action = event.getActionMasked(); 106 int pointerId = event.getPointerId(index); 107 108 switch(action) { 109 case MotionEvent.ACTION_DOWN: 110 if(mVelocityTracker == null) { 111 // Retrieve a new VelocityTracker object to watch the velocity of a motion. 112 mVelocityTracker = VelocityTracker.obtain(); 113 } 114 else { 115 // Reset the velocity tracker back to its initial state. 116 mVelocityTracker.clear(); 117 } 118 // Add a user's movement to the tracker. 119 mVelocityTracker.addMovement(event); 120 break; 121 case MotionEvent.ACTION_MOVE: 122 mVelocityTracker.addMovement(event); 123 // When you want to determine the velocity, call 124 // computeCurrentVelocity(). Then call getXVelocity() 125 // and getYVelocity() to retrieve the velocity for each pointer ID. 126 mVelocityTracker.computeCurrentVelocity(1000); 127 // Log velocity of pixels per second 128 // Best practice to use VelocityTrackerCompat where possible. 129 Log.d("", "X velocity: " + 130 VelocityTrackerCompat.getXVelocity(mVelocityTracker, 131 pointerId)); 132 Log.d("", "Y velocity: " + 133 VelocityTrackerCompat.getYVelocity(mVelocityTracker, 134 pointerId)); 135 break; 136 case MotionEvent.ACTION_UP: 137 case MotionEvent.ACTION_CANCEL: 138 // Return a VelocityTracker object back to be re-used by others. 139 mVelocityTracker.recycle(); 140 break; 141 } 142 return true; 143 } 144} 145</pre> 146 147<p class="note"><strong>Note:</strong> Note that you should calculate velocity after an 148{@link android.view.MotionEvent#ACTION_MOVE} event, 149not after {@link android.view.MotionEvent#ACTION_UP}. After an {@link android.view.MotionEvent#ACTION_UP}, 150the X and Y velocities will be 0. 151</p> 152