Home

# Class goog.ui.MenuButton

A menu button control. Extends {@link goog.ui.Button} by composing a button with a dropdown arrow and a popup menu.

extends goog.ui.Button

Instance Method Summary
| `addItem((goog.ui.Control|goog.ui.MenuItem|goog.ui.MenuSeparator|null) item)` Adds a new menu item at the end of the menu.
| `addItemAt((goog.ui.MenuItem|goog.ui.MenuSeparator|null) item, number index)` Adds a new menu item at the specific index in the menu.
| `attachMenuEventListeners_(?goog.ui.Menu menu, boolean attach)` Attaches or detaches menu event listeners to/from the given menu. Called each time a menu is attached to or detached from the button.
| `attachPopupListeners_(boolean attach)` Attaches or detaches event listeners depending on whether the popup menu is being shown or hidden. Starts listening for document mousedown events and for menu blur events when the menu is shown, and stops listening for these events when it is hidden. Called from {@link #setOpen}.
| `containsElement(?Element element) ⇒ boolean` Returns true if the given element is to be considered part of the component, even if it isn't a DOM descendant of the component's root element.
| `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.
| `enterDocument()` Sets up event handlers specific to menu buttons.
| `exitDocument()` Removes event handlers specific to menu buttons, and ensures that the attached menu also exits the document.
| `getItemAt(number index) ⇒ ?goog.ui.MenuItem` Returns the menu item at a given index.
| `getItemCount() ⇒ number` Returns the number of items in the menu (including separators).
| `getMenu() ⇒ ?goog.ui.Menu` Returns the menu attached to the button. If no menu is attached, creates a new empty menu.
| `handleBlur(?goog.events.Event e)` Handles blur events dispatched by the button's key event target when it loses keyboard focus by closing the popup menu (unless it is focusable). Only registered if the button is focusable.
| `handleDocumentMouseDown(?goog.events.BrowserEvent e)` Handles mousedown events over the document. If the mousedown happens over an element unrelated to the component, hides the menu. TODO(attila): Reconcile this with goog.ui.Popup (and handle frames/windows).
| `handleHighlightItem(?goog.events.Event e)` Handles {@code HIGHLIGHT} events dispatched by the attached menu.
| `handleKeyEventInternal(?goog.events.KeyEvent e) ⇒ boolean` Attempts to handle a keyboard event; returns true if the event was handled, false otherwise. If the button is enabled and the Enter/Space key was pressed, handles the event by dispatching an {@code ACTION} event, and returns true. Overrides {@link goog.ui.Control#handleKeyEventInternal}.
| `handleMenuAction(?goog.events.Event e)` Handles {@code ACTION} events dispatched by an activated menu item.
| `handleMenuBlur(?goog.events.Event e)` Handles {@code BLUR} events dispatched by the popup menu by closing it. Only registered if the menu is focusable.
| `handleMouseDown(?goog.events.Event e)` Handles mousedown events. Invokes the superclass implementation to dispatch an ACTIVATE event and activate the button. Also toggles the visibility of the attached menu.
| `handleMouseUp(?goog.events.Event e)` Handles mouseup events. Invokes the superclass implementation to dispatch an ACTION event and deactivate the button.
| `handleUnHighlightItem(?goog.events.Event e)` Handles UNHIGHLIGHT events dispatched by the associated menu.
| `hideMenu()` Hides the menu and cleans up menu-specific event handling.
| `isAlignMenuToStart() ⇒ boolean`
| `isFocusablePopupMenu() ⇒ boolean`
| `isScrollOnOverflow() ⇒ boolean`
| `onTick_(?goog.events.Event e)` Periodically repositions the menu while it is visible.
| `performActionInternal(?goog.events.Event e) ⇒ boolean` Performs the appropriate action when the menu button is activated by the user. Overrides the superclass implementation by not dispatching an {@code ACTION} event, because menu buttons exist only to reveal menus, not to perform actions themselves. Calls {@link #setActive} to deactivate the button.
| `positionMenu()` Positions the menu under the button. May be called directly in cases when the menu size is known to change.
| `removeItem((goog.ui.MenuItem|goog.ui.MenuSeparator|null) item)` Removes the item from the menu and disposes of it.
| `removeItemAt(number index)` Removes the menu item at a given index in the menu and disposes of it.
| `setAlignMenuToStart(boolean alignToStart)` Sets whether the menu is aligned to the start or the end of the button.
| `setEnabled(boolean enable)` Enables/disables the menu button based on the value of the argument, and updates its CSS styling. Also hides the popup menu if the button is being disabled.
| `setFocusablePopupMenu(boolean focusable)` Sets whether the attached popup menu is focusable. If the popup menu is focusable, it may steal keyboard focus from the menu button, so the button will not hide the menu on blur.
| `setMenu(?goog.ui.Menu menu) ⇒ (goog.ui.Menu|null|undefined)` Replaces the menu attached to the button with the argument, and returns the previous menu (if any).
| `setMenuMargin(?goog.math.Box margin)` Sets a margin that will be applied to the menu's position when it is shown. If null, no margin will be applied.
| `setMenuPosition(?goog.positioning.AnchoredPosition position)` Specify explicitly which corner of the button to use, which will override the value from setAlignMenuToStart() and setScrollOnOverflow().
| `setOpen(boolean open)` Opens or closes the attached popup menu.
| `setPositionElement(?Element positionElement)` Sets an element for anchoring the menu.

`setRenderMenuAsSibling(boolean renderMenuAsSibling)`

Sets whether to render the menu as a sibling element of the button. Normally, the menu is a child of document.body. This option is useful if you need the menu to inherit styles from a common parent element, or if you otherwise need it to share a parent element for desired event handling. One example of the latter is if the parent is in a goog.ui.Popup, to ensure that clicks on the menu are considered being within the popup.

| `setScrollOnOverflow(boolean scrollOnOverflow)` Sets whether the menu should scroll when it's too big to fix vertically on the screen. The css of the menu element should have overflow set to auto. Note: Adding or removing items while the menu is open will not work correctly if scrollOnOverflow is on.
| `setVisible(boolean visible, boolean= opt_force) ⇒ boolean` Shows/hides the menu button based on the value of the argument. Also hides the popup menu if the button is being hidden.
| `showMenu()` Reveals the menu and hooks up menu-specific event handling.