docs/html/guide/topics/ui/menus.jd

page.title=Creating Menus
parent.title=User Interface
parent.link=index.html
@jd:body

<div id="qv-wrapper">
<div id="qv">
  <h2>In this document</h2>
  <ol>
    <li><a href="#xml">Defining Menus</a></li>
    <li><a href="#Inflating">Inflating a Menu Resource</a>
    <li><a href="#options-menu">Creating an Options Menu</a>
      <ol>
        <li><a href="#ChangingTheMenu">Changing the menu when it opens</a></li>
      </ol>
    </li>
    <li><a href="#context-menu">Creating a Context Menu</a></li>
    <li><a href="#submenu">Creating a Submenu</a></li>
    <li><a href="#features">Other Menu Features</a>
      <ol>
        <li><a href="#groups">Menu groups</a></li>
        <li><a href="#checkable">Checkable menu items</a></li>
        <li><a href="#shortcuts">Shortcut keys</a></li>
        <li><a href="#intents">Intents for menu items</a></li>
      </ol>
    </li>
  </ol>

  <h2>Key classes</h2>
  <ol>
    <li>{@link android.view.Menu}</li>
    <li>{@link android.view.MenuItem}</li>
    <li>{@link android.view.ContextMenu}</li>
    <li>{@link android.view.SubMenu}</li>
  </ol>

  <h2>See also</h2>
  <ol>
    <li><a href="{@docRoot}guide/topics/resources/menu-resource.html">Menu Resource</a></li>
  </ol>
</div>
</div>

<p>Menus are an important part of an application that provide a familiar interface for the user
to access application functions and settings. Android offers an easy programming interface
for you to provide application menus in your application.</p>

<p>Android provides three types of application menus:</p>
<dl>
  <dt><strong>Options Menu</strong></dt>
    <dd>The primary menu for an Activity, which appears when the user presses
    the device MENU key. Within the Options Menu are two groups:
      <dl style="margin-top:1em">
        <dt><em>Icon Menu</em></dt>
          <dd>The menu items visible at the bottom of the screen
          at the press of the MENU key. It supports a maximum of six menu items.
          These are the only menu items that support icons and the only menu items that <em>do not</em> support
          checkboxes or radio buttons.</dd>
        <dt><em>Expanded Menu</em></dt>
          <dd>The vertical list of menu items exposed by the "More" menu item in the Icon Menu.
          When the Icon Menu is full, the expanded menu is comprised of the sixth
          menu item and the rest.</dd>
      </dl>
    </dd>
  <dt><strong>Context Menu</strong></dt>
    <dd>A floating list of menu items that appears when the user performs a long-press on a View.
</dd>
  <dt><strong>Submenu</strong></dt>
    <dd>A floating list of menu items that the user opens by pressing a menu item in the Options
Menu or a context menu. A submenu item cannot support a nested submenu. </dd>
</dl>



<h2 id="xml">Defining Menus</h2>

<p>Instead of instantiating {@link android.view.Menu} objects in your application code, you should
define a menu and all its items in an XML <a
href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a>, then inflate the menu
resource (load it as a programmable object) in your application code. Defining your menus in XML is
a good practice because it separates your interface design from your application code (the same as
when you <a href="{@docRoot}guide/topics/ui/declaring-layout.html">define your Activity
layout</a>).</p>

<p>To define a menu, create an XML file inside your project's <code>res/menu/</code>
directory and build the menu with the following elements:</p>
<dl>
  <dt><code>&lt;menu></code></dt>
    <dd>Creates a {@link android.view.Menu}, which is a container for menu items. It must be
the root node and holds one or more of the following elements. You can also nest this element
in an {@code &lt;item&gt;} to create a submenu.</dd>
  <dt><code>&lt;item></code></dt>
    <dd>Creates a {@link android.view.MenuItem}, which represents a single item in a menu.</dd>
  <dt><code>&lt;group></code></dt>
    <dd>An optional, invisible container for {@code &lt;item&gt;} elements. It allows you to
categorize menu items so they share properties such as active state and visibility. See <a
href="#groups">Menu groups</a>.</dd>
</dl>

