Monio

https://docs.rs/monio/0.1.0/
Admin
Monio is a pure Rust cross-platform input monitoring library that detects keyboard and mouse events...
Tokens:167,492
Snippets:1,140
Trust Score:9.7
Update:8 months ago
Show doc for...
Tokens:
Raw
### Example Usage of grab_channel - Rust

Source: https://docs.rs/monio/0.1.0/monio/channel/fn.grab_channel_search=

Provides an example of how to use the `grab_channel` function to set up an event hook. This example demonstrates creating a hook that consumes 'F1' key presses while allowing all other events to pass through. It then iterates over the received events and prints their types.

```rust
use monio::channel::grab_channel;
use monio::{EventType, Key};

// Block F1 key, pass everything else through
let (handle, rx) = grab_channel(100, |event| {
    if event.event_type == EventType::KeyPressed {
        if let Some(kb) = &event.keyboard {
            if kb.key == Key::F1 {
                return false; // Consume F1
            }
        }
    }
    true // Pass through
}).expect("Failed to start hook");

for event in rx.iter() {
    println!("{:?}", event.event_type);
}

```

--------------------------------

### Convenience Functions

Source: https://docs.rs/monio/0.1.0/src/monio/hook.rs_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Provides simplified functions for starting event listening and grabbing.

```APIDOC
## Functions

### `listen<F>(callback: F) -> Result<()>`

#### Description
Convenience function to start listening for events in a blocking manner. This is a simpler alternative to creating a `Hook` instance.

#### Method
`listen`

#### Parameters
- `callback` (F): A closure that takes a reference to an `Event` and performs actions. Must be `Send + Sync + 'static`.

#### Response
- `Result<()>`: Ok if the listener started successfully, Err otherwise.

#### Example
```rust
use monio::{listen, Event, EventType};

listen(|event: &Event| {
    match event.event_type {
        EventType::MouseDragged => {
            if let Some(mouse) = &event.mouse {
                println!("Dragging at ({}, {})", mouse.x, mouse.y);
            }
        }
        EventType::KeyPressed => {
            if let Some(kb) = &event.keyboard {
                println!("Key pressed: {:?}", kb.key);
            }
        }
        _ => {}
    }
}).expect("Failed to start hook");
```

### `grab<F>(callback: F) -> Result<()>`

#### Description
Convenience function to start grabbing events with the ability to consume them. Returning `None` from the callback consumes the event; returning `Some(event)` passes it through. This function blocks until the hook is stopped.

#### Platform Support
- **macOS**: Full support via CGEventTap
- **Windows**: Full support via low-level hooks
- **Linux/X11**: Falls back to listen mode (XRecord cannot grab)

#### Method
`grab`

#### Parameters
- `callback` (F): A closure that takes a reference to an `Event`, and returns `Option<Event>`. Returning `None` consumes the event. Must be `Send + Sync + 'static`.

#### Response
- `Result<()>`: Ok if the grabber started successfully, Err otherwise.

#### Example
```rust
use monio::{grab, Event, EventType, Key};

grab(|event: &Event| {
    // Block the Escape key
    if event.event_type == EventType::KeyPressed {
        if let Some(kb) = &event.keyboard {
            if kb.key == Key::Escape {
                println!("Blocked Escape key!");
                return None;
            }
        }
    }
    Some(event.clone())
}).expect("Failed to start grab");
```
```

--------------------------------

### Get System Settings (X11)

Source: https://docs.rs/monio/0.1.0/src/monio/platform/linux/x11/display.rs_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Retrieves mouse control settings (sensitivity, acceleration, threshold) from the X11 server. It uses `XGetPointerControl` to get these values. Other system settings like keyboard repeat rate or double-click time are not implemented and returned as `None`. Returns a `Result<SystemSettings>`.

```rust
pub fn system_settings() -> Result<SystemSettings> {
    let (mouse_sensitivity, mouse_acceleration, mouse_acceleration_threshold) =
        with_display(|display| unsafe {
            let mut accel_numerator: i32 = 0;
            let mut accel_denominator: i32 = 0;
            let mut threshold: i32 = 0;
            xlib::XGetPointerControl(
                display,
                &mut accel_numerator,
                &mut accel_denominator,
                &mut threshold,
            );

            Ok((
                Some(accel_numerator as f64),
                Some(accel_denominator as f64),
                Some(threshold as f64),
            ))
        })?;

    Ok(SystemSettings {
        keyboard_repeat_rate: None,
        keyboard_repeat_delay: None,
        mouse_sensitivity,
        mouse_acceleration,
        mouse_acceleration_threshold,
        double_click_time: None,
        keyboard_layout: None,
    })
}
```

--------------------------------

### Example Usage of `grab` function (Rust)

Source: https://docs.rs/monio/0.1.0/src/monio/hook.rs

Illustrates the use of the `grab` function to intercept and potentially block system events. This example shows how to prevent the 'Escape' key press from propagating by returning `None` from the callback.

```rust
use monio::{grab, Event, EventType, Key};
 grab(|event: &Event| {
    // Block the Escape key
    if event.event_type == EventType::KeyPressed {
        if let Some(kb) = &event.keyboard {
            if kb.key == Key::Escape {
                println!("Blocked Escape key!");
                return None;
            }
        }
    }
    Some(event.clone())
}).expect("Failed to start grab");
```

--------------------------------

### Listening for Events

Source: https://docs.rs/monio/0.1.0/monio/hook/index_search=

Documentation for the 'listen' function, a convenience function to start listening for input events in a non-consuming manner.

```APIDOC
## Functions

listen
    Convenience function to start listening for events.

