blob: 136b37a3337e0537dab47a51e1ec7be3b93c12bb [file] [log] [blame]
page.title=Tracking Movement
parent.title=Using Touch Gestures
next.title=Animating a Scroll Gesture
<div id="tb-wrapper">
<div id="tb">
<!-- table of contents -->
<h2>This lesson teaches you to</h2>
<li><a href="#velocity">Track Velocity</a></li>
<!-- other docs (NOT javadocs) -->
<h2>You should also read</h2>
<li><a href="">Input Events</a> API Guide
<li><a href="{@docRoot}guide/topics/sensors/sensors_overview.html">Sensors Overview</a></li>
<li><a href="{@docRoot}training/custom-views/making-interactive.html">Making the View Interactive</a> </li>
<li>Design Guide for <a href="{@docRoot}design/patterns/gestures.html">Gestures</a></li>
<li>Design Guide for <a href="{@docRoot}design/style/touch-feedback.html">Touch Feedback</a></li>
<h2>Try it out</h2>
<div class="download-box">
<a href="{@docRoot}shareables/training/"
class="button">Download the sample</a>
<p class="filename"></p>
<p>This lesson describes how to track movement in touch events.</p>
<p>A new {@link
android.view.View#onTouchEvent onTouchEvent()} is triggered with an {@link
android.view.MotionEvent#ACTION_MOVE} event whenever the current touch contact
position, pressure, or size changes. As described in <a
href="detector.html">Detecting Common Gestures</a>, all of these events are
recorded in the {@link android.view.MotionEvent} parameter of {@link
android.view.View#onTouchEvent onTouchEvent()}.</p>
<p>Because finger-based touch isn't always the most precise form of interaction,
detecting touch events is often based more on movement than on simple contact.
To help apps distinguish between movement-based gestures (such as a swipe) and
non-movement gestures (such as a single tap), Android includes the notion of
"touch slop." Touch slop refers to the distance in pixels a user's touch can wander
before the gesture is interpreted as a movement-based gesture. For more discussion of this
topic, see <a href="viewgroup.html#vc">Managing Touch Events in a ViewGroup</a>.</p>
<p>There are several different ways to track movement in a gesture, depending on
the needs of your application. For example:</p>
<li>The starting and ending position of a pointer (for example, move an
on-screen object from point A to point B).</li>
<li>The direction the pointer is traveling in, as determined by the x and y coordinates.</li>
<li>History. You can find the size of a gesture's history by calling the {@link
android.view.MotionEvent} method {@link android.view.MotionEvent#getHistorySize
getHistorySize()}. You can then obtain the positions, sizes, time, and pressures
of each of the historical events by using the motion event's {@code
getHistorical<em>&lt;Value&gt;</em>} methods. History is useful when rendering a trail of the user's finger,
such as for touch drawing. See the {@link android.view.MotionEvent} reference for
<li>The velocity of the pointer as it moves across the touch screen.</li>
<h2 id="velocity">Track Velocity</h2>
<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
determining factor in tracking a gesture's characteristics or even deciding
whether the gesture occurred. To make velocity calculation easier, Android
provides the {@link android.view.VelocityTracker} class and the
{@link} class in the
<a href="{@docRoot}tools/support-library/index.html">Support Library</a>.
android.view.VelocityTracker} helps you track the velocity of touch events. This
is useful for gestures in which velocity is part of the criteria for the
gesture, such as a fling.</p>
<p>Here is a simple example that illustrates the purpose of the methods in the
{@link android.view.VelocityTracker} API:</p>
<pre>public class MainActivity extends Activity {
private static final String DEBUG_TAG = "Velocity";
private VelocityTracker mVelocityTracker = null;
public boolean onTouchEvent(MotionEvent event) {
int index = event.getActionIndex();
int action = event.getActionMasked();
int pointerId = event.getPointerId(index);
switch(action) {
case MotionEvent.ACTION_DOWN:
if(mVelocityTracker == null) {
// Retrieve a new VelocityTracker object to watch the velocity of a motion.
mVelocityTracker = VelocityTracker.obtain();
else {
// Reset the velocity tracker back to its initial state.
// Add a user's movement to the tracker.
case MotionEvent.ACTION_MOVE:
// When you want to determine the velocity, call
// computeCurrentVelocity(). Then call getXVelocity()
// and getYVelocity() to retrieve the velocity for each pointer ID.
// Log velocity of pixels per second
// Best practice to use VelocityTrackerCompat where possible.
Log.d("", "X velocity: " +
Log.d("", "Y velocity: " +
case MotionEvent.ACTION_UP:
case MotionEvent.ACTION_CANCEL:
// Return a VelocityTracker object back to be re-used by others.
return true;
<p class="note"><strong>Note:</strong> Note that you should calculate velocity after an
{@link android.view.MotionEvent#ACTION_MOVE} event,
not after {@link android.view.MotionEvent#ACTION_UP}. After an {@link android.view.MotionEvent#ACTION_UP},
the X and Y velocities will be 0.