| Flutter macOS Embedder |

Classes | Public Member Functions | Protected Member Functions | List of all members
flutter::AccessibilityBridge Class Referenceabstract

`#include <accessibility_bridge.h>`

Inheritance diagram for flutter::AccessibilityBridge:

## Public Member Functions
| AccessibilityBridge ()
| Creates a new instance of a accessibility bridge. More...
virtual | ~AccessibilityBridge ()
void | AddFlutterSemanticsNodeUpdate (const FlutterSemanticsNode2 &node)
| Adds a semantics node update to the pending semantics update. Calling this method alone will NOT update the semantics tree. To flush the pending updates, call the CommitUpdates(). More...
void | AddFlutterSemanticsCustomActionUpdate (const FlutterSemanticsCustomAction2 &action)
| Adds a custom semantics action update to the pending semantics update. Calling this method alone will NOT update the semantics tree. To flush the pending updates, call the CommitUpdates(). More...
void | CommitUpdates ()
| Flushes the pending updates and applies them to this accessibility bridge. Calling this with no pending updates does nothing, and callers should call this method at the end of an atomic batch to avoid leaving the tree in a unstable state. For example if a node reparents from A to B, callers should only call this method when both removal from A and addition to B are in the pending updates. More...
std::weak_ptr< FlutterPlatformNodeDelegate > | GetFlutterPlatformNodeDelegateFromID (AccessibilityNodeId id) const
| Get the flutter platform node delegate with the given id from this accessibility bridge. Returns expired weak_ptr if the delegate associated with the id does not exist or has been removed from the accessibility tree. More...
const ui::AXTreeData & | GetAXTreeData () const
| Get the ax tree data from this accessibility bridge. The tree data contains information such as the id of the node that has the keyboard focus or the text selection range. More...
const std::vector< ui::AXEventGenerator::TargetedEvent > | GetPendingEvents () const
| Gets all pending accessibility events generated during semantics updates. This is useful when deciding how to handle events in AccessibilityBridgeDelegate::OnAccessibilityEvent in case one may decide to handle an event differently based on all pending events. More...
ui::AXNode * | GetNodeFromTree (const ui::AXTreeID tree_id, const ui::AXNode::AXID node_id) const override
ui::AXNode * | GetNodeFromTree (const ui::AXNode::AXID node_id) const override
ui::AXTreeID | GetTreeID () const override
ui::AXTreeID | GetParentTreeID () const override
ui::AXNode * | GetRootAsAXNode () const override
ui::AXNode * | GetParentNodeFromParentTreeAsAXNode () const override
ui::AXTree * | GetTree () const override
ui::AXPlatformNode * | GetPlatformNodeFromTree (const ui::AXNode::AXID node_id) const override
ui::AXPlatformNode * | GetPlatformNodeFromTree (const ui::AXNode &node) const override
ui::AXPlatformNodeDelegate * | RootDelegate () const override
Public Member Functions inherited from flutter::FlutterPlatformNodeDelegate::OwnerBridge
virtual | ~OwnerBridge ()=default

## Protected Member Functions
virtual void | OnAccessibilityEvent (ui::AXEventGenerator::TargetedEvent targeted_event)=0
| Handle accessibility events generated due to accessibility tree changes. These events are needed to be sent to native accessibility system. See ui::AXEventGenerator::Event for possible events. More...
virtual std::shared_ptr< FlutterPlatformNodeDelegate > | CreateFlutterPlatformNodeDelegate ()=0
| Creates a platform specific FlutterPlatformNodeDelegate. Ownership passes to the caller. This method will be called whenever a new AXNode is created in AXTree. Each platform needs to implement this method in order to inject its subclass into the accessibility bridge. More...
Protected Member Functions inherited from flutter::FlutterPlatformNodeDelegate::OwnerBridge
virtual void | DispatchAccessibilityAction (AccessibilityNodeId target, FlutterSemanticsAction action, fml::MallocMapping data)=0
| Dispatch accessibility action back to the Flutter framework. These actions are generated in the native accessibility system when users interact with the assistive technologies. For example, a FlutterSemanticsAction::kFlutterSemanticsActionTap is fired when user click or touch the screen. More...

## Detailed Description

Use this class to maintain an accessibility tree. This class consumes semantics updates from the embedder API and produces an accessibility tree in the native format.

The bridge creates an AXTree to hold the semantics data that comes from Flutter semantics updates. The tree holds AXNode[s] which contain the semantics information for semantics node. The AXTree resemble the Flutter semantics tree in the Flutter framework. The bridge also uses FlutterPlatformNodeDelegate to wrap each AXNode in order to provide an accessibility tree in the native format.

To use this class, one must subclass this class and provide their own implementation of FlutterPlatformNodeDelegate.

AccessibilityBridge must be created as a shared_ptr, since some methods acquires its weak_ptr.

