Menus of Options

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

The first thing you should do is chain upward to the superclass (super. onCreateOptionsMenu(menu)) 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 onCreateOptionsMenu() or implement onPrepareOptionsMenu(), which is called just before displaying the menu each time it is requested.

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

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

• A choice identifier (also an int) for use in identifying this choice in the onOptionsItemSelected() 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 NONE.

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

The add() family of methods all return an instance of MenuItem, 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 setAlphabeticShortcut() and setNumericShortcut(), respectively. The menu is placed into alphabetic shortcut mode by calling setQwertyMode() on the menu with a true parameter.

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

• Calling MenuItem#setCheckable() 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 Menu#setGroupCheckable() 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 addIntentOptions() 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 addSubMenu() and supplying the same parameters as addMenu(). Android will eventually call onCreatePanelMenu(), passing it the choice identifier of your sub-menu, along with another Menu instance representing the sub-menu itself. As with onCreateOptionsMenu(), 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 onOptionsItemSelected() callback that a menu choice was selected. You are given the MenuItem object corresponding to the selected menu choice. A typical pattern is to switch() on the menu ID (item.getItemId()) and take appropriate action. Note that onOptionsItemSelected() is used regardless of whether the chosen menu item was in the base menu or in a sub-menu.

0 0

Post a comment