1page.title=Menu Resource 2parent.title=Resource Types 3parent.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">Menus</a></li> 11 </ol> 12 </div> 13</div> 14 15<p>A menu resource defines an application menu (Options Menu, Context Menu, or submenu) that 16can be inflated with {@link android.view.MenuInflater}.</p> 17 18<p>For a guide to using menus, see the <a href="{@docRoot}guide/topics/ui/menus.html">Menus</a> 19developer guide.</p> 20 21<dl class="xml"> 22 23<dt>file location:</dt> 24<dd><code>res/menu/<em>filename</em>.xml</code><br/> 25The filename will be used as the resource ID.</dd> 26 27<dt>compiled resource datatype:</dt> 28<dd>Resource pointer to a {@link android.view.Menu} (or subclass) resource.</dd> 29 30<dt>resource reference:</dt> 31<dd> 32In Java: <code>R.menu.<em>filename</em></code><br/> 33In XML: <code>@[<em>package</em>:]menu.<em>filename</em></code> 34</dd> 35 36<dt>syntax:</dt> 37<dd> 38<pre> 39<?xml version="1.0" encoding="utf-8"?> 40<<a href="#menu-element">menu</a> xmlns:android="http://schemas.android.com/apk/res/android"> 41 <<a href="#item-element">item</a> android:id="@[+][<em>package</em>:]id/<em>resource_name</em>" 42 android:title="<em>string</em>" 43 android:titleCondensed="<em>string</em>" 44 android:icon="@[package:]drawable/<em>drawable_resource_name</em>" 45 android:onClick="<em>method name</em>" 46 android:showAsAction=["ifRoom" | "never" | "withText" | "always" | "collapseActionView"] 47 android:actionLayout="@[package:]layout/<em>layout_resource_name</em>" 48 android:actionViewClass="<em>class name</em>" 49 android:actionProviderClass="<em>class name</em>" 50 android:alphabeticShortcut="<em>string</em>" 51 android:numericShortcut="<em>string</em>" 52 android:checkable=["true" | "false"] 53 android:visible=["true" | "false"] 54 android:enabled=["true" | "false"] 55 android:menuCategory=["container" | "system" | "secondary" | "alternative"] 56 android:orderInCategory="<em>integer</em>" /> 57 <<a href="#group-element">group</a> android:id="@[+][<em>package</em>:]id/<em>resource name</em>" 58 android:checkableBehavior=["none" | "all" | "single"] 59 android:visible=["true" | "false"] 60 android:enabled=["true" | "false"] 61 android:menuCategory=["container" | "system" | "secondary" | "alternative"] 62 android:orderInCategory="<em>integer</em>" > 63 <<a href="#item-element">item</a> /> 64 </group> 65 <<a href="#item-element">item</a> > 66 <<a href="#menu-element">menu</a>> 67 <<a href="#item-element">item</a> /> 68 </menu> 69 </item> 70</menu> 71</pre> 72</dd> 73 74<dt>elements:</dt> 75<dd> 76<dl class="tag-list"> 77 78 <dt id="menu-element"><code><menu></code></dt> 79 <dd><strong>Required.</strong> This must be the root node. Contains <code><item></code> and/or 80 <code><group></code> elements. 81 <p class="caps">attributes:</p> 82 <dl class="atn-list"> 83 <dt><code>xmlns:android</code></dt> 84 <dd><em>XML namespace</em>. <strong>Required.</strong> Defines the XML namespace, which 85must be <code>"http://schemas.android.com/apk/res/android"</code>. 86 </dl> 87 </dd> 88 89 <dt id="item-element"><code><item></code></dt> 90 <dd>A menu item. May contain a <code><menu></code> element (for a Sub 91 Menu). Must be a child of a <code><menu></code> or <code><group></code> element. 92 <p class="caps">attributes:</p> 93 <dl class="atn-list"> 94 <dt><code>android:id</code></dt> 95 <dd><em>Resource ID</em>. A unique resource ID. To create a new resource ID for this item, use the form: 96<code>"@+id/<em>name</em>"</code>. The plus symbol indicates that this should be created as a new 97ID.</dd> 98 <dt><code>android:title</code></dt> 99 <dd><em>String resource</em>. The menu title as a string resource or raw string.</dd> 100 <dt><code>android:titleCondensed</code></dt> 101 <dd><em>String resource</em>. A condensed title as a string resource or a raw string. This 102title is used for situations in which the normal title is too long.</dd> 103 104 <dt><code>android:icon</code></dt> 105 <dd><em>Drawable resource</em>. An image to be used as the menu item icon.</dd> 106 107 <dt><code>android:onClick</code></dt> 108 <dd><em>Method name</em>. The method to call when this menu item is clicked. The 109method must be declared in the activity as public and accept a {@link android.view.MenuItem} as its 110only parameter, which indicates the item clicked. This method takes precedence over the standard 111callback to {@link android.app.Activity#onOptionsItemSelected onOptionsItemSelected()}. See the 112example at the bottom. 113 <p class="warning"><strong>Warning:</strong> If you obfuscate your code using <a 114href="{@docRoot}tools/help/proguard.html">ProGuard</a> (or a similar tool), 115be sure to exclude the method you specify in this attribute from renaming, because it can break the 116functionality.</p> 117 <p>Introduced in API Level 11.</p></dd> 118 119 <dt><code>android:showAsAction</code></dt> 120 <dd><em>Keyword</em>. When and how this item should appear as an action item in the Action 121Bar. A menu item can appear as an action item only when the activity includes an {@link 122android.app.ActionBar} (introduced in API Level 11). Valid values: 123 <table> 124 <tr><th>Value</th><th>Description</th></tr> 125 <tr><td><code>ifRoom</code></td><td>Only place this item in the Action Bar if 126there is room for it.</td></tr> 127 <tr><td><code>withText</code></td><td>Also include the title text (defined 128by {@code android:title}) with the action item. You can include this value along with one 129of the others as a flag set, by separating them with a pipe {@code |}.</td></tr> 130 <tr><td><code>never</code></td><td>Never place this item in the Action Bar.</td></tr> 131 <tr><td><code>always</code></td><td>Always place this item in the Action Bar. 132Avoid using this unless it's critical that the item always appear in the action 133bar. Setting multiple items to always appear as action items can result in them overlapping 134with other UI in the action bar.</td></tr> 135 <tr><td><code>collapseActionView</code></td><td>The action view associated 136with this action item (as declared by <code>android:actionLayout</code> or 137<code>android:actionViewClass</code>) is 138collapsible.<br/>Introduced in API Level 14.</td></tr> 139 </table> 140 <p>See the <a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> developer 141guide for more information.</p> 142 <p>Introduced in API Level 11.</p> 143 </dd> 144 145 <dt><code>android:actionLayout</code></dt> 146 <dd><em>Layout resource</em>. A layout to use as the action view. 147 <p>See the <a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> developer 148guide for more information.</p> 149 <p>Introduced in API Level 11.</p></dd> 150 151 <dt><code>android:actionViewClass</code></dt> 152 <dd><em>Class name</em>. A fully-qualified class name for the {@link android.view.View} 153to use as the action view. For example, 154{@code "android.widget.SearchView"} to use {@link android.widget.SearchView} as an action view. 155 <p>See the <a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> developer 156guide for more information.</p> 157 <p class="warning"><strong>Warning:</strong> If you obfuscate your code using <a 158href="{@docRoot}tools/help/proguard.html">ProGuard</a> (or a similar tool), 159be sure to exclude the class you specify in this attribute from renaming, because it can break the 160functionality.</p> 161 <p>Introduced in API Level 11.</p></dd> 162 163 <dt><code>android:actionProviderClass</code></dt> 164 <dd><em>Class name</em>. A fully-qualified class name for the {@link 165android.view.ActionProvider} to use in place of the action item. For example, 166{@code "android.widget.ShareActionProvider"} to use {@link android.widget.ShareActionProvider}. 167 <p>See the <a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> developer 168guide for more information.</p> 169 <p class="warning"><strong>Warning:</strong> If you obfuscate your code using <a 170href="{@docRoot}tools/help/proguard.html">ProGuard</a> (or a similar tool), 171be sure to exclude the class you specify in this attribute from renaming, because it can break the 172functionality.</p> 173 <p>Introduced in API Level 14.</p></dd> 174 175 <dt><code>android:alphabeticShortcut</code></dt> 176 <dd><em>Char</em>. A character for the alphabetic shortcut key.</dd> 177 <dt><code>android:numericShortcut</code></dt> 178 <dd><em>Integer</em>. A number for the numeric shortcut key.</dd> 179 <dt><code>android:checkable</code></dt> 180 <dd><em>Boolean</em>. "true" if the item is checkable.</dd> 181 <dt><code>android:checked</code></dt> 182 <dd><em>Boolean</em>. "true" if the item is checked by default.</dd> 183 <dt><code>android:visible</code></dt> 184 <dd><em>Boolean</em>. "true" if the item is visible by default.</dd> 185 <dt><code>android:enabled</code></dt> 186 <dd><em>Boolean</em>. "true" if the item is enabled by default.</dd> 187 <dt><code>android:menuCategory</code></dt> 188 <dd><em>Keyword</em>. Value corresponding to {@link android.view.Menu} {@code CATEGORY_*} 189 constants, which define the item's priority. Valid values: 190 <table> 191 <tr><th>Value</th><th>Description</th></tr> 192 <tr><td><code>container</code></td><td>For items that are part of a 193container.</td></tr> 194 <tr><td><code>system</code></td><td>For items that are provided by the 195system.</td></tr> 196 <tr><td><code>secondary</code></td><td>For items that are user-supplied secondary 197(infrequently used) options.</td></tr> 198 <tr><td><code>alternative</code></td><td>For items that are alternative actions 199on the data that is currently displayed.</td></tr> 200 </table> 201 </dd> 202 <dt><code>android:orderInCategory</code></dt> 203 <dd><em>Integer</em>. The order of "importance" of the item, within a group.</dd> 204 </dl> 205 </dd> 206 207 <dt id="group-element"><code><group></code></dt> 208 <dd>A menu group (to create a collection of items that share traits, such as whether they are 209visible, enabled, or checkable). Contains one or more <code><item></code> elements. Must be a 210child of a <code><menu></code> element. 211 <p class="caps">attributes:</p> 212 <dl class="atn-list"> 213 <dt><code>android:id</code></dt> 214 <dd><em>Resource ID</em>. A unique resource ID. To create a new resource ID for this item, 215use the form: 216<code>"@+id/<em>name</em>"</code>. The plus symbol indicates that this should be created as a new 217ID.</dd> 218 <dt><code>android:checkableBehavior</code></dt> 219 <dd><em>Keyword</em>. The type of checkable behavior for the group. Valid values: 220 <table> 221 <tr><th>Value</th><th>Description</th></tr> 222 <tr><td><code>none</code></td><td>Not checkable</td></tr> 223 <tr><td><code>all</code></td><td>All items can be checked (use checkboxes)</td></tr> 224 <tr><td><code>single</code></td><td>Only one item can be checked (use radio 225buttons)</td></tr> 226 </table> 227 </dd> 228 <dt><code>android:visible</code></dt> 229 <dd><em>Boolean</em>. "true" if the group is visible.</dd> 230 <dt><code>android:enabled</code></dt> 231 <dd><em>Boolean</em>. "true" if the group is enabled.</dd> 232 <dt><code>android:menuCategory</code></dt> 233 <dd><em>Keyword</em>. Value corresponding to {@link android.view.Menu} {@code CATEGORY_*} 234 constants, which define the group's priority. Valid values: 235 <table> 236 <tr><th>Value</th><th>Description</th></tr> 237 <tr><td><code>container</code></td><td>For groups that are part of a 238container.</td></tr> 239 <tr><td><code>system</code></td><td>For groups that are provided by the 240system.</td></tr> 241 <tr><td><code>secondary</code></td><td>For groups that are user-supplied secondary 242(infrequently used) options.</td></tr> 243 <tr><td><code>alternative</code></td><td>For groups that are alternative actions 244on the data that is currently displayed.</td></tr> 245 </table> 246 </dd> 247 <dt><code>android:orderInCategory</code></dt> 248 <dd><em>Integer</em>. The default order of the items within the category.</dd> 249 </dl> 250 </dd> 251</dl> 252 253</dd> 254 255<dt>example:</dt> 256<dd>XML file saved at <code>res/menu/example_menu.xml</code>: 257<pre> 258<menu xmlns:android="http://schemas.android.com/apk/res/android"> 259 <item android:id="@+id/item1" 260 android:title="@string/item1" 261 android:icon="@drawable/group_item1_icon" 262 android:showAsAction="ifRoom|withText"/> 263 <group android:id="@+id/group"> 264 <item android:id="@+id/group_item1" 265 android:onClick="onGroupItemClick" 266 android:title="@string/group_item1" 267 android:icon="@drawable/group_item1_icon" /> 268 <item android:id="@+id/group_item2" 269 android:onClick="onGroupItemClick" 270 android:title="@string/group_item2" 271 android:icon="@drawable/group_item2_icon" /> 272 </group> 273 <item android:id="@+id/submenu" 274 android:title="@string/submenu_title" 275 android:showAsAction="ifRoom|withText" > 276 <menu> 277 <item android:id="@+id/submenu_item1" 278 android:title="@string/submenu_item1" /> 279 </menu> 280 </item> 281</menu> 282</pre> 283 <p>The following application code inflates the menu from the {@link 284android.app.Activity#onCreateOptionsMenu(Menu)} callback and also declares the on-click 285callback for two of the items:</p> 286<pre> 287public boolean onCreateOptionsMenu(Menu menu) { 288 MenuInflater inflater = getMenuInflater(); 289 inflater.inflate(R.menu.example_menu, menu); 290 return true; 291} 292 293public void onGroupItemClick(MenuItem item) { 294 // One of the group items (using the onClick attribute) was clicked 295 // The item parameter passed here indicates which item it is 296 // All other menu item clicks are handled by {@link android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} 297} 298</pre> 299<p class="note"><strong>Note:</strong> The {@code android:showAsAction} attribute is 300available only on Android 3.0 (API Level 11) and greater.</p> 301</dd> <!-- end example --> 302 303 304</dl>