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&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: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>" /&gt;
50    &lt;<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>" &gt;
56        &lt;<a href="#item-element">item</a> /&gt;
57    &lt;/group&gt;
58    &lt;<a href="#item-element">item</a> &gt;
59        &lt;<a href="#menu-element">menu</a>&gt;
60          &lt;<a href="#item-element">item</a> /&gt;
61        &lt;/menu&gt;
62    &lt;/item&gt;
63&lt;/menu&gt;
64</pre>
65</dd>
66
67<dt>elements:</dt>
68<dd>
69<dl class="tag-list">
70
71  <dt id="menu-element"><code>&lt;menu&gt;</code></dt>
72    <dd><strong>Required.</strong> This must be the root node. Contains <code>&lt;item></code> and/or
73      <code>&lt;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>&lt;item&gt;</code></dt>
83    <dd>A menu item. May contain a <code>&lt;menu&gt;</code> element (for a Sub
84      Menu). Must be a child of a <code>&lt;menu&gt;</code> or <code>&lt;group&gt;</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>&lt;group&gt;</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>&lt;item&gt;</code> elements. Must be a
156child of a <code>&lt;menu&gt;</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&lt;menu xmlns:android="http://schemas.android.com/apk/res/android">
205    &lt;item android:id="@+id/item1"
206          android:title="@string/item1"
207          android:icon="@drawable/group_item1_icon"
208          android:showAsAction="ifRoom|withText"/>
209    &lt;group android:id="@+id/group">
210        &lt;item android:id="@+id/group_item1"
211              android:title="@string/group_item1"
212              android:icon="@drawable/group_item1_icon" />
213        &lt;item android:id="@+id/group_item2"
214              android:title="G@string/group_item2"
215              android:icon="@drawable/group_item2_icon" />
216    &lt;/group>
217    &lt;item android:id="@+id/submenu"
218          android:title="@string/submenu_title"
219          android:showAsAction="ifRoom|withText" >
220        &lt;menu>
221            &lt;item android:id="@+id/submenu_item1"
222                  android:title="@string/submenu_item1" />
223        &lt;/menu>
224    &lt;/item>
225&lt;/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>