Home

# Class goog.ui.Container

Base class for containers. 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 containers without the need to subclass this class,
- methods to manage child controls hosted in the container,
- default mouse and keyboard event handling methods.

extends goog.ui.Component

Instance Method Summary
| `addChild(?goog.ui.Control child, boolean= opt_render)` Adds the specified control as the last child of this container. See {@link goog.ui.Container#addChildAt} for detailed semantics.
| `addChildAt(?goog.ui.Control control, number index, boolean= opt_render)` Adds the control as a child of this container at the given 0-based index. Overrides {@link goog.ui.Component#addChildAt} by also updating the container's highlight index. Since {@link goog.ui.Component#addChild} uses {@link #addChildAt} internally, we only need to override this method.
| `canDecorate(?Element element) ⇒ boolean` Returns true if the given element can be decorated by this container. Overrides {@link goog.ui.Component#canDecorate}.
| `canHighlightItem(?goog.ui.Control item) ⇒ boolean` Returns whether the given item can be highlighted.
| `createDom()` Creates the container's DOM. Overrides {@link goog.ui.Component#createDom}.
| `decorateInternal(?Element element)` Decorates the given element with this container. Overrides {@link goog.ui.Component#decorateInternal}. Considered protected.
| `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.
| `enableFocusHandling_(boolean enable)` Sets up listening for events applicable to focusable containers.
| `enterDocument()` Configures the container after its DOM has been rendered, and sets up event handling. Overrides {@link goog.ui.Component#enterDocument}.
| `exitDocument()` Cleans up the container before its DOM is removed from the document, and removes event handlers. Overrides {@link goog.ui.Component#exitDocument}.
| `getContentElement() ⇒ ?Element` Returns the DOM element into which child components are to be rendered, or null if the container itself hasn't been rendered yet. Overrides {@link goog.ui.Component#getContentElement} by delegating to the renderer.
| `getHighlighted() ⇒ ?goog.ui.Control` Returns the currently highlighted item (if any).
| `getHighlightedIndex() ⇒ number` Returns the index of the currently highlighted item (-1 if none).
| `getKeyEventTarget() ⇒ ?Element` Returns the DOM element on which the container is listening for keyboard events (null if none).
| `getKeyHandler() ⇒ ?goog.events.KeyHandler` Returns the keyboard event handler for this container, lazily created the first time this method is called. The keyboard event handler listens for keyboard events on the container's key event target, as determined by its renderer.
| `getOpenItem() ⇒ ?goog.ui.Control` Returns the currently open (expanded) control in the container (null if none).
| `getOrientation() ⇒ ?goog.ui.Container.Orientation` Returns the container's orientation.
| `getOwnerControl(?Node node) ⇒ ?goog.ui.Control` Returns the child control that owns the given DOM node, or null if no such control is found.
| `getRenderer() ⇒ ?goog.ui.ContainerRenderer` Returns the renderer used by this container to render itself or to decorate an existing element.
| `handleBlur(?goog.events.BrowserEvent e)` Handles blur events raised when the container's key event target loses keyboard focus. The default implementation clears the highlight index.
| `handleChildMouseEvents(?goog.events.BrowserEvent e)` Handles mouse events originating from nodes belonging to the controls hosted in the container. Locates the child control based on the DOM node that dispatched the event, and forwards the event to the control for handling.
| `handleCloseItem(?goog.events.Event e)` Handles CLOSE events dispatched by items in the container when they are closed.
| `handleDocumentMouseUp(?goog.events.BrowserEvent e)` Handles mouseup events over the document. The default implementation clears the "mouse button pressed" flag.
| `handleEnterItem(?goog.events.Event e) ⇒ boolean` Handles ENTER events raised by child controls when they are navigated to.
| `handleFocus(?goog.events.BrowserEvent e)` Handles focus events raised when the container's key event target receives keyboard focus.
| `handleHighlightItem(?goog.events.Event e)` Handles HIGHLIGHT events dispatched by items in the container when they are highlighted.
| `handleKeyEvent(?goog.events.KeyEvent e) ⇒ boolean` Attempts to handle a keyboard event, if the control is enabled, 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. If the container is enabled, and a child is highlighted, calls the child control's {@code handleKeyEvent} method to give the control a chance to handle the event first.
| `handleMouseDown(?goog.events.BrowserEvent e)` Handles mousedown events over the container. The default implementation sets the "mouse button pressed" flag and, if the container is focusable, grabs keyboard focus.
| `handleOpenItem(?goog.events.Event e)` Handles OPEN events dispatched by items in the container when they are opened.
| `handleUnHighlightItem(?goog.events.Event e)` Handles UNHIGHLIGHT events dispatched by items in the container when they are unhighlighted.
| `highlightFirst()` Highlights the first highlightable item in the container
| `highlightHelper(function (number, number): number fn, number startIndex) ⇒ boolean` Helper function that manages the details of moving the highlight among child controls in response to keyboard events.
| `highlightLast()` Highlights the last highlightable item in the container.
| `highlightNext()` Highlights the next highlightable item (or the first if nothing is currently highlighted).
| `highlightPrevious()` Highlights the previous highlightable item (or the last if nothing is currently highlighted).
| `isEnabled() ⇒ boolean` Returns true if the container is enabled, false otherwise.
| `isFocusable() ⇒ boolean` Returns true if the container is focusable, false otherwise. The default is true. Focusable containers always have a tab index and allocate a key handler to handle keyboard events while focused.
| `isFocusableChildrenAllowed() ⇒ boolean` Returns true if the container allows children to be focusable, false otherwise. Only effective if the container is not focusable.
| `isMouseButtonPressed() ⇒ boolean` Returns true if the mouse button is pressed, false otherwise.
| `isOpenFollowsHighlight() ⇒ boolean`
| `isVisible() ⇒ boolean` Returns true if the container's visibility is set to visible, false if it is set to hidden. A container that is set to hidden is guaranteed to be hidden from the user, but the reverse isn't necessarily true. A container may be set to visible but can otherwise be obscured by another element, rendered off-screen, or hidden using direct CSS manipulation.
| `registerChildId_(?goog.ui.Control child)` Creates a DOM ID for the child control and registers it to an internal hash table to be able to find it fast by id.
| `removeChild((goog.ui.Control|null|string) control, boolean= opt_unrender) ⇒ ?goog.ui.Control` Removes a child control. Overrides {@link goog.ui.Component#removeChild} by updating the highlight index. Since {@link goog.ui.Component#removeChildAt} uses {@link #removeChild} internally, we only need to override this method.
| `setEnabled(boolean enable)` Enables/disables the container based on the {@code enable} argument. Dispatches an {@code ENABLED} or {@code DISABLED} event prior to changing the container's state, which may be caught and canceled to prevent the container from changing state. Also enables/disables child controls.
| `setFocusable(boolean focusable)` Sets whether the container is focusable. The default is true. Focusable containers always have a tab index and allocate a key handler to handle keyboard events while focused.
| `setFocusableChildrenAllowed(boolean focusable)` Sets whether the container allows children to be focusable, false otherwise. Only effective if the container is not focusable.
| `setHighlighted(?goog.ui.Control item)` Highlights the given item if it exists and is a child of the container; otherwise un-highlights the currently highlighted item.
| `setHighlightedIndex(number index)` Highlights the item at the given 0-based index (if any). If another item was previously highlighted, it is un-highlighted.
| `setHighlightedIndexFromKeyEvent(number index)` Helper method that sets the highlighted index to the given index in response to a keyboard event. The base class implementation simply calls the {@link #setHighlightedIndex} method, but subclasses can override this behavior as needed.
| `setKeyEventTarget((Element|null|undefined) element)` Attaches an element on which to listen for key events.
| `setMouseButtonPressed(boolean pressed)` Sets or clears the "mouse button pressed" flag.
| `setOpenFollowsHighlight(boolean follow)` Sets whether highlighting a child component should also open it.
| `setOrientation(?goog.ui.Container.Orientation orientation)` Sets the container's orientation.
| `setRenderer(?goog.ui.ContainerRenderer renderer)` Registers the given renderer with the container. Changing renderers after the container has already been rendered or decorated is an error.
| `setVisible(boolean visible, boolean= opt_force) ⇒ boolean` Shows or hides the container. Does nothing if the container already has the requested visibility. Otherwise, dispatches a SHOW or HIDE event as appropriate, giving listeners a chance to prevent the visibility change.