raw_input/platform/
mod.rs

1#[cfg(feature = "serialize")]
2use serde::{Deserialize, Serialize};
3
4// #[cfg(target_os = "linux")]
5// mod linux;
6// #[cfg(target_os = "macos")]
7// mod mac;
8#[cfg(target_os = "windows")]
9mod windows;
10
11/// Errors that occur when trying to capture OS events.
12///
13/// # Note on macOS
14/// On macOS, failing to set Accessibility permissions does not necessarily
15/// trigger an error; the system may simply ignore events or return empty data.
16#[derive(Debug)]
17#[non_exhaustive]
18pub enum CoreError {
19    /// macOS: Failed to create an event tap.
20    MacEventTapError,
21    /// macOS: Failed to add the event tap to the run loop.
22    MacLoopSourceError,
23    /// Linux: Could not open the X11 display.
24    LinuxMissingDisplayError,
25    /// Linux: Keyboard-related error in the X11 or Wayland backend.
26    LinuxKeyboardError,
27    /// Linux: Failed to enable the XRecord context.
28    LinuxRecordContextEnablingError,
29    /// Linux: General XRecord context error.
30    LinuxRecordContextError,
31    /// Linux: The XRecord extension is missing or incompatible.
32    LinuxXRecordExtensionError,
33    /// Windows: Failed to set a low-level keyboard hook.
34    WindowsKeyHookError(String),
35    /// Windows: Failed to set a low-level mouse hook.
36    WindowsMouseHookError(String),
37    /// Windows: Failed to register for Raw Input devices.
38    WindowsRegisterRawInputError(String),
39}
40
41/// The system background engine manager.
42///
43/// `Core` handles the lifecycle of the platform's native event loop.
44///
45/// # Example
46/// ```no_run
47/// use raw_input::Core;
48///
49/// // Initialize and start the background event loop
50/// std::thread::spawn(|| {
51///     Core::start().expect("Failed to start raw-input core");
52/// });
53/// ```
54pub struct Core;
55
56/// Global input listener for monitoring events.
57///
58/// This provides a way to observe keyboard and mouse actions without blocking them.
59///
60/// # Example
61/// ```no_run
62/// use raw_input::{Listen, Event};
63///
64/// // It must be started first
65/// // Core::start(); // This is a blocking operation
66/// 
67/// // Start listening to all input
68/// Listen::start();  // defaults to listening to all input
69/// 
70/// // customizable
71/// // Listen::mouse_move(true);
72/// // Listen::mouse_wheel(true);
73/// // Listen::mouse_button(true);
74/// // Listen::keyboard(true);
75///
76/// // Subscribe to all global input events
77/// let handle = Listen::subscribe(|event| {
78///     match event {
79///         Event::KeyDown { key } => println!("Key pressed: {:?}", key),
80///         Event::MouseMove { delta } => println!("Mouse delta: {:?}", delta),
81///         _ => {},
82///     }
83/// });
84///
85/// // Use handle.pause(), handle.resume(), or handle.unsubscribe() to manage the lifecycle.
86///
87/// Listen::stop();
88/// ```
89pub struct Listen;
90
91/// Input interceptor for blocking or modifying events.
92///
93/// `Grab` allows you to prevent specific events from reaching other applications.
94///
95/// # Example
96/// ```no_run
97/// use raw_input::Grab;
98/// 
99/// // It must be started first
100/// // Core::start(); // This is a blocking operation
101///
102/// // Block all keyboard input
103/// Grab::start();  // defaults to blocking all input
104/// 
105/// // customizable
106/// // Grab::mouse_move(true);
107/// // Grab::mouse_wheel(true);
108/// // Grab::mouse_button(true);
109/// // Grab::keyboard(true);
110///
111/// // Stop grabbing later
112/// // Grab::stop();
113/// ```
114pub struct Grab;
115
116/// Input simulator for synthesizing events.
117///
118/// Use `Simulate` to programmatically trigger keyboard and mouse actions.
119///
120/// # Example
121/// ```no_run
122/// use raw_input::{Simulate, Event, Key};
123///
124/// // Simulate pressing the 'A' key
125/// Simulate::simulate(Event::KeyDown { key: Key::KeyA });
126///
127/// // Convenience methods for mouse
128/// Simulate::mouse_move(100, 100);
129/// ```
130pub struct Simulate;
131
132/// Screen and monitor information provider.
133///
134/// # Example
135/// ```no_run
136/// use raw_input::Display;
137///
138/// let monitors = Display::get_available_monitors();
139/// for monitor in monitors {
140///     println!("Monitor: {} - Size: {:?}", monitor.name, monitor.size);
141/// }
142///
143/// let scale = Display::get_scale_factor();
144/// println!("Current UI Scale: {}", scale);
145/// ```
146pub struct Display;
147
148/// Information about a connected physical monitor.
149#[derive(Debug, Clone, PartialEq)]
150#[cfg_attr(feature = "serialize", derive(Serialize, Deserialize))]
151pub struct MonitorInfo {
152    /// The OS-assigned name or identifier of the monitor.
153    pub name: String,
154    /// Indicates whether this is the primary monitor of the system.
155    pub is_primary: bool,
156    /// The starting coordinates (x, y) of the monitor in the global physical coordinate system.
157    pub offset: (i32, i32),
158    /// The physical resolution (width, height) of the monitor in pixels.
159    pub size: (i32, i32),
160    /// The UI scale factor (e.g., 1.0, 1.5, 2.0) for High-DPI support.
161    pub scale_factor: f64,
162}
163
164impl MonitorInfo {
165    /// Returns the width of the monitor.
166    pub fn width(&self) -> i32 {
167        self.size.0
168    }
169
170    /// Returns the height of the monitor.
171    pub fn height(&self) -> i32 {
172        self.size.1
173    }
174}
raw_input/platform/mod.rs

raw_input/platform/
mod.rs