```

--------------------------------

### Get X11 Displays and System Settings - Rust

Source: https://docs.rs/monio/0.1.0/src/monio/platform/linux/x11/display.rs_search=std%3A%3Avec

This Rust code retrieves information about connected displays and system settings using the X11 library. It defines functions to get all displays, the primary display, the display at a given point, and mouse control parameters. It depends on the `x11` crate and standard Rust libraries.

```Rust
use crate::display::{DisplayInfo, Rect, SystemSettings};
use crate::error::{Error, Result};
use std::ptr::null;
use x11::xlib;

pub fn displays() -> Result<Vec<DisplayInfo>> {
    with_display(|display| unsafe {
        let screen = xlib::XDefaultScreen(display);
        let width = xlib::XDisplayWidth(display, screen) as f64;
        let height = xlib::XDisplayHeight(display, screen) as f64;

        Ok(vec![DisplayInfo {
            id: 1,
            bounds: Rect {
                x: 0.0,
                y: 0.0,
                width,
                height,
            },
            scale_factor: 1.0,
            refresh_rate: None,
            is_primary: true,
        }])
    })
}

pub fn primary_display() -> Result<DisplayInfo> {
    displays()? 
        .into_iter()
        .next()
        .ok_or_else(|| Error::Platform("X11 display information unavailable".into()))
}

pub fn display_at_point(x: f64, y: f64) -> Result<Option<DisplayInfo>> {
    let displays = displays()?;
    Ok(displays
        .into_iter()
        .find(|display| display.bounds.contains(x, y)))
}

pub fn system_settings() -> Result<SystemSettings> {
    let (mouse_sensitivity, mouse_acceleration, mouse_acceleration_threshold) =
        with_display(|display| unsafe {
            let mut accel_numerator: i32 = 0;
            let mut accel_denominator: i32 = 0;
            let mut threshold: i32 = 0;
            xlib::XGetPointerControl(
                display,
                &mut accel_numerator,
                &mut accel_denominator,
                &mut threshold,
            );

            Ok((
                Some(accel_numerator as f64),
                Some(accel_denominator as f64),
                Some(threshold as f64),
            ))
        })?;

    Ok(SystemSettings {
        keyboard_repeat_rate: None,
        keyboard_repeat_delay: None,
        mouse_sensitivity,
        mouse_acceleration,
        mouse_acceleration_threshold,
        double_click_time: None,
        keyboard_layout: None,
    })
}

fn with_display<T>(f: impl FnOnce(*mut xlib::Display) -> Result<T>) -> Result<T> {
    unsafe {
        let display = xlib::XOpenDisplay(null());
        if display.is_null() {
            return Err(Error::Platform("XOpenDisplay failed".into()));
        }
        let result = f(display);
        xlib::XCloseDisplay(display);
        result
    }
}

```

--------------------------------

### Start a channel hook to listen for events in Rust

Source: https://docs.rs/monio/0.1.0/monio/channel/fn.listen_channel_search=u32+-%3E+bool

Starts a hook that sends events to a bounded channel. Returns a handle to control the hook and a receiver for events. The hook runs in a background thread. The capacity argument determines the maximum number of events to buffer; if the buffer is full, new events are dropped.

```Rust
pub fn listen_channel(
    capacity: usize,
) -> Result<(ChannelHookHandle, Receiver<Event>)>

```

```Rust
use monio::channel::listen_channel;

let (handle, rx) = listen_channel(100).expect("Failed to start hook");

for event in rx.iter() {
    println!("{:?}", event.event_type);
}

```

--------------------------------

### Create and Run Hook (Blocking Listen)

Source: https://docs.rs/monio/0.1.0/monio/hook/struct.Hook_search=u32+-%3E+bool

Demonstrates creating a new `Hook` instance and starting it in a blocking, listen-only mode. This method will block the current thread until `stop()` is called from another thread. Events are passed through to other applications.

```rust
let hook = Hook::new();
hook.run(handler)?; // handler must implement EventHandler
```

--------------------------------

### grab_channel

Source: https://docs.rs/monio/0.1.0/monio/channel/index_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Starts a grab hook that sends events to a channel with a sync filter.

```APIDOC
## grab_channel

### Description
Starts a grab hook that sends events to a channel with a sync filter.

### Method
(Not applicable, this is a Rust function)

### Endpoint
(Not applicable, this is a Rust function)

### Parameters
#### Path Parameters
(None)

#### Query Parameters
(None)

#### Request Body
(None)

### Request Example
(No specific example provided in the documentation)

### Response
#### Success Response (200)
(Not applicable, this is a Rust function)

#### Response Example
(No specific example provided in the documentation)
```

--------------------------------

### listen_channel (Sync)

Source: https://docs.rs/monio/0.1.0/monio/channel/index_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Starts a hook that sends events to a bounded channel, allowing for synchronous event processing.

```APIDOC
## listen_channel (Sync)

### Description
Starts a hook that sends events to a bounded channel.

### Method
(Not applicable, this is a Rust function)

### Endpoint
(Not applicable, this is a Rust function)

### Parameters
#### Path Parameters
(None)

#### Query Parameters
(None)

#### Request Body
(None)

### Request Example
```rust
use monio::channel::listen_channel;
use std::time::Duration;

let (handle, rx) = listen_channel(100).expect("Failed to start hook");

// Process events in a loop
loop {
    match rx.recv_timeout(Duration::from_millis(100)) {
        Ok(event) => println!("{:?}", event.event_type),
        Err(_) => {
            // Timeout - do other work or check exit condition
        }
    }
}

// Stop when done
handle.stop().unwrap();
```

