com.google.gwt.user.client.ui

## Class MenuBar

- java.lang.Object
- - com.google.gwt.user.client.ui.UIObject
  - - com.google.gwt.user.client.ui.Widget
    - - com.google.gwt.user.client.ui.MenuBar

All Implemented Interfaces:
  HasAttachHandlers, HasCloseHandlers<PopupPanel>, HasHandlers, EventListener, HasAnimation, HasVisibility, IsWidget, PopupListener

    public class MenuBar
    extends Widget
    implements PopupListener, HasAnimation, HasCloseHandlers<PopupPanel>

A standard menu bar widget. A menu bar can contain any number of menu items, each of which can either fire a `Scheduler.ScheduledCommand` or open a cascaded menu bar.

### CSS Style Rules

.gwt-MenuBar
  the menu bar itself
.gwt-MenuBar-horizontal
  dependent style applied to horizontal menu bars
.gwt-MenuBar-vertical
  dependent style applied to vertical menu bars
.gwt-MenuBar .gwt-MenuItem
  menu items
.gwt-MenuBar .gwt-MenuItem-selected
  selected menu items
.gwt-MenuBar .gwt-MenuItemSeparator
  section breaks between menu items
.gwt-MenuBar .gwt-MenuItemSeparator .menuSeparatorInner
  inner component of section separators
.gwt-MenuBarPopup .menuPopupTopLeft
  the top left cell
.gwt-MenuBarPopup .menuPopupTopLeftInner
  the inner element of the cell
.gwt-MenuBarPopup .menuPopupTopCenter
  the top center cell
.gwt-MenuBarPopup .menuPopupTopCenterInner
  the inner element of the cell
.gwt-MenuBarPopup .menuPopupTopRight
  the top right cell
.gwt-MenuBarPopup .menuPopupTopRightInner
  the inner element of the cell
.gwt-MenuBarPopup .menuPopupMiddleLeft
  the middle left cell
.gwt-MenuBarPopup .menuPopupMiddleLeftInner
  the inner element of the cell
.gwt-MenuBarPopup .menuPopupMiddleCenter
  the middle center cell
.gwt-MenuBarPopup .menuPopupMiddleCenterInner
  the inner element of the cell
.gwt-MenuBarPopup .menuPopupMiddleRight
  the middle right cell
.gwt-MenuBarPopup .menuPopupMiddleRightInner
  the inner element of the cell
.gwt-MenuBarPopup .menuPopupBottomLeft
  the bottom left cell
.gwt-MenuBarPopup .menuPopupBottomLeftInner
  the inner element of the cell
.gwt-MenuBarPopup .menuPopupBottomCenter
  the bottom center cell
.gwt-MenuBarPopup .menuPopupBottomCenterInner
  the inner element of the cell
.gwt-MenuBarPopup .menuPopupBottomRight
  the bottom right cell
.gwt-MenuBarPopup .menuPopupBottomRightInner
  the inner element of the cell

### Example

>     public class MenuBarExample implements EntryPoint {

>       public void onModuleLoad() {
>         // Make a command that we will execute from all leaves.
>         Command cmd = new Command() {
>           public void execute() {
>             Window.alert("You selected a menu item!");
>           }
>         };

>         // Make some sub-menus that we will cascade from the top menu.
>         MenuBar fooMenu = new MenuBar(true);
>         fooMenu.addItem("the", cmd);
>         fooMenu.addItem("foo", cmd);
>         fooMenu.addItem("menu", cmd);

>         MenuBar barMenu = new MenuBar(true);
>         barMenu.addItem("the", cmd);
>         barMenu.addItem("bar", cmd);
>         barMenu.addItem("menu", cmd);

>         MenuBar bazMenu = new MenuBar(true);
>         bazMenu.addItem("the", cmd);
>         bazMenu.addItem("baz", cmd);
>         bazMenu.addItem("menu", cmd);

>         // Make a new menu bar, adding a few cascading menus to it.
>         MenuBar menu = new MenuBar();
>         menu.addItem("foo", fooMenu);
>         menu.addItem("bar", barMenu);
>         menu.addItem("baz", bazMenu);

>         // Add it to the root panel.
>         RootPanel.get().add(menu);
>       }
>     }

