Android
android.view
public interface

android.view.Menu

android.view.Menu

Interface for managing the items in a menu.

By default, every Activity supports an options menu of actions or options. You can add items to this menu and handle clicks on your additions. The easiest way of adding menu items is inflating an XML file into the Menu via MenuInflater. The easiest way of attaching code to clicks is via onOptionsItemSelected(MenuItem) and onContextItemSelected(MenuItem).

Different menu types support different features:

  1. Context menus: Do not support item shortcuts, item icons, and sub menus.
  2. Options menus: The icon menus do not support item check marks and only show the item's condensed title. The expanded menus (only available if six or more menu items are visible, reached via the 'More' item in the icon menu) do not show item icons, and item check marks are discouraged.
  3. Sub menus: Do not support item icons, or nested sub menus.

Known Indirect Subclasses

Summary

Constants

      Value  
int  CATEGORY_ALTERNATIVE  Category code for the order integer for items/groups that are alternative actions on the data that is currently displayed -- or/add this with your base value.  262144  0x00040000 
int  CATEGORY_CONTAINER  Category code for the order integer for items/groups that are part of a container -- or/add this with your base value.  65536  0x00010000 
int  CATEGORY_SECONDARY  Category code for the order integer for items/groups that are user-supplied secondary (infrequently used) options -- or/add this with your base value.  196608  0x00030000 
int  CATEGORY_SYSTEM  Category code for the order integer for items/groups that are provided by the system -- or/add this with your base value.  131072  0x00020000 
int  FIRST  First value for group and item identifier integers.  0x00000001 
int  FLAG_ALWAYS_PERFORM_CLOSE  Flag for performShortcut(int, KeyEvent, int): if set, always close the menu after executing the shortcut.  0x00000002 
int  FLAG_APPEND_TO_GROUP  Flag for addIntentOptions(int, int, int, ComponentName, Intent[], Intent, int, MenuItem[]): if set, do not automatically remove any existing menu items in the same group.  0x00000001 
int  FLAG_PERFORM_NO_CLOSE  Flag for performShortcut(int, KeyEvent, int): if set, do not close the menu after executing the shortcut.  0x00000001 
int  NONE  Value to use for group and item identifier integers when you don't care about them.  0x00000000 

Public Methods

          MenuItem  add(int titleRes)
Add a new item to the menu.
          MenuItem  add(int groupId, int itemId, int order, CharSequence title)
Add a new item to the menu.
          MenuItem  add(int groupId, int itemId, int order, int titleRes)
Variation on add(int, int, int, CharSequence) that takes a string resource identifier instead of the string itself.
          MenuItem  add(CharSequence title)
Add a new item to the menu.
          int  addIntentOptions(int groupId, int itemId, int order, ComponentName caller, Intent[] specifics, Intent intent, int flags, MenuItem[] outSpecificItems)
Add a group of menu items corresponding to actions that can be performed for a particular Intent.
          SubMenu  addSubMenu(int titleRes)
Add a new sub-menu to the menu.
          SubMenu  addSubMenu(int groupId, int itemId, int order, int titleRes)
Variation on addSubMenu(int, int, int, CharSequence) that takes a string resource identifier for the title instead of the string itself.
          SubMenu  addSubMenu(CharSequence title)
Add a new sub-menu to the menu.
          SubMenu  addSubMenu(int groupId, int itemId, int order, CharSequence title)
Add a new sub-menu to the menu.
          void  clear()
Remove all existing items from the menu, leaving it empty as if it had just been created.
          MenuItem  findItem(int id)
Return the menu item with a particular identifier.
          boolean  hasVisibleItems()
Return whether the menu currently has item items that are visible.
          boolean  isShortcutKey(int keyCode, KeyEvent event)
Is a keypress one of the defined shortcut keys for this window.
          boolean  performIdentifierAction(int id, int flags)
Execute the menu item action associated with the given menu identifier.
          boolean  performShortcut(int keyCode, KeyEvent event, int flags)
Execute the menu item action associated with the given shortcut character.
          void  removeGroup(int groupId)
Remove all items in the given group.
          void  removeItem(int id)
Remove the item with the given identifier.
          void  setGroupCheckable(int group, boolean checkable, boolean exclusive)
Control whether a particular group of items can show a check mark.
          void  setGroupEnabled(int group, boolean enabled)
Enable or disable all menu items that are in the given group.
          void  setGroupVisible(int group, boolean visible)
Show or hide all menu items that are in the given group.
          void  setQwertyMode(boolean isQwerty)
Control whether the menu should be running in qwerty mode (alphabetic shortcuts) or 12-key mode (numeric shortcuts).
          int  size()
Get the number of items in the menu.

Details

Constants

public static final int CATEGORY_ALTERNATIVE

