Struct KeyboardListener 

pub struct KeyboardListener { /* private fields */ }

Platform-agnostic Keyboard Listener

Streams all keyboard events. Can optionally block events that match registered hotkeys.

Implementations

impl KeyboardListener

pub fn new() -> Result<Self>

Create a new KeyboardListener (non-blocking mode)

Events are observed but not blocked. Use this for “record hotkey” UI flows.

On macOS, this will check for accessibility permissions and fail if not granted.

Examples found in repository

examples/record_hotkey.rs (line 16)

fn main() -> Result<()> {
    println!("Recording keyboard events...");
    println!("Press keys to see events. Press Escape to exit.");
    println!();

    let listener = KeyboardListener::new()?;

    loop {
        // Non-blocking check for events
        if let Some(event) = listener.try_recv() {
            let state = if event.is_key_down { "DOWN" } else { "UP" };

            // Build a display string for the current combination
            let combo = if event.modifiers.is_empty() {
                match event.key {
                    Some(key) => format!("{}", key),
                    None => "(no key)".to_string(),
                }
            } else {
                match event.key {
                    Some(key) => format!("{}+{}", event.modifiers, key),
                    None => format!("{}", event.modifiers),
                }
            };

            println!("[{}] {}", state, combo);

            // Check for Escape to exit
            if event.key == Some(handy_keys::Key::Escape) && event.is_key_down {
                println!("\nEscape pressed, exiting...");
                break;
            }
        }

        // Small sleep to avoid busy-waiting
        std::thread::sleep(Duration::from_millis(10));
    }

    Ok(())
}

pub fn new_with_blocking(blocking_hotkeys: BlockingHotkeys) -> Result<Self>

Create a new KeyboardListener with blocking support

Events matching hotkeys in the provided set will be blocked from reaching other applications. The set can be modified after creation to add/remove hotkeys dynamically.

Note: On Wayland, blocking may not work due to compositor restrictions.

pub fn blocking_hotkeys(&self) -> Option<&BlockingHotkeys>

Get a reference to the blocking hotkeys set (if blocking is enabled)

pub fn recv(&self) -> Result<KeyEvent>

Blocking receive for key events

Blocks until a key event is received or the listener stops.

pub fn recv_timeout(&self, timeout: Duration) -> Result<KeyEvent>

Blocking receive with timeout

Blocks until a key event is received, the timeout expires, or the listener stops.

pub fn try_recv(&self) -> Option<KeyEvent>

Non-blocking receive for key events

Returns Some(event) if an event is available, None otherwise.

Examples found in repository

examples/record_hotkey.rs (line 20)

fn main() -> Result<()> {
    println!("Recording keyboard events...");
    println!("Press keys to see events. Press Escape to exit.");
    println!();

    let listener = KeyboardListener::new()?;

    loop {
        // Non-blocking check for events
        if let Some(event) = listener.try_recv() {
            let state = if event.is_key_down { "DOWN" } else { "UP" };

            // Build a display string for the current combination
            let combo = if event.modifiers.is_empty() {
                match event.key {
                    Some(key) => format!("{}", key),
                    None => "(no key)".to_string(),
                }
            } else {
                match event.key {
                    Some(key) => format!("{}+{}", event.modifiers, key),
                    None => format!("{}", event.modifiers),
                }
            };

            println!("[{}] {}", state, combo);

            // Check for Escape to exit
            if event.key == Some(handy_keys::Key::Escape) && event.is_key_down {
                println!("\nEscape pressed, exiting...");
                break;
            }
        }

        // Small sleep to avoid busy-waiting
        std::thread::sleep(Duration::from_millis(10));
    }

    Ok(())
}

Trait Implementations

impl Drop for KeyboardListener

fn drop(&mut self)

Executes the destructor for this type.