1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
//! Linux evdev input for Denise.
//!
//! Reads mice, touchscreens and keyboards straight from `/dev/input/event*`, with
//! no display server in the way.
//!
//! # Testing
//!
//! [`translate`] and [`keymap`] are platform-independent and unit tested
//! everywhere. That is not tidiness: multitouch slot tracking, frame batching and
//! modifier state are the parts that break, and each one is far easier to pin down
//! as a table of raw event codes than by dragging a finger across a panel and
//! guessing. Only device discovery and reading are gated to Linux.
//!
//! # Permissions
//!
//! Reading `/dev/input/event*` needs membership in the `input` group, or root.
//! Being able to read every keystroke on the machine is exactly as sensitive as it
//! sounds, which is why the group exists.
//!
//! # Blocking
//!
//! [`InputSource::poll`](denise::InputSource::poll) never blocks: it drains whatever is ready and returns.
//! A frame loop that wants to sleep should wait on [`InputBackend::raw_fds`]
//! together with the DRM device's descriptor, so the process idles in the kernel
//! until either input arrives or the display retires a flip — rather than spinning
//! to ask.
//!
//! # Devices that arrive late
//!
//! The set is not fixed, so that list of descriptors is not either. A wireless
//! mouse asleep when the panel starts has no `/dev/input/event*` node at all — the
//! receiver enumerates, the mouse does not — and the node appears whenever
//! somebody first moves it, which on a machine left running is measured in
//! minutes rather than seconds. `poll` opens it then, and a loop holding a list
//! made at startup would neither read it nor wake for it.
//!
//! So: ask [`InputBackend::devices_changed`] each pass, and take
//! [`InputBackend::raw_fds`] again when it says yes. `examples/bare-linux`
//! packages that as `Waits` and every kiosk example uses it.
// Off Linux, some of the items the documentation above links to are compiled
// out, so those links resolve to nothing and `cargo doc` fails. CI documents on
// Ubuntu and never sees it; a developer on a Mac cannot avoid it. Linux stays
// the platform that checks these links, being the one with the items to check
// them against.
/// Keyboard layouts, re-exported from [`denise_layout`].
///
/// They lived here until 0.16, and a position-to-character table is no more
/// about evdev than it is about Cocoa — an on-screen keyboard wants the same
/// tables and should not depend on a Linux input backend to get them.
pub use denise_layout as layout;
pub use key_code;
pub use ;
pub use ;
pub use ;
pub use EvdevError;
/// Compiles the examples in this crate's README, so they cannot drift from the API
/// they claim to demonstrate. Never built except under `cargo test --doc`.
;