### Response
#### Success Response (200)
(Not applicable, this is a Rust function)

#### Response Example
(See Request Example for usage context)
```

--------------------------------

### Simulate Mouse Click in Rust

Source: https://docs.rs/monio/0.1.0/src/monio/lib.rs_search=std%3A%3Avec

Provides an example of simulating a mouse click event using `monio::mouse_click`. This function can be used to programmatically trigger mouse clicks at a specified position.

```rust
use monio::mouse_click;

mouse_click(monio::Button::Left, 100, 200);

```

--------------------------------

### Get System Settings (Rust)

Source: https://docs.rs/monio/0.1.0/monio/display/fn.system_settings_search=

Retrieves system input settings using a best-effort approach, which may vary per platform. This function returns a Result type, indicating potential success or failure during the query.

```Rust
pub fn system_settings() -> Result<SystemSettings>
```

--------------------------------

### grab_async_channel

Source: https://docs.rs/monio/0.1.0/src/monio/channel.rs_search=

Starts an asynchronous grab hook that sends events to a tokio async channel. Allows filtering of events.

```APIDOC
## grab_async_channel

### Description
Starts an asynchronous grab hook that sends events to a tokio async channel. Allows filtering of events. The filter function determines whether an event should be passed through or consumed.

### Method
`pub fn grab_async_channel<F>(capacity: usize, filter: F) -> Result<(ChannelHookHandle, tokio_mpsc::Receiver<Event>)> where F: Fn(&Event) -> bool + Send + Sync + 'static`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
use monio::channel::grab_async_channel;
use monio::{EventType, Key};

#[tokio::main]
async fn main() {
    let (handle, mut rx) = grab_async_channel(100, |event| {
        // Block F1 key
        if event.event_type == EventType::KeyPressed {
            if let Some(kb) = &event.keyboard {
                if kb.key == Key::F1 {
                    return false;
                }
            }
        }
        true
    }).expect("Failed to start hook");

    while let Some(event) = rx.recv().await {
        println!("{:?}", event.event_type);
    }
}
```

### Response
#### Success Response (200)
Returns a tuple containing a `ChannelHookHandle` and a `tokio_mpsc::Receiver<Event>`.

#### Response Example
```json
{
  "handle": "ChannelHookHandle",
  "receiver": "tokio_mpsc::Receiver<Event>"
}
```
```

--------------------------------

### listen_async_channel (Async with Tokio)

Source: https://docs.rs/monio/0.1.0/monio/channel/index_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Starts a hook that sends events to a channel, designed for asynchronous event processing with frameworks like Tokio.

```APIDOC
## listen_async_channel (Async with Tokio)

### Description
Starts a hook that sends events to a channel, suitable for asynchronous event processing.

### Method
(Not applicable, this is a Rust function)

### Endpoint
(Not applicable, this is a Rust function)

### Parameters
#### Path Parameters
(None)

#### Query Parameters
(None)

#### Request Body
(None)

### Request Example
```rust
use monio::channel::listen_async_channel;

#[tokio::main]
async fn main() {
    let (handle, mut rx) = listen_async_channel(100).expect("Failed to start hook");

    while let Some(event) = rx.recv().await {
        println!("{:?}", event.event_type);
    }
}
```

### Response
#### Success Response (200)
(Not applicable, this is a Rust function)

#### Response Example
(See Request Example for usage context)
```

--------------------------------

### listen

Source: https://docs.rs/monio/0.1.0/monio/hook/fn.listen

Starts listening for events and executes a callback function for each event. This function blocks until the hook is stopped or an error occurs.

```APIDOC
## listen

### Description
Convenience function to start listening for events. This is a simpler alternative to creating a Hook instance. Blocks until the hook is stopped externally or an error occurs.

### Method
`listen` (function)

### Parameters
#### Callback Function
- **callback** (`F: Fn(&Event) + Send + Sync + 'static`) - Required - A function that takes a reference to an `Event` and is executed for each received event. It must be `Send`, `Sync`, and have a `'static` lifetime.

### Request Example
```rust
use monio::{listen, Event, EventType};

listen(|event: &Event| {
    match event.event_type {
        EventType::MouseDragged => {
            if let Some(mouse) = &event.mouse {
                println!("Dragging at ({}, {})", mouse.x, mouse.y);
            }
        }
        EventType::KeyPressed => {
            if let Some(kb) = &event.keyboard {
                println!("Key pressed: {:?}", kb.key);
            }
        }
        _ => {}
    }
}).expect("Failed to start hook");
```

### Response
#### Success Response
- **Result** (`Result<()>`): Returns `Ok(())` on successful execution or if the hook is stopped. Returns an `Err` if an error occurs during event listening.

#### Response Example
(No specific response body, returns `Ok(())` or an `Err`)
```

--------------------------------

### monio::channel::listen_channel

Source: https://docs.rs/monio/0.1.0/monio/channel/fn.listen_channel_search=u32+-%3E+bool

Starts a hook that sends events to a bounded channel. The hook runs in a background thread.

```APIDOC
## listen_channel

### Description
Starts a hook that sends events to a bounded channel. Returns a handle to control the hook and a receiver for events. The hook runs in a background thread.

### Method
`fn`

### Endpoint
`monio::channel::listen_channel`

### Parameters
#### Arguments
- **capacity** (usize) - Required - Maximum number of events to buffer. If the buffer is full, new events are dropped to prevent blocking input.

### Request Example
```rust
use monio::channel::listen_channel;

let (handle, rx) = listen_channel(100).expect("Failed to start hook");

for event in rx.iter() {
    println!("{:?}", event.event_type);
}
```

### Response
#### Success Response
- **ChannelHookHandle** - A handle to control the hook.
- **Receiver<Event>** - A receiver for events.

#### Response Example
```rust
// Example return type structure (actual types may vary)
// let (handle, rx) = (ChannelHookHandle, Receiver<Event>);
```
```

--------------------------------

### listen_async_channel

Source: https://docs.rs/monio/0.1.0/src/monio/channel.rs_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Starts an asynchronous channel listener that buffers a specified number of events. It returns a handle to control the listener and a receiver for the events.

```APIDOC
## POST /listen_async_channel

### Description
Starts an asynchronous channel listener that buffers a specified number of events. It returns a handle to control the listener and a receiver for the events.

### Method
POST

### Endpoint
/listen_async_channel

### Parameters
#### Query Parameters
- **capacity** (usize) - Required - Maximum number of events to buffer

### Request Body
None

### Response
#### Success Response (200)
- **ChannelHookHandle** - Handle to control the listener.
- **tokio_mpsc::Receiver<Event>** - Receiver for the buffered events.

#### Response Example
{
  "handle": "ChannelHookHandle",
  "receiver": "tokio_mpsc::Receiver<Event>"
}
```

--------------------------------

### monio::hook::grab

Source: https://docs.rs/monio/0.1.0/monio/hook/fn.grab_search=std%3A%3Avec

Starts grabbing events with a provided callback function. The callback can consume events by returning `None` or pass them through by returning `Some(event)`.

```APIDOC
## POST /grab

### Description
Convenience function to start grabbing events with the ability to consume them. Return `None` from the callback to consume the event (prevent it from reaching other apps). Return `Some(event)` to pass the event through.

### Method
POST

### Endpoint
/grab

### Parameters
#### Query Parameters
- **callback** (Fn(&Event) -> Option<Event>) - Required - A closure that takes an `Event` and returns an `Option<Event>`. If `None` is returned, the event is consumed. If `Some(event)` is returned, the event is passed through.

### Request Body
This endpoint does not have a request body.

### Response
#### Success Response (200)
- **Result** (Result<()>) - Indicates success or failure of starting the grab operation.

#### Response Example
```json
{
  "success": true
}
```

### Platform Support
- **macOS**: Full support via CGEventTap
- **Windows**: Full support via low-level hooks
- **Linux/X11**: Falls back to listen mode (XRecord cannot grab)

### Example
```rust
use monio::{grab, Event, EventType, Key};
 grab(|event: &Event| {
    // Block the Escape key
    if event.event_type == EventType::KeyPressed {
        if let Some(kb) = &event.keyboard {
            if kb.key == Key::Escape {
                println!("Blocked Escape key!");
                return None;
            }
        }
    }
    Some(event.clone())
}).expect("Failed to start grab");
```
```

--------------------------------

### Start listening for events (blocking)

Source: https://docs.rs/monio/0.1.0/monio/hook/struct.Hook

Initiates a blocking listen-only mode for the Hook, capturing keyboard and mouse events. The current thread is blocked until stop() is called. Events are passed through to other applications.

```rust
pub fn run<H: EventHandler + 'static>(&self, handler: H) -> Result<()>
```

--------------------------------

### Get All Displays (X11)

Source: https://docs.rs/monio/0.1.0/src/monio/platform/linux/x11/display.rs_search=u32+-%3E+bool

Retrieves a list of all connected displays using the X11 library. It queries the default screen's dimensions and returns a vector of DisplayInfo structs. Dependencies include the 'x11' crate. Returns an Error if XOpenDisplay fails.

```rust
1//! X11 display and system property queries.
2
3use crate::display::{DisplayInfo, Rect, SystemSettings};
4use crate::error::{Error, Result};
5use std::ptr::null;
6use x11::xlib;
7
8pub fn displays() -> Result<Vec<DisplayInfo>> {
9    with_display(|display| unsafe {
10        let screen = xlib::XDefaultScreen(display);
11        let width = xlib::XDisplayWidth(display, screen) as f64;
12        let height = xlib::XDisplayHeight(display, screen) as f64;
13
14        Ok(vec![DisplayInfo {
15            id: 1,
16            bounds: Rect {
17                x: 0.0,
18                y: 0.0,
19                width,
20                height,
21            },
22            scale_factor: 1.0,
23            refresh_rate: None,
24            is_primary: true,
25        }])
26    })
27}
28
29pub fn primary_display() -> Result<DisplayInfo> {
30    displays()? 
31        .into_iter()
32        .next()
33        .ok_or_else(|| Error::Platform("X11 display information unavailable".into()))
34}
35
36pub fn display_at_point(x: f64, y: f64) -> Result<Option<DisplayInfo>> {
37    let displays = displays()?;
38    Ok(displays
39        .into_iter()
40        .find(|display| display.bounds.contains(x, y)))
41}
42
43pub fn system_settings() -> Result<SystemSettings> {
44    let (mouse_sensitivity, mouse_acceleration, mouse_acceleration_threshold) =
45        with_display(|display| unsafe {
46            let mut accel_numerator: i32 = 0;
47            let mut accel_denominator: i32 = 0;
48            let mut threshold: i32 = 0;
49            xlib::XGetPointerControl(
50                display,
51                &mut accel_numerator,
52                &mut accel_denominator,
53                &mut threshold,
54            );
55
56            Ok((
57                Some(accel_numerator as f64),
58                Some(accel_denominator as f64),
59                Some(threshold as f64),
60            ))
61        })?;
62
63    Ok(SystemSettings {
64        keyboard_repeat_rate: None,
65        keyboard_repeat_delay: None,
66        mouse_sensitivity,
67        mouse_acceleration,
68        mouse_acceleration_threshold,
69        double_click_time: None,
70        keyboard_layout: None,
71    })
72}
73
74fn with_display<T>(f: impl FnOnce(*mut xlib::Display) -> Result<T>) -> Result<T> {
75    unsafe {
76        let display = xlib::XOpenDisplay(null());
77        if display.is_null() {
78            return Err(Error::Platform("XOpenDisplay failed".into()));
79        }
80        let result = f(display);
81        xlib::XCloseDisplay(display);
82        result
83    }
84}

```