Category code for the order integer for items/groups that are alternative actions on the data that is currently displayed -- or/add this with your base value.
Constant Value: 262144 (0x00040000)

public static final int CATEGORY_CONTAINER

Category code for the order integer for items/groups that are part of a container -- or/add this with your base value.
Constant Value: 65536 (0x00010000)

public static final int CATEGORY_SECONDARY

Category code for the order integer for items/groups that are user-supplied secondary (infrequently used) options -- or/add this with your base value.
Constant Value: 196608 (0x00030000)

public static final int CATEGORY_SYSTEM

Category code for the order integer for items/groups that are provided by the system -- or/add this with your base value.
Constant Value: 131072 (0x00020000)

public static final int FIRST

First value for group and item identifier integers.
Constant Value: 1 (0x00000001)

public static final int FLAG_ALWAYS_PERFORM_CLOSE

Flag for performShortcut(int, KeyEvent, int): if set, always close the menu after executing the shortcut. Closing the menu also resets the prepared state.
Constant Value: 2 (0x00000002)

public static final int FLAG_APPEND_TO_GROUP

Flag for addIntentOptions(int, int, int, ComponentName, Intent[], Intent, int, MenuItem[]): if set, do not automatically remove any existing menu items in the same group.
Constant Value: 1 (0x00000001)

public static final int FLAG_PERFORM_NO_CLOSE

Flag for performShortcut(int, KeyEvent, int): if set, do not close the menu after executing the shortcut.
Constant Value: 1 (0x00000001)

public static final int NONE

Value to use for group and item identifier integers when you don't care about them.
Constant Value: 0 (0x00000000)

Public Methods

public MenuItem add(int titleRes)

Add a new item to the menu. This item displays the given title for its label.

Parameters

titleRes Resource identifier of title string.

Returns

  • The newly added menu item.

public MenuItem add(int groupId, int itemId, int order, CharSequence title)

Add a new item to the menu. This item displays the given title for its label.

Parameters

groupId The group identifier that this item should be part of. This can be used to define groups of items for batch state changes. Normally use NONE if an item should not be in a group.
itemId Unique item ID. Use NONE if you do not need a unique ID.
order The order for the item. Use NONE if you do not care about the order. See getOrder().
title The text to display for the item.

Returns

  • The newly added menu item.

public MenuItem add(int groupId, int itemId, int order, int titleRes)

Variation on add(int, int, int, CharSequence) that takes a string resource identifier instead of the string itself.

Parameters

groupId The group identifier that this item should be part of. This can also be used to define groups of items for batch state changes. Normally use NONE if an item should not be in a group.
itemId Unique item ID. Use NONE if you do not need a unique ID.
order The order for the item. Use NONE if you do not care about the order. See getOrder().
titleRes Resource identifier of title string.

Returns

  • The newly added menu item.

public MenuItem add(CharSequence title)

Add a new item to the menu. This item displays the given title for its label.

Parameters

title The text to display for the item.

Returns

  • The newly added menu item.

public int addIntentOptions(int groupId, int itemId, int order, ComponentName caller, Intent[] specifics, Intent intent, int flags, MenuItem[] outSpecificItems)

Add a group of menu items corresponding to actions that can be performed for a particular Intent. The Intent is most often configured with a null action, the data that the current activity is working with, and includes either the CATEGORY_ALTERNATIVE or CATEGORY_SELECTED_ALTERNATIVE to find activities that have said they would like to be included as optional action. You can, however, use any Intent you want.

See queryIntentActivityOptions(ComponentName, Intent[], Intent, int) for more * details on the caller, specifics, and intent arguments. The list returned by that function is used to populate the resulting menu items.

All of the menu items of possible options for the intent will be added with the given group and id. You can use the group to control ordering of the items in relation to other items in the menu. Normally this function will automatically remove any existing items in the menu in the same group and place a divider above and below the added items; this behavior can be modified with the flags parameter. For each of the generated items setIntent(Intent) is called to associate the appropriate Intent with the item; this means the activity will automatically be started for you without having to do anything else.

Parameters

groupId The group identifier that the items should be part of. This can also be used to define groups of items for batch state changes. Normally use NONE if the items should not be in a group.
itemId Unique item ID. Use NONE if you do not need a unique ID.
order The order for the items. Use NONE if you do not care about the order. See getOrder().
caller The current activity component name as defined by queryIntentActivityOptions().
specifics Specific items to place first as defined by queryIntentActivityOptions().
intent Intent describing the kinds of items to populate in the list as defined by queryIntentActivityOptions().
flags Additional options controlling how the items are added.
outSpecificItems Optional array in which to place the menu items that were generated for each of the specifics that were requested. Entries may be null if no activity was found for that specific action.

