SpringAnimation
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 |
|
---|---|
Public constructors |
|
---|---|
<init>(floatValueHolder: FloatValueHolder!) This creates a SpringAnimation that animates a |
|
<init>(floatValueHolder: FloatValueHolder!, finalPosition: Float) This creates a SpringAnimation that animates a |
|
<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 |
Queries whether the spring can eventually come to the rest position. |
Unit |
cancel() Cancels the on-going animation. |
SpringForce! |
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 |
Skips to the end of the animation. |
Unit |
start() |
Inherited functions |
|
---|---|
Extension functions |
||
---|---|---|
From androidx.dynamicanimation.animation
|
Inherited properties |
|
---|---|
Public constructors
<init>
SpringAnimation(floatValueHolder: FloatValueHolder!)
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()
.
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 |
FloatValueHolder!: 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 |
K: the property to be animated |
<K> |
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 |
K: the property to be animated |
finalPosition |
K: the final position of the spring to be created. |
<K> |
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 throughSpringForce#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