{% setvar book_path %}/reference/androidx/_book.yaml{% endsetvar %} {% include "_shared/_reference-head-tags.html" %}

AnimationState

public final class AnimationState<T extends Object, V extends AnimationVector> implements State


AnimationState contains the necessary information to indicate the state of an animation. Once an AnimationState is constructed, it can only be updated/mutated by animations. If there's a need to mutate some of the fields of an AnimationState, consider using copy functions.

Summary

Public constructors

<T extends Object, V extends AnimationVector> AnimationState(
    @NonNull TwoWayConverter<@NonNull T, @NonNull V> typeConverter,
    @NonNull T initialValue,
    V initialVelocityVector,
    long lastFrameTimeNanos,
    long finishedTimeNanos,
    boolean isRunning
)

Public methods

final long

The time when the animation finished successfully in the System.nanoTime timebase.

final long

Last frame time of the animation.

final @NonNull TwoWayConverter<@NonNull T, @NonNull V>

TwoWayConverter to convert type T from and to AnimationVector

@NonNull T

Current value of the AnimationState.

final @NonNull T

Velocity of type T, converted from velocityVector.

final @NonNull V

Current velocity vector of the AnimationState.

final boolean

Indicates whether the animation is currently running.

@NonNull String

Extension functions

final @NonNull AnimationState<@NonNull Float, @NonNull AnimationVector1D>
AnimationStateKt.copy(
    @NonNull AnimationState<@NonNull Float, @NonNull AnimationVector1D> receiver,
    float value,
    float velocity,
    long lastFrameTimeNanos,
    long finishedTimeNanos,
    boolean isRunning
)

Creates a new AnimationState of Float value type from a given AnimationState of the same type.

final @NonNull AnimationState<@NonNull T, @NonNull V>
<T extends Object, V extends AnimationVector> AnimationStateKt.copy(
    @NonNull AnimationState<@NonNull T, @NonNull V> receiver,
    @NonNull T value,
    V velocityVector,
    long lastFrameTimeNanos,
    long finishedTimeNanos,
    boolean isRunning
)

Creates a new AnimationState from a given AnimationState.

final boolean

Indicates whether the given AnimationState is for an animation that has finished, indicated by AnimationState.finishedTimeNanos having a specified value.

final void
<T extends Object, V extends AnimationVector> SuspendAnimationKt.animateDecay(
    @NonNull AnimationState<@NonNull T, @NonNull V> receiver,
    @NonNull DecayAnimationSpec<@NonNull T> animationSpec,
    boolean sequentialAnimation,
    @ExtensionFunctionType @NonNull Function1<@NonNull AnimationScope<@NonNull T, @NonNull V>, Unit> block
)

Decay animation that slows down from the current velocity and value captured in AnimationState until the velocity reaches 0.

final void
<T extends Object, V extends AnimationVector> SuspendAnimationKt.animateTo(
    @NonNull AnimationState<@NonNull T, @NonNull V> receiver,
    @NonNull T targetValue,
    @NonNull AnimationSpec<@NonNull T> animationSpec,
    boolean sequentialAnimation,
    @ExtensionFunctionType @NonNull Function1<@NonNull AnimationScope<@NonNull T, @NonNull V>, Unit> block
)

Target based animation that takes the value and velocity from the AnimationState as the starting condition, and animate to the targetValue, using the animationSpec.

Public constructors

AnimationState

public <T extends Object, V extends AnimationVector> AnimationState(
    @NonNull TwoWayConverter<@NonNull T, @NonNull V> typeConverter,
    @NonNull T initialValue,
    V initialVelocityVector,
    long lastFrameTimeNanos,
    long finishedTimeNanos,
    boolean isRunning
)
Parameters
@NonNull TwoWayConverter<@NonNull T, @NonNull V> typeConverter

TwoWayConverter to convert type T from and to AnimationVector

@NonNull T initialValue

initial value of the AnimationState

V initialVelocityVector

initial velocity of the AnimationState, null (i.e. no velocity) by default.

long lastFrameTimeNanos

last frame time of the animation, AnimationConstants.UnspecifiedTime by default

long finishedTimeNanos

the time that the animation finished successfully, AnimationConstants.UnspecifiedTime until then

boolean isRunning

whether the AnimationState is currently being updated by an animation. False by default

