flutter::AccessibilityBridge Class Reference

#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.

    : tree_(std::make_unique<ui::AXTree>()) {
  event_generator_.SetTree(tree_.get());
  tree_->AddObserver(static_cast<ui::AXTreeObserver*>(this));
  ui::AXTreeData data = tree_->data();
  data.tree_id = ui::AXTreeID::CreateNewAXTreeID();
  tree_->UpdateData(data);
  ui::AXTreeManagerMap::GetInstance().AddTreeManager(tree_->GetAXTreeID(),
                                                     this);
}

~AccessibilityBridge()

flutter::AccessibilityBridge::~AccessibilityBridge ( )

virtual

Definition at line 34 of file accessibility_bridge.cc.

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

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.

                                                 {
  pending_semantics_custom_action_updates_[action.id] =
      FromFlutterSemanticsCustomAction(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]

node

A reference to the semantics node update.

Definition at line 39 of file accessibility_bridge.cc.

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

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.

                                        {
  // AXTree cannot move a node in a single update.
  // This must be split across two updates:
  //
  // * Update 1: remove nodes from their old parents.
  // * Update 2: re-add nodes (including their children) to their new parents.
  //
  // First, start by removing nodes if necessary.
  std::optional<ui::AXTreeUpdate> remove_reparented =
      CreateRemoveReparentedNodesUpdate();
  if (remove_reparented.has_value()) {
    tree_->Unserialize(remove_reparented.value());
 
    std::string error = tree_->error();
    if (!error.empty()) {
      FML_LOG(ERROR) << "Failed to update ui::AXTree, error: " << error;
      assert(false);
      return;
    }
  }
 
  // Second, apply the pending node updates. This also moves reparented nodes to
  // their new parents if needed.
  ui::AXTreeUpdate update{.tree_data = tree_->data()};
 
  // Figure out update order, ui::AXTree only accepts update in tree order,
  // where parent node must come before the child node in
  // ui::AXTreeUpdate.nodes. We start with picking a random node and turn the
  // entire subtree into a list. We pick another node from the remaining update,
  // and keep doing so until the update map is empty. We then concatenate the
  // lists in the reversed order, this guarantees parent updates always come
  // before child updates. If the root is in the update, it is guaranteed to
  // be the first node of the last list.
  std::vector<std::vector<SemanticsNode>> results;
  while (!pending_semantics_node_updates_.empty()) {
    auto begin = pending_semantics_node_updates_.begin();
    SemanticsNode target = begin->second;
    std::vector<SemanticsNode> sub_tree_list;
    GetSubTreeList(target, sub_tree_list);
    results.push_back(sub_tree_list);
    pending_semantics_node_updates_.erase(begin);
  }
 
  for (size_t i = results.size(); i > 0; i--) {
    for (const SemanticsNode& node : results[i - 1]) {
      ConvertFlutterUpdate(node, update);
    }
  }
 
  // The first update must set the tree's root, which is guaranteed to be the
  // last list's first node. A tree's root node never changes, though it can be
  // modified.
  if (!results.empty() && GetRootAsAXNode()->id() == ui::AXNode::kInvalidAXID) {
    FML_DCHECK(!results.back().empty());
 
    update.root_id = results.back().front().id;
  }
 
  tree_->Unserialize(update);
  pending_semantics_node_updates_.clear();
  pending_semantics_custom_action_updates_.clear();
 
  std::string error = tree_->error();
  if (!error.empty()) {
    FML_LOG(ERROR) << "Failed to update ui::AXTree, error: " << error;
    return;
  }
  // Handles accessibility events as the result of the semantics update.
  for (const auto& targeted_event : event_generator_) {
    auto event_target =
        GetFlutterPlatformNodeDelegateFromID(targeted_event.node->id());
    if (event_target.expired()) {
      continue;
    }
 
    OnAccessibilityEvent(targeted_event);
  }
  event_generator_.ClearEvents();
}

References error, GetFlutterPlatformNodeDelegateFromID(), GetRootAsAXNode(), i, OnAccessibilityEvent(), and target.

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::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.

                                                             {
  return tree_->data();
}

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.

                                  {
  const auto iter = id_wrapper_map_.find(id);
  if (iter != id_wrapper_map_.end()) {
    return iter->second;
  }
 
  return std::weak_ptr<FlutterPlatformNodeDelegate>();
}

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 692 of file accessibility_bridge.cc.

                                {
  return tree_->GetFromId(node_id);
}

GetNodeFromTree() [2/2]

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

override

Definition at line 686 of file accessibility_bridge.cc.

                                {
  return GetNodeFromTree(node_id);
}

GetParentNodeFromParentTreeAsAXNode()

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

override

Definition at line 709 of file accessibility_bridge.cc.

                                                                         {
  return nullptr;
}

GetParentTreeID()

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

override

Definition at line 701 of file accessibility_bridge.cc.

                                                      {
  return ui::AXTreeIDUnknown();
}

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.

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

References result.

GetPlatformNodeFromTree() [1/2]

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

override

Definition at line 727 of file accessibility_bridge.cc.

                                {
  return GetPlatformNodeFromTree(node.id());
}

References GetPlatformNodeFromTree().

GetPlatformNodeFromTree() [2/2]

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

override

Definition at line 717 of file accessibility_bridge.cc.

                                      {
  auto platform_delegate_weak = GetFlutterPlatformNodeDelegateFromID(node_id);
  auto platform_delegate = platform_delegate_weak.lock();
  if (!platform_delegate) {
    return nullptr;
  }
  return platform_delegate->GetPlatformNode();
}

References GetFlutterPlatformNodeDelegateFromID().

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

GetRootAsAXNode()

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

override

Definition at line 705 of file accessibility_bridge.cc.

                                                     {
  return tree_->root();
}

Referenced by CommitUpdates(), and RootDelegate().

GetTree()

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

override

Definition at line 713 of file accessibility_bridge.cc.

                                             {
  return tree_.get();
}

GetTreeID()

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

override

Definition at line 697 of file accessibility_bridge.cc.

                                                {
  return tree_->GetAXTreeID();
}

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_event

The object that contains both the generated event and the event target.

Implemented in flutter::TestAccessibilityBridge.

Referenced by CommitUpdates().

RootDelegate()

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

override

Definition at line 732 of file accessibility_bridge.cc.

                                                                  {
  return GetFlutterPlatformNodeDelegateFromID(GetRootAsAXNode()->id())
      .lock()
      .get();
}

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