ui/accessibility/ax_tree.h

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