FlingAnimation

Kotlin |Java

class FlingAnimation : DynamicAnimation<FlingAnimation!>

kotlin.Any
↳	androidx.dynamicanimation.animation.DynamicAnimation<androidx.dynamicanimation.animation.FlingAnimation>
	↳	androidx.dynamicanimation.animation.FlingAnimation

Fling animation is an animation that continues an initial momentum (most often from gesture velocity) and gradually slows down. The fling animation will come to a stop when the velocity of the animation is below the threshold derived from setMinimumVisibleChange(float), or when the value of the animation has gone beyond the min or max value defined via DynamicAnimation#setMinValue(float) or DynamicAnimation#setMaxValue(float). It is recommended to restrict the fling animation with min and/or max value, such that the animation can end when it goes beyond screen bounds, thus preserving CPU cycles and resources.

For example, you can create a fling animation that animates the translationX of a view:

FlingAnimation flingAnim = new FlingAnimation(view, DynamicAnimation.TRANSLATION_X)
          // Sets the start velocity to -2000 (pixel/s)
          .setStartVelocity(-2000)
          // Optional but recommended to set a reasonable min and max range for the animation.
          // In this particular case, we set the min and max to -200 and 2000 respectively.
          .setMinValue(-200).setMaxValue(2000);
  flingAnim.start();

Summary

Inherited constants

From class DynamicAnimation

`Float`	`MIN_VISIBLE_CHANGE_ALPHA` The minimum visible change in alpha that can be visible to users.
`Float`	`MIN_VISIBLE_CHANGE_PIXELS` The minimum visible change in pixels that can be visible to users.
`Float`	`MIN_VISIBLE_CHANGE_ROTATION_DEGREES` The minimum visible change in degrees that can be visible to users.
`Float`	`MIN_VISIBLE_CHANGE_SCALE` The minimum visible change in scale that can be visible to users.

Public constructors
`<init>(floatValueHolder: FloatValueHolder!)` This creates a FlingAnimation that animates a `FloatValueHolder` instance.
`<init>(object: K, property: FloatPropertyCompat<K>!)` This creates a FlingAnimation that animates the property of the given object.

Public methods
Float	`getFriction()` Returns the friction being set on the animation via `setFriction(float)`.
FlingAnimation!	`setFriction(friction: Float)` Sets the friction for the fling animation.
FlingAnimation!	`setMaxValue(maxValue: Float)` Sets the max value of the animation.
FlingAnimation!	`setMinValue(minValue: Float)` Sets the min value of the animation.
FlingAnimation!	`setStartVelocity(startVelocity: Float)` Start velocity of the animation.

Inherited functions

From class DynamicAnimation

