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 ([`EvdevKeyCodeExt`], [`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
37//! ├─ event0 ──┐ ┌─ discover + poll ──→ DeviceKeyEvent
38//! ├─ event1 ──┼──────→│ hotplug (inotify) │
39//! └─ event2 ──┘ └───────────────────────┘
40//! │
41//! EvdevKeyCodeExt::to_key()
42//! │
43//! ▼
44//! kbd::Key
45//! │
46//! ┌─────────────────┼─────────────────┐
47//! │ │ │
48//! Dispatcher KeyState UinputForwarder
49//! (kbd core) (kbd core) (grab mode only)
50//! ```
51//!
52//! # Usage
53//!
54//! Most users should use [`kbd-global`](https://docs.rs/kbd-global) which wraps
55//! this crate in a threaded runtime. Use `kbd-evdev` directly when you need
56//! low-level control over the poll loop.
57//!
58//! # See also
59//!
60//! - [`kbd`](https://docs.rs/kbd) — core key types, matching, and layers
61//! - [`kbd-global`](https://docs.rs/kbd-global) — threaded runtime built on
62//! this crate
63
64/// Extension traits for converting between `evdev::KeyCode` and [`kbd::key::Key`].
65pub mod convert;
66/// Device discovery, hotplug monitoring, and event polling.
67pub mod devices;
68/// Error types for the evdev backend.
69pub mod error;
70/// Virtual uinput device for forwarding and emitting key events.
71pub mod forwarder;
72
73/// Convert an [`evdev::KeyCode`] to a [`kbd::key::Key`].
74pub use crate::convert::EvdevKeyCodeExt;
75/// Convert a [`kbd::key::Key`] to an [`evdev::KeyCode`].
76pub use crate::convert::KbdKeyExt;