Returns

  • The number of menu items that were added.

public SubMenu addSubMenu(int titleRes)

Add a new sub-menu to the menu. This item displays the given title for its label. To modify other attributes on the submenu's menu item, use getItem().

Parameters

titleRes Resource identifier of title string.

Returns

  • The newly added sub-menu

public SubMenu addSubMenu(int groupId, int itemId, int order, int titleRes)

Variation on addSubMenu(int, int, int, CharSequence) that takes a string resource identifier for the title instead of the string itself.

Parameters

groupId The group identifier that this item should be part of. This can also be used to define groups of items for batch state changes. Normally use NONE if an item should not be in a group.
itemId Unique item ID. Use NONE if you do not need a unique ID.
order The order for the item. Use NONE if you do not care about the order. See getOrder().
titleRes Resource identifier of title string.

Returns

  • The newly added sub-menu

public SubMenu addSubMenu(CharSequence title)

Add a new sub-menu to the menu. This item displays the given title for its label. To modify other attributes on the submenu's menu item, use getItem().

Parameters

title The text to display for the item.

Returns

  • The newly added sub-menu

public SubMenu addSubMenu(int groupId, int itemId, int order, CharSequence title)

Add a new sub-menu to the menu. This item displays the given title for its label. To modify other attributes on the submenu's menu item, use getItem().

Note that you can only have one level of sub-menus, i.e. you cannnot add a subMenu to a subMenu: An UnsupportedOperationException will be thrown if you try.

Parameters

groupId The group identifier that this item should be part of. This can also be used to define groups of items for batch state changes. Normally use NONE if an item should not be in a group.
itemId Unique item ID. Use NONE if you do not need a unique ID.
order The order for the item. Use NONE if you do not care about the order. See getOrder().
title The text to display for the item.

Returns

  • The newly added sub-menu

public void clear()

Remove all existing items from the menu, leaving it empty as if it had just been created.

public MenuItem findItem(int id)

Return the menu item with a particular identifier.

Parameters

id The identifier to find.

Returns

  • The menu item object, or null if there is no item with this identifier.

public boolean hasVisibleItems()

Return whether the menu currently has item items that are visible.

Returns

  • True if there is one or more item visible, else false.

public boolean isShortcutKey(int keyCode, KeyEvent event)

Is a keypress one of the defined shortcut keys for this window.

Parameters

keyCode the key code from KeyEvent to check.
event the KeyEvent to use to help check.

public boolean performIdentifierAction(int id, int flags)

Execute the menu item action associated with the given menu identifier.

Parameters

id Identifier associated with the menu item.
flags Additional option flags or 0.

Returns

  • If the given identifier exists and is shown, returns true; else returns false.

public boolean performShortcut(int keyCode, KeyEvent event, int flags)

Execute the menu item action associated with the given shortcut character.

Parameters

keyCode The keycode of the shortcut key.
event Key event message.
flags Additional option flags or 0.

Returns

  • If the given shortcut exists and is shown, returns true; else returns false.

public void removeGroup(int groupId)

Remove all items in the given group.

Parameters

groupId The group to be removed. If there are no items in this group, nothing happens.

public void removeItem(int id)

Remove the item with the given identifier.

Parameters

id The item to be removed. If there is no item with this identifier, nothing happens.

public void setGroupCheckable(int group, boolean checkable, boolean exclusive)

Control whether a particular group of items can show a check mark. This is similar to calling setCheckable(boolean) on all of the menu items with the given group identifier, but in addition you can control whether this group contains a mutually-exclusive set items. This should be called after the items of the group have been added to the menu.

Parameters

group The group of items to operate on.
checkable Set to true to allow a check mark, false to disallow. The default is false.
exclusive If set to true, only one item in this group can be checked at a time; checking an item will automatically uncheck all others in the group. If set to false, each item can be checked independently of the others.

public void setGroupEnabled(int group, boolean enabled)

Enable or disable all menu items that are in the given group.

Parameters

group The group of items to operate on.
enabled If true the items will be enabled, else they will be disabled.

public void setGroupVisible(int group, boolean visible)

Show or hide all menu items that are in the given group.

Parameters

group The group of items to operate on.
visible If true the items are visible, else they are hidden.

public void setQwertyMode(boolean isQwerty)

Control whether the menu should be running in qwerty mode (alphabetic shortcuts) or 12-key mode (numeric shortcuts).

Parameters

isQwerty If true the menu will use alphabetic shortcuts; else it will use numeric shortcuts.

public int size()

Get the number of items in the menu. Note that this will change any times items are added or removed from the menu.

Returns

  • The item count.
Copyright 2007 Google Inc. Build 0.9_r1-98467 - 14 Aug 2008 18:56