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}