docs: add dev guide for action bar and update other relevant documents

Change-Id: I1d3deda4c35066f7cf05b06fe5b60acfa1fae149

docs/html/guide/guide_toc.cs

@@ -71,6 +71,9 @@
           <li><a href="<?cs var:toroot ?>guide/topics/ui/menus.html">
                <span class="en">Creating Menus</span>
               </a></li>
+          <li><a href="<?cs var:toroot ?>guide/topics/ui/actionbar.html">
+               <span class="en">Using the Action Bar</span>
+              </a> <span class="new">new!</span></li>
           <li><a href="<?cs var:toroot ?>guide/topics/ui/dialogs.html">
                 <span class="en">Creating Dialogs</span>
               </a></li>

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

@@ -0,0 +1,332 @@
+page.title=Using the Action Bar
+parent.title=User Interface
+parent.link=index.html
+@jd:body
+
+<div id="qv-wrapper">
+<div id="qv">
+
+  <h2>Quickview</h2>
+  <ul>
+    <li>A replacement for the title bar for displaying global actions for the activity</li>
+    <li>Provides toolbar actions and modes of navigating around the application</li>
+    <li>Switches to contextual menu options when one or more items are selected</li>
+    <li>Requires API Level HONEYCOMB</li>
+  </ul>
+
+  <h2>In this document</h2>
+  <ol>
+    <li><a href="#Adding">Adding the Action Bar</a></li>
+    <li><a href="#ActionItems">Adding Action Items</a>
+      <ol>
+        <li><a href="#Home">Using the application icon as an action item</a></li>
+      </ol>
+    </li>
+    <li><a href="#Tabs">Adding Tabs</a></li>
+    <li><a href="#Dropdown">Adding Drop-down Navigation</a></li>
+    <li><a href="#Search">Adding Search</a></li>
+  </ol>
+
+  <h2>Key classes</h2>
+  <ol>
+    <li>{@link android.app.ActionBar}</li>
+    <li>{@link android.view.Menu}</li>
+  </ol>
+
+  <h2>See also</h2>
+  <ol>
+    <li><a href="{@docRoot}guide/topics/ui/menus.html">Creating Menus</a></li>
+  </ol>
+</div>
+</div>
+
+<p>The action bar is a widget for activities that replaces the traditional title bar at
+the top of an activity. By default, the action bar includes the application logo on the left side,
+followed by the activity title. The action bar offers several useful features for
+applications&mdash;especially those targeted to tablet devices. The action bar features include
+the ability to:</p>
+
+<ul>
+  <li>Display menu items from the <a
+href="{@docRoot}guide/topics/ui/menus.html#OptionsMenu">options menu</a> as "action
+items"&mdash;providing instant access to key user actions.</li>
+  <li>Provide tabs for navigating between <a
+href="{@docRoot}guide/topics/fragments/index.html">fragments</a>.</li>
+  <li>Provide drop-down navigation items.</li>
+  <li>Embed a {@link android.widget.SearchView} for instant searching.</li>
+  <li>Use the application logo as a "return home" or "up" navigation action.</li>
+</ul>
+
+<img src="{@docRoot}images/ui/actionbar.png" height="36" alt="" />
+<p class="img-caption"><strong>Figure 1.</strong> A screenshot of the action bar in the NotePad
+sample application, containing action items to save and delete the note.</p>
+
+
+<h2 id="Adding">Adding the Action Bar</h2>
+
+<p>To add the Action Bar to your activity, apply the holographic theme&mdash;{@code
+Theme.Holo}&mdash;or the action bar theme&mdash;{@code Theme.WithActionBar}&mdash;in your manifest
+file. For example:</p>
+
+<pre>
+&lt;activity android:theme="@android:style/Theme.Holo" &gt;
+</pre>
+
+<p>The activity now appears with the action bar in place of the traditional title bar.</p>
+
+
+<h2 id="ActionItems">Adding Action Items</h2>
+
+<p>For each action item you want to add to the action bar, you must add a menu item to the
+activity's <a href="{@docRoot}guide/topics/ui/menus.html#OptionsMenu">options menu</a> and declare
+that the item be shown as an action, using the {@code android:showAsAction} attribute in the menu
+XML or with {@link android.view.MenuItem#setShowAsAction setShowAsAction()} on the {@link
+android.view.MenuItem}.</p>
+
+<div class="figure" style="width:359px">
+  <img src="{@docRoot}images/ui/actionbar-item-withtext.png" height="57" alt="" />
+  <p class="img-caption"><strong>Figure 2.</strong> A screenshot from an action bar with two
+action items.</p>
+</div>
+
+<p>You can specify a menu item to appear as an action item in the action bar&mdash;if there is room
+for it&mdash;from the <a href="{@docRoot}guide/topics/resources/menu-resource.html">menu
+resource</a> by declaring {@code
+android:showAsAction="ifRoom"} for the {@code &lt;item&gt;} element. This way, the item will display
+in the action bar for quick access only if there is room available for it&mdash;if there's not
+enough room, the item is placed the options menu (revealed by the drop-down icon on the right side
+of the action bar). From your application code, you can specify the item to appear as an action item
+by calling {@link android.view.MenuItem#setShowAsAction setShowAsAction()} on the {@link
+android.view.MenuItem} and passing {@link android.view.MenuItem#SHOW_AS_ACTION_IF_ROOM}.</p>
+
+<p>If your item supplies both a title and an icon, then the action item shows only
+the icon by defult. If you want to include the text with the action item, add the <em>with text</em>
+flag&mdash;in XML, add {@code withText} to the {@code android:showAsAction} attribute or, in
+your application code, use the {@link android.view.MenuItem#SHOW_AS_ACTION_WITH_TEXT} flag when
+calling {@link android.view.MenuItem#setShowAsAction setShowAsAction()}. Figure 2 shows a screenshot
+of an action bar with two action items that include text.</p>
+
+<p>Here's an example of how you can declare a menu item as an action item in a <a
+href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a> file:</p>
+<pre>
+&lt;?xml version="1.0" encoding="utf-8"?&gt;
+&lt;menu xmlns:android="http://schemas.android.com/apk/res/android">
+    &lt;item android:id="@+id/menu_add"
+          android:icon="@drawable/ic_menu_save"
+          android:title="@string/menu_save"
+          <b>android:showAsAction="ifRoom|withText"</b> /&gt;
+&lt;/menu&gt;
+</pre>
+
+<p>In this case, both the {@code ifRoom} and {@code withText} flags are set, so that when this
+item appears as an action item, it includes the title text along with the icon.</p>
+
+<p>A menu item placed in the action bar triggers the same callback methods as other items in the
+options menu. When the user selects an item in the action bar, your activity receives a call to
+{@link android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()}, passing the
+item ID. (If you added the item from a fragment, then the respective {@link
+android.app.Fragment#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} method is called
+for that fragment.)</p>
+
+<p class="note"><strong>Note:</strong> Even menu items that are contained in the options menu
+(and not shown as action items) will show an icon, so when using the action bar, you should
+provide an icon for every item in the options menu.</p>
+
+<p>You can also declare an item to <em>always</em> appear as an action item,  but you should avoid
+doing so. Most of the time, there will be enough room for several action items and they will appear
+in the order you declare them. If you set items to always appear as action
+items  (instead of <em>if room</em>), then they are added without discrimination and there is a risk
+that they will collide with other elements in the action bar, such as tabs or custom views.</p>
+
+<p>For more information about menus, see the <a
+href="{@docRoot}guide/topics/ui/menus.html#options-menu">Creating Menus</a> developer guide.</p>
+
+
+<h3 id="Home">Using the application icon as an action item</h3>
+
+<p>By default, the application icon appears in the action bar on the left side, but does nothing
+when tapped. To use the application icon as an action item when tapped, you simply need to add a
+condition to your {@link android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} method
+that performs an action when the {@link android.view.MenuItem} ID is {@code android.R.id.home}.
+This ID is delivered every time the user taps the application icon.</p>
+
+<p>For example, here's an implementation of {@link android.app.Activity#onOptionsItemSelected
+onOptionsItemSelected()} that returns to the application's "home" activity:</p>
+
+<pre>
+&#64;Override
+public boolean onOptionsItemSelected(MenuItem item) {
+    switch (item.getItemId()) {
+        case android.R.id.home:
+            // app icon in action bar clicked; go home
+            Intent intent = new Intent(this, HomeActivity.class);
+            startActivity(intent);
+            break;
+    }
+    return super.onOptionsItemSelected(item);
+}
+</pre>
+
+<div class="figure" style="width:144px">
+  <img src="{@docRoot}images/ui/actionbar-logo.png" height="140" alt="" />
+  <p class="img-caption"><strong>Figure 3.</strong> The standard icon for the Email application
+(top) and the "up navigation" icon (bottom).</p>
+</div>
+
+<p>You can also use the application icon to provide "up" navigation. The way you handle the event
+when a user taps the icon is the same, but if the user experience for the event is to <em>navigate
+up to the parent activity</em>, then you should indicate this behavior by setting the
+action bar to "show home as up." You can do so by calling {@link
+android.app.ActionBar#setDisplayOptions setDisplayOptions()} on your activity's {@link
+android.app.ActionBar}, and passing the {@link
+android.app.ActionBar#DISPLAY_HOME_AS_UP} display option.</p>
+
+<p>To get the {@link android.app.ActionBar}, call {@link android.app.Activity#getActionBar} from
+your {@link android.app.Activity} during {@link android.app.Activity#onCreate onCreate()} (but be
+sure you do so <em>after</em> you've called {@link android.app.Activity#setContentView
+setContentView()}).</p>
+
+<p>For example, here's how you can change the action bar display mode to show the application
+icon as an "up" action:</p>
+
+<pre>
+&#64;Override
+protected void onStart() {
+  super.onStart();
+  ActionBar actionBar = this.getActionBar();
+  actionBar.setDisplayOptions(ActionBar.DISPLAY_HOME_AS_UP, ActionBar.DISPLAY_HOME_AS_UP);
+}
+</pre>
+
+<p class="caution"><strong>Caution:</strong> If your activity does not have an action bar (if you
+did not set the theme of your activity or application to the holographic or action bar theme), then
+{@link android.app.Activity#getActionBar} returns null.</p>
+
+
+<h2 id="Tabs">Adding Tabs</h2>
+
+<p>The action bar can display tabs that allow the user navigate between different fragments in the
+activity. Each tab can include a title and/or an icon.</p>
+
+<p>To begin, your layout must include a {@link android.view.View} in which each {@link
+android.app.Fragment} associated with a tab is displayed. Be sure the view has an ID that you
+can use to reference it from your code.</p>
+
+<p>To add tabs to the action bar:</p>
+<ol>
+  <li>Create an implementation of {@link android.app.ActionBar.TabListener} to handle the
+interaction events on the action bar tabs. You must implement all methods: {@link
+android.app.ActionBar.TabListener#onTabSelected onTabSelected()}, {@link
+android.app.ActionBar.TabListener#onTabUnselected onTabUnselected()}, and {@link
+android.app.ActionBar.TabListener#onTabReselected onTabReselected()}.
+    <p>Each callback method passes the {@link android.app.ActionBar.Tab} that received the
+event and a {@link android.app.FragmentTransaction} for you to perform the fragment
+transactions (add or remove fragments).</p>
+    <p>For example:</p>
+<pre>
+private class MyTabListener implements ActionBar.TabListener {
+    private TabContentFragment mFragment;
+
+    // Called to create an instance of the listener when adding a new tab
+    public TabListener(TabContentFragment fragment) {
+        mFragment = fragment;
+    }
+
+    &#64;Override
+    public void onTabSelected(Tab tab, FragmentTransaction ft) {
+        ft.add(R.id.fragment_content, mFragment, null);
+    }
+
+    &#64;Override
+    public void onTabUnselected(Tab tab, FragmentTransaction ft) {
+        ft.remove(mFragment);
+    }
+
+    &#64;Override
+    public void onTabReselected(Tab tab, FragmentTransaction ft) {
+        // do nothing
+    }
+
+}
+</pre>
+  <p>This implementation of {@link android.app.ActionBar.TabListener} adds a constructor
+that saves the {@link android.app.Fragment} associated with a tab so that each callback
+can add or remove that fragment.</p>
+  </li>
+  <li>Get the {@link android.app.ActionBar} for your activity by calling {@link
+android.app.Activity#getActionBar} from your {@link android.app.Activity}, during {@link
+android.app.Activity#onCreate onCreate()} (but be sure you do so <em>after</em> you've called
+{@link android.app.Activity#setContentView setContentView()}).</li>
+  <li>Call {@link android.app.ActionBar#setNavigationMode(int)
+setNavigationMode(NAVIGATION_MODE_TABS)} to enable tab mode for the {@link
+android.app.ActionBar}.</li>
+  <li>Create each tab for the action bar:
+    <ol>
+      <li>Create a new {@link android.app.ActionBar.Tab} by calling {@link
+android.app.ActionBar#newTab()} on the {@link android.app.ActionBar}.</li>
+      <li>Add title text and/or an icon for the tab by calling {@link
+android.app.ActionBar.Tab#setText setText()} and/or {@link android.app.ActionBar.Tab#setIcon
+setIcon()}.
+        <p class="note"><strong>Tip:</strong> These methods return the same {@link
+android.app.ActionBar.Tab} instance, so you can chain the calls together.</p></li>
+      <li>Declare the {@link android.app.ActionBar.TabListener} to use for the tab by passing an
+instance of your implementation to {@link android.app.ActionBar.Tab#setTabListener
+setTabListener()}.
+    </ol>
+  </li>
+  <li>Add each {@link android.app.ActionBar.Tab} to the action bar by calling {@link
+android.app.ActionBar#addTab addTab()} on the {@link android.app.ActionBar} and passing the
+{@link android.app.ActionBar.Tab}.</li>
+</ol>
+<p>For example, the following code combines steps 2 - 5 to create two tabs and add them to
+the action bar:</p>
+<pre>
+&#64;Override
+protected void onCreate(Bundle savedInstanceState) {
+    super.onCreate(savedInstanceState);
+    setContentView(R.layout.main);
+
+    // setup action bar for tabs
+    final ActionBar actionBar = getActionBar();
+    actionBar.setNavigationMode(ActionBar.NAVIGATION_MODE_TABS);
+    // remove the activity title to make space for tabs
+    actionBar.setDisplayOptions(0, ActionBar.DISPLAY_SHOW_TITLE);
+
+    // instantiate fragment for the tab
+    Fragment artistsFragment = new ArtistsFragment();
+    // add a new tab and set its title text and tab listener
+    bar.addTab(bar.newTab().setText(R.string.tab_artists)
+            .setTabListener(new TabListener(artistsFragment)));
+
+    Fragment albumsFragment = new AlbumsFragment();
+    bar.addTab(bar.newTab().setText(R.string.tab_albums)
+            .setTabListener(new TabListener(albumsFragment)));
+}
+</pre>
+
+<p>All the behaviors that occur when a tab is selected must be defined by your {@link
+android.app.ActionBar.TabListener} callback methods. When a tab is selected, it receives a call to
+{@link android.app.ActionBar.TabListener#onTabSelected onTabSelected()} and that's where you should
+add the appropriate fragment to the designated view in your layout, using {@link
+android.app.FragmentTransaction#add add()} with the provided {@link
+android.app.FragmentTransaction}. Likewise, when a tab is deselected (because another tab becomes
+selected), you should remove that fragment from the layout, using {@link
+android.app.FragmentTransaction#remove remove()}.</p>
+
+<p class="note"><strong>Note:</strong> You <strong>do not</strong> need
+to call {@link android.app.FragmentTransaction#commit} for these transactions. You also
+<strong>cannot</strong> add these fragment transactions to the back stack.</p>
+
+<p>If your activity is stopped, you should retain the currently selected tab with the saved state so
+that when the user returns to your application, you can open the tab. When it's time to save the
+state, you can query the currently selected tab with {@link
+android.app.ActionBar#getSelectedNavigationItem()}. This returns the index position of the selected
+tab.</p>
+
+<p class="caution"><strong>Caution:</strong> It's important that you save
+the state of each fragment as necessary, so when the user switches fragments with the tabs,
+then returns to a previous fragment, it appears the way they left. For information about saving
+the state of your fragment, see the <a
+href="{@docRoot}guide/topics/fragments/index.html">Fragments</a> developer guide.</p>
+
+

docs/html/guide/topics/ui/declaring-layout.jd

@@ -191,10 +191,12 @@ layout parameters for the View that are appropriate for the ViewGroup in which i
 <p>Every ViewGroup class implements a nested class that extends {@link
 android.view.ViewGroup.LayoutParams}. This subclass
 contains property types that define the size and position for each child view, as
-appropriate for the view group. As you can see in the figure below, the parent
+appropriate for the view group. As you can see in figure 1, the parent
 view group defines layout parameters for each child view (including the child view group).</p>
 
 <img src="{@docRoot}images/layoutparams.png" alt="" height="300" align="center"/>
+<p class="img-caption"><strong>Figure 1.</strong> Visualization of a view hierarchy with layout
+parameters associated with each view.</p>
 
 <p>Note that every LayoutParams subclass has its own syntax for setting
 values. Each child element must define LayoutParams that are appropriate for its parent, 

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

@@ -22,20 +22,32 @@ parent.link=index.html
       </li>
       <li><a href="#CustomDialog">Creating a Custom Dialog</a></li>
     </ol>
-    
+
     <h2>Key classes</h2>
     <ol>
       <li>{@link android.app.Dialog}</li>
+      <li>{@link android.app.AlertDialog}</li>
+      <li>{@link android.app.DialogFragment}</li>
+    </ol>
+
+    <h2>Related tutorials</h2>
+    <ol>
+      <li><a href="{@docRoot}resources/tutorials/views/hello-datepicker.html">Hello
+DatePicker</a></li>
+      <li><a href="{@docRoot}resources/tutorials/views/hello-timepicker.html">Hello
+TimePicker</a></li>
     </ol>
   </div>
 </div>
 
 <p>A dialog is usually a small window that appears in front of the current Activity.
-The underlying Activity loses focus and the dialog accepts all user interaction. 
-Dialogs are normally used
-for notifications and short activities that directly relate to the application in progress.</p>
+The underlying Activity loses focus and the dialog accepts all user interaction. Dialogs are
+normally used for notifications that should interupt the user and to perform short tasks that
+directly relate to the application in progress (such as a progress bar or a login prompt).</p>
 
-<p>The Android API supports the following types of {@link android.app.Dialog} objects:</p>
+<p>The {@link android.app.Dialog} class is the base class for creating dialogs. However, you
+typically should not instantiate a {@link android.app.Dialog} directly. Instead, you should use one
+of the following subclasses:</p>
 <dl>
   <dt>{@link android.app.AlertDialog}</dt>
   <dd>A dialog that can manage zero, one, two, or three buttons, and/or a list of

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

@@ -36,6 +36,7 @@ parent.link=index.html
 
   <h2>See also</h2>
   <ol>
+    <li><a href="{@docRoot}guide/topics/ui/actionbar.html">Using the Action Bar</a></li>
     <li><a href="{@docRoot}guide/topics/resources/menu-resource.html">Menu Resource</a></li>
   </ol>
 </div>
@@ -48,20 +49,9 @@ for you to provide application menus in your application.</p>
 <p>Android provides three types of application menus:</p>
 <dl>
   <dt><strong>Options Menu</strong></dt>
-    <dd>The primary menu for an Activity, which appears when the user presses
-    the device MENU key. Within the Options Menu are two groups:
-      <dl style="margin-top:1em">
-        <dt><em>Icon Menu</em></dt>
-          <dd>The menu items visible at the bottom of the screen
-          at the press of the MENU key. It supports a maximum of six menu items.
-          These are the only menu items that support icons and the only menu items that <em>do not</em> support
-          checkboxes or radio buttons.</dd>
-        <dt><em>Expanded Menu</em></dt>
-          <dd>The vertical list of menu items exposed by the "More" menu item in the Icon Menu.
-          When the Icon Menu is full, the expanded menu is comprised of the sixth
-          menu item and the rest.</dd>
-      </dl>
-    </dd>
+    <dd>The primary collection of menu items for an Activity that is associated with the device MENU
+key. To provide instant access to select menu items, you can place some items in the <a
+href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a>, if available.</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>
@@ -74,7 +64,7 @@ Menu or a context menu. A submenu item cannot support a nested submenu. </dd>
 
 <h2 id="xml">Defining Menus</h2>
 
-<p>Instead of instantiating {@link android.view.Menu} objects in your application code, you should
+<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
@@ -104,9 +94,9 @@ href="#groups">Menu groups</a>.</dd>
     &lt;item android:id="@+id/new_game"
           android:icon="@drawable/ic_new_game"
           android:title="@string/new_game" /&gt;
-    &lt;item android:id="@+id/quit"
-          android:icon="@drawable/ic_quit"
-          android:title="@string/quit" /&gt;
+    &lt;item android:id="@+id/help"
+          android:icon="@drawable/ic_help"
+          android:title="@string/help" /&gt;
 &lt;/menu&gt;
 </pre>
 
@@ -161,36 +151,64 @@ creating an option menu is discussed more in the next section.)</p>
 </div>
 
 
-<p>The Options Menu is where you should include basic application functions
-and necessary navigation items (for example, a button
-to open application settings). The user
-can open the Options Menu with the device MENU key.
-Figure 1 shows a screenshot of an Options Menu.</p>
+<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
+key.</p>
 
-<p>When opened, the first visible portion of the Options Menu is called the Icon Menu. It
-holds the first six menu items.
-If you add more than six items to the Options Menu, Android places the sixth item and those after it
-into the Expanded Menu, which the user can open with the "More" menu item.</p>
+<p>The Action Bar is an optional widget that appears at the top of the activity in place of the
+title bar. It can display several menu items that you choose from the Options Menu, but items in
+the Action Bar display only an icon (no title text). Users can reveal the other menu items in the
+Options Menu with the MENU key.</p>
+
+<p>If you include the Action Bar in your activity, the menu items that are not placed in the Action
+Bar can appear in two different styles:</p>
+<dl>
+  <dt>Action Bar Menu</dt>
+    <dd>If the device has an extra-large screen ({@code xlarge}), then all items in the Options Menu
+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
 {@link android.app.Activity#onCreateOptionsMenu(Menu)
 onCreateOptionsMenu()} method. Override this method in your Activity
 and populate the {@link android.view.Menu} that is passed into the method. Populate the
 {@link android.view.Menu} by inflating a menu resource as described in <a
-href="#Inflating">Inflating a Menu Resource</a>. (You can
-also populate the menu in code, using {@link android.view.Menu#add(int,int,int,int)
-add()} to add menu items.)</p>
+href="#Inflating">Inflating a Menu Resource</a>. For example:</p>
 
-<p>When the user selects a menu item from the Options Menu, the system calls your Activity's
+<pre>
+&#64;Override
+public boolean onCreateOptionsMenu(Menu menu) {
+    MenuInflater inflater = getMenuInflater();
+    inflater.inflate(R.menu.game_menu, menu);
+    return true;
+}
+</pre>
+
+<p>(You can also populate the menu in code, using {@link android.view.Menu#add(int,int,int,int)
+add()} to add items to the {@link android.view.Menu}.)</p>
+
+<p>When the user selects a menu item from the Options Menu (including items selected from 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
 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.</p>
-
-<p>For example:</p>
+against known menu items and perform the appropriate action. For example:</p>
 
 <pre>
 &#64;Override
@@ -200,8 +218,8 @@ public boolean onOptionsItemSelected(MenuItem item) {
     case R.id.new_game:
         newGame();
         return true;
-    case R.id.quit:
-        quit();
+    case R.id.help:
+        showHelp();
         return true;
     default:
         return super.onOptionsItemSelected(item);
@@ -224,8 +242,8 @@ an Activity that implements nothing except the {@link android.app.Activity#onCre
 onCreateOptionsMenu()} and {@link android.app.Activity#onOptionsItemSelected(MenuItem)
 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 decendent class inherits the menu behaviors.<br/><br/>
-If you want to add menu items to one of your decendent activities,
+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
 original menu items are created, then add new menu items with {@link
@@ -542,7 +560,7 @@ 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
-Actvitity in your application or another application). When you know the Intent you want to use and
+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
 android.app.Activity#startActivity(Intent) startActivity()} during the appropriate on-item-selected
 callback method (such as the {@link android.app.Activity#onOptionsItemSelected(MenuItem)