docs: revise menu resources to account for action bar

Change-Id: I40d61653e02735f6a0b47449191b71c233b36fa3

1 files changed, 89 insertions, 55 deletions

diff --git a/docs/html/guide/topics/resources/menu-resource.jd b/docs/html/guide/topics/resources/menu-resource.jd
index cde72bd..7bcd78a 100644
--- a/docs/html/guide/topics/resources/menu-resource.jd
+++ b/docs/html/guide/topics/resources/menu-resource.jd
@@ -36,22 +36,23 @@ In XML: <code>@[<em>package</em>:]menu.<em>filename</em></code>
 &lt;?xml version="1.0" encoding="utf-8"?>
 &lt;<a href="#menu-element">menu</a> xmlns:android="http://schemas.android.com/apk/res/android">
     &lt;<a href="#item-element">item</a> android:id="@[+][<em>package</em>:]id/<em>resource_name</em>"
-          android:menuCategory=["container" | "system" | "secondary" | "alternative"]
-          android:orderInCategory="<em>integer</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"] /&gt;
+          android:enabled=["enabled" | "disabled"]
+          android:menuCategory=["container" | "system" | "secondary" | "alternative"]
+          android:orderInCategory="<em>integer</em>" /&gt;
     &lt;<a href="#group-element">group</a> android:id="@[+][<em>package</em>:]id/<em>resource name</em>"
-           android:menuCategory=["container" | "system" | "secondary" | "alternative"]
-           android:orderInCategory="<em>integer</em>"
            android:checkableBehavior=["none" | "all" | "single"]
            android:visible=["visible" | "invisible" | "gone"]
-           android:enabled=["enabled" | "disabled"] &gt;
+           android:enabled=["enabled" | "disabled"]
+           android:menuCategory=["container" | "system" | "secondary" | "alternative"]
+           android:orderInCategory="<em>integer</em>" &gt;
         &lt;<a href="#item-element">item</a> /&gt;
     &lt;/group&gt;
     &lt;<a href="#item-element">item</a> &gt;
@@ -77,91 +78,120 @@ In XML: <code>@[<em>package</em>:]menu.<em>filename</em></code>
           <code>"http://schemas.android.com/apk/res/android"</code>.
       </dl>
     </dd>
-  <dt id="group-element"><code>&lt;group&gt;</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>&lt;item&gt;</code> elements. Must be a
-child of a <code>&lt;menu&gt;</code> element.
+
+  <dt id="item-element"><code>&lt;item&gt;</code></dt>
+    <dd>A menu item. May contain a <code>&lt;menu&gt;</code> element (for a Sub
+      Menu). Must be a child of a <code>&lt;menu&gt;</code> or <code>&lt;group&gt;</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>
+<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 group's priority. Valid values:
+          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 groups that are part of a
+            <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 groups that are provided by the
+            <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 groups that are user-supplied secondary
+            <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 groups that are alternative actions
+            <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 default order of the items within the category.</dd>
+          <dd><em>Integer</em>. The order of "importance" of the item, within a group.</dd>
+      </dl>
+    </dd>
+
+  <dt id="group-element"><code>&lt;group&gt;</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>&lt;item&gt;</code> elements. Must be a
+child of a <code>&lt;menu&gt;</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>
+            <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>
-      </dl>
-    </dd>
-  <dt id="item-element"><code>&lt;item&gt;</code></dt>
-    <dd>A menu item. May contain a <code>&lt;menu&gt;</code> element (for a Sub
-      Menu). Must be a child of a <code>&lt;menu&gt;</code> or <code>&lt;group&gt;</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: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:
+          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 items that are part of a
+            <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 items that are provided by the
+            <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 items that are user-supplied secondary
+            <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 items that are alternative actions
+            <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 order of "importance" of the item, within a group.</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: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>
+        <dd><em>Integer</em>. The default order of the items within the category.</dd>
       </dl>
     </dd>
 </dl>
@@ -174,7 +204,8 @@ too long.</dd>
 &lt;menu xmlns:android="http://schemas.android.com/apk/res/android">
     &lt;item android:id="@+id/item1"
           android:title="@string/item1"
-          android:icon="@drawable/group_item1_icon" />
+          android:icon="@drawable/group_item1_icon"
+          android:showAsAction="ifRoom|withText"/>
     &lt;group android:id="@+id/group">
         &lt;item android:id="@+id/group_item1"
               android:title="@string/group_item1"
@@ -184,7 +215,8 @@ too long.</dd>
               android:icon="@drawable/group_item2_icon" />
     &lt;/group>
     &lt;item android:id="@+id/submenu"
-          android:title="@string/submenu_title" >
+          android:title="@string/submenu_title"
+          android:showAsAction="ifRoom|withText" >
         &lt;menu>
             &lt;item android:id="@+id/submenu_item1"
                   android:title="@string/submenu_item1" />
@@ -201,6 +233,8 @@ public boolean onCreateOptionsMenu(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 -->