### Use in UiBinder Templates

MenuBar elements in UiBinder template files can have a `vertical` boolean attribute (which defaults to false), and may have only MenuItem elements as children. MenuItems may contain HTML and MenuBars.

For example:

     <g:MenuBar>
       <g:MenuItem>Higgledy
         <g:MenuBar vertical="true">
           <g:MenuItem>able</g:MenuItem>
           <g:MenuItem>baker</g:MenuItem>
           <g:MenuItem>charlie</g:MenuItem>
         </g:MenuBar>
       </g:MenuItem>
       <g:MenuItem>Piggledy
         <g:MenuBar vertical="true">
           <g:MenuItem>foo</g:MenuItem>
           <g:MenuItem>bar</g:MenuItem>
           <g:MenuItem>baz</g:MenuItem>
         </g:MenuBar>
       </g:MenuItem>
       <g:MenuItem><b>Pop!</b>
         <g:MenuBar vertical="true">
           <g:MenuItem>uno</g:MenuItem>
           <g:MenuItem>dos</g:MenuItem>
           <g:MenuItem>tres</g:MenuItem>
         </g:MenuBar>
       </g:MenuItem>
     </g:MenuBar>

### Nested Class Summary

Nested Classes
`static interface` `MenuBar.MenuBarImages` Deprecated. replaced by `MenuBar.Resources`
`static interface` `MenuBar.Resources` A ClientBundle that contains the default resources for this widget.

### Nested classes/interfaces inherited from class com.google.gwt.user.client.ui.UIObject

`UIObject.DebugIdImpl, UIObject.DebugIdImplEnabled`

### Field Summary

### Fields inherited from class com.google.gwt.user.client.ui.Widget

`eventsToSink`

### Fields inherited from class com.google.gwt.user.client.ui.UIObject

`DEBUG_ID_PREFIX, MISSING_ELEMENT_ERROR, SETELEMENT_TWICE_ERROR`

### Constructor Summary

Constructors
Constructor and Description
`MenuBar()` Creates an empty horizontal menu bar.
`MenuBar(boolean vertical)` Creates an empty menu bar.
`MenuBar(boolean vertical, MenuBar.MenuBarImages images)` Deprecated. replaced by `MenuBar(boolean, Resources)`
`MenuBar(boolean vertical, MenuBar.Resources resources)` Creates an empty menu bar that uses the specified ClientBundle for menu images.
`MenuBar(MenuBar.MenuBarImages images)` Deprecated. replaced by `MenuBar(Resources)`
`MenuBar(MenuBar.Resources resources)` Creates an empty horizontal menu bar that uses the specified ClientBundle for menu images.

### Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
`HandlerRegistration` `addCloseHandler(CloseHandler<PopupPanel> handler)` Adds a `CloseEvent` handler.
`MenuItem` `addItem(MenuItem item)` Adds a menu item to the bar.
`MenuItem` `addItem(SafeHtml html, MenuBar popup)` Adds a menu item to the bar, that will open the specified menu when it is selected.
`MenuItem` `addItem(SafeHtml html, Scheduler.ScheduledCommand cmd)` Adds a menu item to the bar containing SafeHtml, that will fire the given command when it is selected.
`MenuItem` `addItem(java.lang.String text, boolean asHTML, MenuBar popup)` Adds a menu item to the bar, that will open the specified menu when it is selected.
`MenuItem` `addItem(java.lang.String text, boolean asHTML, Scheduler.ScheduledCommand cmd)` Adds a menu item to the bar, that will fire the given command when it is selected.
`MenuItem` `addItem(java.lang.String text, MenuBar popup)` Adds a menu item to the bar, that will open the specified menu when it is selected.
`MenuItem` `addItem(java.lang.String text, Scheduler.ScheduledCommand cmd)` Adds a menu item to the bar, that will fire the given command when it is selected.
`MenuItemSeparator` `addSeparator()` Adds a thin line to the `MenuBar` to separate sections of `MenuItem`s.
`MenuItemSeparator` `addSeparator(MenuItemSeparator separator)` Adds a thin line to the `MenuBar` to separate sections of `MenuItem`s.
`void` `clearItems()` Removes all menu items from this menu bar.
`void` `closeAllChildren(boolean focus)` Closes this menu and all child menu popups.
`(package private) void` `closeAllParents()`
`(package private) void` `closeAllParentsAndChildren()` Closes all parent and child menu popups.
`(package private) void` `doItemAction(MenuItem item, boolean fireCommand, boolean focus)`
`void` `focus()` Give this MenuBar focus.
`boolean` `getAutoOpen()` Gets whether this menu bar's child menus will open when the mouse is moved over it.
`int` `getItemIndex(MenuItem item)` Get the index of a `MenuItem`.
`protected java.util.List<MenuItem>` `getItems()` Returns a list containing the `MenuItem` objects in the menu bar.
`(package private) PopupPanel` `getPopup()` Visible for testing.
`protected MenuItem` `getSelectedItem()` Returns the `MenuItem` that is currently selected (highlighted) by the user.
`int` `getSeparatorIndex(MenuItemSeparator item)` Get the index of a `MenuItemSeparator`.
`MenuItem` `insertItem(MenuItem item, int beforeIndex)` Adds a menu item to the bar at a specific index.
`MenuItemSeparator` `insertSeparator(int beforeIndex)` Adds a thin line to the `MenuBar` to separate sections of `MenuItem`s at the specified index.
`MenuItemSeparator` `insertSeparator(MenuItemSeparator separator, int beforeIndex)` Adds a thin line to the `MenuBar` to separate sections of `MenuItem`s at the specified index.
`boolean` `isAnimationEnabled()` Returns true if animations are enabled, false if not.
`boolean` `isFocusOnHoverEnabled()` Check whether or not this widget will steal keyboard focus when the mouse hovers over it.
`(package private) void` `itemOver(MenuItem item, boolean focus)`
`void` `moveSelectionDown()` Moves the menu selection down to the next item.
`void` `moveSelectionUp()` Moves the menu selection up to the previous item.
`void` `onBrowserEvent(Event event)` Fired whenever a browser event is received.
`protected void` `onDetach()` This method is called when a widget is detached from the browser's document.
`protected void` `onEnsureDebugId(java.lang.String baseID)` Affected Elements: -item# = the `MenuItem` at the specified index.
`void` `onPopupClosed(PopupPanel sender, boolean autoClosed)` Deprecated. Use `addCloseHandler(CloseHandler)` instead
`void` `removeItem(MenuItem item)` Removes the specified menu item from the bar.
`void` `removeSeparator(MenuItemSeparator separator)` Removes the specified `MenuItemSeparator` from the bar.
`void` `selectItem(MenuItem item)` Select the given MenuItem, which must be a direct child of this MenuBar.
`void` `setAnimationEnabled(boolean enable)` Enable or disable animations.
`void` `setAutoOpen(boolean autoOpen)` Sets whether this menu bar's child menus will open when the mouse is moved over it.
`void` `setFocusOnHoverEnabled(boolean enabled)` Enable or disable auto focus when the mouse hovers over the MenuBar.
`(package private) void` `setMenuItemDebugIds(java.lang.String baseID)` Set the IDs of the menu items.
`(package private) void` `updateSubmenuIcon(MenuItem item)` Show or hide the icon used for items with a submenu.

### Methods inherited from class com.google.gwt.user.client.ui.Widget

`addAttachHandler, addBitlessDomHandler, addDomHandler, addHandler, asWidget, asWidgetOrNull, createHandlerManager, delegateEvent, doAttachChildren, doDetachChildren, ensureHandlers, fireEvent, getHandlerCount, getHandlerManager, getLayoutData, getParent, isAttached, isOrWasAttached, onAttach, onLoad, onUnload, removeFromParent, replaceElement, setLayoutData, setParent, sinkEvents, unsinkEvents`

### Methods inherited from class com.google.gwt.user.client.ui.UIObject

`addStyleDependentName, addStyleName, ensureDebugId, ensureDebugId, ensureDebugId, getAbsoluteLeft, getAbsoluteTop, getElement, getOffsetHeight, getOffsetWidth, getStyleElement, getStyleName, getStyleName, getStylePrimaryName, getStylePrimaryName, getTitle, isVisible, isVisible, removeStyleDependentName, removeStyleName, resolvePotentialElement, setElement, setElement, setHeight, setPixelSize, setSize, setStyleDependentName, setStyleName, setStyleName, setStyleName, setStyleName, setStylePrimaryName, setStylePrimaryName, setTitle, setVisible, setVisible, setWidth, sinkBitlessEvent, toString`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

