The goog.ui.ControlRenderer Class

goog.ui.ControlRenderer()

Default renderer for {@link goog.ui.Control}s. Can be used as-is, but subclasses of Control will probably want to use renderers specifically tailored for them by extending this class. Controls that use renderers delegate one or more of the following API methods to the renderer:

Controls are stateful; renderers, on the other hand, should be stateless and reusable.

.CSS_CLASS {string}

Default CSS class to be applied to the root element of components rendered by this renderer.

.IE6_CLASS_COMBINATIONS {Array.<Array.<string>>}

Array of arrays of CSS classes that we want composite classes added and removed for in IE6 and lower as a workaround for lack of multi-class CSS selector support. Subclasses that have accompanying CSS requiring this workaround should define their own static IE6_CLASS_COMBINATIONS constant and override getIe6ClassCombinations to return it. For example, if your stylesheet uses the selector .button.collapse-left (and is compiled to .button_collapse-left for the IE6 version of the stylesheet,) you should include ['button', 'collapse-left'] in this array and the class button_collapse-left will be applied to the root element whenever both button and collapse-left are applied individually. Members of each class name combination will be joined with underscores in the order that they're defined in the array. You should alphabetize them (for compatibility with the CSS compiler) unless you are doing something special.

.canDecorate(element)

Returns true if this renderer can decorate the element, false otherwise. The default implementation always returns true.

element {Element}
Element to decorate.
returns {boolean}
Whether the renderer can decorate the element.

.createDom(control)

Returns the control's contents wrapped in a DIV, with the renderer's own CSS class and additional state-specific classes applied to it.

control {goog.ui.Control}
Control to render.
returns {Element}
Root element for the control.

.decorate(control, element)

Default implementation of {@code decorate} for {@link goog.ui.Control}s. Initializes the control's ID, content, and state based on the ID of the element, its child nodes, and its CSS classes, respectively. Returns the element.

control {goog.ui.Control}
Control instance to decorate the element.
element {Element}
Element to decorate.
returns {Element}
Decorated element.
@suppress
{visibility} setContentInternal and setStateInternal

.enableClassName(control, className, enable)

Updates the control's DOM by adding or removing the specified class name to/from its root element. May add additional combined classes as needed in IE6 and lower. Because of this, subclasses should use this method when modifying class names on the control's root element.

control {goog.ui.Control|Element}
Control instance (or root element) to be updated.
className {string}
CSS class name to add or remove.
enable {boolean}
Whether to add or remove the class name.

.enableExtraClassName(control, className, enable)

Updates the control's DOM by adding or removing the specified extra class name to/from its element.

control {goog.ui.Control}
Control to be updated.
className {string}
CSS class name to add or remove.
enable {boolean}
Whether to add or remove the class name.

.getAriaRole()

Returns the ARIA role to be applied to the control. See http://wiki/Main/ARIA for more info.

returns {goog.dom.a11y.Role|undefined}
ARIA role.

.getContentElement(element)

Takes the control's root element and returns the parent element of the control's contents. Since by default controls are rendered as a single DIV, the default implementation returns the element itself. Subclasses with more complex DOM structures must override this method as needed.

element {Element}
Root element of the control whose content element is to be returned.
returns {Element}
The control's content element.

.getCssClass()

Returns the CSS class name to be applied to the root element of all components rendered or decorated using this renderer. The class name is expected to uniquely identify the renderer class, i.e. no two renderer classes are expected to share the same CSS class name.

returns {string}
Renderer-specific CSS class name.

.getCustomRenderer(ctor, cssClassName)

Constructs a new renderer and sets the CSS class that the renderer will use as the base CSS class to apply to all elements rendered by that renderer. An example to use this function using a color palette: 

 var myCustomRenderer = goog.ui.ControlRenderer.getCustomRenderer(
     goog.ui.PaletteRenderer, 'my-special-palette');
 var newColorPalette = new goog.ui.ColorPalette(
     colors, myCustomRenderer, opt_domHelper);
Your CSS can look like this now: 
 .my-special-palette { }
 .my-special-palette-table { }
 .my-special-palette-cell { }
 etc.
instead of 
 .CSS_MY_SPECIAL_PALETTE .goog-palette { }
 .CSS_MY_SPECIAL_PALETTE .goog-palette-table { }
 .CSS_MY_SPECIAL_PALETTE .goog-palette-cell { }
 etc.
