SpringAnimation

Kotlin |Java

class SpringAnimation : DynamicAnimation<SpringAnimation!>

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

SpringAnimation is an animation that is driven by a SpringForce. The spring force defines the spring's stiffness, damping ratio, as well as the rest position. Once the SpringAnimation is started, on each frame the spring force will update the animation's value and velocity. The animation will continue to run until the spring force reaches equilibrium. If the spring used in the animation is undamped, the animation will never reach equilibrium. Instead, it will oscillate forever.

To create a simple SpringAnimation that uses the default SpringForce:

// Create an animation to animate view's X property, set the rest position of the
  // default spring to 0, and start the animation with a starting velocity of 5000 (pixel/s).
  final SpringAnimation anim = new SpringAnimation(view, DynamicAnimation.X, 0)
          .setStartVelocity(5000);
  anim.start();

Alternatively, a SpringAnimation can take a pre-configured SpringForce, and use that to drive the animation.

// Create a low stiffness, low bounce spring at position 0.
  SpringForce spring = new SpringForce(0)
          .setDampingRatio(SpringForce.DAMPING_RATIO_LOW_BOUNCY)
          .setStiffness(SpringForce.STIFFNESS_LOW);
  // Create an animation to animate view's scaleY property, and start the animation using
  // the spring above and a starting value of 0.5. Additionally, constrain the range of value for
  // the animation to be non-negative, effectively preventing any spring overshoot.
  final SpringAnimation anim = new SpringAnimation(view, DynamicAnimation.SCALE_Y)
          .setMinValue(0).setSpring(spring).setStartValue(1);
  anim.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 SpringAnimation that animates a `FloatValueHolder` instance.
`<init>(floatValueHolder: FloatValueHolder!, finalPosition: Float)` This creates a SpringAnimation that animates a `FloatValueHolder` instance.
`<init>(object: K, property: FloatPropertyCompat<K>!)` This creates a SpringAnimation that animates the property of the given object.
`<init>(object: K, property: FloatPropertyCompat<K>!, finalPosition: Float)` This creates a SpringAnimation that animates the property of the given object.

Public methods
Unit	`animateToFinalPosition(finalPosition: Float)` Updates the final position of the spring.
Boolean	`canSkipToEnd()` Queries whether the spring can eventually come to the rest position.
Unit	`cancel()` Cancels the on-going animation.
SpringForce!	`getSpring()` Returns the spring that the animation uses for animations.
SpringAnimation!	`setSpring(force: SpringForce!)` Uses the given spring as the force that drives this animation.
Unit	`skipToEnd()` Skips to the end of the animation.
Unit	`start()`

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.
`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`	`setMaxValue(max: Float)` Sets the max value of the animation. Animations will not animate beyond their max value. Whether or not animation will come to an end when max value is reached is dependent on the child animation's implementation.
`T`	`setMinValue(min: Float)` Sets the min value of the animation. Animations will not animate beyond their min value. Whether or not animation will come to an end when min value is reached is dependent on the child animation's implementation.
`T`	`setMinimumVisibleChange(@FloatRange(0.0, false) 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.
`T`	`setStartVelocity(startVelocity: Float)` Start velocity of the animation. Default velocity is 0. Unit: change in property per second (e.g. pixels per second, scale/alpha value change per second). 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());

Extension functions

From androidx.dynamicanimation.animation

SpringAnimation

SpringAnimation.withSpringForceProperties(func: SpringForce.() -> Unit)

Updates or applies spring force properties like SpringForce.mDampingRatio, SpringForce.mFinalPosition and stiffness on SpringAnimation.

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>

SpringAnimation(floatValueHolder: FloatValueHolder!)

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>

SpringAnimation(
    floatValueHolder: FloatValueHolder!, 
    finalPosition: Float)

This creates a SpringAnimation 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(). A Spring will be created with the given final position and default stiffness and damping ratio. This spring can be accessed and reconfigured through setSpring(SpringForce).

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
`finalPosition`	Float: the final position of the spring to be created.

<init>

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

This creates a SpringAnimation that animates the property of the given object. Note, a spring will need to setup through setSpring(SpringForce) before the animation starts.

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

<init>

SpringAnimation(
    object: K, 
    property: FloatPropertyCompat<K>!, 
    finalPosition: Float)

This creates a SpringAnimation that animates the property of the given object. A Spring will be created with the given final position and default stiffness and damping ratio. This spring can be accessed and reconfigured through setSpring(SpringForce).

Parameters
`object`	K: the Object whose property will be animated
`property`	FloatPropertyCompat<K>!: the property to be animated
`finalPosition`	Float: the final position of the spring to be created.
`<K>`	the class on which the Property is declared

Public methods

animateToFinalPosition

fun animateToFinalPosition(finalPosition: Float): Unit

Updates the final position of the spring.

When the animation is running, calling this method would assume the position change of the spring as a continuous movement since last frame, which yields more accurate results than changing the spring position directly through SpringForce#setFinalPosition(float).

If the animation hasn't started, calling this method will change the spring position, and immediately start the animation.

Parameters
`finalPosition`	Float: rest position of the spring

canSkipToEnd

fun canSkipToEnd(): Boolean

Queries whether the spring can eventually come to the rest position.

Return
`Boolean`	`true` if the spring is damped, otherwise `false`

cancel

@MainThread fun cancel(): Unit

Cancels the on-going animation. If the animation hasn't started, no op. Note that this method should only be called on main thread.

Exceptions
`AndroidRuntimeException`	if this method is not called on the main thread

getSpring

fun getSpring(): SpringForce!

Returns the spring that the animation uses for animations.

Return
`SpringForce!`	the spring that the animation uses for animations

setSpring

fun setSpring(force: SpringForce!): SpringAnimation!

Uses the given spring as the force that drives this animation. If this spring force has its parameters re-configured during the animation, the new configuration will be reflected in the animation immediately.

Parameters
`force`	SpringForce!: a pre-defined spring force that drives the animation

Return
`SpringAnimation!`	the animation that the spring force is set on

skipToEnd

fun skipToEnd(): Unit

Skips to the end of the animation. If the spring is undamped, an IllegalStateException will be thrown, as the animation would never reach to an end. It is recommended to check canSkipToEnd() before calling this method. This method should only be called on main thread. If animation is not running, no-op.

Exceptions
`IllegalStateException`	if the spring is undamped (i.e. damping ratio = 0)
`AndroidRuntimeException`	if this method is not called on the main thread

start

@MainThread fun start(): Unit