Struct Transition 

pub struct Transition<T: Lerp + Clone + PartialEq + 'static> { /* private fields */ }

A value that moves toward a goal over time and changes course when that goal changes.

A Transition pairs an entity that holds a TransitionState with a Motion. Read the value for the current frame with evaluate during render. Change the goal with update from an event handler, then call cx.notify() so the view redraws. T must implement Lerp, Clone and PartialEq.

Clones share the goal and motion state, but each has its own per-frame cache. Read the value through the clone that is rendering it.

Create one during render with Window::use_keyed_transition. Its key keeps the state across frames. Window::use_transition keys state by call site instead, so that state lasts only while the element renders at that call site in consecutive frames.

Continuous and non-continuous mode

Transitions are continuous by default. When the goal changes:

• Continuous (the default): the value continues from where it is now toward the new goal.
• Non-continuous (continuous(false)): the value restarts from the initial value and moves toward the new goal.

Examples

The goal can change from an event handler, and the value follows it. This example uses an easing of |_| 0.5, so the value sits halfway between its start and its goal, and the assertions are exact.

use gpui::{
    AppContext, Context, IntoElement, Render, TestApp, Transition, TransitionState, Window,
    div, prelude::*, secs,
};

struct Fade {
    transition: Transition<f32>,
}

impl Render for Fade {
    fn render(&mut self, window: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
        let opacity = *self.transition.evaluate(window, cx);
        div().opacity(opacity)
    }
}

let mut app = TestApp::new();
let mut window = app.open_window(|_, cx| {
    let state = cx.new(|_| TransitionState::new(0.0_f32, secs(10)));
    Fade {
        transition: Transition::new(state, secs(10)).with_easing(|_| 0.5),
    }
});

window.update(|view, _, cx| {
    view.transition.update(cx, |goal, cx| {
        *goal = 1.0;
        cx.notify();
    });
});
window.draw();

window.update(|view, _, cx| {
    assert_eq!(*view.transition.read_cache(), Some(0.5));
    assert_eq!(*view.transition.read_goal(cx), 1.0);
});

See the animation guide for the keyed hook.

Implementations

impl<T: Lerp + Clone + PartialEq + 'static> Transition<T>

pub fn new(state: Entity<TransitionState<T>>, motion: impl Into<Motion>) -> Self

Creates a transition that stores its state in state and animates with motion.

Inside render, prefer Window::use_keyed_transition, which creates the state for you.

pub fn with_easing(self, easing: impl Fn(f32) -> f32 + 'static) -> Self

Sets the easing of the forward pass. See Motion::with_easing.

The easing maps normalized pass time to presentation progress. It may be non-monotonic, and it may overshoot zero through one.

pub fn continuous(self, continuous: bool) -> Self

Sets whether a new goal continues from the current value.

Continuous is the default. Pass false to restart from the initial value on every goal change instead.

pub fn evaluate(&self, window: &mut Window, cx: &mut App) -> Ref<'_, T>

Returns the value for the current frame, and requests another frame while it moves.

The value depends on the time since the last goal change, and on the easing. The first call samples the clock and caches the result. Later calls return the cached value until the goal changes or the cache is cleared, so a Transition kept across frames returns the same value. Window::use_keyed_transition returns a new Transition on every render, which avoids this. Call this during render or paint.

pub fn read_goal<'b>(&'b self, cx: &'b mut App) -> &'b T

Returns the goal: the value most recently set by update.

This isn’t the value on screen while the transition moves. Use evaluate for that.

pub fn read_cache(&self) -> Ref<'_, Option<T>>

Returns the value cached by the last evaluate, or None if the cache was cleared.

The cache is cleared when the goal changes, and by jump_to, scale_by, reset and with_easing.

pub fn evaluate_delta(&self, cx: &App) -> f32

Returns the eased progress for the current frame, without requesting another frame.

Progress may overshoot zero through one. It doesn’t mean the run has finished: restarting iterations begin again, and alternating iterations run in reverse.

pub fn update<R>( &self, cx: &mut App, update: impl FnOnce(&mut T, &mut Context<'_, TransitionState<T>>) -> R, ) -> bool

Changes the goal, and starts a run toward the new goal if it changed.

update passes the current goal to the closure, which can change it. If the new goal differs from the old one, the value moves toward it. In continuous mode the run starts from the current value. Otherwise it starts from the initial value. The goal isn’t read during render, so change it from an event handler.

Returns true if the goal changed, and false if it stayed the same.

This doesn’t notify GPUI. Call cx.notify() inside the closure to redraw the view.

pub fn jump_to(&self, target: T, cx: &mut App)

Sets the value and the goal to target, with no animation.

Later calls to evaluate return target until the goal changes again. Use this when the next animation should start from a different value.

pub fn scale_by(&self, ratio: f32, cx: &mut App)

where T: Mul<f32, Output = T>,

Multiplies the start value and the goal by ratio.

An in-flight transition keeps its progress when the coordinate space changes, such as a window resize. Pass the ratio of the new scale to the old one.

pub fn entity_id(&self) -> EntityId

Returns the ID of the entity that holds this transition’s state.

Use it to tell two transitions apart.

pub fn reset(&self, cx: &mut App)

Returns the transition to its initial value, with no animation.

This clears any progress and sets the goal back to the value the transition was created with. The cache is cleared too.

Trait Implementations

impl<T: Clone + Lerp + Clone + PartialEq + 'static> Clone for Transition<T>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.