Struct ShellSurface 

pub struct ShellSurface {
    pub kind: ShellSurfaceKind,
    pub name: String,
    pub pid: Option<u32>,
    pub data: ElementData,
    /* private fields */
}

A shell surface: one OS-owned top-level accessibility root, tagged with what it is. The entry point for shell queries, as App is for application queries.

ShellSurface is not an Element — it represents the surface as a whole and provides a locator to search its accessibility tree.

Fields

kind: ShellSurfaceKind

What this surface is.

name: String

Human-readable name: the owning app for per-app surfaces (“Safari” menu bar, “Arq” status items), the platform’s own name otherwise (“Taskbar”, “Dock”). Falls back to the kind’s snake_case spelling when the platform vends no name for the root.

pid: Option<u32>

Owning process where the platform reports one honestly. On macOS this is always the true owner. On Windows it is the process that hosts the surface: explorer.exe / ShellHost.exe for shell chrome, or the owning application for a native popup menu. UIA carries no per-icon owner, so taskbar and tray-icon elements still report their shell host, never a guessed application. On Linux it is the panel process.

data: ElementData

The surface’s root element data.

Implementations

impl ShellSurface

pub fn list_with(provider: Arc<dyn Provider>) -> Result<Vec<Self>>

List the OS shell surfaces currently on screen, using an explicit provider.

Prefer ShellSurface::list from the xa11y crate which uses the global singleton provider. Use this variant when you need to supply a specific provider (e.g. a mock in unit tests).

The listing is live: Flyout surfaces appear only while they are open, and enumerating never opens, closes, or presses anything. A platform with no surface of a given kind simply returns none — that is honest scope, not a failure.

pub fn by_kind_with( provider: Arc<dyn Provider>, kind: ShellSurfaceKind, timeout: Duration, ) -> Result<Self>

Wait for exactly one surface of kind, using an explicit provider.

Prefer ShellSurface::by_kind from the xa11y crate which uses the global singleton provider.

Polls list_with until a single surface of kind exists or timeout elapses; Duration::ZERO performs exactly one attempt (no waiting). An enumeration failure short-circuits — “the shell cannot be listed” is not “the surface isn’t up yet”. The wait is what makes the flyout workflow a one-liner: press the tray chevron, then wait for the overflow window to materialise.

Errors

Returns Error::SelectorNotMatched both when no surface of kind is present and when several are — a second Panel frame, status items from several processes, a leftover Flyout. Ambiguity is refused rather than first-matched: for a surface whose consumers are mostly agents, silently acting on one of several indistinguishable candidates is the failure mode worth ruling out. The refusal is terminal, not a retry — the diagnosis lists the candidates so the caller can disambiguate with list_with and a pid.

pub fn locator(&self, selector: &str) -> Locator

Create a Locator to search this surface’s accessibility tree.

pub fn children(&self) -> Result<Vec<Element>>

Get direct children of the surface root.

pub fn tree(&self, max_depth: Option<usize>) -> Result<TreeNode>

Capture the surface’s accessibility tree as a recursive snapshot, rooted at the surface element.

Equivalent to self.as_element().tree(max_depth). See Element::tree for max_depth semantics.

pub fn dump(&self, max_depth: Option<usize>) -> Result<String>

Render the surface’s accessibility tree as an indented string, rooted at the surface element.

The primary inspection helper for figuring out the role/name of every element in a shell surface before writing selectors. Equivalent to self.as_element().dump(max_depth). See Element::dump for the output format.

pub fn as_element(&self) -> Element

Get an Element handle for the surface root.

Useful when you want to use Element-level methods (e.g. tree, dump, children) without going through a locator.

Trait Implementations

impl Debug for ShellSurface

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for ShellSurface

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.