Definition at line 40 of file accessibility_bridge.h.

## Constructor & Destructor Documentation

## ◆ AccessibilityBridge()

flutter::AccessibilityBridge::AccessibilityBridge | ( |  | ) |

Creates a new instance of a accessibility bridge.

Definition at line 23 of file accessibility_bridge.cc.

24 : tree_(std::make_unique<ui::AXTree>()) {
25 event_generator_.SetTree(tree_.get());
26 tree_->AddObserver(static_cast<ui::AXTreeObserver*>(this));
27 ui::AXTreeData data = tree_->data();
28 data.tree_id = ui::AXTreeID::CreateNewAXTreeID();
29 tree_->UpdateData(data);
30 ui::AXTreeManagerMap::GetInstance().AddTreeManager(tree_->GetAXTreeID(),
31 this);
32 }

## ◆ ~AccessibilityBridge()

flutter::AccessibilityBridge::~AccessibilityBridge | ( |  | ) |
| virtual

Definition at line 34 of file accessibility_bridge.cc.

34 {
35 event_generator_.ReleaseTree();
36 tree_->RemoveObserver(static_cast<ui::AXTreeObserver*>(this));
37 }

## Member Function Documentation

## ◆ AddFlutterSemanticsCustomActionUpdate()

void flutter::AccessibilityBridge::AddFlutterSemanticsCustomActionUpdate | ( | const FlutterSemanticsCustomAction2 & | action | ) |

Adds a custom semantics action update to the pending semantics update. Calling this method alone will NOT update the semantics tree. To flush the pending updates, call the CommitUpdates().

Parameters

  [in] | action | A reference to the custom semantics action update.

Definition at line 44 of file accessibility_bridge.cc.

45 {
46 pending_semantics_custom_action_updates_[action.id] =
47 FromFlutterSemanticsCustomAction(action);
48 }

## ◆ AddFlutterSemanticsNodeUpdate()

void flutter::AccessibilityBridge::AddFlutterSemanticsNodeUpdate | ( | const FlutterSemanticsNode2 & | node | ) |

Adds a semantics node update to the pending semantics update. Calling this method alone will NOT update the semantics tree. To flush the pending updates, call the CommitUpdates().

Parameters

  [in] | node | A reference to the semantics node update.

Definition at line 39 of file accessibility_bridge.cc.

40 {
41 pending_semantics_node_updates_[node.id] = FromFlutterSemanticsNode(node);
42 }

## ◆ CommitUpdates()

void flutter::AccessibilityBridge::CommitUpdates | ( |  | ) |

Flushes the pending updates and applies them to this accessibility bridge. Calling this with no pending updates does nothing, and callers should call this method at the end of an atomic batch to avoid leaving the tree in a unstable state. For example if a node reparents from A to B, callers should only call this method when both removal from A and addition to B are in the pending updates.

Definition at line 50 of file accessibility_bridge.cc.

50 {
51 // AXTree cannot move a node in a single update.
52 // This must be split across two updates:
53 //
54 // * Update 1: remove nodes from their old parents.
55 // * Update 2: re-add nodes (including their children) to their new parents.
56 //
57 // First, start by removing nodes if necessary.
58 std::optional<ui::AXTreeUpdate> remove_reparented =
59 CreateRemoveReparentedNodesUpdate();
60 if (remove_reparented.has_value()) {
61 tree_->Unserialize(remove_reparented.value());
62
63 std::string error = tree_->error();
64 if (!error.empty()) {
65 FML_LOG(ERROR) << "Failed to update ui::AXTree, error: " << error;
66 assert(false);
67 return;
68 }
69 }
70
71 // Second, apply the pending node updates. This also moves reparented nodes to
72 // their new parents if needed.
73 ui::AXTreeUpdate update{.tree_data = tree_->data()};
74
75 // Figure out update order, ui::AXTree only accepts update in tree order,
76 // where parent node must come before the child node in
77 // ui::AXTreeUpdate.nodes. We start with picking a random node and turn the
78 // entire subtree into a list. We pick another node from the remaining update,
79 // and keep doing so until the update map is empty. We then concatenate the
80 // lists in the reversed order, this guarantees parent updates always come
81 // before child updates. If the root is in the update, it is guaranteed to
82 // be the first node of the last list.
83 std::vector<std::vector<SemanticsNode>> results;
84 while (!pending_semantics_node_updates_.empty()) {
85 auto begin = pending_semantics_node_updates_.begin();
86 SemanticsNode target = begin->second;
87 std::vector<SemanticsNode> sub_tree_list;
88 GetSubTreeList(target, sub_tree_list);
89 results.push_back(sub_tree_list);
90 pending_semantics_node_updates_.erase(begin);
91 }
92
93 for (size_t i = results.size(); i > 0; i--) {
94 for (const SemanticsNode& node : results[i - 1]) {
95 ConvertFlutterUpdate(node, update);
96 }
97 }
98
99 // The first update must set the tree's root, which is guaranteed to be the
100 // last list's first node. A tree's root node never changes, though it can be
101 // modified.
102 if (!results.empty() && GetRootAsAXNode()->id() == ui::AXNode::kInvalidAXID) {
103 FML_DCHECK(!results.back().empty());
104
105 update.root_id = results.back().front().id;
106 }
107
108 tree_->Unserialize(update);
109 pending_semantics_node_updates_.clear();
110 pending_semantics_custom_action_updates_.clear();
111
112 std::string error = tree_->error();
113 if (!error.empty()) {
114 FML_LOG(ERROR) << "Failed to update ui::AXTree, error: " << error;
115 return;
116 }
117 // Handles accessibility events as the result of the semantics update.
118 for (const auto& targeted_event : event_generator_) {
119 auto event_target =
120 GetFlutterPlatformNodeDelegateFromID(targeted_event.node->id());
121 if (event_target.expired()) {
122 continue;
123 }
124
125 OnAccessibilityEvent(targeted_event);
126 }
127 event_generator_.ClearEvents();
128 }

