ax_tree_observer.h 7.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175
  1. // Copyright 2018 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_OBSERVER_H_
  5. #define UI_ACCESSIBILITY_AX_TREE_OBSERVER_H_
  6. #include "base/observer_list_types.h"
  7. #include "ui/accessibility/ax_enums.mojom-forward.h"
  8. #include "ui/accessibility/ax_export.h"
  9. #include "ui/accessibility/ax_node_data.h"
  10. #include "ui/accessibility/ax_tree_id.h"
  11. namespace ui {
  12. class AXNode;
  13. class AXTree;
  14. struct AXTreeData;
  15. // Used when you want to be notified when changes happen to an AXTree.
  16. //
  17. // |OnAtomicUpdateFinished| is notified at the end of an atomic update.
  18. // It provides a vector of nodes that were added or changed, for final
  19. // postprocessing.
  20. class AX_EXPORT AXTreeObserver : public base::CheckedObserver {
  21. public:
  22. AXTreeObserver();
  23. ~AXTreeObserver() override;
  24. // Called before any tree modifications have occurred, notifying that a single
  25. // node will change its ignored state or its data. Its id and data will be
  26. // valid, but its links to parents and children are only valid within this
  27. // callstack. Do not hold a reference to the node or any relative nodes such
  28. // as ancestors or descendants described by the node or its node data outside
  29. // of these events.
  30. virtual void OnIgnoredWillChange(AXTree* tree,
  31. AXNode* node,
  32. bool is_ignored_new_value) {}
  33. virtual void OnNodeDataWillChange(AXTree* tree,
  34. const AXNodeData& old_node_data,
  35. const AXNodeData& new_node_data) {}
  36. // Called after all tree modifications have occurred, notifying that a single
  37. // node has changed its data. Its id, data, and links to parent and children
  38. // will all be valid, since the tree is in a stable state after updating.
  39. virtual void OnNodeDataChanged(AXTree* tree,
  40. const AXNodeData& old_node_data,
  41. const AXNodeData& new_node_data) {}
  42. // Individual callbacks for every attribute of AXNodeData that can change.
  43. // Called after all tree mutations have occurred, notifying that a single node
  44. // changed its data. Its id, data, and links to parent and children will all
  45. // be valid, since the tree is in a stable state after updating.
  46. virtual void OnRoleChanged(AXTree* tree,
  47. AXNode* node,
  48. ax::mojom::Role old_role,
  49. ax::mojom::Role new_role) {}
  50. virtual void OnIgnoredChanged(AXTree* tree,
  51. AXNode* node,
  52. bool is_ignored_new_value) {}
  53. virtual void OnStateChanged(AXTree* tree,
  54. AXNode* node,
  55. ax::mojom::State state,
  56. bool new_value) {}
  57. virtual void OnStringAttributeChanged(AXTree* tree,
  58. AXNode* node,
  59. ax::mojom::StringAttribute attr,
  60. const std::string& old_value,
  61. const std::string& new_value) {}
  62. virtual void OnIntAttributeChanged(AXTree* tree,
  63. AXNode* node,
  64. ax::mojom::IntAttribute attr,
  65. int32_t old_value,
  66. int32_t new_value) {}
  67. virtual void OnFloatAttributeChanged(AXTree* tree,
  68. AXNode* node,
  69. ax::mojom::FloatAttribute attr,
  70. float old_value,
  71. float new_value) {}
  72. virtual void OnBoolAttributeChanged(AXTree* tree,
  73. AXNode* node,
  74. ax::mojom::BoolAttribute attr,
  75. bool new_value) {}
  76. virtual void OnIntListAttributeChanged(
  77. AXTree* tree,
  78. AXNode* node,
  79. ax::mojom::IntListAttribute attr,
  80. const std::vector<int32_t>& old_value,
  81. const std::vector<int32_t>& new_value) {}
  82. virtual void OnStringListAttributeChanged(
  83. AXTree* tree,
  84. AXNode* node,
  85. ax::mojom::StringListAttribute attr,
  86. const std::vector<std::string>& old_value,
  87. const std::vector<std::string>& new_value) {}
  88. // Called when tree data changes, after all nodes have been updated.
  89. virtual void OnTreeDataChanged(AXTree* tree,
  90. const AXTreeData& old_data,
  91. const AXTreeData& new_data) {}
  92. // Called before any tree modifications have occurred, notifying that a single
  93. // node will be deleted. Its id and data will be valid, but its links to
  94. // parents and children are only valid within this callstack. Do not hold
  95. // a reference to node outside of the event.
  96. virtual void OnNodeWillBeDeleted(AXTree* tree, AXNode* node) {}
  97. // Same as OnNodeWillBeDeleted, but only called once for an entire subtree.
  98. virtual void OnSubtreeWillBeDeleted(AXTree* tree, AXNode* node) {}
  99. // Called just before a node is deleted for reparenting. See
  100. // |OnNodeWillBeDeleted| for additional information.
  101. virtual void OnNodeWillBeReparented(AXTree* tree, AXNode* node) {}
  102. // Called just before a subtree is deleted for reparenting. See
  103. // |OnSubtreeWillBeDeleted| for additional information.
  104. virtual void OnSubtreeWillBeReparented(AXTree* tree, AXNode* node) {}
  105. // Called after all tree mutations have occurred, notifying that a single node
  106. // has been created. Its id, data, and links to parent and children will all
  107. // be valid, since the tree is in a stable state after updating.
  108. virtual void OnNodeCreated(AXTree* tree, AXNode* node) {}
  109. // Called after all tree mutations have occurred or during tree teardown,
  110. // notifying that a single node has been deleted from the tree.
  111. virtual void OnNodeDeleted(AXTree* tree, AXNodeID node_id) {}
  112. // Same as |OnNodeCreated|, but called for nodes that have been reparented.
  113. virtual void OnNodeReparented(AXTree* tree, AXNode* node) {}
  114. // Called after all tree mutations have occurred, notifying that a single node
  115. // has updated its data or children. Its id, data, and links to parent and
  116. // children will all be valid, since the tree is in a stable state after
  117. // updating.
  118. virtual void OnNodeChanged(AXTree* tree, AXNode* node) {}
  119. // Called just before a tree manager is removed from the AXTreeManagerMap.
  120. //
  121. // Why is this needed?
  122. // In some cases, we update the tree id of an AXTree and need to update the
  123. // map entry that corresponds to that tree. The observers maintained in the
  124. // observers list of that AXTree might need to be notified of that change to
  125. // remove themselves from the list, if needed.
  126. virtual void OnTreeManagerWillBeRemoved(AXTreeID previous_tree_id) {}
  127. enum ChangeType {
  128. NODE_CREATED,
  129. SUBTREE_CREATED,
  130. NODE_CHANGED,
  131. NODE_REPARENTED,
  132. SUBTREE_REPARENTED
  133. };
  134. struct Change {
  135. Change(AXNode* node, ChangeType type) {
  136. this->node = node;
  137. this->type = type;
  138. }
  139. AXNode* node;
  140. ChangeType type;
  141. };
  142. // Called at the end of the update operation. Every node that was added
  143. // or changed will be included in |changes|, along with an enum indicating
  144. // the type of change - either (1) a node was created, (2) a node was created
  145. // and it's the root of a new subtree, or (3) a node was changed. Finally,
  146. // a bool indicates if the root of the tree was changed or not.
  147. virtual void OnAtomicUpdateFinished(AXTree* tree,
  148. bool root_changed,
  149. const std::vector<Change>& changes) {}
  150. };
  151. } // namespace ui
  152. #endif // UI_ACCESSIBILITY_AX_TREE_OBSERVER_H_