Debian Codegraph @

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

raw
1 // Copyright 2007 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 Base class for containers that host {@link goog.ui.Control}s,
17 * such as menus and toolbars. Provides default keyboard and mouse event
18 * handling and child management, based on a generalized version of
19 * {@link goog.ui.Menu}.
20 *
21 * @author [email protected] (Attila Bodis)
22 * @see ../demos/container.html
23 */
24 // TODO(attila): Fix code/logic duplication between this and goog.ui.Control.
25 // TODO(attila): Maybe pull common stuff all the way up into Component...?
26
27 goog.provide('goog.ui.Container');
28 goog.provide('goog.ui.Container.EventType');
29 goog.provide('goog.ui.Container.Orientation');
30
31 goog.require('goog.a11y.aria');
32 goog.require('goog.a11y.aria.State');
33 goog.require('goog.asserts');
34 goog.require('goog.dom');
35 goog.require('goog.events.EventType');
36 goog.require('goog.events.KeyCodes');
37 goog.require('goog.events.KeyHandler');
38 goog.require('goog.object');
39 goog.require('goog.style');
40 goog.require('goog.ui.Component');
41 goog.require('goog.ui.ContainerRenderer');
42 goog.require('goog.ui.Control');
43
44
45
46 /**
47 * Base class for containers. Extends {@link goog.ui.Component} by adding
48 * the following:
49 * <ul>
50 * <li>a {@link goog.events.KeyHandler}, to simplify keyboard handling,
51 * <li>a pluggable <em>renderer</em> framework, to simplify the creation of
52 * containers without the need to subclass this class,
53 * <li>methods to manage child controls hosted in the container,
54 * <li>default mouse and keyboard event handling methods.
55 * </ul>
56 * @param {?goog.ui.Container.Orientation=} opt_orientation Container
57 * orientation; defaults to {@code VERTICAL}.
58 * @param {goog.ui.ContainerRenderer=} opt_renderer Renderer used to render or
59 * decorate the container; defaults to {@link goog.ui.ContainerRenderer}.
60 * @param {goog.dom.DomHelper=} opt_domHelper DOM helper, used for document
61 * interaction.
62 * @extends {goog.ui.Component}
63 * @constructor
64 */
65 goog.ui.Container = function(opt_orientation, opt_renderer, opt_domHelper) {
66 goog.ui.Component.call(this, opt_domHelper);
67 this.renderer_ = opt_renderer || goog.ui.ContainerRenderer.getInstance();
68 this.orientation_ = opt_orientation || this.renderer_.getDefaultOrientation();
69 };
70 goog.inherits(goog.ui.Container, goog.ui.Component);
71 goog.tagUnsealableClass(goog.ui.Container);
72
73
74 /**
75 * Container-specific events.
76 * @enum {string}
77 */
78 goog.ui.Container.EventType = {
79 /**
80 * Dispatched after a goog.ui.Container becomes visible. Non-cancellable.
81 * NOTE(user): This event really shouldn't exist, because the
82 * goog.ui.Component.EventType.SHOW event should behave like this one. But the
83 * SHOW event for containers has been behaving as other components'
84 * BEFORE_SHOW event for a long time, and too much code relies on that old
85 * behavior to fix it now.
86 */
87 AFTER_SHOW: 'aftershow',
88
89 /**
90 * Dispatched after a goog.ui.Container becomes invisible. Non-cancellable.
91 */
92 AFTER_HIDE: 'afterhide'
93 };
94
95
96 /**
97 * Container orientation constants.
98 * @enum {string}
99 */
100 goog.ui.Container.Orientation = {
101 HORIZONTAL: 'horizontal',
102 VERTICAL: 'vertical'
103 };
104
105
106 /**
107 * Allows an alternative element to be set to receive key events, otherwise
108 * defers to the renderer's element choice.
109 * @type {Element|undefined}
110 * @private
111 */
112 goog.ui.Container.prototype.keyEventTarget_ = null;
113
114
115 /**
116 * Keyboard event handler.
117 * @type {goog.events.KeyHandler?}
118 * @private
119 */
120 goog.ui.Container.prototype.keyHandler_ = null;
121
122
123 /**
124 * Renderer for the container. Defaults to {@link goog.ui.ContainerRenderer}.
125 * @type {goog.ui.ContainerRenderer?}
126 * @private
127 */
128 goog.ui.Container.prototype.renderer_ = null;
129
130
131 /**
132 * Container orientation; determines layout and default keyboard navigation.
133 * @type {?goog.ui.Container.Orientation}
134 * @private
135 */
136 goog.ui.Container.prototype.orientation_ = null;
137
138
139 /**
140 * Whether the container is set to be visible. Defaults to true.
141 * @type {boolean}
142 * @private
143 */
144 goog.ui.Container.prototype.visible_ = true;
145
146
147 /**
148 * Whether the container is enabled and reacting to keyboard and mouse events.
149 * Defaults to true.
150 * @type {boolean}
151 * @private
152 */
153 goog.ui.Container.prototype.enabled_ = true;
154
155
156 /**
157 * Whether the container supports keyboard focus. Defaults to true. Focusable
158 * containers have a {@code tabIndex} and can be navigated to via the keyboard.
159 * @type {boolean}
160 * @private
161 */
162 goog.ui.Container.prototype.focusable_ = true;
163
164
165 /**
166 * The 0-based index of the currently highlighted control in the container
167 * (-1 if none).
168 * @type {number}
169 * @private
170 */
171 goog.ui.Container.prototype.highlightedIndex_ = -1;
172
173
174 /**
175 * The currently open (expanded) control in the container (null if none).
176 * @type {goog.ui.Control?}
177 * @private
178 */
179 goog.ui.Container.prototype.openItem_ = null;
180
181
182 /**
183 * Whether the mouse button is held down. Defaults to false. This flag is set
184 * when the user mouses down over the container, and remains set until they
185 * release the mouse button.
186 * @type {boolean}
187 * @private
188 */
189 goog.ui.Container.prototype.mouseButtonPressed_ = false;
190
191
192 /**
193 * Whether focus of child components should be allowed. Only effective if
194 * focusable_ is set to false.
195 * @type {boolean}
196 * @private
197 */
198 goog.ui.Container.prototype.allowFocusableChildren_ = false;
199
200
201 /**
202 * Whether highlighting a child component should also open it.
203 * @type {boolean}
204 * @private
205 */
206 goog.ui.Container.prototype.openFollowsHighlight_ = true;
207
208
209 /**
210 * Map of DOM IDs to child controls. Each key is the DOM ID of a child
211 * control's root element; each value is a reference to the child control
212 * itself. Used for looking up the child control corresponding to a DOM
213 * node in O(1) time.
214 * @type {Object}
215 * @private
216 */
217 goog.ui.Container.prototype.childElementIdMap_ = null;
218
219
220 // Event handler and renderer management.
221
222
223 /**
224 * Returns the DOM element on which the container is listening for keyboard
225 * events (null if none).
226 * @return {Element} Element on which the container is listening for key
227 * events.
228 */
229 goog.ui.Container.prototype.getKeyEventTarget = function() {
230 // Delegate to renderer, unless we've set an explicit target.
231 return this.keyEventTarget_ || this.renderer_.getKeyEventTarget(this);
232 };
233
234
235 /**
236 * Attaches an element on which to listen for key events.
237 * @param {Element|undefined} element The element to attach, or null/undefined
238 * to attach to the default element.
239 */
240 goog.ui.Container.prototype.setKeyEventTarget = function(element) {
241 if (this.focusable_) {
242 var oldTarget = this.getKeyEventTarget();
243 var inDocument = this.isInDocument();
244
245 this.keyEventTarget_ = element;
246 var newTarget = this.getKeyEventTarget();
247
248 if (inDocument) {
249 // Unlisten for events on the old key target. Requires us to reset
250 // key target state temporarily.
251 this.keyEventTarget_ = oldTarget;
252 this.enableFocusHandling_(false);
253 this.keyEventTarget_ = element;
254
255 // Listen for events on the new key target.
256 this.getKeyHandler().attach(newTarget);
257 this.enableFocusHandling_(true);
258 }
259 } else {
260 throw new Error(
261 'Can\'t set key event target for container ' +
262 'that doesn\'t support keyboard focus!');
263 }
264 };
265
266
267 /**
268 * Returns the keyboard event handler for this container, lazily created the
269 * first time this method is called. The keyboard event handler listens for
270 * keyboard events on the container's key event target, as determined by its
271 * renderer.
272 * @return {!goog.events.KeyHandler} Keyboard event handler for this container.
273 */
274 goog.ui.Container.prototype.getKeyHandler = function() {
275 return this.keyHandler_ ||
276 (this.keyHandler_ = new goog.events.KeyHandler(this.getKeyEventTarget()));
277 };
278
279
280 /**
281 * Returns the renderer used by this container to render itself or to decorate
282 * an existing element.
283 * @return {goog.ui.ContainerRenderer} Renderer used by the container.
284 */
285 goog.ui.Container.prototype.getRenderer = function() {
286 return this.renderer_;
287 };
288
289
290 /**
291 * Registers the given renderer with the container. Changing renderers after
292 * the container has already been rendered or decorated is an error.
293 * @param {goog.ui.ContainerRenderer} renderer Renderer used by the container.
294 */
295 goog.ui.Container.prototype.setRenderer = function(renderer) {
296 if (this.getElement()) {
297 // Too late.
298 throw new Error(goog.ui.Component.Error.ALREADY_RENDERED);
299 }
300
301 this.renderer_ = renderer;
302 };
303
304
305 // Standard goog.ui.Component implementation.
306
307
308 /**
309 * Creates the container's DOM.
310 * @override
311 */
312 goog.ui.Container.prototype.createDom = function() {
313 // Delegate to renderer.
314 this.setElementInternal(this.renderer_.createDom(this));
315 };
316
317
318 /**
319 * Returns the DOM element into which child components are to be rendered,
320 * or null if the container itself hasn't been rendered yet. Overrides
321 * {@link goog.ui.Component#getContentElement} by delegating to the renderer.
322 * @return {Element} Element to contain child elements (null if none).
323 * @override
324 */
325 goog.ui.Container.prototype.getContentElement = function() {
326 // Delegate to renderer.
327 return this.renderer_.getContentElement(this.getElement());
328 };
329
330
331 /**
332 * Returns true if the given element can be decorated by this container.
333 * Overrides {@link goog.ui.Component#canDecorate}.
334 * @param {Element} element Element to decorate.
335 * @return {boolean} True iff the element can be decorated.
336 * @override
337 */
338 goog.ui.Container.prototype.canDecorate = function(element) {
339 // Delegate to renderer.
340 return this.renderer_.canDecorate(element);
341 };
342
343
344 /**
345 * Decorates the given element with this container. Overrides {@link
346 * goog.ui.Component#decorateInternal}. Considered protected.
347 * @param {Element} element Element to decorate.
348 * @override
349 */
350 goog.ui.Container.prototype.decorateInternal = function(element) {
351 // Delegate to renderer.
352 this.setElementInternal(this.renderer_.decorate(this, element));
353 // Check whether the decorated element is explicitly styled to be invisible.
354 if (element.style.display == 'none') {
355 this.visible_ = false;
356 }
357 };
358
359
360 /**
361 * Configures the container after its DOM has been rendered, and sets up event
362 * handling. Overrides {@link goog.ui.Component#enterDocument}.
363 * @override
364 */
365 goog.ui.Container.prototype.enterDocument = function() {
366 goog.ui.Container.superClass_.enterDocument.call(this);
367
368 this.forEachChild(function(child) {
369 if (child.isInDocument()) {
370 this.registerChildId_(child);
371 }
372 }, this);
373
374 var elem = this.getElement();
375
376 // Call the renderer's initializeDom method to initialize the container's DOM.
377 this.renderer_.initializeDom(this);
378
379 // Initialize visibility (opt_force = true, so we don't dispatch events).
380 this.setVisible(this.visible_, true);
381
382 // Handle events dispatched by child controls.
383 this.getHandler()
384 .listen(this, goog.ui.Component.EventType.ENTER, this.handleEnterItem)
385 .listen(
386 this, goog.ui.Component.EventType.HIGHLIGHT, this.handleHighlightItem)
387 .listen(
388 this, goog.ui.Component.EventType.UNHIGHLIGHT,
389 this.handleUnHighlightItem)
390 .listen(this, goog.ui.Component.EventType.OPEN, this.handleOpenItem)
391 .listen(this, goog.ui.Component.EventType.CLOSE, this.handleCloseItem)
392 .
393
394 // Handle mouse events.
395 listen(elem, goog.events.EventType.MOUSEDOWN, this.handleMouseDown)
396 .listen(
397 goog.dom.getOwnerDocument(elem), goog.events.EventType.MOUSEUP,
398 this.handleDocumentMouseUp)
399 .
400
401 // Handle mouse events on behalf of controls in the container.
402 listen(
403 elem,
404 [
405 goog.events.EventType.MOUSEDOWN, goog.events.EventType.MOUSEUP,
406 goog.events.EventType.MOUSEOVER, goog.events.EventType.MOUSEOUT,
407 goog.events.EventType.CONTEXTMENU
408 ],
409 this.handleChildMouseEvents);
410
411 // If the container is focusable, set up keyboard event handling.
412 if (this.isFocusable()) {
413 this.enableFocusHandling_(true);
414 }
415 };
416
417
418 /**
419 * Sets up listening for events applicable to focusable containers.
420 * @param {boolean} enable Whether to enable or disable focus handling.
421 * @private
422 */
423 goog.ui.Container.prototype.enableFocusHandling_ = function(enable) {
424 var handler = this.getHandler();
425 var keyTarget = this.getKeyEventTarget();
426 if (enable) {
427 handler.listen(keyTarget, goog.events.EventType.FOCUS, this.handleFocus)
428 .listen(keyTarget, goog.events.EventType.BLUR, this.handleBlur)
429 .listen(
430 this.getKeyHandler(), goog.events.KeyHandler.EventType.KEY,
431 this.handleKeyEvent);
432 } else {
433 handler.unlisten(keyTarget, goog.events.EventType.FOCUS, this.handleFocus)
434 .unlisten(keyTarget, goog.events.EventType.BLUR, this.handleBlur)
435 .unlisten(
436 this.getKeyHandler(), goog.events.KeyHandler.EventType.KEY,
437 this.handleKeyEvent);
438 }
439 };
440
441
442 /**
443 * Cleans up the container before its DOM is removed from the document, and
444 * removes event handlers. Overrides {@link goog.ui.Component#exitDocument}.
445 * @override
446 */
447 goog.ui.Container.prototype.exitDocument = function() {
448 // {@link #setHighlightedIndex} has to be called before
449 // {@link goog.ui.Component#exitDocument}, otherwise it has no effect.
450 this.setHighlightedIndex(-1);
451
452 if (this.openItem_) {
453 this.openItem_.setOpen(false);
454 }
455
456 this.mouseButtonPressed_ = false;
457
458 goog.ui.Container.superClass_.exitDocument.call(this);
459 };
460
461
462 /** @override */
463 goog.ui.Container.prototype.disposeInternal = function() {
464 goog.ui.Container.superClass_.disposeInternal.call(this);
465
466 if (this.keyHandler_) {
467 this.keyHandler_.dispose();
468 this.keyHandler_ = null;
469 }
470
471 this.keyEventTarget_ = null;
472 this.childElementIdMap_ = null;
473 this.openItem_ = null;
474 this.renderer_ = null;
475 };
476
477
478 // Default event handlers.
479
480
481 /**
482 * Handles ENTER events raised by child controls when they are navigated to.
483 * @param {goog.events.Event} e ENTER event to handle.
484 * @return {boolean} Whether to prevent handleMouseOver from handling
485 * the event.
486 */
487 goog.ui.Container.prototype.handleEnterItem = function(e) {
488 // Allow the Control to highlight itself.
489 return true;
490 };
491
492
493 /**
494 * Handles HIGHLIGHT events dispatched by items in the container when
495 * they are highlighted.
496 * @param {goog.events.Event} e Highlight event to handle.
497 */
498 goog.ui.Container.prototype.handleHighlightItem = function(e) {
499 var index = this.indexOfChild(/** @type {goog.ui.Control} */ (e.target));
500 if (index > -1 && index != this.highlightedIndex_) {
501 var item = this.getHighlighted();
502 if (item) {
503 // Un-highlight previously highlighted item.
504 item.setHighlighted(false);
505 }
506
507 this.highlightedIndex_ = index;
508 item = this.getHighlighted();
509
510 if (this.isMouseButtonPressed()) {
511 // Activate item when mouse button is pressed, to allow MacOS-style
512 // dragging to choose menu items. Although this should only truly
513 // happen if the highlight is due to mouse movements, there is little
514 // harm in doing it for keyboard or programmatic highlights.
515 item.setActive(true);
516 }
517
518 // Update open item if open item needs follow highlight.
519 if (this.openFollowsHighlight_ && this.openItem_ &&
520 item != this.openItem_) {
521 if (item.isSupportedState(goog.ui.Component.State.OPENED)) {
522 item.setOpen(true);
523 } else {
524 this.openItem_.setOpen(false);
525 }
526 }
527 }
528
529 var element = this.getElement();
530 goog.asserts.assert(
531 element, 'The DOM element for the container cannot be null.');
532 if (e.target.getElement() != null) {
533 goog.a11y.aria.setState(
534 element, goog.a11y.aria.State.ACTIVEDESCENDANT,
535 e.target.getElement().id);
536 }
537 };
538
539
540 /**
541 * Handles UNHIGHLIGHT events dispatched by items in the container when
542 * they are unhighlighted.
543 * @param {goog.events.Event} e Unhighlight event to handle.
544 */
545 goog.ui.Container.prototype.handleUnHighlightItem = function(e) {
546 if (e.target == this.getHighlighted()) {
547 this.highlightedIndex_ = -1;
548 }
549 var element = this.getElement();
550 goog.asserts.assert(
551 element, 'The DOM element for the container cannot be null.');
552 // Setting certain ARIA attributes to empty strings is problematic.
553 // Just remove the attribute instead.
554 goog.a11y.aria.removeState(element, goog.a11y.aria.State.ACTIVEDESCENDANT);
555 };
556
557
558 /**
559 * Handles OPEN events dispatched by items in the container when they are
560 * opened.
561 * @param {goog.events.Event} e Open event to handle.
562 */
563 goog.ui.Container.prototype.handleOpenItem = function(e) {
564 var item = /** @type {goog.ui.Control} */ (e.target);
565 if (item && item != this.openItem_ && item.getParent() == this) {
566 if (this.openItem_) {
567 this.openItem_.setOpen(false);
568 }
569 this.openItem_ = item;
570 }
571 };
572
573
574 /**
575 * Handles CLOSE events dispatched by items in the container when they are
576 * closed.
577 * @param {goog.events.Event} e Close event to handle.
578 */
579 goog.ui.Container.prototype.handleCloseItem = function(e) {
580 if (e.target == this.openItem_) {
581 this.openItem_ = null;
582 }
583
584 var element = this.getElement();
585 var targetEl = e.target.getElement();
586 // Set the active descendant to the menu item when its submenu is closed and
587 // it is still highlighted. This can sometimes be called when the menuitem is
588 // unhighlighted because the focus moved elsewhere, do nothing at that point.
589 if (element && e.target.isHighlighted() && targetEl) {
590 goog.a11y.aria.setActiveDescendant(element, targetEl);
591 }
592 };
593
594
595 /**
596 * Handles mousedown events over the container. The default implementation
597 * sets the "mouse button pressed" flag and, if the container is focusable,
598 * grabs keyboard focus.
599 * @param {goog.events.BrowserEvent} e Mousedown event to handle.
600 */
601 goog.ui.Container.prototype.handleMouseDown = function(e) {
602 if (this.enabled_) {
603 this.setMouseButtonPressed(true);
604 }
605
606 var keyTarget = this.getKeyEventTarget();
607 if (keyTarget && goog.dom.isFocusableTabIndex(keyTarget)) {
608 // The container is configured to receive keyboard focus.
609 keyTarget.focus();
610 } else {
611 // The control isn't configured to receive keyboard focus; prevent it
612 // from stealing focus or destroying the selection.
613 e.preventDefault();
614 }
615 };
616
617
618 /**
619 * Handles mouseup events over the document. The default implementation
620 * clears the "mouse button pressed" flag.
621 * @param {goog.events.BrowserEvent} e Mouseup event to handle.
622 */
623 goog.ui.Container.prototype.handleDocumentMouseUp = function(e) {
624 this.setMouseButtonPressed(false);
625 };
626
627
628 /**
629 * Handles mouse events originating from nodes belonging to the controls hosted
630 * in the container. Locates the child control based on the DOM node that
631 * dispatched the event, and forwards the event to the control for handling.
632 * @param {goog.events.BrowserEvent} e Mouse event to handle.
633 */
634 goog.ui.Container.prototype.handleChildMouseEvents = function(e) {
635 var control = this.getOwnerControl(/** @type {Node} */ (e.target));
636 if (control) {
637 // Child control identified; forward the event.
638 switch (e.type) {
639 case goog.events.EventType.MOUSEDOWN:
640 control.handleMouseDown(e);
641 break;
642 case goog.events.EventType.MOUSEUP:
643 control.handleMouseUp(e);
644 break;
645 case goog.events.EventType.MOUSEOVER:
646 control.handleMouseOver(e);
647 break;
648 case goog.events.EventType.MOUSEOUT:
649 control.handleMouseOut(e);
650 break;
651 case goog.events.EventType.CONTEXTMENU:
652 control.handleContextMenu(e);
653 break;
654 }
655 }
656 };
657
658
659 /**
660 * Returns the child control that owns the given DOM node, or null if no such
661 * control is found.
662 * @param {Node} node DOM node whose owner is to be returned.
663 * @return {goog.ui.Control?} Control hosted in the container to which the node
664 * belongs (if found).
665 * @protected
666 */
667 goog.ui.Container.prototype.getOwnerControl = function(node) {
668 // Ensure that this container actually has child controls before
669 // looking up the owner.
670 if (this.childElementIdMap_) {
671 var elem = this.getElement();
672 // See http://b/2964418 . IE9 appears to evaluate '!=' incorrectly, so
673 // using '!==' instead.
674 // TODO(user): Possibly revert this change if/when IE9 fixes the issue.
675 while (node && node !== elem) {
676 var id = node.id;
677 if (id in this.childElementIdMap_) {
678 return this.childElementIdMap_[id];
679 }
680 node = node.parentNode;
681 }
682 }
683 return null;
684 };
685
686
687 /**
688 * Handles focus events raised when the container's key event target receives
689 * keyboard focus.
690 * @param {goog.events.BrowserEvent} e Focus event to handle.
691 */
692 goog.ui.Container.prototype.handleFocus = function(e) {
693 // No-op in the base class.
694 };
695
696
697 /**
698 * Handles blur events raised when the container's key event target loses
699 * keyboard focus. The default implementation clears the highlight index.
700 * @param {goog.events.BrowserEvent} e Blur event to handle.
701 */
702 goog.ui.Container.prototype.handleBlur = function(e) {
703 this.setHighlightedIndex(-1);
704 this.setMouseButtonPressed(false);
705 // If the container loses focus, and one of its children is open, close it.
706 if (this.openItem_) {
707 this.openItem_.setOpen(false);
708 }
709 };
710
711
712 /**
713 * Attempts to handle a keyboard event, if the control is enabled, by calling
714 * {@link handleKeyEventInternal}. Considered protected; should only be used
715 * within this package and by subclasses.
716 * @param {goog.events.KeyEvent} e Key event to handle.
717 * @return {boolean} Whether the key event was handled.
718 */
719 goog.ui.Container.prototype.handleKeyEvent = function(e) {
720 if (this.isEnabled() && this.isVisible() &&
721 (this.getChildCount() != 0 || this.keyEventTarget_) &&
722 this.handleKeyEventInternal(e)) {
723 e.preventDefault();
724 e.stopPropagation();
725 return true;
726 }
727 return false;
728 };
729
730
731 /**
732 * Attempts to handle a keyboard event; returns true if the event was handled,
733 * false otherwise. If the container is enabled, and a child is highlighted,
734 * calls the child control's {@code handleKeyEvent} method to give the control
735 * a chance to handle the event first.
736 * @param {goog.events.KeyEvent} e Key event to handle.
737 * @return {boolean} Whether the event was handled by the container (or one of
738 * its children).
739 */
740 goog.ui.Container.prototype.handleKeyEventInternal = function(e) {
741 // Give the highlighted control the chance to handle the key event.
742 var highlighted = this.getHighlighted();
743 if (highlighted && typeof highlighted.handleKeyEvent == 'function' &&
744 highlighted.handleKeyEvent(e)) {
745 return true;
746 }
747
748 // Give the open control the chance to handle the key event.
749 if (this.openItem_ && this.openItem_ != highlighted &&
750 typeof this.openItem_.handleKeyEvent == 'function' &&
751 this.openItem_.handleKeyEvent(e)) {
752 return true;
753 }
754
755 // Do not handle the key event if any modifier key is pressed.
756 if (e.shiftKey || e.ctrlKey || e.metaKey || e.altKey) {
757 return false;
758 }
759
760 // Either nothing is highlighted, or the highlighted control didn't handle
761 // the key event, so attempt to handle it here.
762 switch (e.keyCode) {
763 case goog.events.KeyCodes.ESC:
764 if (this.isFocusable()) {
765 this.getKeyEventTarget().blur();
766 } else {
767 return false;
768 }
769 break;
770
771 case goog.events.KeyCodes.HOME:
772 this.highlightFirst();
773 break;
774
775 case goog.events.KeyCodes.END:
776 this.highlightLast();
777 break;
778
779 case goog.events.KeyCodes.UP:
780 if (this.orientation_ == goog.ui.Container.Orientation.VERTICAL) {
781 this.highlightPrevious();
782 } else {
783 return false;
784 }
785 break;
786
787 case goog.events.KeyCodes.LEFT:
788 if (this.orientation_ == goog.ui.Container.Orientation.HORIZONTAL) {
789 if (this.isRightToLeft()) {
790 this.highlightNext();
791 } else {
792 this.highlightPrevious();
793 }
794 } else {
795 return false;
796 }
797 break;
798
799 case goog.events.KeyCodes.DOWN:
800 if (this.orientation_ == goog.ui.Container.Orientation.VERTICAL) {
801 this.highlightNext();
802 } else {
803 return false;
804 }
805 break;
806
807 case goog.events.KeyCodes.RIGHT:
808 if (this.orientation_ == goog.ui.Container.Orientation.HORIZONTAL) {
809 if (this.isRightToLeft()) {
810 this.highlightPrevious();
811 } else {
812 this.highlightNext();
813 }
814 } else {
815 return false;
816 }
817 break;
818
819 default:
820 return false;
821 }
822
823 return true;
824 };
825
826
827 // Child component management.
828
829
830 /**
831 * Creates a DOM ID for the child control and registers it to an internal
832 * hash table to be able to find it fast by id.
833 * @param {goog.ui.Component} child The child control. Its root element has
834 * to be created yet.
835 * @private
836 */
837 goog.ui.Container.prototype.registerChildId_ = function(child) {
838 // Map the DOM ID of the control's root element to the control itself.
839 var childElem = child.getElement();
840
841 // If the control's root element doesn't have a DOM ID assign one.
842 var id = childElem.id || (childElem.id = child.getId());
843
844 // Lazily create the child element ID map on first use.
845 if (!this.childElementIdMap_) {
846 this.childElementIdMap_ = {};
847 }
848 this.childElementIdMap_[id] = child;
849 };
850
851
852 /**
853 * Adds the specified control as the last child of this container. See
854 * {@link goog.ui.Container#addChildAt} for detailed semantics.
855 * @param {goog.ui.Component} child The new child control.
856 * @param {boolean=} opt_render Whether the new child should be rendered
857 * immediately after being added (defaults to false).
858 * @override
859 */
860 goog.ui.Container.prototype.addChild = function(child, opt_render) {
861 goog.asserts.assertInstanceof(
862 child, goog.ui.Control, 'The child of a container must be a control');
863 goog.ui.Container.superClass_.addChild.call(this, child, opt_render);
864 };
865
866
867 /**
868 * Overrides {@link goog.ui.Container#getChild} to make it clear that it
869 * only returns {@link goog.ui.Control}s.
870 * @param {string} id Child component ID.
871 * @return {goog.ui.Control} The child with the given ID; null if none.
872 * @override
873 */
874 goog.ui.Container.prototype.getChild;
875
876
877 /**
878 * Overrides {@link goog.ui.Container#getChildAt} to make it clear that it
879 * only returns {@link goog.ui.Control}s.
880 * @param {number} index 0-based index.
881 * @return {goog.ui.Control} The child with the given ID; null if none.
882 * @override
883 */
884 goog.ui.Container.prototype.getChildAt;
885
886
887 /**
888 * Adds the control as a child of this container at the given 0-based index.
889 * Overrides {@link goog.ui.Component#addChildAt} by also updating the
890 * container's highlight index. Since {@link goog.ui.Component#addChild} uses
891 * {@link #addChildAt} internally, we only need to override this method.
892 * @param {goog.ui.Component} control New child.
893 * @param {number} index Index at which the new child is to be added.
894 * @param {boolean=} opt_render Whether the new child should be rendered
895 * immediately after being added (defaults to false).
896 * @override
897 */
898 goog.ui.Container.prototype.addChildAt = function(control, index, opt_render) {
899 goog.asserts.assertInstanceof(control, goog.ui.Control);
900
901 // Make sure the child control dispatches HIGHLIGHT, UNHIGHLIGHT, OPEN, and
902 // CLOSE events, and that it doesn't steal keyboard focus.
903 control.setDispatchTransitionEvents(goog.ui.Component.State.HOVER, true);
904 control.setDispatchTransitionEvents(goog.ui.Component.State.OPENED, true);
905 if (this.isFocusable() || !this.isFocusableChildrenAllowed()) {
906 control.setSupportedState(goog.ui.Component.State.FOCUSED, false);
907 }
908
909 // Disable mouse event handling by child controls.
910 control.setHandleMouseEvents(false);
911
912 var srcIndex =
913 (control.getParent() == this) ? this.indexOfChild(control) : -1;
914
915 // Let the superclass implementation do the work.
916 goog.ui.Container.superClass_.addChildAt.call(
917 this, control, index, opt_render);
918
919 if (control.isInDocument() && this.isInDocument()) {
920 this.registerChildId_(control);
921 }
922
923 this.updateHighlightedIndex_(srcIndex, index);
924 };
925
926
927 /**
928 * Updates the highlighted index when children are added or moved.
929 * @param {number} fromIndex Index of the child before it was moved, or -1 if
930 * the child was added.
931 * @param {number} toIndex Index of the child after it was moved or added.
932 * @private
933 */
934 goog.ui.Container.prototype.updateHighlightedIndex_ = function(
935 fromIndex, toIndex) {
936 if (fromIndex == -1) {
937 fromIndex = this.getChildCount();
938 }
939 if (fromIndex == this.highlightedIndex_) {
940 // The highlighted element itself was moved.
941 this.highlightedIndex_ = Math.min(this.getChildCount() - 1, toIndex);
942 } else if (
943 fromIndex > this.highlightedIndex_ && toIndex <= this.highlightedIndex_) {
944 // The control was added or moved behind the highlighted index.
945 this.highlightedIndex_++;
946 } else if (
947 fromIndex < this.highlightedIndex_ && toIndex > this.highlightedIndex_) {
948 // The control was moved from before to behind the highlighted index.
949 this.highlightedIndex_--;
950 }
951 };
952
953
954 /**
955 * Removes a child control. Overrides {@link goog.ui.Component#removeChild} by
956 * updating the highlight index. Since {@link goog.ui.Component#removeChildAt}
957 * uses {@link #removeChild} internally, we only need to override this method.
958 * @param {string|goog.ui.Component} control The ID of the child to remove, or
959 * the control itself.
960 * @param {boolean=} opt_unrender Whether to call {@code exitDocument} on the
961 * removed control, and detach its DOM from the document (defaults to
962 * false).
963 * @return {goog.ui.Control} The removed control, if any.
964 * @override
965 */
966 goog.ui.Container.prototype.removeChild = function(control, opt_unrender) {
967 control = goog.isString(control) ? this.getChild(control) : control;
968 goog.asserts.assertInstanceof(control, goog.ui.Control);
969
970 if (control) {
971 var index = this.indexOfChild(control);
972 if (index != -1) {
973 if (index == this.highlightedIndex_) {
974 control.setHighlighted(false);
975 this.highlightedIndex_ = -1;
976 } else if (index < this.highlightedIndex_) {
977 this.highlightedIndex_--;
978 }
979 }
980
981 // Remove the mapping from the child element ID map.
982 var childElem = control.getElement();
983 if (childElem && childElem.id && this.childElementIdMap_) {
984 goog.object.remove(this.childElementIdMap_, childElem.id);
985 }
986 }
987
988 control = /** @type {!goog.ui.Control} */ (
989 goog.ui.Container.superClass_.removeChild.call(
990 this, control, opt_unrender));
991
992 // Re-enable mouse event handling (in case the control is reused elsewhere).
993 control.setHandleMouseEvents(true);
994
995 return control;
996 };
997
998
999 // Container state management.
1000
1001
1002 /**
1003 * Returns the container's orientation.
1004 * @return {?goog.ui.Container.Orientation} Container orientation.
1005 */
1006 goog.ui.Container.prototype.getOrientation = function() {
1007 return this.orientation_;
1008 };
1009
1010
1011 /**
1012 * Sets the container's orientation.
1013 * @param {goog.ui.Container.Orientation} orientation Container orientation.
1014 */
1015 // TODO(attila): Do we need to support containers with dynamic orientation?
1016 goog.ui.Container.prototype.setOrientation = function(orientation) {
1017 if (this.getElement()) {
1018 // Too late.
1019 throw new Error(goog.ui.Component.Error.ALREADY_RENDERED);
1020 }
1021
1022 this.orientation_ = orientation;
1023 };
1024
1025
1026 /**
1027 * Returns true if the container's visibility is set to visible, false if
1028 * it is set to hidden. A container that is set to hidden is guaranteed
1029 * to be hidden from the user, but the reverse isn't necessarily true.
1030 * A container may be set to visible but can otherwise be obscured by another
1031 * element, rendered off-screen, or hidden using direct CSS manipulation.
1032 * @return {boolean} Whether the container is set to be visible.
1033 */
1034 goog.ui.Container.prototype.isVisible = function() {
1035 return this.visible_;
1036 };
1037
1038
1039 /**
1040 * Shows or hides the container. Does nothing if the container already has
1041 * the requested visibility. Otherwise, dispatches a SHOW or HIDE event as
1042 * appropriate, giving listeners a chance to prevent the visibility change.
1043 * @param {boolean} visible Whether to show or hide the container.
1044 * @param {boolean=} opt_force If true, doesn't check whether the container
1045 * already has the requested visibility, and doesn't dispatch any events.
1046 * @return {boolean} Whether the visibility was changed.
1047 */
1048 goog.ui.Container.prototype.setVisible = function(visible, opt_force) {
1049 if (opt_force || (this.visible_ != visible &&
1050 this.dispatchEvent(
1051 visible ? goog.ui.Component.EventType.SHOW :
1052 goog.ui.Component.EventType.HIDE))) {
1053 this.visible_ = visible;
1054
1055 var elem = this.getElement();
1056 if (elem) {
1057 goog.style.setElementShown(elem, visible);
1058 if (this.isFocusable()) {
1059 // Enable keyboard access only for enabled & visible containers.
1060 this.renderer_.enableTabIndex(
1061 this.getKeyEventTarget(), this.enabled_ && this.visible_);
1062 }
1063 if (!opt_force) {
1064 this.dispatchEvent(
1065 this.visible_ ? goog.ui.Container.EventType.AFTER_SHOW :
1066 goog.ui.Container.EventType.AFTER_HIDE);
1067 }
1068 }
1069
1070 return true;
1071 }
1072
1073 return false;
1074 };
1075
1076
1077 /**
1078 * Returns true if the container is enabled, false otherwise.
1079 * @return {boolean} Whether the container is enabled.
1080 */
1081 goog.ui.Container.prototype.isEnabled = function() {
1082 return this.enabled_;
1083 };
1084
1085
1086 /**
1087 * Enables/disables the container based on the {@code enable} argument.
1088 * Dispatches an {@code ENABLED} or {@code DISABLED} event prior to changing
1089 * the container's state, which may be caught and canceled to prevent the
1090 * container from changing state. Also enables/disables child controls.
1091 * @param {boolean} enable Whether to enable or disable the container.
1092 */
1093 goog.ui.Container.prototype.setEnabled = function(enable) {
1094 if (this.enabled_ != enable &&
1095 this.dispatchEvent(
1096 enable ? goog.ui.Component.EventType.ENABLE :
1097 goog.ui.Component.EventType.DISABLE)) {
1098 if (enable) {
1099 // Flag the container as enabled first, then update children. This is
1100 // because controls can't be enabled if their parent is disabled.
1101 this.enabled_ = true;
1102 this.forEachChild(function(child) {
1103 // Enable child control unless it is flagged.
1104 if (child.wasDisabled) {
1105 delete child.wasDisabled;
1106 } else {
1107 child.setEnabled(true);
1108 }
1109 });
1110 } else {
1111 // Disable children first, then flag the container as disabled. This is
1112 // because controls can't be disabled if their parent is already disabled.
1113 this.forEachChild(function(child) {
1114 // Disable child control, or flag it if it's already disabled.
1115 if (child.isEnabled()) {
1116 child.setEnabled(false);
1117 } else {
1118 child.wasDisabled = true;
1119 }
1120 });
1121 this.enabled_ = false;
1122 this.setMouseButtonPressed(false);
1123 }
1124
1125 if (this.isFocusable()) {
1126 // Enable keyboard access only for enabled & visible components.
1127 this.renderer_.enableTabIndex(
1128 this.getKeyEventTarget(), enable && this.visible_);
1129 }
1130 }
1131 };
1132
1133
1134 /**
1135 * Returns true if the container is focusable, false otherwise. The default
1136 * is true. Focusable containers always have a tab index and allocate a key
1137 * handler to handle keyboard events while focused.
1138 * @return {boolean} Whether the component is focusable.
1139 */
1140 goog.ui.Container.prototype.isFocusable = function() {
1141 return this.focusable_;
1142 };
1143
1144
1145 /**
1146 * Sets whether the container is focusable. The default is true. Focusable
1147 * containers always have a tab index and allocate a key handler to handle
1148 * keyboard events while focused.
1149 * @param {boolean} focusable Whether the component is to be focusable.
1150 */
1151 goog.ui.Container.prototype.setFocusable = function(focusable) {
1152 if (focusable != this.focusable_ && this.isInDocument()) {
1153 this.enableFocusHandling_(focusable);
1154 }
1155 this.focusable_ = focusable;
1156 if (this.enabled_ && this.visible_) {
1157 this.renderer_.enableTabIndex(this.getKeyEventTarget(), focusable);
1158 }
1159 };
1160
1161
1162 /**
1163 * Returns true if the container allows children to be focusable, false
1164 * otherwise. Only effective if the container is not focusable.
1165 * @return {boolean} Whether children should be focusable.
1166 */
1167 goog.ui.Container.prototype.isFocusableChildrenAllowed = function() {
1168 return this.allowFocusableChildren_;
1169 };
1170
1171
1172 /**
1173 * Sets whether the container allows children to be focusable, false
1174 * otherwise. Only effective if the container is not focusable.
1175 * @param {boolean} focusable Whether the children should be focusable.
1176 */
1177 goog.ui.Container.prototype.setFocusableChildrenAllowed = function(focusable) {
1178 this.allowFocusableChildren_ = focusable;
1179 };
1180
1181
1182 /**
1183 * @return {boolean} Whether highlighting a child component should also open it.
1184 */
1185 goog.ui.Container.prototype.isOpenFollowsHighlight = function() {
1186 return this.openFollowsHighlight_;
1187 };
1188
1189
1190 /**
1191 * Sets whether highlighting a child component should also open it.
1192 * @param {boolean} follow Whether highlighting a child component also opens it.
1193 */
1194 goog.ui.Container.prototype.setOpenFollowsHighlight = function(follow) {
1195 this.openFollowsHighlight_ = follow;
1196 };
1197
1198
1199 // Highlight management.
1200
1201
1202 /**
1203 * Returns the index of the currently highlighted item (-1 if none).
1204 * @return {number} Index of the currently highlighted item.
1205 */
1206 goog.ui.Container.prototype.getHighlightedIndex = function() {
1207 return this.highlightedIndex_;
1208 };
1209
1210
1211 /**
1212 * Highlights the item at the given 0-based index (if any). If another item
1213 * was previously highlighted, it is un-highlighted.
1214 * @param {number} index Index of item to highlight (-1 removes the current
1215 * highlight).
1216 */
1217 goog.ui.Container.prototype.setHighlightedIndex = function(index) {
1218 var child = this.getChildAt(index);
1219 if (child) {
1220 child.setHighlighted(true);
1221 } else if (this.highlightedIndex_ > -1) {
1222 this.getHighlighted().setHighlighted(false);
1223 }
1224 };
1225
1226
1227 /**
1228 * Highlights the given item if it exists and is a child of the container;
1229 * otherwise un-highlights the currently highlighted item.
1230 * @param {goog.ui.Control} item Item to highlight.
1231 */
1232 goog.ui.Container.prototype.setHighlighted = function(item) {
1233 this.setHighlightedIndex(this.indexOfChild(item));
1234 };
1235
1236
1237 /**
1238 * Returns the currently highlighted item (if any).
1239 * @return {goog.ui.Control?} Highlighted item (null if none).
1240 */
1241 goog.ui.Container.prototype.getHighlighted = function() {
1242 return this.getChildAt(this.highlightedIndex_);
1243 };
1244
1245
1246 /**
1247 * Highlights the first highlightable item in the container
1248 */
1249 goog.ui.Container.prototype.highlightFirst = function() {
1250 this.highlightHelper(function(index, max) {
1251 return (index + 1) % max;
1252 }, this.getChildCount() - 1);
1253 };
1254
1255
1256 /**
1257 * Highlights the last highlightable item in the container.
1258 */
1259 goog.ui.Container.prototype.highlightLast = function() {
1260 this.highlightHelper(function(index, max) {
1261 index--;
1262 return index < 0 ? max - 1 : index;
1263 }, 0);
1264 };
1265
1266
1267 /**
1268 * Highlights the next highlightable item (or the first if nothing is currently
1269 * highlighted).
1270 */
1271 goog.ui.Container.prototype.highlightNext = function() {
1272 this.highlightHelper(function(index, max) {
1273 return (index + 1) % max;
1274 }, this.highlightedIndex_);
1275 };
1276
1277
1278 /**
1279 * Highlights the previous highlightable item (or the last if nothing is
1280 * currently highlighted).
1281 */
1282 goog.ui.Container.prototype.highlightPrevious = function() {
1283 this.highlightHelper(function(index, max) {
1284 index--;
1285 return index < 0 ? max - 1 : index;
1286 }, this.highlightedIndex_);
1287 };
1288
1289
1290 /**
1291 * Helper function that manages the details of moving the highlight among
1292 * child controls in response to keyboard events.
1293 * @param {function(this: goog.ui.Container, number, number) : number} fn
1294 * Function that accepts the current and maximum indices, and returns the
1295 * next index to check.
1296 * @param {number} startIndex Start index.
1297 * @return {boolean} Whether the highlight has changed.
1298 * @protected
1299 */
1300 goog.ui.Container.prototype.highlightHelper = function(fn, startIndex) {
1301 // If the start index is -1 (meaning there's nothing currently highlighted),
1302 // try starting from the currently open item, if any.
1303 var curIndex =
1304 startIndex < 0 ? this.indexOfChild(this.openItem_) : startIndex;
1305 var numItems = this.getChildCount();
1306
1307 curIndex = fn.call(this, curIndex, numItems);
1308 var visited = 0;
1309 while (visited <= numItems) {
1310 var control = this.getChildAt(curIndex);
1311 if (control && this.canHighlightItem(control)) {
1312 this.setHighlightedIndexFromKeyEvent(curIndex);
1313 return true;
1314 }
1315 visited++;
1316 curIndex = fn.call(this, curIndex, numItems);
1317 }
1318 return false;
1319 };
1320
1321
1322 /**
1323 * Returns whether the given item can be highlighted.
1324 * @param {goog.ui.Control} item The item to check.
1325 * @return {boolean} Whether the item can be highlighted.
1326 * @protected
1327 */
1328 goog.ui.Container.prototype.canHighlightItem = function(item) {
1329 return item.isVisible() && item.isEnabled() &&
1330 item.isSupportedState(goog.ui.Component.State.HOVER);
1331 };
1332
1333
1334 /**
1335 * Helper method that sets the highlighted index to the given index in response
1336 * to a keyboard event. The base class implementation simply calls the
1337 * {@link #setHighlightedIndex} method, but subclasses can override this
1338 * behavior as needed.
1339 * @param {number} index Index of item to highlight.
1340 * @protected
1341 */
1342 goog.ui.Container.prototype.setHighlightedIndexFromKeyEvent = function(index) {
1343 this.setHighlightedIndex(index);
1344 };
1345
1346
1347 /**
1348 * Returns the currently open (expanded) control in the container (null if
1349 * none).
1350 * @return {goog.ui.Control?} The currently open control.
1351 */
1352 goog.ui.Container.prototype.getOpenItem = function() {
1353 return this.openItem_;
1354 };
1355
1356
1357 /**
1358 * Returns true if the mouse button is pressed, false otherwise.
1359 * @return {boolean} Whether the mouse button is pressed.
1360 */
1361 goog.ui.Container.prototype.isMouseButtonPressed = function() {
1362 return this.mouseButtonPressed_;
1363 };
1364
1365
1366 /**
1367 * Sets or clears the "mouse button pressed" flag.
1368 * @param {boolean} pressed Whether the mouse button is presed.
1369 */
1370 goog.ui.Container.prototype.setMouseButtonPressed = function(pressed) {
1371 this.mouseButtonPressed_ = pressed;
1372 };