android.view
public
interface
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:
- Context menus: Do not support item shortcuts, item icons, and sub
menus.
- 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.
- Sub menus: Do not support item icons, or nested sub menus.
Known Indirect Subclasses
ContextMenu |
Extension of Menu for context menus providing functionality to modify
the header of the context menu. |
SubMenu |
Subclass of Menu for sub menus. |
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. |
1 |
0x00000001 |
int |
FLAG_ALWAYS_PERFORM_CLOSE |
Flag for performShortcut(int, KeyEvent, int): if set, always
close the menu after executing the shortcut. |
2 |
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. |
1 |
0x00000001 |
int |
FLAG_PERFORM_NO_CLOSE |
Flag for performShortcut(int, KeyEvent, int): if set, do not close the menu after
executing the shortcut. |
1 |
0x00000001 |
int |
NONE |
Value to use for group and item identifier integers when you don't care
about them. |
0 |
0x00000000 |
Public Methods
|
|
|
|
|
MenuItem |
add(int titleRes) |
|
|
|
|
|
MenuItem |
add(int groupId, int itemId, int order, CharSequence title) |
|
|
|
|
|
MenuItem |
add(int groupId, int itemId, int order, int titleRes) |
|
|
|
|
|
MenuItem |
add(CharSequence title) |
|
|
|
|
|
int |
addIntentOptions(int groupId, int itemId, int order, ComponentName caller, Intent[] specifics, Intent intent, int flags, MenuItem[] outSpecificItems) |
|
|
|
|
|
SubMenu |
addSubMenu(int titleRes) |
|
|
|
|
|
SubMenu |
addSubMenu(int groupId, int itemId, int order, int titleRes) |
|
|
|
|
|
SubMenu |
addSubMenu(CharSequence title) |
|
|
|
|
|
SubMenu |
addSubMenu(int groupId, int itemId, int order, CharSequence title) |
|
|
|
|
|
void |
clear() |
|
|
|
|
|
MenuItem |
findItem(int id) |
|
|
|
|
|
boolean |
hasVisibleItems() |
|
|
|
|
|
boolean |
isShortcutKey(int keyCode, KeyEvent event) |
|
|
|
|
|
boolean |
performIdentifierAction(int id, int flags) |
|
|
|
|
|
boolean |
performShortcut(int keyCode, KeyEvent event, int flags) |
|
|
|
|
|
void |
removeGroup(int groupId) |
|
|
|
|
|
void |
removeItem(int id) |
|
|
|
|
|
void |
setGroupCheckable(int group, boolean checkable, boolean exclusive) |
|
|
|
|
|
void |
setGroupEnabled(int group, boolean enabled) |
|
|
|
|
|
void |
setGroupVisible(int group, boolean visible) |
|
|
|
|
|
void |
setQwertyMode(boolean isQwerty) |
|
|
|
|
|
int |
size() |
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
public
static
final
int
FLAG_PERFORM_NO_CLOSE
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.
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. |
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. |
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. |
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. |
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.