ax_tree_manager_base.h 5.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133
  1. // Copyright 2022 The Chromium Authors. All rights reserved.
  2. // Use of this source code is governed by a BSD-style license that can be
  3. // found in the LICENSE file.
  4. #ifndef UI_ACCESSIBILITY_AX_TREE_MANAGER_BASE_H_
  5. #define UI_ACCESSIBILITY_AX_TREE_MANAGER_BASE_H_
  6. #include <memory>
  7. #include "base/containers/flat_map.h"
  8. #include "third_party/abseil-cpp/absl/types/optional.h"
  9. #include "ui/accessibility/ax_export.h"
  10. #include "ui/accessibility/ax_node_data.h"
  11. #include "ui/accessibility/ax_tree.h"
  12. #include "ui/accessibility/ax_tree_data.h"
  13. #include "ui/accessibility/ax_tree_id.h"
  14. #include "ui/accessibility/ax_tree_update.h"
  15. namespace ui {
  16. class AXNode;
  17. // A class that owns an accessibility tree and manages its connections to other
  18. // accessibility trees. Each accessibility tree could be connected to one parent
  19. // tree and multiple child trees, the whole collection essentially being a
  20. // forest of trees representing user interface elements. Each tree is typically
  21. // backed by a rendering surface.
  22. //
  23. // This class is movable but not copyable.
  24. class AX_EXPORT AXTreeManagerBase final {
  25. public:
  26. // Returns the manager of the tree with the given ID, if any.
  27. static AXTreeManagerBase* GetManager(const AXTreeID& tree_id);
  28. // Returns the node identified by the given `tree_id` and `node_id`. This
  29. // allows for callers to access nodes outside of their own tree.
  30. static AXNode* GetNodeFromTree(const AXTreeID& tree_id,
  31. const AXNodeID& node_id);
  32. // This default constructor does not create an empty accessibility tree. Call
  33. // `SetTree` if you need to manage a specific tree.
  34. AXTreeManagerBase();
  35. explicit AXTreeManagerBase(std::unique_ptr<AXTree> tree);
  36. explicit AXTreeManagerBase(const AXTreeUpdate& initial_state);
  37. virtual ~AXTreeManagerBase();
  38. AXTreeManagerBase(const AXTreeManagerBase&) = delete;
  39. AXTreeManagerBase& operator=(const AXTreeManagerBase&) = delete;
  40. AXTreeManagerBase(AXTreeManagerBase&& manager);
  41. AXTreeManagerBase& operator=(AXTreeManagerBase&& manager);
  42. // Returns a pointer to the managed tree, if any.
  43. AXTree* GetTree() const;
  44. // Takes ownership of a new accessibility tree and returns the one that is
  45. // currently being managed. It is considered an error to pass an empty
  46. // unique_ptr for `tree`. If no tree is currently being managed, returns an
  47. // empty unique_ptr.
  48. std::unique_ptr<AXTree> SetTree(std::unique_ptr<AXTree> tree);
  49. std::unique_ptr<AXTree> SetTree(const AXTreeUpdate& initial_state);
  50. // Detaches the managed tree, if any.
  51. std::unique_ptr<AXTree> ReleaseTree();
  52. // Returns a snapshot of the managed tree by serializing it into an
  53. // `AXTreeUpdate`.
  54. AXTreeUpdate SnapshotTree() const;
  55. // Tries to update the managed tree by unserializing and applying the provided
  56. // `update`. Returns a boolean value indicating success or failure.
  57. bool ApplyTreeUpdate(const AXTreeUpdate& update);
  58. // Returns the ID of the managed tree.
  59. //
  60. // Note that tree IDs are expensive to copy, hence the use of a const
  61. // reference.
  62. const AXTreeID& GetTreeID() const;
  63. // Returns the ID of the parent tree.
  64. //
  65. // Note that tree IDs are expensive to copy, hence the use of a const
  66. // reference.
  67. const AXTreeID& GetParentTreeID() const;
  68. // Returns the managed tree's data.
  69. const AXTreeData& GetTreeData() const;
  70. // Returns the node identified with the given `node_id).
  71. AXNode* GetNode(const AXNodeID& node_id) const;
  72. // Returns the rootnode of the managed tree. The rootnode could be nullptr
  73. // during some `AXTreeObserver` callbacks.
  74. AXNode* GetRoot() const;
  75. // Returns the rootnode of the child tree hosted at `host_node_id`. The
  76. // rootnode could be nullptr during some `AXTreeObserver` callbacks.
  77. AXNode* GetRootOfChildTree(const AXNodeID& host_node_id) const;
  78. AXNode* GetRootOfChildTree(const AXNode& host_node) const;
  79. // If this tree has a parent tree, returns the node in the parent tree that
  80. // is hosting the current tree.
  81. AXNode* GetHostNode() const;
  82. // Attaches the given child tree to the given host node. Returns a boolean
  83. // indicating success or failure.
  84. bool AttachChildTree(const AXNodeID& host_node_id,
  85. AXTreeManagerBase& child_manager);
  86. bool AttachChildTree(AXNode& host_node, AXTreeManagerBase& child_manager);
  87. // Creates a child tree based on `initial_state` and attaches it to the given
  88. // host node. Returns the child tree's manager if successful.
  89. absl::optional<AXTreeManagerBase> AttachChildTree(
  90. const AXNodeID& host_node_id,
  91. const AXTreeUpdate& initial_state);
  92. absl::optional<AXTreeManagerBase> AttachChildTree(
  93. AXNode& host_node,
  94. const AXTreeUpdate& initial_state);
  95. // Detaches the child tree hosted by the given host node, returning a pointer
  96. // to its manager.
  97. AXTreeManagerBase* DetachChildTree(const AXNodeID& host_node_id);
  98. AXTreeManagerBase* DetachChildTree(AXNode& host_node);
  99. private:
  100. static base::flat_map<AXTreeID, AXTreeManagerBase*>&
  101. GetTreeManagerMapInstance();
  102. std::unique_ptr<AXTree> tree_;
  103. };
  104. } // namespace ui
  105. #endif // UI_ACCESSIBILITY_AX_TREE_MANAGER_BASE_H_