Debian Codegraph @

closure-library/closure/goog/ui/popupmenu.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 menu class for showing popups. A single popup can be
17 * attached to multiple anchor points. The menu will try to reposition itself
18 * if it goes outside the viewport.
19 *
20 * Decoration is the same as goog.ui.Menu except that the outer DIV can have a
21 * 'for' property, which is the ID of the element which triggers the popup.
22 *
23 * Decorate Example:
24 * <button id="dButton">Decorated Popup</button>
25 * <div id="dMenu" for="dButton" class="goog-menu">
26 * <div class="goog-menuitem">A a</div>
27 * <div class="goog-menuitem">B b</div>
28 * <div class="goog-menuitem">C c</div>
29 * <div class="goog-menuitem">D d</div>
30 * <div class="goog-menuitem">E e</div>
31 * <div class="goog-menuitem">F f</div>
32 * </div>
33 *
34 * TESTED=FireFox 2.0, IE6, Opera 9, Chrome.
35 * TODO(user): Key handling is flakey in Opera and Chrome
36 *
37 * @see ../demos/popupmenu.html
38 */
39
40 goog.provide('goog.ui.PopupMenu');
41
42 goog.require('goog.events');
43 goog.require('goog.events.BrowserEvent');
44 goog.require('goog.events.EventType');
45 goog.require('goog.events.KeyCodes');
46 goog.require('goog.positioning.AnchoredViewportPosition');
47 goog.require('goog.positioning.Corner');
48 goog.require('goog.positioning.MenuAnchoredPosition');
49 goog.require('goog.positioning.Overflow');
50 goog.require('goog.positioning.ViewportClientPosition');
51 goog.require('goog.structs.Map');
52 goog.require('goog.style');
53 goog.require('goog.ui.Component');
54 goog.require('goog.ui.Menu');
55 goog.require('goog.ui.PopupBase');
56
57
58
59 /**
60 * A basic menu class.
61 * @param {?goog.dom.DomHelper=} opt_domHelper Optional DOM helper.
62 * @param {?goog.ui.MenuRenderer=} opt_renderer Renderer used to render or
63 * decorate the container; defaults to {@link goog.ui.MenuRenderer}.
64 * @extends {goog.ui.Menu}
65 * @constructor
66 */
67 goog.ui.PopupMenu = function(opt_domHelper, opt_renderer) {
68 goog.ui.Menu.call(this, opt_domHelper, opt_renderer);
69
70 this.setAllowAutoFocus(true);
71
72 // Popup menus are hidden by default.
73 this.setVisible(false, true);
74
75 /**
76 * Map of attachment points for the menu. Key -> Object
77 * @type {!goog.structs.Map}
78 * @private
79 */
80 this.targets_ = new goog.structs.Map();
81 };
82 goog.inherits(goog.ui.PopupMenu, goog.ui.Menu);
83 goog.tagUnsealableClass(goog.ui.PopupMenu);
84
85
86 /**
87 * If true, then if the menu will toggle off if it is already visible.
88 * @type {boolean}
89 * @private
90 */
91 goog.ui.PopupMenu.prototype.toggleMode_ = false;
92
93
94 /**
95 * Time that the menu was last shown.
96 * @type {number}
97 * @private
98 */
99 goog.ui.PopupMenu.prototype.lastHide_ = 0;
100
101
102 /**
103 * Current element where the popup menu is anchored.
104 * @type {?Element}
105 * @private
106 */
107 goog.ui.PopupMenu.prototype.currentAnchor_ = null;
108
109
110 /**
111 * Decorate an existing HTML structure with the menu. Menu items will be
112 * constructed from elements with classname 'goog-menuitem', separators will be
113 * made from HR elements.
114 * @param {?Element} element Element to decorate.
115 * @override
116 */
117 goog.ui.PopupMenu.prototype.decorateInternal = function(element) {
118 goog.ui.PopupMenu.superClass_.decorateInternal.call(this, element);
119 // 'for' is a custom attribute for attaching the menu to a click target
120 var htmlFor = element.getAttribute('for') || element.htmlFor;
121 if (htmlFor) {
122 this.attach(
123 this.getDomHelper().getElement(htmlFor),
124 goog.positioning.Corner.BOTTOM_LEFT);
125 }
126 };
127
128
129 /** @override */
130 goog.ui.PopupMenu.prototype.enterDocument = function() {
131 goog.ui.PopupMenu.superClass_.enterDocument.call(this);
132
133 this.targets_.forEach(this.attachEvent_, this);
134
135 var handler = this.getHandler();
136 handler.listen(this, goog.ui.Component.EventType.ACTION, this.onAction_);
137 handler.listen(
138 this.getDomHelper().getDocument(), goog.events.EventType.MOUSEDOWN,
139 this.onDocClick, true);
140 };
141
142
143 /**
144 * Attaches the menu to a new popup position and anchor element. A menu can
145 * only be attached to an element once, since attaching the same menu for
146 * multiple positions doesn't make sense.
147 *
148 * @param {?Element} element Element whose click event should trigger the menu.
149 * @param {?goog.positioning.Corner=} opt_targetCorner Corner of the target that
150 * the menu should be anchored to.
151 * @param {goog.positioning.Corner=} opt_menuCorner Corner of the menu that
152 * should be anchored.
153 * @param {boolean=} opt_contextMenu Whether the menu should show on
154 * {@link goog.events.EventType.CONTEXTMENU} events, false if it should
155 * show on {@link goog.events.EventType.MOUSEDOWN} events. Default is
156 * MOUSEDOWN.
157 * @param {?goog.math.Box=} opt_margin Margin for the popup used in positioning
158 * algorithms.
159 */
160 goog.ui.PopupMenu.prototype.attach = function(
161 element, opt_targetCorner, opt_menuCorner, opt_contextMenu, opt_margin) {
162
163 if (this.isAttachTarget(element)) {
164 // Already in the popup, so just return.
165 return;
166 }
167
168 var target = this.createAttachTarget(
169 element, opt_targetCorner, opt_menuCorner, opt_contextMenu, opt_margin);
170
171 if (this.isInDocument()) {
172 this.attachEvent_(target);
173 }
174
175 // Add a listener for keyboard actions on the menu.
176 var handler = goog.partial(this.onMenuKeyboardAction_, element);
177 if (this.getElement()) {
178 this.getHandler().listen(
179 this.getElement(), goog.events.EventType.KEYDOWN, handler);
180 }
181 };
182
183
184 /**
185 * Handles keyboard actions on the PopupMenu, according to
186 * http://www.w3.org/WAI/PF/aria-practices/#menubutton.
187 *
188 * <p>If the ESC key is pressed, the menu is hidden (which is handled by
189 * this.onAction_), and the focus is returned to the element whose click event
190 * triggered opening of the menu.
191 *
192 * <p>If the SPACE or ENTER keys are pressed, the highlighted menu item's
193 * listeners are fired.
194 *
195 * @param {Element} element Element whose click event triggered the menu.
196 * @param {!goog.events.BrowserEvent} e The key down event.
197 * @private
198 */
199 goog.ui.PopupMenu.prototype.onMenuKeyboardAction_ = function(element, e) {
200 if (e.keyCode == goog.events.KeyCodes.ESC) {
201 element.focus();
202 return;
203 }
204 var highlightedItem = this.getChildAt(this.getHighlightedIndex());
205 if (!highlightedItem) {
206 return;
207 }
208 var targetElement = highlightedItem.getElement();
209 // Create an event to pass to the menu item's listener.
210 var event = new goog.events.BrowserEvent(e.getBrowserEvent(), targetElement);
211 event.target = targetElement;
212 // If an item is highlighted and the user presses the SPACE/ENTER key, the
213 // event target is the menu rather than the menu item, so we manually fire
214 // the listener of the correct menu item.
215 if (e.keyCode == goog.events.KeyCodes.SPACE ||
216 e.keyCode == goog.events.KeyCodes.ENTER) {
217 goog.events.fireListeners(
218 targetElement, goog.events.EventType.KEYDOWN, false, event);
219 }
220 // After activating a menu item the PopupMenu should be hidden (already
221 // implemented in this.onAction_ for ENTER/MOUSEDOWN).
222 if (e.keyCode == goog.events.KeyCodes.SPACE) {
223 this.hide();
224 }
225 };
226
227
228 /**
229 * Creates an object describing how the popup menu should be attached to the
230 * anchoring element based on the given parameters. The created object is
231 * stored, keyed by {@code element} and is retrievable later by invoking
232 * {@link #getAttachTarget(element)} at a later point.
233 *
234 * Subclass may add more properties to the returned object, as needed.
235 *
236 * @param {?Element} element Element whose click event should trigger the menu.
237 * @param {?goog.positioning.Corner=} opt_targetCorner Corner of the target that
238 * the menu should be anchored to.
239 * @param {?goog.positioning.Corner=} opt_menuCorner Corner of the menu that
240 * should be anchored.
241 * @param {boolean=} opt_contextMenu Whether the menu should show on
242 * {@link goog.events.EventType.CONTEXTMENU} events, false if it should
243 * show on {@link goog.events.EventType.MOUSEDOWN} events. Default is
244 * MOUSEDOWN.
245 * @param {?goog.math.Box=} opt_margin Margin for the popup used in positioning
246 * algorithms.
247 *
248 * @return {?Object} An object that describes how the popup menu should be
249 * attached to the anchoring element.
250 *
251 * @protected
252 */
253 goog.ui.PopupMenu.prototype.createAttachTarget = function(
254 element, opt_targetCorner, opt_menuCorner, opt_contextMenu, opt_margin) {
255 if (!element) {
256 return null;
257 }
258
259 var target = {
260 element_: element,
261 targetCorner_: opt_targetCorner,
262 menuCorner_: opt_menuCorner,
263 eventType_: opt_contextMenu ? goog.events.EventType.CONTEXTMENU :
264 goog.events.EventType.MOUSEDOWN,
265 margin_: opt_margin
266 };
267
268 this.targets_.set(goog.getUid(element), target);
269
270 return target;
271 };
272
273
274 /**
275 * Returns the object describing how the popup menu should be attach to given
276 * element or {@code null}. The object is created and the association is formed
277 * when {@link #attach} is invoked.
278 *
279 * @param {?Element} element DOM element.
280 * @return {?Object} The object created when {@link attach} is invoked on
281 * {@code element}. Returns {@code null} if the element does not trigger
282 * the menu (i.e. {@link attach} has never been invoked on
283 * {@code element}).
284 * @protected
285 */
286 goog.ui.PopupMenu.prototype.getAttachTarget = function(element) {
287 return element ?
288 /** @type {?Object} */ (this.targets_.get(goog.getUid(element))) :
289 null;
290 };
291
292
293 /**
294 * @param {?Element} element Any DOM element.
295 * @return {boolean} Whether clicking on the given element will trigger the
296 * menu.
297 *
298 * @protected
299 */
300 goog.ui.PopupMenu.prototype.isAttachTarget = function(element) {
301 return element ? this.targets_.containsKey(goog.getUid(element)) : false;
302 };
303
304
305 /**
306 * @return {?Element} The current element where the popup is anchored, if it's
307 * visible.
308 */
309 goog.ui.PopupMenu.prototype.getAttachedElement = function() {
310 return this.currentAnchor_;
311 };
312
313
314 /**
315 * Attaches two event listeners to a target. One with corresponding event type,
316 * and one with the KEYDOWN event type for accessibility purposes.
317 * @param {?Object} target The target to attach an event to.
318 * @private
319 */
320 goog.ui.PopupMenu.prototype.attachEvent_ = function(target) {
321 this.getHandler().listen(
322 target.element_, target.eventType_, this.onTargetClick_);
323 if (target.eventType_ != goog.events.EventType.CONTEXTMENU) {
324 this.getHandler().listen(
325 target.element_, goog.events.EventType.KEYDOWN,
326 this.onTargetKeyboardAction_);
327 }
328 };
329
330
331 /**
332 * Detaches all listeners
333 */
334 goog.ui.PopupMenu.prototype.detachAll = function() {
335 if (this.isInDocument()) {
336 var keys = this.targets_.getKeys();
337 for (var i = 0; i < keys.length; i++) {
338 this.detachEvent_(/** @type {!Object} */ (this.targets_.get(keys[i])));
339 }
340 }
341
342 this.targets_.clear();
343 };
344
345
346 /**
347 * Detaches a menu from a given element.
348 * @param {?Element} element Element whose click event should trigger the menu.
349 */
350 goog.ui.PopupMenu.prototype.detach = function(element) {
351 if (!this.isAttachTarget(element)) {
352 throw new Error('Menu not attached to provided element, unable to detach.');
353 }
354
355 var key = goog.getUid(element);
356 if (this.isInDocument()) {
357 this.detachEvent_(/** @type {!Object} */ (this.targets_.get(key)));
358 }
359
360 this.targets_.remove(key);
361 };
362
363
364 /**
365 * Detaches an event listener to a target
366 * @param {!Object} target The target to detach events from.
367 * @private
368 */
369 goog.ui.PopupMenu.prototype.detachEvent_ = function(target) {
370 this.getHandler().unlisten(
371 target.element_, target.eventType_, this.onTargetClick_);
372 };
373
374
375 /**
376 * Sets whether the menu should toggle if it is already open. For context
377 * menus this should be false, for toolbar menus it makes more sense to be true.
378 * @param {boolean} toggle The new toggle mode.
379 */
380 goog.ui.PopupMenu.prototype.setToggleMode = function(toggle) {
381 this.toggleMode_ = toggle;
382 };
383
384
385 /**
386 * Gets whether the menu is in toggle mode
387 * @return {boolean} toggle.
388 */
389 goog.ui.PopupMenu.prototype.getToggleMode = function() {
390 return this.toggleMode_;
391 };
392
393
394 /**
395 * Show the menu using given positioning object.
396 * @param {?goog.positioning.AbstractPosition} position The positioning
397 * instance.
398 * @param {goog.positioning.Corner=} opt_menuCorner The corner of the menu to be
399 * positioned.
400 * @param {?goog.math.Box=} opt_margin A margin specified in pixels.
401 * @param {?Element=} opt_anchor The element which acts as visual anchor for
402 * this menu.
403 */
404 goog.ui.PopupMenu.prototype.showWithPosition = function(
405 position, opt_menuCorner, opt_margin, opt_anchor) {
406 var isVisible = this.isVisible();
407 if (this.isOrWasRecentlyVisible() && this.toggleMode_) {
408 this.hide();
409 return;
410 }
411
412 // Set current anchor before dispatching BEFORE_SHOW. This is typically useful
413 // when we would need to make modifications based on the current anchor to the
414 // menu just before displaying it.
415 this.currentAnchor_ = opt_anchor || null;
416
417 // Notify event handlers that the menu is about to be shown.
418 if (!this.dispatchEvent(goog.ui.Component.EventType.BEFORE_SHOW)) {
419 return;
420 }
421
422 var menuCorner = typeof opt_menuCorner != 'undefined' ?
423 opt_menuCorner :
424 goog.positioning.Corner.TOP_START;
425
426 // This is a little hacky so that we can position the menu with minimal
427 // flicker.
428
429 if (!isVisible) {
430 // On IE, setting visibility = 'hidden' on a visible menu
431 // will cause a blur, forcing the menu to close immediately.
432 this.getElement().style.visibility = 'hidden';
433 }
434
435 goog.style.setElementShown(this.getElement(), true);
436 position.reposition(this.getElement(), menuCorner, opt_margin);
437
438 if (!isVisible) {
439 this.getElement().style.visibility = 'visible';
440 }
441
442 this.setHighlightedIndex(-1);
443
444 // setVisible dispatches a goog.ui.Component.EventType.SHOW event, which may
445 // be canceled to prevent the menu from being shown.
446 this.setVisible(true);
447 };
448
449
450 /**
451 * Show the menu at a given attached target.
452 * @param {!Object} target Popup target.
453 * @param {number} x The client-X associated with the show event.
454 * @param {number} y The client-Y associated with the show event.
455 * @protected
456 */
457 goog.ui.PopupMenu.prototype.showMenu = function(target, x, y) {
458 var position = goog.isDef(target.targetCorner_) ?
459 new goog.positioning.AnchoredViewportPosition(
460 target.element_, target.targetCorner_, true) :
461 new goog.positioning.ViewportClientPosition(x, y);
462 if (position.setLastResortOverflow) {
463 // This is a ViewportClientPosition, so we can set the overflow policy.
464 // Allow the menu to slide from the corner rather than clipping if it is
465 // completely impossible to fit it otherwise.
466 position.setLastResortOverflow(
467 goog.positioning.Overflow.ADJUST_X |
468 goog.positioning.Overflow.ADJUST_Y);
469 }
470 this.showWithPosition(
471 position, target.menuCorner_, target.margin_, target.element_);
472 };
473
474
475 /**
476 * Shows the menu immediately at the given client coordinates.
477 * @param {number} x The client-X associated with the show event.
478 * @param {number} y The client-Y associated with the show event.
479 * @param {goog.positioning.Corner=} opt_menuCorner Corner of the menu that
480 * should be anchored.
481 */
482 goog.ui.PopupMenu.prototype.showAt = function(x, y, opt_menuCorner) {
483 this.showWithPosition(
484 new goog.positioning.ViewportClientPosition(x, y), opt_menuCorner);
485 };
486
487
488 /**
489 * Shows the menu immediately attached to the given element
490 * @param {?Element} element The element to show at.
491 * @param {goog.positioning.Corner} targetCorner The corner of the target to
492 * anchor to.
493 * @param {goog.positioning.Corner=} opt_menuCorner Corner of the menu that
494 * should be anchored.
495 */
496 goog.ui.PopupMenu.prototype.showAtElement = function(
497 element, targetCorner, opt_menuCorner) {
498 this.showWithPosition(
499 new goog.positioning.MenuAnchoredPosition(element, targetCorner, true),
500 opt_menuCorner, null, element);
501 };
502
503
504 /**
505 * Hides the menu.
506 */
507 goog.ui.PopupMenu.prototype.hide = function() {
508 if (!this.isVisible()) {
509 return;
510 }
511
512 // setVisible dispatches a goog.ui.Component.EventType.HIDE event, which may
513 // be canceled to prevent the menu from being hidden.
514 this.setVisible(false);
515 if (!this.isVisible()) {
516 // HIDE event wasn't canceled; the menu is now hidden.
517 this.lastHide_ = goog.now();
518 this.currentAnchor_ = null;
519 }
520 };
521
522
523 /**
524 * Returns whether the menu is currently visible or was visible within about
525 * 150 ms ago. This stops the menu toggling back on if the toggleMode == false.
526 * @return {boolean} Whether the popup is currently visible or was visible
527 * within about 150 ms ago.
528 */
529 goog.ui.PopupMenu.prototype.isOrWasRecentlyVisible = function() {
530 return this.isVisible() || this.wasRecentlyHidden();
531 };
532
533
534 /**
535 * Used to stop the menu toggling back on if the toggleMode == false.
536 * @return {boolean} Whether the menu was recently hidden.
537 * @protected
538 */
539 goog.ui.PopupMenu.prototype.wasRecentlyHidden = function() {
540 return goog.now() - this.lastHide_ < goog.ui.PopupBase.DEBOUNCE_DELAY_MS;
541 };
542
543
544 /**
545 * Dismiss the popup menu when an action fires.
546 * @param {?goog.events.Event=} opt_e The optional event.
547 * @private
548 */
549 goog.ui.PopupMenu.prototype.onAction_ = function(opt_e) {
550 this.hide();
551 };
552
553
554 /**
555 * Handles a browser click event on one of the popup targets.
556 * @param {?goog.events.BrowserEvent} e The browser event.
557 * @private
558 */
559 goog.ui.PopupMenu.prototype.onTargetClick_ = function(e) {
560 this.onTargetActivation_(e);
561 };
562
563
564 /**
565 * Handles a KEYDOWN browser event on one of the popup targets.
566 * @param {!goog.events.BrowserEvent} e The browser event.
567 * @private
568 */
569 goog.ui.PopupMenu.prototype.onTargetKeyboardAction_ = function(e) {
570 if (e.keyCode == goog.events.KeyCodes.SPACE ||
571 e.keyCode == goog.events.KeyCodes.ENTER ||
572 e.keyCode == goog.events.KeyCodes.DOWN) {
573 this.onTargetActivation_(e);
574 }
575 // If the popupmenu is opened using the DOWN key, the focus should be on the
576 // first menu item.
577 if (e.keyCode == goog.events.KeyCodes.DOWN) {
578 this.highlightFirst();
579 }
580 };
581
582
583 /**
584 * Handles a browser event on one of the popup targets.
585 * @param {?goog.events.BrowserEvent} e The browser event.
586 * @private
587 */
588 goog.ui.PopupMenu.prototype.onTargetActivation_ = function(e) {
589 var keys = this.targets_.getKeys();
590 for (var i = 0; i < keys.length; i++) {
591 var target = /** @type {!Object} */ (this.targets_.get(keys[i]));
592 if (target.element_ == e.currentTarget) {
593 this.showMenu(target, (e.clientX), (e.clientY));
594 e.preventDefault();
595 e.stopPropagation();
596 return;
597 }
598 }
599 };
600
601
602 /**
603 * Handles click events that propagate to the document.
604 * @param {!goog.events.BrowserEvent} e The browser event.
605 * @protected
606 */
607 goog.ui.PopupMenu.prototype.onDocClick = function(e) {
608 if (this.isVisible() &&
609 !this.containsElement(/** @type {!Element} */ (e.target))) {
610 this.hide();
611 }
612 };
613
614
615 /**
616 * Handles the key event target losing focus.
617 * @param {?goog.events.BrowserEvent} e The browser event.
618 * @protected
619 * @override
620 */
621 goog.ui.PopupMenu.prototype.handleBlur = function(e) {
622 goog.ui.PopupMenu.superClass_.handleBlur.call(this, e);
623 this.hide();
624 };
625
626
627 /** @override */
628 goog.ui.PopupMenu.prototype.disposeInternal = function() {
629 // Always call the superclass' disposeInternal() first (Bug 715885).
630 goog.ui.PopupMenu.superClass_.disposeInternal.call(this);
631
632 // Disposes of the attachment target map.
633 if (this.targets_) {
634 this.targets_.clear();
635 delete this.targets_;
636 }
637 };