Home

# 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:

- {@code createDom} - renders the DOM for the component
- {@code canDecorate} - determines whether an element can be decorated by the component
- {@code decorate} - decorates an existing element with the component
- {@code setState} - updates the appearance of the component based on its state
- {@code getContent} - returns the component's content
- {@code setContent} - sets the component's content

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

Instance Method Summary
| `canDecorate(?Element element) ⇒ boolean` Returns true if this renderer can decorate the element, false otherwise. The default implementation always returns true.
| `createClassByStateMap_()` Creates the lookup table of states to classes, used during state changes.
| `createDom(?goog.ui.Control control) ⇒ ?Element` Returns the control's contents wrapped in a DIV, with the renderer's own CSS class and additional state-specific classes applied to it.
| `createStateByClassMap_()` Creates the lookup table of classes to states, used during decoration.
| `decorate(?goog.ui.Control control, ?Element element) ⇒ ?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.
| `enableClassName((Element|goog.ui.Control|null) control, string className, boolean 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.
| `enableExtraClassName(?goog.ui.Control control, string className, boolean enable)` Updates the control's DOM by adding or removing the specified extra class name to/from its element.

`getAppliedCombinedClassNames_(?Array.<string> classes, ?string= opt_includedClass) ⇒ ?Array.<string>`

Returns an array of all the combined class names that should be applied based on the given list of classes. Checks the result of {@link getIe6ClassCombinations} for any combinations that have all members contained in classes. If a combination matches, the members are joined with an underscore (in order), and added to the return array. If opt_includedClass is provided, return only the combined classes that have all members contained in classes AND include opt_includedClass as well. opt_includedClass is added to classes as well.

| `getAriaRole() ⇒ (goog.dom.a11y.Role|null|undefined)` Returns the ARIA role to be applied to the control. See http://wiki/Main/ARIA for more info.
| `getClassForState(?goog.ui.Component.State state) ⇒ (string|undefined)` Takes a single {@link goog.ui.Component.State}, and returns the corresponding CSS class name (null if none).

`getClassNames(?goog.ui.Control control) ⇒ ?Array.<string>`

Returns all CSS class names applicable to the given control, based on its state. The return value is an array of strings containing

1. the renderer-specific CSS class returned by {@link #getCssClass}, followed by
2. the structural CSS class returned by {@link getStructuralCssClass} (if different from the renderer-specific CSS class), followed by
3. any state-specific classes returned by {@link #getClassNamesForState}, followed by
4. any extra classes returned by the control's {@code getExtraClassNames} method and
5. for IE6 and lower, additional combined classes from {@link getAppliedCombinedClassNames_}.

Since all controls have at least one renderer-specific CSS class name, this method is guaranteed to return an array of at least one element.

`getClassNamesForState(number state) ⇒ !Array`

Takes a bit mask of {@link goog.ui.Component.State}s, and returns an array of the appropriate class names representing the given state, suitable to be applied to the root element of a component rendered using this renderer, or null if no state-specific classes need to be applied. This default implementation uses the renderer's {@link getClassForState} method to generate each state-specific class.

| `getContentElement(?Element element) ⇒ ?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.
| `getCssClass() ⇒ string` 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.
| `getIe6ClassCombinations() ⇒ ?Array.<(Array.<string>|null)>` 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.
| `getKeyEventTarget(?goog.ui.Control control) ⇒ ?Element` 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.
| `getStateFromClass(string className) ⇒ ?goog.ui.Component.State` Takes a single CSS class name which may represent a component state, and returns the corresponding component state (0x00 if none).

`getStructuralCssClass() ⇒ string`

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.

| `initializeDom(?goog.ui.Control 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}.
| `isFocusable(?goog.ui.Control control) ⇒ boolean` Returns true if the control's key event target supports keyboard focus (based on its {@code tabIndex} attribute), false otherwise.
| `setAllowTextSelection(?Element element, boolean allow)` Allows or disallows text selection within the control's DOM.
| `setAriaRole(?Element element, ?goog.dom.a11y.Role= opt_preferredRole)` Sets the element's ARIA role.
| `setAriaStates(!goog.ui.Control control, !Element 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.
| `setContent(?Element element, ?goog.ui.ControlContent 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.
| `setFocusable(?goog.ui.Control control, boolean 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.
| `setRightToLeft(?Element element, boolean 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.
| `setState(?goog.ui.Control control, ?goog.ui.Component.State state, boolean enable)` Updates the appearance of the control in response to a state change.
| `setVisible(?Element element, boolean visible)` Shows or hides the element.
| `updateAriaState(?Element element, ?goog.ui.Component.State state, boolean enable)` Updates the element's ARIA (accessibility) state.

Static Method Summary

`getCustomRenderer(?Function ctor, string cssClassName) ⇒ ?goog.ui.ControlRenderer`

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.