class EE::UI::AccessibilityManager

Overview

Resolves accessibility information directly from the live UI tree. More…

#include <accessibilitymanager.hpp>

class AccessibilityManager {
public:
    // structs

    struct ChildrenCacheEntry;

    // classes

    class ScopedDispatch;

    // construction

    AccessibilityManager(UISceneNode* scene);
    ~AccessibilityManager();

    // methods

    AccessibilityNodeRef getRoot();
    AccessibilityNodeRef getNodeRef(UIWidget* widget);
    AccessibilityNodeRef findNodeRef(UIWidget* widget) const;
    bool isValid(AccessibilityNodeRef ref) const;
    AccessibilityRole getNodeRole(AccessibilityNodeRef ref) const;
    Uint8 getNodeHeadingLevel(AccessibilityNodeRef ref) const;
    AccessibilityState getNodeState(AccessibilityNodeRef ref) const;
    AccessibilityNodeInfo getNodeInfo(AccessibilityNodeRef ref, bool includeValue = true) const;
    AccessibilityNodeInfo getNodeInfo(AccessibilityNodeRef ref, bool includeValue, bool includeTextOffsets) const;
    AccessibilityNodeRef getParent(AccessibilityNodeRef ref);
    Int32 getIndexInParent(AccessibilityNodeRef ref);
    AccessibilityTextInfo getTextInfo(AccessibilityNodeRef ref) const;
    Int32 getTextLength(AccessibilityNodeRef ref) const;
    String getTextRange(AccessibilityNodeRef ref, Int32 start, Int32 end) const;
    bool getTextLineBounds(AccessibilityNodeRef ref, Int32 offset, Int32& start, Int32& end) const;
    AccessibilityTextRevision getTextRevision(AccessibilityNodeRef ref) const;
    void onTextChanged(UIWidget* widget, const Doc::DocumentContentChange* change);
    void setSuppressedTextChanges(AccessibilityNodeRef ref);
    size_t getChildCount(AccessibilityNodeRef ref);
    AccessibilityNodeRef getChild(AccessibilityNodeRef ref, size_t index);
    const std::vector<AccessibilityNodeRef>& getChildren(AccessibilityNodeRef ref);
    std::vector<AccessibilityNodeRef> getSelectedChildren(AccessibilityNodeRef ref);
    AccessibilityNodeRef hitTest(const Math::Vector2f& screenPosition);
    AccessibilityNodeRef getKeyboardFocusedNode();
    bool performAction(AccessibilityNodeRef ref, const AccessibilityActionRequest& request);
    bool isBackendAvailable() const;
    bool isBackendInitializationComplete() const;
    bool hasActiveNativeClients() const;
    void onNativeClientObserved();
    void onClientsDisconnected();
    void update();
    void setBackend(std::unique_ptr<AccessibilityBackend> backend);
    UISceneNode* getSceneNode() const;
    void notify(AccessibilityNodeRef ref, AccessibilityEvent event, AccessibilityNodeRef related = {}, Int32 index = -1);
    const std::vector<AccessibilityPendingEvent>& getPendingEvents() const;
    void clearPendingEvents();
    void announce(const String& message, AccessibilityLive priority = AccessibilityLive::Polite);
    void onLiveRegionChanged(UIWidget* widget, AccessibilityLive priority);
    const std::vector<AccessibilityAnnouncement>& getPendingAnnouncements() const;
    void onRelationTargetChanged(const std::string& id, const Scene::Node* excluded = nullptr);
    bool isRelationTarget(String::HashType idHash) const;
    void onRelationSubtreeChanged(const Scene::Node* subtree, bool removed);
    void onNodeParentChange(Scene::Node* node, bool removed);
    bool onWidgetAccessibilitySourceDelete(UIWidget* widget);
    void onWidgetDelete(UIWidget* widget);
    void onSubtreeRemoved(Scene::Node* node);
};

Detailed Documentation

Resolves accessibility information directly from the live UI tree.

Methods

AccessibilityNodeRef findNodeRef(UIWidget* widget) const

The widget’s identity if one was handed out, without registering one. Clients only hold handed-out identities, so property changes of other widgets need no notification.

AccessibilityRole getNodeRole(AccessibilityNodeRef ref) const

Scalar queries avoid constructing names, values, text offsets or relation caches.

AccessibilityNodeInfo getNodeInfo(AccessibilityNodeRef ref, bool includeValue, bool includeTextOffsets) const

Native metadata queries may also omit document-offset calculation.

Int32 getTextLength(AccessibilityNodeRef ref) const

Ranged text access in code points. Prefer these over getNodeInfo() ‘s value for text elements: they never copy more than the requested range.

bool getTextLineBounds(AccessibilityNodeRef ref, Int32 offset, Int32& start, Int32& end) const

The line containing offset : [start, end), end past its newline.

void onTextChanged(UIWidget* widget, const Doc::DocumentContentChange* change)

Reports an edit of a text widget’s document, or nullptr when its whole text was replaced. Only backends requesting edit records receive them. The first few edits per widget and frame are forwarded exactly; later ones collapse into a single whole-text change, so a replace-all costs one notification.

void setSuppressedTextChanges(AccessibilityNodeRef ref)

While set, text changes of this element are not forwarded: the caller reports them itself (AT-SPI SetTextContents sends one minimal diff). Node refs are local to this manager, so another window’s element sharing the document still reports its changes. Pass an invalid ref to clear.

void onNativeClientObserved()

Updates the scene’s cached fast-path flag after an actual native accessibility query.

void onClientsDisconnected()

The scene’s last client went away: releases what only clients needed, such as queried model rows and their persistent model registrations. Identities are never reused, so a reconnecting client cannot reach a stale row.

void setBackend(std::unique_ptr<AccessibilityBackend> backend)

Replaces the platform backend, which update() otherwise creates on first use. Intended for tests that observe what the manager delivers.

void announce(const String& message, AccessibilityLive priority = AccessibilityLive::Polite)

Asks assistive clients to speak a message without moving focus. Delivered on the next update(); a no-op while no client is active.

void onLiveRegionChanged(UIWidget* widget, AccessibilityLive priority)

Queues the current text of a widget inside a live region, replacing any announcement the same widget queued earlier in this frame.

void onRelationTargetChanged(const std::string& id, const Scene::Node* excluded = nullptr)

The widget with this id changed its name, appeared or went away. Widgets that a client read and that are named or described by it (aria-labelledby, aria-describedby) report NameChanged or DescriptionChanged. Dependents inside excluded are skipped.

bool isRelationTarget(String::HashType idHash) const

Whether an active client may hold a name or description resolved through the id with this hash, so its dependents must be told when that id goes away. Allocation-free; it matches exactly what onRelationTargetChanged() would act on.

void onRelationSubtreeChanged(const Scene::Node* subtree, bool removed)

A subtree appeared or is going away: notifies the dependents of each relation target in it, except those inside the subtree when it is going away.

void onNodeParentChange(Scene::Node* node, bool removed)

Reports a reparent/reorder edge for the exposed roots of a widget or plain-node subtree. Removal is reported while the old parent links are intact; arrival after final relinking.

bool onWidgetAccessibilitySourceDelete(UIWidget* widget)

Returns whether the widget owned a model source that has now been released.

void onWidgetDelete(UIWidget* widget)

Empty and native-root-only managers skip invalidation inline, without a tree walk. Explicit semantic queries can retain descendants/text indexes without a native client: those still require invalidation. Active root relations also require the full path.

void onSubtreeRemoved(Scene::Node* node)

Invalidates registered identities before a subtree changes accessibility owners.