xref: /frameworks/base/docs/html/guide/topics/resources/menu-resource.jd

page.title=Menu Resource
parent.title=Resource Types
parent.link=available-resources.html
@jd:body

<div id="qv-wrapper">
  <div id="qv">
    <h2>See also</h2>
    <ol>
      <li><a href="{@docRoot}guide/topics/ui/menus.html">Menus</a></li>
    </ol>
  </div>
</div>

<p>A menu resource defines an application menu (Options Menu, Context Menu, or submenu) that
can be inflated with {@link android.view.MenuInflater}.</p>

<p>For a guide to using menus, see the <a href="{@docRoot}guide/topics/ui/menus.html">Menus</a>
developer guide.</p>

<dl class="xml">

<dt>file location:</dt>
<dd><code>res/menu/<em>filename</em>.xml</code><br/>
The filename will be used as the resource ID.</dd>

<dt>compiled resource datatype:</dt>
<dd>Resource pointer to a {@link android.view.Menu} (or subclass) resource.</dd>

<dt>resource reference:</dt>
<dd>
In Java: <code>R.menu.<em>filename</em></code><br/>
In XML: <code>@[<em>package</em>:]menu.<em>filename</em></code>
</dd>

<dt>syntax:</dt>
<dd>
<pre>
&lt;?xml version="1.0" encoding="utf-8"?>
&lt;<a href="#menu-element">menu</a> xmlns:android="http://schemas.android.com/apk/res/android">
    &lt;<a href="#item-element">item</a> android:id="@[+][<em>package</em>:]id/<em>resource_name</em>"
          android:title="<em>string</em>"
          android:titleCondensed="<em>string</em>"
          android:icon="@[package:]drawable/<em>drawable_resource_name</em>"
          android:onClick="<em>method name</em>"
          android:showAsAction=["ifRoom" | "never" | "withText" | "always" | "collapseActionView"]
          android:actionLayout="@[package:]layout/<em>layout_resource_name</em>"
          android:actionViewClass="<em>class name</em>"
          android:actionProviderClass="<em>class name</em>"
          android:alphabeticShortcut="<em>string</em>"
          android:numericShortcut="<em>string</em>"
          android:checkable=["true" | "false"]
          android:visible=["true" | "false"]
          android:enabled=["true" | "false"]
          android:menuCategory=["container" | "system" | "secondary" | "alternative"]
          android:orderInCategory="<em>integer</em>" /&gt;
    &lt;<a href="#group-element">group</a> android:id="@[+][<em>package</em>:]id/<em>resource name</em>"
           android:checkableBehavior=["none" | "all" | "single"]
           android:visible=["true" | "false"]
           android:enabled=["true" | "false"]
           android:menuCategory=["container" | "system" | "secondary" | "alternative"]
           android:orderInCategory="<em>integer</em>" &gt;
        &lt;<a href="#item-element">item</a> /&gt;
    &lt;/group&gt;
    &lt;<a href="#item-element">item</a> &gt;
        &lt;<a href="#menu-element">menu</a>&gt;
          &lt;<a href="#item-element">item</a> /&gt;
        &lt;/menu&gt;
    &lt;/item&gt;
&lt;/menu&gt;
</pre>
</dd>

<dt>elements:</dt>
<dd>
<dl class="tag-list">

  <dt id="menu-element"><code>&lt;menu&gt;</code></dt>
    <dd><strong>Required.</strong> This must be the root node. Contains <code>&lt;item></code> and/or
      <code>&lt;group></code> elements.
      <p class="caps">attributes:</p>
      <dl class="atn-list">
        <dt><code>xmlns:android</code></dt>
          <dd><em>XML namespace</em>. <strong>Required.</strong> Defines the XML namespace, which
must be <code>"http://schemas.android.com/apk/res/android"</code>.
      </dl>
    </dd>

  <dt id="item-element"><code>&lt;item&gt;</code></dt>
    <dd>A menu item. May contain a <code>&lt;menu&gt;</code> element (for a Sub
      Menu). Must be a child of a <code>&lt;menu&gt;</code> or <code>&lt;group&gt;</code> element.
      <p class="caps">attributes:</p>
      <dl class="atn-list">
        <dt><code>android:id</code></dt>
        <dd><em>Resource ID</em>. A unique resource ID. To create a new resource ID for this item, use the form:
<code>"@+id/<em>name</em>"</code>. The plus symbol indicates that this should be created as a new
ID.</dd>
        <dt><code>android:title</code></dt>
          <dd><em>String resource</em>. The menu title as a string resource or raw string.</dd>
        <dt><code>android:titleCondensed</code></dt>
          <dd><em>String resource</em>. A condensed title as a string resource or a raw string. This
