| 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 |
}; |