Skip to main content

iphone_cli/ax/
attrs.rs

1//! What the numbered accessibility attributes mean.
2//!
3//! Found by experiment on iOS 27.0.1 with Settings, Calculator and Notes
4//! (2026-11-10): read a screen, compare the numbers with what is visibly
5//! there, change one thing, read again. Numbers not listed here are passed
6//! through untouched in `iph read --raw`.
7//!
8//! Seen but not used: 1 activation point, 13 custom actions, 48 and 43 other
9//! frames, 61 a second role-like number, 73 language, 78 trait descriptions
10//! ("버튼"), 87/88 alternative labels, 128 a pointer string.
11
12/// Text VoiceOver would speak for the element. String or attributed string.
13pub const LABEL: i64 = 3;
14/// Every child element, on screen or not.
15pub const CHILDREN: i64 = 8;
16/// Children the phone considers visible.
17pub const VISIBLE_CHILDREN: i64 = 9;
18/// `{{x, y}, {w, h}}` in logical points, screen coordinates.
19pub const FRAME: i64 = 21;
20/// Developer-assigned accessibilityIdentifier. Only in the additional pass.
21pub const IDENTIFIER: i64 = 25;
22/// Whether this is an accessibility element (false for plain containers).
23pub const IS_ELEMENT: i64 = 26;
24/// Role number, see [`role_name`].
25pub const ROLE: i64 = 45;
26/// Free-text role description, e.g. "back button".
27pub const ROLE_DESCRIPTION: i64 = 46;
28/// Current value: text of a field, "1"/"0" of a switch, percentage of a slider.
29pub const VALUE: i64 = 53;
30/// Bit set of UIAccessibilityTraits, see [`trait_names`].
31pub const TRAITS: i64 = 77;
32/// Hint text VoiceOver adds after the label ("changes the sign of a value").
33pub const HINT: i64 = 23;
34/// The label as plain text (number 3 can be an attributed string).
35pub const LABEL_PLAIN: i64 = 33;
36
37/// Public UIAccessibilityTraits bits, plus private ones. Seen on device:
38/// text_entry and editing (Notes body while typing), search_field (Settings),
39/// back_button (navigation bars), toggle (Settings switches), not_enabled
40/// (Notes share button on an empty note), keyboard_key (keyboard, Calculator).
41/// Not yet seen on device: secure_text, tab_button.
42pub mod traits {
43    pub const BUTTON: u64 = 1 << 0;
44    pub const LINK: u64 = 1 << 1;
45    pub const IMAGE: u64 = 1 << 2;
46    pub const SELECTED: u64 = 1 << 3;
47    pub const PLAYS_SOUND: u64 = 1 << 4;
48    pub const KEYBOARD_KEY: u64 = 1 << 5;
49    pub const STATIC_TEXT: u64 = 1 << 6;
50    pub const SUMMARY: u64 = 1 << 7;
51    pub const NOT_ENABLED: u64 = 1 << 8;
52    pub const UPDATES_FREQUENTLY: u64 = 1 << 9;
53    pub const SEARCH_FIELD: u64 = 1 << 10;
54    pub const STARTS_MEDIA: u64 = 1 << 11;
55    pub const ADJUSTABLE: u64 = 1 << 12;
56    pub const DIRECT_INTERACTION: u64 = 1 << 13;
57    pub const CAUSES_PAGE_TURN: u64 = 1 << 14;
58    pub const TAB_BAR: u64 = 1 << 15;
59    pub const HEADER: u64 = 1 << 16;
60    /// Editable text (text field or text view).
61    pub const TEXT_ENTRY: u64 = 1 << 18;
62    /// The text element that currently has the keyboard.
63    pub const IS_EDITING: u64 = 1 << 21;
64    pub const SECURE_TEXT: u64 = 1 << 24;
65    pub const BACK_BUTTON: u64 = 1 << 27;
66    pub const TAB_BUTTON: u64 = 1 << 28;
67    pub const TOGGLE: u64 = 1 << 53;
68}
69
70const TRAIT_NAMES: &[(u64, &str)] = &[
71    (traits::BUTTON, "button"),
72    (traits::LINK, "link"),
73    (traits::IMAGE, "image"),
74    (traits::SELECTED, "selected"),
75    (traits::PLAYS_SOUND, "plays_sound"),
76    (traits::KEYBOARD_KEY, "keyboard_key"),
77    (traits::STATIC_TEXT, "static_text"),
78    (traits::SUMMARY, "summary"),
79    (traits::NOT_ENABLED, "not_enabled"),
80    (traits::UPDATES_FREQUENTLY, "updates_frequently"),
81    (traits::SEARCH_FIELD, "search_field"),
82    (traits::STARTS_MEDIA, "starts_media"),
83    (traits::ADJUSTABLE, "adjustable"),
84    (traits::DIRECT_INTERACTION, "direct_interaction"),
85    (traits::CAUSES_PAGE_TURN, "causes_page_turn"),
86    (traits::TAB_BAR, "tab_bar"),
87    (traits::HEADER, "header"),
88    (traits::TEXT_ENTRY, "text_entry"),
89    (traits::IS_EDITING, "editing"),
90    (traits::SECURE_TEXT, "secure_text"),
91    (traits::BACK_BUTTON, "back_button"),
92    (traits::TAB_BUTTON, "tab_button"),
93    (traits::TOGGLE, "toggle"),
94];
95
96pub fn trait_names(bits: u64) -> Vec<&'static str> {
97    TRAIT_NAMES
98        .iter()
99        .filter(|(bit, _)| bits & bit != 0)
100        .map(|(_, name)| *name)
101        .collect()
102}
103
104/// Role name for an element. The trait bits are the dependable source (they
105/// are a public, stable set); the role number refines what traits cannot say.
106pub fn role_name(role: Option<i64>, bits: u64, is_application: bool, has_text: bool) -> &'static str {
107    if is_application || role == Some(1) {
108        return "application";
109    }
110    if bits & traits::SECURE_TEXT != 0 {
111        return "secure_text_field";
112    }
113    if bits & traits::SEARCH_FIELD != 0 {
114        return "search_field";
115    }
116    if bits & traits::TEXT_ENTRY != 0 {
117        return "text_field";
118    }
119    if bits & traits::TOGGLE != 0 || role == Some(3) {
120        return "switch";
121    }
122    if bits & traits::KEYBOARD_KEY != 0 {
123        return "key";
124    }
125    if bits & traits::TAB_BUTTON != 0 {
126        return "tab";
127    }
128    if bits & traits::ADJUSTABLE != 0 {
129        return "adjustable";
130    }
131    if bits & traits::LINK != 0 {
132        return "link";
133    }
134    if bits & traits::BUTTON != 0 || role == Some(2) {
135        return "button";
136    }
137    if bits & traits::HEADER != 0 {
138        return "header";
139    }
140    if bits & traits::IMAGE != 0 {
141        return "image";
142    }
143    if bits & traits::STATIC_TEXT != 0 {
144        return "text";
145    }
146    if bits & traits::TAB_BAR != 0 {
147        return "tab_bar";
148    }
149    // No telling trait: a row of plain text, or a container.
150    if has_text { "text" } else { "other" }
151}
152
153#[cfg(test)]
154mod tests {
155    use super::*;
156
157    #[test]
158    fn names_traits_seen_on_device() {
159        // Settings back button: button + back_button (+ an unnamed bit).
160        assert_eq!(trait_names(8724152321), vec!["button", "back_button"]);
161        // Settings airplane-mode row: button + static_text + toggle.
162        assert_eq!(
163            trait_names(9007207844675649),
164            vec!["button", "static_text", "toggle"]
165        );
166    }
167
168    #[test]
169    fn roles_follow_traits() {
170        assert_eq!(role_name(Some(1), 0, true, true), "application");
171        assert_eq!(role_name(Some(3), 9007207844675649, false, true), "switch");
172        assert_eq!(role_name(Some(15), 146029151232, false, false), "search_field");
173        assert_eq!(role_name(Some(2), 8589934657, false, true), "button");
174        assert_eq!(role_name(Some(6), 8590000192, false, true), "header");
175        assert_eq!(role_name(Some(14), 146028888064, false, true), "text");
176        assert_eq!(role_name(None, 0, false, false), "other");
177    }
178}