rdi_core/
events.rs

1//! Event and mode types passed to observer callbacks and returned from
2//! [`AnimationHandle`](crate::AnimationHandle) queries.
3
4use std::time::{Duration as StdDuration, Instant};
5
6use crate::{IconId, Point};
7
8/// How to leave the desktop when [`AnimationHandle::stop`] is invoked.
9///
10/// [`AnimationHandle::stop`]: crate::AnimationHandle::stop
11#[derive(Copy, Clone, Debug, PartialEq, Eq)]
12pub enum StopMode {
13    /// Icons keep their current, mid-animation positions.
14    LeaveInPlace,
15    /// Icons snap to their target positions immediately.
16    TeleportToTarget,
17}
18
19/// Why an animation ended. Delivered through the observer `on_finish` hook
20/// and returned from [`AnimationHandle::wait`].
21///
22/// [`AnimationHandle::wait`]: crate::AnimationHandle::wait
23#[derive(Clone, Debug, PartialEq)]
24pub enum FinishReason {
25    /// All active icons reached their targets.
26    Completed,
27    /// The animation was stopped by an explicit
28    /// [`AnimationHandle::stop`](crate::AnimationHandle::stop) call.
29    Stopped(StopMode),
30    /// The backend reported a fatal error mid-animation.
31    ///
32    /// The string carries a human-readable description of the underlying
33    /// [`DesktopError`](crate::DesktopError). The enum itself is not
34    /// retained, so `FinishReason` stays cheap to clone and safe to
35    /// send across language boundaries.
36    Error(String),
37}
38
39/// Per-icon state, captured under a snapshot lock.
40#[derive(Clone, Debug, PartialEq)]
41pub struct IconAnimationState {
42    pub id: IconId,
43    pub origin: Point,
44    pub current: Point,
45    pub target: Point,
46    /// Normalized time in `[0, 1]` — how far this icon is through its own
47    /// animation, independent of the global animation clock.
48    pub t: f32,
49    /// `true` once the engine has issued the icon's final commit.
50    pub is_final: bool,
51}
52
53/// Payload for `on_start`.
54#[derive(Clone, Debug)]
55pub struct StartContext {
56    pub total_icons: usize,
57    pub missing_icons: usize,
58    pub started_at: Instant,
59}
60
61/// Payload for `on_tick`.
62#[derive(Clone, Debug)]
63pub struct TickContext {
64    /// Wall-clock time since the animation started.
65    pub elapsed: StdDuration,
66    /// Global progress `∈ [0, 1]` (average per-icon `t`, weighted equally).
67    pub progress: f32,
68    /// Icons still moving.
69    pub active_icons: usize,
70    /// Icons that have already reached their target this animation.
71    pub finalized_icons: usize,
72}
rdi_core/events.rs

rdi_core/
events.rs