title is used for situations in which the normal title is too long.</dd>

        <dt><code>android:icon</code></dt>
          <dd><em>Drawable resource</em>. An image to be used as the menu item icon.</dd>

        <dt><code>android:onClick</code></dt>
          <dd><em>Method name</em>. The method to call when this menu item is clicked. The
method must be declared in the activity as public and accept a {@link android.view.MenuItem} as its
only parameter, which indicates the item clicked. This method takes precedence over the standard
callback to {@link android.app.Activity#onOptionsItemSelected onOptionsItemSelected()}. See the
example at the bottom.
          <p class="warning"><strong>Warning:</strong> If you obfuscate your code using <a
href="{@docRoot}tools/help/proguard.html">ProGuard</a> (or a similar tool),
be sure to exclude the method you specify in this attribute from renaming, because it can break the
functionality.</p>
          <p>Introduced in API Level 11.</p></dd>

        <dt><code>android:showAsAction</code></dt>
          <dd><em>Keyword</em>. When and how this item should appear as an action item in the Action
Bar. A menu item can appear as an action item only when the activity includes an {@link
android.app.ActionBar} (introduced in API Level 11). Valid values:
          <table>
            <tr><th>Value</th><th>Description</th></tr>
            <tr><td><code>ifRoom</code></td><td>Only place this item in the Action Bar if
there is room for it.</td></tr>
            <tr><td><code>withText</code></td><td>Also include the title text (defined
by {@code android:title}) with the action item. You can include this value along with one
of the others as a flag set, by separating them with a pipe {@code |}.</td></tr>
            <tr><td><code>never</code></td><td>Never place this item in the Action Bar.</td></tr>
            <tr><td><code>always</code></td><td>Always place this item in the Action Bar.
Avoid using this unless it's critical that the item always appear in the action
bar. Setting multiple items to always appear as action items can result in them overlapping
with other UI in the action bar.</td></tr>
            <tr><td><code>collapseActionView</code></td><td>The action view associated
with this action item (as declared by <code>android:actionLayout</code> or
<code>android:actionViewClass</code>) is
collapsible.<br/>Introduced in API Level 14.</td></tr>
          </table>
          <p>See the <a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> developer 
guide for more information.</p>
          <p>Introduced in API Level 11.</p>
        </dd>

        <dt><code>android:actionLayout</code></dt>
          <dd><em>Layout resource</em>. A layout to use as the action view.
          <p>See the <a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> developer 
guide for more information.</p>
          <p>Introduced in API Level 11.</p></dd>

        <dt><code>android:actionViewClass</code></dt>
          <dd><em>Class name</em>. A fully-qualified class name for the {@link android.view.View}
to use as the action view. For example,
{@code "android.widget.SearchView"} to use {@link android.widget.SearchView} as an action view.
          <p>See the <a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> developer 
guide for more information.</p>
          <p class="warning"><strong>Warning:</strong> If you obfuscate your code using <a
href="{@docRoot}tools/help/proguard.html">ProGuard</a> (or a similar tool),
be sure to exclude the class you specify in this attribute from renaming, because it can break the
functionality.</p>
          <p>Introduced in API Level 11.</p></dd>

        <dt><code>android:actionProviderClass</code></dt>
          <dd><em>Class name</em>. A fully-qualified class name for the {@link
android.view.ActionProvider} to use in place of the action item. For example,
{@code "android.widget.ShareActionProvider"} to use {@link android.widget.ShareActionProvider}.
          <p>See the <a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> developer
guide for more information.</p>
          <p class="warning"><strong>Warning:</strong> If you obfuscate your code using <a
href="{@docRoot}tools/help/proguard.html">ProGuard</a> (or a similar tool),
be sure to exclude the class you specify in this attribute from renaming, because it can break the
functionality.</p>
          <p>Introduced in API Level 14.</p></dd>

        <dt><code>android:alphabeticShortcut</code></dt>
          <dd><em>Char</em>. A character for the alphabetic shortcut key.</dd>
        <dt><code>android:numericShortcut</code></dt>
          <dd><em>Integer</em>. A number for the numeric shortcut key.</dd>
        <dt><code>android:checkable</code></dt>
          <dd><em>Boolean</em>. "true" if the item is checkable.</dd>
        <dt><code>android:checked</code></dt>
          <dd><em>Boolean</em>. "true" if the item is checked by default.</dd>
        <dt><code>android:visible</code></dt>
          <dd><em>Boolean</em>. "true" if the item is visible by default.</dd>
        <dt><code>android:enabled</code></dt>
          <dd><em>Boolean</em>. "true" if the item is enabled by default.</dd>
        <dt><code>android:menuCategory</code></dt>
          <dd><em>Keyword</em>. Value corresponding to {@link android.view.Menu} {@code CATEGORY_*}
          constants, which define the item's priority. Valid values:
          <table>
            <tr><th>Value</th><th>Description</th></tr>
            <tr><td><code>container</code></td><td>For items that are part of a
container.</td></tr>
            <tr><td><code>system</code></td><td>For items that are provided by the
system.</td></tr>
            <tr><td><code>secondary</code></td><td>For items that are user-supplied secondary
(infrequently used) options.</td></tr>
            <tr><td><code>alternative</code></td><td>For items that are alternative actions
on the data that is currently displayed.</td></tr>
          </table>
        </dd>
        <dt><code>android:orderInCategory</code></dt>
          <dd><em>Integer</em>. The order of "importance" of the item, within a group.</dd>
      </dl>
    </dd>

  <dt id="group-element"><code>&lt;group&gt;</code></dt>
    <dd>A menu group (to create a collection of items that share traits, such as whether they are
visible, enabled, or checkable). Contains one or more <code>&lt;item&gt;</code> elements. Must be a
child of a <code>&lt;menu&gt;</code> element.
      <p class="caps">attributes:</p>
      <dl class="atn-list">
        <dt><code>android:id</code></dt>
        <dd><em>Resource ID</em>. A unique resource ID. To create a new resource ID for this item,
use the form:
<code>"@+id/<em>name</em>"</code>. The plus symbol indicates that this should be created as a new
ID.</dd>
        <dt><code>android:checkableBehavior</code></dt>
        <dd><em>Keyword</em>. The type of checkable behavior for the group. Valid values:
          <table>
            <tr><th>Value</th><th>Description</th></tr>
            <tr><td><code>none</code></td><td>Not checkable</td></tr>
            <tr><td><code>all</code></td><td>All items can be checked (use checkboxes)</td></tr>
            <tr><td><code>single</code></td><td>Only one item can be checked (use radio
buttons)</td></tr>
          </table>
        </dd>
        <dt><code>android:visible</code></dt>
        <dd><em>Boolean</em>. "true" if the group is visible.</dd>
        <dt><code>android:enabled</code></dt>
        <dd><em>Boolean</em>. "true" if the group is enabled.</dd>
        <dt><code>android:menuCategory</code></dt>
          <dd><em>Keyword</em>. Value corresponding to {@link android.view.Menu} {@code CATEGORY_*}
          constants, which define the group's priority. Valid values:
          <table>
            <tr><th>Value</th><th>Description</th></tr>
            <tr><td><code>container</code></td><td>For groups that are part of a
container.</td></tr>
            <tr><td><code>system</code></td><td>For groups that are provided by the
system.</td></tr>
            <tr><td><code>secondary</code></td><td>For groups that are user-supplied secondary
(infrequently used) options.</td></tr>
            <tr><td><code>alternative</code></td><td>For groups that are alternative actions
on the data that is currently displayed.</td></tr>
          </table>
        </dd>
        <dt><code>android:orderInCategory</code></dt>
        <dd><em>Integer</em>. The default order of the items within the category.</dd>
      </dl>
    </dd>
</dl>

</dd>

<dt>example:</dt>
<dd>XML file saved at <code>res/menu/example_menu.xml</code>:
<pre>
&lt;menu xmlns:android="http://schemas.android.com/apk/res/android">
    &lt;item android:id="@+id/item1"
          android:title="@string/item1"
          android:icon="@drawable/group_item1_icon"
          android:showAsAction="ifRoom|withText"/>
    &lt;group android:id="@+id/group">
        &lt;item android:id="@+id/group_item1"
              android:onClick="onGroupItemClick"
              android:title="@string/group_item1"
              android:icon="@drawable/group_item1_icon" />
        &lt;item android:id="@+id/group_item2"
              android:onClick="onGroupItemClick"
              android:title="@string/group_item2"
              android:icon="@drawable/group_item2_icon" />
    &lt;/group>
    &lt;item android:id="@+id/submenu"
          android:title="@string/submenu_title"
          android:showAsAction="ifRoom|withText" >
        &lt;menu>
            &lt;item android:id="@+id/submenu_item1"
                  android:title="@string/submenu_item1" />
        &lt;/menu>
    &lt;/item>
&lt;/menu>
</pre>
    <p>The following application code inflates the menu from the {@link
android.app.Activity#onCreateOptionsMenu(Menu)} callback and also declares the on-click
callback for two of the items:</p>
<pre>
public boolean onCreateOptionsMenu(Menu menu) {
    MenuInflater inflater = getMenuInflater();
    inflater.inflate(R.menu.example_menu, menu);
    return true;
}

public void onGroupItemClick(MenuItem item) {
    // One of the group items (using the onClick attribute) was clicked
    // The item parameter passed here indicates which item it is
    // All other menu item clicks are handled by {@link android.app.Activity#onOptionsItemSelected onOptionsItemSelected()}
}
</pre>
<p class="note"><strong>Note:</strong> The {@code android:showAsAction} attribute is
available only on Android 3.0 (API Level 11) and greater.</p>
</dd> <!-- end example -->


</dl>