hotkey_listener/lib.rs
1//! Cross-platform global hotkey listener with native Wayland support.
2//!
3//! This crate provides a simple API for listening to global hotkeys on Linux and macOS.
4//! Unlike other crates, it uses evdev directly on Linux, making it compatible with
5//! both X11 and Wayland.
6//!
7//! # Features
8//!
9//! - **Native Wayland support on Linux** - Uses evdev directly (reads `/dev/input`)
10//! - **Automatic keyboard reconnection** - Handles USB keyboard disconnect/reconnect
11//! - **Modifier key support** - Parse and detect `Shift+F8` style hotkey combinations
12//! - **Simple push-to-talk API** - Clean pressed/released event model
13//! - **Automatic cleanup** - Background thread stops when handle is dropped
14//! - **Cross-platform** - Linux (evdev) + macOS (rdev) with unified API
15//!
16//! # Example
17//!
18//! ```no_run
19//! use hotkey_listener::{parse_hotkey, HotkeyListenerBuilder, HotkeyEvent};
20//! use std::time::Duration;
21//!
22//! fn main() -> anyhow::Result<()> {
23//! let hotkey = parse_hotkey("Shift+F8")?;
24//!
25//! // Build and start the listener - no manual shutdown flag needed
26//! let handle = HotkeyListenerBuilder::new()
27//! .add_hotkey(hotkey)
28//! .build()?
29//! .start()?;
30//!
31//! // Receive hotkey events
32//! loop {
33//! match handle.recv_timeout(Duration::from_millis(100)) {
34//! Ok(HotkeyEvent::Pressed(idx)) => println!("Hotkey {} pressed", idx),
35//! Ok(HotkeyEvent::Released(idx)) => println!("Hotkey {} released", idx),
36//! Err(_) => { /* timeout, check exit conditions */ }
37//! }
38//! }
39//!
40//! // Background thread stops automatically when `handle` is dropped
41//! }
42//! ```
43//!
44//! # Linux Requirements
45//!
46//! On Linux, the user must have permission to read from `/dev/input/event*` devices.
47//! This typically means running as root or being a member of the `input` group.
48
49mod event;
50mod hotkey;
51mod key;
52mod listener;
53
54#[cfg(target_os = "linux")]
55mod linux;
56
57#[cfg(target_os = "macos")]
58mod macos;
59
60pub use event::HotkeyEvent;
61pub use hotkey::{parse_hotkey, Hotkey, Modifiers};
62pub use key::Key;
63pub use listener::{HotkeyListener, HotkeyListenerBuilder, HotkeyListenerHandle};
64
65#[cfg(target_os = "linux")]
66pub use linux::find_keyboards;