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
11goog.provide('cvox.AbstractShifter');
12
13goog.require('cvox.AbstractWalker');
14goog.require('cvox.CursorSelection');
15goog.require('cvox.NavBraille');
16
17
18/**
19 * @constructor
20 */
21cvox.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 */
32cvox.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 */
42cvox.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 */
52cvox.AbstractShifter.prototype.sync = goog.abstractMethod;
53
54
55/**
56 * Name of this shifter.
57 * @return {string} The shifter's name.
58 */
59cvox.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 */
68cvox.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 */
77cvox.AbstractShifter.prototype.getBraille = goog.abstractMethod;
78
79
80/**
81 * Gets the granularity message.
82 * @return {string} The message string.
83 */
84cvox.AbstractShifter.prototype.getGranularityMsg = goog.abstractMethod;
85
86
87/**
88 * Shifts to a less granular level.
89 */
90cvox.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 */
99cvox.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 */
110cvox.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 */
121cvox.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 */
133cvox.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 */
143cvox.AbstractShifter.prototype.hasAction = function(name) {
144return 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 */
154cvox.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 */
165cvox.AbstractShifter.create = goog.abstractMethod;
166