Added in API level 1

Menu

---

Kotlin |Java

interface Menu

android.view.Menu

Known Direct Subclasses ContextMenu, SubMenu ContextMenu Extension of Menu for context menus providing functionality to modify the header of the context menu. SubMenu Subclass of Menu for sub menus.

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 Activity.onOptionsItemSelected(MenuItem) and 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 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.

Summary

Constants
static 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 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 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 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 Int	FIRST First value for group and item identifier integers.
static Int	FLAG_ALWAYS_PERFORM_CLOSE Flag for performShortcut(int,android.view.KeyEvent,int): if set, always close the menu after executing the shortcut.
static Int	FLAG_APPEND_TO_GROUP Flag for addIntentOptions: if set, do not automatically remove any existing menu items in the same group.
static Int	FLAG_PERFORM_NO_CLOSE Flag for performShortcut: if set, do not close the menu after executing the shortcut.
static Int	NONE Value to use for group and item identifier integers when you don't care about them.
static Int	SUPPORTED_MODIFIERS_MASK A mask of all supported modifiers for MenuItem's keyboard shortcuts

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

Constants

CATEGORY_ALTERNATIVE

Added in API level 1

static val CATEGORY_ALTERNATIVE: Int

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.

Value: 262144

CATEGORY_CONTAINER

Added in API level 1

static val CATEGORY_CONTAINER: Int

Category code for the order integer for items/groups that are part of a container -- or/add this with your base value.

Value: 65536

CATEGORY_SECONDARY

Added in API level 1

static val CATEGORY_SECONDARY: Int

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

Value: 196608

CATEGORY_SYSTEM

Added in API level 1

static val CATEGORY_SYSTEM: Int

Category code for the order integer for items/groups that are provided by the system -- or/add this with your base value.

Value: 131072

FIRST

Added in API level 1

static val FIRST: Int

First value for group and item identifier integers.

Value: 1

FLAG_ALWAYS_PERFORM_CLOSE

Added in API level 1

static val FLAG_ALWAYS_PERFORM_CLOSE: Int

Flag for performShortcut(int,android.view.KeyEvent,int): if set, always close the menu after executing the shortcut. Closing the menu also resets the prepared state.

Value: 2

FLAG_APPEND_TO_GROUP

Added in API level 1

static val FLAG_APPEND_TO_GROUP: Int

Flag for addIntentOptions: if set, do not automatically remove any existing menu items in the same group.

Value: 1

FLAG_PERFORM_NO_CLOSE

Added in API level 1

static val FLAG_PERFORM_NO_CLOSE: Int

Flag for performShortcut: if set, do not close the menu after executing the shortcut.

Value: 1

NONE

Added in API level 1

static val NONE: Int

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

Value: 0

SUPPORTED_MODIFIERS_MASK

Added in API level 26

static val SUPPORTED_MODIFIERS_MASK: Int

A mask of all supported modifiers for MenuItem's keyboard shortcuts

Value: 69647

Public methods

add

Added in API level 1

abstract fun add(titleRes: Int): MenuItem!

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

Parameters
titleRes	Int: Resource identifier of title string.

Return
MenuItem!	The newly added menu item.

add

Added in API level 1

abstract fun add(
    groupId: Int, 
    itemId: Int, 
    order: Int, 
    titleRes: Int
): MenuItem!

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

Parameters
groupId	Int: 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	Int: Unique item ID. Use NONE if you do not need a unique ID.
order	Int: The order for the item. Use NONE if you do not care about the order. See MenuItem.getOrder().
titleRes	Int: Resource identifier of title string.

Return
MenuItem!	The newly added menu item.

add

Added in API level 1

abstract fun add(
    groupId: Int, 
    itemId: Int, 
    order: Int, 
    title: CharSequence!
): MenuItem!

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

Parameters
groupId	Int: 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	Int: Unique item ID. Use NONE if you do not need a unique ID.
order	Int: The order for the item. Use NONE if you do not care about the order. See MenuItem.getOrder().
title	CharSequence!: The text to display for the item.

Return
MenuItem!	The newly added menu item.

add

Added in API level 1

abstract fun add(title: CharSequence!): MenuItem!

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

Parameters
title	CharSequence!: The text to display for the item.

Return
MenuItem!	The newly added menu item.

addIntentOptions

Added in API level 1

abstract fun addIntentOptions(
    groupId: Int, 
    itemId: Int, 
    order: Int, 
    caller: ComponentName!, 
    specifics: Array<Intent!>!, 
    intent: Intent!, 
    flags: Int, 
    outSpecificItems: Array<MenuItem!>!
): Int

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 Intent.CATEGORY_ALTERNATIVE or 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 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 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.

Parameters
groupId	Int: 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	Int: Unique item ID. Use NONE if you do not need a unique ID.
order	Int: The order for the items. Use NONE if you do not care about the order. See MenuItem.getOrder().
caller	ComponentName!: The current activity component name as defined by queryIntentActivityOptions().
specifics	Array<Intent!>!: Specific items to place first as defined by queryIntentActivityOptions().
intent	Intent!: Intent describing the kinds of items to populate in the list as defined by queryIntentActivityOptions().
flags	Int: Additional options controlling how the items are added.
outSpecificItems	Array<MenuItem!>!: 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
Int	The number of menu items that were added.

