;
/**
* 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 = 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.
*
* @param {?Function} ctor The constructor of the renderer you are trying to
* create.
* @param {string} cssClassName The name of the CSS class for this renderer.
* @return {?ControlRenderer} An instance of the desired renderer with
* its getCssClass() method overridden to return the supplied custom CSS
* class name.
*/
static getCustomRenderer(ctor: Function | null, cssClassName: string): ControlRenderer | null;
/**
* Returns the appropriate ARIA attribute based on ARIA role if the ARIA
* attribute is an ARIA state.
* @param {!Element} element The element from which to get the ARIA role for
* matching ARIA state.
* @param {?AriaState} attr The ARIA attribute to check to see if it
* can be applied to the given ARIA role.
* @return {?AriaState} An ARIA attribute that can be applied to the
* given ARIA role.
* @private
*/
private static getAriaStateForAriaRole_;
/**
* Determines if the given ARIA attribute is an ARIA property or ARIA state.
* @param {?AriaState} attr The ARIA attribute to classify.
* @return {boolean} If the ARIA attribute is an ARIA state.
* @private
*/
private static isAriaState_;
/**
* Returns the ARIA role to be applied to the control.
* See http://wiki/Main/ARIA for more info.
* @return {Role|undefined} ARIA role.
*/
getAriaRole(): Role | undefined;
/**
* Returns the control's contents wrapped in a DIV, with the renderer's own
* CSS class and additional state-specific classes applied to it.
* @param {?CONTROL} control Control to render.
* @return {?Element} Root element for the control.
*/
createDom(control: CONTROL | null): Element | null;
/**
* 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.
* @param {?Element} element Root element of the control whose content element
* is to be returned.
* @return {?Element} The control's content element.
*/
getContentElement(element: Element | null): Element | null;
/**
* 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.
* @param {CONTROL|?Element} control Control instance (or root element)
* to be updated.
* @param {string} className CSS class name to add or remove.
* @param {boolean} enable Whether to add or remove the class name.
*/
enableClassName(control: Element | CONTROL | null, className: string, enable: boolean): void;
/**
* Updates the control's DOM by adding or removing the specified extra class
* name to/from its element.
* @param {?CONTROL} control Control to be updated.
* @param {string} className CSS class name to add or remove.
* @param {boolean} enable Whether to add or remove the class name.
*/
enableExtraClassName(control: CONTROL | null, className: string, enable: boolean): void;
/**
* Returns true if this renderer can decorate the element, false otherwise.
* The default implementation always returns true.
* @param {?Element} element Element to decorate.
* @return {boolean} Whether the renderer can decorate the element.
*/
canDecorate(element: Element | null): boolean;
/**
* Default implementation of `decorate` for {@link 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.
* @param {?CONTROL} control Control instance to decorate the element.
* @param {?Element} element Element to decorate.
* @return {?Element} Decorated element.
*/
decorate(control: CONTROL | null, element: Element | null): Element | null;
/**
* 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 Control#enterDocument}.
* @param {?CONTROL} control Control whose DOM is to be initialized
* as it enters the document.
*/
initializeDom(control: CONTROL | null): void;
/**
* Sets the element's ARIA role.
* @param {?Element} element Element to update.
* @param {?Role=} opt_preferredRole The preferred ARIA role.
*/
setAriaRole(element: Element | null, opt_preferredRole?: (Role | null) | undefined): void;
/**
* Sets the element's ARIA attributes, including distinguishing between
* universally supported ARIA properties and ARIA states that are only
* supported by certain ARIA roles. Only attributes which are initialized to be
* true will be set.
* @param {!Control} control Control whose ARIA state will be updated.
* @param {!Element} element Element whose ARIA state is to be updated.
*/
setAriaStates(control: Control, element: Element): void;
/**
* Sets the element's ARIA label. This should be overriden by subclasses that
* don't apply the role directly on control.element_.
* @param {!Element} element Element whose ARIA label is to be updated.
* @param {string} ariaLabel Label to add to the element.
*/
setAriaLabel(element: Element, ariaLabel: string): void;
/**
* Allows or disallows text selection within the control's DOM.
* @param {?Element} element The control's root element.
* @param {boolean} allow Whether the element should allow text selection.
*/
setAllowTextSelection(element: Element | null, allow: boolean): void;
/**
* 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.
* @param {?Element} element The control's root element.
* @param {boolean} rightToLeft Whether the component is rendered
* right-to-left.
*/
setRightToLeft(element: Element | null, rightToLeft: boolean): void;
/**
* Returns true if the control's key event target supports keyboard focus
* (based on its `tabIndex` attribute), false otherwise.
* @param {?CONTROL} control Control whose key event target is to be
* checked.
* @return {boolean} Whether the control's key event target is focusable.
*/
isFocusable(control: CONTROL | null): boolean;
/**
* Updates the control's key event target to make it focusable or non-focusable
* via its `tabIndex` attribute. Does nothing if the control doesn't
* support the `FOCUSED` state, or if it has no key event target.
* @param {?CONTROL} control Control whose key event target is to be
* updated.
* @param {boolean} focusable Whether to enable keyboard focus support on the
* control's key event target.
*/
setFocusable(control: CONTROL | null, focusable: boolean): void;
/**
* Shows or hides the element.
* @param {?Element} element Element to update.
* @param {boolean} visible Whether to show the element.
*/
setVisible(element: Element | null, visible: boolean): void;
/**
* Updates the appearance of the control in response to a state change.
* @param {?CONTROL} control Control instance to update.
* @param {?State} state State to enable or disable.
* @param {boolean} enable Whether the control is entering or exiting the state.
*/
setState(control: CONTROL | null, state: State | null, enable: boolean): void;
/**
* Updates the element's ARIA (accessibility) attributes , including
* distinguishing between universally supported ARIA properties and ARIA states
* that are only supported by certain ARIA roles.
* @param {?Element} element Element whose ARIA state is to be updated.
* @param {?State} state Component state being enabled or
* disabled.
* @param {boolean} enable Whether the state is being enabled or disabled.
* @protected
*/
protected updateAriaState(element: Element | null, state: State | null, enable: boolean): void;
/**
* 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.
* @suppress{checkTypes}
* @param {?Element} element The control's root element.
* @param {?ControlContent} content 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.
*/
setContent(element: Element | null, content: ControlContent | null): void;
/**
* 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.
* @param {?CONTROL} control Control whose key event target is to be
* returned.
* @return {?Element} The key event target.
*/
getKeyEventTarget(control: CONTROL | null): Element | null;
/**
* 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.
* @return {string} Renderer-specific CSS class name.
*/
getCssClass(): string;
/**
* 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.
* @return {!Array>} Array of class name combinations.
*/
getIe6ClassCombinations(): Array>;
/**
* 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.
* @return {string} DOM structure-specific CSS class name (same as the renderer-
* specific CSS class name by default).
*/
getStructuralCssClass(): string;
/**
* Returns all CSS class names applicable to the given control, based on its
* state. The return value is an array of strings containing
*
* - the renderer-specific CSS class returned by {@link #getCssClass},
* followed by
*
- the structural CSS class returned by {@link getStructuralCssClass} (if
* different from the renderer-specific CSS class), followed by
*
- any state-specific classes returned by {@link #getClassNamesForState},
* followed by
*
- any extra classes returned by the control's `getExtraClassNames`
* method and
*
- 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.
* @param {?CONTROL} control Control whose CSS classes are to be
* returned.
* @return {!Array} Array of CSS class names applicable to the control.
* @protected
*/
protected getClassNames(control: CONTROL | null): Array;
/**
* 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.
* @param {ArrayLike} classes Array-like thing of classes to
* return matching combined classes for.
* @param {?string=} opt_includedClass If provided, get only the combined
* classes that include this one.
* @return {!Array} Array of combined class names that should be
* applied.
* @private
*/
private getAppliedCombinedClassNames_;
/**
* Takes a bit mask of {@link 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.
* @param {number} state Bit mask of component states.
* @return {!Array} Array of CSS class names representing the given
* state.
* @protected
*/
protected getClassNamesForState(state: number): Array;
/**
* Takes a single {@link State}, and returns the
* corresponding CSS class name (null if none).
* @param {?State} state Component state.
* @return {string|undefined} CSS class representing the given state (undefined
* if none).
* @protected
*/
protected getClassForState(state: State | null): string | undefined;
/**
* Takes a single CSS class name which may represent a component state, and
* returns the corresponding component state (0x00 if none).
* @param {string} className CSS class name, possibly representing a component
* state.
* @return {?State} state Component state corresponding
* to the given CSS class (0x00 if none).
* @protected
*/
protected getStateFromClass(className: string): State | null;
/**
* Creates the lookup table of states to classes, used during state changes.
* @private
*/
private createClassByStateMap_;
/**
* Map of component states to state-specific structural class names,
* used when changing the DOM in response to a state change. Precomputed
* and cached on first use to minimize object allocations and string
* concatenation.
* @type {?Object}
* @private
*/
private classByState_;
/**
* Creates the lookup table of classes to states, used during decoration.
* @private
*/
private createStateByClassMap_;
/**
* Map of state-specific structural class names to component states,
* used during element decoration. Precomputed and cached on first use
* to minimize object allocations and string concatenation.
* @type {?Object}
* @private
*/
private stateByClass_;
}
export namespace ControlRenderer {
const instance_: undefined | ControlRenderer;
const CSS_CLASS: string;
const IE6_CLASS_COMBINATIONS: Array>;
const ariaAttributeMap_: any;
const TOGGLE_ARIA_STATE_MAP_: any;
}
/**
* Returns an instance of {@link Ui_Component} or a subclass suitable to
* decorate the given element, based on its CSS class.
*
* TODO(nnaze): Type of element should be {!Element}.
*
* @param {?Element} element Element to decorate.
* @return {Ui_Component?} Component to decorate the element (null if
* none).
*/
export function getDecorator(element: Element | null): Ui_Component | null;
/**
* Returns the {@link Ui_Component} instance created by the decorator
* factory function registered for the given CSS class name, or null if no
* decorator factory function was found.
* @param {string} className CSS class name.
* @return {Ui_Component?} Component instance.
*/
export function getDecoratorByClassName(className: string): Ui_Component | null;
/**
* @license
* Copyright The Closure Library Authors.
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @fileoverview Global renderer and decorator registry.
*/
/**
* Given a {@link Ui_Component} constructor, returns an instance of its
* default renderer. If the default renderer is a singleton, returns the
* singleton instance; otherwise returns a new instance of the renderer class.
* @param {!Function} componentCtor Component constructor function (for example
* `goog.ui.Button`).
* @return {?ControlRenderer} Renderer instance (for example the
* singleton instance of `goog.ui.ButtonRenderer`), or null if
* no default renderer was found.
*/
export function getDefaultRenderer(componentCtor: Function): ControlRenderer | null;
/**
* Resets the global renderer and decorator registry.
*/
export function reset(): void;
/**
* Maps a CSS class name to a function that returns a new instance of
* {@link Ui_Component} or a subclass, suitable to decorate an element
* that has the specified CSS class.
* @param {string} className CSS class name.
* @param {?Function} decoratorFn No-argument function that returns a new
* instance of a {@link Ui_Component} to decorate an element.
* @throws {Error} If the class name or the decorator function is invalid.
*/
export function setDecoratorByClassName(className: string, decoratorFn: Function | null): void;
/**
* Sets the default renderer for the given {@link Ui_Component}
* constructor.
* @param {?Function} componentCtor Component constructor function (for example
* `goog.ui.Button`).
* @param {?Function} rendererCtor Renderer constructor function (for example
* `goog.ui.ButtonRenderer`).
* @throws {Error} If the arguments aren't functions.
*/
export function setDefaultRenderer(componentCtor: Function | null, rendererCtor: Function | null): void;
import { Component as Ui_Component } from "./component.js";
import { KeyHandler } from "../events/keyhandler.js";
import { Role } from "../a11y/aria/roles.js";
import { ControlContent } from "./controlcontent.js";
import { State } from "./component.js";
import { BrowserEvent as EventsBrowserEvent } from "../events/browserevent.js";
import { Event as EventsEvent } from "../events/event.js";
import { KeyEvent } from "../events/keyevent.js";
import { DomHelper } from "../dom/dom.js";
declare class IeMouseEventSequenceSimulator_ extends Disposable {
/**
* @param {!MouseEvent} e
* @param {?EventsEventType} typeArg
* @return {!MouseEvent}
* @private
*/
private static makeLeftMouseEvent_;
/**
* A singleton that helps Control instances play well with screen
* readers. It necessitated by shortcomings in IE, and need not be
* instantiated in any other browser.
*
* In most cases, a click on a Control results in a sequence of events:
* MOUSEDOWN, MOUSEUP and CLICK. UI controls rely on this sequence since most
* behavior is trigged by MOUSEDOWN and MOUSEUP. But when IE is used with some
* traditional screen readers (JAWS, NVDA and perhaps others), IE only sends
* the CLICK event, resulting in the control being unresponsive. This class
* monitors the sequence of these events, and if it detects a CLICK event not
* not preceded by a MOUSEUP event, directly calls the control's event handlers
* for MOUSEDOWN, then MOUSEUP. While the resulting sequence is different from
* the norm (the CLICK comes first instead of last), testing thus far shows
* the resulting behavior to be correct.
*
* See http://goo.gl/qvQR4C for more details.
*
* @param {!Control} control
* @private
*/
private constructor();
/** @private {Control}*/
private control_;
/** @private {boolean} */
private clickExpected_;
/** @private @const {!EventHandler<
* !Control.IeMouseEventSequenceSimulator_>}
*/
private handler_;
/** @private */
private handleMouseDown_;
/** @private */
private handleMouseUp_;
/**
* @param {!EventsEvent} e
* @private
*/
private handleClick_;
}
import { Disposable } from "../disposable/disposable.js";
export {};