Struct Motion 

pub struct Motion<Description = DurationDescription> { /* private fields */ }

A deterministic, time-sampled motion from a start value to a target.

Motion describes how a value moves over time, and it doesn’t hold the value. It is either duration-based (the default) or spring-based, depending on Description. Call Motion::sample with the time since the run started to get the progress and the lifecycle state at that moment.

A duration motion has one forward MotionPass, an optional reverse pass, an initial delay, and a Playback policy. The default is one forward iteration with no delay. The delay applies once, when a run begins.

Motion::iterations counts total iterations, including the first. Restarting motion begins each iteration with local time at zero. Motion::alternate starts forward, then uses a backward leg on every second iteration. Direction::AlternateReverse starts backward instead. With conventional easing endpoints, forward-first alternating motion rests at its target after an odd count and at its origin after an even count. Reverse-first alternating motion has the opposite endpoints. Custom easing endpoints may settle elsewhere, including outside zero through one.

A backward leg uses the configured reverse pass, or reuses the forward pass’s duration and easing if no reverse pass is configured. Reverse local time still advances from zero to one and is eased in that direction. The resulting presentation progress is 1 - eased. For example, reverse ease-in starts the backward leg slowly and accelerates toward the origin.

Local pass time is normalized. Eased presentation may overshoot, as in upstream spring easing, while pass selection remains deterministic. Finite zero-duration motion resolves immediately once its initial delay is satisfied, with the configured direction and iteration parity determining the final presentation. A zero-length leg in otherwise nonzero alternating motion is instantaneous. Indefinite motion whose applicable passes all have zero duration becomes inactive instead of requesting animation frames forever.

Examples

Ease a one-pass motion. At a quarter of the way through, ease_in_out gives 0.125.

use gpui::{Motion, ease_in_out, millis};

let motion = Motion::new(millis(200)).with_easing(ease_in_out);
assert_eq!(motion.sample(millis(50)).progress.get(), 0.125);
assert!(motion.sample(millis(200)).is_at_end());

Restart the pass three times. Each iteration begins again from zero.

use gpui::{Motion, millis};

let motion = Motion::new(millis(1000)).iterations(3);
let sample = motion.sample(millis(2500));
assert_eq!(sample.iteration, 2);
assert_eq!(sample.local_time.get(), 0.5);
assert!(motion.sample(millis(3000)).is_complete());

Alternate the direction. After an even number of iterations the motion rests at its origin.

use gpui::{Motion, Progress, millis};

let motion = Motion::new(millis(1000)).iterations(2).alternate();
assert_eq!(motion.sample(millis(1500)).progress.get(), 0.5);
assert_eq!(motion.sample(millis(2000)).progress, Progress::START);

Implementations

impl Motion<DurationDescription>

pub fn new(duration: Duration) -> Self

Creates a one-pass linear motion of duration, with no delay, run once.

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

Sets the easing of the forward pass.

An alternating motion without an explicit reverse pass uses this easing for its backward legs too.

pub fn with_spring(self, config: SpringConfig) -> Self

Replaces the easing with a spring sampled over this motion’s duration.

The spring starts at rest and reaches its target at the end of the duration. It doesn’t settle on its own and it doesn’t keep velocity across retargets. For a spring that settles and keeps its velocity, use Motion::spring.

pub fn with_forward_pass(self, pass: MotionPass) -> Self

Replaces the forward pass, including its duration and easing.

pub fn with_reverse_pass(self, pass: MotionPass) -> Self

Sets the pass used for backward legs.

This doesn’t infer direction from changes to an Animated target. A newly retargeted run begins with its configured direction. Without an explicit reverse pass, backward legs reuse the forward pass’s duration and easing.

Reverse local time advances from zero to one and is eased normally. Its presentation is then mapped as 1 - eased, so a reverse ease-in begins slowly and accelerates toward the origin.

pub fn with_delay(self, delay: Duration) -> Self

Delays the start of the run by delay.

The delay applies once, before the first iteration. Restarted iterations don’t wait again. During the delay, the progress is the start value of the run.

pub fn iterations(self, iterations: u32) -> Self

Sets the total number of iterations, including the first.

The default is one. Each iteration restarts local timing. In forward-first alternating motion, odd-numbered iterations are forward and even-numbered iterations are backward. With conventional easing endpoints, counts of one and three rest at the target, and counts of two and four rest at the origin.

Panics

Panics if iterations is zero.

pub fn repeat_forever(self) -> Self

Repeats this motion without end.

Each iteration restarts from the start unless the motion alternates. A motion whose applicable passes all have zero duration becomes MotionPhase::Inactive, resting at a deterministic presentation.