<p>For example, here is a file in <code>res/menu/</code> named <code>game_menu.xml</code>:</p>
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;menu xmlns:android="http://schemas.android.com/apk/res/android"&gt;
    &lt;item android:id="@+id/new_game"
          android:icon="@drawable/ic_new_game"
          android:title="@string/new_game" /&gt;
    &lt;item android:id="@+id/quit"
          android:icon="@drawable/ic_quit"
          android:title="@string/quit" /&gt;
&lt;/menu&gt;
</pre>

<p>This example defines a menu with two menu items. Each item includes the attributes:</p>
<dl>
  <dt>{@code android:id}</dt>
    <dd>A resource ID that's unique to the item so that the application can recognize the item when
the user selects it.</dd>
  <dt>{@code android:icon}</dt>
    <dd>A drawable resource that is the icon visible to the user.</dd>
  <dt>{@code android:title}</dt>
    <dd>A string resource that is the title visible to the user.</dd>
</dl>

<p>For more about the XML syntax and attributes for a menu resource, see the <a
href="{@docRoot}guide/topics/resources/menu-resource.html">Menu Resource</a> reference.</p>


<h2 id="Inflating">Inflating a Menu Resource</h2>

<p>You can inflate your menu resource (convert the XML resource into a programmable object) using
{@link android.view.MenuInflater#inflate(int,Menu) MenuInflater.inflate()}. For
example, the following code inflates the <code>game_menu.xml</code> file defined above during the
{@link android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} callback method, to be
used for the Options Menu:</p>

<pre>
&#64;Override
public boolean onCreateOptionsMenu(Menu menu) {
    MenuInflater inflater = getMenuInflater();
    inflater.inflate(R.menu.game_menu, menu);
    return true;
}
</pre>

<p>The {@link android.app.Activity#getMenuInflater()} method returns a {@link
android.view.MenuInflater} for the Activity. With this object, you can call {@link
android.view.MenuInflater#inflate(int,Menu) inflate()}, which inflates a menu resource into a
{@link android.view.Menu} object. In this example, the menu resource defined by
<code>game_menu.xml</code>
is inflated into the {@link android.view.Menu} that was passed into {@link
android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()}. (This callback method for
creating an option menu is discussed more in the next section.)</p>



<h2 id="options-menu">Creating an Options Menu</h2>

<div class="figure" style="width:200px">
  <img src="{@docRoot}images/options_menu.png" height="300" alt="" />
  <p class="img-caption"><strong>Figure 1.</strong> Screenshot of an Options Menu.</p>
</div>


<p>The Options Menu is where you should include basic application functions
and necessary navigation items (for example, a button
to open application settings). The user
can open the Options Menu with the device MENU key.
Figure 1 shows a screenshot of an Options Menu.</p>

<p>When opened, the first visible portion of the Options Menu is called the Icon Menu. It
holds the first six menu items.
If you add more than six items to the Options Menu, Android places the sixth item and those after it
into the Expanded Menu, which the user can open with the "More" menu item.</p>

<p>When the user opens the Options Menu for the first time, Android calls your Activity's
{@link android.app.Activity#onCreateOptionsMenu(Menu)
onCreateOptionsMenu()} method. Override this method in your Activity
and populate the {@link android.view.Menu} that is passed into the method. Populate the
{@link android.view.Menu} by inflating a menu resource as described in <a
href="#Inflating">Inflating a Menu Resource</a>. (You can
also populate the menu in code, using {@link android.view.Menu#add(int,int,int,int)
add()} to add menu items.)</p>

<p>When the user selects a menu item from the Options Menu, the system calls your Activity's
{@link android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()}
method. This method passes the
{@link android.view.MenuItem} that the user selected. You can identify the menu item by calling
{@link android.view.MenuItem#getItemId()}, which returns the unique ID for the menu
item (defined by the {@code android:id} attribute in the menu resource or with an integer passed
to the {@link android.view.Menu#add(int,int,int,int) add()} method). You can match this ID
against known menu items and perform the appropriate action.</p>

<p>For example:</p>

<pre>
&#64;Override
public boolean onOptionsItemSelected(MenuItem item) {
    // Handle item selection
    switch (item.getItemId()) {
    case R.id.new_game:
        newGame();
        return true;
    case R.id.quit:
        quit();
        return true;
    default:
        return super.onOptionsItemSelected(item);
    }
}
</pre>

<p>In this example, {@link android.view.MenuItem#getItemId()} queries the ID for the selected menu
item and the switch statement compares the ID against the resource IDs that were assigned to menu
items in the XML resource. When a switch case successfully handles the item, it
returns "true" to indicate that the item selection was handled. Otherwise, the default statement
passes the menu item to the super class in
case it can handle the item selected. (If you've directly extended the {@link android.app.Activity}
class, then the super class returns "false", but it's a good practice to
pass unhandled menu items to the super class instead of directly returning "false".)</p>

<p class="note"><strong>Tip:</strong> If your application contains multiple activities and
some of them provide the same Options Menu, consider creating
an Activity that implements nothing except the {@link android.app.Activity#onCreateOptionsMenu(Menu)
onCreateOptionsMenu()} and {@link android.app.Activity#onOptionsItemSelected(MenuItem)
onOptionsItemSelected()} methods. Then extend this class for each Activity that should share the
same Options Menu. This way, you have to manage only one set of code for handling menu
actions and each decendent class inherits the menu behaviors.<br/><br/>
If you want to add menu items to one of your decendent activities,
override {@link android.app.Activity#onCreateOptionsMenu(Menu)
onCreateOptionsMenu()} in that Activity. Call {@code super.onCreateOptionsMenu(menu)} so the
original menu items are created, then add new menu items with {@link
android.view.Menu#add(int,int,int,int) menu.add()}. You can also override the super class's
behavior for individual menu items.</p>


<h3 id="ChangingTheMenu">Changing the menu when it opens</h3>

<p>The {@link android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} method is
called only the first time the Options Menu is opened. The system keeps and re-uses the {@link
android.view.Menu} you define in this method until your Activity is destroyed. If you want to change
the Options Menu each time it opens, you must override the
{@link android.app.Activity#onPrepareOptionsMenu(Menu) onPrepareOptionsMenu()} method. This passes
you the {@link android.view.Menu} object as it currently exists. This is useful if you'd like to
remove, add, disable, or enable menu items depending on the current state of your application.</p>

<p class="note"><strong>Note:</strong> 
You should never change items in the Options Menu based on the {@link android.view.View} currently
in focus. When in touch mode (when the user is not using a trackball or d-pad), Views
cannot take focus, so you should never use focus as the basis for modifying
items in the Options Menu. If you want to provide menu items that are context-sensitive to a {@link
android.view.View}, use a <a href="#context-menu">Context Menu</a>.</p>



<h2 id="context-menu">Creating a Context Menu</h2>

<p>A context menu is conceptually similar to the menu displayed when the user performs a
"right-click" on a PC. You should use a context menu to provide the user access to
actions that pertain to a specific item in the user interface. On Android, a context menu is
displayed when the user performs a "long press" (press and hold) on an item.</p>

<p>You can create a context menu for any View, though context menus are most often used for items in
a {@link android.widget.ListView}. When the user performs a long-press on an item in a ListView and
the list is registered to provide a context menu, the list item signals to the user that a context
menu is available by animating its background color&mdash;it transitions from
orange to white before opening the context menu. (The Contacts application demonstrates this
feature.)</p>

<div class="sidebox-wrapper">
<div class="sidebox">
<h3>Register a ListView</h3>
<p>If your Activity uses a {@link android.widget.ListView} and
you want all list items to provide a context menu, register all items for a context
menu by passing the {@link android.widget.ListView} to {@link
android.app.Activity#registerForContextMenu(View) registerForContextMenu()}. For
example, if you're using a {@link android.app.ListActivity}, register all list items like this:</p>
<p><code>registerForContextMenu({@link android.app.ListActivity#getListView()});</code></p>
</div>
</div>

<p>In order for a View to provide a context menu, you must "register" the view for a context
menu. Call {@link android.app.Activity#registerForContextMenu(View) registerForContextMenu()} and
pass it the {@link android.view.View} you want to give a context menu. When this View then
receives a long-press, it displays a context menu.</p>

<p>To define the context menu's appearance and behavior, override your Activity's context menu
callback methods, {@link android.app.Activity#onCreateContextMenu(ContextMenu,View,ContextMenuInfo)
onCreateContextMenu()} and
{@link android.app.Activity#onContextItemSelected(MenuItem) onContextItemSelected()}.</p>

<p>For example, here's an {@link
android.app.Activity#onCreateContextMenu(ContextMenu,View,ContextMenuInfo)
onCreateContextMenu()} that uses the {@code context_menu.xml} menu resource:</p>
<pre>
&#64;Override
public void onCreateContextMenu(ContextMenu menu, View v,
                                ContextMenuInfo menuInfo) {
  super.onCreateContextMenu(menu, v, menuInfo);
  MenuInflater inflater = getMenuInflater();
  inflater.inflate(R.menu.context_menu, menu);
}
</pre>

<p>{@link android.view.MenuInflater} is used to inflate the context menu from a <a
href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a>. (You can also use
{@link android.view.Menu#add(int,int,int,int) add()} to add menu items.) The callback method
parameters include the {@link android.view.View}
that the user selected and a {@link android.view.ContextMenu.ContextMenuInfo} object that provides
additional information about the item selected. You might use these parameters to determine
which context menu should be created, but in this example, all context menus for the Activity are
the same.</p>

<p>Then when the user selects an item from the context menu, the system calls {@link
android.app.Activity#onContextItemSelected(MenuItem) onContextItemSelected()}. Here is an example
of how you can handle selected items:</p>

<pre>
&#64;Override
public boolean onContextItemSelected(MenuItem item) {
  AdapterContextMenuInfo info = (AdapterContextMenuInfo) item.getMenuInfo();
  switch (item.getItemId()) {
  case R.id.edit:
    editNote(info.id);
    return true;
  case R.id.delete:
    deleteNote(info.id);
    return true;
  default:
    return super.onContextItemSelected(item);
  }
}
</pre>

<p>The structure of this code is similar to the example for <a href="#options-menu">Creating an
Options Menu</a>, in which {@link android.view.MenuItem#getItemId()} queries the ID for the selected
menu item and a switch statement matches the item to the IDs that are defined in the menu resource.
And like the options menu example, the default statement calls the super class in case it
can handle menu items not handled here, if necessary.</p>

<p>In this example, the selected item is an item from a {@link android.widget.ListView}. To
perform an action on the selected item, the application needs to know the list
ID for the selected item (it's position in the ListView). To get the ID, the application calls
{@link android.view.MenuItem#getMenuInfo()}, which returns a {@link
android.widget.AdapterView.AdapterContextMenuInfo} object that includes the list ID for the
selected item in the {@link android.widget.AdapterView.AdapterContextMenuInfo#id id} field. The
local methods <code>editNote()</code> and <code>deleteNote()</code> methods accept this list ID to
perform an action on the data specified by the list ID.</p>

<p class="note"><strong>Note:</strong> Items in a context menu do not support icons or shortcut
keys.</p>



<h2 id="submenu">Creating Submenus</h2>

<p>A submenu is a menu that the user can open by selecting an item in another menu. You can add a
submenu to any menu (except a submenu). Submenus are useful when your application has a lot of
functions that can be organized into topics, like items in a PC application's menu bar (File, Edit,
View, etc.).</p>

<p>When creating your <a href="{@docRoot}guide/topics/resources/menu-resource.html">menu
resource</a>, you can create a submenu by adding a {@code &lt;menu&gt;} element as the child of an
{@code &lt;item&gt;}. For example:</p>

<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;menu xmlns:android="http://schemas.android.com/apk/res/android"&gt;
    &lt;item android:id="@+id/file"
          android:icon="@drawable/file"
          android:title="@string/file" &gt;
        &lt;!-- "file" submenu --&gt;
        &lt;menu"&gt;
            &lt;item android:id="@+id/new"
                  android:title="@string/new" /&gt;
            &lt;item android:id="@+id/open"
                  android:title="@string/open" /&gt;
        &lt;/menu&gt;
    &lt;/item&gt;
&lt;/menu&gt;
</pre>

<p>When the user selects an item from a submenu, the parent menu's respective on-item-selected
callback method receives the event. For instance, if the above menu is applied as an Options Menu,
then the {@link android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} method
is called when a submenu item is selected.</p>

<p>You can also use {@link android.view.Menu#addSubMenu(int,int,int,int) addSubMenu()} to
dynamically add a {@link android.view.SubMenu} to an existing {@link android.view.Menu}. This
returns the new {@link android.view.SubMenu} object, to which you can add
submenu items, using {@link android.view.Menu#add(int,int,int,int) add()}</p>



<h2 id="features">Other Menu Features</h2>

<p>Here are some other features that you can apply to most menu items.</p>

<h3 id="groups">Menu groups</h3>

<p>A menu group is a collection of menu items that share certain traits. With a group, you
can:</p>
<ul>
  <li>Show or hide all items with {@link android.view.Menu#setGroupVisible(int,boolean)
setGroupVisible()}</li>
  <li>Enable or disable all items with {@link android.view.Menu#setGroupEnabled(int,boolean)
setGroupEnabled()}</li>
  <li>Specify whether all items are checkable with {@link
android.view.Menu#setGroupCheckable(int,boolean,boolean) setGroupCheckable()}</li>
</ul>

<p>You can create a group by nesting {@code &lt;item&gt;} elements inside a {@code &lt;group&gt;}
element in your menu resource or by specifying a group ID with the the {@link
android.view.Menu#add(int,int,int,int) add()} method.</p>

<p>Here's an example menu resource that includes a group:</p>

<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;menu xmlns:android="http://schemas.android.com/apk/res/android"&gt;
    &lt;item android:id="@+id/item1"
          android:icon="@drawable/item1"
          android:title="@string/item1" /&gt;
    &lt;!-- menu group --&gt;
    &lt;group android:id="@+id/group1"&gt;
        &lt;item android:id="@+id/groupItem1"
              android:title="@string/groupItem1" /&gt;
        &lt;item android:id="@+id/groupItem2"
              android:title="@string/groupItem2" /&gt;
    &lt;/group&gt;
&lt;/menu&gt;
</pre>

<p>The items that are in the group appear the same as the first item that is not in a
group&mdash;all three items in the menu are siblings. However, you can modify the traits of the two
items in the group by referencing the group ID and using the methods listed above.</p>


<h3 id="checkable">Checkable menu items</h3>

<div class="figure" style="width:200px">
  <img src="{@docRoot}images/radio_buttons.png" height="300" alt="" />
  <p class="img-caption"><strong>Figure 2.</strong> Screenshot of checkable menu items</p>
</div>

<p>A menu can be useful as an interface for turning options on and off, using a checkbox for
stand-alone options, or radio buttons for groups of
mutually exclusive options. Figure 2 shows a submenu with items that are checkable with radio
buttons.</p>

<p class="note"><strong>Note:</strong> Menu items in the Icon Menu (from the Options Menu) cannot
display a checkbox or radio button. If you choose to make items in the Icon Menu checkable,
you must manually indicate the checked state by swapping the icon and/or text
each time the state changes.</p>

<p>You can define the checkable behavior for individual menu items using the {@code
android:checkable} attribute in the {@code &lt;item&gt;} element, or for an entire group with
the {@code android:checkableBehavior} attribute in the {@code &lt;group&gt;} element. For
example, all items in this menu group are checkable with a radio button:</p>

<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;menu xmlns:android="http://schemas.android.com/apk/res/android"&gt;
    &lt;group android:checkableBehavior="single"&gt;
        &lt;item android:id="@+id/red"
              android:title="@string/red" /&gt;
        &lt;item android:id="@+id/blue"
              android:title="@string/blue" /&gt;
    &lt;/group&gt;
&lt;/menu&gt;
</pre>

<p>The {@code android:checkableBehavior} attribute accepts either:
<dl>
  <dt>{@code single}</dt>
    <dd>Only one item from the group can be checked (radio buttons)</dd>
  <dt>{@code all}</dt>
    <dd>All items can be checked (checkboxes)</dd>
  <dt>{@code none}</dt>
    <dd>No items are checkable</dd>
</dl>

<p>You can apply a default checked state to an item using the {@code android:checked} attribute in
the {@code &lt;item&gt;} element and change it in code with the {@link
android.view.MenuItem#setChecked(boolean) setChecked()} method.</p>

<p>When a checkable item is selected, the system calls your respective item-selected callback method
(such as {@link android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()}). It
is here that you must set the state of the checkbox, because a checkbox or radio button does not
change its state automatically. You can query the current state of the item (as it was before the
user selected it) with {@link android.view.MenuItem#isChecked()} and then set the checked state with
{@link android.view.MenuItem#setChecked(boolean) setChecked()}. For example:</p>

<pre>
&#64;Override
public boolean onOptionsItemSelected(MenuItem item) {
  switch (item.getItemId()) {
  case R.id.vibrate:
  case R.id.dont_vibrate:
    if (item.isChecked()) item.setChecked(false);
    else item.setChecked(true);
    return true;
  default:
    return super.onOptionsItemSelected(item);
  }
}
</pre>

<p>If you don't set the checked state this way, then the visible state of the item (the checkbox or
radio button) will not
change when the user selects it. When you do set the state, the Activity preserves the checked state
of the item so that when the user opens the menu later, the checked state that you
set is visible.</p>

<p class="note"><strong>Note:</strong>
Checkable menu items are intended to be used only on a per-session basis and not saved after the
application is destroyed. If you have application settings that you would like to save for the user,
you should store the data using <a
href="#{@docRoot}guide/topics/data/data-storage.html#pref">Shared Preferences</a>.</p>


<h3 id="shortcuts">Shortcut keys</h3>

<p>You can add quick-access shortcut keys using letters and/or numbers to menu items with the
{@code android:alphabeticShortcut} and {@code android:numericShortcut} attributes in the {@code
&lt;item&gt;} element. You can also use the methods {@link
android.view.MenuItem#setAlphabeticShortcut(char)} and {@link
android.view.MenuItem#setNumericShortcut(char)}. Shortcut keys are <em>not</em>
case sensitive.</p>

<p>For example, if you apply the "s" character as an alphabetic shortcut to a "save" menu item, then
when the menu is open (or while the user holds the MENU key) and the user presses the "s" key,
the "save" menu item is selected.</p>

<p>This shortcut key is displayed as a tip in the menu item, below the menu item name
(except for items in the Icon Menu, which are displayed only if the user holds the MENU
key).</p>

<p class="note"><strong>Note:</strong> Shortcut keys for menu items only work on devices with a
hardware keyboard. Shortcuts cannot be added to items in a Context Menu.</p>


<h3 id="intents">Intents for menu items</h3>

<p>Sometimes you'll want a menu item to launch an Activity using an Intent (whether it's an
Actvitity in your application or another application). When you know the Intent you want to use and
have a specific menu item that should initiate the Intent, you can execute the Intent with {@link
android.app.Activity#startActivity(Intent) startActivity()} during the appropriate on-item-selected
callback method (such as the {@link android.app.Activity#onOptionsItemSelected(MenuItem)
onOptionsItemSelected()} callback).</p>

<p>However, if you are not certain that the user's device
contains an application that handles the Intent, then adding a menu item that executes the
Intent can result in a non-functioning menu item, because the Intent might not resolve to an
Activity that accepts it. To solve this, Android lets you dynamically add menu items to your menu
when Android finds activities on the device that handle your Intent.</p>

<p>If you're not familiar with creating Intents, read the <a
href="/guide/topics/intents/intents-filters.html">Intents and Intent Filters</a>.</p>


<h4>Dynamically adding Intents</h4>

<p>When you don't know if the user's device has an application that handles a specific Intent,
you can define the Intent and let Android search the device for activities that accept the Intent.
When it finds activies that handle the Intent, it adds a menu item for
each one to your menu and attaches the appropriate Intent to open the Activity when the user
selects it.</p>

<p>To add menu items based on available activities that accept an Intent:</p>
<ol>
  <li>Define an
Intent with the category {@link android.content.Intent#CATEGORY_ALTERNATIVE} and/or
{@link android.content.Intent#CATEGORY_SELECTED_ALTERNATIVE}, plus any other requirements.</li>
  <li>Call {@link
android.view.Menu#addIntentOptions(int,int,int,ComponentName,Intent[],Intent,int,MenuItem[])
Menu.addIntentOptions()}. Android then searches for any applications that can perform the Intent
and adds them to your menu.</li>
</ol>

<p>If there are no applications installed
that satisfy the Intent, then no menu items are added.</p>

<p class="note"><strong>Note:</strong>
{@link android.content.Intent#CATEGORY_SELECTED_ALTERNATIVE} is used to handle the currently
selected element on the screen. So, it should only be used when creating a Menu in {@link
android.app.Activity#onCreateContextMenu(ContextMenu,View,ContextMenuInfo)
onCreateContextMenu()}.</p>

<p>For example:</p>

<pre>
&#64;Override
public boolean onCreateOptionsMenu(Menu menu){
    super.onCreateOptionsMenu(menu);

    // Create an Intent that describes the requirements to fulfill, to be included
    // in our menu. The offering app must include a category value of Intent.CATEGORY_ALTERNATIVE.
    Intent intent = new Intent(null, dataUri);
    intent.addCategory(Intent.CATEGORY_ALTERNATIVE);

    // Search and populate the menu with acceptable offering applications.
    menu.addIntentOptions(
         R.id.intent_group,  // Menu group to which new items will be added
         0,      // Unique item ID (none)
         0,      // Order for the items (none)
         this.getComponentName(),   // The current Activity name
         null,   // Specific items to place first (none)
         intent, // Intent created above that describes our requirements
         0,      // Additional flags to control items (none)
         null);  // Array of MenuItems that correlate to specific items (none)

    return true;
}</pre>

<p>For each Activity found that provides an Intent filter matching the Intent defined, a menu
item is added, using the value in the Intent filter's <code>android:label</code> as the
menu item title and the application icon as the menu item icon. The
{@link android.view.Menu#addIntentOptions(int,int,int,ComponentName,Intent[],Intent,int,MenuItem[])
addIntentOptions()} method returns the number of menu items added.</p>

<p class="note"><strong>Note:</strong> When you call {@link
android.view.Menu#addIntentOptions(int,int,int,ComponentName,Intent[],Intent,int,MenuItem[])
addIntentOptions()}, it overrides any and all menu items by the menu group specified in the first
argument.</p>


<h4>Allowing your Activity to be added to menus</h4>

<p>You can also offer the services of your Activity to other applications, so your
application can be included in the menu of others (reverse the roles described above).</p>

<p>To be included in other application menus, you need to define an Intent
filter as usual, but be sure to include the {@link android.content.Intent#CATEGORY_ALTERNATIVE}
and/or {@link android.content.Intent#CATEGORY_SELECTED_ALTERNATIVE} values for the Intent filter
category. For example:</p>
<pre>
&lt;intent-filter label="Resize Image">
    ...
    &lt;category android:name="android.intent.category.ALTERNATIVE" />
    &lt;category android:name="android.intent.category.SELECTED_ALTERNATIVE" />
    ...
&lt;/intent-filter>
</pre>

<p>Read more about writing Intent filters in the
<a href="/guide/topics/intents/intents-filters.html">Intents and Intent Filters</a> document.</p>

<p>For a sample application using this technique, see the 
<a href="{@docRoot}resources/samples/NotePad/src/com/example/android/notepad/NoteEditor.html">Note
Pad</a> sample code.</p>