`T`	`addEndListener(listener: DynamicAnimation.OnAnimationEndListener!)` Adds an end listener to the animation for receiving onAnimationEnd callbacks. If the listener is `null` or has already been added to the list of listeners for the animation, no op.
`T`	`addUpdateListener(listener: DynamicAnimation.OnAnimationUpdateListener!)` Adds an update listener to the animation for receiving per-frame animation update callbacks. If the listener is `null` or has already been added to the list of listeners for the animation, no op. Note that update listener should only be added before the start of the animation.
`Unit`	`cancel()` Cancels the on-going animation. If the animation hasn't started, no op. Note that this method should only be called on main thread.
`Float`	`getMinimumVisibleChange()` Returns the minimum change in the animation property that could be visibly different to users.
`Boolean`	`isRunning()` Returns whether the animation is currently running.
`Unit`	`removeEndListener(listener: DynamicAnimation.OnAnimationEndListener!)` Removes the end listener from the animation, so as to stop receiving animation end callbacks.
`Unit`	`removeUpdateListener(listener: DynamicAnimation.OnAnimationUpdateListener!)` Removes the update listener from the animation, so as to stop receiving animation update callbacks.
`T`	`setMinimumVisibleChange(minimumVisibleChange: Float)` This method sets the minimal change of animation value that is visible to users, which helps determine a reasonable threshold for the animation's termination condition. It is critical to set the minimal visible change for custom properties (i.e. non-`ViewProperty`s) unless the custom property is in pixels. For custom properties, this minimum visible change defaults to change in pixel (i.e. `MIN_VISIBLE_CHANGE_PIXELS`. It is recommended to adjust this value that is reasonable for the property to be animated. A general rule of thumb to calculate such a value is: minimum visible change = range of custom property value / corresponding pixel range. For example, if the property to be animated is a progress (from 0 to 100) that corresponds to a 200-pixel change. Then the min visible change should be 100 / 200. (i.e. 0.5). It's not necessary to call this method when animating `ViewProperty`s, as the minimum visible change will be derived from the property. For example, if the property to be animated is in pixels (i.e. `TRANSLATION_X`, `TRANSLATION_Y`, `TRANSLATION_Z`, @`SCROLL_X` or `SCROLL_Y`), the default minimum visible change is 1 (pixel). For `ROTATION`, `ROTATION_X` or `ROTATION_Y`, the animation will use `MIN_VISIBLE_CHANGE_ROTATION_DEGREES` as the min visible change, which is 1/10. Similarly, the minimum visible change for alpha ( i.e. `MIN_VISIBLE_CHANGE_ALPHA` is defined as 1 / 256.
`T`	`setStartValue(startValue: Float)` Sets the start value of the animation. If start value is not set, the animation will get the current value for the view's property, and use that as the start value.
`Unit`	`start()` Starts an animation. If the animation has already been started, no op. Note that calling `start()` will not immediately set the property value to start value of the animation. The property values will be changed at each animation pulse, which happens before the draw pass. As a result, the changes will be reflected in the next frame, the same as if the values were set immediately. This method should only be called on main thread.

Inherited properties

From class DynamicAnimation

`DynamicAnimation.ViewProperty!`	`ALPHA` View's alpha property.
`DynamicAnimation.ViewProperty!`	`ROTATION` View's rotation property.
`DynamicAnimation.ViewProperty!`	`ROTATION_X` View's rotationX property.
`DynamicAnimation.ViewProperty!`	`ROTATION_Y` View's rotationY property.
`DynamicAnimation.ViewProperty!`	`SCALE_X` View's scaleX property.
`DynamicAnimation.ViewProperty!`	`SCALE_Y` View's scaleY property.
`DynamicAnimation.ViewProperty!`	`SCROLL_X` View's scrollX property.
`DynamicAnimation.ViewProperty!`	`SCROLL_Y` View's scrollY property.
`DynamicAnimation.ViewProperty!`	`TRANSLATION_X` View's translationX property.
`DynamicAnimation.ViewProperty!`	`TRANSLATION_Y` View's translationY property.
`DynamicAnimation.ViewProperty!`	`TRANSLATION_Z` View's translationZ property.
`DynamicAnimation.ViewProperty!`	`X` View's x property.
`DynamicAnimation.ViewProperty!`	`Y` View's y property.
`DynamicAnimation.ViewProperty!`	`Z` View's z property.

Public constructors

<init>

FlingAnimation(floatValueHolder: FloatValueHolder!)

This creates a FlingAnimation that animates a FloatValueHolder instance. During the animation, the FloatValueHolder instance will be updated via FloatValueHolder#setValue(float) each frame. The caller can obtain the up-to-date animation value via FloatValueHolder#getValue().

Note: changing the value in the FloatValueHolder via FloatValueHolder#setValue(float) outside of the animation during an animation run will not have any effect on the on-going animation.

Parameters
`floatValueHolder`	FloatValueHolder!: the property to be animated

<init>

FlingAnimation(
    object: K, 
    property: FloatPropertyCompat<K>!)

This creates a FlingAnimation that animates the property of the given object.

Parameters
`object`	K: the Object whose property will be animated
`property`	FloatPropertyCompat<K>!: the property to be animated
`<K>`	the class on which the property is declared

Public methods

getFriction

fun getFriction(): Float

Returns the friction being set on the animation via setFriction(float). If the friction has not been set, the default friction of 1 will be returned.

Return
`Float`	friction being used in the animation

setFriction

fun setFriction(friction: Float): FlingAnimation!

Sets the friction for the fling animation. The greater the friction is, the sooner the animation will slow down. When not set, the friction defaults to 1.

Parameters
`friction`	Float: the friction used in the animation

Return
`FlingAnimation!`	the animation whose friction will be scaled

Exceptions
`IllegalArgumentException`	if the input friction is not positive

setMaxValue

fun setMaxValue(maxValue: Float): FlingAnimation!

Sets the max value of the animation. When a fling animation reaches the max value, the animation will end immediately. Animations will not animate beyond the max value.

Parameters
`max`	maximum value of the property to be animated
`maxValue`	Float: maximum value of the property to be animated

Return
`FlingAnimation!`	the Animation whose max value is being set

setMinValue

fun setMinValue(minValue: Float): FlingAnimation!

Sets the min value of the animation. When a fling animation reaches the min value, the animation will end immediately. Animations will not animate beyond the min value.

Parameters
`min`	minimum value of the property to be animated
`minValue`	Float: minimum value of the property to be animated

Return
`FlingAnimation!`	the Animation whose min value is being set

setStartVelocity

fun setStartVelocity(startVelocity: Float): FlingAnimation!

Start velocity of the animation. Default velocity is 0. Unit: pixel/second

A non-zero start velocity is required for a FlingAnimation. If no start velocity is set through setStartVelocity(float), the start velocity defaults to 0. In that case, the fling animation will consider itself done in the next frame.

Note when using a fixed value as the start velocity (as opposed to getting the velocity through touch events), it is recommended to define such a value in dp/second and convert it to pixel/second based on the density of the screen to achieve a consistent look across different screens.

To convert from dp/second to pixel/second:

float pixelPerSecond = TypedValue.applyDimension(TypedValue.COMPLEX_UNIT_DIP, dpPerSecond,
              getResources().getDisplayMetrics());

Parameters
`startVelocity`	Float: start velocity of the animation in pixel/second

Return
`FlingAnimation!`	the Animation whose start velocity is being set