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
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
use super::{Response, Ui};
use crate::{context::FocusAxis, AccessOrientation, AccessRole, Id};
use std::hash::Hash;
/// A set of controls that is one Tab stop. Tab and Shift+Tab enter and leave it; inside,
/// the arrow keys along its axis move focus between the controls and Home and End jump to
/// the first and last, skipping controls that are disabled, hidden, clipped away or gone.
/// Focus moves, the value does not: navigation selects nothing and calls nothing.
///
/// Every control built in the closure that takes focus joins: [`Button`](crate::Button)s,
/// regions made with [`Ui::interact`] and `Sense::FOCUS`, other widgets. Clicking one
/// focuses it and makes it the stop, so Tab and Shift+Tab come back to it. A group built
/// inside another is one member of the outer group. Content that opens in another layer
/// (a popup, a window) does not join.
///
/// A control that keeps arrow keys for itself, such as a [`TextEdit`](crate::TextEdit) or a
/// [`Slider`](crate::Slider), is a member too: neighbours move focus onto it, it keeps its
/// own keys while focused, and Tab leaves the group. A custom widget does the same by
/// claiming keys with [`Ui::keys`]. A complex part with several focusable regions and its
/// own arrow-key navigation (a [`TabBar`](crate::TabBar), a [`ListBox`](crate::ListBox)) is
/// a nested [`FocusGroup::slot`]: one member for the group around it, whose arrows then
/// belong to the part alone.
///
/// ```no_run
/// # use zaxis::{FocusGroup, AccessRole, Ui};
/// # fn view(ui: &mut Ui<'_>) {
/// FocusGroup::new("tools")
/// .horizontal()
/// .label("Tools")
/// .role(AccessRole::Toolbar)
/// .show(ui, |ui| {
/// ui.horizontal(|ui| {
/// ui.button("Cut");
/// ui.button("Copy");
/// ui.button("Paste");
/// });
/// });
/// # }
/// ```
#[derive(Clone, Debug)]
pub struct FocusGroup {
source: Id,
axis: FocusAxis,
wrap: bool,
label: Option<String>,
role: AccessRole,
}
/// What [`FocusGroup::show`] returns.
pub struct FocusGroupOutput<R> {
/// The value of the closure.
pub inner: R,
/// The group as a whole. `has_focus` is true while focus is on any member,
/// `gained_focus` and `lost_focus` report focus entering and leaving the group, and
/// `rect` is the union of its members as laid out.
pub response: Response,
stop: Option<Id>,
moved: Option<Id>,
}
impl<R> FocusGroupOutput<R> {
/// The region Tab lands on from outside, as the last pass left it. Pass it to
/// [`Context::request_focus`](crate::Context::request_focus) to move focus into the
/// group from code.
pub fn stop(&self) -> Option<Id> {
self.stop
}
/// The region arrow keys, Home or End moved focus to since the last pass, if they did:
/// the final one when several keys arrived between passes. Tab, clicks and
/// `request_focus` are not reported. A control that selects as focus moves uses this.
pub fn navigated(&self) -> Option<Id> {
self.moved
}
}
impl FocusGroup {
/// A group with a stable identity among its siblings. Arrows are horizontal and do
/// not wrap; the accessibility role is `Group`.
pub fn new(id_source: impl Hash) -> Self {
Self {
source: Id::new(id_source),
axis: FocusAxis::Horizontal,
wrap: false,
label: None,
role: AccessRole::Group,
}
}
/// A part with several focusable regions that navigates itself. No group moves focus
/// inside it with the arrow keys or acts on them while focus is inside; as a member of
/// a group it is one member and one stop.
pub fn slot(id_source: impl Hash) -> Self {
Self::new(id_source).axis(FocusAxis::None)
}
pub fn axis(mut self, axis: FocusAxis) -> Self {
self.axis = axis;
self
}
/// Left and Right move focus.
pub fn horizontal(self) -> Self {
self.axis(FocusAxis::Horizontal)
}
/// Up and Down move focus.
pub fn vertical(self) -> Self {
self.axis(FocusAxis::Vertical)
}
/// Whether moving past the last member continues at the first, and the other way
/// round. Off by default: at an end the key does nothing and stays with the group.
pub fn wrap(mut self, wrap: bool) -> Self {
self.wrap = wrap;
self
}
/// The name assistive technology speaks for the group.
pub fn label(mut self, label: impl Into<String>) -> Self {
self.label = Some(label.into());
self
}
/// What the group is called to assistive technology: `Toolbar`, `RadioGroup`, `Menu`,
/// `TabList`, ... The members describe themselves.
pub fn role(mut self, role: AccessRole) -> Self {
self.role = role;
self
}
/// Build the members. The closure runs once, in a scope of its own for ids.
pub fn show<R>(
self,
ui: &mut Ui<'_>,
build: impl FnOnce(&mut Ui<'_>) -> R,
) -> FocusGroupOutput<R> {
let id = ui.scope.with(("focus-group", self.source));
let scope = ui.a11y_begin(id.with("node"), self.role, |node| {
if let Some(label) = &self.label {
node.label(label.as_str());
}
match self.axis {
FocusAxis::Horizontal => {
node.orientation(AccessOrientation::Horizontal);
}
FocusAxis::Vertical => {
node.orientation(AccessOrientation::Vertical);
}
FocusAxis::Both | FocusAxis::None => {}
}
});
let stop = ui.context.focus_groups.stop(id, ui.context.focused());
// The accessibility node closes even when `build` unwinds, like the scopes it nests in.
let built = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
ui.focus_scope(id, self.axis, self.wrap, |ui| ui.push_id(id, build))
}));
ui.a11y_end(scope, None);
let (inner, end) = match built {
Ok(built) => built,
Err(payload) => std::panic::resume_unwind(payload),
};
let moved = ui.context.focus_groups.take_moved(id);
let focused = ui.context.focused();
let events = ui.context.gestures.events(id);
let mut response = ui.response(id, end.bounds.unwrap_or_default(), false);
response.enabled = ui.is_enabled();
response.has_focus = end.has_focus;
response.focus_visible =
response.has_focus && focused.is_some_and(|focus| ui.context.focus_visible(focus));
response.gained_focus = events.gained_focus;
response.lost_focus = events.lost_focus;
FocusGroupOutput {
inner,
response,
stop,
moved,
}
}
}