Complete live region support in ChromeVox Next.

chrome/common/extensions/api/automation.idl

 // Copyright 2014 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.
 
 // The <code>chrome.automation</code> API allows developers to access the
 // automation (accessibility) tree for the browser. The tree resembles the DOM
 // tree, but only exposes the <em>semantic</em> structure of a page. It can be
 // used to programmatically interact with a page by examining names, roles, and
 // states, listening for events, and performing actions on nodes.
 [nocompile] namespace automation {
@@ skipping 299 matching lines @@
 
   // A change to the Automation tree.
   [nocompile, noinline_doc] dictionary TreeChange {
     // The $(ref:automation.AutomationNode) that changed.
     AutomationNode target;
 
     // The type of change.
     TreeChangeType type;
   };
 
+  enum TreeChangeObserverMask {

[David Tseng, 2015/11/24 18:46:30]

This isn't really a mask since I don't think they're bit-wise orable?

[dmazzoni, 2015/11/30 22:00:46]

Changed to Filter.

+    noTreeChanges,
+    liveRegionTreeChanges,
+    allTreeChanges
+  };
+
   // A listener for changes on the <code>AutomationNode</code> tree.
   callback TreeChangeObserver = void(TreeChange treeChange);
 
   // A single node in an Automation tree.
   [nocompile, noinline_doc] dictionary AutomationNode {
     // The root node of the tree containing this AutomationNode.
     AutomationNode root;
 
     // Whether this AutomationNode is a root node.
     boolean isRootNode;
@@ skipping 234 matching lines @@
     // tab if no tabID is given, enabling automation if necessary. Returns a
     // tree with a placeholder root node; listen for the "loadComplete" event to
     // get a notification that the tree has fully loaded (the previous root node
     // reference will stop working at or before this point).
     [nocompile] static void getTree(optional long tabId, RootCallback callback);
 
     // Get the automation tree for the whole desktop which consists of all on
     // screen views. Note this API is currently only supported on Chrome OS.
     [nocompile] static void getDesktop(RootCallback callback);
 
+    // Set the type of tree change events you want to receive when
+    // calling addTreeChangeObserver.
+    [nocompile] static void setTreeChangeObserverMask(

[Peter Lundblad, 2015/11/20 13:42:59]

I assume this mask is per extension.  IN any case, since you can add more
than one observer, I think it'd make sense to allow a separate mask per
observer. That would allow diferent parts of the user of this api todo
be less coupled.

[dmazzoni, 2015/11/23 20:16:50]

That would be ideal, but it would significantly complicate the implementation so
I'd prefer to leave it like this for now.

The issue is that the mask is implemented in C++, but the registration of
observers happens in the JS bindings layer. The significant performance benefit
of this change happens because we can avoid calls from C++ into JS for the vast
majority of tree changes now.

I'm open to fixing this later if we actually need it. OK to leave it like this
for now?

[David Tseng, 2015/11/24 18:46:30]

I think, this looks a little like re-inventing the node-based eventing we have
(just articulated a little differently). Having listeners there that add
listeners for specific events, looks kind of like what we're adding onto here.

[dmazzoni, 2015/11/26 00:08:04]

The exception here is the onRemoved callback. Right now it gets called *before*
the node gets removed, but when the tree is in a possibly inconsistent state.

Getting rid of the tree change observers and replacing them with events would
mean:

* Rewriting the unserialization algorithm to compute the set of nodes that will
be removed before actually removing anything
* Potentially extra overhead due to event bubbling, etc.

I'm not convinced that events are better than tree change observers. Node that
the HTML DOM has both events and mutation observers, and the original mutation
events actually had to be deprecated because of similar performance issues.

I think what'd be ideal would be to make the tree change observers a lot like
mutation observers, where you could specify exactly what types of changes you're
interested in, and scope it to just part of the tree. The question is how much
we want to take on now, since we don't need all of that for live regions.

+        TreeChangeObserverMask mask);
+
     // Add a tree change observer. Tree change observers are static/global, they
-    // listen to changes across all trees.
+    // listen to changes across all trees. Note that you must also call
+    // setTreeChangeObserverMask for this to do anything.
     [nocompile] static void addTreeChangeObserver(
         TreeChangeObserver observer);
 
     // Remove a tree change observer.
     [nocompile] static void removeTreeChangeObserver(
         TreeChangeObserver observer);
 
     // Sets the selection in a tree. This creates a selection in a single
     // tree (anchorObject and focusObject must have the same root).
     // Everything in the tree between the two node/offset pairs gets included
     // in the selection. The anchor is where the user started the selection,
     // while the focus is the point at which the selection gets extended
     // e.g. when dragging with a mouse or using the keyboard. For nodes with
     // the role staticText, the offset gives the character offset within
     // the value where the selection starts or ends, respectively.
     [nocompile] static void setDocumentSelection(
         SetDocumentSelectionParams params);
   };
 };