Add setSelection function to automation API.

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 294 matching lines @@
   };
 
   // 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 root node.
+    // Whether this AutomationNode is a root node.
     boolean isRootNode;
 
     // The role of this node.
     automation.RoleType role;
 
     // The $(ref:automation.StateType)s describing this node.
     object state;
 
     // The rendered location (as a bounding box) of this node within the frame.
     automation.Rect location;
@@ skipping 89 matching lines @@
     long textSelStart;
 
     // The character index of the end of the selection within this editable
     // text element; -1 if no selection.
     long textSelEnd;
 
     // The input type, like email or number.
     DOMString textInputType;
 
     //
+    // Tree selection attributes (available on root nodes only)
+    //
+
+    AutomationNode? anchorObject;
+    long? anchorOffset;
+    AutomationNode? focusObject;
+    long? focusOffset;

[David Tseng, 2015/09/23 17:57:41]

Please document all of these -- they get picked up as part of the public
documentation for chrome.automation.

+
+    //
     // Range attributes.
     //
 
     // The current value for this range.
     double valueForRange;
 
     // The minimum possible value for this range.
     double minValueForRange;
 
     // The maximum possible value for this range.
@@ skipping 111 matching lines @@
     [nocompile] static void getDesktop(RootCallback callback);
 
     // Add a tree change observer. Tree change observers are static/global, they
     // listen to changes across all trees.
     [nocompile] static void addTreeChangeObserver(
         TreeChangeObserver observer);
 
     // Remove a tree change observer.
     [nocompile] static void removeTreeChangeObserver(
         TreeChangeObserver observer);
+
+    // Sets the selection in a tree.

[David Tseng, 2015/09/23 17:57:41]

Needs more detail. The anchor and focus nodes need to come from the same tree
right? (same tree here means node1.root === node2.root). Also, this doesn't work
for nodes where root.role == 'desktop'.

+    [nocompile] static void setSelection(

[David Tseng, 2015/09/23 17:57:41]

This is now a little confusing as there's two versions of setSelection (one on
chrome.automation and one on the AutomationNode). The AutomationNode version
needs its documentation updated as it's no longer restricted to text fields.
Maybe call the former chrome.automation.setDocumentSelection or something along
those lines.

+        [instanceOf=AutomationNode] object anchorObject,

[David Tseng, 2015/09/23 17:57:41]

Does the instanceOf property do anything here?

+        long anchorOffset,

[David Tseng, 2015/09/23 17:57:41]

Rather than this list of params, use a dictionary (similar to find).

+        [instanceOf=AutomationNode] object focusObject,
+        long focusOffset);
   };
 };