--------------------------------

### Get Metadata of Root Path with `metadata` and `and_then` in Rust

Source: https://docs.rs/monio/0.1.0/monio/error/type.Result_search=u32+-%3E+bool

Illustrates using `Path::metadata` and `and_then` to retrieve file metadata, specifically the modification time of the root directory. This example handles potential errors during metadata retrieval, such as a non-existent path. It checks for success on the root path and failure on a bad path, verifying the error kind.

```rust
use std::{io::ErrorKind, path::Path};

// Note: on Windows "/" maps to "C:\"
let root_modified_time = Path::new("/").metadata().and_then(|md| md.modified());
assert!(root_modified_time.is_ok());

let should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified());
assert!(should_fail.is_err());
assert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound);
```

--------------------------------

### Linux Input Permissions Setup (Bash)

Source: https://docs.rs/monio/0.1.0/src/monio/platform/linux/mod.rs_search=std%3A%3Avec

This code snippet provides bash commands to set up the necessary permissions for the 'evdev' backend on Linux. It demonstrates how to add the current user to the 'input' group, which is required for accessing input devices directly. A logout and login are necessary for these group changes to take effect.

```bash
sudo usermod -aG input $USER
# Then log out and back in
```

--------------------------------

### Hook Start API

Source: https://docs.rs/monio/0.1.0/src/monio/hook.rs

Starts the event grabbing hook in a blocking manner. This function will block the current thread until the hook is stopped externally or an error occurs.

```APIDOC
## POST /hook/run

### Description
Starts the event grabbing hook in a blocking manner. This function will block the current thread until the hook is stopped externally or an error occurs.

### Method
POST

### Endpoint
/hook/run

### Parameters
#### Query Parameters
- **handler** (function) - Required - A callback function that will be executed for each captured event.

### Request Body
None

### Response
#### Success Response (200)
- **result** (Result<()>) - Indicates success or failure of starting the hook.

#### Response Example
```json
{
  "result": "Ok(())"
}
```
```

--------------------------------

### Linux Permissions Setup for evdev Backend

Source: https://docs.rs/monio/0.1.0/src/monio/platform/linux/mod.rs

Provides bash commands to set up the necessary permissions for the evdev backend on Linux. This involves adding the current user to the 'input' group and configuring udev rules for /dev/uinput access, which are required for grab mode functionality.

```bash
sudo usermod -aG input $USER
# Then log out and back in

```

```bash
sudo usermod -aG input $USER
echo 'KERNEL=="uinput", GROUP="input", MODE="0660"' | sudo tee /etc/udev/rules.d/99-uinput.rules
sudo udevadm control --reload-rules

```

--------------------------------

### Start listening for events (non-blocking)

Source: https://docs.rs/monio/0.1.0/monio/hook/struct.Hook

Starts the Hook in a background thread for non-blocking, listen-only event capture. This function returns immediately, and the hook can be terminated using stop(). Events are passed through to other applications.

```rust
pub fn run_async<H: EventHandler + 'static>(&self, handler: H) -> Result<()>
```

--------------------------------

### System Settings API

Source: https://docs.rs/monio/0.1.0/src/monio/display.rs_search=std%3A%3Avec

This section covers endpoints for querying system-wide input settings.

```APIDOC
## GET /system-settings

### Description
Queries the current system input settings, such as keyboard and mouse behavior.

### Method
GET

### Endpoint
/system-settings

### Parameters
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **settings** (SystemSettings) - An object containing system input settings.

  `SystemSettings` object structure:
  - **keyboard_repeat_rate** (Option<u32>) - Keyboard repeat rate (platform-specific units).
  - **keyboard_repeat_delay** (Option<u32>) - Keyboard repeat delay in milliseconds.
  - **mouse_sensitivity** (Option<f64>) - Mouse sensitivity/speed (platform-specific units).
  - **mouse_acceleration** (Option<f64>) - Mouse acceleration (platform-specific units).
  - **mouse_acceleration_threshold** (Option<f64>) - Mouse acceleration threshold (platform-specific units).
  - **double_click_time** (Option<u32>) - Double-click time in milliseconds.
  - **keyboard_layout** (Option<String>) - Current keyboard layout identifier (best-effort).

#### Response Example
```json
{
  "settings": {
    "keyboard_repeat_rate": 30,
    "keyboard_repeat_delay": 200,
    "mouse_sensitivity": 1.0,
    "mouse_acceleration": 0.0,
    "mouse_acceleration_threshold": 0.0,
    "double_click_time": 400,
    "keyboard_layout": "en-US"
  }
}
```
```

--------------------------------

### Example: Implement GrabHandler with a Closure in Rust

Source: https://docs.rs/monio/0.1.0/monio/hook/trait.GrabHandler_search=std%3A%3Avec

Demonstrates how to implement the GrabHandler trait using a closure. This example shows how to block the 'A' key press event by returning None, while allowing other events to pass through by returning Some(event.clone()).

