Initial support for Ranges over automation nodes (used to track ChromeVox focus).

chrome/browser/resources/chromeos/chromevox/cvox2/background/cursors.js

 // 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.
 
 /**
  * @fileoverview Classes related to cursors that point to and select parts of
  * the automation tree.
  */
 
 goog.provide('cursors.Cursor');
@@ skipping 54 matching lines @@
  * not both. An index of |cursors.NODE_INDEX| means the node as a whole is
  * pointed to and covers the case where the accessible text is empty.
  */
 cursors.Cursor = function(node, index) {
   /** @type {!AutomationNode} */
   this.node = node;
   /** @type {number} */
   this.index = index;
 };
 
+/**
+ * Convenience method to construct a Cursor from a node.
+ * @param {!AutomationNode} node
+ * @return {!cursors.Cursor}
+ */
+cursors.Cursor.fromNode = function(node) {
+  return new cursors.Cursor(node, cursors.NODE_INDEX);
+};
+
 cursors.Cursor.prototype = {
   /**
    * Returns a copy of this cursor.
-   * @return {cursors.Cursor}
+   * @return {!cursors.Cursor}
    */
   clone: function() {
     return new cursors.Cursor(this.node, this.index);
   },
 
   /**
+   * Returns true if |rhs| is equal to this cursor.
+   * @param {!cursors.Cursor} rhs
+   * @return {boolean}
+   */
+  equals: function(rhs) {
+    return this.node === rhs.node &&
+        this.index === rhs.index;
+  },
+
+  /**
    * Gets the accessible text of the node associated with this cursor.
    *
    * Note that only one of |name| or |value| attribute is ever nonempty on an
    * automation node. If either contains whitespace, we still treat it as we do
    * for a nonempty string.
    * @param {!AutomationNode=} opt_node Use this node rather than this cursor's
    * node.
    * @return {string}
    */
   getText: function(opt_node) {
@@ skipping 112 matching lines @@
                   AutomationPredicate.linebreak, {before: true}) || node;
             }
             this.node = node || this.node;
             break;
           }
         break;
     }
   }
 };
 
+/**
+ * Represents a range in the automation tree. There is no visible selection on
+ * the page caused by usage of this object.
+ * @param {!cursors.Cursor} start
+ * @param {!cursors.Cursor} end
+ * @constructor
+ */
+cursors.Range = function(start, end) {
+  this.start = start;
+  this.end = end;

[Peter Lundblad, 2014/10/23 13:35:07]

Are these members meant to be public?

+  this.normalize();
+};
+
+/**
+ * Convenience method to construct a Range surrounding one node.
+ * @param {!AutomationNode} node
+ * @return {!cursors.Range}
+ */
+cursors.Range.fromNode = function(node) {
+  return new cursors.Range(cursors.Cursor.fromNode(node),
+                           cursors.Cursor.fromNode(node));
+};
+
+cursors.Range.prototype = {
+  /** @return {!cursors.Range} */
+  clone: function() {
+    return new cursors.Range(this.start.clone(), this.end.clone());
+  },
+
+  /**
+   * Returns true if |rhs| is equal to this range.
+   * @param {!cursors.Range} rhs
+   * @return {boolean}
+   */
+  equals: function(rhs) {
+    return this.start.equals(rhs.start) &&
+        this.end.equals(rhs.end);
+  },
+
+  /**
+   * Gets a cursor bounding this range.
+   * @param {Dir} dir Which endpoint cursor to return; Dir.FORWARD for end,
+   * Dir.BACKWARD for start.
+   * @return {cursors.Cursor}
+   */
+  getBound: function(dir) {
+    return dir == Dir.FORWARD ? this.end : this.start;
+  },
+
+  /**
+   * Collapses this range to an endpoint.
+   * @param {Dir} dir Dir.FORWARD collapses to end; Dir.BACKWARD collapses to
+   * start.
+   * @return {cursors.Range}
+   */
+  collapse: function(dir) {
+    this.start = this.getBound(dir);
+    this.end = this.start;
+    return this;
+  },
+
+  /**
+   * Moves this Range by the unit in the given direction.
+   * @param {Unit} unit
+   * @param {Dir} dir
+   */
+  move: function(unit, dir) {
+    var newStart = this.getBound(dir);
+    var newEnd = newStart.clone();
+    switch (unit) {
+      case Unit.CHARACTER:
+        newStart.move(unit, Movement.BOUND, dir);
+        this.normalize();
+        break;
+      case Unit.WORD:
+      case Unit.LINE:
+      case Unit.NODE:
+        newEnd.move(unit, Movement.DIRECTIONAL, dir);
+        newStart = newEnd.clone();
+        newEnd.move(unit, Movement.BOUND, Dir.FORWARD);
+        break;
+    }
+    this.start = newStart;
+    this.end = newEnd;
+  },
+
+  /**
+   * Normalizes this range to point forward.

[dmazzoni, 2014/10/17 16:46:08]

I'm confused - the description makes it sound like this modifies the range in
place, but it returns a bool.

+   */
+  normalize: function() {
+    if (this.start.node == this.end.node)

[dmazzoni, 2014/10/17 16:46:08]

nit: ===?

[Peter Lundblad, 2014/10/23 13:35:07]

Do we want to be consistent and use === when comparing nodes?

+      return this.start.index <= this.end.index;
+    return AutomationUtil.isBefore(this.start.node, this.end.node);
+  }

[Peter Lundblad, 2014/10/23 13:35:07]

Is this the right implementation for this function?

+};
+
 });  // goog.scope