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