Debian Codegraph @

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

raw
1 // Copyright 2006 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 Definition of the AttachableMenu class.
17 *
18 */
19
20 goog.provide('goog.ui.AttachableMenu');
21
22 goog.require('goog.a11y.aria');
23 goog.require('goog.a11y.aria.State');
24 goog.require('goog.array');
25 goog.require('goog.asserts');
26 goog.require('goog.dom');
27 goog.require('goog.dom.classlist');
28 goog.require('goog.events.Event');
29 goog.require('goog.events.KeyCodes');
30 goog.require('goog.string');
31 goog.require('goog.style');
32 goog.require('goog.ui.ItemEvent');
33 goog.require('goog.ui.MenuBase');
34 goog.require('goog.ui.PopupBase');
35 goog.require('goog.userAgent');
36
37
38
39 /**
40 * An implementation of a menu that can attach itself to DOM element that
41 * are annotated appropriately.
42 *
43 * The following attributes are used by the AttachableMenu
44 *
45 * menu-item - Should be set on DOM elements that function as items in the
46 * menu that can be selected.
47 * classNameSelected - A class that will be added to the element's class names
48 * when the item is selected via keyboard or mouse.
49 *
50 * @param {Element=} opt_element A DOM element for the popup.
51 * @constructor
52 * @extends {goog.ui.MenuBase}
53 * @deprecated Use goog.ui.PopupMenu.
54 * @final
55 */
56 goog.ui.AttachableMenu = function(opt_element) {
57 goog.ui.MenuBase.call(this, opt_element);
58 };
59 goog.inherits(goog.ui.AttachableMenu, goog.ui.MenuBase);
60 goog.tagUnsealableClass(goog.ui.AttachableMenu);
61
62
63 /**
64 * The currently selected element (mouse was moved over it or keyboard arrows)
65 * @type {HTMLElement}
66 * @private
67 */
68 goog.ui.AttachableMenu.prototype.selectedElement_ = null;
69
70
71 /**
72 * Class name to append to a menu item's class when it's selected
73 * @type {string}
74 * @private
75 */
76 goog.ui.AttachableMenu.prototype.itemClassName_ = 'menu-item';
77
78
79 /**
80 * Class name to append to a menu item's class when it's selected
81 * @type {string}
82 * @private
83 */
84 goog.ui.AttachableMenu.prototype.selectedItemClassName_ = 'menu-item-selected';
85
86
87 /**
88 * Keep track of when the last key was pressed so that a keydown-scroll doesn't
89 * trigger a mouseover event
90 * @type {number}
91 * @private
92 */
93 goog.ui.AttachableMenu.prototype.lastKeyDown_ = goog.now();
94
95
96 /** @override */
97 goog.ui.AttachableMenu.prototype.disposeInternal = function() {
98 goog.ui.AttachableMenu.superClass_.disposeInternal.call(this);
99 this.selectedElement_ = null;
100 };
101
102
103 /**
104 * Sets the class name to use for menu items
105 *
106 * @return {string} The class name to use for items.
107 */
108 goog.ui.AttachableMenu.prototype.getItemClassName = function() {
109 return this.itemClassName_;
110 };
111
112
113 /**
114 * Sets the class name to use for menu items
115 *
116 * @param {string} name The class name to use for items.
117 */
118 goog.ui.AttachableMenu.prototype.setItemClassName = function(name) {
119 this.itemClassName_ = name;
120 };
121
122
123 /**
124 * Sets the class name to use for selected menu items
125 * todo(user) - reevaluate if we can simulate pseudo classes in IE
126 *
127 * @return {string} The class name to use for selected items.
128 */
129 goog.ui.AttachableMenu.prototype.getSelectedItemClassName = function() {
130 return this.selectedItemClassName_;
131 };
132
133
134 /**
135 * Sets the class name to use for selected menu items
136 * todo(user) - reevaluate if we can simulate pseudo classes in IE
137 *
138 * @param {string} name The class name to use for selected items.
139 */
140 goog.ui.AttachableMenu.prototype.setSelectedItemClassName = function(name) {
141 this.selectedItemClassName_ = name;
142 };
143
144
145 /**
146 * Returns the selected item
147 *
148 * @return {Element} The item selected or null if no item is selected.
149 * @override
150 */
151 goog.ui.AttachableMenu.prototype.getSelectedItem = function() {
152 return this.selectedElement_;
153 };
154
155
156 /** @override */
157 goog.ui.AttachableMenu.prototype.setSelectedItem = function(obj) {
158 var elt = /** @type {HTMLElement} */ (obj);
159 if (this.selectedElement_) {
160 goog.dom.classlist.remove(
161 this.selectedElement_, this.selectedItemClassName_);
162 }
163
164 this.selectedElement_ = elt;
165
166 var el = /** @type {HTMLElement} */ (this.getElement());
167 goog.asserts.assert(el, 'The attachable menu DOM element cannot be null.');
168 if (this.selectedElement_) {
169 goog.dom.classlist.add(this.selectedElement_, this.selectedItemClassName_);
170
171 if (elt.id) {
172 // Update activedescendant to reflect the new selection. ARIA roles for
173 // menu and menuitem can be set statically (through Soy templates, for
174 // example) whereas this needs to be updated as the selection changes.
175 goog.a11y.aria.setState(
176 el, goog.a11y.aria.State.ACTIVEDESCENDANT, elt.id);
177 }
178
179 var top = this.selectedElement_.offsetTop;
180 var height = this.selectedElement_.offsetHeight;
181 var scrollTop = el.scrollTop;
182 var scrollHeight = el.offsetHeight;
183
184 // If the menu is scrollable this scrolls the selected item into view
185 // (this has no effect when the menu doesn't scroll)
186 if (top < scrollTop) {
187 el.scrollTop = top;
188 } else if (top + height > scrollTop + scrollHeight) {
189 el.scrollTop = top + height - scrollHeight;
190 }
191 } else {
192 // Clear off activedescendant to reflect no selection.
193 goog.a11y.aria.setState(el, goog.a11y.aria.State.ACTIVEDESCENDANT, '');
194 }
195 };
196
197
198 /** @override */
199 goog.ui.AttachableMenu.prototype.showPopupElement = function() {
200 // The scroll position cannot be set for hidden (display: none) elements in
201 // gecko browsers.
202 var el = /** @type {Element} */ (this.getElement());
203 goog.style.setElementShown(el, true);
204 el.scrollTop = 0;
205 el.style.visibility = 'visible';
206 };
207
208
209 /**
210 * Called after the menu is shown.
211 * @protected
212 * @override
213 */
214 goog.ui.AttachableMenu.prototype.onShow = function() {
215 goog.ui.AttachableMenu.superClass_.onShow.call(this);
216
217 // In IE, focusing the menu causes weird scrolling to happen. Focusing the
218 // first child makes the scroll behavior better, and the key handling still
219 // works. In FF, focusing the first child causes us to lose key events, so we
220 // still focus the menu.
221 var el = this.getElement();
222 goog.userAgent.IE ? el.firstChild.focus() : el.focus();
223 };
224
225
226 /**
227 * Returns the next or previous item. Used for up/down arrows.
228 *
229 * @param {boolean} prev True to go to the previous element instead of next.
230 * @return {Element} The next or previous element.
231 * @protected
232 */
233 goog.ui.AttachableMenu.prototype.getNextPrevItem = function(prev) {
234 // first find the index of the next element
235 var elements = this.getElement().getElementsByTagName('*');
236 var elementCount = elements.length;
237 var index;
238 // if there is a selected element, find its index and then inc/dec by one
239 if (this.selectedElement_) {
240 for (var i = 0; i < elementCount; i++) {
241 if (elements[i] == this.selectedElement_) {
242 index = prev ? i - 1 : i + 1;
243 break;
244 }
245 }
246 }
247
248 // if no selected element, start from beginning or end
249 if (!goog.isDef(index)) {
250 index = prev ? elementCount - 1 : 0;
251 }
252
253 // iterate forward or backwards through the elements finding the next
254 // menu item
255 for (var i = 0; i < elementCount; i++) {
256 var multiplier = prev ? -1 : 1;
257 var nextIndex = index + (multiplier * i) % elementCount;
258
259 // if overflowed/underflowed, wrap around
260 if (nextIndex < 0) {
261 nextIndex += elementCount;
262 } else if (nextIndex >= elementCount) {
263 nextIndex -= elementCount;
264 }
265
266 if (this.isMenuItem_(elements[nextIndex])) {
267 return elements[nextIndex];
268 }
269 }
270 return null;
271 };
272
273
274 /**
275 * Mouse over handler for the menu.
276 * @param {goog.events.Event} e The event object.
277 * @protected
278 * @override
279 */
280 goog.ui.AttachableMenu.prototype.onMouseOver = function(e) {
281 var eltItem = this.getAncestorMenuItem_(/** @type {Element} */ (e.target));
282 if (eltItem == null) {
283 return;
284 }
285
286 // Stop the keydown triggering a mouseover in FF.
287 if (goog.now() - this.lastKeyDown_ > goog.ui.PopupBase.DEBOUNCE_DELAY_MS) {
288 this.setSelectedItem(eltItem);
289 }
290 };
291
292
293 /**
294 * Mouse out handler for the menu.
295 * @param {goog.events.Event} e The event object.
296 * @protected
297 * @override
298 */
299 goog.ui.AttachableMenu.prototype.onMouseOut = function(e) {
300 var eltItem = this.getAncestorMenuItem_(/** @type {Element} */ (e.target));
301 if (eltItem == null) {
302 return;
303 }
304
305 // Stop the keydown triggering a mouseout in FF.
306 if (goog.now() - this.lastKeyDown_ > goog.ui.PopupBase.DEBOUNCE_DELAY_MS) {
307 this.setSelectedItem(null);
308 }
309 };
310
311
312 /**
313 * Mouse down handler for the menu. Prevents default to avoid text selection.
314 * @param {!goog.events.Event} e The event object.
315 * @protected
316 * @override
317 */
318 goog.ui.AttachableMenu.prototype.onMouseDown = goog.events.Event.preventDefault;
319
320
321 /**
322 * Mouse up handler for the menu.
323 * @param {goog.events.Event} e The event object.
324 * @protected
325 * @override
326 */
327 goog.ui.AttachableMenu.prototype.onMouseUp = function(e) {
328 var eltItem = this.getAncestorMenuItem_(/** @type {Element} */ (e.target));
329 if (eltItem == null) {
330 return;
331 }
332 this.setVisible(false);
333 this.onItemSelected_(eltItem);
334 };
335
336
337 /**
338 * Key down handler for the menu.
339 * @param {goog.events.KeyEvent} e The event object.
340 * @protected
341 * @override
342 */
343 goog.ui.AttachableMenu.prototype.onKeyDown = function(e) {
344 switch (e.keyCode) {
345 case goog.events.KeyCodes.DOWN:
346 this.setSelectedItem(this.getNextPrevItem(false));
347 this.lastKeyDown_ = goog.now();
348 break;
349 case goog.events.KeyCodes.UP:
350 this.setSelectedItem(this.getNextPrevItem(true));
351 this.lastKeyDown_ = goog.now();
352 break;
353 case goog.events.KeyCodes.ENTER:
354 if (this.selectedElement_) {
355 this.onItemSelected_();
356 this.setVisible(false);
357 }
358 break;
359 case goog.events.KeyCodes.ESC:
360 this.setVisible(false);
361 break;
362 default:
363 if (e.charCode) {
364 var charStr = String.fromCharCode(e.charCode);
365 this.selectByName_(charStr, 1, true);
366 }
367 break;
368 }
369 // Prevent the browser's default keydown behaviour when the menu is open,
370 // e.g. keyboard scrolling.
371 e.preventDefault();
372
373 // Stop propagation to prevent application level keyboard shortcuts from
374 // firing.
375 e.stopPropagation();
376
377 this.dispatchEvent(e);
378 };
379
380
381 /**
382 * Find an item that has the given prefix and select it.
383 *
384 * @param {string} prefix The entered prefix, so far.
385 * @param {number=} opt_direction 1 to search forward from the selection
386 * (default), -1 to search backward (e.g. to go to the previous match).
387 * @param {boolean=} opt_skip True if should skip the current selection,
388 * unless no other item has the given prefix.
389 * @private
390 */
391 goog.ui.AttachableMenu.prototype.selectByName_ = function(
392 prefix, opt_direction, opt_skip) {
393 var elements = this.getElement().getElementsByTagName('*');
394 var elementCount = elements.length;
395 var index;
396
397 if (elementCount == 0) {
398 return;
399 }
400
401 if (!this.selectedElement_ ||
402 (index = goog.array.indexOf(elements, this.selectedElement_)) == -1) {
403 // no selection or selection isn't known => start at the beginning
404 index = 0;
405 }
406
407 var start = index;
408 var re = new RegExp('^' + goog.string.regExpEscape(prefix), 'i');
409 var skip = opt_skip && this.selectedElement_;
410 var dir = opt_direction || 1;
411
412 do {
413 if (elements[index] != skip && this.isMenuItem_(elements[index])) {
414 var name = goog.dom.getTextContent(elements[index]);
415 if (name.match(re)) {
416 break;
417 }
418 }
419 index += dir;
420 if (index == elementCount) {
421 index = 0;
422 } else if (index < 0) {
423 index = elementCount - 1;
424 }
425 } while (index != start);
426
427 if (this.selectedElement_ != elements[index]) {
428 this.setSelectedItem(elements[index]);
429 }
430 };
431
432
433 /**
434 * Dispatch an ITEM_ACTION event when an item is selected
435 * @param {Object=} opt_item Item selected.
436 * @private
437 */
438 goog.ui.AttachableMenu.prototype.onItemSelected_ = function(opt_item) {
439 this.dispatchEvent(
440 new goog.ui.ItemEvent(
441 goog.ui.MenuBase.Events.ITEM_ACTION, this,
442 opt_item || this.selectedElement_));
443 };
444
445
446 /**
447 * Returns whether the specified element is a menu item.
448 * @param {Element} elt The element to find a menu item ancestor of.
449 * @return {boolean} Whether the specified element is a menu item.
450 * @private
451 */
452 goog.ui.AttachableMenu.prototype.isMenuItem_ = function(elt) {
453 return !!elt && goog.dom.classlist.contains(elt, this.itemClassName_);
454 };
455
456
457 /**
458 * Returns the menu-item scoping the specified element, or null if there is
459 * none.
460 * @param {Element|undefined} elt The element to find a menu item ancestor of.
461 * @return {Element} The menu-item scoping the specified element, or null if
462 * there is none.
463 * @private
464 */
465 goog.ui.AttachableMenu.prototype.getAncestorMenuItem_ = function(elt) {
466 if (elt) {
467 var ownerDocumentBody = goog.dom.getOwnerDocument(elt).body;
468 while (elt != null && elt != ownerDocumentBody) {
469 if (this.isMenuItem_(elt)) {
470 return elt;
471 }
472 elt = /** @type {Element} */ (elt.parentNode);
473 }
474 }
475 return null;
476 };