TransitionDefinition

<init>

TransitionDefinition()

TransitionDefinition contains all the animation related configurations that will be used in a state-based transition. It holds a set of TransitionStates and an optional set of TransitionSpecs. It can be used in androidx.compose.animation.transition to create a state-based animation in Compose.

Each TransitionState specifies how the UI should look in terms of values associated with properties that differentiates the UI from one conceptual state to anther. Each TransitionState can be considered as a snapshot of the UI in the form of property values.

TransitionSpec defines how to animate from one state to another with a specific animation for each property defined in the states. TransitionSpec can be created using transition method inside of a TransitionDefinition. Currently the animations supported in a transition are: tween, keyframes, spring, snap, repeatable. When no TransitionSpec is specified, the default spring animation will be used for all properties involved. Similarly, when no animation is provided in a TransitionSpec for a particular property, the default physics animation will be used. For each transition, both the from and the to state can be omitted. Omitting in this case is equivalent to a wildcard on the starting state or ending state. When both are omitted at the same time, it means this transition applies to all the state transitions unless a more specific transition have been defined.

To create a TransitionDefinition, there are generally 3 steps involved:

Step 1: Create PropKeys. One PropKey is required for each property/value that needs to be animated. These should be file level properties, so they are visible to TransitionDefinition ( which will be created in step 3).

    val radius = FloatPropKey()
    val alpha = FloatPropKey()

Step 2 (optional): Create state names.

This is an optional but recommended step to create a reference for different states that the animation should end at. State names can be of type T, which means they can be string, integer, etc, or any custom object, so long as they are consistent.

It is recommended to either reuse the states that you already defined (e.g. TogglableState.On, TogglableState.Off, etc) for animating those state changes, or create an enum class for all the animation states.

    enum class ButtonState {
        Released, Pressed, Disabled
    }

Step 3: Create a TransitionDefinition using the animation DSL.

TransitionDefinition is conceptually an animation configuration that defines:

1. States, each of which are described as a set of values. Each value is associated with a PropKey.
2. Optional transitions, for how to animate from one state to another.

import androidx.compose.animation.core.keyframes
import androidx.compose.animation.core.spring
import androidx.compose.animation.core.transitionDefinition

val definition = transitionDefinition<ButtonState> {
    state(ButtonState.Pressed) {
        this[alpha] = 0f
        this[radius] = 200f
    }
    state(ButtonState.Released) {
        this[alpha] = 0f
        this[radius] = 60f
    }

    // Optional configuration for transition from Pressed to Released. If no transition is
    // defined, the default physics-based transition will be used.
    transition(fromState = ButtonState.Released, toState = ButtonState.Pressed) {
        radius using spring(
            dampingRatio = 1.0f
        )
        alpha using keyframes {
            durationMillis = 375
            0f at 0 // ms  // Optional
            0.4f at 75 // ms
            0.4f at 225 // ms
            0f at 375 // ms  // Optional
        }
        interruptionHandling = InterruptionHandling.UNINTERRUPTIBLE
    }
}

getStateFor

fun getStateFor(name: T): TransitionState

Returns a state holder for the specific state name. Useful for the cases where we don't need actual animation to be happening like in tests.

snapTransition

fun snapTransition(
    vararg fromToPairs: Pair<T?, T?>, 
    nextState: T? = null
): Unit

With this transition definition we are saying that every time we reach the state 'from' we should immediately snap to 'to' state instead.

Sample of usage with Pairs infix extension to: snapTransition(State.Released to State.Pressed)

state

fun state(
    name: T, 
    init: MutableTransitionState.() -> Unit
): Unit

Defines all the properties and their values associated with the state with the name: name The first state defined in the transition definition will be the default state, whose property values will be used as its initial values to createAnimation from.

Note that the first MutableTransitionState created with state in a TransitionDefinition will be used as the initial state.

transition

fun transition(
    fromState: T? = null, 
    toState: T? = null, 
    init: TransitionSpec<T>.() -> Unit
): Unit

Defines a transition from state fromState to toState. When animating from one state to another, TransitionAnimation will find the most specific matching transition, and use the animations defined in it for the state transition. Both fromState and