chrome/browser/resources/chromeos/chromevox/walkers/abstract_shifter.js

   1 // Copyright 2014 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 /**
   6  * @fileoverview An interface for an ordered collection of walkers, called a
   7  * shifter.
   8  */
   9
  10
  11 goog.provide('cvox.AbstractShifter');
  12
  13 goog.require('cvox.AbstractWalker');
  14 goog.require('cvox.CursorSelection');
  15 goog.require('cvox.NavBraille');
  16
  17
  18 /**
  19  * @constructor
  20  */
  21 cvox.AbstractShifter = function() {
  22   this.isSubnavigating_ = false;
  23 };
  24
  25
  26 /**
  27  * Moves to the next selection in the DOM, performing any walker shifts as
  28  * necessary.
  29  * @param {!cvox.CursorSelection} sel The selection to go next from.
  30  * @return {cvox.CursorSelection} The resulting selection.
  31  */
  32 cvox.AbstractShifter.prototype.next = goog.abstractMethod;
  33
  34
  35 /**
  36  * Gets the first (or last) selection for this shifter's current granularity.
  37  * @param {?} sel
  38  * @param {{reversed: (undefined|boolean)}=} kwargs Extra arguments.
  39  *  reversed: If true, syncs to the end and returns a reversed selection.
  40  *    False by default.
  41  * @return {!cvox.CursorSelection} The valid selection.
  42  */
  43 cvox.AbstractShifter.prototype.begin = function(sel, kwargs) {
  44   return this.currentWalker_.begin(kwargs);
  45 };
  46
  47
  48 /**
  49  * Syncs to this shifter.
  50  * @param {!cvox.CursorSelection} sel The selection to sync, if any.
  51  * @return {cvox.CursorSelection} The selection.
  52  */
  53 cvox.AbstractShifter.prototype.sync = goog.abstractMethod;
  54
  55
  56 /**
  57  * Name of this shifter.
  58  * @return {string} The shifter's name.
  59  */
  60 cvox.AbstractShifter.prototype.getName = goog.abstractMethod;
  61
  62
  63 /**
  64  * Gets the current description.
  65  * @param {!cvox.CursorSelection} prevSel The previous selection, for context.
  66  * @param {!cvox.CursorSelection} sel The current selection.
  67  * @return {Array<cvox.NavDescription>} The description array.
  68  */
  69 cvox.AbstractShifter.prototype.getDescription = goog.abstractMethod;
  70
  71
  72 /**
  73  * Gets the current braille.
  74  * @param {!cvox.CursorSelection} prevSel The previous selection, for context.
  75  * @param {!cvox.CursorSelection} sel The current selection.
  76  * @return {!cvox.NavBraille} The braille description.
  77  */
  78 cvox.AbstractShifter.prototype.getBraille = goog.abstractMethod;
  79
  80
  81 /**
  82  * Gets the granularity message.
  83  * @return {string} The message string.
  84  */
  85 cvox.AbstractShifter.prototype.getGranularityMsg = goog.abstractMethod;
  86
  87
  88 /**
  89  * Shifts to a less granular level.
  90  */
  91 cvox.AbstractShifter.prototype.makeLessGranular = function() {
  92   this.ensureNotSubnavigating();
  93 };
  94
  95
  96 /**
  97  * Shifts to a more granular level.
  98  * NOTE: after a shift, we are no longer subnavigating, if we were.
  99  */
 100 cvox.AbstractShifter.prototype.makeMoreGranular = function() {
 101   this.ensureNotSubnavigating();
 102 };
 103
 104
 105 /**
 106  * Enters subnavigation mode, if it was not already in it.
 107  * Subnavigation mode is where the shifter is temporarily one level
 108  * more granular (until either the next granularity shift or
 109  * ensureNotSubnavigating is called).
 110  */
 111 cvox.AbstractShifter.prototype.ensureSubnavigating = function() {
 112   if (this.isSubnavigating_ == false) {
 113     this.makeMoreGranular();
 114     this.isSubnavigating_ = true;
 115   }
 116 };
 117
 118
 119 /**
 120  * Exits subnavigation mode, if it was in it.
 121  */
 122 cvox.AbstractShifter.prototype.ensureNotSubnavigating = function() {
 123   if (this.isSubnavigating_ == true) {
 124     this.isSubnavigating_ = false;
 125     this.makeLessGranular();
 126   }
 127 };
 128
 129
 130 /**
 131  * Returns true if the shifter is currently in subnavigation mode.
 132  * @return {boolean} If in subnavigation mode.
 133  */
 134 cvox.AbstractShifter.prototype.isSubnavigating = function() {
 135   return this.isSubnavigating_;
 136 };
 137
 138
 139 /**
 140  * Delegates to current walker.
 141   * @param {string} name Action name.
 142  * @return {boolean} True if this shifter contains action.
 143  */
 144 cvox.AbstractShifter.prototype.hasAction = function(name) {
 145 return this.currentWalker_.hasAction(name);
 146 };
 147
 148
 149 /**
 150  * Delegates an action to the current walker.
 151  * @param {string} name The action name.
 152  * @param {!cvox.CursorSelection} sel The current selection.
 153  * @return {cvox.CursorSelection} The selection after the action.
 154  */
 155 cvox.AbstractShifter.prototype.performAction = function(name, sel) {
 156   return this.currentWalker_.performAction(name, sel);
 157 };
 158
 159
 160 /**
 161  * Factory method to create an instance of this shifter.
 162  * @param {!cvox.CursorSelection} sel The initial selection.
 163  * @return {cvox.AbstractShifter} The shifter or null if given a selection not
 164  * within the shifter's domain.
 165  */
 166 cvox.AbstractShifter.create = goog.abstractMethod;