Home | History | Annotate | Download | only in resources
      1 page.title=Menu Resource
      2 parent.title=Resource Types
      3 parent.link=available-resources.html
      4 @jd:body
      5 
      6 <div id="qv-wrapper">
      7   <div id="qv">
      8     <h2>See also</h2>
      9     <ol>
     10       <li><a href="{@docRoot}guide/topics/ui/menus.html">Creating Menus</a></li>
     11     </ol>
     12   </div>
     13 </div>
     14 
     15 <p>A menu resource defines an application menu (Options Menu, Context Menu, or Sub Menu) that
     16 can be inflated with {@link android.view.MenuInflater}.</p>
     17 
     18 <dl class="xml">
     19 
     20 <dt>file location:</dt>
     21 <dd><code>res/menu/<em>filename</em>.xml</code><br/>
     22 The filename will be used as the resource ID.</dd>
     23 
     24 <dt>compiled resource datatype:</dt>
     25 <dd>Resource pointer to a {@link android.view.Menu} (or subclass) resource.</dd>
     26 
     27 <dt>resource reference:</dt>
     28 <dd>
     29 In Java: <code>R.menu.<em>filename</em></code><br/>
     30 In XML: <code>@[<em>package</em>:]menu.<em>filename</em></code>
     31 </dd>
     32 
     33 <dt>syntax:</dt>
     34 <dd>
     35 <pre>
     36 &lt;?xml version="1.0" encoding="utf-8"?>
     37 &lt;<a href="#menu-element">menu</a> xmlns:android="http://schemas.android.com/apk/res/android">
     38     &lt;<a href="#item-element">item</a> android:id="@[+][<em>package</em>:]id/<em>resource_name</em>"
     39           android:menuCategory=["container" | "system" | "secondary" | "alternative"]
     40           android:orderInCategory="<em>integer</em>"
     41           android:title="<em>string</em>"
     42           android:titleCondensed="<em>string</em>"
     43           android:icon="@[package:]drawable/<em>drawable_resource_name</em>"
     44           android:alphabeticShortcut="<em>string</em>"
     45           android:numericShortcut="<em>string</em>"
     46           android:checkable=["true" | "false"]
     47           android:visible=["visible" | "invisible" | "gone"]
     48           android:enabled=["enabled" | "disabled"] /&gt;
     49     &lt;<a href="#group-element">group</a> android:id="@[+][<em>package</em>:]id/<em>resource name</em>"
     50            android:menuCategory=["container" | "system" | "secondary" | "alternative"]
     51            android:orderInCategory="<em>integer</em>"
     52            android:checkableBehavior=["none" | "all" | "single"]
     53            android:visible=["visible" | "invisible" | "gone"]
     54            android:enabled=["enabled" | "disabled"] &gt;
     55         &lt;<a href="#item-element">item</a> /&gt;
     56     &lt;/group&gt;
     57     &lt;<a href="#item-element">item</a> &gt;
     58         &lt;<a href="#menu-element">menu</a>&gt;
     59           &lt;<a href="#item-element">item</a> /&gt;
     60         &lt;/menu&gt;
     61     &lt;/item&gt;
     62 &lt;/menu&gt;
     63 </pre>
     64 </dd>
     65 
     66 <dt>elements:</dt>
     67 <dd>
     68 <dl class="tag-list">
     69 
     70   <dt id="menu-element"><code>&lt;menu&gt;</code></dt>
     71     <dd><strong>Required.</strong> This must be the root node. Contains <code>&lt;item></code> and/or
     72       <code>&lt;group></code> elements.
     73       <p class="caps">attributes:</p>
     74       <dl class="atn-list">
     75         <dt><code>xmlns:android</code></dt>
     76           <dd><em>String</em>. <strong>Required.</strong> Defines the XML namespace, which must be
     77           <code>"http://schemas.android.com/apk/res/android"</code>.
     78       </dl>
     79     </dd>
     80   <dt id="group-element"><code>&lt;group&gt;</code></dt>
     81     <dd>A menu group (to create a collection of items that share traits, such as whether they are
     82 visible, enabled, or checkable). Contains one or more <code>&lt;item&gt;</code> elements. Must be a
     83 child of a <code>&lt;menu&gt;</code> element.
     84       <p class="caps">attributes:</p>
     85       <dl class="atn-list">
     86         <dt><code>android:id</code></dt>
     87         <dd><em>Resource ID</em>. A unique resource ID. To create a new resource ID for this item, use the form:
     88 <code>"@+id/<em>name</em>"</code>. The plus symbol indicates that this should be created as a new ID.</dd>
     89         <dt><code>android:menuCategory</code></dt>
     90           <dd><em>Keyword</em>. Value corresponding to {@link android.view.Menu} {@code CATEGORY_*}
     91           constants, which define the group's priority. Valid values:
     92           <table>
     93             <tr><th>Value</th><th>Description</th></tr>
     94             <tr><td><code>container</code></td><td>For groups that are part of a
     95 container.</td></tr>
     96             <tr><td><code>system</code></td><td>For groups that are provided by the
     97 system.</td></tr>
     98             <tr><td><code>secondary</code></td><td>For groups that are user-supplied secondary
     99 (infrequently used) options.</td></tr>
    100             <tr><td><code>alternative</code></td><td>For groups that are alternative actions
    101 on the data that is currently displayed.</td></tr>
    102           </table>
    103         </dd>
    104         <dt><code>android:orderInCategory</code></dt>
    105         <dd><em>Integer</em>. The default order of the items within the category.</dd>
    106         <dt><code>android:checkableBehavior</code></dt>
    107         <dd><em>Keyword</em>. The type of checkable behavior for the group. Valid values:
    108           <table>
    109             <tr><th>Value</th><th>Description</th></tr>
    110             <tr><td><code>none</code></td><td>Not checkable</td></tr>
    111             <tr><td><code>all</code></td><td>All items can be checked (use checkboxes)</td></tr>
    112             <tr><td><code>single</code></td><td>Only one item can be checked (use radio buttons)</td></tr>
    113           </table>
    114         </dd>
    115         <dt><code>android:visible</code></dt>
    116         <dd><em>Boolean</em>. "true" if the group is visible.</dd>
    117         <dt><code>android:enabled</code></dt>
    118         <dd><em>Boolean</em>. "true" if the group is enabled.</dd>
    119       </dl>
    120     </dd>
    121   <dt id="item-element"><code>&lt;item&gt;</code></dt>
    122     <dd>A menu item. May contain a <code>&lt;menu&gt;</code> element (for a Sub
    123       Menu). Must be a child of a <code>&lt;menu&gt;</code> or <code>&lt;group&gt;</code> element.
    124       <p class="caps">attributes:</p>
    125       <dl class="atn-list">
    126         <dt><code>android:id</code></dt>
    127         <dd><em>Resource ID</em>. A unique resource ID. To create a new resource ID for this item, use the form:
    128 <code>"@+id/<em>name</em>"</code>. The plus symbol indicates that this should be created as a new ID.</dd>
    129         <dt><code>android:menuCategory</code></dt>
    130           <dd><em>Keyword</em>. Value corresponding to {@link android.view.Menu} {@code CATEGORY_*}
    131           constants, which define the item's priority. Valid values:
    132           <table>
    133             <tr><th>Value</th><th>Description</th></tr>
    134             <tr><td><code>container</code></td><td>For items that are part of a
    135 container.</td></tr>
    136             <tr><td><code>system</code></td><td>For items that are provided by the
    137 system.</td></tr>
    138             <tr><td><code>secondary</code></td><td>For items that are user-supplied secondary
    139 (infrequently used) options.</td></tr>
    140             <tr><td><code>alternative</code></td><td>For items that are alternative actions
    141 on the data that is currently displayed.</td></tr>
    142           </table>
    143         </dd>
    144         <dt><code>android:orderInCategory</code></dt>
    145           <dd><em>Integer</em>. The order of "importance" of the item, within a group.</dd>
    146         <dt><code>android:title</code></dt>
    147           <dd><em>String</em>. The menu title.</dd>
    148         <dt><code>android:titleCondensed</code></dt>
    149           <dd><em>String</em>. A condensed title, for situations in which the normal title is
    150 too long.</dd>
    151         <dt><code>android:icon</code></dt>
    152           <dd><em>Drawable resource</em>. An image to be used as the menu item icon.</dd>
    153         <dt><code>android:alphabeticShortcut</code></dt>
    154           <dd><em>Char</em>. A character for the alphabetic shortcut key.</dd>
    155         <dt><code>android:numericShortcut</code></dt>
    156           <dd><em>Integer</em>. A number for the numeric shortcut key.</dd>
    157         <dt><code>android:checkable</code></dt>
    158           <dd><em>Boolean</em>. "true" if the item is checkable.</dd>
    159         <dt><code>android:checked</code></dt>
    160           <dd><em>Boolean</em>. "true" if the item is checked by default.</dd>
    161         <dt><code>android:visible</code></dt>
    162           <dd><em>Boolean</em>. "true" if the item is visible by default.</dd>
    163         <dt><code>android:enabled</code></dt>
    164           <dd><em>Boolean</em>. "true" if the item is enabled by default.</dd>
    165       </dl>
    166     </dd>
    167 </dl>
    168 
    169 </dd>
    170 
    171 <dt>example:</dt>
    172 <dd>XML file saved at <code>res/menu/example_menu.xml</code>:
    173 <pre>
    174 &lt;menu xmlns:android="http://schemas.android.com/apk/res/android">
    175     &lt;item android:id="@+id/item1"
    176           android:title="@string/item1"
    177           android:icon="@drawable/group_item1_icon" />
    178     &lt;group android:id="@+id/group">
    179         &lt;item android:id="@+id/group_item1"
    180               android:title="@string/group_item1"
    181               android:icon="@drawable/group_item1_icon" />
    182         &lt;item android:id="@+id/group_item2"
    183               android:title="G@string/group_item2"
    184               android:icon="@drawable/group_item2_icon" />
    185     &lt;/group>
    186     &lt;item android:id="@+id/submenu"
    187           android:title="@string/submenu_title" >
    188         &lt;menu>
    189             &lt;item android:id="@+id/submenu_item1"
    190                   android:title="@string/submenu_item1" />
    191         &lt;/menu>
    192     &lt;/item>
    193 &lt;/menu>
    194 </pre>
    195     <p>This application code will inflate the menu from the {@link
    196 android.app.Activity#onCreateOptionsMenu(Menu)} callback:</p>
    197 <pre>
    198 public boolean onCreateOptionsMenu(Menu menu) {
    199   MenuInflater inflater = getMenuInflater();
    200   inflater.inflate(R.menu.example_menu, menu);
    201   return true;
    202 }
    203 </pre>
    204 </dd> <!-- end example -->
    205 
    206 
    207 </dl>