kbd_evdev/lib.rs
1#![cfg_attr(docsrs, feature(doc_cfg))]
2
3//! Linux evdev backend for `kbd`.
4//!
5//! This crate provides the low-level Linux input layer that
6//! [`kbd-global`](https://docs.rs/kbd-global) builds on. It handles:
7//!
8//! - **Device discovery** — scan [`/dev/input/`](devices::INPUT_DIRECTORY) for
9//! keyboards (devices supporting A–Z + Enter)
10//! - **Hotplug** — inotify watch for device add/remove at runtime
11//! - **Exclusive grab** — [`EVIOCGRAB`](devices::DeviceGrabMode::Exclusive) for
12//! intercepting events before other applications see them
13//! - **Event forwarding** — [`UinputForwarder`](forwarder::UinputForwarder)
14//! re-emits unmatched events through a virtual device so they still reach
15//! applications in grab mode
16//! - **Key conversion** — extension traits ([`convert::EvdevKeyCodeExt`], [`convert::KbdKeyExt`])
17//! for converting between `evdev::KeyCode` and [`kbd::key::Key`]
18//!
19//! # Prerequisites
20//!
21//! - **Linux only** — this crate uses `/dev/input/`, `inotify`, and `/dev/uinput`.
22//! - **Read access to `/dev/input/`** — either run as root, or add your user to
23//! the `input` group:
24//!
25//! ```sh
26//! sudo usermod -aG input $USER
27//! # log out and back in for the group change to take effect
28//! ```
29//!
30//! - **Write access to `/dev/uinput`** (only for grab mode) — needed to create
31//! the virtual device that forwards unmatched events.
32//!
33//! # Architecture
34//!
35//! ```text
36//! /dev/input/event* --> DeviceManager --> DeviceKeyEvent
37//! |
38//! +-- hotplug detection via inotify
39//! |
40//! v
41//! EvdevKeyCodeExt::to_key()
42//! |
43//! v
44//! kbd::Key
45//! |
46//! +----------------+----------------+
47//! | | |
48//! v v v
49//! Dispatcher KeyState UinputForwarder
50//! (kbd core) (kbd core) (grab mode only)
51//! ```
52//!
53//! # Usage
54//!
55//! Most users should use [`kbd-global`](https://docs.rs/kbd-global) which wraps
56//! this crate in a threaded runtime. Use `kbd-evdev` directly when you need
57//! low-level control over the poll loop.
58//!
59//! # See also
60//!
61//! - [`kbd`](https://docs.rs/kbd) — core key types, matching, and layers
62//! - [`kbd-global`](https://docs.rs/kbd-global) — threaded runtime built on
63//! this crate
64
65pub mod convert;
66pub mod devices;
67pub mod error;
68pub mod forwarder;