Debian Codegraph @

closure-library/closure/goog/ui/tabbar.js

raw
1 // Copyright 2008 The Closure Library Authors. All Rights Reserved.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS-IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 /**
16 * @fileoverview Tab bar UI component.
17 *
18 * @author [email protected] (Attila Bodis)
19 * @see ../demos/tabbar.html
20 */
21
22 goog.provide('goog.ui.TabBar');
23 goog.provide('goog.ui.TabBar.Location');
24
25 goog.require('goog.ui.Component.EventType');
26 goog.require('goog.ui.Container');
27 goog.require('goog.ui.Container.Orientation');
28 // We need to include following dependency because of the magic with
29 // goog.ui.registry.setDecoratorByClassName
30 goog.require('goog.ui.Tab');
31 goog.require('goog.ui.TabBarRenderer');
32 goog.require('goog.ui.registry');
33
34
35
36 /**
37 * Tab bar UI component. A tab bar contains tabs, rendered above, below,
38 * before, or after tab contents. Tabs in tab bars dispatch the following
39 * events:
40 * <ul>
41 * <li>{@link goog.ui.Component.EventType.ACTION} when activated via the
42 * keyboard or the mouse,
43 * <li>{@link goog.ui.Component.EventType.SELECT} when selected, and
44 * <li>{@link goog.ui.Component.EventType.UNSELECT} when deselected.
45 * </ul>
46 * Clients may listen for all of the above events on the tab bar itself, and
47 * refer to the event target to identify the tab that dispatched the event.
48 * When an unselected tab is clicked for the first time, it dispatches both a
49 * {@code SELECT} event and an {@code ACTION} event; subsequent clicks on an
50 * already selected tab only result in {@code ACTION} events.
51 *
52 * @param {goog.ui.TabBar.Location=} opt_location Tab bar location; defaults to
53 * {@link goog.ui.TabBar.Location.TOP}.
54 * @param {goog.ui.TabBarRenderer=} opt_renderer Renderer used to render or
55 * decorate the container; defaults to {@link goog.ui.TabBarRenderer}.
56 * @param {goog.dom.DomHelper=} opt_domHelper DOM helper, used for document
57 * interaction.
58 * @constructor
59 * @extends {goog.ui.Container}
60 */
61 goog.ui.TabBar = function(opt_location, opt_renderer, opt_domHelper) {
62 this.setLocation(opt_location || goog.ui.TabBar.Location.TOP);
63
64 goog.ui.Container.call(
65 this, this.getOrientation(),
66 opt_renderer || goog.ui.TabBarRenderer.getInstance(), opt_domHelper);
67
68 this.listenToTabEvents_();
69 };
70 goog.inherits(goog.ui.TabBar, goog.ui.Container);
71 goog.tagUnsealableClass(goog.ui.TabBar);
72
73
74 /**
75 * Tab bar location relative to tab contents.
76 * @enum {string}
77 */
78 goog.ui.TabBar.Location = {
79 // Above tab contents.
80 TOP: 'top',
81 // Below tab contents.
82 BOTTOM: 'bottom',
83 // To the left of tab contents (to the right if the page is right-to-left).
84 START: 'start',
85 // To the right of tab contents (to the left if the page is right-to-left).
86 END: 'end'
87 };
88
89
90 /**
91 * Tab bar location; defaults to {@link goog.ui.TabBar.Location.TOP}.
92 * @type {goog.ui.TabBar.Location}
93 * @private
94 */
95 goog.ui.TabBar.prototype.location_;
96
97
98 /**
99 * Whether keyboard navigation should change the selected tab, or just move
100 * the highlight. Defaults to true.
101 * @type {boolean}
102 * @private
103 */
104 goog.ui.TabBar.prototype.autoSelectTabs_ = true;
105
106
107 /**
108 * The currently selected tab (null if none).
109 * @type {goog.ui.Control?}
110 * @private
111 */
112 goog.ui.TabBar.prototype.selectedTab_ = null;
113
114
115 /**
116 * @override
117 */
118 goog.ui.TabBar.prototype.enterDocument = function() {
119 goog.ui.TabBar.superClass_.enterDocument.call(this);
120
121 this.listenToTabEvents_();
122 };
123
124
125 /** @override */
126 goog.ui.TabBar.prototype.disposeInternal = function() {
127 goog.ui.TabBar.superClass_.disposeInternal.call(this);
128 this.selectedTab_ = null;
129 };
130
131
132 /**
133 * Removes the tab from the tab bar. Overrides the superclass implementation
134 * by deselecting the tab being removed. Since {@link #removeChildAt} uses
135 * {@link #removeChild} internally, we only need to override this method.
136 * @param {string|goog.ui.Component} tab Tab to remove.
137 * @param {boolean=} opt_unrender Whether to call {@code exitDocument} on the
138 * removed tab, and detach its DOM from the document (defaults to false).
139 * @return {goog.ui.Control} The removed tab, if any.
140 * @override
141 */
142 goog.ui.TabBar.prototype.removeChild = function(tab, opt_unrender) {
143 // This actually only accepts goog.ui.Controls. There's a TODO
144 // on the superclass method to fix this.
145 this.deselectIfSelected(/** @type {goog.ui.Control} */ (tab));
146 return goog.ui.TabBar.superClass_.removeChild.call(this, tab, opt_unrender);
147 };
148
149
150 /**
151 * @return {goog.ui.TabBar.Location} Tab bar location relative to tab contents.
152 */
153 goog.ui.TabBar.prototype.getLocation = function() {
154 return this.location_;
155 };
156
157
158 /**
159 * Sets the location of the tab bar relative to tab contents.
160 * @param {goog.ui.TabBar.Location} location Tab bar location relative to tab
161 * contents.
162 * @throws {Error} If the tab bar has already been rendered.
163 */
164 goog.ui.TabBar.prototype.setLocation = function(location) {
165 // setOrientation() will take care of throwing an error if already rendered.
166 this.setOrientation(goog.ui.TabBar.getOrientationFromLocation(location));
167 this.location_ = location;
168 };
169
170
171 /**
172 * @return {boolean} Whether keyboard navigation should change the selected tab,
173 * or just move the highlight.
174 */
175 goog.ui.TabBar.prototype.isAutoSelectTabs = function() {
176 return this.autoSelectTabs_;
177 };
178
179
180 /**
181 * Enables or disables auto-selecting tabs using the keyboard. If auto-select
182 * is enabled, keyboard navigation switches tabs immediately, otherwise it just
183 * moves the highlight.
184 * @param {boolean} enable Whether keyboard navigation should change the
185 * selected tab, or just move the highlight.
186 */
187 goog.ui.TabBar.prototype.setAutoSelectTabs = function(enable) {
188 this.autoSelectTabs_ = enable;
189 };
190
191
192 /**
193 * Highlights the tab at the given index in response to a keyboard event.
194 * Overrides the superclass implementation by also selecting the tab if
195 * {@link #isAutoSelectTabs} returns true.
196 * @param {number} index Index of tab to highlight.
197 * @protected
198 * @override
199 */
200 goog.ui.TabBar.prototype.setHighlightedIndexFromKeyEvent = function(index) {
201 goog.ui.TabBar.superClass_.setHighlightedIndexFromKeyEvent.call(this, index);
202 if (this.autoSelectTabs_) {
203 // Immediately select the tab.
204 this.setSelectedTabIndex(index);
205 }
206 };
207
208
209 /**
210 * @return {goog.ui.Control?} The currently selected tab (null if none).
211 */
212 goog.ui.TabBar.prototype.getSelectedTab = function() {
213 return this.selectedTab_;
214 };
215
216
217 /**
218 * Selects the given tab.
219 * @param {goog.ui.Control?} tab Tab to select (null to select none).
220 */
221 goog.ui.TabBar.prototype.setSelectedTab = function(tab) {
222 if (tab) {
223 // Select the tab and have it dispatch a SELECT event, to be handled in
224 // handleTabSelect() below.
225 tab.setSelected(true);
226 } else if (this.getSelectedTab()) {
227 // De-select the currently selected tab and have it dispatch an UNSELECT
228 // event, to be handled in handleTabUnselect() below.
229 this.getSelectedTab().setSelected(false);
230 }
231 };
232
233
234 /**
235 * @return {number} Index of the currently selected tab (-1 if none).
236 */
237 goog.ui.TabBar.prototype.getSelectedTabIndex = function() {
238 return this.indexOfChild(this.getSelectedTab());
239 };
240
241
242 /**
243 * Selects the tab at the given index.
244 * @param {number} index Index of the tab to select (-1 to select none).
245 */
246 goog.ui.TabBar.prototype.setSelectedTabIndex = function(index) {
247 this.setSelectedTab(/** @type {goog.ui.Tab} */ (this.getChildAt(index)));
248 };
249
250
251 /**
252 * If the specified tab is the currently selected tab, deselects it, and
253 * selects the closest selectable tab in the tab bar (first looking before,
254 * then after the deselected tab). Does nothing if the argument is not the
255 * currently selected tab. Called internally when a tab is removed, hidden,
256 * or disabled, to ensure that another tab is selected instead.
257 * @param {goog.ui.Control?} tab Tab to deselect (if any).
258 * @protected
259 */
260 goog.ui.TabBar.prototype.deselectIfSelected = function(tab) {
261 if (tab && tab == this.getSelectedTab()) {
262 var index = this.indexOfChild(tab);
263 // First look for the closest selectable tab before this one.
264 for (var i = index - 1;
265 tab = /** @type {goog.ui.Tab} */ (this.getChildAt(i)); i--) {
266 if (this.isSelectableTab(tab)) {
267 this.setSelectedTab(tab);
268 return;
269 }
270 }
271 // Next, look for the closest selectable tab after this one.
272 for (var j = index + 1;
273 tab = /** @type {goog.ui.Tab} */ (this.getChildAt(j)); j++) {
274 if (this.isSelectableTab(tab)) {
275 this.setSelectedTab(tab);
276 return;
277 }
278 }
279 // If all else fails, just set the selection to null.
280 this.setSelectedTab(null);
281 }
282 };
283
284
285 /**
286 * Returns true if the tab is selectable, false otherwise. Only visible and
287 * enabled tabs are selectable.
288 * @param {goog.ui.Control} tab Tab to check.
289 * @return {boolean} Whether the tab is selectable.
290 * @protected
291 */
292 goog.ui.TabBar.prototype.isSelectableTab = function(tab) {
293 return tab.isVisible() && tab.isEnabled();
294 };
295
296
297 /**
298 * Handles {@code SELECT} events dispatched by tabs as they become selected.
299 * @param {goog.events.Event} e Select event to handle.
300 * @protected
301 */
302 goog.ui.TabBar.prototype.handleTabSelect = function(e) {
303 if (this.selectedTab_ && this.selectedTab_ != e.target) {
304 // Deselect currently selected tab.
305 this.selectedTab_.setSelected(false);
306 }
307 this.selectedTab_ = /** @type {goog.ui.Tab} */ (e.target);
308 };
309
310
311 /**
312 * Handles {@code UNSELECT} events dispatched by tabs as they become deselected.
313 * @param {goog.events.Event} e Unselect event to handle.
314 * @protected
315 */
316 goog.ui.TabBar.prototype.handleTabUnselect = function(e) {
317 if (e.target == this.selectedTab_) {
318 this.selectedTab_ = null;
319 }
320 };
321
322
323 /**
324 * Handles {@code DISABLE} events displayed by tabs.
325 * @param {goog.events.Event} e Disable event to handle.
326 * @protected
327 */
328 goog.ui.TabBar.prototype.handleTabDisable = function(e) {
329 this.deselectIfSelected(/** @type {goog.ui.Tab} */ (e.target));
330 };
331
332
333 /**
334 * Handles {@code HIDE} events displayed by tabs.
335 * @param {goog.events.Event} e Hide event to handle.
336 * @protected
337 */
338 goog.ui.TabBar.prototype.handleTabHide = function(e) {
339 this.deselectIfSelected(/** @type {goog.ui.Tab} */ (e.target));
340 };
341
342
343 /**
344 * Handles focus events dispatched by the tab bar's key event target. If no tab
345 * is currently highlighted, highlights the selected tab or the first tab if no
346 * tab is selected either.
347 * @param {goog.events.Event} e Focus event to handle.
348 * @protected
349 * @override
350 */
351 goog.ui.TabBar.prototype.handleFocus = function(e) {
352 if (!this.getHighlighted()) {
353 this.setHighlighted(
354 this.getSelectedTab() ||
355 /** @type {goog.ui.Tab} */ (this.getChildAt(0)));
356 }
357 };
358
359
360 /**
361 * Subscribes to events dispatched by tabs.
362 * @private
363 */
364 goog.ui.TabBar.prototype.listenToTabEvents_ = function() {
365 // Listen for SELECT, UNSELECT, DISABLE, and HIDE events dispatched by tabs.
366 this.getHandler()
367 .listen(this, goog.ui.Component.EventType.SELECT, this.handleTabSelect)
368 .listen(
369 this, goog.ui.Component.EventType.UNSELECT, this.handleTabUnselect)
370 .listen(this, goog.ui.Component.EventType.DISABLE, this.handleTabDisable)
371 .listen(this, goog.ui.Component.EventType.HIDE, this.handleTabHide);
372 };
373
374
375 /**
376 * Returns the {@link goog.ui.Container.Orientation} that is implied by the
377 * given {@link goog.ui.TabBar.Location}.
378 * @param {goog.ui.TabBar.Location} location Tab bar location.
379 * @return {goog.ui.Container.Orientation} Corresponding orientation.
380 */
381 goog.ui.TabBar.getOrientationFromLocation = function(location) {
382 return location == goog.ui.TabBar.Location.START ||
383 location == goog.ui.TabBar.Location.END ?
384 goog.ui.Container.Orientation.VERTICAL :
385 goog.ui.Container.Orientation.HORIZONTAL;
386 };
387
388
389 // Register a decorator factory function for goog.ui.TabBars.
390 goog.ui.registry.setDecoratorByClassName(
391 goog.ui.TabBarRenderer.CSS_CLASS,
392 function() { return new goog.ui.TabBar(); });