### Methods inherited from interface com.google.gwt.event.shared.HasHandlers

`fireEvent`

### Constructor Detail

#### MenuBar

    public MenuBar()

Creates an empty horizontal menu bar.

#### MenuBar

    public MenuBar(boolean vertical)

Creates an empty menu bar.

Parameters:
  `vertical` - `true` to orient the menu bar vertically

#### MenuBar

    @Deprecated
    public MenuBar(boolean vertical,
                               MenuBar.MenuBarImages images)

Deprecated. replaced by `MenuBar(boolean, Resources)`
Creates an empty menu bar that uses the specified image bundle for menu images.

Parameters:
  `vertical` - `true` to orient the menu bar vertically
  `images` - a bundle that provides images for this menu

#### MenuBar

    public MenuBar(boolean vertical,
                   MenuBar.Resources resources)

Creates an empty menu bar that uses the specified ClientBundle for menu images.

Parameters:
  `vertical` - `true` to orient the menu bar vertically
  `resources` - a bundle that provides images for this menu

#### MenuBar

    @Deprecated
    public MenuBar(MenuBar.MenuBarImages images)

Deprecated. replaced by `MenuBar(Resources)`
Creates an empty horizontal menu bar that uses the specified image bundle for menu images.

Parameters:
  `images` - a bundle that provides images for this menu

#### MenuBar

    public MenuBar(MenuBar.Resources resources)

Creates an empty horizontal menu bar that uses the specified ClientBundle for menu images.

Parameters:
  `resources` - a bundle that provides images for this menu

### Method Detail

#### addCloseHandler

    public HandlerRegistration addCloseHandler(CloseHandler<PopupPanel> handler)

Description copied from interface: `HasCloseHandlers`
Adds a `CloseEvent` handler.

Specified by:
  `addCloseHandler` in interface `HasCloseHandlers<PopupPanel>`
Parameters:
  `handler` - the handler
Returns:
  the registration for the event

#### addItem

    public MenuItem addItem(MenuItem item)

Adds a menu item to the bar.

Parameters:
  `item` - the item to be added
Returns:
  the `MenuItem` object

#### addItem

    public MenuItem addItem(SafeHtml html,
                            Scheduler.ScheduledCommand cmd)

Adds a menu item to the bar containing SafeHtml, that will fire the given command when it is selected.

Parameters:
  `html` - the item's html text
  `cmd` - the command to be fired
Returns:
  the `MenuItem` object created

#### addItem

    public MenuItem addItem(java.lang.String text,
                            boolean asHTML,
                            Scheduler.ScheduledCommand cmd)

Adds a menu item to the bar, that will fire the given command when it is selected.

Parameters:
  `text` - the item's text
  `asHTML` - `true` to treat the specified text as html
  `cmd` - the command to be fired
Returns:
  the `MenuItem` object created

#### addItem

    public MenuItem addItem(SafeHtml html,
                            MenuBar popup)

Adds a menu item to the bar, that will open the specified menu when it is selected.

Parameters:
  `html` - the item's html text
  `popup` - the menu to be cascaded from it
Returns:
  the `MenuItem` object created

#### addItem

    public MenuItem addItem(java.lang.String text,
                            boolean asHTML,
                            MenuBar popup)

Adds a menu item to the bar, that will open the specified menu when it is selected.

Parameters:
  `text` - the item's text
  `asHTML` - `true` to treat the specified text as html
  `popup` - the menu to be cascaded from it
Returns:
  the `MenuItem` object created

#### addItem

    public MenuItem addItem(java.lang.String text,
                            Scheduler.ScheduledCommand cmd)

Adds a menu item to the bar, that will fire the given command when it is selected.

Parameters:
  `text` - the item's text
  `cmd` - the command to be fired
Returns:
  the `MenuItem` object created

#### addItem

    public MenuItem addItem(java.lang.String text,
                            MenuBar popup)

