Transition

public sealed class Transition<S> protected constructor(
    private val transitionState: TransitionState<S>,
    @get:RestrictTo(RestrictTo.Scope.LIBRARY) public val parentTransition: Transition<*>?,
    public val label: String? = null,
)

Transition manages all the child animations on a state level. Child animations can be created in a declarative way using Transition.animateFloat, Transition.animateValue, animateColor etc. When the targetState changes, Transition will automatically start or adjust course for all its child animations to animate to the new target values defined for each animation.

After arriving at targetState, Transition will be triggered to run if any child animation changes its target value (due to their dynamic target calculation logic, such as theme-dependent values).

Properties

currentState

public val currentState: S

Current state of the transition. This will always be the initialState of the transition until the transition is finished. Once the transition is finished, currentState will be set to targetState. currentState is backed by a MutableState.

targetState

public var targetState: S by mutableStateOf(currentState)

Target state of the transition. This will be read by all child animations to determine their most up-to-date target values.

pendingTargetState

public var pendingTargetState: S? by mutableStateOf(null)

Pending target state of the transition. This is the state that the transition is waiting to animate to. It is non-null only when a deferred update is in progress.

segment

public var segment: Segment<S> by mutableStateOf(SegmentImpl(currentState, currentState))

segment contains the initial state and the target state of the currently on-going transition.

isRunning

public val isRunning: Boolean

Indicates whether there is any animation running in the transition.

playTimeNanos

public var playTimeNanos: Long

Play time in nano-seconds. playTimeNanos is always non-negative. It starts from 0L at the beginning of the transition and increment until all child animations have finished.

transitions

public val transitions: List<Transition<*>>

List of child transitions in a Transition.

animations

public val animations: List<TransitionAnimationState<*, *>>

List of TransitionAnimationStates that are in a Transition.

isSeeking

public var isSeeking: Boolean by mutableStateOf(false)

hasInitialValueAnimations

@get:Suppress("GetterSetterNames") // Don't care about Java name for this property
    public val hasInitialValueAnimations: Boolean

Used internally to know when a SeekableTransitionState is animating initial values after SeekableTransitionState.animateTo or SeekableTransitionState.seekTo has redirected a transition prior to it completing. This is important for knowing when child transitions must be maintained after a parent target state has changed, but the child target state hasn't changed.

totalDurationNanos

public val totalDurationNanos: Long by derivedStateOf { calculateTotalDurationNanos() }

Total duration of the Transition, accounting for all the animations and child transitions defined on the Transition.

Note: The total duration is subject to change as more animations/child transitions get added to Transition. It's strongly recommended to query this after all the animations in the Transition are set up.

Functions

toString

override fun toString(): String

Members

TransitionAnimationState

public inner class TransitionAnimationState<T, V : AnimationVector> internal constructor(
        initialValue: T,
        initialVelocityVector: V,
        public val typeConverter: TwoWayConverter<T, V>,
        public val label: String,
    ) : State<T>

Each animation created using animateFloat, animateDp, etc is represented as a TransitionAnimationState in Transition.

Properties

animationSpec

public var animationSpec: FiniteAnimationSpec<T> by mutableStateOf(defaultSpring)

AnimationSpec that is used for current animation run. This can change when targetState changes.

animation

public var animation: TargetBasedAnimation<T, V> by
            mutableStateOf(
                TargetBasedAnimation(
                    animationSpec,
                    typeConverter,
                    initialValue,
                    targetValue,
                    initialVelocityVector,
                )
            )

All the animation configurations including initial value/velocity & target value for animating from currentState to targetState are captured in animation.

value

override var value: T by mutableStateOf(initialValue)

Functions

toString

override fun toString(): String

Segment

public interface Segment<S>

Segment holds initialState and targetState, which are the beginning and end of a transition. These states will be used to obtain the animation spec that will be used for this transition from the child animations.

Properties

initialState

public val initialState: S

Initial state of a Transition Segment. This is the state that transition starts from.

targetState

public val targetState: S

Target state of a Transition Segment. This is the state that transition will end on.

Functions

isTransitioningTo

public infix fun S.isTransitioningTo(targetState: S): Boolean

Returns whether the provided state matches the initialState && the provided targetState matches Segment.targetState.