Package icyllis.modernui.view

Class VelocityTracker

java.lang.Object
icyllis.modernui.view.VelocityTracker
@Internal public final class VelocityTracker extends Object
Helper for tracking the velocity of touch events, for implementing flinging and other such gestures.

Use obtain() to retrieve a new instance of the class when you are going to begin tracking. Put the motion events you receive into it with addMovement(MotionEvent). When you want to determine the velocity call computeCurrentVelocity(int) and then call getXVelocity() and getYVelocity() to retrieve the velocity.

  • Field Details

    • VELOCITY_TRACKER_STRATEGY_DEFAULT

      public static final int VELOCITY_TRACKER_STRATEGY_DEFAULT
      Velocity Tracker Strategy: Invalid.
      See Also:

    • VELOCITY_TRACKER_STRATEGY_IMPULSE

      public static final int VELOCITY_TRACKER_STRATEGY_IMPULSE
      Velocity Tracker Strategy: Impulse. Physical model of pushing an object. Quality: VERY GOOD. Works with duplicate coordinates, unclean finger liftoff.
      See Also:

    • VELOCITY_TRACKER_STRATEGY_LSQ1

      public static final int VELOCITY_TRACKER_STRATEGY_LSQ1
      Velocity Tracker Strategy: LSQ1. 1st order least squares. Quality: POOR. Frequently under-fits the touch data especially when the finger accelerates or changes direction. Often underestimates velocity. The direction is overly influenced by historical touch points.
      See Also:

    • VELOCITY_TRACKER_STRATEGY_LSQ2

      public static final int VELOCITY_TRACKER_STRATEGY_LSQ2
      Velocity Tracker Strategy: LSQ2. 2nd order least squares. Quality: VERY GOOD. Pretty much ideal, but can be confused by certain kinds of touch data, particularly if the panel has a tendency to generate delayed, duplicate or jittery touch coordinates when the finger is released.
      See Also:

    • VELOCITY_TRACKER_STRATEGY_LSQ3

      public static final int VELOCITY_TRACKER_STRATEGY_LSQ3
      Velocity Tracker Strategy: LSQ3. 3rd order least squares. Quality: UNUSABLE. Frequently over-fits the touch data yielding wildly divergent estimates of the velocity when the finger is released.
      See Also:

    • VELOCITY_TRACKER_STRATEGY_WLSQ2_DELTA

      public static final int VELOCITY_TRACKER_STRATEGY_WLSQ2_DELTA
      Velocity Tracker Strategy: WLSQ2_DELTA. 2nd order weighted least squares, delta weighting. Quality: EXPERIMENTAL
      See Also:

    • VELOCITY_TRACKER_STRATEGY_WLSQ2_CENTRAL

      public static final int VELOCITY_TRACKER_STRATEGY_WLSQ2_CENTRAL
      Velocity Tracker Strategy: WLSQ2_CENTRAL. 2nd order weighted least squares, central weighting. Quality: EXPERIMENTAL
      See Also:

    • VELOCITY_TRACKER_STRATEGY_WLSQ2_RECENT

      public static final int VELOCITY_TRACKER_STRATEGY_WLSQ2_RECENT
      Velocity Tracker Strategy: WLSQ2_RECENT. 2nd order weighted least squares, recent weighting. Quality: EXPERIMENTAL
      See Also:

  • Method Details

    • obtain

      @NonNull public static VelocityTracker obtain()
      Retrieve a new VelocityTracker object to watch the velocity of a motion. Be sure to call recycle() when done. You should generally only maintain an active object while tracking a movement, so that the VelocityTracker can be re-used elsewhere.
      Returns:
      Returns a new VelocityTracker.

    • obtain

      @NonNull public static VelocityTracker obtain(int strategy)
      Obtains a velocity tracker with the specified strategy. For testing and comparison purposes only.
      Parameters:
      strategy - The strategy id, VELOCITY_TRACKER_STRATEGY_DEFAULT to use the default.
      Returns:
      The velocity tracker.

    • recycle

      public void recycle()
      Return a VelocityTracker object back to be re-used by others. You must not touch the object after calling this function.

    • getStrategyId

      public int getStrategyId()
      Return strategy id of VelocityTracker object.
      Returns:
      The velocity tracker strategy id.

    • clear

      public void clear()
      Reset the velocity tracker back to its initial state.

    • addMovement

      public void addMovement(@NonNull MotionEvent event)
      Add a user's movement to the tracker. You should call this for the initial MotionEvent.ACTION_DOWN, the following MotionEvent.ACTION_MOVE events that you receive, and the final MotionEvent.ACTION_UP. You can, however, call this for whichever events you desire.
      Parameters:
      event - The MotionEvent you received and would like to track.

    • computeCurrentVelocity

      public boolean computeCurrentVelocity(int units)
      Equivalent to invoking computeCurrentVelocity(int, float) with a maximum velocity of Float.MAX_VALUE.
      See Also:

    • computeCurrentVelocity

      public boolean computeCurrentVelocity(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 getXVelocity() and getYVelocity().
      Parameters:
      units - The units you would like the velocity in. A value of 1 provides pixels per millisecond, 1000 provides pixels per second, etc.
      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.

    • getXVelocity

      public float getXVelocity()
      Retrieve the last computed X velocity. You must first call computeCurrentVelocity(int) before calling this function.
      Returns:
      The previously computed X velocity.

    • getYVelocity

      public float getYVelocity()
      Retrieve the last computed Y velocity. You must first call computeCurrentVelocity(int) before calling this function.
      Returns:
      The previously computed Y velocity.

    • getEstimator

      @Internal public boolean getEstimator(@NonNull VelocityTracker.Estimator outEstimator)
      Get an estimator for the movements of a pointer using past movements of the pointer to predict future movements.

      It is not necessary to call computeCurrentVelocity(int) before calling this method.

      Parameters:
      outEstimator - The estimator to populate.
      Returns:
      True if an estimator was obtained, false if there is no information available about the pointer.