Adds a menu item to the bar, that will open the specified menu when it is selected.

Parameters:
  `text` - the item's text
  `popup` - the menu to be cascaded from it
Returns:
  the `MenuItem` object created

#### addSeparator

    public MenuItemSeparator addSeparator()

Adds a thin line to the `MenuBar` to separate sections of `MenuItem`s.

Returns:
  the `MenuItemSeparator` object created

#### addSeparator

    public MenuItemSeparator addSeparator(MenuItemSeparator separator)

Adds a thin line to the `MenuBar` to separate sections of `MenuItem`s.

Parameters:
  `separator` - the `MenuItemSeparator` to be added
Returns:
  the `MenuItemSeparator` object

#### clearItems

    public void clearItems()

Removes all menu items from this menu bar.

#### closeAllChildren

    public void closeAllChildren(boolean focus)

Closes this menu and all child menu popups.

Parameters:
  `focus` - true to move focus to the parent

#### focus

    public void focus()

Give this MenuBar focus.

#### getAutoOpen

    public boolean getAutoOpen()

Gets whether this menu bar's child menus will open when the mouse is moved over it.

Returns:
  `true` if child menus will auto-open

#### getItemIndex

    public int getItemIndex(MenuItem item)

Get the index of a `MenuItem`.

Returns:
  the index of the item, or -1 if it is not contained by this MenuBar

#### getSeparatorIndex

    public int getSeparatorIndex(MenuItemSeparator item)

Get the index of a `MenuItemSeparator`.

Returns:
  the index of the separator, or -1 if it is not contained by this MenuBar

#### insertItem

    public MenuItem insertItem(MenuItem item,
                               int beforeIndex)
                        throws java.lang.IndexOutOfBoundsException

Adds a menu item to the bar at a specific index.

Parameters:
  `item` - the item to be inserted
  `beforeIndex` - the index where the item should be inserted
Returns:
  the `MenuItem` object
Throws:
  `java.lang.IndexOutOfBoundsException` - if `beforeIndex` is out of range

#### insertSeparator

    public MenuItemSeparator insertSeparator(int beforeIndex)

Adds a thin line to the `MenuBar` to separate sections of `MenuItem`s at the specified index.

Parameters:
  `beforeIndex` - the index where the separator should be inserted
Returns:
  the `MenuItemSeparator` object
Throws:
  `java.lang.IndexOutOfBoundsException` - if `beforeIndex` is out of range

#### insertSeparator

    public MenuItemSeparator insertSeparator(MenuItemSeparator separator,
                                             int beforeIndex)
                                      throws java.lang.IndexOutOfBoundsException

Adds a thin line to the `MenuBar` to separate sections of `MenuItem`s at the specified index.

Parameters:
  `separator` - the `MenuItemSeparator` to be inserted
  `beforeIndex` - the index where the separator should be inserted
Returns:
  the `MenuItemSeparator` object
Throws:
  `java.lang.IndexOutOfBoundsException` - if `beforeIndex` is out of range

#### isAnimationEnabled

    public boolean isAnimationEnabled()

Description copied from interface: `HasAnimation`
Returns true if animations are enabled, false if not.

Specified by:
  `isAnimationEnabled` in interface `HasAnimation`

#### isFocusOnHoverEnabled

    public boolean isFocusOnHoverEnabled()

Check whether or not this widget will steal keyboard focus when the mouse hovers over it.

Returns:
  true if enabled, false if disabled

#### moveSelectionDown

    public void moveSelectionDown()

Moves the menu selection down to the next item. If there is no selection, selects the first item. If there are no items at all, does nothing.

#### moveSelectionUp

    public void moveSelectionUp()

Moves the menu selection up to the previous item. If there is no selection, selects the first item. If there are no items at all, does nothing.

#### onBrowserEvent

    public void onBrowserEvent(Event event)

Description copied from interface: `EventListener`
Fired whenever a browser event is received.

Specified by:
  `onBrowserEvent` in interface `EventListener`
Overrides:
  `onBrowserEvent` in class `Widget`
Parameters:
  `event` - the event received

#### onPopupClosed

    @Deprecated
    public void onPopupClosed(PopupPanel sender,
                                          boolean autoClosed)

