Debian Codegraph @

closure-library/closure/goog/ui/controlrenderer.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 Base class for control renderers.
17 * TODO(attila): If the renderer framework works well, pull it into Component.
18 *
19 * @author [email protected] (Attila Bodis)
20 */
21
22 goog.provide('goog.ui.ControlRenderer');
23
24 goog.require('goog.a11y.aria');
25 goog.require('goog.a11y.aria.Role');
26 goog.require('goog.a11y.aria.State');
27 goog.require('goog.array');
28 goog.require('goog.asserts');
29 goog.require('goog.dom');
30 goog.require('goog.dom.TagName');
31 goog.require('goog.dom.classlist');
32 goog.require('goog.object');
33 goog.require('goog.string');
34 goog.require('goog.style');
35 goog.require('goog.ui.Component');
36 goog.require('goog.ui.ControlContent');
37 goog.require('goog.userAgent');
38
39 goog.forwardDeclare('goog.ui.Control'); // circular
40
41
42
43 /**
44 * Default renderer for {@link goog.ui.Control}s. Can be used as-is, but
45 * subclasses of Control will probably want to use renderers specifically
46 * tailored for them by extending this class. Controls that use renderers
47 * delegate one or more of the following API methods to the renderer:
48 * <ul>
49 * <li>{@code createDom} - renders the DOM for the component
50 * <li>{@code canDecorate} - determines whether an element can be decorated
51 * by the component
52 * <li>{@code decorate} - decorates an existing element with the component
53 * <li>{@code setState} - updates the appearance of the component based on
54 * its state
55 * <li>{@code getContent} - returns the component's content
56 * <li>{@code setContent} - sets the component's content
57 * </ul>
58 * Controls are stateful; renderers, on the other hand, should be stateless and
59 * reusable.
60 * @constructor
61 */
62 goog.ui.ControlRenderer = function() {};
63 goog.addSingletonGetter(goog.ui.ControlRenderer);
64 goog.tagUnsealableClass(goog.ui.ControlRenderer);
65
66
67 /**
68 * Constructs a new renderer and sets the CSS class that the renderer will use
69 * as the base CSS class to apply to all elements rendered by that renderer.
70 * An example to use this function using a color palette:
71 *
72 * <pre>
73 * var myCustomRenderer = goog.ui.ControlRenderer.getCustomRenderer(
74 * goog.ui.PaletteRenderer, 'my-special-palette');
75 * var newColorPalette = new goog.ui.ColorPalette(
76 * colors, myCustomRenderer, opt_domHelper);
77 * </pre>
78 *
79 * Your CSS can look like this now:
80 * <pre>
81 * .my-special-palette { }
82 * .my-special-palette-table { }
83 * .my-special-palette-cell { }
84 * etc.
85 * </pre>
86 *
87 * <em>instead</em> of
88 * <pre>
89 * .CSS_MY_SPECIAL_PALETTE .goog-palette { }
90 * .CSS_MY_SPECIAL_PALETTE .goog-palette-table { }
91 * .CSS_MY_SPECIAL_PALETTE .goog-palette-cell { }
92 * etc.
93 * </pre>
94 *
95 * You would want to use this functionality when you want an instance of a
96 * component to have specific styles different than the other components of the
97 * same type in your application. This avoids using descendant selectors to
98 * apply the specific styles to this component.
99 *
100 * @param {Function} ctor The constructor of the renderer you are trying to
101 * create.
102 * @param {string} cssClassName The name of the CSS class for this renderer.
103 * @return {goog.ui.ControlRenderer} An instance of the desired renderer with
104 * its getCssClass() method overridden to return the supplied custom CSS
105 * class name.
106 */
107 goog.ui.ControlRenderer.getCustomRenderer = function(ctor, cssClassName) {
108 var renderer = new ctor();
109
110 /**
111 * Returns the CSS class to be applied to the root element of components
112 * rendered using this renderer.
113 * @return {string} Renderer-specific CSS class.
114 */
115 renderer.getCssClass = function() { return cssClassName; };
116
117 return renderer;
118 };
119
120
121 /**
122 * Default CSS class to be applied to the root element of components rendered
123 * by this renderer.
124 * @type {string}
125 */
126 goog.ui.ControlRenderer.CSS_CLASS = goog.getCssName('goog-control');
127
128
129 /**
130 * Array of arrays of CSS classes that we want composite classes added and
131 * removed for in IE6 and lower as a workaround for lack of multi-class CSS
132 * selector support.
133 *
134 * Subclasses that have accompanying CSS requiring this workaround should define
135 * their own static IE6_CLASS_COMBINATIONS constant and override
136 * getIe6ClassCombinations to return it.
137 *
138 * For example, if your stylesheet uses the selector .button.collapse-left
139 * (and is compiled to .button_collapse-left for the IE6 version of the
140 * stylesheet,) you should include ['button', 'collapse-left'] in this array
141 * and the class button_collapse-left will be applied to the root element
142 * whenever both button and collapse-left are applied individually.
143 *
144 * Members of each class name combination will be joined with underscores in the
145 * order that they're defined in the array. You should alphabetize them (for
146 * compatibility with the CSS compiler) unless you are doing something special.
147 * @type {Array<Array<string>>}
148 */
149 goog.ui.ControlRenderer.IE6_CLASS_COMBINATIONS = [];
150
151
152 /**
153 * Map of component states to corresponding ARIA attributes. Since the mapping
154 * of component states to ARIA attributes is neither component- nor
155 * renderer-specific, this is a static property of the renderer class, and is
156 * initialized on first use.
157 * @type {Object<goog.ui.Component.State, goog.a11y.aria.State>}
158 * @private
159 */
160 goog.ui.ControlRenderer.ariaAttributeMap_;
161
162
163 /**
164 * Map of certain ARIA states to ARIA roles that support them. Used for checked
165 * and selected Component states because they are used on Components with ARIA
166 * roles that do not support the corresponding ARIA state.
167 * @private {!Object<goog.a11y.aria.Role, goog.a11y.aria.State>}
168 * @const
169 */
170 goog.ui.ControlRenderer.TOGGLE_ARIA_STATE_MAP_ = goog.object.create(
171 goog.a11y.aria.Role.BUTTON, goog.a11y.aria.State.PRESSED,
172 goog.a11y.aria.Role.CHECKBOX, goog.a11y.aria.State.CHECKED,
173 goog.a11y.aria.Role.MENU_ITEM, goog.a11y.aria.State.SELECTED,
174 goog.a11y.aria.Role.MENU_ITEM_CHECKBOX, goog.a11y.aria.State.CHECKED,
175 goog.a11y.aria.Role.MENU_ITEM_RADIO, goog.a11y.aria.State.CHECKED,
176 goog.a11y.aria.Role.RADIO, goog.a11y.aria.State.CHECKED,
177 goog.a11y.aria.Role.TAB, goog.a11y.aria.State.SELECTED,
178 goog.a11y.aria.Role.TREEITEM, goog.a11y.aria.State.SELECTED);
179
180
181 /**
182 * Returns the ARIA role to be applied to the control.
183 * See http://wiki/Main/ARIA for more info.
184 * @return {goog.a11y.aria.Role|undefined} ARIA role.
185 */
186 goog.ui.ControlRenderer.prototype.getAriaRole = function() {
187 // By default, the ARIA role is unspecified.
188 return undefined;
189 };
190
191
192 /**
193 * Returns the control's contents wrapped in a DIV, with the renderer's own
194 * CSS class and additional state-specific classes applied to it.
195 * @param {goog.ui.Control} control Control to render.
196 * @return {Element} Root element for the control.
197 */
198 goog.ui.ControlRenderer.prototype.createDom = function(control) {
199 // Create and return DIV wrapping contents.
200 var element = control.getDomHelper().createDom(
201 goog.dom.TagName.DIV, this.getClassNames(control).join(' '),
202 control.getContent());
203
204 return element;
205 };
206
207
208 /**
209 * Takes the control's root element and returns the parent element of the
210 * control's contents. Since by default controls are rendered as a single
211 * DIV, the default implementation returns the element itself. Subclasses
212 * with more complex DOM structures must override this method as needed.
213 * @param {Element} element Root element of the control whose content element
214 * is to be returned.
215 * @return {Element} The control's content element.
216 */
217 goog.ui.ControlRenderer.prototype.getContentElement = function(element) {
218 return element;
219 };
220
221
222 /**
223 * Updates the control's DOM by adding or removing the specified class name
224 * to/from its root element. May add additional combined classes as needed in
225 * IE6 and lower. Because of this, subclasses should use this method when
226 * modifying class names on the control's root element.
227 * @param {goog.ui.Control|Element} control Control instance (or root element)
228 * to be updated.
229 * @param {string} className CSS class name to add or remove.
230 * @param {boolean} enable Whether to add or remove the class name.
231 */
232 goog.ui.ControlRenderer.prototype.enableClassName = function(
233 control, className, enable) {
234 var element = /** @type {Element} */ (
235 control.getElement ? control.getElement() : control);
236 if (element) {
237 var classNames = [className];
238
239 // For IE6, we need to enable any combined classes involving this class
240 // as well.
241 // TODO(user): Remove this as IE6 is no longer in use.
242 if (goog.userAgent.IE && !goog.userAgent.isVersionOrHigher('7')) {
243 classNames = this.getAppliedCombinedClassNames_(
244 goog.dom.classlist.get(element), className);
245 classNames.push(className);
246 }
247
248 goog.dom.classlist.enableAll(element, classNames, enable);
249 }
250 };
251
252
253 /**
254 * Updates the control's DOM by adding or removing the specified extra class
255 * name to/from its element.
256 * @param {goog.ui.Control} control Control to be updated.
257 * @param {string} className CSS class name to add or remove.
258 * @param {boolean} enable Whether to add or remove the class name.
259 */
260 goog.ui.ControlRenderer.prototype.enableExtraClassName = function(
261 control, className, enable) {
262 // The base class implementation is trivial; subclasses should override as
263 // needed.
264 this.enableClassName(control, className, enable);
265 };
266
267
268 /**
269 * Returns true if this renderer can decorate the element, false otherwise.
270 * The default implementation always returns true.
271 * @param {Element} element Element to decorate.
272 * @return {boolean} Whether the renderer can decorate the element.
273 */
274 goog.ui.ControlRenderer.prototype.canDecorate = function(element) {
275 return true;
276 };
277
278
279 /**
280 * Default implementation of {@code decorate} for {@link goog.ui.Control}s.
281 * Initializes the control's ID, content, and state based on the ID of the
282 * element, its child nodes, and its CSS classes, respectively. Returns the
283 * element.
284 * @param {goog.ui.Control} control Control instance to decorate the element.
285 * @param {Element} element Element to decorate.
286 * @return {Element} Decorated element.
287 */
288 goog.ui.ControlRenderer.prototype.decorate = function(control, element) {
289 // Set the control's ID to the decorated element's DOM ID, if any.
290 if (element.id) {
291 control.setId(element.id);
292 }
293
294 // Set the control's content to the decorated element's content.
295 var contentElem = this.getContentElement(element);
296 if (contentElem && contentElem.firstChild) {
297 control.setContentInternal(
298 contentElem.firstChild.nextSibling ?
299 goog.array.clone(contentElem.childNodes) :
300 contentElem.firstChild);
301 } else {
302 control.setContentInternal(null);
303 }
304
305 // Initialize the control's state based on the decorated element's CSS class.
306 // This implementation is optimized to minimize object allocations, string
307 // comparisons, and DOM access.
308 var state = 0x00;
309 var rendererClassName = this.getCssClass();
310 var structuralClassName = this.getStructuralCssClass();
311 var hasRendererClassName = false;
312 var hasStructuralClassName = false;
313 var hasCombinedClassName = false;
314 var classNames = goog.array.toArray(goog.dom.classlist.get(element));
315 goog.array.forEach(classNames, function(className) {
316 if (!hasRendererClassName && className == rendererClassName) {
317 hasRendererClassName = true;
318 if (structuralClassName == rendererClassName) {
319 hasStructuralClassName = true;
320 }
321 } else if (!hasStructuralClassName && className == structuralClassName) {
322 hasStructuralClassName = true;
323 } else {
324 state |= this.getStateFromClass(className);
325 }
326 if (this.getStateFromClass(className) == goog.ui.Component.State.DISABLED) {
327 goog.asserts.assertElement(contentElem);
328 if (goog.dom.isFocusableTabIndex(contentElem)) {
329 goog.dom.setFocusableTabIndex(contentElem, false);
330 }
331 }
332 }, this);
333 control.setStateInternal(state);
334
335 // Make sure the element has the renderer's CSS classes applied, as well as
336 // any extra class names set on the control.
337 if (!hasRendererClassName) {
338 classNames.push(rendererClassName);
339 if (structuralClassName == rendererClassName) {
340 hasStructuralClassName = true;
341 }
342 }
343 if (!hasStructuralClassName) {
344 classNames.push(structuralClassName);
345 }
346 var extraClassNames = control.getExtraClassNames();
347 if (extraClassNames) {
348 classNames.push.apply(classNames, extraClassNames);
349 }
350
351 // For IE6, rewrite all classes on the decorated element if any combined
352 // classes apply.
353 if (goog.userAgent.IE && !goog.userAgent.isVersionOrHigher('7')) {
354 var combinedClasses = this.getAppliedCombinedClassNames_(classNames);
355 if (combinedClasses.length > 0) {
356 classNames.push.apply(classNames, combinedClasses);
357 hasCombinedClassName = true;
358 }
359 }
360
361 // Only write to the DOM if new class names had to be added to the element.
362 if (!hasRendererClassName || !hasStructuralClassName || extraClassNames ||
363 hasCombinedClassName) {
364 goog.dom.classlist.set(element, classNames.join(' '));
365 }
366
367 return element;
368 };
369
370
371 /**
372 * Initializes the control's DOM by configuring properties that can only be set
373 * after the DOM has entered the document. This implementation sets up BiDi
374 * and keyboard focus. Called from {@link goog.ui.Control#enterDocument}.
375 * @param {goog.ui.Control} control Control whose DOM is to be initialized
376 * as it enters the document.
377 */
378 goog.ui.ControlRenderer.prototype.initializeDom = function(control) {
379 // Initialize render direction (BiDi). We optimize the left-to-right render
380 // direction by assuming that elements are left-to-right by default, and only
381 // updating their styling if they are explicitly set to right-to-left.
382 if (control.isRightToLeft()) {
383 this.setRightToLeft(control.getElement(), true);
384 }
385
386 // Initialize keyboard focusability (tab index). We assume that components
387 // aren't focusable by default (i.e have no tab index), and only touch the
388 // DOM if the component is focusable, enabled, and visible, and therefore
389 // needs a tab index.
390 if (control.isEnabled()) {
391 this.setFocusable(control, control.isVisible());
392 }
393 };
394
395
396 /**
397 * Sets the element's ARIA role.
398 * @param {Element} element Element to update.
399 * @param {?goog.a11y.aria.Role=} opt_preferredRole The preferred ARIA role.
400 */
401 goog.ui.ControlRenderer.prototype.setAriaRole = function(
402 element, opt_preferredRole) {
403 var ariaRole = opt_preferredRole || this.getAriaRole();
404 if (ariaRole) {
405 goog.asserts.assert(
406 element, 'The element passed as a first parameter cannot be null.');
407 var currentRole = goog.a11y.aria.getRole(element);
408 if (ariaRole == currentRole) {
409 return;
410 }
411 goog.a11y.aria.setRole(element, ariaRole);
412 }
413 };
414
415
416 /**
417 * Sets the element's ARIA attributes, including distinguishing between
418 * universally supported ARIA properties and ARIA states that are only
419 * supported by certain ARIA roles. Only attributes which are initialized to be
420 * true will be set.
421 * @param {!goog.ui.Control} control Control whose ARIA state will be updated.
422 * @param {!Element} element Element whose ARIA state is to be updated.
423 */
424 goog.ui.ControlRenderer.prototype.setAriaStates = function(control, element) {
425 goog.asserts.assert(control);
426 goog.asserts.assert(element);
427
428 var ariaLabel = control.getAriaLabel();
429 if (goog.isDefAndNotNull(ariaLabel)) {
430 this.setAriaLabel(element, ariaLabel);
431 }
432
433 if (!control.isVisible()) {
434 goog.a11y.aria.setState(
435 element, goog.a11y.aria.State.HIDDEN, !control.isVisible());
436 }
437 if (!control.isEnabled()) {
438 this.updateAriaState(
439 element, goog.ui.Component.State.DISABLED, !control.isEnabled());
440 }
441 if (control.isSupportedState(goog.ui.Component.State.SELECTED)) {
442 this.updateAriaState(
443 element, goog.ui.Component.State.SELECTED, control.isSelected());
444 }
445 if (control.isSupportedState(goog.ui.Component.State.CHECKED)) {
446 this.updateAriaState(
447 element, goog.ui.Component.State.CHECKED, control.isChecked());
448 }
449 if (control.isSupportedState(goog.ui.Component.State.OPENED)) {
450 this.updateAriaState(
451 element, goog.ui.Component.State.OPENED, control.isOpen());
452 }
453 };
454
455
456 /**
457 * Sets the element's ARIA label. This should be overriden by subclasses that
458 * don't apply the role directly on control.element_.
459 * @param {!Element} element Element whose ARIA label is to be updated.
460 * @param {string} ariaLabel Label to add to the element.
461 */
462 goog.ui.ControlRenderer.prototype.setAriaLabel = function(element, ariaLabel) {
463 goog.a11y.aria.setLabel(element, ariaLabel);
464 };
465
466
467 /**
468 * Allows or disallows text selection within the control's DOM.
469 * @param {Element} element The control's root element.
470 * @param {boolean} allow Whether the element should allow text selection.
471 */
472 goog.ui.ControlRenderer.prototype.setAllowTextSelection = function(
473 element, allow) {
474 // On all browsers other than IE and Opera, it isn't necessary to recursively
475 // apply unselectable styling to the element's children.
476 goog.style.setUnselectable(
477 element, !allow, !goog.userAgent.IE && !goog.userAgent.OPERA);
478 };
479
480
481 /**
482 * Applies special styling to/from the control's element if it is rendered
483 * right-to-left, and removes it if it is rendered left-to-right.
484 * @param {Element} element The control's root element.
485 * @param {boolean} rightToLeft Whether the component is rendered
486 * right-to-left.
487 */
488 goog.ui.ControlRenderer.prototype.setRightToLeft = function(
489 element, rightToLeft) {
490 this.enableClassName(
491 element, goog.getCssName(this.getStructuralCssClass(), 'rtl'),
492 rightToLeft);
493 };
494
495
496 /**
497 * Returns true if the control's key event target supports keyboard focus
498 * (based on its {@code tabIndex} attribute), false otherwise.
499 * @param {goog.ui.Control} control Control whose key event target is to be
500 * checked.
501 * @return {boolean} Whether the control's key event target is focusable.
502 */
503 goog.ui.ControlRenderer.prototype.isFocusable = function(control) {
504 var keyTarget;
505 if (control.isSupportedState(goog.ui.Component.State.FOCUSED) &&
506 (keyTarget = control.getKeyEventTarget())) {
507 return goog.dom.isFocusableTabIndex(keyTarget);
508 }
509 return false;
510 };
511
512
513 /**
514 * Updates the control's key event target to make it focusable or non-focusable
515 * via its {@code tabIndex} attribute. Does nothing if the control doesn't
516 * support the {@code FOCUSED} state, or if it has no key event target.
517 * @param {goog.ui.Control} control Control whose key event target is to be
518 * updated.
519 * @param {boolean} focusable Whether to enable keyboard focus support on the
520 * control's key event target.
521 */
522 goog.ui.ControlRenderer.prototype.setFocusable = function(control, focusable) {
523 var keyTarget;
524 if (control.isSupportedState(goog.ui.Component.State.FOCUSED) &&
525 (keyTarget = control.getKeyEventTarget())) {
526 if (!focusable && control.isFocused()) {
527 // Blur before hiding. Note that IE calls onblur handlers asynchronously.
528 try {
529 keyTarget.blur();
530 } catch (e) {
531 // TODO(user|user): Find out why this fails on IE.
532 }
533 // The blur event dispatched by the key event target element when blur()
534 // was called on it should have been handled by the control's handleBlur()
535 // method, so at this point the control should no longer be focused.
536 // However, blur events are unreliable on IE and FF3, so if at this point
537 // the control is still focused, we trigger its handleBlur() method
538 // programmatically.
539 if (control.isFocused()) {
540 control.handleBlur(null);
541 }
542 }
543 // Don't overwrite existing tab index values unless needed.
544 if (goog.dom.isFocusableTabIndex(keyTarget) != focusable) {
545 goog.dom.setFocusableTabIndex(keyTarget, focusable);
546 }
547 }
548 };
549
550
551 /**
552 * Shows or hides the element.
553 * @param {Element} element Element to update.
554 * @param {boolean} visible Whether to show the element.
555 */
556 goog.ui.ControlRenderer.prototype.setVisible = function(element, visible) {
557 // The base class implementation is trivial; subclasses should override as
558 // needed. It should be possible to do animated reveals, for example.
559 goog.style.setElementShown(element, visible);
560 if (element) {
561 goog.a11y.aria.setState(element, goog.a11y.aria.State.HIDDEN, !visible);
562 }
563 };
564
565
566 /**
567 * Updates the appearance of the control in response to a state change.
568 * @param {goog.ui.Control} control Control instance to update.
569 * @param {goog.ui.Component.State} state State to enable or disable.
570 * @param {boolean} enable Whether the control is entering or exiting the state.
571 */
572 goog.ui.ControlRenderer.prototype.setState = function(control, state, enable) {
573 var element = control.getElement();
574 if (element) {
575 var className = this.getClassForState(state);
576 if (className) {
577 this.enableClassName(control, className, enable);
578 }
579 this.updateAriaState(element, state, enable);
580 }
581 };
582
583
584 /**
585 * Updates the element's ARIA (accessibility) attributes , including
586 * distinguishing between universally supported ARIA properties and ARIA states
587 * that are only supported by certain ARIA roles.
588 * @param {Element} element Element whose ARIA state is to be updated.
589 * @param {goog.ui.Component.State} state Component state being enabled or
590 * disabled.
591 * @param {boolean} enable Whether the state is being enabled or disabled.
592 * @protected
593 */
594 goog.ui.ControlRenderer.prototype.updateAriaState = function(
595 element, state, enable) {
596 // Ensure the ARIA attribute map exists.
597 if (!goog.ui.ControlRenderer.ariaAttributeMap_) {
598 goog.ui.ControlRenderer.ariaAttributeMap_ = goog.object.create(
599 goog.ui.Component.State.DISABLED, goog.a11y.aria.State.DISABLED,
600 goog.ui.Component.State.SELECTED, goog.a11y.aria.State.SELECTED,
601 goog.ui.Component.State.CHECKED, goog.a11y.aria.State.CHECKED,
602 goog.ui.Component.State.OPENED, goog.a11y.aria.State.EXPANDED);
603 }
604 goog.asserts.assert(
605 element, 'The element passed as a first parameter cannot be null.');
606 var ariaAttr = goog.ui.ControlRenderer.getAriaStateForAriaRole_(
607 element, goog.ui.ControlRenderer.ariaAttributeMap_[state]);
608 if (ariaAttr) {
609 goog.a11y.aria.setState(element, ariaAttr, enable);
610 }
611 };
612
613
614 /**
615 * Returns the appropriate ARIA attribute based on ARIA role if the ARIA
616 * attribute is an ARIA state.
617 * @param {!Element} element The element from which to get the ARIA role for
618 * matching ARIA state.
619 * @param {goog.a11y.aria.State} attr The ARIA attribute to check to see if it
620 * can be applied to the given ARIA role.
621 * @return {goog.a11y.aria.State} An ARIA attribute that can be applied to the
622 * given ARIA role.
623 * @private
624 */
625 goog.ui.ControlRenderer.getAriaStateForAriaRole_ = function(element, attr) {
626 var role = goog.a11y.aria.getRole(element);
627 if (!role) {
628 return attr;
629 }
630 role = /** @type {goog.a11y.aria.Role} */ (role);
631 var matchAttr = goog.ui.ControlRenderer.TOGGLE_ARIA_STATE_MAP_[role] || attr;
632 return goog.ui.ControlRenderer.isAriaState_(attr) ? matchAttr : attr;
633 };
634
635
636 /**
637 * Determines if the given ARIA attribute is an ARIA property or ARIA state.
638 * @param {goog.a11y.aria.State} attr The ARIA attribute to classify.
639 * @return {boolean} If the ARIA attribute is an ARIA state.
640 * @private
641 */
642 goog.ui.ControlRenderer.isAriaState_ = function(attr) {
643 return attr == goog.a11y.aria.State.CHECKED ||
644 attr == goog.a11y.aria.State.SELECTED;
645 };
646
647
648 /**
649 * Takes a control's root element, and sets its content to the given text
650 * caption or DOM structure. The default implementation replaces the children
651 * of the given element. Renderers that create more complex DOM structures
652 * must override this method accordingly.
653 * @param {Element} element The control's root element.
654 * @param {goog.ui.ControlContent} content Text caption or DOM structure to be
655 * set as the control's content. The DOM nodes will not be cloned, they
656 * will only moved under the content element of the control.
657 */
658 goog.ui.ControlRenderer.prototype.setContent = function(element, content) {
659 var contentElem = this.getContentElement(element);
660 if (contentElem) {
661 goog.dom.removeChildren(contentElem);
662 if (content) {
663 if (goog.isString(content)) {
664 goog.dom.setTextContent(contentElem, content);
665 } else {
666 var childHandler = function(child) {
667 if (child) {
668 var doc = goog.dom.getOwnerDocument(contentElem);
669 contentElem.appendChild(
670 goog.isString(child) ? doc.createTextNode(child) : child);
671 }
672 };
673 if (goog.isArray(content)) {
674 // Array of nodes.
675 goog.array.forEach(content, childHandler);
676 } else if (goog.isArrayLike(content) && !('nodeType' in content)) {
677 // NodeList. The second condition filters out TextNode which also has
678 // length attribute but is not array like. The nodes have to be cloned
679 // because childHandler removes them from the list during iteration.
680 goog.array.forEach(
681 goog.array.clone(/** @type {!NodeList<?>} */ (content)),
682 childHandler);
683 } else {
684 // Node or string.
685 childHandler(content);
686 }
687 }
688 }
689 }
690 };
691
692
693 /**
694 * Returns the element within the component's DOM that should receive keyboard
695 * focus (null if none). The default implementation returns the control's root
696 * element.
697 * @param {goog.ui.Control} control Control whose key event target is to be
698 * returned.
699 * @return {Element} The key event target.
700 */
701 goog.ui.ControlRenderer.prototype.getKeyEventTarget = function(control) {
702 return control.getElement();
703 };
704
705
706 // CSS class name management.
707
708
709 /**
710 * Returns the CSS class name to be applied to the root element of all
711 * components rendered or decorated using this renderer. The class name
712 * is expected to uniquely identify the renderer class, i.e. no two
713 * renderer classes are expected to share the same CSS class name.
714 * @return {string} Renderer-specific CSS class name.
715 */
716 goog.ui.ControlRenderer.prototype.getCssClass = function() {
717 return goog.ui.ControlRenderer.CSS_CLASS;
718 };
719
720
721 /**
722 * Returns an array of combinations of classes to apply combined class names for
723 * in IE6 and below. See {@link IE6_CLASS_COMBINATIONS} for more detail. This
724 * method doesn't reference {@link IE6_CLASS_COMBINATIONS} so that it can be
725 * compiled out, but subclasses should return their IE6_CLASS_COMBINATIONS
726 * static constant instead.
727 * @return {Array<Array<string>>} Array of class name combinations.
728 */
729 goog.ui.ControlRenderer.prototype.getIe6ClassCombinations = function() {
730 return [];
731 };
732
733
734 /**
735 * Returns the name of a DOM structure-specific CSS class to be applied to the
736 * root element of all components rendered or decorated using this renderer.
737 * Unlike the class name returned by {@link #getCssClass}, the structural class
738 * name may be shared among different renderers that generate similar DOM
739 * structures. The structural class name also serves as the basis of derived
740 * class names used to identify and style structural elements of the control's
741 * DOM, as well as the basis for state-specific class names. The default
742 * implementation returns the same class name as {@link #getCssClass}, but
743 * subclasses are expected to override this method as needed.
744 * @return {string} DOM structure-specific CSS class name (same as the renderer-
745 * specific CSS class name by default).
746 */
747 goog.ui.ControlRenderer.prototype.getStructuralCssClass = function() {
748 return this.getCssClass();
749 };
750
751
752 /**
753 * Returns all CSS class names applicable to the given control, based on its
754 * state. The return value is an array of strings containing
755 * <ol>
756 * <li>the renderer-specific CSS class returned by {@link #getCssClass},
757 * followed by
758 * <li>the structural CSS class returned by {@link getStructuralCssClass} (if
759 * different from the renderer-specific CSS class), followed by
760 * <li>any state-specific classes returned by {@link #getClassNamesForState},
761 * followed by
762 * <li>any extra classes returned by the control's {@code getExtraClassNames}
763 * method and
764 * <li>for IE6 and lower, additional combined classes from
765 * {@link getAppliedCombinedClassNames_}.
766 * </ol>
767 * Since all controls have at least one renderer-specific CSS class name, this
768 * method is guaranteed to return an array of at least one element.
769 * @param {goog.ui.Control} control Control whose CSS classes are to be
770 * returned.
771 * @return {!Array<string>} Array of CSS class names applicable to the control.
772 * @protected
773 */
774 goog.ui.ControlRenderer.prototype.getClassNames = function(control) {
775 var cssClass = this.getCssClass();
776
777 // Start with the renderer-specific class name.
778 var classNames = [cssClass];
779
780 // Add structural class name, if different.
781 var structuralCssClass = this.getStructuralCssClass();
782 if (structuralCssClass != cssClass) {
783 classNames.push(structuralCssClass);
784 }
785
786 // Add state-specific class names, if any.
787 var classNamesForState = this.getClassNamesForState(control.getState());
788 classNames.push.apply(classNames, classNamesForState);
789
790 // Add extra class names, if any.
791 var extraClassNames = control.getExtraClassNames();
792 if (extraClassNames) {
793 classNames.push.apply(classNames, extraClassNames);
794 }
795
796 // Add composite classes for IE6 support
797 if (goog.userAgent.IE && !goog.userAgent.isVersionOrHigher('7')) {
798 classNames.push.apply(
799 classNames, this.getAppliedCombinedClassNames_(classNames));
800 }
801
802 return classNames;
803 };
804
805
806 /**
807 * Returns an array of all the combined class names that should be applied based
808 * on the given list of classes. Checks the result of
809 * {@link getIe6ClassCombinations} for any combinations that have all
810 * members contained in classes. If a combination matches, the members are
811 * joined with an underscore (in order), and added to the return array.
812 *
813 * If opt_includedClass is provided, return only the combined classes that have
814 * all members contained in classes AND include opt_includedClass as well.
815 * opt_includedClass is added to classes as well.
816 * @param {IArrayLike<string>} classes Array-like thing of classes to
817 * return matching combined classes for.
818 * @param {?string=} opt_includedClass If provided, get only the combined
819 * classes that include this one.
820 * @return {!Array<string>} Array of combined class names that should be
821 * applied.
822 * @private
823 */
824 goog.ui.ControlRenderer.prototype.getAppliedCombinedClassNames_ = function(
825 classes, opt_includedClass) {
826 var toAdd = [];
827 if (opt_includedClass) {
828 classes = goog.array.concat(classes, [opt_includedClass]);
829 }
830 goog.array.forEach(this.getIe6ClassCombinations(), function(combo) {
831 if (goog.array.every(combo, goog.partial(goog.array.contains, classes)) &&
832 (!opt_includedClass || goog.array.contains(combo, opt_includedClass))) {
833 toAdd.push(combo.join('_'));
834 }
835 });
836 return toAdd;
837 };
838
839
840 /**
841 * Takes a bit mask of {@link goog.ui.Component.State}s, and returns an array
842 * of the appropriate class names representing the given state, suitable to be
843 * applied to the root element of a component rendered using this renderer, or
844 * null if no state-specific classes need to be applied. This default
845 * implementation uses the renderer's {@link getClassForState} method to
846 * generate each state-specific class.
847 * @param {number} state Bit mask of component states.
848 * @return {!Array<string>} Array of CSS class names representing the given
849 * state.
850 * @protected
851 */
852 goog.ui.ControlRenderer.prototype.getClassNamesForState = function(state) {
853 var classNames = [];
854 while (state) {
855 // For each enabled state, push the corresponding CSS class name onto
856 // the classNames array.
857 var mask = state & -state; // Least significant bit
858 classNames.push(
859 this.getClassForState(
860 /** @type {goog.ui.Component.State} */ (mask)));
861 state &= ~mask;
862 }
863 return classNames;
864 };
865
866
867 /**
868 * Takes a single {@link goog.ui.Component.State}, and returns the
869 * corresponding CSS class name (null if none).
870 * @param {goog.ui.Component.State} state Component state.
871 * @return {string|undefined} CSS class representing the given state (undefined
872 * if none).
873 * @protected
874 */
875 goog.ui.ControlRenderer.prototype.getClassForState = function(state) {
876 if (!this.classByState_) {
877 this.createClassByStateMap_();
878 }
879 return this.classByState_[state];
880 };
881
882
883 /**
884 * Takes a single CSS class name which may represent a component state, and
885 * returns the corresponding component state (0x00 if none).
886 * @param {string} className CSS class name, possibly representing a component
887 * state.
888 * @return {goog.ui.Component.State} state Component state corresponding
889 * to the given CSS class (0x00 if none).
890 * @protected
891 */
892 goog.ui.ControlRenderer.prototype.getStateFromClass = function(className) {
893 if (!this.stateByClass_) {
894 this.createStateByClassMap_();
895 }
896 var state = parseInt(this.stateByClass_[className], 10);
897 return /** @type {goog.ui.Component.State} */ (isNaN(state) ? 0x00 : state);
898 };
899
900
901 /**
902 * Creates the lookup table of states to classes, used during state changes.
903 * @private
904 */
905 goog.ui.ControlRenderer.prototype.createClassByStateMap_ = function() {
906 var baseClass = this.getStructuralCssClass();
907
908 // This ensures space-separated css classnames are not allowed, which some
909 // ControlRenderers had been doing. See http://b/13694665.
910 var isValidClassName =
911 !goog.string.contains(goog.string.normalizeWhitespace(baseClass), ' ');
912 goog.asserts.assert(
913 isValidClassName,
914 'ControlRenderer has an invalid css class: \'' + baseClass + '\'');
915
916 /**
917 * Map of component states to state-specific structural class names,
918 * used when changing the DOM in response to a state change. Precomputed
919 * and cached on first use to minimize object allocations and string
920 * concatenation.
921 * @type {Object}
922 * @private
923 */
924 this.classByState_ = goog.object.create(
925 goog.ui.Component.State.DISABLED, goog.getCssName(baseClass, 'disabled'),
926 goog.ui.Component.State.HOVER, goog.getCssName(baseClass, 'hover'),
927 goog.ui.Component.State.ACTIVE, goog.getCssName(baseClass, 'active'),
928 goog.ui.Component.State.SELECTED, goog.getCssName(baseClass, 'selected'),
929 goog.ui.Component.State.CHECKED, goog.getCssName(baseClass, 'checked'),
930 goog.ui.Component.State.FOCUSED, goog.getCssName(baseClass, 'focused'),
931 goog.ui.Component.State.OPENED, goog.getCssName(baseClass, 'open'));
932 };
933
934
935 /**
936 * Creates the lookup table of classes to states, used during decoration.
937 * @private
938 */
939 goog.ui.ControlRenderer.prototype.createStateByClassMap_ = function() {
940 // We need the classByState_ map so we can transpose it.
941 if (!this.classByState_) {
942 this.createClassByStateMap_();
943 }
944
945 /**
946 * Map of state-specific structural class names to component states,
947 * used during element decoration. Precomputed and cached on first use
948 * to minimize object allocations and string concatenation.
949 * @type {Object}
950 * @private
951 */
952 this.stateByClass_ = goog.object.transpose(this.classByState_);
953 };