Skip to main content

sim_logic/ui/pointer_button/
events.rs

1use crate::{
2    identity::TransitionIntentToken,
3    input::{InputCancellationReason, PointerSample},
4};
5
6/// Why a captured button interaction ended without a click.
7#[derive(Debug, Clone, Copy, PartialEq, Eq)]
8#[non_exhaustive]
9pub enum PointerButtonCancellation {
10    /// The input runtime cancelled the physical mouse hold.
11    Input(InputCancellationReason),
12    /// The release was outside the captured target, outside the viewport, or
13    /// over a target the caller no longer considers eligible.
14    ReleasedOutside,
15    /// An ordinary release had no known pointer position.
16    MissingPointer,
17}
18
19/// One change emitted while interpreting an individual mouse action edge.
20///
21/// Targets are caller-owned identities. Samples and tokens come from this
22/// exact edge, not the frame's latest pointer or the original press. Tokens
23/// retain their existing runtime lifetime; storing an event does not extend it.
24#[derive(Debug, Clone, Copy, PartialEq, Eq)]
25#[non_exhaustive]
26pub enum PointerButtonEvent<T> {
27    /// A known in-viewport press captured an eligible target.
28    Pressed {
29        /// Target chosen by the caller at the press position.
30        target: T,
31        /// The press's immutable event-time pointer sample.
32        pointer: PointerSample,
33        /// The press occurrence's runtime-issued token.
34        intent: TransitionIntentToken,
35    },
36    /// A normal release over that same eligible target confirmed a click.
37    Clicked {
38        /// Original captured target, equal to the release's eligible hit.
39        target: T,
40        /// The release's immutable event-time pointer sample.
41        pointer: PointerSample,
42        /// The release occurrence's runtime-issued token.
43        intent: TransitionIntentToken,
44    },
45    /// A captured hold ended without confirmation.
46    Cancelled {
47        /// Original captured target; it must not receive a click.
48        target: T,
49        /// Why confirmation was rejected.
50        reason: PointerButtonCancellation,
51        /// The release or cancellation occurrence's runtime-issued token.
52        intent: TransitionIntentToken,
53    },
54}
55
56/// Local routing advice and optional interaction change for one input edge.
57///
58/// A claimed edge can have no event, for example when an invalidated target's
59/// pending release is suppressed. No input snapshot is changed by this result.
60#[derive(Debug, Clone, Copy, PartialEq, Eq)]
61#[must_use = "route claimed input separately from application/gameplay actions"]
62pub struct PointerButtonOutcome<T> {
63    pub(super) claimed: bool,
64    pub(super) event: Option<PointerButtonEvent<T>>,
65}
66
67impl<T: Copy> PointerButtonOutcome<T> {
68    /// Whether this controller owns the edge for local routing purposes.
69    ///
70    /// Do not forward claimed edges to a competing gesture handler. This is
71    /// advice to the caller, not exclusive access, global input consumption,
72    /// or cancellation of Systems that already ran.
73    pub const fn claimed(self) -> bool {
74        self.claimed
75    }
76
77    /// Returns the press, confirmed click, or cancellation emitted by this edge.
78    /// No event is emitted for unrelated controls or a suppressed interaction.
79    pub const fn event(self) -> Option<PointerButtonEvent<T>> {
80        self.event
81    }
82}