Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update menu dev guide with more info about action bar

Browse Source 
Change-Id: I5b0b052c96b23a395a669b1c3da11dc87f625f25
This commit is contained in:
Scott Main
2011-02-02 20:08:20 -08:00
parent 1b1962f383
commit 4fe3e53e85
4 changed files with 177 additions and 146 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
docs/html/guide/topics/resources/menu-resource.jd
View File

@@ -12,9 +12,12 @@ parent.link=available-resources.html
</div>
</div>
<p>A menu resource defines an application menu (Options Menu, Context Menu, or Sub Menu) that
<p>A menu resource defines an application menu (Options Menu, Context Menu, or submenu) that
can be inflated with {@link android.view.MenuInflater}.</p>
<p>For a guide to using menus, see the <a href="{@docRoot}guide/topics/ui/menus.html">Creating
Menus</a> document.</p>
<dl class="xml">
<dt>file location:</dt>
@@ -110,12 +113,12 @@ example at the bottom.
href="{@docRoot}guide/developing/tools/proguard.html">ProGuard</a> (or a similar tool),
be sure to exclude the method you specify in this attribute from renaming, because it can break the
functionality.</p>
<p>Introduced in API Level HONEYCOMB.</p></dd>
<p>Introduced in API Level 11.</p></dd>
<dt><code>android:showAsAction</code></dt>
<dd><em>Keyword</em>. When and how this item should appear as an action item in the Action
Bar. A menu item can appear as an action item only when the activity includes an {@link
android.app.ActionBar} (introduced in API Level HONEYCOMB). Valid values:
android.app.ActionBar} (introduced in API Level 11). Valid values:
<table>
<tr><th>Value</th><th>Description</th></tr>
<tr><td><code>ifRoom</code></td><td>Only place this item in the Action Bar if
@@ -131,14 +134,14 @@ with other UI in the action bar.</td></tr>
</table>
<p>See <a href="{@docRoot}guide/topics/ui/actionbar.html">Using the Action Bar</a> for
more information.</p>
<p>Introduced in API Level HONEYCOMB.</p>
<p>Introduced in API Level 11.</p>
</dd>
<dt><code>android:actionViewLayout</code></dt>
<dd><em>Layout resource</em>. A layout to use as the action view.
<p>See <a href="{@docRoot}guide/topics/ui/actionbar.html">Using the Action Bar</a> for
more information.</p>
<p>Introduced in API Level HONEYCOMB.</p></dd>
<p>Introduced in API Level 11.</p></dd>
<dt><code>android:actionViewClassName</code></dt>
<dd><em>Class name</em>. A fully-qualified class name for the {@link android.view.View}
@@ -149,7 +152,7 @@ more information.</p>
href="{@docRoot}guide/developing/tools/proguard.html">ProGuard</a> (or a similar tool),
be sure to exclude the class you specify in this attribute from renaming, because it can break the
functionality.</p>
<p>Introduced in API Level HONEYCOMB.</p></dd>
<p>Introduced in API Level 11.</p></dd>
<dt><code>android:alphabeticShortcut</code></dt>
@@ -277,7 +280,7 @@ public void onGroupItemClick(MenuItem item) {
}
</pre>
<p class="note"><strong>Note:</strong> The {@code android:showAsAction} attribute is
available only on Android X.X (API Level HONEYCOMB) and greater.</p>
available only on Android 3.0 (API Level 11) and greater.</p>
</dd> <!-- end example -->

306
docs/html/guide/topics/ui/menus.jd
View File