Public methods

getFinishedTimeNanos

public final long getFinishedTimeNanos()

The time when the animation finished successfully in the System.nanoTime timebase.

If the animation has never finished (i.e. currently running, interrupted, or never started), this will be AnimationConstants.UnspecifiedTime, unless specified otherwise in AnimationState constructor.

getLastFrameTimeNanos

public final long getLastFrameTimeNanos()

Last frame time of the animation.

If the animation has never started, this will be AnimationConstants.UnspecifiedTime, unless specified otherwise in the AnimationState constructor. lastFrameTimeNanos is the frame time when the animation is last updated, in the System.nanoTime timebase. It is also used for starting a sequential animation in AnimationState.animateTo. This allows the sequential animation to set its start time to when the previous animation is interrupted or finished.

getTypeConverter

public final @NonNull TwoWayConverter<@NonNull T, @NonNull V> getTypeConverter()

TwoWayConverter to convert type T from and to AnimationVector

getValue

public @NonNullgetValue()

Current value of the AnimationState.

getVelocity

public final @NonNullgetVelocity()

Velocity of type T, converted from velocityVector.

getVelocityVector

public final @NonNullgetVelocityVector()

Current velocity vector of the AnimationState.

isRunning

public final boolean isRunning()

Indicates whether the animation is currently running.

toString

public @NonNull String toString()

Extension functions

AnimationStateKt.copy

public final @NonNull AnimationState<@NonNull Float, @NonNull AnimationVector1DAnimationStateKt.copy(
    @NonNull AnimationState<@NonNull Float, @NonNull AnimationVector1D> receiver,
    float value,
    float velocity,
    long lastFrameTimeNanos,
    long finishedTimeNanos,
    boolean isRunning
)

Creates a new AnimationState of Float value type from a given AnimationState of the same type. This function allows some of the fields to be different in the new AnimationState.

Parameters
float value

value of the AnimationState, using the value of the given AnimationState by default

float velocity

velocity of the AnimationState, using the velocity of the given AnimationState by default.

long lastFrameTimeNanos

last frame time of the animation, same as the given AnimationState by default

long finishedTimeNanos

the time that the animation finished successfully, same as the given AnimationState by default.

boolean isRunning

whether the AnimationState is currently being updated by an animation. Same as the given AnimationState by default

Returns
@NonNull AnimationState<@NonNull Float, @NonNull AnimationVector1D>

A new AnimationState instance copied from the given instance, with some fields optionally altered

AnimationStateKt.copy

public final @NonNull AnimationState<@NonNull T, @NonNull V> <T extends Object, V extends AnimationVector> AnimationStateKt.copy(
    @NonNull AnimationState<@NonNull T, @NonNull V> receiver,
    @NonNull T value,
    V velocityVector,
    long lastFrameTimeNanos,
    long finishedTimeNanos,
    boolean isRunning
)

Creates a new AnimationState from a given AnimationState. This function allows some of the fields to be different in the new AnimationState.

Parameters
@NonNull T value

value of the AnimationState, using the value of the given AnimationState by default

V velocityVector

velocity of the AnimationState, using the velocity of the given AnimationState by default.

long lastFrameTimeNanos

last frame time of the animation, same as the given AnimationState by default

long finishedTimeNanos

the time that the animation finished successfully, AnimationConstants.UnspecifiedTime until then. Default value is the same as the given AnimationState.

boolean isRunning

whether the AnimationState is currently being updated by an animation. Same as the given AnimationState by default

Returns
@NonNull AnimationState<@NonNull T, @NonNull V>

A new AnimationState instance copied from the given instance, with some fields optionally altered

AnimationStateKt.isFinished

public final boolean AnimationStateKt.isFinished(
    @NonNull AnimationState<@NonNull ?, @NonNull ?> receiver
)

Indicates whether the given AnimationState is for an animation that has finished, indicated by AnimationState.finishedTimeNanos having a specified value.

SuspendAnimationKt.animateDecay

public final void <T extends Object, V extends AnimationVector> SuspendAnimationKt.animateDecay(
    @NonNull AnimationState<@NonNull T, @NonNull V> receiver,
    @NonNull DecayAnimationSpec<@NonNull T> animationSpec,
    boolean sequentialAnimation,
    @ExtensionFunctionType @NonNull Function1<@NonNull AnimationScope<@NonNull T, @NonNull V>, Unit> block
)

