1 // Copyright 2013 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 5 #ifndef UI_ACCESSIBILITY_AX_TREE_H_ 6 #define UI_ACCESSIBILITY_AX_TREE_H_ 7 8 #include <set> 9 10 #include "base/containers/hash_tables.h" 11 #include "ui/accessibility/ax_export.h" 12 #include "ui/accessibility/ax_tree_update.h" 13 14 namespace ui { 15 16 class AXNode; 17 struct AXTreeUpdateState; 18 19 // Used when you want to be notified when changes happen to the tree. 20 // 21 // Some of the notifications are called in the middle of an update operation. 22 // Be careful, as the tree may be in an inconsistent state at this time; 23 // don't walk the parents and children at this time: 24 // OnNodeWillBeDeleted 25 // OnNodeCreated 26 // OnNodeChanged 27 // 28 // Other notifications are called at the end of an atomic update operation. 29 // From these, it's safe to walk the tree and do any initialization that 30 // assumes the tree is in a consistent state. 31 // OnNodeCreationFinished 32 // OnNodeChangeFinished 33 // OnRootChanged 34 class AX_EXPORT AXTreeDelegate { 35 public: 36 AXTreeDelegate(); 37 virtual ~AXTreeDelegate(); 38 39 // Called just before a node is deleted. Its id and data will be valid, 40 // but its links to parents and children are invalid. This is called 41 // in the middle of an update, the tree may be in an invalid state! 42 virtual void OnNodeWillBeDeleted(AXNode* node) = 0; 43 44 // Called immediately after a new node is created. The tree may be in 45 // the middle of an update, don't walk the parents and children now. 46 virtual void OnNodeCreated(AXNode* node) = 0; 47 48 // Called when a node changes its data or children. The tree may be in 49 // the middle of an update, don't walk the parents and children now. 50 virtual void OnNodeChanged(AXNode* node) = 0; 51 52 // Called for each new node at the end of an update operation, 53 // when the tree is in a consistent state. 54 virtual void OnNodeCreationFinished(AXNode* node) = 0; 55 56 // Called for each existing node that changed at the end of an update 57 // operation, when the tree is in a consistent state. 58 virtual void OnNodeChangeFinished(AXNode* node) = 0; 59 60 // Called at the end of an update operation when the root node changes. 61 virtual void OnRootChanged(AXNode* new_root) = 0; 62 }; 63 64 // AXTree is a live, managed tree of AXNode objects that can receive 65 // updates from another AXTreeSource via AXTreeUpdates, and it can be 66 // used as a source for sending updates to another client tree. 67 // It's designed to be subclassed to implement support for native 68 // accessibility APIs on a specific platform. 69 class AX_EXPORT AXTree { 70 public: 71 AXTree(); 72 explicit AXTree(const AXTreeUpdate& initial_state); 73 virtual ~AXTree(); 74 75 virtual void SetDelegate(AXTreeDelegate* delegate); 76 77 virtual AXNode* GetRoot() const; 78 virtual AXNode* GetFromId(int32 id) const; 79 80 // Returns true on success. If it returns false, it's a fatal error 81 // and this tree should be destroyed, and the source of the tree update 82 // should not be trusted any longer. 83 virtual bool Unserialize(const AXTreeUpdate& update); 84 85 // Return a multi-line indented string representation, for logging. 86 std::string ToString() const; 87 88 // A string describing the error from an unsuccessful Unserialize, 89 // for testing and debugging. error()90 const std::string& error() { return error_; } 91 92 private: 93 AXNode* CreateNode(AXNode* parent, int32 id, int32 index_in_parent); 94 95 // This is called from within Unserialize(), it returns true on success. 96 bool UpdateNode(const AXNodeData& src, AXTreeUpdateState* update_state); 97 98 void OnRootChanged(); 99 100 // Call Destroy() on |node|, and delete it from the id map, and then 101 // call recursively on all nodes in its subtree. 102 void DestroyNodeAndSubtree(AXNode* node); 103 104 // Iterate over the children of |node| and for each child, destroy the 105 // child and its subtree if its id is not in |new_child_ids|. Returns 106 // true on success, false on fatal error. 107 bool DeleteOldChildren(AXNode* node, 108 const std::vector<int32> new_child_ids); 109 110 // Iterate over |new_child_ids| and populate |new_children| with 111 // pointers to child nodes, reusing existing nodes already in the tree 112 // if they exist, and creating otherwise. Reparenting is disallowed, so 113 // if the id already exists as the child of another node, that's an 114 // error. Returns true on success, false on fatal error. 115 bool CreateNewChildVector(AXNode* node, 116 const std::vector<int32> new_child_ids, 117 std::vector<AXNode*>* new_children, 118 AXTreeUpdateState* update_state); 119 120 AXTreeDelegate* delegate_; 121 AXNode* root_; 122 base::hash_map<int32, AXNode*> id_map_; 123 std::string error_; 124 }; 125 126 } // namespace ui 127 128 #endif // UI_ACCESSIBILITY_AX_TREE_H_ 129