tui_a11y/lib.rs
1//! Experimental Linux accessibility support for terminal UIs, via [AT-SPI]
2//! and [AccessKit].
3//!
4//! Terminal UI frameworks render characters at cell positions; they have no
5//! concept of focus, selection, or semantic roles, and no retained widget
6//! tree to derive them from. This crate doesn't try to infer any of that
7//! from a rendered screen buffer. Instead, the app declares a small,
8//! separate accessibility tree by hand see [`TreeBuilder`] and this crate
9//! serves it over AT-SPI via [`A11y`].
10//!
11//! # Quick start
12//!
13//! ```no_run
14//! use tui_a11y::{A11y, Role, TreeBuilder, node_id};
15//!
16//! let window_id = node_id("window");
17//! let mut tree = TreeBuilder::new();
18//! tree.node(window_id, Role::Window, "My app", []);
19//! tree.root(window_id);
20//!
21//! let mut a11y = A11y::new(tree.build());
22//!
23//! // ...in your render loop, after every draw:
24//! let mut tree = TreeBuilder::new();
25//! tree.node(window_id, Role::Window, "My app", []);
26//! tree.root(window_id);
27//! a11y.update(tree.build());
28//! ```
29//!
30//! # The `IsEnabled` gotcha
31//!
32//! [`A11y::new`] only actually registers on the AT-SPI bus once the desktop
33//! reports `org.a11y.Status.IsEnabled = true` which happens automatically
34//! once a screen reader like Orca is running, but is otherwise off by default
35//! on most Linux desktops. There is no error and no log line when it's off:
36//! [`A11y::update`] just quietly does nothing.
37//! first:
38//!
39//! ```sh
40//! gsettings set org.gnome.desktop.interface toolkit-accessibility true
41//! ```
42//!
43//! [AT-SPI]: https://www.freedesktop.org/wiki/Accessibility/AT-SPI2/
44//! [AccessKit]: https://github.com/AccessKit/accesskit
45
46mod accessible;
47mod adapt;
48mod adapter;
49mod builder;
50mod id;
51mod subtree;
52
53pub use accessible::{Accessible, StatefulAccessible};
54pub use accesskit::{Action, ActionRequest, Node, NodeId, Role, TreeId, TreeInfo, TreeUpdate};
55pub use adapt::{
56 gauge_nodes, group_nodes, items_nodes, list_nodes, table_nodes, tabs_nodes, text_nodes,
57};
58pub use adapter::A11y;
59pub use builder::TreeBuilder;
60pub use id::node_id;
61pub use subtree::SubTree;