VelocityTrackerCompat

Added in 1.1.0

public final class VelocityTrackerCompat


Helper for accessing features in VelocityTracker.

Summary

Public methods

static void

Add a user's movement to the tracker.

static void

Reset the velocity tracker back to its initial state.

static void

Equivalent to invoking computeCurrentVelocity with a maximum velocity of Float.MAX_VALUE.

static void
computeCurrentVelocity(
    @NonNull VelocityTracker tracker,
    int units,
    float maxVelocity
)

Compute the current velocity based on the points that have been collected.

static float
getAxisVelocity(@NonNull VelocityTracker tracker, int axis)

Equivalent to calling getAxisVelocity for axis and the active pointer.

static float
getAxisVelocity(@NonNull VelocityTracker tracker, int axis, int pointerId)

Retrieve the last computed velocity for a given motion axis.

static float
@ReplaceWith(expression = "tracker.getXVelocity(pointerId)")
getXVelocity(VelocityTracker tracker, int pointerId)

This method is deprecated.

Use getXVelocity directly.

static float
@ReplaceWith(expression = "tracker.getYVelocity(pointerId)")
getYVelocity(VelocityTracker tracker, int pointerId)

This method is deprecated.

Use getYVelocity directly.

static boolean
isAxisSupported(@NonNull VelocityTracker tracker, int axis)

Checks whether a given velocity-trackable MotionEvent axis is supported for velocity tracking by this VelocityTracker instance (refer to getAxisVelocity for a list of potentially velocity-trackable axes).

static void

Return a VelocityTracker object back to be re-used by others.

Public methods

addMovement

Added in 1.13.0
public static void addMovement(@NonNull VelocityTracker tracker, @NonNull MotionEvent event)

Add a user's movement to the tracker.

For pointer events, you should call this for the initial ACTION_DOWN, the following ACTION_MOVE events that you receive, and the final ACTION_UP. You can, however, call this for whichever events you desire.

Parameters
@NonNull VelocityTracker tracker

The VelocityTracker to add the movement to.

@NonNull MotionEvent event

The MotionEvent you received and would like to track.

clear

Added in 1.13.0
public static void clear(@NonNull VelocityTracker tracker)

Reset the velocity tracker back to its initial state.

computeCurrentVelocity

Added in 1.13.0
public static void computeCurrentVelocity(@NonNull VelocityTracker tracker, int units)

Equivalent to invoking computeCurrentVelocity with a maximum velocity of Float.MAX_VALUE.

computeCurrentVelocity

Added in 1.13.0
public static void computeCurrentVelocity(
    @NonNull VelocityTracker tracker,
    int units,
    float maxVelocity
)

Compute the current velocity based on the points that have been collected. Only call this when you actually want to retrieve velocity information, as it is relatively expensive. You can then retrieve the velocity with getAxisVelocity ()}.

Parameters
@NonNull VelocityTracker tracker

The VelocityTracker for which to compute velocity.

int units

The units you would like the velocity in. A value of 1 provides units per millisecond, 1000 provides units per second, etc. Note that the units referred to here are the same units with which motion is reported. For axes X and Y, the units are pixels.

float maxVelocity

The maximum velocity that can be computed by this method. This value must be declared in the same unit as the units parameter. This value must be positive.

getAxisVelocity

Added in 1.12.0
public static float getAxisVelocity(@NonNull VelocityTracker tracker, int axis)

Equivalent to calling getAxisVelocity for axis and the active pointer.

Parameters
@NonNull VelocityTracker tracker

The VelocityTracker from which to get axis velocity.

int axis

Which axis' velocity to return.

Returns
float

The previously computed velocity for axis for the active pointer if axis is supported for velocity tracking, or 0 if velocity tracking is not supported for the axis.

getAxisVelocity

Added in 1.12.0
public static float getAxisVelocity(@NonNull VelocityTracker tracker, int axis, int pointerId)

Retrieve the last computed velocity for a given motion axis. You must first call computeCurrentVelocity or computeCurrentVelocity before calling this function.

In addition to AXIS_X and AXIS_Y which have been supported since the introduction of this class, the following axes can be candidates for this method:

  • AXIS_SCROLL: supported via the platform starting UPSIDE_DOWN_CAKE. Supported via a fallback logic at all platform levels for the active pointer only.

Before accessing velocities of an axis using this method, check that your VelocityTracker instance supports the axis by using isAxisSupported.

Parameters
@NonNull VelocityTracker tracker

The VelocityTracker from which to get axis velocity.

int axis

Which axis' velocity to return.

int pointerId

Which pointer's velocity to return.

Returns
float

The previously computed velocity for axis for pointer ID of id if axis is supported for velocity tracking, or 0 if velocity tracking is not supported for the axis.

See also
isAxisSupported

getXVelocity

Added in 1.1.0
Deprecated in 1.1.0
@ReplaceWith(expression = "tracker.getXVelocity(pointerId)")
public static float getXVelocity(VelocityTracker tracker, int pointerId)

Call getXVelocity. If running on a pre-HONEYCOMB device, returns getXVelocity.

getYVelocity

Added in 1.1.0
Deprecated in 1.1.0
@ReplaceWith(expression = "tracker.getYVelocity(pointerId)")
public static float getYVelocity(VelocityTracker tracker, int pointerId)

Call getYVelocity. If running on a pre-HONEYCOMB device, returns getYVelocity.

isAxisSupported

Added in 1.12.0
public static boolean isAxisSupported(@NonNull VelocityTracker tracker, int axis)

Checks whether a given velocity-trackable MotionEvent axis is supported for velocity tracking by this VelocityTracker instance (refer to getAxisVelocity for a list of potentially velocity-trackable axes).

Note that the value returned from this method will stay the same for a given instance, so a single check for axis support is enough per a VelocityTracker instance.

Parameters
@NonNull VelocityTracker tracker

The VelocityTracker for which to check axis support.

int axis

The axis to check for velocity support.

Returns
boolean

true if axis is supported for velocity tracking, or false otherwise.

recycle

Added in 1.13.0
public static void recycle(@NonNull VelocityTracker tracker)

Return a VelocityTracker object back to be re-used by others.

Call this method for your VelocityTracker when you have finished tracking velocity for the use-case you created this tracker for and decided that you no longer need it. This allows it to be returned back to the pool of trackers to be re-used by others.

You must not touch the object after calling this function. That is, don't call any methods on it, or pass it as an input to any of this class' compat APIs, as the instance is no longer valid for velocity tracking.

See also
recycle