update menu dev guide with more info about action bar

Change-Id: I5b0b052c96b23a395a669b1c3da11dc87f625f25

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

@@ -12,9 +12,12 @@ parent.link=available-resources.html
   </div>
 </div>
 
-<p>A menu resource defines an application menu (Options Menu, Context Menu, or Sub Menu) that
+<p>A menu resource defines an application menu (Options Menu, Context Menu, or submenu) that
 can be inflated with {@link android.view.MenuInflater}.</p>
 
+<p>For a guide to using menus, see the <a href="{@docRoot}guide/topics/ui/menus.html">Creating
+Menus</a> document.</p>
+
 <dl class="xml">
 
 <dt>file location:</dt>
@@ -110,12 +113,12 @@ example at the bottom.
 href="{@docRoot}guide/developing/tools/proguard.html">ProGuard</a> (or a similar tool),
 be sure to exclude the method you specify in this attribute from renaming, because it can break the
 functionality.</p>
-          <p>Introduced in API Level HONEYCOMB.</p></dd>
+          <p>Introduced in API Level 11.</p></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:
+android.app.ActionBar} (introduced in API Level 11). 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
@@ -131,14 +134,14 @@ 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>
+          <p>Introduced in API Level 11.</p>
         </dd>
 
         <dt><code>android:actionViewLayout</code></dt>
           <dd><em>Layout resource</em>. A layout to use as the action view.
           <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>
+          <p>Introduced in API Level 11.</p></dd>
 
         <dt><code>android:actionViewClassName</code></dt>
           <dd><em>Class name</em>. A fully-qualified class name for the {@link android.view.View}
@@ -149,7 +152,7 @@ more information.</p>
 href="{@docRoot}guide/developing/tools/proguard.html">ProGuard</a> (or a similar tool),
 be sure to exclude the class you specify in this attribute from renaming, because it can break the
 functionality.</p>
-          <p>Introduced in API Level HONEYCOMB.</p></dd>
+          <p>Introduced in API Level 11.</p></dd>
 
 
         <dt><code>android:alphabeticShortcut</code></dt>
@@ -277,7 +280,7 @@ public void onGroupItemClick(MenuItem item) {
 }
 </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>
+available only on Android 3.0 (API Level 11) and greater.</p>
 </dd> <!-- end example -->
 
 

docs/html/guide/topics/ui/menus.jd

@@ -7,11 +7,11 @@ parent.link=index.html
 <div id="qv">
   <h2>In this document</h2>
   <ol>
-    <li><a href="#xml">Defining Menus</a></li>
+    <li><a href="#xml">Creating a Menu Resource</a></li>
     <li><a href="#Inflating">Inflating a Menu Resource</a>
     <li><a href="#options-menu">Creating an Options Menu</a>
       <ol>
-        <li><a href="#ChangingTheMenu">Changing the menu when it opens</a></li>
+        <li><a href="#ChangingTheMenu">Changing menu items at runtime</a></li>
       </ol>
     </li>
     <li><a href="#context-menu">Creating a Context Menu</a></li>
@@ -21,7 +21,7 @@ parent.link=index.html
         <li><a href="#groups">Menu groups</a></li>
         <li><a href="#checkable">Checkable menu items</a></li>
         <li><a href="#shortcuts">Shortcut keys</a></li>
-        <li><a href="#intents">Intents for menu items</a></li>
+        <li><a href="#intents">Dynamically adding menu intents</a></li>
       </ol>
     </li>
   </ol>
@@ -42,52 +42,60 @@ parent.link=index.html
 </div>
 </div>
 
-<p>Menus are an important part of an application that provide a familiar interface for the user
+<p>Menus are an important part of an activity's user interface, which provide users a familiar
-to access application functions and settings. Android offers an easy programming interface
+way to perform actions. Android offers a simple framework for you to add standard
-for you to provide application menus in your application.</p>
+menus to your application.</p>
 
-<p>Android provides three types of application menus:</p>
+<p>There are three types of application menus:</p>
 <dl>
   <dt><strong>Options Menu</strong></dt>
