Debian Codegraph @

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

raw
1 // Copyright 2008 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 Renderer for {@link goog.ui.MenuItem}s.
17 *
18 * @author [email protected] (Attila Bodis)
19 */
20
21 goog.provide('goog.ui.MenuItemRenderer');
22
23 goog.require('goog.a11y.aria.Role');
24 goog.require('goog.asserts');
25 goog.require('goog.dom');
26 goog.require('goog.dom.TagName');
27 goog.require('goog.dom.classlist');
28 goog.require('goog.ui.Component');
29 goog.require('goog.ui.ControlRenderer');
30
31
32
33 /**
34 * Default renderer for {@link goog.ui.MenuItem}s. Each item has the following
35 * structure:
36 *
37 * <div class="goog-menuitem">
38 * <div class="goog-menuitem-content">
39 * ...(menu item contents)...
40 * </div>
41 * </div>
42 *
43 * @constructor
44 * @extends {goog.ui.ControlRenderer}
45 */
46 goog.ui.MenuItemRenderer = function() {
47 goog.ui.ControlRenderer.call(this);
48
49 /**
50 * Commonly used CSS class names, cached here for convenience (and to avoid
51 * unnecessary string concatenation).
52 * @type {!Array<string>}
53 * @private
54 */
55 this.classNameCache_ = [];
56 };
57 goog.inherits(goog.ui.MenuItemRenderer, goog.ui.ControlRenderer);
58 goog.addSingletonGetter(goog.ui.MenuItemRenderer);
59
60
61 /**
62 * CSS class name the renderer applies to menu item elements.
63 * @type {string}
64 */
65 goog.ui.MenuItemRenderer.CSS_CLASS = goog.getCssName('goog-menuitem');
66
67
68 /**
69 * Constants for referencing composite CSS classes.
70 * @enum {number}
71 * @private
72 */
73 goog.ui.MenuItemRenderer.CompositeCssClassIndex_ = {
74 HOVER: 0,
75 CHECKBOX: 1,
76 CONTENT: 2
77 };
78
79
80 /**
81 * Returns the composite CSS class by using the cached value or by constructing
82 * the value from the base CSS class and the passed index.
83 * @param {goog.ui.MenuItemRenderer.CompositeCssClassIndex_} index Index for the
84 * CSS class - could be highlight, checkbox or content in usual cases.
85 * @return {string} The composite CSS class.
86 * @private
87 */
88 goog.ui.MenuItemRenderer.prototype.getCompositeCssClass_ = function(index) {
89 var result = this.classNameCache_[index];
90 if (!result) {
91 switch (index) {
92 case goog.ui.MenuItemRenderer.CompositeCssClassIndex_.HOVER:
93 result = goog.getCssName(this.getStructuralCssClass(), 'highlight');
94 break;
95 case goog.ui.MenuItemRenderer.CompositeCssClassIndex_.CHECKBOX:
96 result = goog.getCssName(this.getStructuralCssClass(), 'checkbox');
97 break;
98 case goog.ui.MenuItemRenderer.CompositeCssClassIndex_.CONTENT:
99 result = goog.getCssName(this.getStructuralCssClass(), 'content');
100 break;
101 }
102 this.classNameCache_[index] = result;
103 }
104
105 return result;
106 };
107
108
109 /** @override */
110 goog.ui.MenuItemRenderer.prototype.getAriaRole = function() {
111 return goog.a11y.aria.Role.MENU_ITEM;
112 };
113
114
115 /**
116 * Overrides {@link goog.ui.ControlRenderer#createDom} by adding extra markup
117 * and stying to the menu item's element if it is selectable or checkable.
118 * @param {goog.ui.Control} item Menu item to render.
119 * @return {Element} Root element for the item.
120 * @override
121 */
122 goog.ui.MenuItemRenderer.prototype.createDom = function(item) {
123 var element = item.getDomHelper().createDom(
124 goog.dom.TagName.DIV, this.getClassNames(item).join(' '),
125 this.createContent(item.getContent(), item.getDomHelper()));
126 this.setEnableCheckBoxStructure(
127 item, element, item.isSupportedState(goog.ui.Component.State.SELECTED) ||
128 item.isSupportedState(goog.ui.Component.State.CHECKED));
129 return element;
130 };
131
132
133 /** @override */
134 goog.ui.MenuItemRenderer.prototype.getContentElement = function(element) {
135 return /** @type {Element} */ (element && element.firstChild);
136 };
137
138
139 /**
140 * Overrides {@link goog.ui.ControlRenderer#decorate} by initializing the
141 * menu item to checkable based on whether the element to be decorated has
142 * extra stying indicating that it should be.
143 * @param {goog.ui.Control} item Menu item instance to decorate the element.
144 * @param {Element} element Element to decorate.
145 * @return {Element} Decorated element.
146 * @override
147 */
148 goog.ui.MenuItemRenderer.prototype.decorate = function(item, element) {
149 goog.asserts.assert(element);
150 if (!this.hasContentStructure(element)) {
151 element.appendChild(
152 this.createContent(element.childNodes, item.getDomHelper()));
153 }
154 if (goog.dom.classlist.contains(element, goog.getCssName('goog-option'))) {
155 (/** @type {goog.ui.MenuItem} */ (item)).setCheckable(true);
156 this.setCheckable(item, element, true);
157 }
158 return goog.ui.MenuItemRenderer.superClass_.decorate.call(
159 this, item, element);
160 };
161
162
163 /**
164 * Takes a menu item's root element, and sets its content to the given text
165 * caption or DOM structure. Overrides the superclass immplementation by
166 * making sure that the checkbox structure (for selectable/checkable menu
167 * items) is preserved.
168 * @param {Element} element The item's root element.
169 * @param {goog.ui.ControlContent} content Text caption or DOM structure to be
170 * set as the item's content.
171 * @override
172 */
173 goog.ui.MenuItemRenderer.prototype.setContent = function(element, content) {
174 // Save the checkbox element, if present.
175 var contentElement = this.getContentElement(element);
176 var checkBoxElement =
177 this.hasCheckBoxStructure(element) ? contentElement.firstChild : null;
178 goog.ui.MenuItemRenderer.superClass_.setContent.call(this, element, content);
179 if (checkBoxElement && !this.hasCheckBoxStructure(element)) {
180 // The call to setContent() blew away the checkbox element; reattach it.
181 contentElement.insertBefore(
182 checkBoxElement, contentElement.firstChild || null);
183 }
184 };
185
186
187 /**
188 * Returns true if the element appears to have a proper menu item structure by
189 * checking whether its first child has the appropriate structural class name.
190 * @param {Element} element Element to check.
191 * @return {boolean} Whether the element appears to have a proper menu item DOM.
192 * @protected
193 */
194 goog.ui.MenuItemRenderer.prototype.hasContentStructure = function(element) {
195 var child = goog.dom.getFirstElementChild(element);
196 var contentClassName = this.getCompositeCssClass_(
197 goog.ui.MenuItemRenderer.CompositeCssClassIndex_.CONTENT);
198 return !!child && goog.dom.classlist.contains(child, contentClassName);
199 };
200
201
202 /**
203 * Wraps the given text caption or existing DOM node(s) in a structural element
204 * containing the menu item's contents.
205 * @param {goog.ui.ControlContent} content Menu item contents.
206 * @param {goog.dom.DomHelper} dom DOM helper for document interaction.
207 * @return {Element} Menu item content element.
208 * @protected
209 */
210 goog.ui.MenuItemRenderer.prototype.createContent = function(content, dom) {
211 var contentClassName = this.getCompositeCssClass_(
212 goog.ui.MenuItemRenderer.CompositeCssClassIndex_.CONTENT);
213 return dom.createDom(goog.dom.TagName.DIV, contentClassName, content);
214 };
215
216
217 /**
218 * Enables/disables radio button semantics on the menu item.
219 * @param {goog.ui.Control} item Menu item to update.
220 * @param {Element} element Menu item element to update (may be null if the
221 * item hasn't been rendered yet).
222 * @param {boolean} selectable Whether the item should be selectable.
223 */
224 goog.ui.MenuItemRenderer.prototype.setSelectable = function(
225 item, element, selectable) {
226 if (item && element) {
227 this.setEnableCheckBoxStructure(item, element, selectable);
228 }
229 };
230
231
232 /**
233 * Enables/disables checkbox semantics on the menu item.
234 * @param {goog.ui.Control} item Menu item to update.
235 * @param {Element} element Menu item element to update (may be null if the
236 * item hasn't been rendered yet).
237 * @param {boolean} checkable Whether the item should be checkable.
238 */
239 goog.ui.MenuItemRenderer.prototype.setCheckable = function(
240 item, element, checkable) {
241 if (item && element) {
242 this.setEnableCheckBoxStructure(item, element, checkable);
243 }
244 };
245
246
247 /**
248 * Determines whether the item contains a checkbox element.
249 * @param {Element} element Menu item root element.
250 * @return {boolean} Whether the element contains a checkbox element.
251 * @protected
252 */
253 goog.ui.MenuItemRenderer.prototype.hasCheckBoxStructure = function(element) {
254 var contentElement = this.getContentElement(element);
255 if (contentElement) {
256 var child = contentElement.firstChild;
257 var checkboxClassName = this.getCompositeCssClass_(
258 goog.ui.MenuItemRenderer.CompositeCssClassIndex_.CHECKBOX);
259 return !!child && goog.dom.isElement(child) &&
260 goog.dom.classlist.contains(
261 /** @type {!Element} */ (child), checkboxClassName);
262 }
263 return false;
264 };
265
266
267 /**
268 * Adds or removes extra markup and CSS styling to the menu item to make it
269 * selectable or non-selectable, depending on the value of the
270 * {@code selectable} argument.
271 * @param {!goog.ui.Control} item Menu item to update.
272 * @param {!Element} element Menu item element to update.
273 * @param {boolean} enable Whether to add or remove the checkbox structure.
274 * @protected
275 */
276 goog.ui.MenuItemRenderer.prototype.setEnableCheckBoxStructure = function(
277 item, element, enable) {
278 this.setAriaRole(element, item.getPreferredAriaRole());
279 this.setAriaStates(item, element);
280 if (enable != this.hasCheckBoxStructure(element)) {
281 goog.dom.classlist.enable(element, goog.getCssName('goog-option'), enable);
282 var contentElement = this.getContentElement(element);
283 if (enable) {
284 // Insert checkbox structure.
285 var checkboxClassName = this.getCompositeCssClass_(
286 goog.ui.MenuItemRenderer.CompositeCssClassIndex_.CHECKBOX);
287 contentElement.insertBefore(
288 item.getDomHelper().createDom(
289 goog.dom.TagName.DIV, checkboxClassName),
290 contentElement.firstChild || null);
291 } else {
292 // Remove checkbox structure.
293 contentElement.removeChild(contentElement.firstChild);
294 }
295 }
296 };
297
298
299 /**
300 * Takes a single {@link goog.ui.Component.State}, and returns the
301 * corresponding CSS class name (null if none). Overrides the superclass
302 * implementation by using 'highlight' as opposed to 'hover' as the CSS
303 * class name suffix for the HOVER state, for backwards compatibility.
304 * @param {goog.ui.Component.State} state Component state.
305 * @return {string|undefined} CSS class representing the given state
306 * (undefined if none).
307 * @override
308 */
309 goog.ui.MenuItemRenderer.prototype.getClassForState = function(state) {
310 switch (state) {
311 case goog.ui.Component.State.HOVER:
312 // We use 'highlight' as the suffix, for backwards compatibility.
313 return this.getCompositeCssClass_(
314 goog.ui.MenuItemRenderer.CompositeCssClassIndex_.HOVER);
315 case goog.ui.Component.State.CHECKED:
316 case goog.ui.Component.State.SELECTED:
317 // We use 'goog-option-selected' as the class, for backwards
318 // compatibility.
319 return goog.getCssName('goog-option-selected');
320 default:
321 return goog.ui.MenuItemRenderer.superClass_.getClassForState.call(
322 this, state);
323 }
324 };
325
326
327 /**
328 * Takes a single CSS class name which may represent a component state, and
329 * returns the corresponding component state (0x00 if none). Overrides the
330 * superclass implementation by treating 'goog-option-selected' as special,
331 * for backwards compatibility.
332 * @param {string} className CSS class name, possibly representing a component
333 * state.
334 * @return {goog.ui.Component.State} state Component state corresponding
335 * to the given CSS class (0x00 if none).
336 * @override
337 */
338 goog.ui.MenuItemRenderer.prototype.getStateFromClass = function(className) {
339 var hoverClassName = this.getCompositeCssClass_(
340 goog.ui.MenuItemRenderer.CompositeCssClassIndex_.HOVER);
341 switch (className) {
342 case goog.getCssName('goog-option-selected'):
343 return goog.ui.Component.State.CHECKED;
344 case hoverClassName:
345 return goog.ui.Component.State.HOVER;
346 default:
347 return goog.ui.MenuItemRenderer.superClass_.getStateFromClass.call(
348 this, className);
349 }
350 };
351
352
353 /** @override */
354 goog.ui.MenuItemRenderer.prototype.getCssClass = function() {
355 return goog.ui.MenuItemRenderer.CSS_CLASS;
356 };