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