Improve the notifications sent from AXTree updates.

ui/accessibility/ax_tree.h

 // Copyright 2013 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef UI_ACCESSIBILITY_AX_TREE_H_
 #define UI_ACCESSIBILITY_AX_TREE_H_
 
 #include <set>
 
 #include "base/containers/hash_tables.h"
 #include "ui/accessibility/ax_export.h"
 #include "ui/accessibility/ax_tree_update.h"
 
 namespace ui {
 
 class AXNode;
 struct AXTreeUpdateState;
 
 // Used when you want to be notified when changes happen to the tree.
 //
 // Some of the notifications are called in the middle of an update operation.
 // Be careful, as the tree may be in an inconsistent state at this time;
 // don't walk the parents and children at this time:

[David Tseng, 2015/01/23 17:25:39]

At least for |OnSubtreeWillBeDeleted|, it appears to be safe to walk parents and
children.

[dmazzoni, 2015/01/23 23:00:17]

Technically you're right that the parents and children will be valid, but the
parent might have pointers to other children that are invalid. My preference is
to make this statement simpler and more strict, rather than allowing code to
depend on it being safe to walk the tree.

If we end up needing code to walk the tree when there's a node to be deleted, we
should probably refactor the code and create a separate callback for that.

 //   OnNodeWillBeDeleted
+//   OnSubtreeWillBeDeleted
 //   OnNodeCreated
 //   OnNodeChanged
 //
-// Other notifications are called at the end of an atomic update operation.
-// From these, it's safe to walk the tree and do any initialization that
-// assumes the tree is in a consistent state.
-//   OnNodeCreationFinished
-//   OnNodeChangeFinished
-//   OnRootChanged
+// In addition, one additional notification is fired at the end of an
+// atomic update, and it provides a vector of nodes that were added or
+// changed, for final postprocessing.

[David Tseng, 2015/01/23 17:25:39]

Do you mean |OnAtomicUpdateFinished|?

[dmazzoni, 2015/01/23 23:00:17]

Oops, yes - I meant to include that in the comment. Done.

 class AX_EXPORT AXTreeDelegate {
  public:
   AXTreeDelegate();
   virtual ~AXTreeDelegate();
 
   // Called just before a node is deleted. Its id and data will be valid,
   // but its links to parents and children are invalid. This is called
   // in the middle of an update, the tree may be in an invalid state!
   virtual void OnNodeWillBeDeleted(AXNode* node) = 0;
 
+  // Same as OnNodeWillBeDeleted, but only called once for an entire subtree.
+  // This is called in the middle of an update, the tree may be in an
+  // invalid state!
+  virtual void OnSubtreeWillBeDeleted(AXNode* node) = 0;
+
   // Called immediately after a new node is created. The tree may be in
   // the middle of an update, don't walk the parents and children now.
   virtual void OnNodeCreated(AXNode* node) = 0;
 
   // Called when a node changes its data or children. The tree may be in
   // the middle of an update, don't walk the parents and children now.
   virtual void OnNodeChanged(AXNode* node) = 0;
 
-  // Called for each new node at the end of an update operation,
-  // when the tree is in a consistent state.
-  virtual void OnNodeCreationFinished(AXNode* node) = 0;
+  enum ChangeType {
+    NODE_CREATED,
+    SUBTREE_CREATED,
+    NODE_CHANGED
+  };
 
-  // Called for each existing node that changed at the end of an update
-  // operation, when the tree is in a consistent state.
-  virtual void OnNodeChangeFinished(AXNode* node) = 0;
+  struct Change {
+    Change(AXNode* node, ChangeType type) {
+      this->node = node;
+      this->type = type;
+    }
+    AXNode *node;
+    ChangeType type;
+  };
 
-  // Called at the end of an update operation when the root node changes.
-  virtual void OnRootChanged(AXNode* new_root) = 0;
+  // Called at the end of the update operation. Every node that was added
+  // or changed will be included in |changes|, along with an enum indicating
+  // the type of change - either (1) a node was created, (2) a node was created
+  // and it's the root of a new subtree, or (3) a node was changed. Finally,
+  // a bool indicates if the root of the tree was changed or not.
+  virtual void OnAtomicUpdateFinished(bool root_changed,
+                                      const std::vector<Change>& changes) = 0;
 };
 
 // AXTree is a live, managed tree of AXNode objects that can receive
 // updates from another AXTreeSource via AXTreeUpdates, and it can be
 // used as a source for sending updates to another client tree.
 // It's designed to be subclassed to implement support for native
 // accessibility APIs on a specific platform.
 class AX_EXPORT AXTree {
  public:
   AXTree();
@@ skipping 18 matching lines @@
   const std::string& error() { return error_; }
 
  private:
   AXNode* CreateNode(AXNode* parent, int32 id, int32 index_in_parent);
 
   // This is called from within Unserialize(), it returns true on success.
   bool UpdateNode(const AXNodeData& src, AXTreeUpdateState* update_state);
 
   void OnRootChanged();
 
+  // Notify the delegate that the subtree rooted at |node| will be destroyed,
+  // then call DestroyNodeAndSubtree on it.
+  void DestroySubtree(AXNode* node);

[David Tseng, 2015/01/23 17:25:39]

Maybe call this NotifySubtreeWillBeDeleted?

[dmazzoni, 2015/01/23 23:00:17]

It notifies and destroys

+
   // Call Destroy() on |node|, and delete it from the id map, and then
   // call recursively on all nodes in its subtree.
   void DestroyNodeAndSubtree(AXNode* node);
 
   // Iterate over the children of |node| and for each child, destroy the
   // child and its subtree if its id is not in |new_child_ids|. Returns
   // true on success, false on fatal error.
   bool DeleteOldChildren(AXNode* node,
                          const std::vector<int32> new_child_ids);
 
   // Iterate over |new_child_ids| and populate |new_children| with
   // pointers to child nodes, reusing existing nodes already in the tree
   // if they exist, and creating otherwise. Reparenting is disallowed, so
   // if the id already exists as the child of another node, that's an
   // error. Returns true on success, false on fatal error.
   bool CreateNewChildVector(AXNode* node,
                             const std::vector<int32> new_child_ids,
                             std::vector<AXNode*>* new_children,
                             AXTreeUpdateState* update_state);
 
   AXTreeDelegate* delegate_;
   AXNode* root_;
   base::hash_map<int32, AXNode*> id_map_;
   std::string error_;
 };
 
 }  // namespace ui
 
 #endif  // UI_ACCESSIBILITY_AX_TREE_H_