References GetFlutterPlatformNodeDelegateFromID(), GetRootAsAXNode(), and OnAccessibilityEvent().

## ◆ CreateFlutterPlatformNodeDelegate()

virtual std::shared_ptr<FlutterPlatformNodeDelegate> flutter::AccessibilityBridge::CreateFlutterPlatformNodeDelegate | ( |  | ) |
| protected pure virtual

Creates a platform specific FlutterPlatformNodeDelegate. Ownership passes to the caller. This method will be called whenever a new AXNode is created in AXTree. Each platform needs to implement this method in order to inject its subclass into the accessibility bridge.

Implemented in flutter::AccessibilityBridgeMac, and flutter::TestAccessibilityBridge.

## ◆ GetAXTreeData()

const ui::AXTreeData & flutter::AccessibilityBridge::GetAXTreeData | ( |  | ) | const

Get the ax tree data from this accessibility bridge. The tree data contains information such as the id of the node that has the keyboard focus or the text selection range.

Definition at line 141 of file accessibility_bridge.cc.

141 {
142 return tree_->data();
143 }

## ◆ GetFlutterPlatformNodeDelegateFromID()

std::weak_ptr< FlutterPlatformNodeDelegate > flutter::AccessibilityBridge::GetFlutterPlatformNodeDelegateFromID | ( | AccessibilityNodeId | id | ) | const

Get the flutter platform node delegate with the given id from this accessibility bridge. Returns expired weak_ptr if the delegate associated with the id does not exist or has been removed from the accessibility tree.

Parameters

  [in] | id | The id of the flutter accessibility node you want to retrieve.

Definition at line 131 of file accessibility_bridge.cc.

132 {
133 const auto iter = id_wrapper_map_.find(id);
134 if (iter != id_wrapper_map_.end()) {
135 return iter->second;
136 }
137
138 return std::weak_ptr<FlutterPlatformNodeDelegate>();
139 }

Referenced by CommitUpdates(), GetPlatformNodeFromTree(), and RootDelegate().

## ◆ GetNodeFromTree() [1/2]

ui::AXNode * flutter::AccessibilityBridge::GetNodeFromTree | ( | const ui::AXNode::AXID | node_id | ) | const
| override

Definition at line 681 of file accessibility_bridge.cc.

682 {
683 return tree_->GetFromId(node_id);
684 }

## ◆ GetNodeFromTree() [2/2]

ui::AXNode * flutter::AccessibilityBridge::GetNodeFromTree | ( | const ui::AXTreeID | tree_id,
|  | const ui::AXNode::AXID | node_id
| ) |  | const
| override

Definition at line 675 of file accessibility_bridge.cc.

677 {
678 return GetNodeFromTree(node_id);
679 }

## ◆ GetParentNodeFromParentTreeAsAXNode()

ui::AXNode * flutter::AccessibilityBridge::GetParentNodeFromParentTreeAsAXNode | ( |  | ) | const
| override

Definition at line 698 of file accessibility_bridge.cc.

698 {
699 return nullptr;
700 }

## ◆ GetParentTreeID()

ui::AXTreeID flutter::AccessibilityBridge::GetParentTreeID | ( |  | ) | const
| override

Definition at line 690 of file accessibility_bridge.cc.

690 {
691 return ui::AXTreeIDUnknown();
692 }

## ◆ GetPendingEvents()

const std::vector< ui::AXEventGenerator::TargetedEvent > flutter::AccessibilityBridge::GetPendingEvents | ( |  | ) | const

Gets all pending accessibility events generated during semantics updates. This is useful when deciding how to handle events in AccessibilityBridgeDelegate::OnAccessibilityEvent in case one may decide to handle an event differently based on all pending events.

