Skip to main content

sui_core/
motion.rs

1/// How much motion the user wants to see.
2///
3/// Operating systems expose this as an accessibility setting (Windows "Show
4/// animations in Windows", macOS "Reduce motion", the web's
5/// `prefers-reduced-motion`). Motion can trigger discomfort, so widgets honor
6/// it by dropping movement rather than just shortening it.
7#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
8pub enum MotionPreference {
9    /// Play every animation.
10    #[default]
11    Full,
12    /// Keep fades and color changes, but drop movement: surfaces fade in place
13    /// instead of sliding, and sliding indicators jump to their destination.
14    Reduced,
15    /// Skip animations: every transition finishes immediately.
16    Off,
17}
18
19impl MotionPreference {
20    pub const ALL: [Self; 3] = [Self::Full, Self::Reduced, Self::Off];
21
22    pub const fn label(self) -> &'static str {
23        match self {
24            Self::Full => "Full",
25            Self::Reduced => "Reduced",
26            Self::Off => "Off",
27        }
28    }
29}
30
31/// The motion policy in effect: the user's [`MotionPreference`] plus a time
32/// scale for watching transitions in slow motion while debugging.
33#[derive(Debug, Clone, Copy, PartialEq)]
34pub struct MotionPolicy {
35    pub preference: MotionPreference,
36    /// Playback speed of transitions relative to their nominal durations:
37    /// `0.25` plays them at quarter speed. Values are kept at or above
38    /// [`MotionPolicy::MIN_TIME_SCALE`].
39    pub time_scale: f32,
40}
41
42impl MotionPolicy {
43    pub const MIN_TIME_SCALE: f32 = 0.01;
44    pub const FULL: Self = Self::new(MotionPreference::Full);
45
46    pub const fn new(preference: MotionPreference) -> Self {
47        Self {
48            preference,
49            time_scale: 1.0,
50        }
51    }
52
53    pub const fn with_time_scale(mut self, time_scale: f32) -> Self {
54        self.time_scale = time_scale;
55        self
56    }
57
58    /// Whether transitions animate at all.
59    pub fn allows_motion(self) -> bool {
60        self.preference != MotionPreference::Off
61    }
62
63    /// Whether transitions may move content across the screen.
64    pub fn allows_movement(self) -> bool {
65        self.preference == MotionPreference::Full
66    }
67
68    /// The effective time scale, kept positive.
69    pub fn time_scale(self) -> f32 {
70        if self.time_scale.is_finite() {
71            self.time_scale.max(Self::MIN_TIME_SCALE)
72        } else {
73            1.0
74        }
75    }
76
77    /// How long a transition that lasts `nominal` seconds at full motion
78    /// should take: zero when motion is off, stretched by the time scale
79    /// otherwise.
80    pub fn duration(self, nominal: f64) -> f64 {
81        if self.allows_motion() {
82            nominal.max(0.0) / f64::from(self.time_scale())
83        } else {
84            0.0
85        }
86    }
87
88    /// Like [`MotionPolicy::duration`], for a transition that moves content:
89    /// zero unless the policy allows movement.
90    pub fn movement_duration(self, nominal: f64) -> f64 {
91        if self.allows_movement() {
92            self.duration(nominal)
93        } else {
94            0.0
95        }
96    }
97
98    /// Scale a frame delta for animation driven by elapsed time, such as a
99    /// timeline player or a simulation, so it follows the time scale.
100    pub fn scale_delta(self, delta: f64) -> f64 {
101        delta * f64::from(self.time_scale())
102    }
103
104    /// The share of an entrance offset (such as a popover sliding into
105    /// place) to apply at `progress`, from 1 when hidden to 0 when shown.
106    /// Without movement, surfaces fade in place.
107    pub fn entrance_offset(self, progress: f32) -> f32 {
108        if self.allows_movement() {
109            1.0 - progress
110        } else {
111            0.0
112        }
113    }
114}
115
116impl Default for MotionPolicy {
117    fn default() -> Self {
118        Self::FULL
119    }
120}
121
122#[cfg(test)]
123mod tests {
124    use super::{MotionPolicy, MotionPreference};
125
126    #[test]
127    fn full_motion_keeps_nominal_durations() {
128        let policy = MotionPolicy::FULL;
129
130        assert_eq!(policy.duration(0.14), 0.14);
131        assert_eq!(policy.movement_duration(0.14), 0.14);
132        assert_eq!(policy.entrance_offset(0.25), 0.75);
133    }
134
135    #[test]
136    fn time_scale_stretches_durations_and_slows_deltas() {
137        let policy = MotionPolicy::FULL.with_time_scale(0.25);
138
139        assert_eq!(policy.duration(0.1), 0.4);
140        assert_eq!(policy.scale_delta(0.1), 0.025);
141        assert_eq!(
142            MotionPolicy::FULL.with_time_scale(0.0).time_scale(),
143            MotionPolicy::MIN_TIME_SCALE
144        );
145        assert_eq!(
146            MotionPolicy::FULL.with_time_scale(f32::NAN).time_scale(),
147            1.0
148        );
149    }
150
151    #[test]
152    fn reduced_motion_keeps_fades_but_drops_movement() {
153        let policy = MotionPolicy::new(MotionPreference::Reduced);
154
155        assert!(policy.allows_motion());
156        assert!(!policy.allows_movement());
157        assert_eq!(policy.duration(0.14), 0.14);
158        assert_eq!(policy.movement_duration(0.14), 0.0);
159        assert_eq!(policy.entrance_offset(0.25), 0.0);
160    }
161
162    #[test]
163    fn motion_off_finishes_every_transition_immediately() {
164        let policy = MotionPolicy::new(MotionPreference::Off);
165
166        assert!(!policy.allows_motion());
167        assert_eq!(policy.duration(0.34), 0.0);
168        assert_eq!(policy.movement_duration(0.34), 0.0);
169    }
170}