pub fn alternate(self) -> Self

Alternates the direction of successive iterations.

Odd-numbered iterations use the forward pass. Even-numbered iterations use the reverse pass, or the forward pass when none is configured. This is the same as direction(Direction::Alternate).

pub fn direction(self, direction: Direction) -> Self

Sets the direction of successive iterations.

pub fn with_playback(self, playback: Playback) -> Self

Replaces the whole playback policy: iterations and direction.

pub fn forward_pass(&self) -> &MotionPass

Returns the forward pass.

pub fn reverse_pass(&self) -> Option<&MotionPass>

Returns the reverse pass, or None when backward legs reuse the forward pass.

pub fn delay(&self) -> Duration

Returns the delay applied before the first iteration.

pub const fn playback(&self) -> Playback

Returns the iteration count and direction of this motion.

pub fn checked_extent(&self) -> Option<MotionExtent>

Returns the total length of the run, including the delay.

Returns MotionExtent::Infinite for Motion::repeat_forever. Returns None only when a finite total is too large for Duration.

Examples

use gpui::{Motion, MotionExtent, millis};

let motion = Motion::new(millis(300)).with_delay(millis(200)).iterations(3);
assert_eq!(motion.checked_extent(), Some(MotionExtent::Finite(millis(1100))));

pub fn sample(&self, elapsed: Duration) -> MotionSample

Samples this motion at elapsed, measured from the start of the run.

Before the delay ends, the phase is MotionPhase::Delayed. After the last iteration of a finite run, it is MotionPhase::Completed at the final progress. Pass selection, iteration parity and completion use integer nanosecond arithmetic. Only the fraction within the selected pass is converted to a float for easing.

pub fn sample_at<Time>(&self, started_at: Time, now: Time) -> MotionSample

where Time: Sub<Time, Output = Duration>,

Samples this motion at now, given the time started_at when the run began.

Time can be any type that subtracts to a Duration, such as std::time::Instant or the executor’s clock.

impl Motion<SpringDescription>

pub fn spring(config: SpringConfig) -> Self

Creates a spring that runs until it settles.

Give the spring a target with Motion::to. The settling tolerance defaults to 0.001. Change it with Motion::with_epsilon.

pub fn config(&self) -> SpringConfig

Returns the physical parameters of this spring.

pub fn epsilon(&self) -> f32

Returns the settling tolerance of this spring.

pub fn with_epsilon(self, epsilon: f32) -> Self

Sets how close the spring must be to its target before it counts as settled.

The tolerance applies to position, and to velocity scaled by the spring’s natural frequency. Changing it also recomputes the settling time, which is when Motion::sample reports MotionPhase::Completed.

pub fn sample(&self, elapsed: Duration) -> MotionSample

Samples this spring at elapsed, starting from rest at zero progress.

Progress is the spring’s position, which overshoots when the spring is underdamped. From the settling time onward the sample is MotionPhase::Completed at Progress::END, and it is no longer active.

Examples

use gpui::{Motion, Progress, millis, secs, spring};

let motion = Motion::spring(spring(100., 10., 1.));
assert!(motion.sample(millis(0)).is_active);
let settled = motion.sample(secs(10));
assert!(settled.is_complete());
assert_eq!(settled.progress, Progress::END);

pub fn to<T: SpringTarget>(self, target: T) -> SpringAnimation<T>

Targets target with this spring.

The result is a SpringAnimation for AnimationExt::with_spring.

Trait Implementations

impl<Description: Clone> Clone for Motion<Description>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<Description: Debug> Debug for Motion<Description>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Motion<DurationDescription>

fn default() -> Self

Returns the “default value” for a type.

impl<Description> Deref for Motion<Description>

type Target = Description

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<Description> DerefMut for Motion<Description>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl From<&Motion<SpringDescription>> for AnyMotion

fn from(motion: &Motion<SpringDescription>) -> Self

Converts to this type from the input type.

impl From<&Motion> for AnyMotion

fn from(motion: &Motion<DurationDescription>) -> Self

Converts to this type from the input type.

impl From<Duration> for Motion<DurationDescription>

fn from(duration: Duration) -> Self

Converts to this type from the input type.

impl From<Motion<SpringDescription>> for AnyMotion

fn from(motion: Motion<SpringDescription>) -> Self

Converts to this type from the input type.

impl From<Motion> for AnyMotion

fn from(motion: Motion<DurationDescription>) -> Self

Converts to this type from the input type.

impl From<SpringConfig> for Motion<SpringDescription>

fn from(config: SpringConfig) -> Self

Converts to this type from the input type.