Home

# Class goog.ui.Control

Base class for UI controls. Extends {@link goog.ui.Component} by adding the following:

- a {@link goog.events.KeyHandler}, to simplify keyboard handling,
- a pluggable renderer framework, to simplify the creation of simple controls without the need to subclass this class,
- the notion of component content, like a text caption or DOM structure displayed in the component (e.g. a button label),
- getter and setter for component content, as well as a getter and setter specifically for caption text (for convenience),
- support for hiding/showing the component,
- fine-grained control over supported states and state transition events, and
- default mouse and keyboard event handling.

This class has sufficient built-in functionality for most simple UI controls. All controls dispatch SHOW, HIDE, ENTER, LEAVE, and ACTION events on show, hide, mouseover, mouseout, and user action, respectively. Additional states are also supported. See closure/demos/control.html for example usage.extends goog.ui.Component

Instance Method Summary
| `addClassName(string className)` Adds the given class name to the list of classes to be applied to the component's root element.
| `canDecorate(?Element element) ⇒ boolean` Returns true if the given element can be decorated by this component. Overrides {@link goog.ui.Component#canDecorate}.
| `createDom()` Creates the control's DOM. Overrides {@link goog.ui.Component#createDom} by delegating DOM manipulation to the control's renderer.
| `decorateInternal(?Element element)` Decorates the given element with this component. Overrides {@link goog.ui.Component#decorateInternal} by delegating DOM manipulation to the control's renderer.
| `disposeInternal()` Disposes of the component. Calls {@code exitDocument}, which is expected to remove event handlers and clean up the component. Propagates the call to the component's children, if any. Removes the component's DOM from the document unless it was decorated.
| `enableClassName(string className, boolean enable)` Adds or removes the given class name to/from the list of classes to be applied to the component's root element.
| `enableMouseEventHandling_(boolean enable)` Enables or disables mouse event handling on the control.
| `enterDocument()` Configures the component after its DOM has been rendered, and sets up event handling. Overrides {@link goog.ui.Component#enterDocument}.
| `exitDocument()` Cleans up the component before its DOM is removed from the document, and removes event handlers. Overrides {@link goog.ui.Component#exitDocument} by making sure that components that are removed from the document aren't focusable (i.e. have no tab index).
| `getCaption() ⇒ string`
| `getContent() ⇒ ?goog.ui.ControlContent` Returns the text caption or DOM structure displayed in the component.
| `getContentElement() ⇒ ?Element` Returns the DOM element into which child components are to be rendered, or null if the control itself hasn't been rendered yet. Overrides {@link goog.ui.Component#getContentElement} by delegating to the renderer.
| `getExtraClassNames() ⇒ ?Array.<string>` Returns any additional class name(s) to be applied to the component's root element, or null if no extra class names are needed.
| `getKeyEventTarget() ⇒ ?Element` Returns the DOM element on which the control is listening for keyboard events (null if none).
| `getKeyHandler() ⇒ ?goog.events.KeyHandler` Returns the keyboard event handler for this component, lazily created the first time this method is called. Considered protected; should only be used within this package and by subclasses.

`getPreferredAriaRole() ⇒ ?goog.dom.a11y.Role`

Returns the control's preferred ARIA role. This can be used by a control to override the role that would be assigned by the renderer. This is useful in cases where a different ARIA role is appropriate for a control because of the context in which it's used. E.g., a {@link goog.ui.MenuButton} added to a {@link goog.ui.Select} should have an ARIA role of LISTBOX and not MENUITEM.

| `getRenderer() ⇒ (goog.ui.ControlRenderer|null|undefined)` Returns the renderer used by this component to render itself or to decorate an existing element.
| `getState() ⇒ number` Returns the component's state as a bit mask of {@link goog.ui.Component.State}s.

`handleBlur(?goog.events.Event e)`

Handles blur events on the component's key event target element. Always deactivates the component. In addition, if the component is focusable, updates its state and styling to indicate that it no longer has keyboard focus. Considered protected; should only be used within this package and by subclasses. Warning: IE dispatches focus and blur events asynchronously!

`handleDblClick(?goog.events.Event e)`

Handles dblclick events. Should only be registered if the user agent is IE. If the component is enabled, performs its associated action by calling {@link performActionInternal}. This is used to allow more performant buttons in IE. In IE, no mousedown event is fired when that mousedown will trigger a dblclick event. Because of this, a user clicking quickly will only cause ACTION events to fire on every other click. This is a workaround to generate ACTION events for every click. Unfortunately, this workaround won't ever trigger the ACTIVE state. This is roughly the same behaviour as if this were a 'button' element with a listener on mouseup. Considered protected; should only be used within this package and by subclasses.

| `handleFocus(?goog.events.Event e)` Handles focus events on the component's key event target element. If the component is focusable, updates its state and styling to indicate that it now has keyboard focus. Considered protected; should only be used within this package and by subclasses. Warning: IE dispatches focus and blur events asynchronously!
| `handleKeyEvent(?goog.events.KeyEvent e) ⇒ boolean` Attempts to handle a keyboard event, if the component is enabled and visible, by calling {@link handleKeyEventInternal}. Considered protected; should only be used within this package and by subclasses.
| `handleKeyEventInternal(?goog.events.KeyEvent e) ⇒ boolean` Attempts to handle a keyboard event; returns true if the event was handled, false otherwise. Considered protected; should only be used within this package and by subclasses.
| `handleMouseDown(?goog.events.Event e)` Handles mousedown events. If the component is enabled, highlights and activates it. If the component isn't configured for keyboard access, prevents it from receiving keyboard focus. Considered protected; should only be used within this package andy by subclasses.
| `handleMouseOut(?goog.events.BrowserEvent e)` Handles mouseout events. Dispatches a LEAVE event; if the event isn't canceled, and the component supports auto-highlighting, deactivates and un-highlights the component. Considered protected; should only be used within this package and by subclasses.
| `handleMouseOver(?goog.events.BrowserEvent e)` Handles mouseover events. Dispatches an ENTER event; if the event isn't canceled, the component is enabled, and it supports auto-highlighting, highlights the component. Considered protected; should only be used within this package and by subclasses.
| `handleMouseUp(?goog.events.Event e)` Handles mouseup events. If the component is enabled, highlights it. If the component has previously been activated, performs its associated action by calling {@link performActionInternal}, then deactivates it. Considered protected; should only be used within this package and by subclasses.
| `hasState(?goog.ui.Component.State state) ⇒ boolean` Returns true if the component is in the specified state, false otherwise.
| `isActive() ⇒ boolean` Returns true if the component is active (pressed), false otherwise.
| `isAllowTextSelection() ⇒ boolean` Returns true if the control allows text selection within its DOM, false otherwise. Controls that disallow text selection have the appropriate unselectable styling applied to their elements. Note that controls hosted in containers will report that they allow text selection even if their container disallows text selection.
| `isAutoState(?goog.ui.Component.State state) ⇒ boolean` Returns true if the component provides default event handling for the state, false otherwise.
| `isChecked() ⇒ boolean` Returns true if the component is checked, false otherwise.
| `isDispatchTransitionEvents(?goog.ui.Component.State state) ⇒ boolean` Returns true if the component is set to dispatch transition events for the given state, false otherwise.
| `isEnabled() ⇒ boolean` Returns true if the component is enabled, false otherwise.
| `isFocused() ⇒ boolean` Returns true if the component is styled to indicate that it has keyboard focus, false otherwise. Note that {@code isFocused()} returning true doesn't guarantee that the component's key event target has keyborad focus, only that it is styled as such.
| `isHandleMouseEvents() ⇒ boolean` Returns true if the control is configured to handle its own mouse events, false otherwise. Controls not hosted in {@link goog.ui.Container}s have to handle their own mouse events, but controls hosted in containers may allow their parent to handle mouse events on their behalf. Considered protected; should only be used within this package and by subclasses.
| `isHighlighted() ⇒ boolean` Returns true if the component is currently highlighted, false otherwise.
| `isOpen() ⇒ boolean` Returns true if the component is open (expanded), false otherwise.
| `isParentDisabled_() ⇒ boolean` Returns true if the control has a parent that is itself disabled, false otherwise.
| `isSelected() ⇒ boolean` Returns true if the component is selected, false otherwise.
| `isSupportedState(?goog.ui.Component.State state) ⇒ boolean` Returns true if the component supports the specified state, false otherwise.

`isTransitionAllowed(?goog.ui.Component.State state, boolean enable) ⇒ boolean`

Returns true if the transition into or out of the given state is allowed to proceed, false otherwise. A state transition is allowed under the following conditions:

- the component supports the state,
- the component isn't already in the target state,
- either the component is configured not to dispatch events for this state transition, or a transition event was dispatched and wasn't canceled by any event listener, and
- the component hasn't been disposed of

Considered protected; should only be used within this package and by subclasses.

| `isVisible() ⇒ boolean` Returns true if the component's visibility is set to visible, false if it is set to hidden. A component that is set to hidden is guaranteed to be hidden from the user, but the reverse isn't necessarily true. A component may be set to visible but can otherwise be obscured by another element, rendered off-screen, or hidden using direct CSS manipulation.
| `performActionInternal(?goog.events.Event e) ⇒ boolean` Performs the appropriate action when the control is activated by the user. The default implementation first updates the checked and selected state of controls that support them, then dispatches an ACTION event. Considered protected; should only be used within this package and by subclasses.
| `removeClassName(string className)` Removes the given class name from the list of classes to be applied to the component's root element.
| `setActive(boolean active)` Activates or deactivates the component. Does nothing if this state transition is disallowed.
| `setAllowTextSelection(boolean allow)` Allows or disallows text selection within the control's DOM.
| `setAutoStates(number states, boolean enable)` Enables or disables automatic event handling for the given state(s).
| `setCaption(string caption)` Sets the text caption of the component.
| `setChecked(boolean check)` Checks or unchecks the component. Does nothing if this state transition is disallowed.
| `setContent(?goog.ui.ControlContent content)` Sets the component's content to the given text caption, element, or array of nodes. (If the argument is an array of nodes, it must be an actual array, not an array-like object.)
| `setContentInternal(?goog.ui.ControlContent content)` Sets the component's content to the given text caption, element, or array of nodes. Unlike {@link #setContent}, doesn't modify the component's DOM. Called by renderers during element decoration. Considered protected; should only be used within this package and by subclasses.
| `setDispatchTransitionEvents(number states, boolean enable)` Enables or disables transition events for the given state(s). Controls handle state transitions internally by default, and only dispatch state transition events if explicitly requested to do so by calling this method.

`setEnabled(boolean enable)`

Enables or disables the component. Does nothing if this state transition is disallowed. If the component is both visible and focusable, updates its focused state and tab index as needed. If the component is being disabled, ensures that it is also deactivated and un-highlighted first. Note that the component's enabled/disabled state is "locked" as long as it is hosted in a {@link goog.ui.Container} that is itself disabled; this is to prevent clients from accidentally re-enabling a control that is in a disabled container.

`setFocused(boolean focused)`

Applies or removes styling indicating that the component has keyboard focus. Note that unlike the other "set" methods, this method is called as a result of the component's element having received or lost keyboard focus, not the other way around, so calling {@code setFocused(true)} doesn't guarantee that the component's key event target has keyboard focus, only that it is styled as such.

| `setHandleMouseEvents(boolean enable)` Enables or disables mouse event handling for the control. Containers may use this method to disable mouse event handling in their child controls. Considered protected; should only be used within this package and by subclasses.
| `setHighlighted(boolean highlight)` Highlights or unhighlights the component. Does nothing if this state transition is disallowed.
| `setOpen(boolean open)` Opens (expands) or closes (collapses) the component. Does nothing if this state transition is disallowed.

`setPreferredAriaRole(?goog.dom.a11y.Role role)`

Sets the control's preferred ARIA role. This can be used to override the role that would be assigned by the renderer. This is useful in cases where a different ARIA role is appropriate for a control because of the context in which it's used. E.g., a {@link goog.ui.MenuButton} added to a {@link goog.ui.Select} should have an ARIA role of LISTBOX and not MENUITEM.

| `setRenderer(?goog.ui.ControlRenderer renderer)` Registers the given renderer with the component. Changing renderers after the component has entered the document is an error.
| `setRightToLeft(boolean rightToLeft)` Set is right-to-left. This function should be used if the component needs to know the rendering direction during dom creation (i.e. before {@link #enterDocument} is called and is right-to-left is set).
| `setSelected(boolean select)` Selects or unselects the component. Does nothing if this state transition is disallowed.
| `setState(?goog.ui.Component.State state, boolean enable)` Sets or clears the given state on the component, and updates its styling accordingly. Does nothing if the component is already in the correct state or if it doesn't support the specified state. Doesn't dispatch any state transition events; use advisedly.
| `setStateInternal(number state)` Sets the component's state to the state represented by a bit mask of {@link goog.ui.Component.State}s. Unlike {@link #setState}, doesn't update the component's styling, and doesn't reject unsupported states. Called by renderers during element decoration. Considered protected; should only be used within this package and by subclasses.
| `setSupportedState(?goog.ui.Component.State state, boolean support)` Enables or disables support for the given state. Disabling support for a state while the component is in that state is an error.

`setVisible(boolean visible, boolean= opt_force) ⇒ boolean`

Shows or hides the component. Does nothing if the component already has the requested visibility. Otherwise, dispatches a SHOW or HIDE event as appropriate, giving listeners a chance to prevent the visibility change. When showing a component that is both enabled and focusable, ensures that its key target has a tab index. When hiding a component that is enabled and focusable, blurs its key target and removes its tab index.

Static Method Summary
| `isMouseEventWithinElement_(?goog.events.BrowserEvent e, ?Element elem) ⇒ boolean` Checks if a mouse event (mouseover or mouseout) occured below an element.