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