-    <dd>The primary collection of menu items for an Activity that is associated with the device MENU
+    <dd>The primary collection of menu items for an activity, which appears when the user touches
-key. To provide instant access to select menu items, you can place some items in the <a
+the MENU button. When your application is running on Android 3.0 or later, you can provide
-href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a>, if available.</dd>
+quick access to select menu items by placing them directly in the <a
+href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a>, as "action items."</dd>
   <dt><strong>Context Menu</strong></dt>
-    <dd>A floating list of menu items that appears when the user performs a long-press on a View.
+    <dd>A floating list of menu items that appears when the user touches and holds a view
+that's registered to provide a context menu.
 </dd>
   <dt><strong>Submenu</strong></dt>
-    <dd>A floating list of menu items that the user opens by pressing a menu item in the Options
+    <dd>A floating list of menu items that appears when the user touches a menu item that contains
-Menu or a context menu. A submenu item cannot support a nested submenu. </dd>
+a nested menu.</dd>
 </dl>
 
+<p>This document shows you how to create each type of menu, using XML to define the content of
+the menu and callback methods in your activity to respond when the user selects an item.</p>
 
 
-<h2 id="xml">Defining Menus</h2>
+
+<h2 id="xml">Creating a Menu Resource</h2>
 
 <p>Instead of instantiating a {@link android.view.Menu} in your application code, you should
 define a menu and all its items in an XML <a
 href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a>, then inflate the menu
-resource (load it as a programmable object) in your application code. Defining your menus in XML is
+resource (load it as a programmable object) in your application code. Using a menu resource to
-a good practice because it separates your interface design from your application code (the same as
+define your menu is a good practice because it separates the content for the menu from your
-when you <a href="{@docRoot}guide/topics/ui/declaring-layout.html">define your Activity
+application code. It's also easier to visualize the structure and content of a menu in XML.</p>
-layout</a>).</p>
 
-<p>To define a menu, create an XML file inside your project's <code>res/menu/</code>
+<p>To create a menu resource, create an XML file inside your project's <code>res/menu/</code>
 directory and build the menu with the following elements:</p>
 <dl>
   <dt><code>&lt;menu></code></dt>
-    <dd>Creates a {@link android.view.Menu}, which is a container for menu items. It must be
+    <dd>Defines a {@link android.view.Menu}, which is a container for menu items. A
-the root node and holds one or more of the following elements. You can also nest this element
+<code>&lt;menu></code> element must be the root node for the file and can hold one or more
-in an {@code &lt;item&gt;} to create a submenu.</dd>
+<code>&lt;item></code> and <code>&lt;group></code> elements.</dd>
+
   <dt><code>&lt;item></code></dt>
-    <dd>Creates a {@link android.view.MenuItem}, which represents a single item in a menu.</dd>
+    <dd>Creates a {@link android.view.MenuItem}, which represents a single item in a menu. This
+element may contain a nested <code>&lt;menu></code> element in order to create a submenu.</dd>
+    
   <dt><code>&lt;group></code></dt>
     <dd>An optional, invisible container for {@code &lt;item&gt;} elements. It allows you to
-categorize menu items so they share properties such as active state and visibility. See <a
+categorize menu items so they share properties such as active state and visibility. See the
-href="#groups">Menu groups</a>.</dd>
+section about <a href="#groups">Menu groups</a>.</dd>
 </dl>
 
-<p>For example, here is a file in <code>res/menu/</code> named <code>game_menu.xml</code>:</p>
+
+<p>Here's an example menu named <code>game_menu.xml</code>:</p>
 <pre>
 &lt;?xml version="1.0" encoding="utf-8"?&gt;
 &lt;menu xmlns:android="http://schemas.android.com/apk/res/android"&gt;
@@ -100,28 +108,33 @@ href="#groups">Menu groups</a>.</dd>
 &lt;/menu&gt;
 </pre>
 
-<p>This example defines a menu with two menu items. Each item includes the attributes:</p>
+<p>This example defines a menu with two items. Each item includes the attributes:</p>
 <dl>
   <dt>{@code android:id}</dt>