```rust
use monio::{grab, Event, EventType, Key};
 grab(|event: &Event| {
    // Block the 'A' key
    if event.event_type == EventType::KeyPressed {
        if let Some(kb) = &event.keyboard {
            if kb.key == Key::KeyA {
                return None; // Consume the event
            }
        }
    }
    Some(event.clone()) // Pass through
}).expect("Failed to start grab");
```

--------------------------------

### List All Displays

Source: https://docs.rs/monio/0.1.0/monio/display/fn.displays

Retrieves a list of all available display information from the Monio system.

```APIDOC
## GET /displays

### Description
Retrieves a list of all available display information.

### Method
GET

### Endpoint
/displays

### Parameters
#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **displays** (Vec<DisplayInfo>) - A vector containing information about each available display.

#### Response Example
```json
{
  "displays": [
    {
      "id": "display-1",
      "name": "Primary Display",
      "resolution": {
        "width": 1920,
        "height": 1080
      },
      "refresh_rate": 60
    },
    {
      "id": "display-2",
      "name": "Secondary Display",
      "resolution": {
        "width": 1280,
        "height": 720
      },
      "refresh_rate": 30
    }
  ]
}
```
```

--------------------------------

### Start and Stop Event Hook (Rust)

Source: https://docs.rs/monio/0.1.0/src/monio/hook.rs_search=

Manages the lifecycle of an event hook, allowing it to be started, stopped, and checked for its running status. It supports both synchronous and asynchronous operation, with the asynchronous mode running the hook in a background thread.

```rust
pub fn grab_async<H: GrabHandler + 'static>(&self, handler: H) -> Result<()> {
        if self.running.swap(true, Ordering::SeqCst) {
            return Err(Error::AlreadyRunning);
        }

        // Reset state before starting
        crate::state::reset_mask();

        let running = self.running.clone();
        let handle = std::thread::spawn(move || {
            let _ = platform::run_grab_hook(&running, handler);
            running.store(false, Ordering::SeqCst);
        });

        *self.thread_handle.write().unwrap() = Some(handle);
        Ok(())
    }

    /// Stop the hook.
    pub fn stop(&self) -> Result<()> {
        if !self.running.swap(false, Ordering::SeqCst) {
            return Err(Error::NotRunning);
        }

        platform::stop_hook()?;

        // Wait for the thread to finish if running async
        if let Some(handle) = self.thread_handle.write().unwrap().take() {
            handle
                .join()
                .map_err(|_| Error::ThreadError("failed to join hook thread".into()))?;
        }

        Ok(())
    }

    /// Check if the hook is currently running.
    pub fn is_running(&self) -> bool {
        self.running.load(Ordering::SeqCst)
    }
}

impl Drop for Hook {
    fn drop(&mut self) {
        if self.is_running() {
            let _ = self.stop();
        }
    }
}
```

--------------------------------

### Start Event Listener Channel

Source: https://docs.rs/monio/0.1.0/monio/channel/fn.listen_channel

Starts a hook that sends events to a bounded channel. Returns a handle to control the hook and a receiver for events. The hook runs in a background thread. If the buffer is full, new events are dropped to prevent blocking input.

```rust
use monio::channel::listen_channel;

let (handle, rx) = listen_channel(100).expect("Failed to start hook");

for event in rx.iter() {
    println!("{:?}", event.event_type);
}
```

--------------------------------

### System Input Settings API

Source: https://docs.rs/monio/0.1.0/src/monio/display.rs_search=u32+-%3E+bool

Provides an endpoint for querying system-wide input settings such as keyboard repeat rate and mouse sensitivity.

```APIDOC
## GET /system-settings

### Description
Retrieves the current system input settings, including keyboard and mouse preferences.

### Method
GET

### Endpoint
/system-settings

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **settings** (SystemSettings) - An object containing system input settings.
  * **keyboard_repeat_rate** (u32 or null) - Keyboard repeat rate (platform-specific units).
  * **keyboard_repeat_delay** (u32 or null) - Keyboard repeat delay (milliseconds).
  * **mouse_sensitivity** (f64 or null) - Mouse sensitivity/speed (platform-specific units).
  * **mouse_acceleration** (f64 or null) - Mouse acceleration (platform-specific units).
  * **mouse_acceleration_threshold** (f64 or null) - Mouse acceleration threshold (platform-specific units).
  * **double_click_time** (u32 or null) - Double-click time in milliseconds.
  * **keyboard_layout** (string or null) - Current keyboard layout identifier (best-effort).

#### Response Example
```json
{
  "settings": {
    "keyboard_repeat_rate": 30,
    "keyboard_repeat_delay": 250,
    "mouse_sensitivity": 1.0,
    "mouse_acceleration": 0.0,
    "mouse_acceleration_threshold": 0.0,
    "double_click_time": 400,
    "keyboard_layout": "us"
  }
}
```
```

--------------------------------

### Query System Input Settings (Rust)

Source: https://docs.rs/monio/0.1.0/src/monio/display.rs

Provides the `system_settings` function, returning a `Result` with a `SystemSettings` struct. This function queries the operating system for current input device configurations, such as keyboard repeat behavior and mouse sensitivity. This is valuable for creating a consistent user experience across different systems.

```rust
/// Query system input settings (best-effort, per platform).
pub fn system_settings() -> Result<SystemSettings> {
    crate::platform::system_settings()
}
```

--------------------------------

### Rust Type Conversion Search Examples

Source: https://docs.rs/monio/0.1.0/monio/event/struct.Event_search=

