device_query

device_query is a small cross-platform Rust library for querying mouse and keyboard state on demand, without needing an application window or event loop. It reports current mouse coordinates, pressed buttons, and held keys directly from the operating system.

It works on Windows, Linux (X11), and macOS through platform-specific backends, and also offers an event-based API with callbacks for key and mouse changes. This makes it a convenient choice for global hotkey polling, games, and background utilities that need raw input state.

What You Get

• On-demand queries for current mouse coordinates and button state
• On-demand queries for currently pressed keyboard keys
• Cross-platform backends for Windows, Linux X11, and macOS
• An event-based API with callbacks for key and mouse changes
• A simple DeviceQuery trait exposing get_mouse and get_keys

Common Use Cases

• Polling global keyboard and mouse state in games or tools
• Building background utilities that react to input without a window
• Implementing custom hotkey detection by checking held keys
• Logging or visualizing raw input for debugging or automation

Under The Hood

Architecture - The crate exposes a DeviceState struct implementing the DeviceQuery trait (device_query.rs, lib.rs), which delegates to per-OS backends under src/device_state (linux, macos, windows) selected via cfg attributes. A separate src/device_events module layers an event loop (event_loop.rs) and callback registry on top of polling, and keymap.rs plus mouse_state.rs define the portable Keycode and MouseState types.

Tech Stack - Rust with a build.rs that uses pkg-config to locate native libraries. Platform dependencies are gated by target_os: x11 on Linux, the windows crate on Windows, and readkey/readmouse/macos-accessibility-client on macOS. It has no runtime dependencies on the common platform, keeping the core lightweight.

Code Quality - The codebase is small and focused, with the platform-specific complexity isolated per OS backend. It ships runnable examples for both polling and event-based usage (print_keys.rs, event_based_print_keys.rs), though it has no dedicated unit test suite and recent development activity is low. The repository has since relocated to Codeberg.

API Design - The API is minimal and immediately usable: create a DeviceState, then call get_mouse() and get_keys(). This on-demand model avoids the boilerplate of setting up a window or event loop, and the optional callback API accommodates event-driven code. The main caveats are documented platform quirks, such as extra permissions and key limitations on recent macOS.