Home

# Class goog.ui.Palette

A palette is a grid of DOM nodes that the user can highlight or select via the keyboard or the mouse. The selection state of the palette is controlled an ACTION event. Event listeners may retrieve the selected item using the {@link #getSelectedItem} or {@link #getSelectedIndex} method. Use this class as the base for components like color palettes or emoticon pickers. Use {@link #setContent} to set/change the items in the palette after construction. See palette.html demo for example usage.

extends goog.ui.Control

Instance Method Summary
| `adjustSize_()` Calculates and updates the size of the palette based on any preset values and the number of palette items. If there is no preset size, sets the palette size to the smallest square big enough to contain all items. If there is a preset number of columns, increases the number of rows to hold all items if needed. (If there are too many rows, does nothing.)
| `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.
| `getCaption() ⇒ null` Overrides {@link goog.ui.Control#getCaption} to return null, since palettes don't have text captions.
| `getHighlightedIndex() ⇒ number` Returns the 0-based index of the currently highlighted palette item, or -1 if no item is highlighted.
| `getHighlightedItem() ⇒ ?Node` Returns the currently highlighted palette item, or null if no item is highlighted.
| `getSelectedIndex() ⇒ number` Returns the 0-based index of the currently selected palette item, or -1 if no item is selected.
| `getSelectedItem() ⇒ ?Node` Returns the currently selected palette item, or null if no item is selected.
| `getSize() ⇒ ?goog.math.Size` Returns the size of the palette grid.

`handleKeyEvent(?goog.events.KeyEvent e) ⇒ boolean`

Handles keyboard events dispatched while the palette has focus. Moves the highlight on arrow keys, and selects the highlighted item on Enter or Space. Returns true if the event was handled, false otherwise. In particular, if the user attempts to navigate out of the grid, the highlight isn't changed, and this method returns false; it is then up to the parent component to handle the event (e.g. by wrapping the highlight around). Overrides {@link goog.ui.Control#handleKeyEvent}.

| `handleMouseDown(?goog.events.Event e)` Handles mousedown events. Overrides {@link goog.ui.Control#handleMouseDown} by ensuring that the item on which the user moused down is highlighted.
| `handleMouseOut(?goog.events.BrowserEvent e)` Handles mouseout events. Overrides {@link goog.ui.Control#handleMouseOut} by determining the palette item that the mouse just left (if any), and making sure it is un-highlighted.
| `handleMouseOver(?goog.events.BrowserEvent e)` Handles mouseover events. Overrides {@link goog.ui.Control#handleMouseOver} by determining which palette item (if any) was moused over, highlighting it, and un-highlighting any previously-highlighted item.
| `handleSelectionChange(?goog.events.Event e)` Handles selection change events dispatched by the selection model.
| `highlightIndex_(number index, boolean highlight)` Private helper; highlights or un-highlights the item at the given index based on the value of the Boolean argument. This implementation simply applies highlight styling to the cell containing the item to be highighted. Does nothing if the palette hasn't been rendered yet.
| `performActionInternal(?goog.events.Event e) ⇒ boolean` Selects the currently highlighted palette item (triggered by mouseup or by keyboard action). Overrides {@link goog.ui.Control#performActionInternal} by selecting the highlighted item and dispatching an ACTION event.
| `selectItem_(?Node item, boolean select)` Private helper; selects or deselects the given item based on the value of the Boolean argument. This implementation simply applies selection styling to the cell containing the item to be selected. Does nothing if the palette hasn't been rendered yet.
| `setCaption(string caption)` Overrides {@link goog.ui.Control#setCaption} to be a no-op, since palettes don't have text captions.
| `setContentInternal(?Array items)` Overrides {@link goog.ui.Control#setContentInternal} by also updating the grid size and the selection model. Considered protected.
| `setHighlightedIndex(number index)` Highlights the item at the given 0-based index, or removes the highlight if the argument is -1 or out of range. Any previously-highlighted item will be un-highlighted.
| `setHighlightedItem(?Node item)` Highlights the given item, or removes the highlight if the argument is null or invalid. Any previously-highlighted item will be un-highlighted.
| `setSelectedIndex(number index)` Selects the item at the given 0-based index, or clears the selection if the argument is -1 or out of range. Any previously-selected item will be deselected.
| `setSelectedItem(?Node item)` Selects the given item, or clears the selection if the argument is null or invalid. Any previously-selected item will be deselected.

`setSize((goog.math.Size|null|number) size, number= opt_rows)`

Sets the size of the palette grid to the given size. Callers can either pass a single {@link goog.math.Size} or a pair of numbers (first the number of columns, then the number of rows) to this method. In both cases, the number of rows is optional and will be calculated automatically if needed. It is an error to attempt to change the size of the palette after it has been rendered.