Transition

public class Transition<S>
internal 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).

Secondary Constructors

@PublishedApi
internal constructor(
    transitionState: TransitionState<S>,
    label: String? = null,
) : this(transitionState, null, label)

internal constructor(
    initialState: S,
    label: String?,
) : this(MutableTransitionState(initialState), null, label)

@PublishedApi
internal constructor(
    transitionState: MutableTransitionState<S>,
    label: String? = null,
) : this(transitionState as TransitionState<S>, null, label)

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

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

segment

public var segment: Segment<S>

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

@get:RestrictTo(RestrictTo.Scope.LIBRARY)
@set:RestrictTo(RestrictTo.Scope.LIBRARY)
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

@get:RestrictTo(RestrictTo.Scope.LIBRARY)
@set:RestrictTo(RestrictTo.Scope.LIBRARY)
public var isSeeking: Boolean

hasInitialValueAnimations

@InternalAnimationApi
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

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

setPlaytimeAfterInitialAndTargetStateEstablished

@RestrictTo(RestrictTo.Scope.LIBRARY_GROUP_PREFIX)

public fun setPlaytimeAfterInitialAndTargetStateEstablished(
    initialState: S,
    targetState: S,
    playTimeNanos: Long,
)

This allows tools to set the transition (between initial and target state) to a specific playTimeNanos.

Note: This function is intended for tooling use only.

Caveat: Once initialState or targetState changes, it needs to take a whole composition pass for all the animations and child transitions to recompose with the new initialState and targetState. Subsequently all the animations will be updated to the given play time.

Caveat: This function puts Transition in a manual playtime setting mode. From then on the Transition will not resume normal animation runs.