AXUIElement::system_wide() in Rust, and the trap the docs leave out

The constructors, and which one you actually want

The struct gives you four ways to get an AXUIElement to start from: system_wide(), application(pid), application_with_bundle(bundle_id), and application_with_bundle_timeout(bundle_id, timeout). People reach for system_wide() first because it is the one that needs no arguments. That is usually the wrong move. Here is the difference that matters:

The single legitimate reason to start from system_wide() is the focused-element query. Reading the AXFocusedUIElement attribute on the system root tells you which control has keyboard focus right now, across every app on the machine. That is the global hook editors and clipboard tools use. For anything scoped to a known process, take the pid and call application(pid).

Why system_wide() “works” but reads nothing

The first surprise is that system_wide() cannot fail. Its return type is Self, not Result<Self, Error>. So the handle always looks fine. The failure shows up one call later, when you read an attribute and macOS refuses because your process was never granted Accessibility permission. The element is real; the data behind it is gated.

use accessibility::{AXUIElement, AXAttribute};

// Infallible: you always get an element back.
let system = AXUIElement::system_wide();

// Fallible: this is where missing permission bites.
match system.attribute(&AXAttribute::focused_uielement()) {
    Ok(focused) => { /* the control with keyboard focus */ }
    Err(e) => {
        // Not a panic. An Err you must handle.
        eprintln!("AX read failed (permission?): {e:?}");
    }
}

Check the grant up front so you can prompt the user cleanly instead of failing deep in a tree walk. These are the preconditions before any attribute() call returns real data:

The trap: the stock TreeWalker does not traverse windows

This is the part no reference page mentions, and the reason this guide exists. The accessibility crate ships a TreeWalker. If you point it at an application's AXUIElement and expect it to enumerate the windows and controls, you will get an almost-empty tree. The reason: on macOS an application's windows are reached through dedicated accessors, not reliably through the generic AXChildren attribute the stock walker follows.

Terminator hit this and left the explanation as the literal first line of its walker file, crates/terminator/src/platforms/tree_search.rs:

/// TLDR: default TreeWalker does not traverse windows,
/// so we need to traverse windows manually
use accessibility::{AXAttribute, AXUIElement, AXUIElementAttributes, Error};

The fix is a custom walker, TreeWalkerWithWindows, that visits things in a deliberate order. For each element it tries the windows first, then the main window, then the ordinary children:

// crates/terminator/src/platforms/tree_search.rs (abridged)
if flow == TreeWalkerFlow::Continue {
    // 1. windows() - the step the stock walker skips
    if let Ok(windows) = &root.windows() {
        for window in windows.iter() {
            self.walk_one(&window, visitor);
        }
    }
    // 2. main_window() - some apps expose it outside windows()
    if let Ok(main_window) = root.main_window() {
        self.walk_one(&main_window, visitor);
    }
    // 3. only now, the generic children attribute
    if let Ok(children) = root.attribute(&self.attr_children) {
        for child in children.into_iter() {
            self.walk_one(&child, visitor);
        }
    }
}

And it is a graph, so it has cycles

Once you walk windows manually you hit the second surprise: the accessibility tree is not a tree. The same element can show up under more than one parent, so a naive recursive descent loops forever. Terminator dedupes by wrapping every AXUIElement in an AXUIElementWrapper and keeping a HashSet of what it has already seen. The wrapper's identity is the underlying Core Foundation object, compared with CFEqual and hashed with CFHash, not a Rust pointer:

impl PartialEq for AXUIElementWrapper {
    fn eq(&self, other: &Self) -> bool {
        unsafe {
            let a = self.element.as_concrete_TypeRef();
            let b = other.element.as_concrete_TypeRef();
            core_foundation::base::CFEqual(a as _, b as _) != 0
        }
    }
}

impl Hash for AXUIElementWrapper {
    fn hash<H: Hasher>(&self, state: &mut H) {
        unsafe {
            let r = self.element.as_concrete_TypeRef();
            state.write_u64(core_foundation::base::CFHash(r as _) as u64);
        }
    }
}

Before recursing, the walker checks the set; a repeat returns SkipSubtree and increments a cycle counter you can log. There is also a hard MAX_DEPTH of 100 as a backstop, and the element finder polls on an implicit-wait deadline, sleeping in 250 ms slices until the target appears or time runs out. None of this is in the crate docs; all of it is in tree_search.rs, MIT licensed, ready to copy.

Frequently asked questions