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

Modifier and Type	Class and Description
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

Modifier and Type	Method and Description
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 MenuItems.
MenuItemSeparator	addSeparator(MenuItemSeparator separator) Adds a thin line to the MenuBar to separate sections of MenuItems.
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 MenuItems at the specified index.
MenuItemSeparator	insertSeparator(MenuItemSeparator separator, int beforeIndex) Adds a thin line to the MenuBar to separate sections of MenuItems 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 MenuItems.

Returns:

the MenuItemSeparator object created

addSeparator

public MenuItemSeparator addSeparator(MenuItemSeparator separator)

Adds a thin line to the MenuBar to separate sections of MenuItems.

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 MenuItems 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 MenuItems 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