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">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 16 can 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> 19 developer guide.</p> 20 21 <dl class="xml"> 22 23 <dt>file location:</dt> 24 <dd><code>res/menu/<em>filename</em>.xml</code><br/> 25 The 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> 32 In Java: <code>R.menu.<em>filename</em></code><br/> 33 In 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 85 must 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 97 ID.</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 102 title 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 109 method must be declared in the activity as public and accept a {@link android.view.MenuItem} as its 110 only parameter, which indicates the item clicked. This method takes precedence over the standard 111 callback to {@link android.app.Activity#onOptionsItemSelected onOptionsItemSelected()}. See the 112 example at the bottom. 113 <p class="warning"><strong>Warning:</strong> If you obfuscate your code using <a 114 href="{@docRoot}tools/help/proguard.html">ProGuard</a> (or a similar tool), 115 be sure to exclude the method you specify in this attribute from renaming, because it can break the 116 functionality.</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 app 121 bar. A menu item can appear as an action item only when the activity includes an 122 app bar. 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 126 app bar if there is room for it. If there is not room for all 127 the items marked <code>"ifRoom"</code>, the items with the lowest 128 <code>orderInCategory</code> values are displayed as actions, and 129 the remaining items are displayed in the overflow menu.</td></tr> 130 <tr><td><code>withText</code></td><td>Also include the title text (defined 131 by {@code android:title}) with the action item. You can include this value along with one 132 of the others as a flag set, by separating them with a pipe {@code |}.</td></tr> 133 <tr><td><code>never</code></td><td>Never place this item in the app bar. Instead, list the item in the app bar's overflow 134 menu.</td></tr> 135 <tr><td><code>always</code></td><td>Always place this item in the app bar. 136 Avoid using this unless it's critical that the item always appear in the action 137 bar. Setting multiple items to always appear as action items can result in them overlapping 138 with other UI in the app bar.</td></tr> 139 <tr><td><code>collapseActionView</code></td><td>The action view associated 140 with this action item (as declared by <code>android:actionLayout</code> or 141 <code>android:actionViewClass</code>) is 142 collapsible.<br/>Introduced in API Level 14.</td></tr> 143 </table> 144 <p>See the <a href="{@docRoot}training/appbar/index.html">Adding the App Bar</a> 145 training class for more information.</p> 146 <p>Introduced in API Level 11.</p> 147 </dd> 148 149 <dt><code>android:actionLayout</code></dt> 150 <dd><em>Layout resource</em>. A layout to use as the action view. 151 <p>See <a href="{@docRoot}training/appbar/action-views.html">Action 152 Views and Action Providers</a> for more information.</p> 153 <p>Introduced in API Level 11.</p></dd> 154 155 <dt><code>android:actionViewClass</code></dt> 156 <dd><em>Class name</em>. A fully-qualified class name for the {@link android.view.View} 157 to use as the action view. For example, 158 {@code "android.widget.SearchView"} to use {@link android.widget.SearchView} as an action view. 159 <p>See <a href="{@docRoot}training/appbar/action-views.html">Action 160 Views and Action Providers</a> for more information.</p> 161 <p class="warning"><strong>Warning:</strong> If you obfuscate your code using <a 162 href="{@docRoot}tools/help/proguard.html">ProGuard</a> (or a similar tool), 163 be sure to exclude the class you specify in this attribute from renaming, because it can break the 164 functionality.</p> 165 <p>Introduced in API Level 11.</p></dd> 166 167 <dt><code>android:actionProviderClass</code></dt> 168 <dd><em>Class name</em>. A fully-qualified class name for the {@link 169 android.view.ActionProvider} to use in place of the action item. For example, 170 {@code "android.widget.ShareActionProvider"} to use {@link android.widget.ShareActionProvider}. 171 <p>See <a href="{@docRoot}training/appbar/action-views.html">Action 172 Views and Action Providers</a> for more information.</p> 173 <p class="warning"><strong>Warning:</strong> If you obfuscate your code using <a 174 href="{@docRoot}tools/help/proguard.html">ProGuard</a> (or a similar tool), 175 be sure to exclude the class you specify in this attribute from renaming, because it can break the 176 functionality.</p> 177 <p>Introduced in API Level 14.</p></dd> 178 179 <dt><code>android:alphabeticShortcut</code></dt> 180 <dd><em>Char</em>. A character for the alphabetic shortcut key.</dd> 181 <dt><code>android:numericShortcut</code></dt> 182 <dd><em>Integer</em>. A number for the numeric shortcut key.</dd> 183 <dt><code>android:checkable</code></dt> 184 <dd><em>Boolean</em>. "true" if the item is checkable.</dd> 185 <dt><code>android:checked</code></dt> 186 <dd><em>Boolean</em>. "true" if the item is checked by default.</dd> 187 <dt><code>android:visible</code></dt> 188 <dd><em>Boolean</em>. "true" if the item is visible by default.</dd> 189 <dt><code>android:enabled</code></dt> 190 <dd><em>Boolean</em>. "true" if the item is enabled by default.</dd> 191 <dt><code>android:menuCategory</code></dt> 192 <dd><em>Keyword</em>. Value corresponding to {@link android.view.Menu} {@code CATEGORY_*} 193 constants, which define the item's priority. Valid values: 194 <table> 195 <tr><th>Value</th><th>Description</th></tr> 196 <tr><td><code>container</code></td><td>For items that are part of a 197 container.</td></tr> 198 <tr><td><code>system</code></td><td>For items that are provided by the 199 system.</td></tr> 200 <tr><td><code>secondary</code></td><td>For items that are user-supplied secondary 201 (infrequently used) options.</td></tr> 202 <tr><td><code>alternative</code></td><td>For items that are alternative actions 203 on the data that is currently displayed.</td></tr> 204 </table> 205 </dd> 206 <dt><code>android:orderInCategory</code></dt> 207 <dd><em>Integer</em>. The order of "importance" of the item, within a group.</dd> 208 </dl> 209 </dd> 210 211 <dt id="group-element"><code><group></code></dt> 212 <dd>A menu group (to create a collection of items that share traits, such as whether they are 213 visible, enabled, or checkable). Contains one or more <code><item></code> elements. Must be a 214 child of a <code><menu></code> element. 215 <p class="caps">attributes:</p> 216 <dl class="atn-list"> 217 <dt><code>android:id</code></dt> 218 <dd><em>Resource ID</em>. A unique resource ID. To create a new resource ID for this item, 219 use the form: 220 <code>"@+id/<em>name</em>"</code>. The plus symbol indicates that this should be created as a new 221 ID.</dd> 222 <dt><code>android:checkableBehavior</code></dt> 223 <dd><em>Keyword</em>. The type of checkable behavior for the group. Valid values: 224 <table> 225 <tr><th>Value</th><th>Description</th></tr> 226 <tr><td><code>none</code></td><td>Not checkable</td></tr> 227 <tr><td><code>all</code></td><td>All items can be checked (use checkboxes)</td></tr> 228 <tr><td><code>single</code></td><td>Only one item can be checked (use radio 229 buttons)</td></tr> 230 </table> 231 </dd> 232 <dt><code>android:visible</code></dt> 233 <dd><em>Boolean</em>. "true" if the group is visible.</dd> 234 <dt><code>android:enabled</code></dt> 235 <dd><em>Boolean</em>. "true" if the group is enabled.</dd> 236 <dt><code>android:menuCategory</code></dt> 237 <dd><em>Keyword</em>. Value corresponding to {@link android.view.Menu} {@code CATEGORY_*} 238 constants, which define the group's priority. Valid values: 239 <table> 240 <tr><th>Value</th><th>Description</th></tr> 241 <tr><td><code>container</code></td><td>For groups that are part of a 242 container.</td></tr> 243 <tr><td><code>system</code></td><td>For groups that are provided by the 244 system.</td></tr> 245 <tr><td><code>secondary</code></td><td>For groups that are user-supplied secondary 246 (infrequently used) options.</td></tr> 247 <tr><td><code>alternative</code></td><td>For groups that are alternative actions 248 on the data that is currently displayed.</td></tr> 249 </table> 250 </dd> 251 <dt><code>android:orderInCategory</code></dt> 252 <dd><em>Integer</em>. The default order of the items within the category.</dd> 253 </dl> 254 </dd> 255 </dl> 256 257 </dd> 258 259 <dt>example:</dt> 260 <dd>XML file saved at <code>res/menu/example_menu.xml</code>: 261 <pre> 262 <menu xmlns:android="http://schemas.android.com/apk/res/android"> 263 <item android:id="@+id/item1" 264 android:title="@string/item1" 265 android:icon="@drawable/group_item1_icon" 266 android:showAsAction="ifRoom|withText"/> 267 <group android:id="@+id/group"> 268 <item android:id="@+id/group_item1" 269 android:onClick="onGroupItemClick" 270 android:title="@string/group_item1" 271 android:icon="@drawable/group_item1_icon" /> 272 <item android:id="@+id/group_item2" 273 android:onClick="onGroupItemClick" 274 android:title="@string/group_item2" 275 android:icon="@drawable/group_item2_icon" /> 276 </group> 277 <item android:id="@+id/submenu" 278 android:title="@string/submenu_title" 279 android:showAsAction="ifRoom|withText" > 280 <menu> 281 <item android:id="@+id/submenu_item1" 282 android:title="@string/submenu_item1" /> 283 </menu> 284 </item> 285 </menu> 286 </pre> 287 <p>The following application code inflates the menu from the {@link 288 android.app.Activity#onCreateOptionsMenu(Menu)} callback and also declares the on-click 289 callback for two of the items:</p> 290 <pre> 291 public boolean onCreateOptionsMenu(Menu menu) { 292 MenuInflater inflater = getMenuInflater(); 293 inflater.inflate(R.menu.example_menu, menu); 294 return true; 295 } 296 297 public void onGroupItemClick(MenuItem item) { 298 // One of the group items (using the onClick attribute) was clicked 299 // The item parameter passed here indicates which item it is 300 // All other menu item clicks are handled by {@link android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} 301 } 302 </pre> 303 304 </dd> <!-- end example --> 305 306 307 </dl> 308
