Debian Codegraph @

closure-library/closure/goog/ui/submenu.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 A class representing menu items that open a submenu.
17 * @see goog.ui.Menu
18 *
19 * @see ../demos/submenus.html
20 * @see ../demos/submenus2.html
21 */
22
23 goog.provide('goog.ui.SubMenu');
24
25 goog.require('goog.Timer');
26 goog.require('goog.asserts');
27 goog.require('goog.dom');
28 goog.require('goog.dom.classlist');
29 goog.require('goog.events.KeyCodes');
30 goog.require('goog.positioning.AnchoredViewportPosition');
31 goog.require('goog.positioning.Corner');
32 goog.require('goog.style');
33 goog.require('goog.ui.Component');
34 goog.require('goog.ui.Menu');
35 goog.require('goog.ui.MenuItem');
36 goog.require('goog.ui.SubMenuRenderer');
37 goog.require('goog.ui.registry');
38
39
40
41 /**
42 * Class representing a submenu that can be added as an item to other menus.
43 *
44 * @param {goog.ui.ControlContent} content Text caption or DOM structure to
45 * display as the content of the submenu (use to add icons or styling to
46 * menus).
47 * @param {*=} opt_model Data/model associated with the menu item.
48 * @param {goog.dom.DomHelper=} opt_domHelper Optional dom helper used for dom
49 * interactions.
50 * @param {goog.ui.MenuItemRenderer=} opt_renderer Renderer used to render or
51 * decorate the component; defaults to {@link goog.ui.SubMenuRenderer}.
52 * @constructor
53 * @extends {goog.ui.MenuItem}
54 */
55 goog.ui.SubMenu = function(content, opt_model, opt_domHelper, opt_renderer) {
56 goog.ui.MenuItem.call(
57 this, content, opt_model, opt_domHelper,
58 opt_renderer || goog.ui.SubMenuRenderer.getInstance());
59 };
60 goog.inherits(goog.ui.SubMenu, goog.ui.MenuItem);
61 goog.tagUnsealableClass(goog.ui.SubMenu);
62
63
64 /**
65 * The delay before opening the sub menu in milliseconds.
66 * @type {number}
67 */
68 goog.ui.SubMenu.MENU_DELAY_MS = 218;
69
70
71 /**
72 * Timer used to dismiss the submenu when the item becomes unhighlighted.
73 * @type {?number}
74 * @private
75 */
76 goog.ui.SubMenu.prototype.dismissTimer_ = null;
77
78
79 /**
80 * Timer used to show the submenu on mouseover.
81 * @type {?number}
82 * @private
83 */
84 goog.ui.SubMenu.prototype.showTimer_ = null;
85
86
87 /**
88 * Whether the submenu believes the menu is visible.
89 * @type {boolean}
90 * @private
91 */
92 goog.ui.SubMenu.prototype.menuIsVisible_ = false;
93
94
95 /**
96 * The lazily created sub menu.
97 * @type {goog.ui.Menu?}
98 * @private
99 */
100 goog.ui.SubMenu.prototype.subMenu_ = null;
101
102
103 /**
104 * Whether or not the sub-menu was set explicitly.
105 * @type {boolean}
106 * @private
107 */
108 goog.ui.SubMenu.prototype.externalSubMenu_ = false;
109
110
111 /**
112 * Whether or not to align the submenu at the end of the parent menu.
113 * If true, the menu expands to the right in LTR languages and to the left
114 * in RTL langauges.
115 * @type {boolean}
116 * @private
117 */
118 goog.ui.SubMenu.prototype.alignToEnd_ = true;
119
120
121 /**
122 * Whether the position of this submenu may be adjusted to fit
123 * the visible area, as in {@link goog.ui.Popup.positionAtCoordinate}.
124 * @type {boolean}
125 * @private
126 */
127 goog.ui.SubMenu.prototype.isPositionAdjustable_ = false;
128
129
130 /** @override */
131 goog.ui.SubMenu.prototype.enterDocument = function() {
132 goog.ui.SubMenu.superClass_.enterDocument.call(this);
133
134 this.getHandler().listen(
135 this.getParent(), goog.ui.Component.EventType.HIDE, this.onParentHidden_);
136
137 if (this.subMenu_) {
138 this.setMenuListenersEnabled_(this.subMenu_, true);
139 }
140 };
141
142
143 /** @override */
144 goog.ui.SubMenu.prototype.exitDocument = function() {
145 this.getHandler().unlisten(
146 this.getParent(), goog.ui.Component.EventType.HIDE, this.onParentHidden_);
147
148 if (this.subMenu_) {
149 this.setMenuListenersEnabled_(this.subMenu_, false);
150 if (!this.externalSubMenu_) {
151 this.subMenu_.exitDocument();
152 goog.dom.removeNode(this.subMenu_.getElement());
153 }
154 }
155
156 goog.ui.SubMenu.superClass_.exitDocument.call(this);
157 };
158
159
160 /** @override */
161 goog.ui.SubMenu.prototype.disposeInternal = function() {
162 if (this.subMenu_ && !this.externalSubMenu_) {
163 this.subMenu_.dispose();
164 }
165 this.subMenu_ = null;
166 goog.ui.SubMenu.superClass_.disposeInternal.call(this);
167 };
168
169
170 /**
171 * @override
172 * Dismisses the submenu on a delay, with the result that the user needs less
173 * accuracy when moving to submenus. Alternate implementations could use
174 * geometry instead of a timer.
175 * @param {boolean} highlight Whether item should be highlighted.
176 * @param {boolean=} opt_btnPressed Whether the mouse button is held down.
177 */
178 goog.ui.SubMenu.prototype.setHighlighted = function(highlight, opt_btnPressed) {
179 goog.ui.SubMenu.superClass_.setHighlighted.call(this, highlight);
180
181 if (opt_btnPressed) {
182 this.getMenu().setMouseButtonPressed(true);
183 }
184
185 if (!highlight) {
186 if (this.dismissTimer_) {
187 goog.Timer.clear(this.dismissTimer_);
188 }
189 this.dismissTimer_ = goog.Timer.callOnce(
190 this.dismissSubMenu, goog.ui.SubMenu.MENU_DELAY_MS, this);
191 }
192 };
193
194
195 /**
196 * Show the submenu and ensure that all siblings are hidden.
197 */
198 goog.ui.SubMenu.prototype.showSubMenu = function() {
199 // Only show the menu if this item is still selected. This is called on a
200 // timeout, so make sure our parent still exists.
201 var parent = this.getParent();
202 if (parent && parent.getHighlighted() == this) {
203 this.setSubMenuVisible_(true);
204 this.dismissSiblings_();
205 }
206 };
207
208
209 /**
210 * Dismisses the menu and all further submenus.
211 */
212 goog.ui.SubMenu.prototype.dismissSubMenu = function() {
213 // Because setHighlighted calls this function on a timeout, we need to make
214 // sure that the sub menu hasn't been disposed when we come back.
215 var subMenu = this.subMenu_;
216 if (subMenu && subMenu.getParent() == this) {
217 this.setSubMenuVisible_(false);
218 subMenu.forEachChild(function(child) {
219 if (typeof child.dismissSubMenu == 'function') {
220 child.dismissSubMenu();
221 }
222 });
223 }
224 };
225
226
227 /**
228 * Clears the show and hide timers for the sub menu.
229 */
230 goog.ui.SubMenu.prototype.clearTimers = function() {
231 if (this.dismissTimer_) {
232 goog.Timer.clear(this.dismissTimer_);
233 }
234 if (this.showTimer_) {
235 goog.Timer.clear(this.showTimer_);
236 }
237 };
238
239
240 /**
241 * Sets the menu item to be visible or invisible.
242 * @param {boolean} visible Whether to show or hide the component.
243 * @param {boolean=} opt_force If true, doesn't check whether the component
244 * already has the requested visibility, and doesn't dispatch any events.
245 * @return {boolean} Whether the visibility was changed.
246 * @override
247 */
248 goog.ui.SubMenu.prototype.setVisible = function(visible, opt_force) {
249 var visibilityChanged =
250 goog.ui.SubMenu.superClass_.setVisible.call(this, visible, opt_force);
251 // For menus that allow menu items to be hidden (i.e. ComboBox) ensure that
252 // the submenu is hidden.
253 if (visibilityChanged && !this.isVisible()) {
254 this.dismissSubMenu();
255 }
256 return visibilityChanged;
257 };
258
259
260 /**
261 * Dismiss all the sub menus of sibling menu items.
262 * @private
263 */
264 goog.ui.SubMenu.prototype.dismissSiblings_ = function() {
265 this.getParent().forEachChild(function(child) {
266 if (child != this && typeof child.dismissSubMenu == 'function') {
267 child.dismissSubMenu();
268 child.clearTimers();
269 }
270 }, this);
271 };
272
273
274 /**
275 * Handles a key event that is passed to the menu item from its parent because
276 * it is highlighted. If the right key is pressed the sub menu takes control
277 * and delegates further key events to its menu until it is dismissed OR the
278 * left key is pressed.
279 * @param {goog.events.KeyEvent} e A key event.
280 * @return {boolean} Whether the event was handled.
281 * @override
282 */
283 goog.ui.SubMenu.prototype.handleKeyEvent = function(e) {
284 var keyCode = e.keyCode;
285 var openKeyCode = this.isRightToLeft() ? goog.events.KeyCodes.LEFT :
286 goog.events.KeyCodes.RIGHT;
287 var closeKeyCode = this.isRightToLeft() ? goog.events.KeyCodes.RIGHT :
288 goog.events.KeyCodes.LEFT;
289
290 if (!this.menuIsVisible_) {
291 // Menu item doesn't have keyboard control and the right key was pressed.
292 // So open take keyboard control and open the sub menu.
293 if (this.isEnabled() &&
294 (keyCode == openKeyCode || keyCode == this.getMnemonic())) {
295 this.showSubMenu();
296 this.getMenu().highlightFirst();
297 this.clearTimers();
298
299 // The menu item doesn't currently care about the key events so let the
300 // parent menu handle them accordingly .
301 } else {
302 return false;
303 }
304
305 // Menu item has control, so let its menu try to handle the keys (this may
306 // in turn be handled by sub-sub menus).
307 } else if (this.getMenu().handleKeyEvent(e)) {
308 // Nothing to do
309
310 // The menu has control and the key hasn't yet been handled, on left arrow
311 // we turn off key control.
312 } else if (keyCode == closeKeyCode) {
313 this.dismissSubMenu();
314
315 } else {
316 // Submenu didn't handle the key so let the parent decide what to do.
317 return false;
318 }
319
320 e.preventDefault();
321 return true;
322 };
323
324
325 /**
326 * Listens to the sub menus items and ensures that this menu item is selected
327 * while dismissing the others. This handles the case when the user mouses
328 * over other items on their way to the sub menu.
329 * @param {goog.events.Event} e Enter event to handle.
330 * @private
331 */
332 goog.ui.SubMenu.prototype.onChildEnter_ = function(e) {
333 if (this.subMenu_.getParent() == this) {
334 this.clearTimers();
335 this.getParentEventTarget().setHighlighted(this);
336 this.dismissSiblings_();
337 }
338 };
339
340
341 /**
342 * Listens to the parent menu's hide event and ensures that all submenus are
343 * hidden at the same time.
344 * @param {goog.events.Event} e The event.
345 * @private
346 */
347 goog.ui.SubMenu.prototype.onParentHidden_ = function(e) {
348 // Ignore propagated events
349 if (e.target == this.getParentEventTarget()) {
350 // TODO(user): Using an event for this is expensive. Consider having a
351 // generalized interface that the parent menu calls on its children when
352 // it is hidden.
353 this.dismissSubMenu();
354 this.clearTimers();
355 }
356 };
357
358
359 /**
360 * @override
361 * Sets a timer to show the submenu and then dispatches an ENTER event to the
362 * parent menu.
363 * @param {goog.events.BrowserEvent} e Mouse event to handle.
364 * @protected
365 */
366 goog.ui.SubMenu.prototype.handleMouseOver = function(e) {
367 if (this.isEnabled()) {
368 this.clearTimers();
369 this.showTimer_ = goog.Timer.callOnce(
370 this.showSubMenu, goog.ui.SubMenu.MENU_DELAY_MS, this);
371 }
372 goog.ui.SubMenu.superClass_.handleMouseOver.call(this, e);
373 };
374
375
376 /**
377 * Overrides the default mouseup event handler, so that the ACTION isn't
378 * dispatched for the submenu itself, instead the submenu is shown instantly.
379 * @param {goog.events.Event} e The browser event.
380 * @return {boolean} True if the action was allowed to proceed, false otherwise.
381 * @override
382 */
383 goog.ui.SubMenu.prototype.performActionInternal = function(e) {
384 this.clearTimers();
385 var shouldHandleClick =
386 this.isSupportedState(goog.ui.Component.State.SELECTED) ||
387 this.isSupportedState(goog.ui.Component.State.CHECKED);
388 if (shouldHandleClick) {
389 return goog.ui.SubMenu.superClass_.performActionInternal.call(this, e);
390 } else {
391 this.showSubMenu();
392 return true;
393 }
394 };
395
396
397 /**
398 * Sets the visiblility of the sub menu.
399 * @param {boolean} visible Whether to show menu.
400 * @private
401 */
402 goog.ui.SubMenu.prototype.setSubMenuVisible_ = function(visible) {
403 // Unhighlighting the menuitems if closing the menu so the event handlers can
404 // determine the correct state.
405 if (!visible && this.getMenu()) {
406 this.getMenu().setHighlightedIndex(-1);
407 }
408
409 // Dispatch OPEN event before calling getMenu(), so we can create the menu
410 // lazily on first access.
411 this.dispatchEvent(
412 goog.ui.Component.getStateTransitionEvent(
413 goog.ui.Component.State.OPENED, visible));
414 var subMenu = this.getMenu();
415 if (visible != this.menuIsVisible_) {
416 goog.dom.classlist.enable(
417 goog.asserts.assert(this.getElement()),
418 goog.getCssName('goog-submenu-open'), visible);
419 }
420 if (visible != subMenu.isVisible()) {
421 if (visible) {
422 // Lazy-render menu when first shown, if needed.
423 if (!subMenu.isInDocument()) {
424 subMenu.render();
425 }
426 subMenu.setHighlightedIndex(-1);
427 }
428 subMenu.setVisible(visible);
429 // We must position after the menu is visible, otherwise positioning logic
430 // breaks in RTL.
431 if (visible) {
432 this.positionSubMenu();
433 }
434 }
435 this.menuIsVisible_ = visible;
436 };
437
438
439 /**
440 * Attaches or detaches menu event listeners to/from the given menu. Called
441 * each time a menu is attached to or detached from the submenu.
442 * @param {goog.ui.Menu} menu Menu on which to listen for events.
443 * @param {boolean} attach Whether to attach or detach event listeners.
444 * @private
445 */
446 goog.ui.SubMenu.prototype.setMenuListenersEnabled_ = function(menu, attach) {
447 var handler = this.getHandler();
448 var method = attach ? handler.listen : handler.unlisten;
449 method.call(
450 handler, menu, goog.ui.Component.EventType.ENTER, this.onChildEnter_);
451 };
452
453
454 /**
455 * Sets whether the submenu is aligned at the end of the parent menu.
456 * @param {boolean} alignToEnd True to align to end, false to align to start.
457 */
458 goog.ui.SubMenu.prototype.setAlignToEnd = function(alignToEnd) {
459 if (alignToEnd != this.alignToEnd_) {
460 this.alignToEnd_ = alignToEnd;
461 if (this.isInDocument()) {
462 // Completely re-render the widget.
463 var oldElement = this.getElement();
464 this.exitDocument();
465
466 if (oldElement.nextSibling) {
467 this.renderBefore(/** @type {!Element} */ (oldElement.nextSibling));
468 } else {
469 this.render(/** @type {Element} */ (oldElement.parentNode));
470 }
471 }
472 }
473 };
474
475
476 /**
477 * Determines whether the submenu is aligned at the end of the parent menu.
478 * @return {boolean} True if aligned to the end (the default), false if
479 * aligned to the start.
480 */
481 goog.ui.SubMenu.prototype.isAlignedToEnd = function() {
482 return this.alignToEnd_;
483 };
484
485
486 /**
487 * Positions the submenu. This method should be called if the sub menu is
488 * opened and the menu element's size changes (e.g., when adding/removing items
489 * to an opened sub menu).
490 */
491 goog.ui.SubMenu.prototype.positionSubMenu = function() {
492 var position = new goog.positioning.AnchoredViewportPosition(
493 this.getElement(),
494 this.isAlignedToEnd() ? goog.positioning.Corner.TOP_END :
495 goog.positioning.Corner.TOP_START,
496 this.isPositionAdjustable_);
497
498 // TODO(user): Clean up popup code and have this be a one line call
499 var subMenu = this.getMenu();
500 var el = subMenu.getElement();
501 if (!subMenu.isVisible()) {
502 el.style.visibility = 'hidden';
503 goog.style.setElementShown(el, true);
504 }
505
506 position.reposition(
507 el, this.isAlignedToEnd() ? goog.positioning.Corner.TOP_START :
508 goog.positioning.Corner.TOP_END);
509
510 if (!subMenu.isVisible()) {
511 goog.style.setElementShown(el, false);
512 el.style.visibility = 'visible';
513 }
514 };
515
516
517 // Methods delegated to sub-menu but accessible here for convinience
518
519
520 /**
521 * Adds a new menu item at the end of the menu.
522 * @param {goog.ui.MenuHeader|goog.ui.MenuItem|goog.ui.MenuSeparator} item Menu
523 * item to add to the menu.
524 */
525 goog.ui.SubMenu.prototype.addItem = function(item) {
526 this.getMenu().addChild(item, true);
527 };
528
529
530 /**
531 * Adds a new menu item at a specific index in the menu.
532 * @param {goog.ui.MenuHeader|goog.ui.MenuItem|goog.ui.MenuSeparator} item Menu
533 * item to add to the menu.
534 * @param {number} n Index at which to insert the menu item.
535 */
536 goog.ui.SubMenu.prototype.addItemAt = function(item, n) {
537 this.getMenu().addChildAt(item, n, true);
538 };
539
540
541 /**
542 * Removes an item from the menu and disposes it.
543 * @param {goog.ui.MenuItem} item The menu item to remove.
544 */
545 goog.ui.SubMenu.prototype.removeItem = function(item) {
546 var child = this.getMenu().removeChild(item, true);
547 if (child) {
548 child.dispose();
549 }
550 };
551
552
553 /**
554 * Removes a menu item at a given index in the menu and disposes it.
555 * @param {number} n Index of item.
556 */
557 goog.ui.SubMenu.prototype.removeItemAt = function(n) {
558 var child = this.getMenu().removeChildAt(n, true);
559 if (child) {
560 child.dispose();
561 }
562 };
563
564
565 /**
566 * Returns a reference to the menu item at a given index.
567 * @param {number} n Index of menu item.
568 * @return {goog.ui.Component} Reference to the menu item.
569 */
570 goog.ui.SubMenu.prototype.getItemAt = function(n) {
571 return this.getMenu().getChildAt(n);
572 };
573
574
575 /**
576 * Returns the number of items in the sub menu (including separators).
577 * @return {number} The number of items in the menu.
578 */
579 goog.ui.SubMenu.prototype.getItemCount = function() {
580 return this.getMenu().getChildCount();
581 };
582
583
584 /**
585 * Returns the menu items contained in the sub menu.
586 * @return {!Array<!goog.ui.MenuItem>} An array of menu items.
587 * @deprecated Use getItemAt/getItemCount instead.
588 */
589 goog.ui.SubMenu.prototype.getItems = function() {
590 return this.getMenu().getItems();
591 };
592
593
594 /**
595 * Gets a reference to the submenu's actual menu.
596 * @return {!goog.ui.Menu} Reference to the object representing the sub menu.
597 */
598 goog.ui.SubMenu.prototype.getMenu = function() {
599 if (!this.subMenu_) {
600 this.setMenu(
601 new goog.ui.Menu(this.getDomHelper()), /* opt_internal */ true);
602 } else if (this.externalSubMenu_ && this.subMenu_.getParent() != this) {
603 // Since it is possible for the same popup menu to be attached to multiple
604 // submenus, we need to ensure that it has the correct parent event target.
605 this.subMenu_.setParent(this);
606 }
607 // Always create the menu DOM, for backward compatibility.
608 if (!this.subMenu_.getElement()) {
609 this.subMenu_.createDom();
610 }
611 return this.subMenu_;
612 };
613
614
615 /**
616 * Sets the submenu to a specific menu.
617 * @param {goog.ui.Menu} menu The menu to show when this item is selected.
618 * @param {boolean=} opt_internal Whether this menu is an "internal" menu, and
619 * should be disposed of when this object is disposed of.
620 */
621 goog.ui.SubMenu.prototype.setMenu = function(menu, opt_internal) {
622 var oldMenu = this.subMenu_;
623 if (menu != oldMenu) {
624 if (oldMenu) {
625 this.dismissSubMenu();
626 if (this.isInDocument()) {
627 this.setMenuListenersEnabled_(oldMenu, false);
628 }
629 }
630
631 this.subMenu_ = menu;
632 this.externalSubMenu_ = !opt_internal;
633
634 if (menu) {
635 menu.setParent(this);
636 // There's no need to dispatch a HIDE event during submenu construction.
637 menu.setVisible(false, /* opt_force */ true);
638 menu.setAllowAutoFocus(false);
639 menu.setFocusable(false);
640 if (this.isInDocument()) {
641 this.setMenuListenersEnabled_(menu, true);
642 }
643 }
644 }
645 };
646
647
648 /**
649 * Returns true if the provided element is to be considered inside the menu for
650 * purposes such as dismissing the menu on an event. This is so submenus can
651 * make use of elements outside their own DOM.
652 * @param {Element} element The element to test for.
653 * @return {boolean} Whether or not the provided element is contained.
654 */
655 goog.ui.SubMenu.prototype.containsElement = function(element) {
656 return this.getMenu().containsElement(element);
657 };
658
659
660 /**
661 * @param {boolean} isAdjustable Whether this submenu is adjustable.
662 */
663 goog.ui.SubMenu.prototype.setPositionAdjustable = function(isAdjustable) {
664 this.isPositionAdjustable_ = !!isAdjustable;
665 };
666
667
668 /**
669 * @return {boolean} Whether this submenu is adjustable.
670 */
671 goog.ui.SubMenu.prototype.isPositionAdjustable = function() {
672 return this.isPositionAdjustable_;
673 };
674
675
676 // Register a decorator factory function for goog.ui.SubMenus.
677 goog.ui.registry.setDecoratorByClassName(
678 goog.getCssName('goog-submenu'),
679 function() { return new goog.ui.SubMenu(null); });