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>&lt;Value&gt;</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    &#64;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