rdev Rust Library

Use the simulate function to inject global input events into the system.

Note on Timing: On some operating systems (like macOS), it is recommended to add a small delay (e.g., 20ms) between simulated events to allow the OS to catch up.

Limitations: Not all keys are mapped to an OS code; simulate may return a SimulateError if you attempt to send an unmapped key.

use rdev::{simulate, Button, EventType, Key, SimulateError};
use std::{thread, time};

fn send(event_type: &EventType) {
    let delay = time::Duration::from_millis(20);
    match simulate(event_type) {
        Ok(()) => (),
        Err(SimulateError) => {
            println!("We could not send {:?}", event_type);
        }
    }
    // Let the OS catch up
    thread::sleep(delay);
}

send(&EventType::KeyPress(Key::KeyS));
send(&EventType::KeyRelease(Key::KeyS));

send(&EventType::MouseMove { x: 0.0, y: 0.0 });
send(&EventType::MouseMove { x: 400.0, y: 400.0 });
send(&EventType::ButtonPress(Button::Left));
send(&EventType::ButtonRelease(Button::Right));
send(&EventType::Wheel {
    delta_x: 0,
    delta_y: 1,
});

Use the listen function to start a blocking loop that executes a callback whenever a global input event occurs. The callback receives an Event struct.

Important OS Caveats:

• macOS: The process must be the parent process (no forking before calling listen). You must grant the application (e.g., Terminal.app) access to the Accessibility API in System Preferences > Security & Privacy > Privacy > Accessibility. If access is not granted, listen will fail silently without triggering callbacks.
• Linux: listen uses X11 APIs and will not work in Wayland or the Linux kernel virtual console.

use rdev::{listen, Event};

// This will block.
if let Err(error) = listen(callback) {
    println!("Error: {:?}", error)
}

fn callback(event: Event) {
    println!("My callback {:?}", event);
    match event.name {
        Some(string) => println!("User wrote {:?}", string),
        None => (),
    }
}

By enabling the unstable_grab feature, you can use the grab function to intercept events before they reach other applications or the window manager.

How it works: Provide a callback that returns Option<Event>:

• Return None to consume/cancel the event (it will not reach other apps).
• Return Some(event) to let the event pass through normally.

OS Caveats:

• macOS: Requires Accessibility API access. If access is denied, grab will fail with an EventTapError.
• Linux: Uses evdev and works with both X11 and Wayland. The process must run as root or as a user in the input group (or plugdev group on some distributions).

Warning: The grab API is marked unstable and is subject to change.

#[cfg(feature = "unstable_grab")]
use rdev::{grab, Event, EventType, Key};

#[cfg(feature = "unstable_grab")]
let callback = |event: Event| -> Option<Event> {
    if let EventType::KeyPress(Key::CapsLock) = event.event_type {
        println!("Consuming and cancelling CapsLock");
        None  // CapsLock is now effectively disabled
    }
    else { Some(event) }
};

// This will block.
#[cfg(feature = "unstable_grab")]
if let Err(error) = grab(callback) {
    println!("Error: {:?}", error)
}

The Event struct is the primary data container for all input received from the OS. It includes a time (SystemTime), an optional name (the character produced based on the OS layout), and an event_type.

EventType categorizes the input into one of the following:

• KeyPress(Key) / KeyRelease(Key): Keyboard interactions using the Key enum.
• ButtonPress(Button) / ButtonRelease(Button): Mouse button interactions.
• MouseMove { x: f64, y: f64 }: Mouse movement in pixels (top-left is 0,0).
• Wheel { delta_x: i64, delta_y: i64 }: Scroll wheel movement (positive is up/right, negative is down/left).

Note on Keys: Key values represent physical locations. For character-based input, use Event.name instead of mapping Key to characters manually, as Key is layout-agnostic and does not account for modifiers or layout logic.

// Example of the structure of an Event
let event = Event {
    time: SystemTime::now(),
    name: Some("a".to_string()),
    event_type: EventType::KeyPress(Key::KeyA),
};

The simulate function allows you to programmatically trigger input events.

Best Practice: On macOS, it is recommended to add a small delay (e.g., 20ms) between simulated events to allow the OS to catch up.

use rdev::{simulate, Button, EventType, Key, SimulateError};
use std::{thread, time};

fn send(event_type: &EventType) {
    let delay = time::Duration::from_millis(20);
    match simulate(event_type) {
        Ok(()) => (),
        Err(SimulateError) => {
            println!("We could not send {:?}", event_type);
        }
    }
    // Let the OS catchup (at least MacOS)
    thread::sleep(delay);
}

fn main() {
    send(&EventType::KeyPress(Key::KeyS));
    send(&EventType::KeyRelease(Key::KeyS));

    send(&EventType::MouseMove { x: 0.0, y: 0.0 });
    send(&EventType::MouseMove { x: 400.0, y: 400.0 });
    send(&EventType::ButtonPress(Button::Left));
    send(&EventType::ButtonRelease(Button::Right));
    send(&EventType::Wheel {
        delta_x: 0,
        delta_y: 1,
    });
}