Debian Codegraph @

closure-library/closure/goog/ui/menuitem.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 for representing items in menus.
17 * @see goog.ui.Menu
18 *
19 * @author [email protected] (Attila Bodis)
20 * @see ../demos/menuitem.html
21 */
22
23 goog.provide('goog.ui.MenuItem');
24
25 goog.require('goog.a11y.aria.Role');
26 goog.require('goog.array');
27 goog.require('goog.dom');
28 goog.require('goog.dom.classlist');
29 goog.require('goog.math.Coordinate');
30 goog.require('goog.string');
31 goog.require('goog.ui.Component');
32 goog.require('goog.ui.Control');
33 goog.require('goog.ui.MenuItemRenderer');
34 goog.require('goog.ui.registry');
35
36 goog.forwardDeclare('goog.ui.Menu'); // circular
37
38
39
40 /**
41 * Class representing an item in a menu.
42 *
43 * @param {goog.ui.ControlContent} content Text caption or DOM structure to
44 * display as the content of the item (use to add icons or styling to
45 * menus).
46 * @param {*=} opt_model Data/model associated with the menu item.
47 * @param {goog.dom.DomHelper=} opt_domHelper Optional DOM helper used for
48 * document interactions.
49 * @param {goog.ui.MenuItemRenderer=} opt_renderer Optional renderer.
50 * @constructor
51 * @extends {goog.ui.Control}
52 */
53 goog.ui.MenuItem = function(content, opt_model, opt_domHelper, opt_renderer) {
54 goog.ui.Control.call(
55 this, content, opt_renderer || goog.ui.MenuItemRenderer.getInstance(),
56 opt_domHelper);
57 this.setValue(opt_model);
58 };
59 goog.inherits(goog.ui.MenuItem, goog.ui.Control);
60 goog.tagUnsealableClass(goog.ui.MenuItem);
61
62
63 /**
64 * The access key for this menu item. This key allows the user to quickly
65 * trigger this item's action with they keyboard. For example, setting the
66 * mnenomic key to 70 (F), when the user opens the menu and hits "F," the
67 * menu item is triggered.
68 *
69 * @type {goog.events.KeyCodes}
70 * @private
71 */
72 goog.ui.MenuItem.prototype.mnemonicKey_;
73
74
75 /**
76 * The class set on an element that contains a parenthetical mnemonic key hint.
77 * Parenthetical hints are added to items in which the mnemonic key is not found
78 * within the menu item's caption itself. For example, if you have a menu item
79 * with the caption "Record," but its mnemonic key is "I", the caption displayed
80 * in the menu will appear as "Record (I)".
81 *
82 * @type {string}
83 * @private
84 */
85 goog.ui.MenuItem.MNEMONIC_WRAPPER_CLASS_ =
86 goog.getCssName('goog-menuitem-mnemonic-separator');
87
88
89 /**
90 * The class set on an element that contains a keyboard accelerator hint.
91 * @type {string}
92 */
93 goog.ui.MenuItem.ACCELERATOR_CLASS = goog.getCssName('goog-menuitem-accel');
94
95
96 // goog.ui.Component and goog.ui.Control implementation.
97
98
99 /**
100 * Returns the value associated with the menu item. The default implementation
101 * returns the model object associated with the item (if any), or its caption.
102 * @return {*} Value associated with the menu item, if any, or its caption.
103 */
104 goog.ui.MenuItem.prototype.getValue = function() {
105 var model = this.getModel();
106 return model != null ? model : this.getCaption();
107 };
108
109
110 /**
111 * Sets the value associated with the menu item. The default implementation
112 * stores the value as the model of the menu item.
113 * @param {*} value Value to be associated with the menu item.
114 */
115 goog.ui.MenuItem.prototype.setValue = function(value) {
116 this.setModel(value);
117 };
118
119
120 /** @override */
121 goog.ui.MenuItem.prototype.setSupportedState = function(state, support) {
122 goog.ui.MenuItem.base(this, 'setSupportedState', state, support);
123 switch (state) {
124 case goog.ui.Component.State.SELECTED:
125 this.setSelectableInternal_(support);
126 break;
127 case goog.ui.Component.State.CHECKED:
128 this.setCheckableInternal_(support);
129 break;
130 }
131 };
132
133
134 /**
135 * Sets the menu item to be selectable or not. Set to true for menu items
136 * that represent selectable options.
137 * @param {boolean} selectable Whether the menu item is selectable.
138 */
139 goog.ui.MenuItem.prototype.setSelectable = function(selectable) {
140 this.setSupportedState(goog.ui.Component.State.SELECTED, selectable);
141 };
142
143
144 /**
145 * Sets the menu item to be selectable or not.
146 * @param {boolean} selectable Whether the menu item is selectable.
147 * @private
148 */
149 goog.ui.MenuItem.prototype.setSelectableInternal_ = function(selectable) {
150 if (this.isChecked() && !selectable) {
151 this.setChecked(false);
152 }
153
154 var element = this.getElement();
155 if (element) {
156 this.getRenderer().setSelectable(this, element, selectable);
157 }
158 };
159
160
161 /**
162 * Sets the menu item to be checkable or not. Set to true for menu items
163 * that represent checkable options.
164 * @param {boolean} checkable Whether the menu item is checkable.
165 */
166 goog.ui.MenuItem.prototype.setCheckable = function(checkable) {
167 this.setSupportedState(goog.ui.Component.State.CHECKED, checkable);
168 };
169
170
171 /**
172 * Sets the menu item to be checkable or not.
173 * @param {boolean} checkable Whether the menu item is checkable.
174 * @private
175 */
176 goog.ui.MenuItem.prototype.setCheckableInternal_ = function(checkable) {
177 var element = this.getElement();
178 if (element) {
179 this.getRenderer().setCheckable(this, element, checkable);
180 }
181 };
182
183
184 /**
185 * Returns the text caption of the component while ignoring accelerators.
186 * @override
187 */
188 goog.ui.MenuItem.prototype.getCaption = function() {
189 var content = this.getContent();
190 if (goog.isArray(content)) {
191 var acceleratorClass = goog.ui.MenuItem.ACCELERATOR_CLASS;
192 var mnemonicWrapClass = goog.ui.MenuItem.MNEMONIC_WRAPPER_CLASS_;
193 var caption =
194 goog.array
195 .map(
196 content,
197 function(node) {
198 if (goog.dom.isElement(node) &&
199 (goog.dom.classlist.contains(
200 /** @type {!Element} */ (node), acceleratorClass) ||
201 goog.dom.classlist.contains(
202 /** @type {!Element} */ (node),
203 mnemonicWrapClass))) {
204 return '';
205 } else {
206 return goog.dom.getRawTextContent(node);
207 }
208 })
209 .join('');
210 return goog.string.collapseBreakingSpaces(caption);
211 }
212 return goog.ui.MenuItem.superClass_.getCaption.call(this);
213 };
214
215
216 /**
217 * @return {?string} The keyboard accelerator text, or null if the menu item
218 * doesn't have one.
219 */
220 goog.ui.MenuItem.prototype.getAccelerator = function() {
221 var dom = this.getDomHelper();
222 var content = this.getContent();
223 if (goog.isArray(content)) {
224 var acceleratorEl = goog.array.find(content, function(e) {
225 return goog.dom.classlist.contains(
226 /** @type {!Element} */ (e), goog.ui.MenuItem.ACCELERATOR_CLASS);
227 });
228 if (acceleratorEl) {
229 return dom.getTextContent(acceleratorEl);
230 }
231 }
232 return null;
233 };
234
235
236 /** @override */
237 goog.ui.MenuItem.prototype.handleMouseUp = function(e) {
238 var parentMenu = /** @type {goog.ui.Menu} */ (this.getParent());
239
240 if (parentMenu) {
241 var oldCoords = parentMenu.openingCoords;
242 // Clear out the saved opening coords immediately so they're not used twice.
243 parentMenu.openingCoords = null;
244
245 if (oldCoords && goog.isNumber(e.clientX)) {
246 var newCoords = new goog.math.Coordinate(e.clientX, e.clientY);
247 if (goog.math.Coordinate.equals(oldCoords, newCoords)) {
248 // This menu was opened by a mousedown and we're handling the consequent
249 // mouseup. The coords haven't changed, meaning this was a simple click,
250 // not a click and drag. Don't do the usual behavior because the menu
251 // just popped up under the mouse and the user didn't mean to activate
252 // this item.
253 return;
254 }
255 }
256 }
257
258 goog.ui.MenuItem.base(this, 'handleMouseUp', e);
259 };
260
261
262 /** @override */
263 goog.ui.MenuItem.prototype.handleKeyEventInternal = function(e) {
264 if (e.keyCode == this.getMnemonic() && this.performActionInternal(e)) {
265 return true;
266 } else {
267 return goog.ui.MenuItem.base(this, 'handleKeyEventInternal', e);
268 }
269 };
270
271
272 /**
273 * Sets the mnemonic key code. The mnemonic is the key associated with this
274 * action.
275 * @param {goog.events.KeyCodes} key The key code.
276 */
277 goog.ui.MenuItem.prototype.setMnemonic = function(key) {
278 this.mnemonicKey_ = key;
279 };
280
281
282 /**
283 * Gets the mnemonic key code. The mnemonic is the key associated with this
284 * action.
285 * @return {goog.events.KeyCodes} The key code of the mnemonic key.
286 */
287 goog.ui.MenuItem.prototype.getMnemonic = function() {
288 return this.mnemonicKey_;
289 };
290
291
292 // Register a decorator factory function for goog.ui.MenuItems.
293 goog.ui.registry.setDecoratorByClassName(
294 goog.ui.MenuItemRenderer.CSS_CLASS, function() {
295 // MenuItem defaults to using MenuItemRenderer.
296 return new goog.ui.MenuItem(null);
297 });
298
299
300 /**
301 * @override
302 */
303 goog.ui.MenuItem.prototype.getPreferredAriaRole = function() {
304 if (this.isSupportedState(goog.ui.Component.State.CHECKED)) {
305 return goog.a11y.aria.Role.MENU_ITEM_CHECKBOX;
306 }
307 if (this.isSupportedState(goog.ui.Component.State.SELECTED)) {
308 return goog.a11y.aria.Role.MENU_ITEM_RADIO;
309 }
310 return goog.ui.MenuItem.base(this, 'getPreferredAriaRole');
311 };
312
313
314 /**
315 * @override
316 * @return {goog.ui.Menu}
317 */
318 goog.ui.MenuItem.prototype.getParent = function() {
319 return /** @type {goog.ui.Menu} */ (
320 goog.ui.Control.prototype.getParent.call(this));
321 };
322
323
324 /**
325 * @override
326 * @return {goog.ui.Menu}
327 */
328 goog.ui.MenuItem.prototype.getParentEventTarget = function() {
329 return /** @type {goog.ui.Menu} */ (
330 goog.ui.Control.prototype.getParentEventTarget.call(this));
331 };