1b10b48f62d3cac684424e4181d4e8ec61f227e95Scott Mainpage.title=Menus 29066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectparent.title=User Interface 39066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectparent.link=index.html 49066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project@jd:body 59066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 69066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<div id="qv-wrapper"> 79066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<div id="qv"> 89066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <h2>In this document</h2> 95e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<ol> 105e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <li><a href="#xml">Defining a Menu in XML</a></li> 115e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <li><a href="#options-menu">Creating an Options Menu</a> 125e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <ol> 135e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <li><a href="#RespondingOptionsMenu">Handling click events</a></li> 145e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <li><a href="#ChangingTheMenu">Changing menu items at runtime</a></li> 155e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main </ol> 165e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main </li> 175e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <li><a href="#context-menu">Creating Contextual Menus</a> 185e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <ol> 195e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <li><a href="#FloatingContextMenu">Creating a floating context menu</a></li> 2009ff04d7893a9f49e478bb732ce1ea1b17662a3bScott Main <li><a href="#CAB">Using the contextual action mode</a></li> 215e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main </ol> 225e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main </li> 235e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <li><a href="#PopupMenu">Creating a Popup Menu</a> 245e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <ol> 255e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <li><a href="#PopupEvents">Handling click events</a></li> 265e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main </ol> 275e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main </li> 285e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <li><a href="#groups">Creating Menu Groups</a> 295e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <ol> 305e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <li><a href="#checkable">Using checkable menu items</a></li> 315e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main </ol> 325e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main </li> 335e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <li><a href="#intents">Adding Menu Items Based on an Intent</a> 345e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <ol> 355e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <li><a href="#AllowingToAdd">Allowing your activity to be added to other menus</a></li> 365e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main </ol> 375e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main </li> 385e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main</ol> 39b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 40b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main <h2>Key classes</h2> 41b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main <ol> 42b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main <li>{@link android.view.Menu}</li> 43b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main <li>{@link android.view.MenuItem}</li> 44b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main <li>{@link android.view.ContextMenu}</li> 455e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <li>{@link android.view.ActionMode}</li> 46b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main </ol> 47b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 48b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main <h2>See also</h2> 49b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main <ol> 50b10b48f62d3cac684424e4181d4e8ec61f227e95Scott Main <li><a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a></li> 51b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main <li><a href="{@docRoot}guide/topics/resources/menu-resource.html">Menu Resource</a></li> 525e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <li><a 535e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainhref="http://android-developers.blogspot.com/2012/01/say-goodbye-to-menu-button.html">Say 545e0959393426371dadef2c7905d5c915a1ac2dd4Scott MainGoodbye to the Menu Button</a></li> 55b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main </ol> 569066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project</div> 579066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project</div> 589066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 595e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>Menus are a common user interface component in many types of applications. To provide a familiar 605e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainand consistent user experience, you should use the {@link android.view.Menu} APIs to present user 615e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainactions and other options in your activities.</p> 625e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 635e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>Beginning with Android 3.0 (API level 11), Android-powered devices are no longer required to 645e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainprovide a dedicated <em>Menu</em> button. With this change, Android apps should migrate away from a 655e0959393426371dadef2c7905d5c915a1ac2dd4Scott Maindependence on the traditional 6-item menu panel and instead provide an action bar to present common 665e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainuser actions.</p> 675e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 685e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>Although the design and user experience for some menu items have changed, the semantics to define 695e0959393426371dadef2c7905d5c915a1ac2dd4Scott Maina set of actions and options is still based on the {@link android.view.Menu} APIs. This 705e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainguide shows how to create the three fundamental types of menus or action presentations on all 715e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainversions of Android:</p> 729066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 739066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<dl> 745e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <dt><strong>Options menu and action bar</strong></dt> 755e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <dd>The <a href="#options-menu">options menu</a> is the primary collection of menu items for an 765e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainactivity. It's where you should place actions that have a global impact on the app, such as 775e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main"Search," "Compose email," and "Settings." 785e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <p>If you're developing for Android 2.3 or lower, users can 795e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainreveal the options menu panel by pressing the <em>Menu</em> button.</p> 805e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <p>On Android 3.0 and higher, items from the options menu are presented by the <a 815e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainhref="{@docRoot}guide/topics/ui/actionbar.html">action bar</a> as a combination of on-screen action 825e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainitems and overflow options. Beginning with Android 3.0, the <em>Menu</em> button is deprecated (some 835e0959393426371dadef2c7905d5c915a1ac2dd4Scott Maindevices 845e0959393426371dadef2c7905d5c915a1ac2dd4Scott Maindon't have one), so you should migrate toward using the action bar to provide access to actions and 855e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainother options.</p> 865e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <p>See the section about <a href="#options-menu">Creating an Options Menu</a>.</p> 875e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main </dd> 885e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 895e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <dt><strong>Context menu and contextual action mode</strong></dt> 905e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 915e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <dd>A context menu is a <a href="#FloatingContextMenu">floating menu</a> that appears when the 925e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainuser performs a long-click on an element. It provides actions that affect the selected content or 935e0959393426371dadef2c7905d5c915a1ac2dd4Scott Maincontext frame. 945e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <p>When developing for Android 3.0 and higher, you should instead use the <a 955e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainhref="#CAB">contextual action mode</a> to enable actions on selected content. This mode displays 965e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainaction items that affect the selected content in a bar at the top of the screen and allows the user 975e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainto select multiple items.</p> 985e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <p>See the section about <a href="#context-menu">Creating Contextual Menus</a>.</p> 995e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main</dd> 1005e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 1015e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <dt><strong>Popup menu</strong></dt> 1025e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <dd>A popup menu displays a list of items in a vertical list that's anchored to the view that 1035e0959393426371dadef2c7905d5c915a1ac2dd4Scott Maininvoked the menu. It's good for providing an overflow of actions that relate to specific content or 1045e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainto provide options for a second part of a command. Actions in a popup menu should 1055e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<strong>not</strong> directly affect the corresponding content—that's what contextual actions 1065e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainare for. Rather, the popup menu is for extended actions that relate to regions of content in your 1075e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainactivity. 1085e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <p>See the section about <a href="#PopupMenu">Creating a Popup Menu</a>.</p> 109b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main</dd> 1109066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project</dl> 1119066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1129066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1139066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1145e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<h2 id="xml">Defining a Menu in XML</h2> 1154fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Main 1165e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>For all menu types, Android provides a standard XML format to define menu items. 1175e0959393426371dadef2c7905d5c915a1ac2dd4Scott MainInstead of building a menu in your activity's code, you should define a menu and all its items in an 1185e0959393426371dadef2c7905d5c915a1ac2dd4Scott MainXML <a href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a>. You can then 1195e0959393426371dadef2c7905d5c915a1ac2dd4Scott Maininflate the menu resource (load it as a {@link android.view.Menu} object) in your activity or 1205e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainfragment.</p> 121b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 1225e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>Using a menu resource is a good practice for a few reasons:</p> 1235e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<ul> 1245e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <li>It's easier to visualize the menu structure in XML.</li> 1255e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <li>It separates the content for the menu from your application's behavioral code.</li> 1265e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <li>It allows you to create alternative menu configurations for different platform versions, 1275e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainscreen sizes, and other configurations by leveraging the <a 1285e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainhref="{@docRoot}guide/topics/resources/index.html">app resources</a> framework.</li> 1295e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main</ul> 130b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 1315e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>To define the menu, create an XML file inside your project's <code>res/menu/</code> 132b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Maindirectory and build the menu with the following elements:</p> 133b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main<dl> 134b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main <dt><code><menu></code></dt> 1354fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Main <dd>Defines a {@link android.view.Menu}, which is a container for menu items. A 1364fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Main<code><menu></code> element must be the root node for the file and can hold one or more 1374fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Main<code><item></code> and <code><group></code> elements.</dd> 1384fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Main 139b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main <dt><code><item></code></dt> 1404fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Main <dd>Creates a {@link android.view.MenuItem}, which represents a single item in a menu. This 1414fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Mainelement may contain a nested <code><menu></code> element in order to create a submenu.</dd> 1424fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Main 143b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main <dt><code><group></code></dt> 144b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main <dd>An optional, invisible container for {@code <item>} elements. It allows you to 1455e0959393426371dadef2c7905d5c915a1ac2dd4Scott Maincategorize menu items so they share properties such as active state and visibility. For more 1465e0959393426371dadef2c7905d5c915a1ac2dd4Scott Maininformation, see the section about <a href="#groups">Creating Menu Groups</a>.</dd> 147b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main</dl> 1489066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 1494fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Main 1504fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Main<p>Here's an example menu named <code>game_menu.xml</code>:</p> 1519066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<pre> 152b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main<?xml version="1.0" encoding="utf-8"?> 153b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main<menu xmlns:android="http://schemas.android.com/apk/res/android"> 154b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main <item android:id="@+id/new_game" 155b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main android:icon="@drawable/ic_new_game" 1565e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main android:title="@string/new_game" 1575e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main android:showAsAction="ifRoom"/> 15818439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main <item android:id="@+id/help" 15918439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main android:icon="@drawable/ic_help" 16018439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main android:title="@string/help" /> 161b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main</menu> 162b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main</pre> 163b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 1645e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>The <code><item></code> element supports several attributes you can use to define an item's 1655e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainappearance and behavior. The items in the above menu include the following attributes:</p> 1665e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 167b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main<dl> 168b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main <dt>{@code android:id}</dt> 1694fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Main <dd>A resource ID that's unique to the item, which allows the application can recognize the item 1704fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Mainwhen the user selects it.</dd> 171b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main <dt>{@code android:icon}</dt> 1724fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Main <dd>A reference to a drawable to use as the item's icon.</dd> 173b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main <dt>{@code android:title}</dt> 1744fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Main <dd>A reference to a string to use as the item's title.</dd> 1755e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <dt>{@code android:showAsAction}</dt> 1765e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <dd>Specifies when and how this item should appear as an action item in the <a 1775e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainhref="{@docRoot}guide/topics/ui/actionbar.html">action bar</a>.</dd> 178b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main</dl> 179b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 1805e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>These are the most important attributes you should use, but there are many more available. 1815e0959393426371dadef2c7905d5c915a1ac2dd4Scott MainFor information about all the supported attributes, see the <a 1825e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainhref="{@docRoot}guide/topics/resources/menu-resource.html">Menu Resource</a> document.</p> 183b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 1845e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>You can add a submenu to an item in any menu (except a submenu) by adding a {@code <menu>} 1855e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainelement as the child of an {@code <item>}. Submenus are useful when your application has a lot 1865e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainof functions that can be organized into topics, like items in a PC application's menu bar (File, 1875e0959393426371dadef2c7905d5c915a1ac2dd4Scott MainEdit, View, etc.). For example:</p> 188b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 189b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main<pre> 1905e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<?xml version="1.0" encoding="utf-8"?> 1915e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<menu xmlns:android="http://schemas.android.com/apk/res/android"> 1925e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <item android:id="@+id/file" 1935e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main android:title="@string/file" > 1945e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <!-- "file" submenu --> 1955e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <menu> 1965e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <item android:id="@+id/create_new" 1975e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main android:title="@string/create_new" /> 1985e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <item android:id="@+id/open" 1995e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main android:title="@string/open" /> 2005e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main </menu> 2015e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main </item> 2025e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main</menu> 203b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main</pre> 204b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 2055e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>To use the menu in your activity, you need to inflate the menu resource (convert the XML 2065e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainresource into a programmable object) using {@link android.view.MenuInflater#inflate(int,Menu) 2075e0959393426371dadef2c7905d5c915a1ac2dd4Scott MainMenuInflater.inflate()}. In the following sections, you'll see how to inflate a menu for each 2085e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainmenu type.</p> 209b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 210b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 211b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 212b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main<h2 id="options-menu">Creating an Options Menu</h2> 213b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 2145e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<div class="figure" style="width:200px;margin:0"> 2154fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Main <img src="{@docRoot}images/options_menu.png" height="333" alt="" /> 2165e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <p class="img-caption"><strong>Figure 1.</strong> Options menu in the 2175e0959393426371dadef2c7905d5c915a1ac2dd4Scott MainBrowser, on Android 2.3.</p> 218b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main</div> 219b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 2205e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>The options menu is where you should include actions and other options that are relevant to the 2215e0959393426371dadef2c7905d5c915a1ac2dd4Scott Maincurrent activity context, such as "Search," "Compose email," and "Settings."</p> 2225e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 2235e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>Where the items in your options menu appear on the screen depends on the version for which you've 2245e0959393426371dadef2c7905d5c915a1ac2dd4Scott Maindeveloped your application:</p> 2255e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 2265e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<ul> 2275e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <li>If you've developed your application for <strong>Android 2.3.x (API level 10) or 2285e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainlower</strong>, the contents of your options menu appear at the bottom of the screen when the user 2295e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainpresses the <em>Menu</em> button, as shown in figure 1. When opened, the first visible portion is 2305e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainthe icon 2315e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainmenu, which holds up to six menu items. If your menu includes more than six items, Android places 2325e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainthe sixth item and the rest into the overflow menu, which the user can open by selecting 2335e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<em>More</em>.</li> 2345e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 2355e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <li>If you've developed your application for <strong>Android 3.0 (API level 11) and 2365e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainhigher</strong>, items from the options menu are available in the <a 2375e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainhref="{@docRoot}guide/topics/ui/actionbar.html">action bar</a>. By default, the system 2385e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainplaces all items in the action overflow, which the user can reveal with the action overflow icon on 2395e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainthe right side of the action bar (or by pressing the device <em>Menu</em> button, if available). To 2405e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainenable 2415e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainquick access to important actions, you can promote a few items to appear in the action bar by adding 2425e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main{@code android:showAsAction="ifRoom"} to the corresponding {@code <item>} elements (see figure 2435e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main2). <p>For more information about action items and other action bar behaviors, see the <a 2445e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainhref="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> guide. </p> 2455e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p class="note"><strong>Note:</strong> Even if you're <em>not</em> developing for Android 3.0 or 2465e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainhigher, you can build your own action bar layout for a similar effect. For an example of how you can 2475e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainsupport older versions of Android with an action bar, see the <a 2485e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainhref="{@docRoot}resources/samples/ActionBarCompat/index.html">Action Bar Compatibility</a> 2495e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainsample.</p> 2505e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main</li> 2515e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main</ul> 2525e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 2535e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<img src="{@docRoot}images/ui/actionbar.png" alt="" /> 2545e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p class="img-caption"><strong>Figure 2.</strong> Action bar from the <a 2555e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainhref="{@docRoot}resources/samples/HoneycombGallery/index.html">Honeycomb Gallery</a> app, showing 2565e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainnavigation tabs and a camera action item (plus the action overflow button).</p> 2575e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 2585e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>You can declare items for the options menu from either your {@link android.app.Activity} 2595e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainsubclass or a {@link android.app.Fragment} subclass. If both your activity and fragment(s) 2605e0959393426371dadef2c7905d5c915a1ac2dd4Scott Maindeclare items for the options menu, they are combined in the UI. The activity's items appear 2615e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainfirst, followed by those of each fragment in the order in which each fragment is added to the 2625e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainactivity. If necessary, you can re-order the menu items with the {@code android:orderInCategory} 2635e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainattribute in each {@code <item>} you need to move.</p> 2645e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 2655e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>To specify the options menu for an activity, override {@link 2665e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainandroid.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} (fragments provide their 2675e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainown {@link android.app.Fragment#onCreateOptionsMenu onCreateOptionsMenu()} callback). In this 2685e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainmethod, you can inflate your menu resource (<a href="#xml">defined in XML</a>) into the {@link 2695e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainandroid.view.Menu} provided in the callback. For example:</p> 27018439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 27118439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main<pre> 27218439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main@Override 27318439bee6f8b525abe3f1fac69bc4cea184e1565Scott Mainpublic boolean onCreateOptionsMenu(Menu menu) { 2745e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main MenuInflater inflater = {@link android.app.Activity#getMenuInflater()}; 27518439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main inflater.inflate(R.menu.game_menu, menu); 27618439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main return true; 27718439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main} 27818439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main</pre> 279b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 2805e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>You can also add menu items using {@link android.view.Menu#add(int,int,int,int) 2815e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainadd()} and retrieve items with {@link android.view.Menu#findItem findItem()} to revise their 2825e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainproperties with {@link android.view.MenuItem} APIs.</p> 2834fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Main 2845e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>If you've developed your application for Android 2.3.x and lower, the system calls {@link 2855e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainandroid.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} to create the options menu 2865e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainwhen the user opens the menu for the first time. If you've developed for Android 3.0 and higher, the 2875e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainsystem calls {@link android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} when 2885e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainstarting the activity, in order to show items to the action bar.</p> 28918439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 2904fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Main 2914fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Main 2925e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<h3 id="RespondingOptionsMenu">Handling click events</h3> 2934fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Main 2945e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>When the user selects an item from the options menu (including action items in the action bar), 2955e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainthe system calls your activity's {@link android.app.Activity#onOptionsItemSelected(MenuItem) 2965e0959393426371dadef2c7905d5c915a1ac2dd4Scott MainonOptionsItemSelected()} method. This method passes the {@link android.view.MenuItem} selected. You 2975e0959393426371dadef2c7905d5c915a1ac2dd4Scott Maincan identify the item by calling {@link android.view.MenuItem#getItemId()}, which returns the unique 2985e0959393426371dadef2c7905d5c915a1ac2dd4Scott MainID for the menu item (defined by the {@code android:id} attribute in the menu resource or with an 2995e0959393426371dadef2c7905d5c915a1ac2dd4Scott Maininteger given to the {@link android.view.Menu#add(int,int,int,int) add()} method). You can match 3005e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainthis ID against known menu items to perform the appropriate action. For example:</p> 3019066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 302b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main<pre> 303b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main@Override 3049066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectpublic boolean onOptionsItemSelected(MenuItem item) { 305b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main // Handle item selection 3069066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project switch (item.getItemId()) { 3075e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main case R.id.new_game: 3085e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main newGame(); 3095e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main return true; 3105e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main case R.id.help: 3115e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main showHelp(); 3125e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main return true; 3135e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main default: 3145e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main return super.onOptionsItemSelected(item); 3159066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project } 3169066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project} 3179066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project</pre> 3189066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 3195e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>When you successfully handle a menu item, return {@code true}. If you don't handle the menu 3205e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainitem, you should call the superclass implementation of {@link 3215e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainandroid.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} (the default 3225e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainimplementation returns false).</p> 3235e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 3245e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>If your activity includes fragments, the system first calls {@link 3255e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainandroid.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} for the activity then 3265e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainfor each fragment (in the order each fragment was added) until one returns 3275e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main{@code true} or all fragments have been called.</p> 3285e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 3295e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p class="note"><strong>Tip:</strong> Android 3.0 adds the ability for you to define the on-click 3305e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainbehavior for a menu item in XML, using the {@code android:onClick} attribute. The value for the 3315e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainattribute must be the name of a method defined by the activity using the menu. The method 3325e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainmust be public and accept a single {@link android.view.MenuItem} parameter—when the system 3335e0959393426371dadef2c7905d5c915a1ac2dd4Scott Maincalls this method, it passes the menu item selected. For more information and an example, see the <a 3345e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainhref="{@docRoot}guide/topics/resources/menu-resource.html">Menu Resource</a> document.</p> 335b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 336b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main<p class="note"><strong>Tip:</strong> If your application contains multiple activities and 3375e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainsome of them provide the same options menu, consider creating 3384fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Mainan activity that implements nothing except the {@link android.app.Activity#onCreateOptionsMenu(Menu) 339b4d2e42a8508a09f944b13f27c043952eef6c1ccScott MainonCreateOptionsMenu()} and {@link android.app.Activity#onOptionsItemSelected(MenuItem) 3404fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott MainonOptionsItemSelected()} methods. Then extend this class for each activity that should share the 3415e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainsame options menu. This way, you can manage one set of code for handling menu 3425e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainactions and each descendant class inherits the menu behaviors. 3435e0959393426371dadef2c7905d5c915a1ac2dd4Scott MainIf you want to add menu items to one of the descendant activities, 344b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Mainoverride {@link android.app.Activity#onCreateOptionsMenu(Menu) 3454fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott MainonCreateOptionsMenu()} in that activity. Call {@code super.onCreateOptionsMenu(menu)} so the 346b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Mainoriginal menu items are created, then add new menu items with {@link 347b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Mainandroid.view.Menu#add(int,int,int,int) menu.add()}. You can also override the super class's 348b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Mainbehavior for individual menu items.</p> 349b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 350b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 3514fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Main<h3 id="ChangingTheMenu">Changing menu items at runtime</h3> 352b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 3535e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>After the system calls {@link android.app.Activity#onCreateOptionsMenu(Menu) 3545e0959393426371dadef2c7905d5c915a1ac2dd4Scott MainonCreateOptionsMenu()}, it retains an instance of the {@link android.view.Menu} you populate and 3555e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainwill not call {@link android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} 3565e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainagain unless the menu is invalidated for some reason. However, you should use {@link 3575e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainandroid.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} only to create the initial 3585e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainmenu state and not to make changes during the activity lifecycle.</p> 3595e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 3605e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>If you want to modify the options menu based on 3615e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainevents that occur during the activity lifecycle, you can do so in 3625e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainthe {@link android.app.Activity#onPrepareOptionsMenu(Menu) onPrepareOptionsMenu()} method. This 3635e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainmethod passes you the {@link android.view.Menu} object as it currently exists so you can modify it, 3645e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainsuch as add, remove, or disable items. (Fragments also provide an {@link 3655e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainandroid.app.Fragment#onPrepareOptionsMenu onPrepareOptionsMenu()} callback.)</p> 3665e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 3675e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>On Android 2.3.x and lower, the system calls {@link 3685e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainandroid.app.Activity#onPrepareOptionsMenu(Menu) 3695e0959393426371dadef2c7905d5c915a1ac2dd4Scott MainonPrepareOptionsMenu()} each time the user opens the options menu (presses the <em>Menu</em> 3705e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainbutton).</p> 3714fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Main 3725e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>On Android 3.0 and higher, the options menu is considered to always be open when menu items are 3735e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainpresented in the action bar. When an event occurs and you want to perform a menu update, you must 3745e0959393426371dadef2c7905d5c915a1ac2dd4Scott Maincall {@link android.app.Activity#invalidateOptionsMenu invalidateOptionsMenu()} to request that the 3755e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainsystem call {@link android.app.Activity#onPrepareOptionsMenu(Menu) onPrepareOptionsMenu()}.</p> 3764fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Main 3779066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<p class="note"><strong>Note:</strong> 3785e0959393426371dadef2c7905d5c915a1ac2dd4Scott MainYou should never change items in the options menu based on the {@link android.view.View} currently 3794fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Mainin focus. When in touch mode (when the user is not using a trackball or d-pad), views 380b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Maincannot take focus, so you should never use focus as the basis for modifying 3815e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainitems in the options menu. If you want to provide menu items that are context-sensitive to a {@link 382b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Mainandroid.view.View}, use a <a href="#context-menu">Context Menu</a>.</p> 383b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 3844fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Main 3854fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Main 386b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 3875e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<h2 id="context-menu">Creating Contextual Menus</h2> 388b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 3895e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<div class="figure" style="width:420px;margin-top:-1em"> 3905e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <img src="{@docRoot}images/ui/menu-context.png" alt="" /> 3915e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <p class="img-caption"><strong>Figure 3.</strong> Screenshots of a floating context menu (left) 3925e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainand the contextual action bar (right).</p> 3935e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main</div> 394b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 3955e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>A contextual menu offers actions that affect a specific item or context frame in the UI. You 3965e0959393426371dadef2c7905d5c915a1ac2dd4Scott Maincan provide a context menu for any view, but they are most often used for items in a {@link 3975e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainandroid.widget.ListView}, {@link android.widget.GridView}, or other view collections in which 3985e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainthe user can perform direct actions on each item.</p> 399b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 4005e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>There are two ways to provide contextual actions:</p> 4015e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<ul> 4025e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <li>In a <a href="#FloatingContextMenu">floating context menu</a>. A menu appears as a 4035e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainfloating list of menu items (similar to a dialog) when the user performs a long-click (press and 4045e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainhold) on a view that declares support for a context menu. Users can perform a contextual 4055e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainaction on one item at a time.</li> 4065e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 4075e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <li>In the <a href="#CAB">contextual action mode</a>. This mode is a system implementation of 4085e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main{@link android.view.ActionMode} that displays a <em>contextual action bar</em> at the top of the 4095e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainscreen with action items that affect the selected item(s). When this mode is active, users 4105e0959393426371dadef2c7905d5c915a1ac2dd4Scott Maincan perform an action on multiple items at once (if your app allows it).</li> 4115e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main</ul> 412b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 4135e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p class="note"><strong>Note:</strong> The contextual action mode is available on Android 3.0 (API 4145e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainlevel 11) and higher and is the preferred technique for displaying contextual actions when 4155e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainavailable. If your app supports versions lower than 3.0 then you should fall back to a floating 4165e0959393426371dadef2c7905d5c915a1ac2dd4Scott Maincontext menu on those devices.</p> 417b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 418b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 4195e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<h3 id="FloatingContextMenu">Creating a floating context menu</h3> 420b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 4215e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>To provide a floating context menu:</p> 4225e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<ol> 4235e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <li>Register the {@link android.view.View} to which the context menu should be associated by 4245e0959393426371dadef2c7905d5c915a1ac2dd4Scott Maincalling {@link android.app.Activity#registerForContextMenu(View) registerForContextMenu()} and pass 4255e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainit the {@link android.view.View}. 4265e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <p>If your activity uses a {@link android.widget.ListView} or {@link android.widget.GridView} and 4275e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainyou want each item to provide the same context menu, register all items for a context menu by 4285e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainpassing the {@link android.widget.ListView} or {@link android.widget.GridView} to {@link 4295e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainandroid.app.Activity#registerForContextMenu(View) registerForContextMenu()}.</p> 4305e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main</li> 4315e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 4325e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <li>Implement the {@link 4335e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainandroid.view.View.OnCreateContextMenuListener#onCreateContextMenu onCreateContextMenu()} method 4345e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainin your {@link android.app.Activity} or {@link android.app.Fragment}. 4355e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <p>When the registered view receives a long-click event, the system calls your {@link 4365e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainandroid.view.View.OnCreateContextMenuListener#onCreateContextMenu onCreateContextMenu()} 4375e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainmethod. This is where you define the menu items, usually by inflating a menu resource. For 4385e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainexample:</p> 4399066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<pre> 440b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main@Override 4419066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectpublic void onCreateContextMenu(ContextMenu menu, View v, 4429066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project ContextMenuInfo menuInfo) { 4435e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main super.onCreateContextMenu(menu, v, menuInfo); 4445e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main MenuInflater inflater = getMenuInflater(); 4455e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main inflater.inflate(R.menu.context_menu, menu); 4469066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project} 447b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main</pre> 448b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 4495e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>{@link android.view.MenuInflater} allows you to inflate the context menu from a <a 4505e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainhref="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a>. The callback method 451b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Mainparameters include the {@link android.view.View} 452b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Mainthat the user selected and a {@link android.view.ContextMenu.ContextMenuInfo} object that provides 4535e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainadditional information about the item selected. If your activity has several views that each provide 4545e0959393426371dadef2c7905d5c915a1ac2dd4Scott Maina different context menu, you might use these parameters to determine which context menu to 4555e0959393426371dadef2c7905d5c915a1ac2dd4Scott Maininflate.</p> 4565e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main</li> 457b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 4585e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<li>Implement {@link android.app.Activity#onContextItemSelected(MenuItem) 4595e0959393426371dadef2c7905d5c915a1ac2dd4Scott MainonContextItemSelected()}. 4605e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <p>When the user selects a menu item, the system calls this method so you can perform the 4615e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainappropriate action. For example:</p> 4629066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 463b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main<pre> 464b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main@Override 4659066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectpublic boolean onContextItemSelected(MenuItem item) { 4665e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main AdapterContextMenuInfo info = (AdapterContextMenuInfo) item.getMenuInfo(); 4675e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main switch (item.getItemId()) { 4685e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main case R.id.edit: 4695e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main editNote(info.id); 4705e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main return true; 4715e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main case R.id.delete: 4725e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main deleteNote(info.id); 4735e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main return true; 4745e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main default: 4755e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main return super.onContextItemSelected(item); 4765e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main } 4779066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project} 4789066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project</pre> 4799066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 4805e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>The {@link android.view.MenuItem#getItemId()} method queries the ID for 4815e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainthe selected menu item, which you should assign to each menu item in XML using the {@code 4825e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainandroid:id} attribute, as shown in the section about <a href="#xml">Defining a Menu in 4835e0959393426371dadef2c7905d5c915a1ac2dd4Scott MainXML</a>.</p> 4845e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 4855e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>When you successfully handle a menu item, return {@code true}. If you don't handle the menu item, 4865e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainyou should pass the menu item to the superclass implementation. If your activity includes fragments, 4875e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainthe activity receives this callback first. By calling the superclass when unhandled, the system 4885e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainpasses the event to the respective callback method in each fragment, one at a time (in the order 4895e0959393426371dadef2c7905d5c915a1ac2dd4Scott Maineach fragment was added) until {@code true} or {@code false} is returned. (The default 4905e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainimplementation for {@link android.app.Activity} and {@code android.app.Fragment} return {@code 4915e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainfalse}, so you should always call the superclass when unhandled.)</p> 4925e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main</li> 4935e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main</ol> 4945e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 4955e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 4965e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<h3 id="CAB">Using the contextual action mode</h3> 4979066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 4985e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>The contextual action mode is a system implementation of {@link android.view.ActionMode} that 4995e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainfocuses user interaction toward performing contextual actions. When a 5005e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainuser enables this mode by selecting an item, a <em>contextual action bar</em> appears at the top of 5015e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainthe screen to present actions the user can perform on the currently selected item(s). While this 5025e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainmode is enabled, the user can select multiple items (if you allow it), deselect items, and continue 5035e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainto navigate within the activity (as much as you're willing to allow). The action mode is disabled 5045e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainand the contextual action bar disappears when the user deselects all items, presses the BACK button, 5055e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainor selects the <em>Done</em> action on the left side of the bar.</p> 5069066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 5075e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p class="note"><strong>Note:</strong> The contextual action bar is not necessarily 5085e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainassociated with the <a href="{@docRoot}guide/topics/ui/actionbar.html">action bar</a>. They operate 5095e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainindependently, even though the contextual action bar visually overtakes the action bar 5105e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainposition.</p> 5119066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 5125e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>If you're developing for Android 3.0 (API level 11) or higher, you 5135e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainshould usually use the contextual action mode to present contextual actions, instead of the <a 5145e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainhref="#FloatingContextMenu">floating context menu</a>.</p> 5159066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 5165e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>For views that provide contextual actions, you should usually invoke the contextual action mode 5175e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainupon one of two events (or both):</p> 5185e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<ul> 5195e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <li>The user performs a long-click on the view.</li> 5205e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <li>The user selects a checkbox or similar UI component within the view.</li> 5215e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main</ul> 5225e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 5235e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>How your application invokes the contextual action mode and defines the behavior for each 5245e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainaction depends on your design. There are basically two designs:</p> 5255e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<ul> 5265e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <li>For contextual actions on individual, arbitrary views.</li> 5275e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <li>For batch contextual actions on groups of items in a {@link 5285e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainandroid.widget.ListView} or {@link android.widget.GridView} (allowing the user to select multiple 5295e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainitems and perform an action on them all).</li> 5305e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main</ul> 5319066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 5325e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>The following sections describe the setup required for each scenario.</p> 5339066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 5349066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 5355e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<h4 id="CABforViews">Enabling the contextual action mode for individual views</h4> 5369066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 5375e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>If you want to invoke the contextual action mode only when the user selects specific 5385e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainviews, you should:</p> 5395e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<ol> 5405e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <li>Implement the {@link android.view.ActionMode.Callback} interface. In its callback methods, you 5415e0959393426371dadef2c7905d5c915a1ac2dd4Scott Maincan specify the actions for the contextual action bar, respond to click events on action items, and 5425e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainhandle other lifecycle events for the action mode.</li> 5435e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <li>Call {@link android.app.Activity#startActionMode startActionMode()} when you want to show the 5445e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainbar (such as when the user long-clicks the view).</li> 5455e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main</ol> 5465e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 5475e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>For example:</p> 5485e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 5495e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<ol> 5505e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <li>Implement the {@link android.view.ActionMode.Callback ActionMode.Callback} interface: 5519066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<pre> 5525e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainprivate ActionMode.Callback mActionModeCallback = new ActionMode.Callback() { 5535e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 5545e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main // Called when the action mode is created; startActionMode() was called 5555e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main @Override 5565e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main public boolean onCreateActionMode(ActionMode mode, Menu menu) { 5575e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main // Inflate a menu resource providing context menu items 5585e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main MenuInflater inflater = mode.getMenuInflater(); 5595e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main inflater.inflate(R.menu.context_menu, menu); 5605e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main return true; 5615e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main } 5625e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 5635e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main // Called each time the action mode is shown. Always called after onCreateActionMode, but 5645e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main // may be called multiple times if the mode is invalidated. 5655e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main @Override 5665e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main public boolean onPrepareActionMode(ActionMode mode, Menu menu) { 5675e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main return false; // Return false if nothing is done 5685e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main } 5695e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 5705e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main // Called when the user selects a contextual menu item 5715e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main @Override 5725e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main public boolean onActionItemClicked(ActionMode mode, MenuItem item) { 5735e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main switch (item.getItemId()) { 5745e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main case R.id.menu_share: 5755e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main shareCurrentItem(); 5765e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main mode.finish(); // Action picked, so close the CAB 5775e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main return true; 5785e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main default: 5795e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main return false; 5805e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main } 5815e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main } 5825e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 5835e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main // Called when the user exits the action mode 5845e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main @Override 5855e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main public void onDestroyActionMode(ActionMode mode) { 5865e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main mActionMode = null; 5875e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main } 5885e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main}; 5895e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main</pre> 5905e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 5915e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>Notice that these event callbacks are almost exactly the same as the callbacks for the <a 5925e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainhref="#options-menu">options menu</a>, except each of these also pass the {@link 5935e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainandroid.view.ActionMode} object associated with the event. You can use {@link 5945e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainandroid.view.ActionMode} APIs to make various changes to the CAB, such as revise the title and 5955e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainsubtitle with {@link android.view.ActionMode#setTitle setTitle()} and {@link 5965e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainandroid.view.ActionMode#setSubtitle setSubtitle()} (useful to indicate how many items are 5975e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainselected).</p> 5985e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 5995e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>Also notice that the above sample sets the {@code mActionMode} variable null when the 6005e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainaction mode is destroyed. In the next step, you'll see how it's initialized and how saving 6015e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainthe member variable in your activity or fragment can be useful.</p> 6025e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main</li> 6035e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 6045e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <li>Call {@link android.app.Activity#startActionMode startActionMode()} to enable the contextual 6055e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainaction mode when appropriate, such as in response to a long-click on a {@link 6065e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainandroid.view.View}:</p> 6075e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 6085e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<pre> 6095e0959393426371dadef2c7905d5c915a1ac2dd4Scott MainsomeView.setOnLongClickListener(new View.OnLongClickListener() { 6105e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main // Called when the user long-clicks on someView 6115e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main public boolean onLongClick(View view) { 6125e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main if (mActionMode != null) { 6135e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main return false; 6145e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main } 6155e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 6165e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main // Start the CAB using the ActionMode.Callback defined above 6175e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main mActionMode = getActivity().startActionMode(mActionModeCallback); 6185e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main view.setSelected(true); 6195e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main return true; 6205e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main } 6215e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main}); 6225e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main</pre> 6235e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 6245e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>When you call {@link android.app.Activity#startActionMode startActionMode()}, the system returns 6255e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainthe {@link android.view.ActionMode} created. By saving this in a member variable, you can 6265e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainmake changes to the contextual action bar in response to other events. In the above sample, the 6275e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main{@link android.view.ActionMode} is used to ensure that the {@link android.view.ActionMode} instance 6285e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainis not recreated if it's already active, by checking whether the member is null before starting the 6295e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainaction mode.</p> 6305e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main</li> 6315e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main</ol> 6325e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 6335e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 6345e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 6355e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<h4 id="CABforListView">Enabling batch contextual actions in a ListView or GridView</h4> 6365e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 6375e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>If you have a collection of items in a {@link android.widget.ListView} or {@link 6385e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainandroid.widget.GridView} (or another extension of {@link android.widget.AbsListView}) and want to 6395e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainallow users to perform batch actions, you should:</p> 6405e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 6415e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<ul> 6425e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <li>Implement the {@link android.widget.AbsListView.MultiChoiceModeListener} interface and set it 6435e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainfor the view group with {@link android.widget.AbsListView#setMultiChoiceModeListener 6445e0959393426371dadef2c7905d5c915a1ac2dd4Scott MainsetMultiChoiceModeListener()}. In the listener's callback methods, you can specify the actions 6455e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainfor the contextual action bar, respond to click events on action items, and handle other callbacks 6465e0959393426371dadef2c7905d5c915a1ac2dd4Scott Maininherited from the {@link android.view.ActionMode.Callback} interface.</li> 6475e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 6485e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <li>Call {@link android.widget.AbsListView#setChoiceMode setChoiceMode()} with the {@link 6495e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainandroid.widget.AbsListView#CHOICE_MODE_MULTIPLE_MODAL} argument.</li> 6505e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main</ul> 6515e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 6525e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>For example:</p> 6535e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 6545e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<pre> 6555e0959393426371dadef2c7905d5c915a1ac2dd4Scott MainListView listView = getListView(); 6565e0959393426371dadef2c7905d5c915a1ac2dd4Scott MainlistView.setChoiceMode(ListView.CHOICE_MODE_MULTIPLE_MODAL); 6575e0959393426371dadef2c7905d5c915a1ac2dd4Scott MainlistView.setMultiChoiceModeListener(new MultiChoiceModeListener() { 6585e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 6595e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main @Override 6605e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main public void onItemCheckedStateChanged(ActionMode mode, int position, 6615e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main long id, boolean checked) { 6625e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main // Here you can do something when items are selected/de-selected, 6635e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main // such as update the title in the CAB 6645e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main } 6655e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 6665e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main @Override 6675e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main public boolean onActionItemClicked(ActionMode mode, MenuItem item) { 6685e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main // Respond to clicks on the actions in the CAB 6695e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main switch (item.getItemId()) { 6705e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main case R.id.menu_delete: 6715e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main deleteSelectedItems(); 6725e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main mode.finish(); // Action picked, so close the CAB 6735e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main return true; 6745e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main default: 6755e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main return false; 6765e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main } 6775e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main } 6785e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 6795e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main @Override 6805e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main public boolean onCreateActionMode(ActionMode mode, Menu menu) { 6815e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main // Inflate the menu for the CAB 6825e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main MenuInflater inflater = mode.getMenuInflater(); 6835e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main inflater.inflate(R.menu.context, menu); 6845e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main return true; 6855e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main } 6865e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 6875e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main @Override 6885e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main public void onDestroyActionMode(ActionMode mode) { 6895e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main // Here you can make any necessary updates to the activity when 6905e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main // the CAB is removed. By default, selected items are deselected/unchecked. 6915e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main } 6925e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 6935e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main @Override 6945e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main public boolean onPrepareActionMode(ActionMode mode, Menu menu) { 6955e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main // Here you can perform updates to the CAB due to 6965e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main // an {@link android.view.ActionMode#invalidate} request 6975e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main return false; 6985e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main } 6995e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main}); 7005e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main</pre> 7015e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 7025e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>That's it. Now when the user selects an item with a long-click, the system calls the {@link 7035e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainandroid.widget.AbsListView.MultiChoiceModeListener#onCreateActionMode onCreateActionMode()} 7045e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainmethod and displays the contextual action bar with the specified actions. While the contextual 7055e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainaction bar is visible, users can select additional items.</p> 7065e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 7075e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>In some cases in which the contextual actions provide common action items, you might 7085e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainwant to add a checkbox or a similar UI element that allows users to select items, because they 7095e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainmight not discover the long-click behavior. When a user selects the checkbox, you 7105e0959393426371dadef2c7905d5c915a1ac2dd4Scott Maincan invoke the contextual action mode by setting the respective list item to the checked 7115e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainstate with {@link android.widget.AbsListView#setItemChecked setItemChecked()}.</p> 7125e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 7135e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 7145e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 7155e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 7165e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<h2 id="PopupMenu">Creating a Popup Menu</h2> 7175e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 7185e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<div class="figure" style="width:220px"> 7195e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<img src="{@docRoot}images/ui/popupmenu.png" alt="" /> 7205e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p><strong>Figure 4.</strong> A popup menu in the Gmail app, anchored to the overflow 7215e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainbutton at the top-right.</p> 7225e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main</div> 7235e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 7245e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>A {@link android.widget.PopupMenu} is a modal menu anchored to a {@link android.view.View}. 7255e0959393426371dadef2c7905d5c915a1ac2dd4Scott MainIt appears below the anchor view if there is room, or above the view otherwise. It's useful for:</p> 7265e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<ul> 7275e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <li>Providing an overflow-style menu for actions that <em>relate to</em> specific content (such as 7285e0959393426371dadef2c7905d5c915a1ac2dd4Scott MainGmail's email headers, shown in figure 4). 7295e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <p class="note"><strong>Note:</strong> This is not the same as a context menu, which is 7305e0959393426371dadef2c7905d5c915a1ac2dd4Scott Maingenerally for actions that <em>affect</em> selected content. For actions that affect selected 7315e0959393426371dadef2c7905d5c915a1ac2dd4Scott Maincontent, use the <a href="#CAB">contextual action mode</a> or <a 7325e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainhref="#FloatingContextMenu">floating context menu</a>.</p></li> 7335e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <li>Providing a second part of a command sentence (such as a button marked "Add" 7345e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainthat produces a popup menu with different "Add" options).</li> 7355e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <li>Providing a drop-down similar to {@link android.widget.Spinner} that does not retain 7365e0959393426371dadef2c7905d5c915a1ac2dd4Scott Maina persistent selection.</li> 7375e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main</ul> 7385e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 7395e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 7405e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p class="note"><strong>Note:</strong> {@link android.widget.PopupMenu} is available with API 7415e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainlevel 11 and higher.</p> 7425e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 7435e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>If you <a href="#xml">define your menu in XML</a>, here's how you can show the popup menu:</p> 7445e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<ol> 7455e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <li>Instantate a {@link android.widget.PopupMenu} with its constructor, which takes the 7465e0959393426371dadef2c7905d5c915a1ac2dd4Scott Maincurrent application {@link android.content.Context} and the {@link android.view.View} to which the 7475e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainmenu should be anchored.</li> 7485e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <li>Use {@link android.view.MenuInflater} to inflate your menu resource into the {@link 7495e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainandroid.view.Menu} object returned by {@link 7505e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainandroid.widget.PopupMenu#getMenu() PopupMenu.getMenu()}. On API level 14 and above, you can use 7515e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main{@link android.widget.PopupMenu#inflate PopupMenu.inflate()} instead.</li> 7525e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <li>Call {@link android.widget.PopupMenu#show() PopupMenu.show()}.</li> 7535e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main</ol> 7545e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 7555e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>For example, here's a button with the {@link android.R.attr#onClick android:onClick} attribute 7565e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainthat shows a popup menu:</p> 7575e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 7585e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<pre> 7595e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<ImageButton 7605e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main android:layout_width="wrap_content" 7615e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main android:layout_height="wrap_content" 7625e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main android:src="@drawable/ic_overflow_holo_dark" 7635e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main android:contentDescription="@string/descr_overflow_button" 7645e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main android:onClick="showPopup" /> 7655e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main</pre> 7665e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 7675e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>The activity can then show the popup menu like this:</p> 7685e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 7695e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<pre> 7705e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainpublic void showPopup(View v) { 7715e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main PopupMenu popup = new PopupMenu(this, v); 7725e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main MenuInflater inflater = popup.getMenuInflater(); 7735e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main inflater.inflate(R.menu.actions, popup.getMenu()); 7745e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main popup.show(); 7755e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main} 7769066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project</pre> 7779066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 7785e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>In API level 14 and higher, you can combine the two lines that inflate the menu with {@link 7795e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainandroid.widget.PopupMenu#inflate PopupMenu.inflate()}.</p> 7805e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 7815e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>The menu is dismissed when the user selects an item or touches outside the menu 7825e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainarea. You can listen for the dismiss event using {@link 7835e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainandroid.widget.PopupMenu.OnDismissListener}.</p> 7845e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 7855e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<h3 id="PopupEvents">Handling click events</h3> 7869066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 7875e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>To perform an 7885e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainaction when the user selects a menu item, you must implement the {@link 7895e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainandroid.widget.PopupMenu.OnMenuItemClickListener} interface and register it with your {@link 7905e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainandroid.widget.PopupMenu} by calling {@link android.widget.PopupMenu#setOnMenuItemClickListener 7915e0959393426371dadef2c7905d5c915a1ac2dd4Scott MainsetOnMenuItemclickListener()}. When the user selects an item, the system calls the {@link 7925e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainandroid.widget.PopupMenu.OnMenuItemClickListener#onMenuItemClick onMenuItemClick()} callback in 7935e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainyour interface.</p> 7949066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 7955e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>For example:</p> 7969066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 7975e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<pre> 7985e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainpublic void showMenu(View v) { 7995e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main PopupMenu popup = new PopupMenu(this, v); 8009066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 8015e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main // This activity implements OnMenuItemClickListener 8025e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main popup.setOnMenuItemClickListener(this); 8035e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main popup.inflate(R.menu.actions); 8045e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main popup.show(); 8055e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main} 8065e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 8075e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main@Override 8085e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainpublic boolean onMenuItemClick(MenuItem item) { 8095e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main switch (item.getItemId()) { 8105e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main case R.id.archive: 8115e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main archive(item); 8125e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main return true; 8135e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main case R.id.delete: 8145e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main delete(item); 8155e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main return true; 8165e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main default: 8175e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main return false; 8185e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main } 8195e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main} 8205e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main</pre> 821b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 8229066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 8235e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<h2 id="groups">Creating Menu Groups</h2> 824b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 825b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main<p>A menu group is a collection of menu items that share certain traits. With a group, you 826b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Maincan:</p> 827b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main<ul> 828b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main <li>Show or hide all items with {@link android.view.Menu#setGroupVisible(int,boolean) 829b4d2e42a8508a09f944b13f27c043952eef6c1ccScott MainsetGroupVisible()}</li> 830b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main <li>Enable or disable all items with {@link android.view.Menu#setGroupEnabled(int,boolean) 831b4d2e42a8508a09f944b13f27c043952eef6c1ccScott MainsetGroupEnabled()}</li> 832b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main <li>Specify whether all items are checkable with {@link 833b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Mainandroid.view.Menu#setGroupCheckable(int,boolean,boolean) setGroupCheckable()}</li> 834b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main</ul> 835b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 836b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main<p>You can create a group by nesting {@code <item>} elements inside a {@code <group>} 83776dfc02135abae5337b48fe99a1b8c0a7d95e33akmccormickelement in your menu resource or by specifying a group ID with the {@link 838b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Mainandroid.view.Menu#add(int,int,int,int) add()} method.</p> 839b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 840b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main<p>Here's an example menu resource that includes a group:</p> 841b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 842b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main<pre> 843b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main<?xml version="1.0" encoding="utf-8"?> 844b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main<menu xmlns:android="http://schemas.android.com/apk/res/android"> 8455e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <item android:id="@+id/menu_save" 8465e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main android:icon="@drawable/menu_save" 8475e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main android:title="@string/menu_save" /> 848b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main <!-- menu group --> 8495e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <group android:id="@+id/group_delete"> 8505e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <item android:id="@+id/menu_archive" 8515e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main android:title="@string/menu_archive" /> 8525e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <item android:id="@+id/menu_delete" 8535e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main android:title="@string/menu_delete" /> 854b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main </group> 855b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main</menu> 856b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main</pre> 857b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 8585e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p>The items that are in the group appear at the same level as the first item—all three items 8595e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainin the menu are siblings. However, you can modify the traits of the two 8605e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainitems in the group by referencing the group ID and using the methods listed above. The system 8615e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainwill also never separate grouped items. For example, if you declare {@code 8625e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainandroid:showAsAction="ifRoom"} for each item, they will either both appear in the action 8635e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainbar or both appear in the action overflow.</p> 864b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 8659066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 8665e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<h3 id="checkable">Using checkable menu items</h3> 8679066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 868b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main<div class="figure" style="width:200px"> 8694fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Main <img src="{@docRoot}images/radio_buttons.png" height="333" alt="" /> 8705e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main <p class="img-caption"><strong>Figure 5.</strong> Screenshot of a submenu with checkable 8714fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Mainitems.</p> 872b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main</div> 873b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 874b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main<p>A menu can be useful as an interface for turning options on and off, using a checkbox for 875b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Mainstand-alone options, or radio buttons for groups of 8765e0959393426371dadef2c7905d5c915a1ac2dd4Scott Mainmutually exclusive options. Figure 5 shows a submenu with items that are checkable with radio 877b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Mainbuttons.</p> 878b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 8795e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<p class="note"><strong>Note:</strong> Menu items in the Icon Menu (from the options menu) cannot 8809066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectdisplay a checkbox or radio button. If you choose to make items in the Icon Menu checkable, 881b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Mainyou must manually indicate the checked state by swapping the icon and/or text 882b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Maineach time the state changes.</p> 883b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 884b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main<p>You can define the checkable behavior for individual menu items using the {@code 885b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Mainandroid:checkable} attribute in the {@code <item>} element, or for an entire group with 886b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Mainthe {@code android:checkableBehavior} attribute in the {@code <group>} element. For 887b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Mainexample, all items in this menu group are checkable with a radio button:</p> 8889066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 8899066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<pre> 890b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main<?xml version="1.0" encoding="utf-8"?> 891b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main<menu xmlns:android="http://schemas.android.com/apk/res/android"> 892b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main <group android:checkableBehavior="single"> 893b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main <item android:id="@+id/red" 894b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main android:title="@string/red" /> 895b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main <item android:id="@+id/blue" 896b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main android:title="@string/blue" /> 897b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main </group> 898b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main</menu> 8999066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project</pre> 900b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 901b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main<p>The {@code android:checkableBehavior} attribute accepts either: 902b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main<dl> 903b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main <dt>{@code single}</dt> 904b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main <dd>Only one item from the group can be checked (radio buttons)</dd> 905b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main <dt>{@code all}</dt> 906b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main <dd>All items can be checked (checkboxes)</dd> 907b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main <dt>{@code none}</dt> 908b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main <dd>No items are checkable</dd> 909b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main</dl> 910b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 911b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main<p>You can apply a default checked state to an item using the {@code android:checked} attribute in 912b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Mainthe {@code <item>} element and change it in code with the {@link 913b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Mainandroid.view.MenuItem#setChecked(boolean) setChecked()} method.</p> 914b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 915b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main<p>When a checkable item is selected, the system calls your respective item-selected callback method 916b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main(such as {@link android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()}). It 917b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Mainis here that you must set the state of the checkbox, because a checkbox or radio button does not 918b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Mainchange its state automatically. You can query the current state of the item (as it was before the 919b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Mainuser selected it) with {@link android.view.MenuItem#isChecked()} and then set the checked state with 920b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main{@link android.view.MenuItem#setChecked(boolean) setChecked()}. For example:</p> 921b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 9229066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<pre> 923b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main@Override 924b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Mainpublic boolean onOptionsItemSelected(MenuItem item) { 9255e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main switch (item.getItemId()) { 9265e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main case R.id.vibrate: 9275e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main case R.id.dont_vibrate: 9285e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main if (item.isChecked()) item.setChecked(false); 9295e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main else item.setChecked(true); 9305e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main return true; 9315e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main default: 9325e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main return super.onOptionsItemSelected(item); 9335e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main } 9349066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project} 9359066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project</pre> 9369066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 937b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main<p>If you don't set the checked state this way, then the visible state of the item (the checkbox or 938b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Mainradio button) will not 9394fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Mainchange when the user selects it. When you do set the state, the activity preserves the checked state 940b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Mainof the item so that when the user opens the menu later, the checked state that you 941b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Mainset is visible.</p> 9429066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 9439066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<p class="note"><strong>Note:</strong> 944b4d2e42a8508a09f944b13f27c043952eef6c1ccScott MainCheckable menu items are intended to be used only on a per-session basis and not saved after the 945b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Mainapplication is destroyed. If you have application settings that you would like to save for the user, 946b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Mainyou should store the data using <a 947369c1c1fa22802b6504c5cde533d797841700a66Scott Mainhref="{@docRoot}guide/topics/data/data-storage.html#pref">Shared Preferences</a>.</p> 9489066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 9499066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 950b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 9515e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<h2 id="intents">Adding Menu Items Based on an Intent</h2> 952b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 9534fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Main<p>Sometimes you'll want a menu item to launch an activity using an {@link android.content.Intent} 9544fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Main(whether it's an activity in your application or another application). When you know the intent you 9554fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Mainwant to use and have a specific menu item that should initiate the intent, you can execute the 9564fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Mainintent with {@link android.app.Activity#startActivity(Intent) startActivity()} during the 9574fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Mainappropriate on-item-selected callback method (such as the {@link 9584fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Mainandroid.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} callback).</p> 959b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 9604fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Main<p>However, if you are not certain that the user's device 9614fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Maincontains an application that handles the intent, then adding a menu item that invokes it can result 9624fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Mainin a non-functioning menu item, because the intent might not resolve to an 9634fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Mainactivity. To solve this, Android lets you dynamically add menu items to your menu 9644fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Mainwhen Android finds activities on the device that handle your intent.</p> 965b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 9664fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Main<p>To add menu items based on available activities that accept an intent:</p> 967b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main<ol> 968b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main <li>Define an 9694fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Mainintent with the category {@link android.content.Intent#CATEGORY_ALTERNATIVE} and/or 970b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main{@link android.content.Intent#CATEGORY_SELECTED_ALTERNATIVE}, plus any other requirements.</li> 971b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main <li>Call {@link 972b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Mainandroid.view.Menu#addIntentOptions(int,int,int,ComponentName,Intent[],Intent,int,MenuItem[]) 9734fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott MainMenu.addIntentOptions()}. Android then searches for any applications that can perform the intent 974b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Mainand adds them to your menu.</li> 975b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main</ol> 976b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 977b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main<p>If there are no applications installed 9784fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Mainthat satisfy the intent, then no menu items are added.</p> 9799066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 9809066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<p class="note"><strong>Note:</strong> 981b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main{@link android.content.Intent#CATEGORY_SELECTED_ALTERNATIVE} is used to handle the currently 982b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Mainselected element on the screen. So, it should only be used when creating a Menu in {@link 983b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Mainandroid.app.Activity#onCreateContextMenu(ContextMenu,View,ContextMenuInfo) 984b4d2e42a8508a09f944b13f27c043952eef6c1ccScott MainonCreateContextMenu()}.</p> 9859066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 986b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main<p>For example:</p> 9879066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 9889066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<pre> 989b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main@Override 9909066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Projectpublic boolean onCreateOptionsMenu(Menu menu){ 9919066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project super.onCreateOptionsMenu(menu); 9929066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 9939066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project // Create an Intent that describes the requirements to fulfill, to be included 994b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main // in our menu. The offering app must include a category value of Intent.CATEGORY_ALTERNATIVE. 995b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main Intent intent = new Intent(null, dataUri); 9969066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project intent.addCategory(Intent.CATEGORY_ALTERNATIVE); 997b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 998b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main // Search and populate the menu with acceptable offering applications. 9999066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project menu.addIntentOptions( 1000b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main R.id.intent_group, // Menu group to which new items will be added 10019066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 0, // Unique item ID (none) 10029066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 0, // Order for the items (none) 10034fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Main this.getComponentName(), // The current activity name 10049066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project null, // Specific items to place first (none) 10059066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project intent, // Intent created above that describes our requirements 10069066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 0, // Additional flags to control items (none) 10077f877069274c94b373478a8d0c969c9cfd93864fElliott Hughes null); // Array of MenuItems that correlate to specific items (none) 10089066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 10099066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project return true; 10109066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project}</pre> 10119066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 10124fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Main<p>For each activity found that provides an intent filter matching the intent defined, a menu 10134fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Mainitem is added, using the value in the intent filter's <code>android:label</code> as the 1014b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Mainmenu item title and the application icon as the menu item icon. The 1015b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main{@link android.view.Menu#addIntentOptions(int,int,int,ComponentName,Intent[],Intent,int,MenuItem[]) 1016b4d2e42a8508a09f944b13f27c043952eef6c1ccScott MainaddIntentOptions()} method returns the number of menu items added.</p> 1017b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 1018b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main<p class="note"><strong>Note:</strong> When you call {@link 1019b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Mainandroid.view.Menu#addIntentOptions(int,int,int,ComponentName,Intent[],Intent,int,MenuItem[]) 1020b4d2e42a8508a09f944b13f27c043952eef6c1ccScott MainaddIntentOptions()}, it overrides any and all menu items by the menu group specified in the first 1021b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Mainargument.</p> 1022b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 1023b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 10245e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<h3 id="AllowingToAdd">Allowing your activity to be added to other menus</h3> 1025b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 10264fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Main<p>You can also offer the services of your activity to other applications, so your 1027b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Mainapplication can be included in the menu of others (reverse the roles described above).</p> 1028b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 10294fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Main<p>To be included in other application menus, you need to define an intent 1030b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Mainfilter as usual, but be sure to include the {@link android.content.Intent#CATEGORY_ALTERNATIVE} 10314fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Mainand/or {@link android.content.Intent#CATEGORY_SELECTED_ALTERNATIVE} values for the intent filter 1032b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Maincategory. For example:</p> 10339066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<pre> 10345e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main<intent-filter label="@string/resize_image"> 10359066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project ... 10369066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <category android:name="android.intent.category.ALTERNATIVE" /> 10379066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project <category android:name="android.intent.category.SELECTED_ALTERNATIVE" /> 10389066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project ... 10399066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project</intent-filter> 10409066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project</pre> 1041b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main 10424fe3e53e854b0056b774bfe25e3d1a2d4841aa32Scott Main<p>Read more about writing intent filters in the 104350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<a href="/guide/components/intents-filters.html">Intents and Intent Filters</a> document.</p> 10449066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project 10459066cfe9886ac131c34d59ed0e2d287b0e3c0087The Android Open Source Project<p>For a sample application using this technique, see the 1046b4d2e42a8508a09f944b13f27c043952eef6c1ccScott Main<a href="{@docRoot}resources/samples/NotePad/src/com/example/android/notepad/NoteEditor.html">Note 1047b4d2e42a8508a09f944b13f27c043952eef6c1ccScott MainPad</a> sample code.</p> 1048