Deprecated. Use `addCloseHandler(CloseHandler)` instead
Closes the menu bar.

Specified by:
  `onPopupClosed` in interface `PopupListener`
Parameters:
  `sender` - popup being closed.
  `autoClosed` - `true` if the popup was automatically closed; `false` if it was closed programmatically.

#### removeItem

    public void removeItem(MenuItem item)

Removes the specified menu item from the bar.

Parameters:
  `item` - the item to be removed

#### removeSeparator

    public void removeSeparator(MenuItemSeparator separator)

Removes the specified `MenuItemSeparator` from the bar.

Parameters:
  `separator` - the separator to be removed

#### selectItem

    public void selectItem(MenuItem item)

Select the given MenuItem, which must be a direct child of this MenuBar.

Parameters:
  `item` - the MenuItem to select, or null to clear selection

#### setAnimationEnabled

    public void setAnimationEnabled(boolean enable)

Description copied from interface: `HasAnimation`
Enable or disable animations.

Specified by:
  `setAnimationEnabled` in interface `HasAnimation`
Parameters:
  `enable` - true to enable, false to disable

#### setAutoOpen

    public void setAutoOpen(boolean autoOpen)

Sets whether this menu bar's child menus will open when the mouse is moved over it.

Parameters:
  `autoOpen` - `true` to cause child menus to auto-open

#### setFocusOnHoverEnabled

    public void setFocusOnHoverEnabled(boolean enabled)

Enable or disable auto focus when the mouse hovers over the MenuBar. This allows the MenuBar to respond to keyboard events without the user having to click on it, but it will steal focus from other elements on the page. Enabled by default.

Parameters:
  `enabled` - true to enable, false to disable

#### getItems

    protected java.util.List<MenuItem> getItems()

Returns a list containing the `MenuItem` objects in the menu bar. If there are no items in the menu bar, then an empty `List` object will be returned.

Returns:
  a list containing the `MenuItem` objects in the menu bar

#### getSelectedItem

    protected MenuItem getSelectedItem()

Returns the `MenuItem` that is currently selected (highlighted) by the user. If none of the items in the menu are currently selected, then `null` will be returned.

Returns:
  the `MenuItem` that is currently selected, or `null` if no items are currently selected

#### onDetach

    protected void onDetach()

Description copied from class: `Widget`

This method is called when a widget is detached from the browser's document. To receive notification before a Widget is removed from the document, override the `Widget.onUnload()` method or use `Widget.addAttachHandler(com.google.gwt.event.logical.shared.AttachEvent.Handler)`.

It is strongly recommended that you override `Widget.onUnload()` or `Widget.doDetachChildren()` instead of this method to avoid inconsistencies between logical and physical attachment states.

Subclasses that override this method must call `super.onDetach()` to ensure that the Widget has been detached from the underlying Element. Failure to do so will result in application memory leaks due to circular references between DOM Elements and JavaScript objects.

Overrides:
  `onDetach` in class `Widget`
See Also:
  `Widget.onUnload()`, `Widget.doDetachChildren()`

#### onEnsureDebugId

    protected void onEnsureDebugId(java.lang.String baseID)

Affected Elements:

- -item# = the `MenuItem` at the specified index.

Overrides:
  `onEnsureDebugId` in class `UIObject`
Parameters:
  `baseID` - the base ID used by the main element
See Also:
  `UIObject.onEnsureDebugId(String)`

#### closeAllParents

    void closeAllParents()

#### closeAllParentsAndChildren

    void closeAllParentsAndChildren()

Closes all parent and child menu popups.

#### doItemAction

    void doItemAction(MenuItem item,
                      boolean fireCommand,
                      boolean focus)

#### getPopup

    PopupPanel getPopup()

Visible for testing.

#### itemOver

    void itemOver(MenuItem item,
                  boolean focus)

#### setMenuItemDebugIds

    void setMenuItemDebugIds(java.lang.String baseID)

Set the IDs of the menu items.

Parameters:
  `baseID` - the base ID

#### updateSubmenuIcon

    void updateSubmenuIcon(MenuItem item)

Show or hide the icon used for items with a submenu.

Parameters:
  `item` - the item with or without a submenu