Skip to main content

sim_logic/application/input/
capture.rs

1//! Explicit application-owned pointer capture intent and backend acknowledgement.
2
3/// Last known outcome of a desktop pointer-capture operation.
4#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
5#[non_exhaustive]
6pub enum PointerCaptureStatus {
7    /// No capture has been established; the desktop cursor is visible.
8    #[default]
9    Released,
10    /// The backend locked the cursor and hides it while focused.
11    Locked,
12    /// Lock was unavailable; confinement succeeded and the cursor is hidden.
13    Confined,
14    /// The last backend request failed. Cursor visibility is restored and raw
15    /// motion is disabled; after release failure physical grab state is unknown.
16    Unavailable,
17}
18
19/// Optional application-owned pointer capture service, independent of winit.
20///
21/// Register once with `Application::register_app_resource(Self::default())`.
22/// Frame systems use `AppResMut<PointerCapture>` to request lock on an explicit
23/// user gesture and release it for menus. Desktop applies requests after the
24/// logical frame; requesting capture does not promise backend support.
25/// Focus loss clears the request immediately. Focus regain never reissues it.
26///
27/// Requests are immediate application-resource mutations, not transactional
28/// Commands. A headless runner preserves intent but performs no OS operation;
29/// deterministic tests may inject relative motion independently of OS status.
30#[derive(Debug, Default)]
31pub struct PointerCapture {
32    requested: bool,
33    pending: bool,
34    status: PointerCaptureStatus,
35}
36
37impl PointerCapture {
38    /// Requests capture or explicitly retries an unavailable backend. Call on a
39    /// fresh click/key gesture, not unconditionally every update. An already
40    /// acknowledged capture needs no repeated backend operation.
41    pub fn request_lock(&mut self) {
42        if self.requested && self.is_captured() {
43            return;
44        }
45        self.requested = true;
46        self.pending = true;
47    }
48    /// Requests cursor release and visibility, normally when opening a menu.
49    /// Repeating an acknowledged release performs no new backend operation.
50    pub fn release(&mut self) {
51        if !self.requested && self.status == PointerCaptureStatus::Released {
52            return;
53        }
54        self.requested = false;
55        self.pending = true;
56    }
57    /// Returns current application intent, not actual OS capture availability.
58    pub const fn requested(&self) -> bool {
59        self.requested
60    }
61    /// Returns the latest acknowledged backend state.
62    pub const fn status(&self) -> PointerCaptureStatus {
63        self.status
64    }
65    /// Reports successful locked/confined capture, not merely a request.
66    pub const fn is_captured(&self) -> bool {
67        matches!(
68            self.status,
69            PointerCaptureStatus::Locked | PointerCaptureStatus::Confined
70        )
71    }
72    #[cfg(feature = "desktop")]
73    pub(crate) const fn pending(&self) -> bool {
74        self.pending
75    }
76    #[cfg(feature = "desktop")]
77    pub(crate) fn acknowledge(&mut self, status: PointerCaptureStatus) {
78        self.status = status;
79        self.pending = false;
80    }
81}