Android - An Open Handset Alliance Project

android.view
public interface

android.view.Menu

Interface for managing the items in a menu.

By default, every Android Activity supports a popup menu of actions or options. You can add items to this menu and handle clicks on your additions. Menu items also support check marks.

Nested Classes

Menu.Item	Interface for direct access to a previously created menu item.
Menu.OnClickListener	Interface to find out when a menu item is invoked.
Menu.OnSelectionListener	Interface to find out when the selection state of a menu item changes.

Known Indirect Subclasses

ContextMenu, MenuBuilder, SubMenu, SubMenuBuilder

Summary

Constants

			Value
int	ALTERNATIVE	Category code for menu group and identifier integers that are alternative actions on the data that is currently displayed -- or/add this with your base value.	262144	0x00040000
int	APPEND_TO_GROUP	Flag for addIntentOptions(int, int, ComponentName, Intent[], Intent, int, Menu.Item[]): if set, do not automatically remove any existing menu items in the same group.	1	0x00000001
int	CATEGORY_MASK	This is the part of a menu group or identifier integer that supplies the category of the item.	-65536	0xffff0000
int	CATEGORY_SHIFT	Bit shift of the category portion of the group/identifier integer.	16	0x00000010
int	CONTAINER	Category code for menu group and identifier integers that are part of a container -- or/add this with your base value.	65536	0x00010000
int	FIRST	First value for group and identifier integers, for normal menu items that do not have a category.	1	0x00000001
int	NONE	Value to use for group and identifier integers when you don't care about them.	0	0x00000000
int	PERFORM_NO_CLOSE	Flag for performShortcut(int, KeyEvent, int): if set, do not close the menu after executing the shortcut.	1	0x00000001
int	SECONDARY	Category code for menu group and identifier integers that are user-supplied secondary (infrequently used) options -- or/add this with your base value.	196608	0x00030000
int	SELECTED_ALTERNATIVE	Category code for menu group and identifier integers that are alternative actions on the item that is currently selected -- or/add this with your base value.	327680	0x00050000
int	SYSTEM	Category code for menu group and identifier integers that are provided by the system -- or/add this with your base value.	131072	0x00020000
int	USER_MASK	This is the part of a menu group or identifier integer that the user can provide.	65535	0x0000ffff
int	USER_SHIFT	Bit shift of the user portion of the group/identifier integer.	0	0x00000000

Public Methods

				Item	add(int group, int id, CharSequence title, Runnable callback)
					Add a new item to the menu.
				Item	add(int group, int id, CharSequence title, int iconRes)
					Add a new item to the menu.
				Item	add(int group, int id, int titleRes, int iconRes)
					Add a new item to the menu.
				Item	add(int group, int id, CharSequence title)
					Add a new item to the menu.
				Item	add(int group, int id, int titleRes)
					Variation on add(int, int, CharSequence) that takes a string resource identifier instead of the string itself.
				Item	add(int group, int id, int titleRes, Runnable callback)
					Variation on add(int, int, CharSequence, Runnable) that takes a string resource identifier instead of the string itself.
				int	addIntentOptions(int group, int id, ComponentName caller, Intent[] specifics, Intent intent, int flags, Item[] outSpecificItems)
					Add a group of menu items corresponding to actions that can be performed for a particular Intent.
				SubMenu	addSubMenu(int group, int id, CharSequence title)
					Add a new sub-menu to the menu.
				SubMenu	addSubMenu(int group, int id, CharSequence title, int iconRes)
					Add a new sub-menu to the menu.
				SubMenu	addSubMenu(int group, int id, int titleRes, int iconRes)
					Variation on addSubMenu(int, int, CharSequence) that takes a string resource identifier for the title instead of the string itself and a resource identifier for the icon.
				SubMenu	addSubMenu(int group, int id, int titleRes, Drawable icon)
					Variation on addSubMenu(int, int, CharSequence) that takes a string resource identifier for the title instead of the string itself, and a Drawable for the icon.
				SubMenu	addSubMenu(int group, int id, int titleRes)
					Variation on addSubMenu(int, int, CharSequence) that takes a string resource identifier for the title instead of the string itself.
				SubMenu	addSubMenu(int group, int id, CharSequence title, Drawable icon)
					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.
				int	findGroupIndex(int group)
					Get the index of the first menu item that is in the given group.
				Item	findItem(int id)
					Return the menu item with a particular identifier.
				int	findItemIndex(int id)
					Get the index of a menu item that has the given identifier.
				Item	get(int index)
					Retrieve the menu item object at a particular index.
				boolean	hasShownItems()
					Return whether the menu currently has item items that are being shown.
				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 group)
					Remove all items in the given group.
				void	removeItem(int id)
					Remove the item with the given identifier.
				void	removeItemAt(int index)
					Remove the item at the given index.
				void	setDefaultItem(int id)
					Set the item that is initially selected when the menu is displayed.
				void	setGroupCheckable(int group, boolean checkable, boolean exclusive)
					Control whether a particular group of items can show a check mark.
				void	setGroupShown(int group, boolean shown)
					Show or hide all menu items that are in the given group.
				void	setItemCheckable(int id, boolean checkable)
					Control whether a particular item with the given identifier can display a check mark.
				void	setItemChecked(int id, boolean checked)
					Show or hide the check mark for a particular menu item selected by its identifier.
				void	setItemShown(int id, boolean shown)
					Show or hide a particular menu item selected by its identifier.
				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 ALTERNATIVE