Illustrates common search queries for type conversions in Rust. These examples show how to find information about converting standard library types like `std::vec`, primitive types such as `u32` to `bool`, and generic conversions involving `Option<T>`.

```rust
// Example search: std::vec
// Example search: u32 -> bool
// Example search: Option<T>, (T -> U) -> Option<U>
```

--------------------------------

### Start Event Grabbing Asynchronously (Rust)

Source: https://docs.rs/monio/0.1.0/src/monio/hook.rs

Starts event grabbing in a background thread, returning immediately. The `grab_async` method uses a `GrabHandler` to process events and allows for consuming events by returning `None`. It manages thread handles and ensures the hook is not already running.

```rust
pub fn grab_async<H: GrabHandler + 'static>(&self, handler: H) -> Result<()> {
        if self.running.swap(true, Ordering::SeqCst) {
            return Err(Error::AlreadyRunning);
        }

        // Reset state before starting
        crate::state::reset_mask();

        let running = self.running.clone();
        let handle = std::thread::spawn(move || {
            let _ = platform::run_grab_hook(&running, handler);
            running.store(false, Ordering::SeqCst);
        });

        *self.thread_handle.write().unwrap() = Some(handle);
        Ok(())
    }
```

--------------------------------

### displays

Source: https://docs.rs/monio/0.1.0/monio/display/fn.displays_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Retrieves a list of all available display information.

```APIDOC
## GET /displays

### Description
Lists all available displays on the system.

### Method
GET

### Endpoint
/displays

### Parameters
#### Query Parameters
None

### Request Example
```
GET /displays
```

### Response
#### Success Response (200)
- **displays** (array) - An array of DisplayInfo objects.
  - **id** (integer) - The unique identifier for the display.
  - **name** (string) - The name of the display.
  - **resolution** (object) - The resolution of the display.
    - **width** (integer) - The width of the display in pixels.
    - **height** (integer) - The height of the display in pixels.
  - **position** (object) - The position of the display on the virtual screen.
    - **x** (integer) - The x-coordinate of the top-left corner.
    - **y** (integer) - The y-coordinate of the top-left corner.

#### Response Example
```json
{
  "displays": [
    {
      "id": 0,
      "name": "Primary Display",
      "resolution": {
        "width": 1920,
        "height": 1080
      },
      "position": {
        "x": 0,
        "y": 0
      }
    },
    {
      "id": 1,
      "name": "Secondary Display",
      "resolution": {
        "width": 1280,
        "height": 720
      },
      "position": {
        "x": 1920,
        "y": 0
      }
    }
  ]
}
```
```

--------------------------------

### Define System Input Settings Structure (Rust)

Source: https://docs.rs/monio/0.1.0/src/monio/display.rs

Defines the `SystemSettings` struct to encapsulate various system input configurations. It includes settings for keyboard repeat rate and delay, mouse sensitivity and acceleration, and double-click time. This structure allows for querying and potentially adjusting user input behavior.

```rust
/// System input settings (platform-specific units where noted).
#[derive(Debug, Clone, PartialEq)]
pub struct SystemSettings {
    /// Keyboard repeat rate (platform-specific units).
    pub keyboard_repeat_rate: Option<u32>,
    /// Keyboard repeat delay (milliseconds when available).
    pub keyboard_repeat_delay: Option<u32>,
    /// Mouse sensitivity/speed (platform-specific units).
    pub mouse_sensitivity: Option<f64>,
    /// Mouse acceleration (platform-specific units).
    pub mouse_acceleration: Option<f64>,
    /// Mouse acceleration threshold (platform-specific units).
    pub mouse_acceleration_threshold: Option<f64>,
    /// Double-click time in milliseconds.
    pub double_click_time: Option<u32>,
    /// Current keyboard layout identifier (best-effort).
    pub keyboard_layout: Option<String>,
}
```

--------------------------------

### Start Unbounded Channel Hook for Events (Rust)

Source: https://docs.rs/monio/0.1.0/monio/channel/fn.listen_unbounded_channel_search=

Starts a hook that sends events to an unbounded channel. This function is useful when you need to guarantee that no events are dropped, but it's important to monitor memory usage if the event consumer is not keeping up. It returns a tuple containing a ChannelHookHandle and a Receiver for the events.

```rust
pub fn listen_unbounded_channel() -> Result<(ChannelHookHandle, Receiver<Event>)>
```

```rust
use monio::channel::listen_unbounded_channel;

let (handle, rx) = listen_unbounded_channel().expect("Failed to start hook");

for event in rx.iter() {
    println!("{:?}", event.event_type);
}
```

--------------------------------

### listen_unbounded_channel

Source: https://docs.rs/monio/0.1.0/monio/channel/index_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Starts a hook that sends events to an unbounded channel.

```APIDOC
## listen_unbounded_channel

### Description
Starts a hook that sends events to an unbounded channel.

### Method
(Not applicable, this is a Rust function)

### Endpoint
(Not applicable, this is a Rust function)

### Parameters
#### Path Parameters
(None)

#### Query Parameters
(None)

#### Request Body
(None)

### Request Example
(No specific example provided in the documentation)

### Response
#### Success Response (200)
(Not applicable, this is a Rust function)

#### Response Example
(No specific example provided in the documentation)
```

--------------------------------

### Create a new Hook instance

Source: https://docs.rs/monio/0.1.0/monio/hook/struct.Hook

Instantiates a new Hook object, which is used to capture input events. This is the entry point for setting up event listeners or grabbers.

```rust
pub fn new() -> Self
```

--------------------------------

### listen_unbounded_channel

Source: https://docs.rs/monio/0.1.0/monio/channel/index_search=

