Skip to main content

sui_core/
semantics.rs

1use crate::{Rect, WidgetId};
2
3#[derive(Debug, Clone, PartialEq, Eq)]
4pub enum SemanticsRole {
5    Window,
6    Root,
7    GenericContainer,
8    Separator,
9    List,
10    ListItem,
11    Tree,
12    Table,
13    Splitter,
14    Breadcrumb,
15    TabBar,
16    Tabs,
17    Button,
18    Link,
19    CheckBox,
20    Switch,
21    RadioButton,
22    RadioGroup,
23    Menu,
24    MenuItem,
25    ContextMenu,
26    Tooltip,
27    Dialog,
28    Popover,
29    Slider,
30    ProgressBar,
31    BusyIndicator,
32    Document,
33    Paragraph,
34    Heading,
35    Code,
36    Status,
37    Attachment,
38    Text,
39    TextInput,
40    SpinBox,
41    ComboBox,
42    Image,
43    ColorSwatch,
44    ColorPicker,
45    Canvas,
46    ScrollView,
47}
48
49#[derive(Debug, Clone, Copy, PartialEq, Eq)]
50pub enum SemanticsPopupKind {
51    Menu,
52    ListBox,
53    Tree,
54    Grid,
55    Dialog,
56}
57
58#[derive(Debug, Clone, Copy, PartialEq, Eq)]
59pub enum SemanticsLiveRegion {
60    Polite,
61    Assertive,
62}
63
64#[derive(Debug, Clone, PartialEq, Eq, Default)]
65pub struct SemanticsRelations {
66    pub controls: Vec<WidgetId>,
67    pub labelled_by: Vec<WidgetId>,
68    pub described_by: Vec<WidgetId>,
69    pub owns: Vec<WidgetId>,
70}
71
72#[derive(Debug, Clone, PartialEq, Eq)]
73pub enum SemanticsAction {
74    Focus,
75    Blur,
76    Activate,
77    Expand,
78    Collapse,
79    Increment,
80    Decrement,
81    SetValue,
82    SetSelection,
83    InsertText,
84    DeleteBackward,
85    DeleteForward,
86    Copy,
87    Cut,
88    Paste,
89    Undo,
90    Redo,
91    Custom(String),
92}
93
94/// A concrete accessibility action requested by a platform assistive-technology
95/// provider.
96///
97/// [`SemanticsAction`] describes the capabilities advertised by a semantic
98/// node. This type carries the payload needed when one of those capabilities is
99/// invoked. Keeping the request typed avoids platform-specific string encoding
100/// while still allowing widgets to own the behavior and state changes.
101#[derive(Debug, Clone, PartialEq)]
102pub enum SemanticsActionRequest {
103    Focus,
104    Blur,
105    Activate,
106    Expand,
107    Collapse,
108    Increment,
109    Decrement,
110    SetValue(SemanticsValue),
111    SetSelection(SemanticsTextRange),
112    InsertText(String),
113    DeleteBackward,
114    DeleteForward,
115    Copy,
116    Cut,
117    Paste,
118    Undo,
119    Redo,
120    Custom { name: String, value: Option<String> },
121}
122
123impl SemanticsActionRequest {
124    /// Return the capability a semantic node must advertise for this request.
125    pub fn advertised_action(&self) -> SemanticsAction {
126        match self {
127            Self::Focus => SemanticsAction::Focus,
128            Self::Blur => SemanticsAction::Blur,
129            Self::Activate => SemanticsAction::Activate,
130            Self::Expand => SemanticsAction::Expand,
131            Self::Collapse => SemanticsAction::Collapse,
132            Self::Increment => SemanticsAction::Increment,
133            Self::Decrement => SemanticsAction::Decrement,
134            Self::SetValue(_) => SemanticsAction::SetValue,
135            Self::SetSelection(_) => SemanticsAction::SetSelection,
136            Self::InsertText(_) => SemanticsAction::InsertText,
137            Self::DeleteBackward => SemanticsAction::DeleteBackward,
138            Self::DeleteForward => SemanticsAction::DeleteForward,
139            Self::Copy => SemanticsAction::Copy,
140            Self::Cut => SemanticsAction::Cut,
141            Self::Paste => SemanticsAction::Paste,
142            Self::Undo => SemanticsAction::Undo,
143            Self::Redo => SemanticsAction::Redo,
144            Self::Custom { name, .. } => SemanticsAction::Custom(name.clone()),
145        }
146    }
147}
148
149#[derive(Debug, Clone, Copy, PartialEq, Eq)]
150pub enum ToggleState {
151    Unchecked,
152    Checked,
153    Mixed,
154}
155
156#[derive(Debug, Clone, PartialEq)]
157pub enum SemanticsValue {
158    Text(String),
159    Number(f64),
160    Range { value: f64, min: f64, max: f64 },
161}
162
163#[derive(Debug, Clone, PartialEq, Eq, Default)]
164pub struct SemanticsState {
165    pub disabled: bool,
166    pub focused: bool,
167    pub hidden: bool,
168    pub hovered: bool,
169    pub checked: Option<ToggleState>,
170    pub selected: bool,
171    pub expanded: Option<bool>,
172    pub busy: bool,
173    pub modal: bool,
174}
175
176#[derive(Debug, Clone, PartialEq, Eq)]
177pub struct SemanticsTextRange {
178    pub start: usize,
179    pub end: usize,
180}
181
182impl SemanticsTextRange {
183    pub const fn new(start: usize, end: usize) -> Self {
184        Self { start, end }
185    }
186}
187
188#[derive(Debug, Clone, PartialEq)]
189pub struct EditableTextSemantics {
190    pub caret_offset: usize,
191    pub selection: SemanticsTextRange,
192    pub multiline: bool,
193    pub password: bool,
194    pub readonly: bool,
195    pub scroll_x: f32,
196    pub scroll_y: f32,
197}
198
199#[derive(Debug, Clone, PartialEq)]
200pub struct SemanticsNode {
201    pub id: WidgetId,
202    pub parent: Option<WidgetId>,
203    pub role: SemanticsRole,
204    pub name: Option<String>,
205    pub description: Option<String>,
206    pub value: Option<SemanticsValue>,
207    /// Smallest meaningful numeric adjustment for range-style controls.
208    /// `None` means the control does not expose a numeric step.
209    pub numeric_step: Option<f64>,
210    pub state: SemanticsState,
211    pub actions: Vec<SemanticsAction>,
212    pub editable_text: Option<EditableTextSemantics>,
213    pub relations: SemanticsRelations,
214    pub popup: Option<SemanticsPopupKind>,
215    pub live_region: Option<SemanticsLiveRegion>,
216    pub bounds: Rect,
217}
218
219impl SemanticsNode {
220    pub fn new(id: WidgetId, role: SemanticsRole, bounds: Rect) -> Self {
221        Self {
222            id,
223            parent: None,
224            role,
225            name: None,
226            description: None,
227            value: None,
228            numeric_step: None,
229            state: SemanticsState::default(),
230            actions: Vec::new(),
231            editable_text: None,
232            relations: SemanticsRelations::default(),
233            popup: None,
234            live_region: None,
235            bounds,
236        }
237    }
238}
239
240#[cfg(test)]
241mod tests {
242    use super::{SemanticsNode, SemanticsRole};
243    use crate::{Rect, WidgetId};
244
245    #[test]
246    fn semantic_nodes_default_to_no_numeric_step() {
247        let node = SemanticsNode::new(WidgetId::new(7), SemanticsRole::Slider, Rect::ZERO);
248
249        assert_eq!(node.numeric_step, None);
250    }
251}