Category code for menu group and identifier integers 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 APPEND_TO_GROUP

Flag for addIntentOptions(int, int, ComponentName, Intent[], Intent, int, Menu.Item[]): if set, do not automatically remove any existing menu items in the same group.

Constant Value: 1 (0x00000001)

public static final int CATEGORY_MASK

This is the part of a menu group or identifier integer that supplies the category of the item.

Constant Value: -65536 (0xffff0000)

public static final int CATEGORY_SHIFT

Bit shift of the category portion of the group/identifier integer.

Constant Value: 16 (0x00000010)

public static final int CONTAINER

Category code for menu group and identifier integers that are part of a container -- or/add this with your base value.

Constant Value: 65536 (0x00010000)

public static final int FIRST

First value for group and identifier integers, for normal menu items that do not have a category.

Constant Value: 1 (0x00000001)

public static final int NONE

Value to use for group and identifier integers when you don't care about them.

Constant Value: 0 (0x00000000)

public static final int 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 SECONDARY

Category code for menu group and identifier integers that are user-supplied secondary (infrequently used) options -- or/add this with your base value.

Constant Value: 196608 (0x00030000)

public static final int SELECTED_ALTERNATIVE

Category code for menu group and identifier integers that are alternative actions on the item that is currently selected -- or/add this with your base value.

Constant Value: 327680 (0x00050000)

public static final int SYSTEM

Category code for menu group and identifier integers that are provided by the system -- or/add this with your base value.

Constant Value: 131072 (0x00020000)

public static final int USER_MASK

This is the part of a menu group or identifier integer that the user can provide.

Constant Value: 65535 (0x0000ffff)

public static final int USER_SHIFT

Bit shift of the user portion of the group/identifier integer.

Constant Value: 0 (0x00000000)

Public Methods

public Item add(int group, int id, CharSequence title, Runnable callback)

Add a new item to the menu. This item displays the given title for its label and will invoke callback when it is selected.

Parameters

group	Item ordering grouping control. The item will be added after all other items whose order is <= this number, and before any that are larger than it. This can also be used to define groups of items for batch state changes. Normally use 0.
id	Unique item ID. Use 0 if you do not need a unique ID.
title	The text to display for the item.
callback	The object to invoke when the item is selected.

Returns

Item The newly added menu item.

public Item add(int group, int id, CharSequence title, int iconRes)

Add a new item to the menu. This item displays the given title for its label. Also displays the given iconRes (which is converted to a Drawable only when needed).

Parameters

group	Item ordering grouping control. The item will be added after all other items whose order is <= this number, and before any that are larger than it. This can also be used to define groups of items for batch state changes. Normally use 0.
id	Unique item ID. Use 0 if you do not need a unique ID.
title	The text to display for the item.
iconRes	The resource ID of the icon for the item.

Returns

Item The newly added menu item.

public Item add(int group, int id, int titleRes, int iconRes)

Add a new item to the menu. This item displays the given titleRes resource for its label. Also displays the given iconRes (which is converted to a Drawable only when needed).

Parameters

group	Item ordering grouping control. The item will be added after all other items whose order is <= this number, and before any that are larger than it. This can also be used to define groups of items for batch state changes. Normally use 0.
id	Unique item ID. Use 0 if you do not need a unique ID.
titleRes	The resource ID of the text to display for the item.
iconRes	The resource ID of the icon for the item.

Returns

Item The newly added menu item.

public Item add(int group, int id, CharSequence title)

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

Parameters

group	Item ordering grouping control. The item will be added after all other items whose order is <= this number, and before any that are larger than it. This can also be used to define groups of items for batch state changes. Normally use 0.
id	Unique item ID. Use 0 if you do not need a unique ID.
title	The text to display for the item.

Returns

Item The newly added menu item.

