cranpose_foundation/nodes/input/
types.rs

1use std::{
2    cell::{Cell, RefCell},
3    rc::Rc,
4};
5
6use cranpose_ui_graphics::Point;
7
8use super::rotary::RotaryScrollEvent;
9
10pub type PointerId = u64;
11
12type PostDispatchAction = Box<dyn FnOnce() -> bool>;
13
14#[derive(Clone)]
15struct DeferredPostDispatch {
16    action: Rc<RefCell<Option<PostDispatchAction>>>,
17}
18
19impl std::fmt::Debug for DeferredPostDispatch {
20    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
21        formatter
22            .debug_struct("DeferredPostDispatch")
23            .field("is_pending", &self.action.borrow().is_some())
24            .finish()
25    }
26}
27
28#[derive(Clone, Copy, Debug, PartialEq, Eq)]
29pub enum PointerPhase {
30    Start,
31    Move,
32    End,
33    Cancel,
34}
35
36#[derive(Clone, Copy, Debug, PartialEq, Eq)]
37pub enum PointerEventKind {
38    Down,
39    Move,
40    Up,
41    Cancel,
42    Scroll,
43    /// Discrete zoom step (desktop ctrl+wheel, browser pinch-trackpad).
44    /// The multiplicative factor is carried in [`PointerEvent::zoom_delta`].
45    Zoom,
46    /// Rotary scroll (Wear OS crown / rotating bezel) during the **capture**
47    /// pass, which runs root-to-focused so ancestors can intercept the event
48    /// before the focused node sees it.
49    ///
50    /// The scroll amounts are carried in [`PointerEvent::scroll_delta`] (`y` =
51    /// vertical pixels, `x` = horizontal pixels) and the rotary uptime in
52    /// [`PointerEvent::time_ms`]; use
53    /// [`PointerEvent::rotary_scroll_event`] to read them back as a
54    /// [`RotaryScrollEvent`]. Mirrors Compose's `onPreRotaryScrollEvent`.
55    RotaryScrollPre,
56    /// Rotary scroll during the **bubble** pass, which runs focused-to-root.
57    /// Mirrors Compose's `onRotaryScrollEvent`.
58    RotaryScroll,
59    Enter,
60    Exit,
61}
62
63impl PointerEventKind {
64    /// Returns true for the two rotary passes.
65    pub fn is_rotary(self) -> bool {
66        matches!(self, Self::RotaryScrollPre | Self::RotaryScroll)
67    }
68}
69
70/// The kind of physical device that produced a pointer event.
71///
72/// Threaded from the platform layer (Android `MotionEvent` tool type, winit
73/// `PointerSource`/`ButtonSource`, web `PointerEvent.pointerType`) so input
74/// consumers can preserve device-specific gesture details while keeping shared
75/// direct-manipulation behavior source-independent.
76#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
77pub enum PointerSource {
78    /// A mouse or other indirect precise pointer (desktop, web `"mouse"`).
79    Mouse,
80    /// A finger on a touchscreen (Android finger, winit touch, web `"touch"`).
81    Touch,
82    /// A stylus/pen (Android stylus/eraser, winit tablet tool, web `"pen"`).
83    Stylus,
84    /// The platform did not report a device type.
85    #[default]
86    Unknown,
87}
88
89impl PointerSource {
90    /// Whether this source is a direct-touch device (finger or stylus), used
91    /// for contact-specific release and velocity semantics.
92    pub fn is_touch_like(self) -> bool {
93        matches!(self, PointerSource::Touch | PointerSource::Stylus)
94    }
95}
96
97#[repr(u8)]
98#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
99pub enum PointerButton {
100    Primary = 0,
101    Secondary = 1,
102    Middle = 2,
103    Back = 3,
104    Forward = 4,
105}
106
107#[derive(Clone, Copy, Debug, PartialEq, Eq)]
108pub struct PointerButtons(u8);
109
110impl PointerButtons {
111    pub const NONE: Self = Self(0);
112
113    pub fn new() -> Self {
114        Self::NONE
115    }
116
117    pub fn with(mut self, button: PointerButton) -> Self {
118        self.insert(button);
119        self
120    }
121
122    pub fn insert(&mut self, button: PointerButton) {
123        self.0 |= 1 << (button as u8);
124    }
125
126    pub fn remove(&mut self, button: PointerButton) {
127        self.0 &= !(1 << (button as u8));
128    }
129
130    pub fn contains(&self, button: PointerButton) -> bool {
131        (self.0 & (1 << (button as u8))) != 0
132    }
133}
134
135impl Default for PointerButtons {
136    fn default() -> Self {
137        Self::NONE
138    }
139}
140
141/// Keyboard modifier keys held during an input sample.
142///
143/// Lives here (rather than up in `cranpose-ui`, where the keyboard `KeyEvent`
144/// type lives) because [`PointerEvent`] needs it too and `cranpose-foundation`
145/// sits below `cranpose-ui` in the dependency graph — this is the one crate
146/// both a key event and a pointer event can share it from. `cranpose-ui`
147/// re-exports this type rather than defining its own, so there is exactly one
148/// `Modifiers` in the framework.
149#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
150pub struct Modifiers {
151    /// Shift key is pressed.
152    pub shift: bool,
153    /// Control key is pressed (Cmd on macOS).
154    pub ctrl: bool,
155    /// Alt key is pressed (Option on macOS).
156    pub alt: bool,
157    /// Meta/Super key is pressed (Windows key, Cmd on macOS).
158    pub meta: bool,
159}
160
161impl Modifiers {
162    /// No modifiers pressed.
163    pub const NONE: Modifiers = Modifiers {
164        shift: false,
165        ctrl: false,
166        alt: false,
167        meta: false,
168    };
169
170    /// Returns true if any modifier is pressed.
171    pub fn any(&self) -> bool {
172        self.shift || self.ctrl || self.alt || self.meta
173    }
174
175    /// Returns true if Ctrl (or Cmd on macOS) is pressed.
176    pub fn command_or_ctrl(&self) -> bool {
177        #[cfg(target_os = "macos")]
178        {
179            self.meta
180        }
181        #[cfg(not(target_os = "macos"))]
182        {
183            self.ctrl
184        }
185    }
186}
187
188/// Pointer event with consumption tracking for gesture disambiguation.
189///
190/// Events can be consumed by handlers (e.g., scroll) to prevent other handlers
191/// (e.g., clicks) from receiving them. This enables proper gesture disambiguation
192/// matching Jetpack Compose's event consumption pattern.
193#[derive(Clone, Debug)]
194pub struct PointerEvent {
195    pub id: PointerId,
196    pub kind: PointerEventKind,
197    pub phase: PointerPhase,
198    pub position: Point,
199    pub global_position: Point,
200    /// Scroll delta in logical pixels.
201    ///
202    /// This is non-zero for [`PointerEventKind::Scroll`] events and zero for
203    /// button/move events.
204    pub scroll_delta: Point,
205    pub buttons: PointerButtons,
206    /// Platform timestamp of the input sample in milliseconds, when available.
207    ///
208    /// The time base is platform specific (e.g. Android's uptime clock); only
209    /// differences between events of the same gesture are meaningful. Gesture
210    /// velocity trackers must prefer this over the delivery time because
211    /// platforms like Android deliver input batched/frame-aligned: several
212    /// samples arrive back-to-back and delivery-time stamping makes computed
213    /// velocities wildly wrong.
214    pub time_ms: Option<i64>,
215    /// Timestamp in the animation frame-clock domain at input dispatch.
216    /// Unlike `time_ms`, this has the same origin as frame callbacks and can
217    /// anchor input-driven animations without a wall/platform clock conversion.
218    pub animation_time_nanos: Option<u64>,
219    /// Multiplicative zoom factor for [`PointerEventKind::Zoom`] events
220    /// (`> 1.0` zooms in, `< 1.0` zooms out). `1.0` for all other events.
221    pub zoom_delta: f32,
222    /// The kind of device that produced this event (touch, mouse, stylus), when
223    /// the platform reports it. Defaults to [`PointerSource::Unknown`].
224    pub source: PointerSource,
225    /// Keyboard modifiers held at the time of this sample, when the platform
226    /// can report them.
227    ///
228    /// `None` means the platform never told the shell what the keyboard state
229    /// was — touch-only Android/iOS input has no channel for it today — and is
230    /// deliberately distinct from `Some(Modifiers::NONE)`, which means the
231    /// platform looked and nothing was held. An app that wants shift/ctrl-click
232    /// multi-select reads this field directly; it must not treat `None` as
233    /// "nothing held" or it silently drops the gesture on the platforms that
234    /// cannot yet report it instead of visibly doing nothing.
235    pub modifiers: Option<Modifiers>,
236    consumed: Rc<Cell<bool>>,
237    deferred_post_dispatch: DeferredPostDispatch,
238}
239
240impl PointerEvent {
241    pub fn new(kind: PointerEventKind, position: Point, global_position: Point) -> Self {
242        Self {
243            id: 0,
244            kind,
245            phase: match kind {
246                PointerEventKind::Down => PointerPhase::Start,
247                PointerEventKind::Move | PointerEventKind::Enter | PointerEventKind::Exit => {
248                    PointerPhase::Move
249                }
250                PointerEventKind::Up => PointerPhase::End,
251                PointerEventKind::Cancel => PointerPhase::Cancel,
252                PointerEventKind::Scroll
253                | PointerEventKind::Zoom
254                | PointerEventKind::RotaryScrollPre
255                | PointerEventKind::RotaryScroll => PointerPhase::Move,
256            },
257            position,
258            global_position,
259            scroll_delta: Point { x: 0.0, y: 0.0 },
260            buttons: PointerButtons::NONE,
261            time_ms: None,
262            animation_time_nanos: None,
263            zoom_delta: 1.0,
264            source: PointerSource::Unknown,
265            modifiers: None,
266            consumed: Rc::new(Cell::new(false)),
267            deferred_post_dispatch: DeferredPostDispatch {
268                action: Rc::new(RefCell::new(None)),
269            },
270        }
271    }
272
273    /// Set the pointer id for this event (`0` is the primary pointer).
274    pub fn with_id(mut self, id: PointerId) -> Self {
275        self.id = id;
276        self
277    }
278
279    /// Set the multiplicative zoom factor for a [`PointerEventKind::Zoom`] event.
280    pub fn with_zoom_delta(mut self, zoom_delta: f32) -> Self {
281        self.zoom_delta = zoom_delta;
282        self
283    }
284
285    /// Set the scroll delta for this event.
286    pub fn with_scroll_delta(mut self, scroll_delta: Point) -> Self {
287        self.scroll_delta = scroll_delta;
288        self
289    }
290
291    /// Set the platform timestamp (milliseconds) for this event.
292    pub fn with_time_ms(mut self, time_ms: Option<i64>) -> Self {
293        self.time_ms = time_ms;
294        self
295    }
296
297    /// Set the timestamp in the animation frame-clock domain.
298    pub fn with_animation_time_nanos(mut self, time_nanos: u64) -> Self {
299        self.animation_time_nanos = Some(time_nanos);
300        self
301    }
302
303    /// Set the buttons state for this event
304    pub fn with_buttons(mut self, buttons: PointerButtons) -> Self {
305        self.buttons = buttons;
306        self
307    }
308
309    /// Set the device source (touch/mouse/stylus) for this event.
310    pub fn with_source(mut self, source: PointerSource) -> Self {
311        self.source = source;
312        self
313    }
314
315    /// Set the keyboard modifiers held during this event, when the platform
316    /// can report them. See the [`modifiers`](Self::modifiers) field docs for
317    /// why this takes a concrete [`Modifiers`] rather than an `Option`: the
318    /// `None` case is the *absence* of a call to this builder, not a value it
319    /// produces.
320    pub fn with_modifiers(mut self, modifiers: Modifiers) -> Self {
321        self.modifiers = Some(modifiers);
322        self
323    }
324
325    /// Builds a rotary pointer event for one dispatch pass.
326    ///
327    /// `kind` must be [`PointerEventKind::RotaryScrollPre`] (capture) or
328    /// [`PointerEventKind::RotaryScroll`] (bubble). The rotary payload rides on
329    /// the existing `scroll_delta`/`time_ms` fields so rotary reuses the
330    /// pointer dispatch path without widening [`PointerEvent`].
331    pub fn rotary(kind: PointerEventKind, rotary: RotaryScrollEvent, position: Point) -> Self {
332        debug_assert!(
333            kind.is_rotary(),
334            "PointerEvent::rotary requires a rotary event kind"
335        );
336        Self::new(kind, position, position)
337            .with_scroll_delta(Point {
338                x: rotary.horizontal_scroll_pixels,
339                y: rotary.vertical_scroll_pixels,
340            })
341            .with_time_ms(Some(rotary.uptime_millis as i64))
342    }
343
344    /// Reads this event back as a [`RotaryScrollEvent`], or `None` when it is
345    /// not a rotary event.
346    ///
347    /// Copies three scalars out of the event; it never allocates.
348    pub fn rotary_scroll_event(&self) -> Option<RotaryScrollEvent> {
349        if !self.kind.is_rotary() {
350            return None;
351        }
352        Some(RotaryScrollEvent {
353            vertical_scroll_pixels: self.scroll_delta.y,
354            horizontal_scroll_pixels: self.scroll_delta.x,
355            uptime_millis: self.time_ms.unwrap_or(0).max(0) as u64,
356        })
357    }
358
359    /// Mark this event as consumed, preventing other handlers from processing it.
360    ///
361    /// Example: Scroll gestures consume events once dragging starts to prevent
362    /// child buttons from firing clicks.
363    pub fn consume(&self) {
364        self.consumed.set(true);
365    }
366
367    /// Check if this event has been consumed by another handler.
368    ///
369    /// Handlers should check this before processing events. For example,
370    /// clickable should not fire if the event was consumed by a scroll gesture.
371    pub fn is_consumed(&self) -> bool {
372        self.consumed.get()
373    }
374
375    pub fn defer_post_dispatch_action<F>(&self, action: F)
376    where
377        F: FnOnce() -> bool + 'static,
378    {
379        *self.deferred_post_dispatch.action.borrow_mut() = Some(Box::new(action));
380    }
381
382    pub fn finish_post_dispatch(&self) {
383        if self.is_consumed() {
384            self.deferred_post_dispatch.action.borrow_mut().take();
385            return;
386        }
387
388        let Some(action) = self.deferred_post_dispatch.action.borrow_mut().take() else {
389            return;
390        };
391        if action() {
392            self.consume();
393        }
394    }
395
396    /// Creates a copy of this event with a new local position, sharing the consumption state.
397    pub fn copy_with_local_position(&self, position: Point) -> Self {
398        Self {
399            id: self.id,
400            kind: self.kind,
401            phase: self.phase,
402            position,
403            global_position: self.global_position,
404            scroll_delta: self.scroll_delta,
405            buttons: self.buttons,
406            time_ms: self.time_ms,
407            animation_time_nanos: self.animation_time_nanos,
408            zoom_delta: self.zoom_delta,
409            source: self.source,
410            modifiers: self.modifiers,
411            consumed: self.consumed.clone(),
412            deferred_post_dispatch: self.deferred_post_dispatch.clone(),
413        }
414    }
415}
416
417#[cfg(test)]
418mod tests {
419    use super::*;
420
421    fn point(x: f32, y: f32) -> Point {
422        Point { x, y }
423    }
424
425    #[test]
426    fn pointer_event_clones_share_consumed_state() {
427        let event = PointerEvent::new(PointerEventKind::Move, point(1.0, 2.0), point(3.0, 4.0));
428        let cloned = event.clone();
429        assert!(!event.is_consumed());
430        assert!(!cloned.is_consumed());
431
432        cloned.consume();
433
434        assert!(event.is_consumed());
435        assert!(cloned.is_consumed());
436    }
437
438    #[test]
439    fn pointer_event_source_defaults_unknown_and_threads_through_copy() {
440        let event = PointerEvent::new(PointerEventKind::Down, point(1.0, 1.0), point(1.0, 1.0));
441        assert_eq!(event.source, PointerSource::Unknown);
442        assert!(!PointerSource::Unknown.is_touch_like());
443
444        let touch = event.with_source(PointerSource::Touch);
445        assert_eq!(touch.source, PointerSource::Touch);
446        assert!(PointerSource::Touch.is_touch_like());
447        assert!(PointerSource::Stylus.is_touch_like());
448        assert!(!PointerSource::Mouse.is_touch_like());
449
450        let local = touch.copy_with_local_position(point(5.0, 5.0));
451        assert_eq!(local.source, PointerSource::Touch);
452    }
453
454    #[test]
455    fn modifiers_any_is_true_when_any_field_is_set() {
456        assert!(!Modifiers::NONE.any());
457        assert!(!Modifiers::default().any());
458        assert!(
459            Modifiers {
460                shift: true,
461                ..Modifiers::NONE
462            }
463            .any()
464        );
465    }
466
467    #[test]
468    fn modifiers_command_or_ctrl_reads_the_platform_appropriate_key() {
469        let ctrl_only = Modifiers {
470            ctrl: true,
471            ..Modifiers::NONE
472        };
473        let meta_only = Modifiers {
474            meta: true,
475            ..Modifiers::NONE
476        };
477
478        #[cfg(target_os = "macos")]
479        {
480            assert!(!ctrl_only.command_or_ctrl());
481            assert!(meta_only.command_or_ctrl());
482        }
483        #[cfg(not(target_os = "macos"))]
484        {
485            assert!(ctrl_only.command_or_ctrl());
486            assert!(!meta_only.command_or_ctrl());
487        }
488        assert!(!Modifiers::NONE.command_or_ctrl());
489    }
490
491    #[test]
492    fn pointer_event_modifiers_default_to_unreported_and_thread_through_copy() {
493        let event = PointerEvent::new(PointerEventKind::Down, point(1.0, 1.0), point(1.0, 1.0));
494        assert_eq!(event.modifiers, None);
495
496        let shift = event.with_modifiers(Modifiers {
497            shift: true,
498            ..Modifiers::NONE
499        });
500        assert_eq!(
501            shift.modifiers,
502            Some(Modifiers {
503                shift: true,
504                ..Modifiers::NONE
505            })
506        );
507
508        let local = shift.copy_with_local_position(point(5.0, 5.0));
509        assert_eq!(local.modifiers, shift.modifiers);
510    }
511
512    #[test]
513    fn rotary_payload_round_trips_through_pointer_event() {
514        let rotary = RotaryScrollEvent::new(-64.0, 12.0, 1_234);
515        let event = PointerEvent::rotary(PointerEventKind::RotaryScroll, rotary, point(5.0, 6.0));
516
517        assert_eq!(event.phase, PointerPhase::Move);
518        assert_eq!(event.scroll_delta, point(12.0, -64.0));
519        assert_eq!(event.time_ms, Some(1_234));
520        assert_eq!(event.rotary_scroll_event(), Some(rotary));
521    }
522
523    #[test]
524    fn rotary_payload_survives_local_position_copies() {
525        let rotary = RotaryScrollEvent::new(-8.0, 0.0, 7);
526        let event =
527            PointerEvent::rotary(PointerEventKind::RotaryScrollPre, rotary, point(0.0, 0.0));
528
529        let local = event.copy_with_local_position(point(3.0, 4.0));
530
531        assert_eq!(local.rotary_scroll_event(), Some(rotary));
532    }
533
534    #[test]
535    fn non_rotary_events_have_no_rotary_payload() {
536        let scroll = PointerEvent::new(PointerEventKind::Scroll, point(0.0, 0.0), point(0.0, 0.0))
537            .with_scroll_delta(point(1.0, 2.0));
538
539        assert_eq!(scroll.rotary_scroll_event(), None);
540        assert!(!PointerEventKind::Scroll.is_rotary());
541        assert!(PointerEventKind::RotaryScroll.is_rotary());
542        assert!(PointerEventKind::RotaryScrollPre.is_rotary());
543    }
544
545    #[test]
546    fn pointer_event_copy_with_local_position_preserves_consumption_state() {
547        let event = PointerEvent::new(PointerEventKind::Down, point(4.0, 5.0), point(4.0, 5.0))
548            .with_time_ms(Some(123))
549            .with_animation_time_nanos(456_000_000);
550        let local = event.copy_with_local_position(point(1.0, 1.0));
551
552        assert_eq!(local.position, point(1.0, 1.0));
553        assert_eq!(local.global_position, event.global_position);
554        assert_eq!(local.time_ms, Some(123));
555        assert_eq!(local.animation_time_nanos, Some(456_000_000));
556        assert!(!local.is_consumed());
557
558        event.consume();
559
560        assert!(local.is_consumed());
561    }
562
563    #[test]
564    fn deferred_post_dispatch_action_consumes_when_it_applies() {
565        let event = PointerEvent::new(PointerEventKind::Move, point(0.0, 0.0), point(0.0, 0.0));
566        event.defer_post_dispatch_action(|| true);
567
568        event.finish_post_dispatch();
569
570        assert!(event.is_consumed());
571    }
572
573    #[test]
574    fn deferred_post_dispatch_action_is_replaced_and_discarded_when_consumed() {
575        let event = PointerEvent::new(PointerEventKind::Move, point(0.0, 0.0), point(0.0, 0.0));
576        let first_called = Rc::new(Cell::new(false));
577        let second_called = Rc::new(Cell::new(false));
578        let first_called_in_action = first_called.clone();
579        let second_called_in_action = second_called.clone();
580        event.defer_post_dispatch_action(move || {
581            first_called_in_action.set(true);
582            true
583        });
584        event.defer_post_dispatch_action(move || {
585            second_called_in_action.set(true);
586            true
587        });
588        event.consume();
589
590        event.finish_post_dispatch();
591
592        assert!(!first_called.get());
593        assert!(!second_called.get());
594        assert!(event.is_consumed());
595    }
596}
cranpose_foundation/nodes/input/types.rs

cranpose_foundation/nodes/input/
types.rs
