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}