Definition at line 146 of file accessibility_bridge.cc.

146 {
147 std::vector<ui::AXEventGenerator::TargetedEvent> result(
148 event_generator_.begin(), event_generator_.end());
149 return result;
150 }

## ◆ GetPlatformNodeFromTree() [1/2]

ui::AXPlatformNode * flutter::AccessibilityBridge::GetPlatformNodeFromTree | ( | const ui::AXNode & | node | ) | const
| override

Definition at line 716 of file accessibility_bridge.cc.

717 {
718 return GetPlatformNodeFromTree(node.id());
719 }

References GetPlatformNodeFromTree().

## ◆ GetPlatformNodeFromTree() [2/2]

ui::AXPlatformNode * flutter::AccessibilityBridge::GetPlatformNodeFromTree | ( | const ui::AXNode::AXID | node_id | ) | const
| override

Definition at line 706 of file accessibility_bridge.cc.

707 {
708 auto platform_delegate_weak = GetFlutterPlatformNodeDelegateFromID(node_id);
709 auto platform_delegate = platform_delegate_weak.lock();
710 if (!platform_delegate) {
711 return nullptr;
712 }
713 return platform_delegate->GetPlatformNode();
714 }

References GetFlutterPlatformNodeDelegateFromID().

Referenced by flutter::FlutterPlatformNodeDelegate::GetFromNodeID(), flutter::FlutterPlatformNodeDelegate::GetFromTreeIDAndNodeID(), and GetPlatformNodeFromTree().

## ◆ GetRootAsAXNode()

ui::AXNode * flutter::AccessibilityBridge::GetRootAsAXNode | ( |  | ) | const
| override

Definition at line 694 of file accessibility_bridge.cc.

694 {
695 return tree_->root();
696 }

Referenced by CommitUpdates(), and RootDelegate().

## ◆ GetTree()

ui::AXTree * flutter::AccessibilityBridge::GetTree | ( |  | ) | const
| override

Definition at line 702 of file accessibility_bridge.cc.

702 {
703 return tree_.get();
704 }

## ◆ GetTreeID()

ui::AXTreeID flutter::AccessibilityBridge::GetTreeID | ( |  | ) | const
| override

Definition at line 686 of file accessibility_bridge.cc.

686 {
687 return tree_->GetAXTreeID();
688 }

## ◆ OnAccessibilityEvent()

virtual void flutter::AccessibilityBridge::OnAccessibilityEvent | ( | ui::AXEventGenerator::TargetedEvent | targeted_event | ) |
| protected pure virtual

Handle accessibility events generated due to accessibility tree changes. These events are needed to be sent to native accessibility system. See ui::AXEventGenerator::Event for possible events.

Parameters

  [in] | targeted_event | The object that contains both the generated event and the event target.

Implemented in flutter::AccessibilityBridgeMac, and flutter::TestAccessibilityBridge.

Referenced by CommitUpdates().

## ◆ RootDelegate()

ui::AXPlatformNodeDelegate * flutter::AccessibilityBridge::RootDelegate | ( |  | ) | const
| override

Definition at line 721 of file accessibility_bridge.cc.

721 {
722 return GetFlutterPlatformNodeDelegateFromID(GetRootAsAXNode()->id())
723 .lock()
724 .get();
725 }

References GetFlutterPlatformNodeDelegateFromID(), and GetRootAsAXNode().

The documentation for this class was generated from the following files:

- shell/platform/common/accessibility_bridge.h
- shell/platform/common/accessibility_bridge.cc

flutter::AccessibilityBridge::OnAccessibilityEvent
virtual void OnAccessibilityEvent(ui::AXEventGenerator::TargetedEvent targeted_event)=0
Handle accessibility events generated due to accessibility tree changes. These events are needed to b...
flutter::AccessibilityBridge::GetPlatformNodeFromTree
ui::AXPlatformNode * GetPlatformNodeFromTree(const ui::AXNode::AXID node_id) const override
Definition: accessibility_bridge.cc:706
flutter::AccessibilityBridge::GetRootAsAXNode
ui::AXNode * GetRootAsAXNode() const override
Definition: accessibility_bridge.cc:694
flutter::AccessibilityBridge::GetFlutterPlatformNodeDelegateFromID
std::weak_ptr< FlutterPlatformNodeDelegate > GetFlutterPlatformNodeDelegateFromID(AccessibilityNodeId id) const
Get the flutter platform node delegate with the given id from this accessibility bridge....
Definition: accessibility_bridge.cc:131
flutter::AccessibilityBridge::GetNodeFromTree
ui::AXNode * GetNodeFromTree(const ui::AXTreeID tree_id, const ui::AXNode::AXID node_id) const override
Definition: accessibility_bridge.cc:675