Struct AnimationController 

pub struct AnimationController { /* private fields */ }

A 0.0..=1.0 animation value driven either by a duration + Curve or by a Spring fling.

It is plain data + math (see the module docs’ contract): it holds no clock and no scheduler. A widget advances it during paint with the frame’s FrameTime, reads value, and re-requests a frame while advance keeps returning true.

Status semantics

forward/reverse drive to the 1.0/ 0.0 bounds and settle as Completed/Dismissed. animate_to settles as Completed when it moved forward (target ≥ start) and Dismissed when it moved reverse. repeat never completes (advance always returns true). A fling settles at 1.0 (positive velocity) or 0.0 (negative) as Completed/Dismissed.

Overshoot (spring-driven only)

Duration+Curve motion (forward/reverse/animate_to/repeat) always keeps value in 0.0..=1.0 — unchanged from before this contract existed. A fling, by contrast, is not clamped while in flight: an under-damped SpringDesc (M3’s spatial presets use damping_ratio: 0.9) genuinely overshoots its target before settling, and that overshoot is the whole visual point of a “bouncy” spring — clamping it away would hide it. value() may therefore transiently read outside [0, 1] mid-fling; it always lands exactly on the target (0.0/1.0) once advance reports settled (status() becomes Completed/Dismissed). A consumer that needs the value pinned to [0, 1] at every frame (e.g. to feed a Lerp/Tween that assumes bounded input) should use value_clamped instead. A critically-/over-damped spring (damping_ratio >= 1.0, e.g. M3’s “effects” presets) released with zero velocity (the common “settle to target” fling usage) never overshoots in the first place, so value()/value_clamped() agree for that case; a large enough release velocity can still carry even a critically-/over-damped spring past its target before it settles back — damping ratio bounds oscillation (repeated overshoot), not a single one.

Implementations

impl AnimationController

pub fn new(duration: Duration) -> Self

Create an idle controller at value 0.0 with the given default duration and a Curve::Linear easing.

pub fn with_curve(self, curve: Curve) -> Self

Set the easing curve applied to duration-driven motion (returns self for builder-style construction).

pub fn value(&self) -> f64

The current value.

For duration+Curve motion this is always in 0.0..=1.0. For a spring fling it may transiently read outside that range — an under-damped spring’s overshoot is real motion, not a bug (see the type docs’ Overshoot section) — but always lands exactly on the target once the fling settles. Use value_clamped if a bounded [0, 1] read is required instead.

pub fn value_clamped(&self) -> f64

value, clamped to 0.0..=1.0.

Identical to value() for duration+Curve motion (already bounded); for a spring fling mid-overshoot this clips the transient excursion past the target — for consumers (e.g. a Lerp/Tween feed) that need a bounded value and don’t want the bounce visually represented.

pub fn status(&self) -> AnimationStatus

The current lifecycle status.

pub fn is_animating(&self) -> bool

Whether a motion is currently in progress (the next advance will make progress).

pub fn forward(&mut self)

Animate forward to 1.0 over the controller’s duration.

pub fn reverse(&mut self)

Animate reverse to 0.0 over the controller’s duration.

pub fn animate_to(&mut self, target: f64)

Animate from the current value to target (clamped to 0.0..=1.0) over the controller’s duration.

pub fn repeat(&mut self)

Loop 0.0→1.0 (eased) indefinitely with a period of the controller’s duration. advance always returns true for a repeat.

pub fn fling(&mut self, velocity: f64, spring: SpringDesc)

Start a spring fling from the current value with initial velocity (in value-units per second). It settles toward 1.0 for a non-negative velocity, 0.0 otherwise.

Unlike duration+Curve motion, the value driven by a fling is not clamped to [0, 1] while in flight — see the type docs’ Overshoot section and value/ value_clamped.

pub fn stop(&mut self)

Halt any in-progress motion, leaving the value where it is and the status AnimationStatus::Idle.

pub fn advance(&mut self, now: FrameTime) -> bool

Advance the animation to frame time now, returning whether it is still animating (in which case the caller must request another frame).

The delta from the previous advance is derived via FrameTime::saturating_sub, so a repeated or out-of-order timestamp yields a zero (never negative) delta: safe, no panic, no NaN. The first advance after starting a motion only seeds the clock (zero delta); the next one makes progress.

Trait Implementations

impl Clone for AnimationController

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for AnimationController

impl Debug for AnimationController

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

Formats the value using the given formatter.