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.h" 13 #include "ui/accessibility/ax_tree_update.h" 14 15 namespace ui { 16 17 class AXNode; 18 19 // AXTree is a live, managed tree of AXNode objects that can receive 20 // updates from another AXTreeSource via AXTreeUpdates, and it can be 21 // used as a source for sending updates to another client tree. 22 // It's designed to be subclassed to implement support for native 23 // accessibility APIs on a specific platform. 24 class AX_EXPORT AXTree { 25 public: 26 AXTree(); 27 explicit AXTree(const AXTreeUpdate& initial_state); 28 virtual ~AXTree(); 29 30 virtual AXNode* GetRoot() const; 31 virtual AXNode* GetFromId(int32 id) const; 32 33 // Returns true on success. If it returns false, it's a fatal error 34 // and this tree should be destroyed, and the source of the tree update 35 // should not be trusted any longer. 36 virtual bool Unserialize(const AXTreeUpdate& update); 37 38 // A string describing the error from an unsuccessful Unserialize, 39 // for testing and debugging. error()40 const std::string& error() { return error_; } 41 42 protected: 43 // Subclasses can override this to use a subclass of AXNode. 44 virtual AXNode* CreateNode(AXNode* parent, int32 id, int32 index_in_parent); 45 46 // This is called from within Unserialize(), it returns true on success. 47 // Subclasses can override this to do additional processing. |pending_nodes| 48 // is updated to contain all nodes that have been implicitly referenced 49 // as part of this update, but haven't been updated yet. It's an error if 50 // there are any pending nodes at the end of Unserialize. 51 virtual bool UpdateNode(const AXNodeData& src, 52 std::set<AXNode*>* pending_nodes); 53 54 // Subclasses can override this to do special behavior when the root changes. 55 virtual void OnRootChanged(); 56 57 private: 58 // Convenience function to create a node and call Initialize on it. 59 AXNode* CreateAndInitializeNode( 60 AXNode* parent, int32 id, int32 index_in_parent); 61 62 // Call Destroy() on |node|, and delete it from the id map, and then 63 // call recursively on all nodes in its subtree. 64 void DestroyNodeAndSubtree(AXNode* node); 65 66 // Iterate over the children of |node| and for each child, destroy the 67 // child and its subtree if its id is not in |new_child_ids|. Returns 68 // true on success, false on fatal error. 69 bool DeleteOldChildren(AXNode* node, 70 const std::vector<int32> new_child_ids); 71 72 // Iterate over |new_child_ids| and populate |new_children| with 73 // pointers to child nodes, reusing existing nodes already in the tree 74 // if they exist, and creating otherwise. Reparenting is disallowed, so 75 // if the id already exists as the child of another node, that's an 76 // error. Returns true on success, false on fatal error. See 77 // UpdateNode, above, for an explanation of |pending_nodes|. 78 bool CreateNewChildVector(AXNode* node, 79 const std::vector<int32> new_child_ids, 80 std::vector<AXNode*>* new_children, 81 std::set<AXNode*>* pending_nodes); 82 83 AXNode* root_; 84 base::hash_map<int32, AXNode*> id_map_; 85 std::string error_; 86 }; 87 88 } // namespace ui 89 90 #endif // UI_ACCESSIBILITY_AX_TREE_H_ 91