See Also

• #FLAG_APPEND_TO_GROUP
• android.view.MenuItem#setIntent

addSubMenu

Added in API level 1

abstract fun addSubMenu(titleRes: Int): SubMenu!

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 SubMenu.getItem().

Parameters
titleRes	Int: Resource identifier of title string.

Return
SubMenu!	The newly added sub-menu

addSubMenu

Added in API level 1

abstract fun addSubMenu(
    groupId: Int, 
    itemId: Int, 
    order: Int, 
    titleRes: Int
): SubMenu!

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

Parameters
groupId	Int: 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	Int: Unique item ID. Use NONE if you do not need a unique ID.
order	Int: The order for the item. Use NONE if you do not care about the order. See MenuItem.getOrder().
titleRes	Int: Resource identifier of title string.

Return
SubMenu!	The newly added sub-menu

addSubMenu

Added in API level 1

abstract fun addSubMenu(
    groupId: Int, 
    itemId: Int, 
    order: Int, 
    title: CharSequence!
): SubMenu!

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 SubMenu.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	Int: 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	Int: Unique item ID. Use NONE if you do not need a unique ID.
order	Int: The order for the item. Use NONE if you do not care about the order. See MenuItem.getOrder().
title	CharSequence!: The text to display for the item.

Return
SubMenu!	The newly added sub-menu

addSubMenu

Added in API level 1

abstract fun addSubMenu(title: CharSequence!): SubMenu!

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 SubMenu.getItem().

Parameters
title	CharSequence!: The text to display for the item.

Return
SubMenu!	The newly added sub-menu

clear

Added in API level 1

abstract fun clear(): Unit

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

close

Added in API level 3

abstract fun close(): Unit

Closes the menu, if open.

findItem

Added in API level 1

abstract fun findItem(id: Int): MenuItem!

Return the menu item with a particular identifier.

Parameters
id	Int: The identifier to find.

Return
MenuItem!	The menu item object, or null if there is no item with this identifier.

getItem

Added in API level 3

abstract fun getItem(index: Int): MenuItem!

Gets the menu item at the given index.

Parameters
index	Int: The index of the menu item to return.

Return
MenuItem!	The menu item.

Exceptions
java.lang.IndexOutOfBoundsException	when index < 0 || >= size()

hasVisibleItems

Added in API level 1

abstract fun hasVisibleItems(): Boolean

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

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

isShortcutKey

Added in API level 1

abstract fun isShortcutKey(
    keyCode: Int, 
    event: KeyEvent!
): Boolean

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

Parameters
keyCode	Int: the key code from KeyEvent to check.
event	KeyEvent!: the KeyEvent to use to help check.

performIdentifierAction

Added in API level 1

abstract fun performIdentifierAction(
    id: Int, 
    flags: Int
): Boolean

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

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

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

See Also

• #FLAG_PERFORM_NO_CLOSE

performShortcut

Added in API level 1

abstract fun performShortcut(
    keyCode: Int, 
    event: KeyEvent!, 
    flags: Int
): Boolean

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

Parameters
keyCode	Int: The keycode of the shortcut key.
event	KeyEvent!: Key event message.
flags	Int: Additional option flags or 0.

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

See Also

• #FLAG_PERFORM_NO_CLOSE

removeGroup

Added in API level 1

abstract fun removeGroup(groupId: Int): Unit

Remove all items in the given group.

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

removeItem

Added in API level 1

abstract fun removeItem(id: Int): Unit

Remove the item with the given identifier.

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

setGroupCheckable

Added in API level 1

abstract fun setGroupCheckable(
    group: Int, 
    checkable: Boolean, 
    exclusive: Boolean
): Unit

Control whether a particular group of items can show a check mark. This is similar to calling 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.

Parameters
group	Int: The group of items to operate on.
checkable	Boolean: Set to true to allow a check mark, false to disallow. The default is false.
exclusive	Boolean: 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 Also

• android.view.MenuItem#setCheckable
• android.view.MenuItem#setChecked

setGroupDividerEnabled

Added in API level 28

open fun setGroupDividerEnabled(groupDividerEnabled: Boolean): Unit

Enable or disable the group dividers.

setGroupEnabled

Added in API level 1

abstract fun setGroupEnabled(
    group: Int, 
    enabled: Boolean
): Unit

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

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

See Also

• android.view.MenuItem#setEnabled

setGroupVisible

Added in API level 1

abstract fun setGroupVisible(
    group: Int, 
    visible: Boolean
): Unit

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

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

See Also

• android.view.MenuItem#setVisible

setQwertyMode

Added in API level 1

abstract fun setQwertyMode(isQwerty: Boolean): Unit

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

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

size

Added in API level 1

abstract fun size(): Int

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

Return
Int	The item count.