@@ -7,11 +7,11 @@ parent.link=index.html
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#xml">Defining Menus</a></li>
<li><a href="#xml">Creating a Menu Resource</a></li>
<li><a href="#Inflating">Inflating a Menu Resource</a>
<li><a href="#options-menu">Creating an Options Menu</a>
<ol>
<li><a href="#ChangingTheMenu">Changing the menu when it opens</a></li>
<li><a href="#ChangingTheMenu">Changing menu items at runtime</a></li>
</ol>
</li>
<li><a href="#context-menu">Creating a Context Menu</a></li>
@@ -21,7 +21,7 @@ parent.link=index.html
<li><a href="#groups">Menu groups</a></li>
<li><a href="#checkable">Checkable menu items</a></li>
<li><a href="#shortcuts">Shortcut keys</a></li>
<li><a href="#intents">Intents for menu items</a></li>
<li><a href="#intents">Dynamically adding menu intents</a></li>
</ol>
</li>
</ol>
@@ -42,52 +42,60 @@ parent.link=index.html
</div>
</div>
<p>Menus are an important part of an application that provide a familiar interface for the user
to access application functions and settings. Android offers an easy programming interface
for you to provide application menus in your application.</p>
<p>Menus are an important part of an activity's user interface, which provide users a familiar
way to perform actions. Android offers a simple framework for you to add standard
menus to your application.</p>
<p>Android provides three types of application menus:</p>
<p>There are three types of application menus:</p>
<dl>
<dt><strong>Options Menu</strong></dt>
<dd>The primary collection of menu items for an Activity that is associated with the device MENU
key. To provide instant access to select menu items, you can place some items in the <a
href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a>, if available.</dd>
<dd>The primary collection of menu items for an activity, which appears when the user touches
the MENU button. When your application is running on Android 3.0 or later, you can provide
quick access to select menu items by placing them directly in the <a
href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a>, as "action items."</dd>
<dt><strong>Context Menu</strong></dt>
<dd>A floating list of menu items that appears when the user performs a long-press on a View.
<dd>A floating list of menu items that appears when the user touches and holds a view
that's registered to provide a context menu.
</dd>
<dt><strong>Submenu</strong></dt>
<dd>A floating list of menu items that the user opens by pressing a menu item in the Options
Menu or a context menu. A submenu item cannot support a nested submenu. </dd>
<dd>A floating list of menu items that appears when the user touches a menu item that contains
a nested menu.</dd>
</dl>
<p>This document shows you how to create each type of menu, using XML to define the content of
the menu and callback methods in your activity to respond when the user selects an item.</p>
<h2 id="xml">Defining Menus</h2>
<h2 id="xml">Creating a Menu Resource</h2>
<p>Instead of instantiating a {@link android.view.Menu} in your application code, you should
define a menu and all its items in an XML <a
href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a>, then inflate the menu
resource (load it as a programmable object) in your application code. Defining your menus in XML is
a good practice because it separates your interface design from your application code (the same as
when you <a href="{@docRoot}guide/topics/ui/declaring-layout.html">define your Activity
layout</a>).</p>
resource (load it as a programmable object) in your application code. Using a menu resource to
define your menu is a good practice because it separates the content for the menu from your
application code. It's also easier to visualize the structure and content of a menu in XML.</p>
<p>To define a menu, create an XML file inside your project's <code>res/menu/</code>
<p>To create a menu resource, create an XML file inside your project's <code>res/menu/</code>
directory and build the menu with the following elements:</p>
<dl>
<dt><code>&lt;menu></code></dt>
<dd>Creates a {@link android.view.Menu}, which is a container for menu items. It must be
the root node and holds one or more of the following elements. You can also nest this element
in an {@code &lt;item&gt;} to create a submenu.</dd>
<dd>Defines a {@link android.view.Menu}, which is a container for menu items. A
<code>&lt;menu></code> element must be the root node for the file and can hold one or more
<code>&lt;item></code> and <code>&lt;group></code> elements.</dd>
<dt><code>&lt;item></code></dt>
<dd>Creates a {@link android.view.MenuItem}, which represents a single item in a menu.</dd>
<dd>Creates a {@link android.view.MenuItem}, which represents a single item in a menu. This
element may contain a nested <code>&lt;menu></code> element in order to create a submenu.</dd>
<dt><code>&lt;group></code></dt>
<dd>An optional, invisible container for {@code &lt;item&gt;} elements. It allows you to
categorize menu items so they share properties such as active state and visibility. See <a
href="#groups">Menu groups</a>.</dd>
categorize menu items so they share properties such as active state and visibility. See the
section about <a href="#groups">Menu groups</a>.</dd>
</dl>
<p>For example, here is a file in <code>res/menu/</code> named <code>game_menu.xml</code>:</p>
<p>Here's an example menu named <code>game_menu.xml</code>:</p>
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;menu xmlns:android="http://schemas.android.com/apk/res/android"&gt;
@@ -100,28 +108,33 @@ href="#groups">Menu groups</a>.</dd>
&lt;/menu&gt;
</pre>
<p>This example defines a menu with two menu items. Each item includes the attributes:</p>
<p>This example defines a menu with two items. Each item includes the attributes:</p>
<dl>
<dt>{@code android:id}</dt>
<dd>A resource ID that's unique to the item so that the application can recognize the item when
the user selects it.</dd>
<dd>A resource ID that's unique to the item, which allows the application can recognize the item
when the user selects it.</dd>
<dt>{@code android:icon}</dt>
<dd>A drawable resource that is the icon visible to the user.</dd>
<dd>A reference to a drawable to use as the item's icon.</dd>
<dt>{@code android:title}</dt>
<dd>A string resource that is the title visible to the user.</dd>
<dd>A reference to a string to use as the item's title.</dd>
</dl>
<p>For more about the XML syntax and attributes for a menu resource, see the <a
<p>There are many more attributes you can include in an {@code &lt;item&gt;}, including some that
specify how the item may appear in the <a
href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a>. For more information about the XML
syntax and attributes for a menu resource, see the <a
href="{@docRoot}guide/topics/resources/menu-resource.html">Menu Resource</a> reference.</p>
<h2 id="Inflating">Inflating a Menu Resource</h2>
<p>You can inflate your menu resource (convert the XML resource into a programmable object) using
<p>From your application code, you can inflate a menu resource (convert the XML resource into a
programmable object) using
{@link android.view.MenuInflater#inflate(int,Menu) MenuInflater.inflate()}. For
example, the following code inflates the <code>game_menu.xml</code> file defined above during the
{@link android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} callback method, to be
used for the Options Menu:</p>
example, the following code inflates the <code>game_menu.xml</code> file defined above, during the
{@link android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} callback method, to
use the menu as the activity's Options Menu:</p>
<pre>
&#64;Override
@@ -133,59 +146,47 @@ public boolean onCreateOptionsMenu(Menu menu) {
</pre>
<p>The {@link android.app.Activity#getMenuInflater()} method returns a {@link
android.view.MenuInflater} for the Activity. With this object, you can call {@link
android.view.MenuInflater} for the activity. With this object, you can call {@link
android.view.MenuInflater#inflate(int,Menu) inflate()}, which inflates a menu resource into a
{@link android.view.Menu} object. In this example, the menu resource defined by
<code>game_menu.xml</code>
is inflated into the {@link android.view.Menu} that was passed into {@link
android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()}. (This callback method for
creating an option menu is discussed more in the next section.)</p>
the Options Menu is discussed more in the next section.)</p>
<h2 id="options-menu">Creating an Options Menu</h2>
<div class="figure" style="width:200px">
<img src="{@docRoot}images/options_menu.png" height="300" alt="" />
<p class="img-caption"><strong>Figure 1.</strong> Screenshot of an Options Menu.</p>
<img src="{@docRoot}images/options_menu.png" height="333" alt="" />
<p class="img-caption"><strong>Figure 1.</strong> Screenshot of the Options Menu in the
Browser.</p>
</div>
<p>The Options Menu is where you should include basic application functions and necessary navigation
<p>The Options Menu is where you should include basic activity actions and necessary navigation
items (for example, a button to open the application settings). Items in the Options Menu are
accessible in two distinct ways: in the Action Bar and in the menu revealed by the MENU
key.</p>
accessible in two distinct ways: the MENU button or in the <a
href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> (on devices running Android 3.0
or higher).</p>
<p>The Action Bar is an optional widget that appears at the top of the activity in place of the
title bar. It can display several menu items that you choose from the Options Menu, but items in
the Action Bar display only an icon (no title text). Users can reveal the other menu items in the
Options Menu with the MENU key.</p>
<p>When running on a device with Android 2.3 and lower, the Options Menu appears at the bottom of
the screen, as shown in figure 1. When opened, the first visible portion of the Options Menu is
the icon menu. It holds the first six menu items. If you add more than six items to the
Options Menu, Android places the sixth item and those after it into the overflow menu, which the
user can open by touching the "More" menu item.</p>
<p>If you include the Action Bar in your activity, the menu items that are not placed in the Action
Bar can appear in two different styles:</p>
<dl>
<dt>Action Bar Menu</dt>
<dd>If the device has an extra-large screen ({@code xlarge}), then all items in the Options Menu
that are not placed in the Action Bar are placed into a drop-down list at the right side of the
Action Bar, with icons and title text. The user can reveal the drop-down list by pressing the
drop-down icon in the Action Bar or the MENU key.</dd>
<dt>Standard Options Menu</dt>
<dd>If the device <em>does not</em> have an extra-large screen, then all items in the Options
Menu that are not placed in the Action Bar are placed into the Standard Options Menu at the bottom
of the activity. The user can reveal the standard Options Menu by pressing the MENU key.
<p>The first visible portion of the Standard Options Menu is called the Icon Menu.
It holds the first six menu items (excluding any added to the Action Bar), with icons and title
text. If there are more than six items, Android adds a "More" item as the sixth menu item and places
the remaining items into the Expanded Menu, which the user can open by selecting "More". The
Expanded Menu displays menu items only by their title text (no icon)</p>
</dd>
</dl>
<p>On Android 3.0 and higher, items from the Options Menu is placed in the Action Bar, which appears
at the top of the activity in place of the traditional title bar. By default all items from the
Options Menu are placed in the overflow menu, which the user can open by touching the menu icon
on the right side of the Action Bar. However, you can place select menu items directly in the
Action Bar as "action items," for instant access, as shown in figure 2.</p>
<p>When the user opens the Options Menu for the first time, Android calls your Activity's
{@link android.app.Activity#onCreateOptionsMenu(Menu)
onCreateOptionsMenu()} method. Override this method in your Activity
and populate the {@link android.view.Menu} that is passed into the method. Populate the
{@link android.view.Menu} by inflating a menu resource as described in <a
<p>When the Android system creates the Options Menu for the first time, it calls your
activity's {@link android.app.Activity#onCreateOptionsMenu(Menu)
onCreateOptionsMenu()} method. Override this method in your activity
and populate the {@link android.view.Menu} that is passed into the method,
{@link android.view.Menu} by inflating a menu resource as described above in <a
href="#Inflating">Inflating a Menu Resource</a>. For example:</p>
<pre>
@@ -197,17 +198,31 @@ public boolean onCreateOptionsMenu(Menu menu) {
}
</pre>
<p>(You can also populate the menu in code, using {@link android.view.Menu#add(int,int,int,int)
add()} to add items to the {@link android.view.Menu}.)</p>
<div class="figure" style="width:500px">
<img src="{@docRoot}images/ui/actionbar.png" height="34" alt="" />
<p class="img-caption"><strong>Figure 2.</strong> Screenshot of the Action Bar in the Email
application, with two action items from the Options Menu, plus the overflow menu.</p>
</div>
<p>When the user selects a menu item from the Options Menu (including items selected from the
Action Bar), the system calls your Activity's
<p>You can also populate the menu in code, using {@link android.view.Menu#add(int,int,int,int)
add()} to add items to the {@link android.view.Menu}.</p>
<p class="note"><strong>Note:</strong> On Android 2.3 and lower, the system calls {@link
android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} to create the Options Menu
when the user opens it for the first time, but on Android 3.0 and greater, the system creates it as
soon as the activity is created, in order to populate the Action Bar.</p>
<h3 id="RespondingOptionsMenu">Responding to user action</h3>
<p>When the user selects a menu item from the Options Menu (including action items in the
Action Bar), the system calls your activity's
{@link android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()}
method. This method passes the
{@link android.view.MenuItem} that the user selected. You can identify the menu item by calling
{@link android.view.MenuItem#getItemId()}, which returns the unique ID for the menu
item (defined by the {@code android:id} attribute in the menu resource or with an integer passed
to the {@link android.view.Menu#add(int,int,int,int) add()} method). You can match this ID
item (defined by the {@code android:id} attribute in the menu resource or with an integer
given to the {@link android.view.Menu#add(int,int,int,int) add()} method). You can match this ID
against known menu items and perform the appropriate action. For example:</p>
<pre>
@@ -229,45 +244,67 @@ public boolean onOptionsItemSelected(MenuItem item) {
<p>In this example, {@link android.view.MenuItem#getItemId()} queries the ID for the selected menu
item and the switch statement compares the ID against the resource IDs that were assigned to menu
items in the XML resource. When a switch case successfully handles the item, it
returns "true" to indicate that the item selection was handled. Otherwise, the default statement
passes the menu item to the super class in
items in the XML resource. When a switch case successfully handles the menu item, it
returns {@code true} to indicate that the item selection was handled. Otherwise, the default
statement passes the menu item to the super class, in
case it can handle the item selected. (If you've directly extended the {@link android.app.Activity}
class, then the super class returns "false", but it's a good practice to
pass unhandled menu items to the super class instead of directly returning "false".)</p>
class, then the super class returns {@code false}, but it's a good practice to
pass unhandled menu items to the super class instead of directly returning {@code false}.)</p>
<p>Additionally, Android 3.0 adds the ability for you to define the on-click behavior for a menu
item in the <a href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a> XML,
using the {@code android:onClick} attribute. So you don't need to implement {@link
android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()}. Using the {@code
android:onClick} attribute, you can specify a method to call when the user selects the menu item.
Your activity must then implement the method specified in the {@code android:onClick} attribute so
that it accepts a single {@link android.view.MenuItem} parameter&mdash;when the system calls this
method, it passes the menu item selected.</p>
<p class="note"><strong>Tip:</strong> If your application contains multiple activities and
some of them provide the same Options Menu, consider creating
an Activity that implements nothing except the {@link android.app.Activity#onCreateOptionsMenu(Menu)
an activity that implements nothing except the {@link android.app.Activity#onCreateOptionsMenu(Menu)
onCreateOptionsMenu()} and {@link android.app.Activity#onOptionsItemSelected(MenuItem)
onOptionsItemSelected()} methods. Then extend this class for each Activity that should share the
onOptionsItemSelected()} methods. Then extend this class for each activity that should share the
same Options Menu. This way, you have to manage only one set of code for handling menu
actions and each descendant class inherits the menu behaviors.<br/><br/>
If you want to add menu items to one of your descendant activities,
override {@link android.app.Activity#onCreateOptionsMenu(Menu)
onCreateOptionsMenu()} in that Activity. Call {@code super.onCreateOptionsMenu(menu)} so the
onCreateOptionsMenu()} in that activity. Call {@code super.onCreateOptionsMenu(menu)} so the
original menu items are created, then add new menu items with {@link
android.view.Menu#add(int,int,int,int) menu.add()}. You can also override the super class's
behavior for individual menu items.</p>
<h3 id="ChangingTheMenu">Changing the menu when it opens</h3>
<h3 id="ChangingTheMenu">Changing menu items at runtime</h3>
<p>The {@link android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} method is
called only the first time the Options Menu is opened. The system keeps and re-uses the {@link
android.view.Menu} you define in this method until your Activity is destroyed. If you want to change
the Options Menu each time it opens, you must override the
<p>Once the activity is created, the {@link android.app.Activity#onCreateOptionsMenu(Menu)
onCreateOptionsMenu()} method is
called only once, as described above. The system keeps and re-uses the {@link
android.view.Menu} you define in this method until your activity is destroyed. If you want to change
the Options Menu any time after it's first created, you must override the
{@link android.app.Activity#onPrepareOptionsMenu(Menu) onPrepareOptionsMenu()} method. This passes
you the {@link android.view.Menu} object as it currently exists. This is useful if you'd like to
remove, add, disable, or enable menu items depending on the current state of your application.</p>
<p>On Android 2.3 and lower, the system calls {@link android.app.Activity#onPrepareOptionsMenu(Menu)
onPrepareOptionsMenu()} each time the user opens the Options Menu.</p>
<p>On Android 3.0 and higher, you must call {@link android.app.Activity#invalidateOptionsMenu
invalidateOptionsMenu()} when you want to update the menu, because the menu is always open. The
system will then call {@link android.app.Activity#onPrepareOptionsMenu(Menu) onPrepareOptionsMenu()}
so you can update the menu items.</p>
<p class="note"><strong>Note:</strong>
You should never change items in the Options Menu based on the {@link android.view.View} currently
in focus. When in touch mode (when the user is not using a trackball or d-pad), Views
in focus. When in touch mode (when the user is not using a trackball or d-pad), views
cannot take focus, so you should never use focus as the basis for modifying
items in the Options Menu. If you want to provide menu items that are context-sensitive to a {@link
android.view.View}, use a <a href="#context-menu">Context Menu</a>.</p>
<p>If you're developing for Android 3.0 or higher, be sure to also read <a
href="{@docRoot}guide/topics/ui/actionbar.html">Using the Action Bar</a>.</p>
<h2 id="context-menu">Creating a Context Menu</h2>
@@ -287,7 +324,7 @@ feature.)</p>
<div class="sidebox-wrapper">
<div class="sidebox">
<h3>Register a ListView</h3>
<p>If your Activity uses a {@link android.widget.ListView} and
<p>If your activity uses a {@link android.widget.ListView} and
you want all list items to provide a context menu, register all items for a context
menu by passing the {@link android.widget.ListView} to {@link
android.app.Activity#registerForContextMenu(View) registerForContextMenu()}. For
@@ -301,7 +338,7 @@ menu. Call {@link android.app.Activity#registerForContextMenu(View) registerForC
pass it the {@link android.view.View} you want to give a context menu. When this View then
receives a long-press, it displays a context menu.</p>
<p>To define the context menu's appearance and behavior, override your Activity's context menu
<p>To define the context menu's appearance and behavior, override your activity's context menu
callback methods, {@link android.app.Activity#onCreateContextMenu(ContextMenu,View,ContextMenuInfo)
onCreateContextMenu()} and
{@link android.app.Activity#onContextItemSelected(MenuItem) onContextItemSelected()}.</p>
@@ -325,7 +362,7 @@ href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a>. (Y
parameters include the {@link android.view.View}
that the user selected and a {@link android.view.ContextMenu.ContextMenuInfo} object that provides
additional information about the item selected. You might use these parameters to determine
which context menu should be created, but in this example, all context menus for the Activity are
which context menu should be created, but in this example, all context menus for the activity are
the same.</p>
<p>Then when the user selects an item from the context menu, the system calls {@link
@@ -387,9 +424,9 @@ resource</a>, you can create a submenu by adding a {@code &lt;menu&gt;} element
android:icon="@drawable/file"
android:title="@string/file" &gt;
&lt;!-- "file" submenu --&gt;
&lt;menu"&gt;
&lt;item android:id="@+id/new"
android:title="@string/new" /&gt;
&lt;menu&gt;
&lt;item android:id="@+id/create_new"
android:title="@string/create_new" /&gt;
&lt;item android:id="@+id/open"
android:title="@string/open" /&gt;
&lt;/menu&gt;
@@ -456,8 +493,9 @@ items in the group by referencing the group ID and using the methods listed abov
<h3 id="checkable">Checkable menu items</h3>
<div class="figure" style="width:200px">
<img src="{@docRoot}images/radio_buttons.png" height="300" alt="" />
<p class="img-caption"><strong>Figure 2.</strong> Screenshot of checkable menu items</p>
<img src="{@docRoot}images/radio_buttons.png" height="333" alt="" />
<p class="img-caption"><strong>Figure 3.</strong> Screenshot of a submenu with checkable
items.</p>
</div>
<p>A menu can be useful as an interface for turning options on and off, using a checkbox for
@@ -525,7 +563,7 @@ public boolean onOptionsItemSelected(MenuItem item) {
<p>If you don't set the checked state this way, then the visible state of the item (the checkbox or
radio button) will not
change when the user selects it. When you do set the state, the Activity preserves the checked state
change when the user selects it. When you do set the state, the activity preserves the checked state
of the item so that when the user opens the menu later, the checked state that you
set is visible.</p>
@@ -538,7 +576,8 @@ href="{@docRoot}guide/topics/data/data-storage.html#pref">Shared Preferences</a>
<h3 id="shortcuts">Shortcut keys</h3>
<p>You can add quick-access shortcut keys using letters and/or numbers to menu items with the
<p>To facilitate quick access to items in the Options Menu when the user's device has a hardware
keyboard, you can add quick-access shortcut keys using letters and/or numbers, with the
{@code android:alphabeticShortcut} and {@code android:numericShortcut} attributes in the {@code
&lt;item&gt;} element. You can also use the methods {@link
android.view.MenuItem#setAlphabeticShortcut(char)} and {@link
@@ -546,57 +585,46 @@ android.view.MenuItem#setNumericShortcut(char)}. Shortcut keys are <em>not</em>
case sensitive.</p>
<p>For example, if you apply the "s" character as an alphabetic shortcut to a "save" menu item, then
when the menu is open (or while the user holds the MENU key) and the user presses the "s" key,
when the menu is open (or while the user holds the MENU button) and the user presses the "s" key,
the "save" menu item is selected.</p>
<p>This shortcut key is displayed as a tip in the menu item, below the menu item name
(except for items in the Icon Menu, which are displayed only if the user holds the MENU
key).</p>
button).</p>
<p class="note"><strong>Note:</strong> Shortcut keys for menu items only work on devices with a
hardware keyboard. Shortcuts cannot be added to items in a Context Menu.</p>
<h3 id="intents">Intents for menu items</h3>
<p>Sometimes you'll want a menu item to launch an Activity using an Intent (whether it's an
Activity in your application or another application). When you know the Intent you want to use and
have a specific menu item that should initiate the Intent, you can execute the Intent with {@link
android.app.Activity#startActivity(Intent) startActivity()} during the appropriate on-item-selected
callback method (such as the {@link android.app.Activity#onOptionsItemSelected(MenuItem)
onOptionsItemSelected()} callback).</p>
<h3 id="intents">Dynamically adding menu intents</h3>
<p>Sometimes you'll want a menu item to launch an activity using an {@link android.content.Intent}
(whether it's an activity in your application or another application). When you know the intent you
want to use and have a specific menu item that should initiate the intent, you can execute the
intent with {@link android.app.Activity#startActivity(Intent) startActivity()} during the
appropriate on-item-selected callback method (such as the {@link
android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} callback).</p>
<p>However, if you are not certain that the user's device
contains an application that handles the Intent, then adding a menu item that executes the
Intent can result in a non-functioning menu item, because the Intent might not resolve to an
Activity that accepts it. To solve this, Android lets you dynamically add menu items to your menu
when Android finds activities on the device that handle your Intent.</p>
contains an application that handles the intent, then adding a menu item that invokes it can result
in a non-functioning menu item, because the intent might not resolve to an
activity. To solve this, Android lets you dynamically add menu items to your menu
when Android finds activities on the device that handle your intent.</p>
<p>If you're not familiar with creating Intents, read the <a
href="/guide/topics/intents/intents-filters.html">Intents and Intent Filters</a>.</p>
<h4>Dynamically adding Intents</h4>
<p>When you don't know if the user's device has an application that handles a specific Intent,
you can define the Intent and let Android search the device for activities that accept the Intent.
When it finds activies that handle the Intent, it adds a menu item for
each one to your menu and attaches the appropriate Intent to open the Activity when the user
selects it.</p>
<p>To add menu items based on available activities that accept an Intent:</p>
<p>To add menu items based on available activities that accept an intent:</p>
<ol>
<li>Define an
Intent with the category {@link android.content.Intent#CATEGORY_ALTERNATIVE} and/or
intent with the category {@link android.content.Intent#CATEGORY_ALTERNATIVE} and/or
{@link android.content.Intent#CATEGORY_SELECTED_ALTERNATIVE}, plus any other requirements.</li>
<li>Call {@link
android.view.Menu#addIntentOptions(int,int,int,ComponentName,Intent[],Intent,int,MenuItem[])
Menu.addIntentOptions()}. Android then searches for any applications that can perform the Intent
Menu.addIntentOptions()}. Android then searches for any applications that can perform the intent
and adds them to your menu.</li>
</ol>
<p>If there are no applications installed
that satisfy the Intent, then no menu items are added.</p>
that satisfy the intent, then no menu items are added.</p>
<p class="note"><strong>Note:</strong>
{@link android.content.Intent#CATEGORY_SELECTED_ALTERNATIVE} is used to handle the currently
@@ -621,7 +649,7 @@ public boolean onCreateOptionsMenu(Menu menu){
R.id.intent_group, // Menu group to which new items will be added
0, // Unique item ID (none)
0, // Order for the items (none)
this.getComponentName(), // The current Activity name
this.getComponentName(), // The current activity name
null, // Specific items to place first (none)
intent, // Intent created above that describes our requirements
0, // Additional flags to control items (none)
@@ -630,8 +658,8 @@ public boolean onCreateOptionsMenu(Menu menu){
return true;
}</pre>
<p>For each Activity found that provides an Intent filter matching the Intent defined, a menu
item is added, using the value in the Intent filter's <code>android:label</code> as the
<p>For each activity found that provides an intent filter matching the intent defined, a menu
item is added, using the value in the intent filter's <code>android:label</code> as the
menu item title and the application icon as the menu item icon. The
{@link android.view.Menu#addIntentOptions(int,int,int,ComponentName,Intent[],Intent,int,MenuItem[])
addIntentOptions()} method returns the number of menu items added.</p>
@@ -642,14 +670,14 @@ addIntentOptions()}, it overrides any and all menu items by the menu group speci
argument.</p>
<h4>Allowing your Activity to be added to menus</h4>
<h4>Allowing your activity to be added to other menus</h4>
<p>You can also offer the services of your Activity to other applications, so your
<p>You can also offer the services of your activity to other applications, so your
application can be included in the menu of others (reverse the roles described above).</p>
<p>To be included in other application menus, you need to define an Intent
<p>To be included in other application menus, you need to define an intent
filter as usual, but be sure to include the {@link android.content.Intent#CATEGORY_ALTERNATIVE}
and/or {@link android.content.Intent#CATEGORY_SELECTED_ALTERNATIVE} values for the Intent filter
and/or {@link android.content.Intent#CATEGORY_SELECTED_ALTERNATIVE} values for the intent filter
category. For example:</p>
<pre>
&lt;intent-filter label="Resize Image">
@@ -660,7 +688,7 @@ category. For example:</p>
&lt;/intent-filter>
</pre>
<p>Read more about writing Intent filters in the
<p>Read more about writing intent filters in the
<a href="/guide/topics/intents/intents-filters.html">Intents and Intent Filters</a> document.</p>
<p>For a sample application using this technique, see the

BIN
docs/html/images/options_menu.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 24 KiB

After

Width:  |  Height:  |  Size: 40 KiB

BIN
docs/html/images/radio_buttons.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 24 KiB

After

Width:  |  Height:  |  Size: 74 KiB