Overview  Package   Class  Use  Deprecated  Help 
GWT 2.7.0
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.google.gwt.user.client.ui
Class MenuBar

java.lang.Object
  extended by com.google.gwt.user.client.ui.UIObject
      extended by com.google.gwt.user.client.ui.Widget
          extended by 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
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
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
 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:

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
Overview  Package   Class  Use  Deprecated  Help 
GWT 2.7.0
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD