Menus of Options

Rather than building your activity’s options menu during , the way you wire up the rest of your UI, you instead need to implement . This callback receives an instance of .

The first thing you should do is chain upward to the superclass () so the Android framework can add in any menu choices it feels are necessary. Then you can go about adding your own options, described momentarily.

If you will need to adjust the menu during your activity’s use (e.g., disable a now‑invalid menu choice), just hold onto the Menu instance you receive in or implement , which is called just before displaying the menu each time it is requested.

Given that you have received a Menu object via , you add menu choices by calling . There are many flavors of this method, which require some combination of the following parameters:

• A group identifier (), which should be NONE unless you are creating a specific grouped set of menu choices for use with (see the following list).

• A choice identifier (also an int) for use in identifying this choice in the callback when a menu choice is selected.

• An order identifier (yet another int), for indicating where this menu choice should be slotted if the menu has Android‑supplied choices alongside your own – for now, just use .

• The text of the menu choice, as a or a resource ID.

The family of methods all return an instance of , where you can adjust any of the menu‑item settings you have already set (e.g., the text of the menu choice). You can also set the shortcuts for the menu choice – single‑character mnemonics that select that menu choice when the menu is visible. Android supports both an alphabetic (or QWERTY) set of shortcuts and a numeric set of shortcuts. These are set individually by calling and , respectively. The menu is placed into alphabetic shortcut mode by calling on the menu with a parameter.

The choice and group identifiers are keys used to unlock additional menu features, such as these:

• Calling with a choice identifier to control if the menu choice has a two‑state checkbox alongside the title, where the checkbox value gets toggled when the user chooses that menu choice

• Calling with a group identifier to turn a set of menu choices into ones with a mutual‑exclusion radio button between them, so one out of the group can be in the “checked” state at any time

You can also call to populate the menu with menu choices corresponding to the available activities for an intent (see Chapter 25).

Finally, you can create fly‑out sub‑menus by calling and supplying the same parameters as . Android will eventually call , passing it the choice identifier of your sub‑menu, along with another instance representing the sub‑menu itself. As with , you should chain upward to the superclass, then add menu choices to the sub‑menu. One limitation is that you cannot indefinitely nest sub‑menus – a menu can have a sub‑menu, but a sub‑menu cannot itself have a sub‑sub‑menu.

If the user makes a menu choice, your activity will be notified via the callback that a menu choice was selected. You are given the object corresponding to the selected menu choice. A typical pattern is to on the menu ID () and take appropriate action. Note that is used regardless of whether the chosen menu item was in the base menu or in a sub‑menu.