FileDocCategorySizeDatePackage
Menu.javaAPI DocAndroid 5.1 API17492Thu Mar 12 22:22:10 GMT 2015android.view

Menu

public interface 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 {@link Menu} via {@link MenuInflater}. The easiest way of attaching code to clicks is via {@link Activity#onOptionsItemSelected(MenuItem)} and {@link Activity#onContextItemSelected(MenuItem)}.

Different menu types support different features:

  1. Context menus: Do not support item shortcuts and item icons.
  2. Options menus: The icon menus do not support item check marks and only show the item's {@link MenuItem#setTitleCondensed(CharSequence) 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.

Developer Guides

For more information about creating menus, read the Menus developer guide.

Fields Summary
static final int
USER_MASK
This is the part of an order integer that the user can provide.
static final int
USER_SHIFT
Bit shift of the user portion of the order integer.
static final int
CATEGORY_MASK
This is the part of an order integer that supplies the category of the item.
static final int
CATEGORY_SHIFT
Bit shift of the category portion of the order integer.
static final int
NONE
Value to use for group and item identifier integers when you don't care about them.
static final int
FIRST
First value for group and item identifier integers.
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.
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.
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.
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.
static final int
FLAG_APPEND_TO_GROUP
Flag for {@link #addIntentOptions}: if set, do not automatically remove any existing menu items in the same group.
static final int
FLAG_PERFORM_NO_CLOSE
Flag for {@link #performShortcut}: if set, do not close the menu after executing the shortcut.
static final int
FLAG_ALWAYS_PERFORM_CLOSE
Flag for {@link #performShortcut(int, KeyEvent, int)}: if set, always close the menu after executing the shortcut. Closing the menu also resets the prepared state.
Constructors Summary
Methods Summary
public MenuItemadd(java.lang.CharSequence title)
Add a new item to the menu. This item displays the given title for its label.

param
title The text to display for the item.
return
The newly added menu item.

public MenuItemadd(int titleRes)
Add a new item to the menu. This item displays the given title for its label.

param
titleRes Resource identifier of title string.
return
The newly added menu item.

public MenuItemadd(int groupId, int itemId, int order, java.lang.CharSequence title)
Add a new item to the menu. This item displays the given title for its label.

param
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 {@link #NONE} if an item should not be in a group.
param
itemId Unique item ID. Use {@link #NONE} if you do not need a unique ID.
param
order The order for the item. Use {@link #NONE} if you do not care about the order. See {@link MenuItem#getOrder()}.
param
title The text to display for the item.
return
The newly added menu item.

public MenuItemadd(int groupId, int itemId, int order, int titleRes)
Variation on {@link #add(int, int, int, CharSequence)} that takes a string resource identifier instead of the string itself.

param
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 {@link #NONE} if an item should not be in a group.
param
itemId Unique item ID. Use {@link #NONE} if you do not need a unique ID.
param
order The order for the item. Use {@link #NONE} if you do not care about the order. See {@link MenuItem#getOrder()}.
param
titleRes Resource identifier of title string.
return
The newly added menu item.

public intaddIntentOptions(int groupId, int itemId, int order, android.content.ComponentName caller, android.content.Intent[] specifics, android.content.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 {@link Intent#CATEGORY_ALTERNATIVE} or {@link Intent#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 {@link android.content.pm.PackageManager#queryIntentActivityOptions} 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 {@link MenuItem#setIntent} 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.

param
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 {@link #NONE} if the items should not be in a group.
param
itemId Unique item ID. Use {@link #NONE} if you do not need a unique ID.
param
order The order for the items. Use {@link #NONE} if you do not care about the order. See {@link MenuItem#getOrder()}.
param
caller The current activity component name as defined by queryIntentActivityOptions().
param
specifics Specific items to place first as defined by queryIntentActivityOptions().
param
intent Intent describing the kinds of items to populate in the list as defined by queryIntentActivityOptions().
param
flags Additional options controlling how the items are added.
param
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.
return
The number of menu items that were added.
see
#FLAG_APPEND_TO_GROUP
see
MenuItem#setIntent
see
android.content.pm.PackageManager#queryIntentActivityOptions

public SubMenuaddSubMenu(java.lang.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 {@link SubMenu#getItem()}.

param
title The text to display for the item.
return
The newly added sub-menu

public SubMenuaddSubMenu(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 {@link SubMenu#getItem()}.

param
titleRes Resource identifier of title string.
return
The newly added sub-menu

public SubMenuaddSubMenu(int groupId, int itemId, int order, java.lang.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 {@link SubMenu#getItem()}.

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

param
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 {@link #NONE} if an item should not be in a group.
param
itemId Unique item ID. Use {@link #NONE} if you do not need a unique ID.
param
order The order for the item. Use {@link #NONE} if you do not care about the order. See {@link MenuItem#getOrder()}.
param
title The text to display for the item.
return
The newly added sub-menu

public SubMenuaddSubMenu(int groupId, int itemId, int order, int titleRes)
Variation on {@link #addSubMenu(int, int, int, CharSequence)} that takes a string resource identifier for the title instead of the string itself.

param
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 {@link #NONE} if an item should not be in a group.
param
itemId Unique item ID. Use {@link #NONE} if you do not need a unique ID.
param
order The order for the item. Use {@link #NONE} if you do not care about the order. See {@link MenuItem#getOrder()}.
param
titleRes Resource identifier of title string.
return
The newly added sub-menu

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

public voidclose()
Closes the menu, if open.

public MenuItemfindItem(int id)
Return the menu item with a particular identifier.

param
id The identifier to find.
return
The menu item object, or null if there is no item with this identifier.

public MenuItemgetItem(int index)
Gets the menu item at the given index.

param
index The index of the menu item to return.
return
The menu item.
exception
IndexOutOfBoundsException when {@code index < 0 || >= size()}

public booleanhasVisibleItems()
Return whether the menu currently has item items that are visible.

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

public booleanisShortcutKey(int keyCode, KeyEvent event)
Is a keypress one of the defined shortcut keys for this window.

param
keyCode the key code from {@link KeyEvent} to check.
param
event the {@link KeyEvent} to use to help check.

public booleanperformIdentifierAction(int id, int flags)
Execute the menu item action associated with the given menu identifier.

param
id Identifier associated with the menu item.
param
flags Additional option flags or 0.
return
If the given identifier exists and is shown, returns true; else returns false.
see
#FLAG_PERFORM_NO_CLOSE

public booleanperformShortcut(int keyCode, KeyEvent event, int flags)
Execute the menu item action associated with the given shortcut character.

param
keyCode The keycode of the shortcut key.
param
event Key event message.
param
flags Additional option flags or 0.
return
If the given shortcut exists and is shown, returns true; else returns false.
see
#FLAG_PERFORM_NO_CLOSE

public voidremoveGroup(int groupId)
Remove all items in the given group.

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

public voidremoveItem(int id)
Remove the item with the given identifier.

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

public voidsetGroupCheckable(int group, boolean checkable, boolean exclusive)
Control whether a particular group of items can show a check mark. This is similar to calling {@link MenuItem#setCheckable} 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.

param
group The group of items to operate on.
param
checkable Set to true to allow a check mark, false to disallow. The default is false.
param
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.
see
MenuItem#setCheckable
see
MenuItem#setChecked

public voidsetGroupEnabled(int group, boolean enabled)
Enable or disable all menu items that are in the given group.

param
group The group of items to operate on.
param
enabled If true the items will be enabled, else they will be disabled.
see
MenuItem#setEnabled

public voidsetGroupVisible(int group, boolean visible)
Show or hide all menu items that are in the given group.

param
group The group of items to operate on.
param
visible If true the items are visible, else they are hidden.
see
MenuItem#setVisible

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

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

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

return
The item count.