Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 0f6f5187 authored by Scott Main's avatar Scott Main
Browse files

docs: revise menu resources to account for action bar 

Change-Id: I40d61653e02735f6a0b47449191b71c233b36fa3
parent 691da62b

docs/html/guide/topics/resources/menu-resource.jd

+89 −55
Original line number Diff line number Diff line
@@ -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;

    &lt;<a href="#group-element">group</a> android:id="@[+][<em>package</em>:]id/<em>resource name</em>"

          android:enabled=["enabled" | "disabled"]

          android:menuCategory=["container" | "system" | "secondary" | "alternative"]

           android:orderInCategory="<em>integer</em>"

          android:orderInCategory="<em>integer</em>" /&gt;

    &lt;<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"] &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 -->