Decay animation that slows down from the current velocity and value captured in AnimationState until the velocity reaches 0. During the animation, the given AnimationState will be updated with the up-to-date value/velocity, frame time, etc. This is often used to animate the result of a fling gesture.

Parameters
@NonNull DecayAnimationSpec<@NonNull T> animationSpec

Defines the decay animation that will be used for this animation. Some options for animationSpec include: splineBasedDecay and exponentialDecay.

boolean sequentialAnimation

Indicates whether the animation should use the AnimationState.lastFrameTimeNanos as the starting time (if true), or start in a new frame. By default, sequentialAnimation is false, to start the animation in a few frame. In cases where an on-going animation is interrupted and a new animation is started to carry over the momentum, using the interruption time (captured in AnimationState.lastFrameTimeNanos) creates a smoother animation.

@ExtensionFunctionType @NonNull Function1<@NonNull AnimationScope<@NonNull T, @NonNull V>, Unit> block

will be invoked on every frame during the animation, and the AnimationScope will be checked against cancellation before the animation continues. To cancel the animation from the block, simply call AnimationScope.cancelAnimation. After AnimationScope.cancelAnimation is called, block will not be invoked again. The animation loop will exit after the block returns. All the animation related info can be accessed via AnimationScope.

SuspendAnimationKt.animateTo

public final void <T extends Object, V extends AnimationVector> SuspendAnimationKt.animateTo(
    @NonNull AnimationState<@NonNull T, @NonNull V> receiver,
    @NonNull T targetValue,
    @NonNull AnimationSpec<@NonNull T> animationSpec,
    boolean sequentialAnimation,
    @ExtensionFunctionType @NonNull Function1<@NonNull AnimationScope<@NonNull T, @NonNull V>, Unit> block
)

Target based animation that takes the value and velocity from the AnimationState as the starting condition, and animate to the targetValue, using the animationSpec. During the animation, the given AnimationState will be updated with the up-to-date value/velocity, frame time, etc.

import androidx.compose.animation.core.AnimationState
import androidx.compose.animation.core.Spring
import androidx.compose.animation.core.animate
import androidx.compose.animation.core.animateTo
import androidx.compose.animation.core.isFinished
import androidx.compose.animation.core.spring
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.remember

@Composable
fun simpleAnimate(
    target: Float,
): Float {
    // Create an AnimationState to be updated by the animation.
    val animationState = remember { AnimationState(target) }

    // Launch the suspend animation into the composition's CoroutineContext, and pass
    // `target` to LaunchedEffect so that when`target` changes the old animation job is
    // canceled, and a new animation is created with a new target.
    LaunchedEffect(target) {
        // This starts an animation that updates the animationState on each frame
        animationState.animateTo(
            targetValue = target,
            // Use a low stiffness spring. This can be replaced with any type of `AnimationSpec`
            animationSpec = spring(stiffness = Spring.StiffnessLow),
            // If the previous animation was interrupted (i.e. not finished), configure the
            // animation as a sequential animation to continue from the time the animation was
            // interrupted.
            sequentialAnimation = !animationState.isFinished
        )
        // When the function above returns, the animation has finished.
    }
    // Return the value updated by the animation.
    return animationState.value
}
Parameters
@NonNull T targetValue

The target value that the animation will animate to.

@NonNull AnimationSpec<@NonNull T> animationSpec

The animation configuration that will be used. spring by default.

boolean sequentialAnimation

Indicates whether the animation should use the AnimationState.lastFrameTimeNanos as the starting time (if true), or start in a new frame. By default, sequentialAnimation is false, to start the animation in a few frame. In cases where an on-going animation is interrupted and a new animation is started to carry over the momentum, using the interruption time (captured in AnimationState.lastFrameTimeNanos) creates a smoother animation.

@ExtensionFunctionType @NonNull Function1<@NonNull AnimationScope<@NonNull T, @NonNull V>, Unit> block

Will be invoked on every frame, and the AnimationScope will be checked against cancellation before the animation continues. To cancel the animation from the block, simply call AnimationScope.cancelAnimation. After AnimationScope.cancelAnimation is called, block will not be invoked again. The animation loop will exit after the block returns. All the animation related info can be accessed via AnimationScope.