You would want to use this functionality when you want an instance of a component to have specific styles different than the other components of the same type in your application. This avoids using descendant selectors to apply the specific styles to this component.
ctor {Function}
The constructor of the renderer you are trying to create.
cssClassName {string}
The name of the CSS class for this renderer.
returns {goog.ui.ControlRenderer}
An instance of the desired renderer with its getCssClass() method overridden to return the supplied custom CSS class name.

.getIe6ClassCombinations()

Returns an array of combinations of classes to apply combined class names for in IE6 and below. See {@link IE6_CLASS_COMBINATIONS} for more detail. This method doesn't reference {@link IE6_CLASS_COMBINATIONS} so that it can be compiled out, but subclasses should return their IE6_CLASS_COMBINATIONS static constant instead.

returns {Array.<Array.<string>>}
Array of class name combinations.

.getKeyEventTarget(control)

Returns the element within the component's DOM that should receive keyboard focus (null if none). The default implementation returns the control's root element.

control {goog.ui.Control}
Control whose key event target is to be returned.
returns {Element}
The key event target.

.getStructuralCssClass()

Returns the name of a DOM structure-specific CSS class to be applied to the root element of all components rendered or decorated using this renderer. Unlike the class name returned by {@link #getCssClass}, the structural class name may be shared among different renderers that generate similar DOM structures. The structural class name also serves as the basis of derived class names used to identify and style structural elements of the control's DOM, as well as the basis for state-specific class names. The default implementation returns the same class name as {@link #getCssClass}, but subclasses are expected to override this method as needed.

returns {string}
DOM structure-specific CSS class name (same as the renderer- specific CSS class name by default).

.initializeDom(control)

Initializes the control's DOM by configuring properties that can only be set after the DOM has entered the document. This implementation sets up BiDi and keyboard focus. Called from {@link goog.ui.Control#enterDocument}.

control {goog.ui.Control}
Control whose DOM is to be initialized as it enters the document.

.isFocusable(control)

Returns true if the control's key event target supports keyboard focus (based on its {@code tabIndex} attribute), false otherwise.

control {goog.ui.Control}
Control whose key event target is to be checked.
returns {boolean}
Whether the control's key event target is focusable.

.setAllowTextSelection(element, allow)

Allows or disallows text selection within the control's DOM.

element {Element}
The control's root element.
allow {boolean}
Whether the element should allow text selection.

.setAriaRole(element, opt_preferredRole)

Sets the element's ARIA role.

element {Element}
Element to update.
opt_preferredRole {?goog.dom.a11y.Role=}
The preferred ARIA role.

.setAriaStates(control, element)

Sets the element's ARIA states. An element does not need an ARIA role in order to have an ARIA state. Only states which are initialized to be true will be set.

control {!goog.ui.Control}
Control whose ARIA state will be updated.
element {!Element}
Element whose ARIA state is to be updated.

.setContent(element, content)

Takes a control's root element, and sets its content to the given text caption or DOM structure. The default implementation replaces the children of the given element. Renderers that create more complex DOM structures must override this method accordingly.

element {Element}
The control's root element.
content {goog.ui.ControlContent}
Text caption or DOM structure to be set as the control's content. The DOM nodes will not be cloned, they will only moved under the content element of the control.

.setFocusable(control, focusable)

Updates the control's key event target to make it focusable or non-focusable via its {@code tabIndex} attribute. Does nothing if the control doesn't support the {@code FOCUSED} state, or if it has no key event target.

control {goog.ui.Control}
Control whose key event target is to be updated.
focusable {boolean}
Whether to enable keyboard focus support on the control's key event target.

.setRightToLeft(element, rightToLeft)

Applies special styling to/from the control's element if it is rendered right-to-left, and removes it if it is rendered left-to-right.

element {Element}
The control's root element.
rightToLeft {boolean}
Whether the component is rendered right-to-left.

.setState(control, state, enable)

Updates the appearance of the control in response to a state change.

control {goog.ui.Control}
Control instance to update.
state {goog.ui.Component.State}
State to enable or disable.
enable {boolean}
Whether the control is entering or exiting the state.

.setVisible(element, visible)

Shows or hides the element.

element {Element}
Element to update.
visible {boolean}
Whether to show the element.

Documentation generated using JvJsDoc, version 0.5 on 2012-09-03.