public Item add(int group, int id, int titleRes)

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

Parameters

group	Item ordering grouping control. The item will be added after all other items whose order is <= this number, and before any that are larger than it. This can also be used to define groups of items for batch state changes. Normally use 0.
id	Unique item ID. Use 0 if you do not need a unique ID.
titleRes	Resource identifier of title string.

Returns

Item The newly added menu item.

public Item add(int group, int id, int titleRes, Runnable callback)

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

Parameters

group	Item ordering grouping control. The item will be added after all other items whose order is <= this number, and before any that are larger than it. This can also be used to define groups of items for batch state changes. Normally use 0.
id	Unique item ID. Use 0 if you do not need a unique ID.
titleRes	Resource identifier of title string.
callback	The object to invoke when the item is selected.

Returns

Item The newly added menu item.

public int addIntentOptions(int group, int id, ComponentName caller, Intent[] specifics, Intent intent, int flags, Item[] 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 ALTERNATIVE_CATEGORY or SELECTED_ALTERNATIVE_CATEGORY 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

group	Item ordering grouping control. The item will be added after all other items whose order is <= this number, and before any that are larger than it. This can also be used to define groups of items for batch state changes. Normally use 0.
id	Unique item ID. Use 0 if you do not need a unique ID.
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 group, int id, CharSequence title)

Add a new sub-menu to the menu. This item displays the given title for its label. The system will call the activity's onCreatePanelMenu(int, Menu) callback method with a SubMenu object and the id you supply here. 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

group	Item ordering grouping control. The item will be added after all other items whose order is <= this number, and before any that are larger than it. This can also be used to define groups of items for batch state changes. Normally use 0.
id	Unique item ID. Use 0 if you do not need a unique ID.
title	The text to display for the item.

Returns

SubMenu The newly added sub-menu

public SubMenu addSubMenu(int group, int id, CharSequence title, int iconRes)

Add a new sub-menu to the menu. This item displays the given title for its label and iconRes as the icon. The system will call the activity's onCreatePanelMenu(int, Menu) callback method with a SubMenu object and the id you supply here. 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

group	Item ordering grouping control. The item will be added after all other items whose order is <= this number, and before any that are larger than it. This can also be used to define groups of items for batch state changes. Normally use 0.
id	Unique item ID. Use 0 if you do not need a unique ID.
title	The text to display for the item.
iconRes	The new icon (as a resource ID) to be displayed.

Returns

SubMenu The newly added sub-menu

public SubMenu addSubMenu(int group, int id, int titleRes, int iconRes)

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

Parameters

group	Item ordering grouping control. The item will be added after all other items whose order is <= this number, and before any that are larger than it. This can also be used to define groups of items for batch state changes. Normally use 0.
id	Unique item ID. Use 0 if you do not need a unique ID.
titleRes	Resource identifier of title string.
iconRes	The new icon (as a resource ID) to be displayed.

Returns

SubMenu The newly added sub-menu

public SubMenu addSubMenu(int group, int id, int titleRes, Drawable icon)

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

Parameters

group	Item ordering grouping control. The item will be added after all other items whose order is <= this number, and before any that are larger than it. This can also be used to define groups of items for batch state changes. Normally use 0.
id	Unique item ID. Use 0 if you do not need a unique ID.
titleRes	Resource identifier of title string.
icon	The new icon (as a Drawable) to be displayed.

Returns

SubMenu The newly added sub-menu

public SubMenu addSubMenu(int group, int id, int titleRes)

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

Parameters

group	Item ordering grouping control. The item will be added after all other items whose order is <= this number, and before any that are larger than it. This can also be used to define groups of items for batch state changes. Normally use 0.
id	Unique item ID. Use 0 if you do not need a unique ID.
titleRes	Resource identifier of title string.

Returns

SubMenu The newly added sub-menu

public SubMenu addSubMenu(int group, int id, CharSequence title, Drawable icon)

Parameters

group	Item ordering grouping control. The item will be added after all other items whose order is <= this number, and before any that are larger than it. This can also be used to define groups of items for batch state changes. Normally use 0.
id	Unique item ID. Use 0 if you do not need a unique ID.
title	The text to display for the item.
icon	The new icon (as a Drawable) to be displayed.

Returns

SubMenu 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 int findGroupIndex(int group)

Get the index of the first menu item that is in the given group. Note that this index can change any time items are added or removed from the menu; you should not keep it around. If you want to hold on to an item for later access, hold on to the Item object.

Parameters

group	The group to find.

Returns

int The index of the group, or -1 if there is no such item.

public Item findItem(int id)

Return the menu item with a particular identifier.

Parameters