-    <dd>A resource ID that's unique to the item so that the application can recognize the item when
+    <dd>A resource ID that's unique to the item, which allows the application can recognize the item
-the user selects it.</dd>
+when the user selects it.</dd>
   <dt>{@code android:icon}</dt>
-    <dd>A drawable resource that is the icon visible to the user.</dd>
+    <dd>A reference to a drawable to use as the item's icon.</dd>
   <dt>{@code android:title}</dt>
-    <dd>A string resource that is the title visible to the user.</dd>
+    <dd>A reference to a string to use as the item's title.</dd>
 </dl>
 
-<p>For more about the XML syntax and attributes for a menu resource, see the <a
+<p>There are many more attributes you can include in an {@code &lt;item&gt;}, including some that
+ specify how the item may appear in the <a
+href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a>. For more information about the XML
+syntax and attributes for a menu resource, see the <a
 href="{@docRoot}guide/topics/resources/menu-resource.html">Menu Resource</a> reference.</p>
 
 
+
 <h2 id="Inflating">Inflating a Menu Resource</h2>
 
-<p>You can inflate your menu resource (convert the XML resource into a programmable object) using
+<p>From your application code, you can inflate a menu resource (convert the XML resource into a
+programmable object) using
 {@link android.view.MenuInflater#inflate(int,Menu) MenuInflater.inflate()}. For
-example, the following code inflates the <code>game_menu.xml</code> file defined above during the
+example, the following code inflates the <code>game_menu.xml</code> file defined above, during the
-{@link android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} callback method, to be
+{@link android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} callback method, to
-used for the Options Menu:</p>
+use the menu as the activity's Options Menu:</p>
 
 <pre>
 &#64;Override
@@ -133,59 +146,47 @@ public boolean onCreateOptionsMenu(Menu menu) {
 </pre>
 
 <p>The {@link android.app.Activity#getMenuInflater()} method returns a {@link
-android.view.MenuInflater} for the Activity. With this object, you can call {@link
+android.view.MenuInflater} for the activity. With this object, you can call {@link
 android.view.MenuInflater#inflate(int,Menu) inflate()}, which inflates a menu resource into a
 {@link android.view.Menu} object. In this example, the menu resource defined by
 <code>game_menu.xml</code>
 is inflated into the {@link android.view.Menu} that was passed into {@link
 android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()}. (This callback method for
-creating an option menu is discussed more in the next section.)</p>
+the Options Menu is discussed more in the next section.)</p>
 
 
 
 <h2 id="options-menu">Creating an Options Menu</h2>
 
 <div class="figure" style="width:200px">
-  <img src="{@docRoot}images/options_menu.png" height="300" alt="" />
+  <img src="{@docRoot}images/options_menu.png" height="333" alt="" />
-  <p class="img-caption"><strong>Figure 1.</strong> Screenshot of an Options Menu.</p>
+  <p class="img-caption"><strong>Figure 1.</strong> Screenshot of the Options Menu in the
+Browser.</p>
 </div>
 
-
+<p>The Options Menu is where you should include basic activity actions and necessary navigation
-<p>The Options Menu is where you should include basic application functions and necessary navigation
 items (for example, a button to open the application settings). Items in the Options Menu are
-accessible in two distinct ways: in the Action Bar and in the menu revealed by the MENU
+accessible in two distinct ways: the MENU button or in the <a
-key.</p>
+href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> (on devices running Android 3.0
+or higher).</p>
 
-<p>The Action Bar is an optional widget that appears at the top of the activity in place of the
+<p>When running on a device with Android 2.3 and lower, the Options Menu appears at the bottom of
-title bar. It can display several menu items that you choose from the Options Menu, but items in
+the screen, as shown in figure 1. When opened, the first visible portion of the Options Menu is
-the Action Bar display only an icon (no title text). Users can reveal the other menu items in the
+the icon menu. It holds the first six menu items. If you add more than six items to the
-Options Menu with the MENU key.</p>
+Options Menu, Android places the sixth item and those after it into the overflow menu, which the
+user can open by touching the "More" menu item.</p>
 
-<p>If you include the Action Bar in your activity, the menu items that are not placed in the Action
+<p>On Android 3.0 and higher, items from the Options Menu is placed in the Action Bar, which appears
-Bar can appear in two different styles:</p>
+at the top of the activity in place of the traditional title bar. By default all items from the
-<dl>
+Options Menu are placed in the overflow menu, which the user can open by touching the menu icon
-  <dt>Action Bar Menu</dt>
+on the right side of the Action Bar. However, you can place select menu items directly in the
-    <dd>If the device has an extra-large screen ({@code xlarge}), then all items in the Options Menu
+Action Bar as "action items," for instant access, as shown in figure 2.</p>
-that are not placed in the Action Bar are placed into a drop-down list at the right side of the
-Action Bar, with icons and title text. The user can reveal the drop-down list by pressing the
-drop-down icon in the Action Bar or the MENU key.</dd>
-  <dt>Standard Options Menu</dt>
-    <dd>If the device <em>does not</em> have an extra-large screen, then all items in the Options
-Menu that are not placed in the Action Bar are placed into the Standard Options Menu at the bottom
-of the activity. The user can reveal the standard Options Menu by pressing the MENU key.
-    <p>The first visible portion of the Standard Options Menu is called the Icon Menu.
-It holds the first six menu items (excluding any added to the Action Bar), with icons and title
-text. If there are more than six items, Android adds a "More" item as the sixth menu item and places
-the remaining items into the Expanded Menu, which the user can open by selecting "More". The
-Expanded Menu displays menu items only by their title text (no icon)</p>
-    </dd>
-</dl>
 
-<p>When the user opens the Options Menu for the first time, Android calls your Activity's
+<p>When the Android system creates the Options Menu for the first time, it calls your
-{@link android.app.Activity#onCreateOptionsMenu(Menu)
+activity's {@link android.app.Activity#onCreateOptionsMenu(Menu)
-onCreateOptionsMenu()} method. Override this method in your Activity
+onCreateOptionsMenu()} method. Override this method in your activity
-and populate the {@link android.view.Menu} that is passed into the method. Populate the
+and populate the {@link android.view.Menu} that is passed into the method,
-{@link android.view.Menu} by inflating a menu resource as described in <a
+{@link android.view.Menu} by inflating a menu resource as described above in <a
 href="#Inflating">Inflating a Menu Resource</a>. For example:</p>
 
 <pre>
@@ -197,17 +198,31 @@ public boolean onCreateOptionsMenu(Menu menu) {
 }
 </pre>
 
-<p>(You can also populate the menu in code, using {@link android.view.Menu#add(int,int,int,int)
+<div class="figure" style="width:500px">
-add()} to add items to the {@link android.view.Menu}.)</p>
+<img src="{@docRoot}images/ui/actionbar.png" height="34" alt="" />
+<p class="img-caption"><strong>Figure 2.</strong> Screenshot of the Action Bar in the Email
+application, with two action items from the Options Menu, plus the overflow menu.</p>
+</div>
 
-<p>When the user selects a menu item from the Options Menu (including items selected from the
+<p>You can also populate the menu in code, using {@link android.view.Menu#add(int,int,int,int)
-Action Bar), the system calls your Activity's
+add()} to add items to the {@link android.view.Menu}.</p>
+
+<p class="note"><strong>Note:</strong> On Android 2.3 and lower, the system calls {@link
+android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} to create the Options Menu
+when the user opens it for the first time, but on Android 3.0 and greater, the system creates it as
+soon as the activity is created, in order to populate the Action Bar.</p>
+
+
+<h3 id="RespondingOptionsMenu">Responding to user action</h3>
+
+<p>When the user selects a menu item from the Options Menu (including action items in the
+Action Bar), the system calls your activity's
 {@link android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()}
 method. This method passes the
 {@link android.view.MenuItem} that the user selected. You can identify the menu item by calling
 {@link android.view.MenuItem#getItemId()}, which returns the unique ID for the menu
-item (defined by the {@code android:id} attribute in the menu resource or with an integer passed
+item (defined by the {@code android:id} attribute in the menu resource or with an integer
-to the {@link android.view.Menu#add(int,int,int,int) add()} method). You can match this ID
+given to the {@link android.view.Menu#add(int,int,int,int) add()} method). You can match this ID
 against known menu items and perform the appropriate action. For example:</p>
 
 <pre>
@@ -229,45 +244,67 @@ public boolean onOptionsItemSelected(MenuItem item) {
 
 <p>In this example, {@link android.view.MenuItem#getItemId()} queries the ID for the selected menu
 item and the switch statement compares the ID against the resource IDs that were assigned to menu
-items in the XML resource. When a switch case successfully handles the item, it
+items in the XML resource. When a switch case successfully handles the menu item, it
-returns "true" to indicate that the item selection was handled. Otherwise, the default statement
+returns {@code true} to indicate that the item selection was handled. Otherwise, the default
-passes the menu item to the super class in
+statement passes the menu item to the super class, in
 case it can handle the item selected. (If you've directly extended the {@link android.app.Activity}
-class, then the super class returns "false", but it's a good practice to
+class, then the super class returns {@code false}, but it's a good practice to
-pass unhandled menu items to the super class instead of directly returning "false".)</p>
+pass unhandled menu items to the super class instead of directly returning {@code false}.)</p>
+
+<p>Additionally, Android 3.0 adds the ability for you to define the on-click behavior for a menu
+item in the <a href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a> XML,
+using the {@code android:onClick} attribute. So you don't need to implement {@link
+android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()}. Using the {@code
+android:onClick} attribute, you can specify a method to call when the user selects the menu item.
+Your activity must then implement the method specified in the {@code android:onClick} attribute so 
+that it accepts a single {@link android.view.MenuItem} parameter&mdash;when the system calls this
+method, it passes the menu item selected.</p>
 
 <p class="note"><strong>Tip:</strong> If your application contains multiple activities and
 some of them provide the same Options Menu, consider creating
-an Activity that implements nothing except the {@link android.app.Activity#onCreateOptionsMenu(Menu)
+an activity that implements nothing except the {@link android.app.Activity#onCreateOptionsMenu(Menu)
 onCreateOptionsMenu()} and {@link android.app.Activity#onOptionsItemSelected(MenuItem)
-onOptionsItemSelected()} methods. Then extend this class for each Activity that should share the
+onOptionsItemSelected()} methods. Then extend this class for each activity that should share the
 same Options Menu. This way, you have to manage only one set of code for handling menu
 actions and each descendant class inherits the menu behaviors.<br/><br/>
 If you want to add menu items to one of your descendant activities,
 override {@link android.app.Activity#onCreateOptionsMenu(Menu)
-onCreateOptionsMenu()} in that Activity. Call {@code super.onCreateOptionsMenu(menu)} so the
+onCreateOptionsMenu()} in that activity. Call {@code super.onCreateOptionsMenu(menu)} so the
 original menu items are created, then add new menu items with {@link
 android.view.Menu#add(int,int,int,int) menu.add()}. You can also override the super class's
 behavior for individual menu items.</p>
 
 
-<h3 id="ChangingTheMenu">Changing the menu when it opens</h3>
+<h3 id="ChangingTheMenu">Changing menu items at runtime</h3>
 
-<p>The {@link android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} method is
+<p>Once the activity is created, the {@link android.app.Activity#onCreateOptionsMenu(Menu)
-called only the first time the Options Menu is opened. The system keeps and re-uses the {@link
+onCreateOptionsMenu()} method is
-android.view.Menu} you define in this method until your Activity is destroyed. If you want to change
+called only once, as described above. The system keeps and re-uses the {@link
-the Options Menu each time it opens, you must override the
+android.view.Menu} you define in this method until your activity is destroyed. If you want to change
+the Options Menu any time after it's first created, you must override the
 {@link android.app.Activity#onPrepareOptionsMenu(Menu) onPrepareOptionsMenu()} method. This passes
 you the {@link android.view.Menu} object as it currently exists. This is useful if you'd like to
 remove, add, disable, or enable menu items depending on the current state of your application.</p>
 
+<p>On Android 2.3 and lower, the system calls {@link android.app.Activity#onPrepareOptionsMenu(Menu)
+onPrepareOptionsMenu()} each time the user opens the Options Menu.</p>
+
+<p>On Android 3.0 and higher, you must call {@link android.app.Activity#invalidateOptionsMenu
+invalidateOptionsMenu()} when you want to update the menu, because the menu is always open. The
+system will then call {@link android.app.Activity#onPrepareOptionsMenu(Menu) onPrepareOptionsMenu()}
+so you can update the menu items.</p>
+
 <p class="note"><strong>Note:</strong> 
 You should never change items in the Options Menu based on the {@link android.view.View} currently
-in focus. When in touch mode (when the user is not using a trackball or d-pad), Views
+in focus. When in touch mode (when the user is not using a trackball or d-pad), views
 cannot take focus, so you should never use focus as the basis for modifying
 items in the Options Menu. If you want to provide menu items that are context-sensitive to a {@link
 android.view.View}, use a <a href="#context-menu">Context Menu</a>.</p>
 
+<p>If you're developing for Android 3.0 or higher, be sure to also read <a
+href="{@docRoot}guide/topics/ui/actionbar.html">Using the Action Bar</a>.</p>
+
+
 
 
 <h2 id="context-menu">Creating a Context Menu</h2>
@@ -287,7 +324,7 @@ feature.)</p>
 <div class="sidebox-wrapper">
 <div class="sidebox">
 <h3>Register a ListView</h3>
-<p>If your Activity uses a {@link android.widget.ListView} and
+<p>If your activity uses a {@link android.widget.ListView} and
 you want all list items to provide a context menu, register all items for a context
 menu by passing the {@link android.widget.ListView} to {@link
 android.app.Activity#registerForContextMenu(View) registerForContextMenu()}. For
@@ -301,7 +338,7 @@ menu. Call {@link android.app.Activity#registerForContextMenu(View) registerForC
 pass it the {@link android.view.View} you want to give a context menu. When this View then
 receives a long-press, it displays a context menu.</p>
 
-<p>To define the context menu's appearance and behavior, override your Activity's context menu
+<p>To define the context menu's appearance and behavior, override your activity's context menu
 callback methods, {@link android.app.Activity#onCreateContextMenu(ContextMenu,View,ContextMenuInfo)
 onCreateContextMenu()} and
 {@link android.app.Activity#onContextItemSelected(MenuItem) onContextItemSelected()}.</p>
@@ -325,7 +362,7 @@ href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a>. (Y
 parameters include the {@link android.view.View}
 that the user selected and a {@link android.view.ContextMenu.ContextMenuInfo} object that provides
 additional information about the item selected. You might use these parameters to determine
-which context menu should be created, but in this example, all context menus for the Activity are
+which context menu should be created, but in this example, all context menus for the activity are
 the same.</p>
 
 <p>Then when the user selects an item from the context menu, the system calls {@link
@@ -387,9 +424,9 @@ resource</a>, you can create a submenu by adding a {@code &lt;menu&gt;} element
           android:icon="@drawable/file"
           android:title="@string/file" &gt;
         &lt;!-- "file" submenu --&gt;
-        &lt;menu"&gt;
+        &lt;menu&gt;
-            &lt;item android:id="@+id/new"
+            &lt;item android:id="@+id/create_new"
-                  android:title="@string/new" /&gt;
+                  android:title="@string/create_new" /&gt;
             &lt;item android:id="@+id/open"
                   android:title="@string/open" /&gt;
         &lt;/menu&gt;
@@ -456,8 +493,9 @@ items in the group by referencing the group ID and using the methods listed abov
 <h3 id="checkable">Checkable menu items</h3>
 
 <div class="figure" style="width:200px">
-  <img src="{@docRoot}images/radio_buttons.png" height="300" alt="" />
+  <img src="{@docRoot}images/radio_buttons.png" height="333" alt="" />
-  <p class="img-caption"><strong>Figure 2.</strong> Screenshot of checkable menu items</p>
+  <p class="img-caption"><strong>Figure 3.</strong> Screenshot of a submenu with checkable
+items.</p>
 </div>
 
 <p>A menu can be useful as an interface for turning options on and off, using a checkbox for
@@ -525,7 +563,7 @@ public boolean onOptionsItemSelected(MenuItem item) {
 
 <p>If you don't set the checked state this way, then the visible state of the item (the checkbox or
 radio button) will not
-change when the user selects it. When you do set the state, the Activity preserves the checked state
+change when the user selects it. When you do set the state, the activity preserves the checked state
 of the item so that when the user opens the menu later, the checked state that you
 set is visible.</p>
 
@@ -538,7 +576,8 @@ href="{@docRoot}guide/topics/data/data-storage.html#pref">Shared Preferences</a>
 
 <h3 id="shortcuts">Shortcut keys</h3>
 
-<p>You can add quick-access shortcut keys using letters and/or numbers to menu items with the
+<p>To facilitate quick access to items in the Options Menu when the user's device has a hardware
+keyboard, you can add quick-access shortcut keys using letters and/or numbers, with the
 {@code android:alphabeticShortcut} and {@code android:numericShortcut} attributes in the {@code
 &lt;item&gt;} element. You can also use the methods {@link
 android.view.MenuItem#setAlphabeticShortcut(char)} and {@link
@@ -546,57 +585,46 @@ android.view.MenuItem#setNumericShortcut(char)}. Shortcut keys are <em>not</em>
 case sensitive.</p>
 
 <p>For example, if you apply the "s" character as an alphabetic shortcut to a "save" menu item, then
-when the menu is open (or while the user holds the MENU key) and the user presses the "s" key,
+when the menu is open (or while the user holds the MENU button) and the user presses the "s" key,
 the "save" menu item is selected.</p>
 
 <p>This shortcut key is displayed as a tip in the menu item, below the menu item name
 (except for items in the Icon Menu, which are displayed only if the user holds the MENU
-key).</p>
+button).</p>
 
 <p class="note"><strong>Note:</strong> Shortcut keys for menu items only work on devices with a
 hardware keyboard. Shortcuts cannot be added to items in a Context Menu.</p>
 
 
-<h3 id="intents">Intents for menu items</h3>
 
-<p>Sometimes you'll want a menu item to launch an Activity using an Intent (whether it's an
+<h3 id="intents">Dynamically adding menu intents</h3>
-Activity in your application or another application). When you know the Intent you want to use and
+
-have a specific menu item that should initiate the Intent, you can execute the Intent with {@link
+<p>Sometimes you'll want a menu item to launch an activity using an {@link android.content.Intent}
-android.app.Activity#startActivity(Intent) startActivity()} during the appropriate on-item-selected
+(whether it's an activity in your application or another application). When you know the intent you
-callback method (such as the {@link android.app.Activity#onOptionsItemSelected(MenuItem)
+want to use and have a specific menu item that should initiate the intent, you can execute the
-onOptionsItemSelected()} callback).</p>
+intent with {@link android.app.Activity#startActivity(Intent) startActivity()} during the
+appropriate on-item-selected callback method (such as the {@link
+android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} callback).</p>
 
 <p>However, if you are not certain that the user's device
-contains an application that handles the Intent, then adding a menu item that executes the
+contains an application that handles the intent, then adding a menu item that invokes it can result
-Intent can result in a non-functioning menu item, because the Intent might not resolve to an
+in a non-functioning menu item, because the intent might not resolve to an
-Activity that accepts it. To solve this, Android lets you dynamically add menu items to your menu
+activity. To solve this, Android lets you dynamically add menu items to your menu
-when Android finds activities on the device that handle your Intent.</p>
+when Android finds activities on the device that handle your intent.</p>
 
-<p>If you're not familiar with creating Intents, read the <a
+<p>To add menu items based on available activities that accept an intent:</p>
-href="/guide/topics/intents/intents-filters.html">Intents and Intent Filters</a>.</p>
-
-
-<h4>Dynamically adding Intents</h4>
-
-<p>When you don't know if the user's device has an application that handles a specific Intent,
-you can define the Intent and let Android search the device for activities that accept the Intent.
-When it finds activies that handle the Intent, it adds a menu item for
-each one to your menu and attaches the appropriate Intent to open the Activity when the user
-selects it.</p>
-
-<p>To add menu items based on available activities that accept an Intent:</p>
 <ol>
   <li>Define an
-Intent with the category {@link android.content.Intent#CATEGORY_ALTERNATIVE} and/or
+intent with the category {@link android.content.Intent#CATEGORY_ALTERNATIVE} and/or
 {@link android.content.Intent#CATEGORY_SELECTED_ALTERNATIVE}, plus any other requirements.</li>
   <li>Call {@link
 android.view.Menu#addIntentOptions(int,int,int,ComponentName,Intent[],Intent,int,MenuItem[])
-Menu.addIntentOptions()}. Android then searches for any applications that can perform the Intent
+Menu.addIntentOptions()}. Android then searches for any applications that can perform the intent
 and adds them to your menu.</li>
 </ol>
 
 <p>If there are no applications installed
-that satisfy the Intent, then no menu items are added.</p>
+that satisfy the intent, then no menu items are added.</p>
 
 <p class="note"><strong>Note:</strong>
 {@link android.content.Intent#CATEGORY_SELECTED_ALTERNATIVE} is used to handle the currently
@@ -621,7 +649,7 @@ public boolean onCreateOptionsMenu(Menu menu){
          R.id.intent_group,  // Menu group to which new items will be added
          0,      // Unique item ID (none)
          0,      // Order for the items (none)
-         this.getComponentName(),   // The current Activity name
+         this.getComponentName(),   // The current activity name
          null,   // Specific items to place first (none)
          intent, // Intent created above that describes our requirements
          0,      // Additional flags to control items (none)
@@ -630,8 +658,8 @@ public boolean onCreateOptionsMenu(Menu menu){
     return true;
 }</pre>
 
-<p>For each Activity found that provides an Intent filter matching the Intent defined, a menu
+<p>For each activity found that provides an intent filter matching the intent defined, a menu
-item is added, using the value in the Intent filter's <code>android:label</code> as the
+item is added, using the value in the intent filter's <code>android:label</code> as the
 menu item title and the application icon as the menu item icon. The
 {@link android.view.Menu#addIntentOptions(int,int,int,ComponentName,Intent[],Intent,int,MenuItem[])
 addIntentOptions()} method returns the number of menu items added.</p>
@@ -642,14 +670,14 @@ addIntentOptions()}, it overrides any and all menu items by the menu group speci
 argument.</p>
 
 
-<h4>Allowing your Activity to be added to menus</h4>
+<h4>Allowing your activity to be added to other menus</h4>
 
-<p>You can also offer the services of your Activity to other applications, so your
+<p>You can also offer the services of your activity to other applications, so your
 application can be included in the menu of others (reverse the roles described above).</p>
 
-<p>To be included in other application menus, you need to define an Intent
+<p>To be included in other application menus, you need to define an intent
 filter as usual, but be sure to include the {@link android.content.Intent#CATEGORY_ALTERNATIVE}
-and/or {@link android.content.Intent#CATEGORY_SELECTED_ALTERNATIVE} values for the Intent filter
+and/or {@link android.content.Intent#CATEGORY_SELECTED_ALTERNATIVE} values for the intent filter
 category. For example:</p>
 <pre>
 &lt;intent-filter label="Resize Image">
@@ -660,7 +688,7 @@ category. For example:</p>
 &lt;/intent-filter>
 </pre>
 
-<p>Read more about writing Intent filters in the
+<p>Read more about writing intent filters in the
 <a href="/guide/topics/intents/intents-filters.html">Intents and Intent Filters</a> document.</p>
 
 <p>For a sample application using this technique, see the