Starts a hook that sends events to an unbounded channel.

```APIDOC
## listen_unbounded_channel

### Description
Starts a hook that sends events to an unbounded channel.

### Method
(Not applicable - this is a Rust function call)

### Endpoint
(Not applicable - this is a Rust function call)

### Parameters
#### Path Parameters
(None)

#### Query Parameters
(None)

#### Request Body
(None)

### Request Example
(No specific example provided in the source text for `listen_unbounded_channel`)

### Response
#### Success Response
(Details not specified in the source text)

#### Response Example
(Details not specified in the source text)
```

--------------------------------

### List Displays

Source: https://docs.rs/monio/0.1.0/monio/display/fn.displays_search=std%3A%3Avec

Retrieves a list of all available display information.

```APIDOC
## GET /displays

### Description
Lists all available displays.

### Method
GET

### Endpoint
/displays

### Parameters
#### Query Parameters
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **displays** (array) - An array of DisplayInfo objects.
  - **id** (integer) - The unique identifier for the display.
  - **name** (string) - The name of the display.
  - **is_primary** (boolean) - Indicates if this is the primary display.
  - **resolution** (object) - The resolution of the display.
    - **width** (integer) - The width of the display in pixels.
    - **height** (integer) - The height of the display in pixels.
  - **position** (object) - The position of the display on the virtual screen.
    - **x** (integer) - The x-coordinate of the top-left corner.
    - **y** (integer) - The y-coordinate of the top-left corner.

#### Response Example
```json
{
  "displays": [
    {
      "id": 0,
      "name": "Display 1",
      "is_primary": true,
      "resolution": {
        "width": 1920,
        "height": 1080
      },
      "position": {
        "x": 0,
        "y": 0
      }
    },
    {
      "id": 1,
      "name": "Display 2",
      "is_primary": false,
      "resolution": {
        "width": 1280,
        "height": 720
      },
      "position": {
        "x": 1920,
        "y": 0
      }
    }
  ]
}
```
```

--------------------------------

### Simulate Key Press in Rust

Source: https://docs.rs/monio/0.1.0/src/monio/lib.rs_search=std%3A%3Avec

Shows how to simulate a key press event using the `monio::key_press` function. This is part of the event simulation capabilities provided by the library, allowing for automated testing or scripting of user interactions.

```rust
use monio::key_press;

key_press(monio::Key::A);

```

--------------------------------

### System Settings API

Source: https://docs.rs/monio/0.1.0/monio/display/fn.system_settings

Retrieves system input settings. This function provides a best-effort query for settings on a per-platform basis.

```APIDOC
## GET /system_settings

### Description
Query system input settings (best-effort, per platform).

### Method
GET

### Endpoint
/system_settings

### Parameters
#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **SystemSettings** (object) - An object containing system input settings.
  - **setting1** (string) - Description of setting 1
  - **setting2** (integer) - Description of setting 2

#### Response Example
```json
{
  "setting1": "example_value",
  "setting2": 123
}
```
```

--------------------------------

### listen_async_channel

Source: https://docs.rs/monio/0.1.0/src/monio/channel.rs_search=

Starts an asynchronous channel to listen for events. Events are buffered up to the specified capacity.

```APIDOC
## listen_async_channel

### Description
Starts an asynchronous channel to listen for events. Events are buffered up to the specified capacity.

### Method
`pub fn listen_async_channel(capacity: usize) -> Result<(ChannelHookHandle, tokio_mpsc::Receiver<Event>)>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
use monio::channel::listen_async_channel;

#[tokio::main]
async fn main() {
    let (handle, mut rx) = listen_async_channel(100).expect("Failed to start hook");

    while let Some(event) = rx.recv().await {
        println!("{:?}", event.event_type);
    }
}
```

### Response
#### Success Response (200)
Returns a tuple containing a `ChannelHookHandle` and a `tokio_mpsc::Receiver<Event>`.

#### Response Example
```json
{
  "handle": "ChannelHookHandle",
  "receiver": "tokio_mpsc::Receiver<Event>"
}
```
```

--------------------------------

### Get Mask Value

Source: https://docs.rs/monio/0.1.0/monio/state/fn.get_mask

Retrieves the current mask value from the Monio state.

```APIDOC
## GET /state/mask

### Description
Get the current mask value.

### Method
GET

### Endpoint
/state/mask

### Parameters
#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **mask** (u32) - The current mask value.

#### Response Example
```json
{
  "mask": 12345
}
```
```

--------------------------------

### Start Grab Hook with Synchronous Filter - Rust

Source: https://docs.rs/monio/0.1.0/monio/channel/fn.grab_channel_search=u32+-%3E+bool

Starts a grab hook that sends events to a channel with a synchronous filter. The filter function is called synchronously for each event and must decide immediately whether to pass the event through (true) or consume it (false). All events are sent to the channel. Requires the 'monio' crate.

```rust
pub fn grab_channel<F>(
    capacity: usize,
    filter: F,
) -> Result<(ChannelHookHandle, Receiver<Event>)>
where
    F: Fn(&Event) -> bool + Send + Sync + 'static,

```

```rust
use monio::channel::grab_channel;
use monio::{EventType, Key};

// Block F1 key, pass everything else through
let (handle, rx) = grab_channel(100, |event| {
    if event.event_type == EventType::KeyPressed {
        if let Some(kb) = &event.keyboard {
            if kb.key == Key::F1 {
                return false; // Consume F1
            }
        }
    }
    true // Pass through
}).expect("Failed to start hook");

for event in rx.iter() {
    println!("{:?}", event.event_type);
}

```
Tokens:
Raw