Flutter Windows Embedder
flutter::AccessibilityBridge Class Referenceabstract

#include <accessibility_bridge.h>

Inheritance diagram for flutter::AccessibilityBridge:
flutter::FlutterPlatformNodeDelegate::OwnerBridge flutter::AccessibilityBridgeWindows flutter::TestAccessibilityBridge

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< FlutterPlatformNodeDelegateGetFlutterPlatformNodeDelegateFromID (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< FlutterPlatformNodeDelegateCreateFlutterPlatformNodeDelegate ()=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]actionA 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 }

References action.

◆ 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]nodeA 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 ( )
protectedpure 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::AccessibilityBridgeWindows, 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 }

Referenced by flutter::AccessibilityBridgeWindows::GetFocusedNode().

◆ 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]idThe 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(), flutter::AccessibilityBridgeWindows::GetFocusedNode(), GetPlatformNodeFromTree(), flutter::AccessibilityBridgeWindows::OnAccessibilityEvent(), 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)
protectedpure 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_eventThe object that contains both the generated event and the event target.

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

Referenced by CommitUpdates().

◆ RootDelegate()

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

Definition at line 721 of file accessibility_bridge.cc.

721  {
723  .lock()
724  .get();
725 }

References GetFlutterPlatformNodeDelegateFromID(), and GetRootAsAXNode().

Referenced by flutter::AccessibilityBridgeWindows::GetChildOfAXFragmentRoot().


The documentation for this class was generated from the following files:
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
action
int action
Definition: keyboard_key_handler_unittests.cc:116