id	The identifier to find.

Returns

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

public int findItemIndex(int id)

Get the index of a menu item that has the given identifier. Note that this index can change any time items are added or removed from the menu; you should not keep it around. If you want to hold on to an item for later access, hold on to the Item object.

Parameters

id	The identifier to find.

Returns

int The index of the identifier, or -1 if there is no such item.

public Item get(int index)

Retrieve the menu item object at a particular index. Use with findItemIndex() and size().

Parameters

index	The index of the desired item.

Returns

Item The item object. Always returns non-null; an exception will be thrown if the index does not exist.

public boolean hasShownItems()

Return whether the menu currently has item items that are being shown.

Returns

boolean True if there is one or more item in the shown state; 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

boolean 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

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

public void removeGroup(int group)

Remove all items in the given group.

Parameters

group	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 removeItemAt(int index)

Remove the item at the given index.

Parameters

index	The index of the item to be removed. If this index is invalid an exception is thrown.

public void setDefaultItem(int id)

Set the item that is initially selected when the menu is displayed.

Parameters

id	The identifier of the menu item to select. Supply -1 to cleat the default item.

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 setGroupShown(int group, boolean shown)

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

Parameters

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

public void setItemCheckable(int id, boolean checkable)

Control whether a particular item with the given identifier can display a check mark. This is the same as looking up the Menu.Item and calling setCheckable(boolean) on it.

Parameters

id	The menu item to operate on.
checkable	Set to true to allow a check mark, false to disallow. The default is false.

public void setItemChecked(int id, boolean checked)

Show or hide the check mark for a particular menu item selected by its identifier. If this item is a member of a group that contains mutually-exclusive items (set via setGroupCheckable(int, boolean, boolean), the other items in the group will be unchecked. This is the same as looking up the Menu.Item and calling setChecked(boolean) on it.

Parameters

id	The menu item to operate on.
checked	Set to true to display a check mark, false to hide it. The default value is false.

public void setItemShown(int id, boolean shown)

Show or hide a particular menu item selected by its identifier.

Parameters

id	The menu item to operate on.
shown	If true the item is shown, else it is 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

int The item count.

ContextMenu	Extension of Menu for context menus providing functionality to modify the header of the context menu.
MenuBuilder	Implementation of the Menu interface for creating a standard menu UI.
SubMenu	Subclass of Menu for submenus
SubMenuBuilder	The model for a sub menu, which is an extension of the menu.


e.g. "intent" or "activity"

Android - An Open Handset Alliance Project

Documentation

Goodies

android.view.Menu

Nested Classes

Known Indirect Subclasses

Summary

Constants

Public Methods

Details

Constants

public static final int ALTERNATIVE

public static final int APPEND_TO_GROUP

public static final int CATEGORY_MASK

public static final int CATEGORY_SHIFT

public static final int CONTAINER

public static final int FIRST

public static final int NONE

public static final int PERFORM_NO_CLOSE

public static final int SECONDARY

public static final int SELECTED_ALTERNATIVE

public static final int SYSTEM

public static final int USER_MASK

public static final int USER_SHIFT

Public Methods

public Item add(int group, int id, CharSequence title, Runnable callback)

Parameters

Returns

public Item add(int group, int id, CharSequence title, int iconRes)

Parameters

Returns

public Item add(int group, int id, int titleRes, int iconRes)

Parameters

Returns

public Item add(int group, int id, CharSequence title)

Parameters

Returns

public Item add(int group, int id, int titleRes)

Parameters

Returns

public Item add(int group, int id, int titleRes, Runnable callback)

Parameters

Returns

public int addIntentOptions(int group, int id, ComponentName caller, Intent[] specifics, Intent intent, int flags, Item[] outSpecificItems)

Parameters

Returns

See Also

public SubMenu addSubMenu(int group, int id, CharSequence title)

Parameters

Returns

public SubMenu addSubMenu(int group, int id, CharSequence title, int iconRes)

Parameters

Returns

public SubMenu addSubMenu(int group, int id, int titleRes, int iconRes)

Parameters

Returns

public SubMenu addSubMenu(int group, int id, int titleRes, Drawable icon)

Parameters

Returns

public SubMenu addSubMenu(int group, int id, int titleRes)

Parameters

Returns

public SubMenu addSubMenu(int group, int id, CharSequence title, Drawable icon)

Parameters

Returns

public void clear()

public int findGroupIndex(int group)

Parameters

Returns

public Item findItem(int id)

Parameters

Returns

public int findItemIndex(int id)

Parameters

Returns

public Item get(int index)

Parameters

Returns

public boolean hasShownItems()

Returns