menu-resource.jd revision 0f6f51879cf6fbb6e21e7f6e3ffd2625c5a9a5f6
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:showAsAction=["ifRoom" | "never" | "withText" | "always"] 43 android:alphabeticShortcut="<em>string</em>" 44 android:numericShortcut="<em>string</em>" 45 android:checkable=["true" | "false"] 46 android:visible=["visible" | "invisible" | "gone"] 47 android:enabled=["enabled" | "disabled"] 48 android:menuCategory=["container" | "system" | "secondary" | "alternative"] 49 android:orderInCategory="<em>integer</em>" /> 50 <<a href="#group-element">group</a> android:id="@[+][<em>package</em>:]id/<em>resource name</em>" 51 android:checkableBehavior=["none" | "all" | "single"] 52 android:visible=["visible" | "invisible" | "gone"] 53 android:enabled=["enabled" | "disabled"] 54 android:menuCategory=["container" | "system" | "secondary" | "alternative"] 55 android:orderInCategory="<em>integer</em>" > 56 <<a href="#item-element">item</a> /> 57 </group> 58 <<a href="#item-element">item</a> > 59 <<a href="#menu-element">menu</a>> 60 <<a href="#item-element">item</a> /> 61 </menu> 62 </item> 63</menu> 64</pre> 65</dd> 66 67<dt>elements:</dt> 68<dd> 69<dl class="tag-list"> 70 71 <dt id="menu-element"><code><menu></code></dt> 72 <dd><strong>Required.</strong> This must be the root node. Contains <code><item></code> and/or 73 <code><group></code> elements. 74 <p class="caps">attributes:</p> 75 <dl class="atn-list"> 76 <dt><code>xmlns:android</code></dt> 77 <dd><em>String</em>. <strong>Required.</strong> Defines the XML namespace, which must be 78 <code>"http://schemas.android.com/apk/res/android"</code>. 79 </dl> 80 </dd> 81 82 <dt id="item-element"><code><item></code></dt> 83 <dd>A menu item. May contain a <code><menu></code> element (for a Sub 84 Menu). Must be a child of a <code><menu></code> or <code><group></code> element. 85 <p class="caps">attributes:</p> 86 <dl class="atn-list"> 87 <dt><code>android:id</code></dt> 88 <dd><em>Resource ID</em>. A unique resource ID. To create a new resource ID for this item, use the form: 89<code>"@+id/<em>name</em>"</code>. The plus symbol indicates that this should be created as a new 90ID.</dd> 91 <dt><code>android:title</code></dt> 92 <dd><em>String</em>. The menu title.</dd> 93 <dt><code>android:titleCondensed</code></dt> 94 <dd><em>String</em>. A condensed title, for situations in which the normal title is 95too long.</dd> 96 <dt><code>android:icon</code></dt> 97 <dd><em>Drawable resource</em>. An image to be used as the menu item icon.</dd> 98 99 <dt><code>android:showAsAction</code></dt> 100 <dd><em>Keyword</em>. When and how this item should appear as an action item in the Action 101Bar. A menu item can appear as an action item only when the activity includes an {@link 102android.app.ActionBar} (introduced in API Level HONEYCOMB). Valid values: 103 <table> 104 <tr><th>Value</th><th>Description</th></tr> 105 <tr><td><code>ifRoom</code></td><td>Only place this item in the Action Bar if 106there is room for it.</td></tr> 107 <tr><td><code>withText</code></td><td>Also include the title text (defined 108by {@code android:title}) with the action item. You can include this value along with one 109of the others as a flag set, by separating them with a pipe {@code |}.</td></tr> 110 <tr><td><code>never</code></td><td>Never place this item in the Action Bar.</td></tr> 111 <tr><td><code>always</code></td><td>Always place this item in the Action Bar. 112Avoid using this unless it's critical that the item always appear in the action 113bar. Setting multiple items to always appear as action items can result in them overlapping 114with other UI in the action bar.</td></tr> 115 </table> 116 <p>See <a href="{@docRoot}guide/topics/ui/actionbar.html">Using the Action Bar</a> for 117more information.</p> 118 <p>Introduced in API Level HONEYCOMB.</p> 119 </dd> 120 121 <dt><code>android:alphabeticShortcut</code></dt> 122 <dd><em>Char</em>. A character for the alphabetic shortcut key.</dd> 123 <dt><code>android:numericShortcut</code></dt> 124 <dd><em>Integer</em>. A number for the numeric shortcut key.</dd> 125 <dt><code>android:checkable</code></dt> 126 <dd><em>Boolean</em>. "true" if the item is checkable.</dd> 127 <dt><code>android:checked</code></dt> 128 <dd><em>Boolean</em>. "true" if the item is checked by default.</dd> 129 <dt><code>android:visible</code></dt> 130 <dd><em>Boolean</em>. "true" if the item is visible by default.</dd> 131 <dt><code>android:enabled</code></dt> 132 <dd><em>Boolean</em>. "true" if the item is enabled by default.</dd> 133 <dt><code>android:menuCategory</code></dt> 134 <dd><em>Keyword</em>. Value corresponding to {@link android.view.Menu} {@code CATEGORY_*} 135 constants, which define the item's priority. Valid values: 136 <table> 137 <tr><th>Value</th><th>Description</th></tr> 138 <tr><td><code>container</code></td><td>For items that are part of a 139container.</td></tr> 140 <tr><td><code>system</code></td><td>For items that are provided by the 141system.</td></tr> 142 <tr><td><code>secondary</code></td><td>For items that are user-supplied secondary 143(infrequently used) options.</td></tr> 144 <tr><td><code>alternative</code></td><td>For items that are alternative actions 145on the data that is currently displayed.</td></tr> 146 </table> 147 </dd> 148 <dt><code>android:orderInCategory</code></dt> 149 <dd><em>Integer</em>. The order of "importance" of the item, within a group.</dd> 150 </dl> 151 </dd> 152 153 <dt id="group-element"><code><group></code></dt> 154 <dd>A menu group (to create a collection of items that share traits, such as whether they are 155visible, enabled, or checkable). Contains one or more <code><item></code> elements. Must be a 156child of a <code><menu></code> element. 157 <p class="caps">attributes:</p> 158 <dl class="atn-list"> 159 <dt><code>android:id</code></dt> 160 <dd><em>Resource ID</em>. A unique resource ID. To create a new resource ID for this item, 161use the form: 162<code>"@+id/<em>name</em>"</code>. The plus symbol indicates that this should be created as a new 163ID.</dd> 164 <dt><code>android:checkableBehavior</code></dt> 165 <dd><em>Keyword</em>. The type of checkable behavior for the group. Valid values: 166 <table> 167 <tr><th>Value</th><th>Description</th></tr> 168 <tr><td><code>none</code></td><td>Not checkable</td></tr> 169 <tr><td><code>all</code></td><td>All items can be checked (use checkboxes)</td></tr> 170 <tr><td><code>single</code></td><td>Only one item can be checked (use radio 171buttons)</td></tr> 172 </table> 173 </dd> 174 <dt><code>android:visible</code></dt> 175 <dd><em>Boolean</em>. "true" if the group is visible.</dd> 176 <dt><code>android:enabled</code></dt> 177 <dd><em>Boolean</em>. "true" if the group is enabled.</dd> 178 <dt><code>android:menuCategory</code></dt> 179 <dd><em>Keyword</em>. Value corresponding to {@link android.view.Menu} {@code CATEGORY_*} 180 constants, which define the group's priority. Valid values: 181 <table> 182 <tr><th>Value</th><th>Description</th></tr> 183 <tr><td><code>container</code></td><td>For groups that are part of a 184container.</td></tr> 185 <tr><td><code>system</code></td><td>For groups that are provided by the 186system.</td></tr> 187 <tr><td><code>secondary</code></td><td>For groups that are user-supplied secondary 188(infrequently used) options.</td></tr> 189 <tr><td><code>alternative</code></td><td>For groups that are alternative actions 190on the data that is currently displayed.</td></tr> 191 </table> 192 </dd> 193 <dt><code>android:orderInCategory</code></dt> 194 <dd><em>Integer</em>. The default order of the items within the category.</dd> 195 </dl> 196 </dd> 197</dl> 198 199</dd> 200 201<dt>example:</dt> 202<dd>XML file saved at <code>res/menu/example_menu.xml</code>: 203<pre> 204<menu xmlns:android="http://schemas.android.com/apk/res/android"> 205 <item android:id="@+id/item1" 206 android:title="@string/item1" 207 android:icon="@drawable/group_item1_icon" 208 android:showAsAction="ifRoom|withText"/> 209 <group android:id="@+id/group"> 210 <item android:id="@+id/group_item1" 211 android:title="@string/group_item1" 212 android:icon="@drawable/group_item1_icon" /> 213 <item android:id="@+id/group_item2" 214 android:title="G@string/group_item2" 215 android:icon="@drawable/group_item2_icon" /> 216 </group> 217 <item android:id="@+id/submenu" 218 android:title="@string/submenu_title" 219 android:showAsAction="ifRoom|withText" > 220 <menu> 221 <item android:id="@+id/submenu_item1" 222 android:title="@string/submenu_item1" /> 223 </menu> 224 </item> 225</menu> 226</pre> 227 <p>This application code will inflate the menu from the {@link 228android.app.Activity#onCreateOptionsMenu(Menu)} callback:</p> 229<pre> 230public boolean onCreateOptionsMenu(Menu menu) { 231 MenuInflater inflater = getMenuInflater(); 232 inflater.inflate(R.menu.example_menu, menu); 233 return true; 234} 235</pre> 236<p class="note"><strong>Note:</strong> The {@code android:showAsAction} attribute is 237available only on Android X.X (API Level HONEYCOMB) and greater.</p> 238</dd> <!-- end example --> 239 240 241</dl>