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.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static final class`
  `VelocityTracker.Estimator`
  An estimator for the movements of a pointer based on a polynomial model.
  `static class`
  `VelocityTracker.ImpulseStrategy`
  `static class`
  `VelocityTracker.LeastSquaresStrategy`
  `static interface`
  `VelocityTracker.Strategy`
  Implements a particular velocity tracker algorithm.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `VELOCITY_TRACKER_STRATEGY_DEFAULT`
  Velocity Tracker Strategy: Invalid.
  `static final int`
  `VELOCITY_TRACKER_STRATEGY_IMPULSE`
  Velocity Tracker Strategy: Impulse.
  `static final int`
  `VELOCITY_TRACKER_STRATEGY_LSQ1`
  Velocity Tracker Strategy: LSQ1.
  `static final int`
  `VELOCITY_TRACKER_STRATEGY_LSQ2`
  Velocity Tracker Strategy: LSQ2.
  `static final int`
  `VELOCITY_TRACKER_STRATEGY_LSQ3`
  Velocity Tracker Strategy: LSQ3.
  `static final int`
  `VELOCITY_TRACKER_STRATEGY_WLSQ2_CENTRAL`
  Velocity Tracker Strategy: WLSQ2_CENTRAL.
  `static final int`
  `VELOCITY_TRACKER_STRATEGY_WLSQ2_DELTA`
  Velocity Tracker Strategy: WLSQ2_DELTA.
  `static final int`
  `VELOCITY_TRACKER_STRATEGY_WLSQ2_RECENT`
  Velocity Tracker Strategy: WLSQ2_RECENT.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addMovement(MotionEvent event)`
  Add a user's movement to the tracker.
  `void`
  `clear()`
  Reset the velocity tracker back to its initial state.
  `boolean`
  `computeCurrentVelocity(int units)`
  Equivalent to invoking `computeCurrentVelocity(int, float)` with a maximum velocity of Float.MAX_VALUE.
  `boolean`
  `computeCurrentVelocity(int units, float maxVelocity)`
  Compute the current velocity based on the points that have been collected.
  `boolean`
  `getEstimator(VelocityTracker.Estimator outEstimator)`
  Get an estimator for the movements of a pointer using past movements of the pointer to predict future movements.
  `int`
  `getStrategyId()`
  Return strategy id of VelocityTracker object.
  `float`
  `getXVelocity()`
  Retrieve the last computed X velocity.
  `float`
  `getYVelocity()`
  Retrieve the last computed Y velocity.
  `static VelocityTracker`
  `obtain()`
  Retrieve a new VelocityTracker object to watch the velocity of a motion.
  `static VelocityTracker`
  `obtain(int strategy)`
  Obtains a velocity tracker with the specified strategy.
  `void`
  `recycle()`
  Return a VelocityTracker object back to be re-used by others.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### VELOCITY_TRACKER_STRATEGY_DEFAULT

    public static final int VELOCITY_TRACKER_STRATEGY_DEFAULT
    Velocity Tracker Strategy: Invalid.
    See Also:
      - Constant Field Values

  - ### 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:
      - Constant Field Values

  - ### 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:
      - Constant Field Values

  - ### 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:
      - Constant Field Values

  - ### 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:
      - Constant Field Values

  - ### 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:
      - Constant Field Values

  - ### 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:
      - Constant Field Values

  - ### 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:
      - Constant Field Values

- ## 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(int, float)`

  - ### 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.