Merge "docs: New app bar training docs" into mnc-preview-docs

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

@@ -122,12 +122,16 @@ Bar. A menu item can appear as an action item only when the activity includes an
 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
+            <tr><td><code>ifRoom</code></td><td>Only place this item in the
-there is room for it.</td></tr>
+            Action Bar if there is room for it. If there is not room for all
+            the items marked <code>"ifRoom"</code>, the items with the lowest
+            <code>orderInCategory</code> values are displayed as actions, and
+            the remaining items are displayed in the overflow menu.</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>never</code></td><td>Never place this item in the Action Bar. Instead, list the item in the Action Bar's overflow
+            menu.</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

docs/html/training/appbar/actions.jd

@@ -0,0 +1,154 @@
+page.title=Adding and Handling Actions
+page.tags="appbar","actionbar"
+helpoutsWidget=true
+trainingnavtop=true
+
+@jd:body
+
+<div id="tb-wrapper">
+  <div id="tb">
+
+    <h2>This lesson teaches you to</h2>
+
+    <ol>
+      <li><a href="#add-actions">Add Action Buttons</a></li>
+      <li><a href="#handle-actions">Respond to Actions</a></li>
+    </ol>
+
+    <h2>Useful Resources</h2>
+    <ul>
+      <li><a href="https://www.google.com/design/icons/">Material Icons</a></li>
+    </ul>
+
+
+  </div>
+</div>
+
+
+<a class="notice-designers wide" href="{@docRoot}design/patterns/actionbar.html#ActionButtons">
+  <div>
+    <h3>Design Guide</h3>
+    <p>Action Buttons</p>
+  </div>
+</a>
+
+
+<p>
+  The app bar allows you to add buttons for user actions. This feature lets you
+  put the most important <em>actions</em> for the current context right at the
+  top of the app. For example, a photo browsing app might show <em>share</em>
+  and <em>create album</em> buttons at the top when the user is looking at
+  their photo roll; when the user looks at an individual photo, the app might
+  show <em>crop</em> and <em>filter</em> buttons.
+</p>
+
+<p>
+  Space in the app bar is limited. If an app declares more actions than can
+  fit in the app bar, the app bar send the excess actions to an
+  <em>overflow</em> menu. The app can also specify that an action should always
+  be shown in the overflow menu, instead of being displayed on the app bar.
+</p>
+
+<img src="{@docRoot}images/training/appbar/appbar_with_button_2x.png"
+  srcset="{@docRoot}images/training/appbar/appbar_with_button.png 1x,
+      {@docRoot}images/training/appbar/appbar_with_button_2x.png 2x"
+  width="400" alt="">
+
+<p class="img-caption">
+  <strong>Figure 1.</strong> An app bar with a single action button and an
+  overflow menu.
+</p>
+
+<h2 id="add-actions">Add Action Buttons</h2>
+
+<p>
+  All action buttons and other items available in the action overflow are
+  defined in an XML <a href=
+  "{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a>. To
+  add actions to the action bar, create a new XML file in your project's
+  <code>res/menu/</code> directory.
+</p>
+
+<p>
+  Add an <a href=
+  "{@docRoot}guide/topics/resources/menu-resource.html#item-element"><code>&lt;item&gt;</code></a>
+  element for each item you want to include in the action bar, as shown in this
+  code example of a menu XML file:
+</p>
+
+<pre>
+&lt;menu xmlns:android="http://schemas.android.com/apk/res/android" &gt;
+
+    &lt;!-- "Mark Favorite", should appear as action button if possible --&gt;
+    &lt;item
+        android:id="@+id/action_favorite"
+        android:icon="@drawable/ic_favorite_black_48dp"
+        android:title="@string/action_favorite"
+        app:showAsAction="ifRoom"/&gt;
+
+    &lt;!-- Settings, should always be in the overflow --&gt;
+    &lt;item android:id="@+id/action_settings"
+          android:title="@string/action_settings"
+          app:showAsAction="never"/&gt;
+
+&lt;/menu&gt;
+</pre>
+
+<p>
+  The <code>app:showAsAction</code> attribute specifies whether the action
+  should be shown as a button on the app bar. If you set
+  <code>app:showAsAction="ifRoom"</code> (as in the example code's <em>favorite</em> action), the action is displayed as a button
+  if there is room in the app bar for it; if there is not enough room, excess
+  actions are sent to the overflow menu. If you set
+  <code>app:showAsAction="never"</code> (as in the example code's <em>settings</em> action), the action is always listed in the
+  overflow menu, not displayed in the app bar.
+</p>
+
+<p>
+  The system uses the action's icon as the action button if the action is
+  displayed in the app bar. You can find many useful icons on the <a href=
+  "https://www.google.com/design/icons/">Material Icons</a> page.
+</p>
+
+<h2 id="handle-actions">Respond to Actions</h2>
+
+<p>
+  When the user selects one of the app bar items, the system calls your
+  activity's {@link android.app.Activity#onOptionsItemSelected
+  onOptionsItemSelected()} callback method, and passes a {@link
+  android.view.MenuItem} object to indicate which item was clicked. In your
+  implementation of {@link android.app.Activity#onOptionsItemSelected
+  onOptionsItemSelected()}, call the {@link android.view.MenuItem#getItemId
+  MenuItem.getItemId()} method to determine which item was pressed. The ID returned
+  matches the value you declared in the corresponding <a href=
+  "{@docRoot}guide/topics/resources/menu-resource.html#item-element"><code>&lt;item&gt;</code></a>
+  element's <code>android:id</code> attribute.
+</p>
+
+<p>
+  For example, the following code checks to see which action the user selected.
+  If the method does not recognize the user's action, it invokes the superclass
+  method:
+</p>
+
+<pre>
+&#64;Override
+public boolean onOptionsItemSelected(MenuItem item) {
+    switch (item.getItemId()) {
+        case R.id.action_settings:
+            // User chose the "Settings" item, show the app settings UI...
+            return true;
+
+        case R.id.action_favorite:
+            // User chose the "Favorite" action, mark the current item
+            // as a favorite...
+            return true;
+
+        default:
+            // If we got here, the user's action was not recognized.
+            // Invoke the superclass to handle it.
+            return super.onOptionsItemSelected(item);
+
+    }
+}
+</pre>

docs/html/training/appbar/index.jd

@@ -0,0 +1,98 @@
+page.title=Adding the App Bar
+page.tags="appbar","actionbar"
+helpoutsWidget=true
+trainingnavtop=true
+startpage=true
+
+@jd:body
+
+<div id="tb-wrapper">
+<div id="tb">
+
+<h2>Dependencies and prerequisites</h2>
+<ul>
+  <li>Android 2.1 (API level 7) or higher</li>
+</ul>
+
+
+<h2>You should also read</h2>
+<ul>
+  <li><a href="{@docRoot}training/implementing-navigation/index.html">
+    Implementing Effective Navigation</a></li>
+  <li><a href="http://www.google.com/design/spec/layout/structure.html#structure-app-bar">
+    Material Design: App Bar</a></li>
+</ul>
+
+</div>
+</div>
+
+<p>
+  The <em>app bar</em>, also known as the <em>action bar</em>, is one of the most
+  important design elements in your app's activities, because
+  it provides a visual structure and interactive elements that are familiar to
+  users. Using the app bar makes your app consistent with other Android apps,
+  allowing users to quickly understand how to operate your app and have a great
+  experience.
+  The key functions of the app bar
+  are as follows:
+</p>
+
+<ul>
+  <li>A dedicated space for giving your app an identity and indicating the
+  user's location in the app.
+  </li>
+
+  <li>Access to important actions in a predictable way, such as search.
+  </li>
+
+  <li>Support for navigation and view switching (with tabs or drop-down lists).
+  </li>
+</ul>
+
+<img src="{@docRoot}images/training/appbar/appbar_sheets_2x.png"
+    srcset="{@docRoot}images/training/appbar/appbar_sheets.png 1x,
+        {@docRoot}images/training/appbar/appbar_sheets_2x.png 2x"
+    width="400" alt="" />
+
+<p>
+  This class describes how to use the
+  <a href="{@docRoot}tools/support-library/features.html#v7-appcompat">v7
+  appcompat</a> support library's {@link
+  android.support.v7.widget.Toolbar} widget as an app bar. There are other ways
+  to implement an app bar—for example, some themes set up an {@link
+  android.app.ActionBar} as an app bar by default—but using the appcompat
+  {@link android.support.v7.widget.Toolbar} makes it easy to set up an app bar
+  that works on the widest range of devices, and also gives you room to
+  customize your app bar later on as your app develops.
+</p>
+
+<h2>Lessons</h2>
+
+<dl>
+  <dt>
+    <b><a href="setting-up.html">Setting Up the App Bar</a></b>
+  </dt>
+
+  <dd>
+    Learn how to add a {@link android.support.v7.widget.Toolbar} widget to your
+    activity, and set it as the activity's app bar.
+  </dd>
+
+  <dt>
+    <b><a href="actions.html">Adding and Handling Actions</a></b>
+  </dt>
+
+  <dd>
+    Learn how to add actions to the app bar and its overflow menu, and how to
+    respond when users choose those actions.
+  </dd>
+
+  <dt>
+    <b><a href="up-action.html">Adding an Up Action</a></b>
+  </dt>
+
+  <dd>
+    Learn how to add an <em>Up</em> button to your app bar, so users
+    can navigate back to the app's home screen.
+  </dd>
+</dl>

docs/html/training/appbar/setting-up.jd

@@ -0,0 +1,181 @@
+page.title=Setting Up the App Bar
+page.tags="appbar","actionbar", "toolbar"
+helpoutsWidget=true
+trainingnavtop=true
+
+@jd:body
+
+<div id="tb-wrapper">
+  <div id="tb">
+
+    <h2>This lesson teaches you to</h2>
+
+    <ol>
+      <li><a href="#add-toolbar">Add a Toolbar to an Activity</a></li>
+      <li><a href="#utility">Use App Bar Utility Methods</a></li>
+    </ol>
+
+    <h2>You should also read</h2>
+    <ul>
+      <li><a href="{@docRoot}tools/support-library/setup.html"
+    >Setting Up the Support Library</a></li>
+    </ul>
+  </div>
+</div>
+
+
+<p>
+  In its most basic form, the action bar displays the title for the activity on
+  one side and an <em>overflow menu</em> on the other. Even in this simple
+  form, the app bar provides useful information to the users, and helps to give
+  Android apps a consistent look and feel.
+</p>
+
+<img src="{@docRoot}images/training/appbar/appbar_basic_2x.png"
+    srcset="{@docRoot}images/training/appbar/appbar_basic.png 1x,
+        {@docRoot}images/training/appbar/appbar_basic_2x.png 2x"
+    width="400" alt="" />
+<p class="img-caption"><strong>Figure 1.</strong> An app bar with the app
+title and overflow menu.</a>
+
+<p>
+  Beginning with Android 3.0 (API level 11), all
+  activities that use the default theme have an {@link android.app.ActionBar}
+  as an app bar. However, app bar features have gradually been added to the
+  native {@link android.app.ActionBar} over various Android releases. As a
+  result, the native {@link android.app.ActionBar} behaves differently
+  depending on what version of the Android system a device may be using. By
+  contrast, the most recent features are added to the support library's version
+  of {@link android.support.v7.widget.Toolbar}, and they are available on any
+  device that can use the support library.
+</p>
+
+<p>
+  For this reason, you should use the support library's {@link
+  android.support.v7.widget.Toolbar} class to implement your activities' app
+  bars. Using the support library's toolbar helps ensure that your app will
+  have consistent behavior across the widest range of devices. For example, the
+  {@link android.support.v7.widget.Toolbar} widget provides a <a href=
+  "{@docRoot}design/material/index.html">material design</a> experience on
+  devices running Android 2.1 (API level 7) or later, but the native action
+  bar doesn't support material design unless the device is running Android 5.0
+  (API level 21) or later.
+</p>
+
+<h2 id="add-toolbar">Add a Toolbar to an Activity</h2>
+
+These steps describe how to set up a {@link android.support.v7.widget.Toolbar}
+as your activity's app bar:
+
+<ol>
+  <li>Add the the
+  <a href="{@docRoot}tools/support-library/features.html#v7-appcompat">v7
+  appcompat</a> support library to your project, as described in <a href=
+  "{@docRoot}tools/support-library/setup.html">Support Library Setup</a>.
+  </li>
+
+  <li>Make sure the activity extends {@link
+  android.support.v7.app.AppCompatActivity}:
+
+    <pre>
+public class MyActivity extends AppCompatActivity {
+  // ...
+}
+</pre>
+    <p class="note">
+      <strong>Note:</strong> Make this change for every activity in your app
+      that uses a {@link android.support.v7.widget.Toolbar} as an app bar.
+    </p>
+  </li>
+
+  <li>In the app manifest, set the <a href=
+  "{@docRoot}guide/topics/manifest/application-element.html"><code>&lt;application&gt;</code></a>
+  element to use one of appcompat's {@link
+  android.support.v7.appcompat.R.style#Theme_AppCompat_NoActionBar NoActionBar}
+  themes. Using one of these themes prevents the app from using the native
+  {@link android.app.ActionBar} class to provide the app bar. For example:
+
+    <pre>
+&lt;application
+    android:theme="&#64;style/Theme.AppCompat.Light.NoActionBar"
+    /&gt;
+</pre>
+  </li>
+
+  <li>Add a {@link android.support.v7.widget.Toolbar} to the activity's layout.
+  For example, the following layout code adds a {@link
+  android.support.v7.widget.Toolbar} and gives it the appearance of floating
+  above the activity:
+
+    <pre>
+&lt;android.support.v7.widget.Toolbar
+   android:id="&#64;+id/my_toolbar"
+   android:layout_width="match_parent"
+   android:layout_height="?attr/actionBarSize"
+   android:background="?attr/colorPrimary"
+   android:elevation="4dp"
+   android:theme="&#64;style/ThemeOverlay.AppCompat.ActionBar"
+   app:popupTheme="&#64;style/ThemeOverlay.AppCompat.Light"/&gt;
+</pre>
+    <p>
+      The <a href=
+      "https://www.google.com/design/spec/what-is-material/elevation-shadows.html#elevation-shadows-shadows">
+      Material Design specification</a> recommends that app bars have an
+      elevation of 4 dp.
+    </p>
+
+    <p>
+      Position the toolbar at the top of the activity's
+      <a href="{@docRoot}guide/topics/ui/declaring-layout.html">layout</a>,
+      since you are using it as an app bar.
+    </p>
+  </li>
+
+  <li>In the activity's {@link android.app.Activity#onCreate onCreate()}
+  method, call the activity's {@link
+  android.support.v7.app.AppCompatActivity#setSupportActionBar
+  setSupportActionBar()} method, and pass the activity's toolbar. This method
+  sets the toolbar as the app bar for the activity. For example:
+
+    <pre>
+&#64;Override
+protected void onCreate(Bundle savedInstanceState) {
+    super.onCreate(savedInstanceState);
+    setContentView(R.layout.activity_my);
+    <strong>Toolbar myToolbar = (Toolbar) findViewById(R.id.my_toolbar);
+    setSupportActionBar(myToolbar);</strong>
+    }
+</pre>
+  </li>
+</ol>
+
+<p>
+  Your app now has a basic action bar. By default, the action bar contains just
+  the name of the app and an overflow menu. The options menu initially contains
+  just the <strong>Settings</strong> item. You can add more actions to the
+  action bar and the overflow menu, as described in <a href=
+  "actions.html">Adding and Handling Actions</a>.
+</p>
+
+<h2 id="utility">Use App Bar Utility Methods</h2>
+
+<p>
+  Once you set the toolbar as an activity's app bar, you have access to the
+  various utility methods provided by the
+  <a href="{@docRoot}tools/support-library/features.html#v7-appcompat">v7
+  appcompat</a> support library's {@link
+  android.support.v7.app.ActionBar} class. This approach lets you do a number of useful
+  things, like hide and show the app bar.
+</p>
+
+<p>
+  To use the {@link android.support.v7.app.ActionBar} utility methods, call the
+  activity's {@link
+  android.support.v7.app.AppCompatActivity#getSupportActionBar
+  getSupportActionBar()} method. This method returns a reference to an
+  appcompat {@link android.support.v7.app.ActionBar} object.
+  Once you have that reference, you can call any of the {@link
+  android.support.v7.app.ActionBar} methods to adjust the app bar. For example,
+  to hide the app bar, call {@link android.support.v7.app.ActionBar#hide
+  ActionBar.hide()}.
+</p>

docs/html/training/appbar/up-action.jd

@@ -0,0 +1,134 @@
+page.title=Adding an Up Action
+page.tags="appbar","actionbar", "up"
+helpoutsWidget=true
+trainingnavtop=true
+
+@jd:body
+
+<div id="tb-wrapper">
+  <div id="tb">
+
+    <h2>This lesson teaches you to</h2>
+
+    <ol>
+      <li>
+        <a href="#declare-parent">Declare a Parent Activity</a>
+      </li>
+
+      <li>
+        <a href="#enable-up">Enable the Up Button</a>
+      </li>
+    </ol>
+
+    <h2>See Also</h2>
+    <ul>
+      <li><a href="{@docRoot}training/implementing-navigation/ancestral.html">
+          Providing Up Navigation</a></li>
+    </ul>
+
+
+  </div>
+</div>
+
+<p>
+  Your app should make it easy for users to find their way back to the app's
+  main screen. One simple way to do this is to provide an <em>Up</em>
+  button on the app bar for all activities except the main one. When the user
+  selects the <em>Up</em> button, the app navigates to the parent
+  activity.
+</p>
+
+<p>
+  This lesson shows you how to add an <em>Up</em> button to an activity by
+  declaring the activity's parent in the manifest, and enabling the app bar's
+  <em>Up</em> button.
+</p>
+
+<h2 id="declare-parent">Declare a Parent Activity</h2>
+
+<p>
+  To support the up functionality in an activity, you need to declare the
+  activity's parent. You can do this in the app manifest, by setting an
+  <code>android:parentActivityName</code> attribute.
+</p>
+
+<p>
+  The <code>android:parentActivityName</code> attribute
+  was introduced in Android 4.1 (API level 16). To support devices with older
+  versions of Android, define a <a href=
+  "{@docRoot}guide/topics/manifest/meta-data-element.html"><code>&lt;meta-data&gt;</code></a>
+  name-value pair, where the name is
+  <code>"android.support.PARENT_ACTIVITY"</code> and the value is the name of
+  the parent activity.
+</p>
+
+<p>
+  For example, suppose your app has a main activity named
+  <code>MainActivity</code> and a single child activity. The following manifest
+  code declares both activities, and specifies the parent/child relationship:
+</p>
+<pre>
+&lt;application ... &gt;
+    ...
+
+    &lt;!-- The main/home activity (it has no parent activity) --&gt;
+
+    &lt;activity
+        android:name="com.example.myfirstapp.MainActivity" ...&gt;
+        ...
+    &lt;/activity&gt;
+
+    &lt;!-- A child of the main activity --&gt;
+    &lt;activity
+        android:name="com.example.myfirstapp.MyChildActivity"
+        android:label="@string/title_activity_child"
+        <strong>android:parentActivityName="com.example.myfirstapp.MainActivity"</strong> &gt;
+
+        &lt;!-- Parent activity meta-data to support 4.0 and lower --&gt;
+        &lt;meta-data
+            <strong>android:name="android.support.PARENT_ACTIVITY"
+            android:value="com.example.myfirstapp.MainActivity" /&gt;</strong>
+    &lt;/activity&gt;
+&lt;/application&gt;
+</pre>
+
+<h2 id="enable-up">Enable the Up Button</h2>
+
+<p>
+  To enable the <em>Up</em> button for an activity that has a parent
+  activity, call the app bar's {@link
+  android.support.v7.app.ActionBar#setDisplayHomeAsUpEnabled
+  setDisplayHomeAsUpEnabled()} method. Typically, you would do this when the
+  activity is created. For example, the following {@link
+  android.app.Activity#onCreate onCreate()} method sets a {@link
+  android.support.v7.widget.Toolbar} as the app bar for
+  <code>MyChildActivity</code>, then enables that app bar's <em>Up</em> button:
+</p>
+
+<pre>
+&#64;Override
+protected void onCreate(Bundle savedInstanceState) {
+    super.onCreate(savedInstanceState);
+    setContentView(R.layout.activity_my_child);
+
+    // my_child_toolbar is defined in the layout file
+    Toolbar myChildToolbar =
+        (Toolbar) findViewById(R.id.my_child_toolbar);
+    setSupportActionBar(myChildToolbar);
+
+    // Get a support ActionBar corresponding to this toolbar
+    ActionBar ab = getSupportActionBar();
+
+    // Enable the Up button
+    <strong>ab.setDisplayHomeAsUpEnabled(true);</strong>
+}
+</pre>
+
+<p>
+  You do <em>not</em> need to catch the up action in the activity's {@link
+  android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} method.
+  Instead, that method should call its superclass, as shown in <a href=
+  "actions.html#handle-actions">Respond to Actions</a>. The superclass method
+  responds to the <em>Up</em> selection by navigating to the parent
+  activity, as specified in the app manifest.
+</p>

docs/html/training/training_toc.cs

@@ -1388,7 +1388,6 @@ results."
     </div>
     <ul>
 
-
       <li class="nav-section">
         <div class="nav-section-header">
           <a href="<?cs var:toroot ?>training/multiscreen/index.html"
@@ -1424,6 +1423,27 @@ results."
         </ul>
       </li>
 
+      <li class="nav-section">
+        <div class="nav-section-header">
+          <a href="<?cs var:toroot ?>training/appbar/index.html"
+             description=
+             "How to use the support library's toolbar widget to implement an
+             app bar that displays properly on a wide range of devices."
+            >Adding the App Bar</a>
+        </div>
+        <ul>
+          <li><a href="<?cs var:toroot ?>training/appbar/setting-up.html"
+            >Setting Up the App Bar</a>
+          </li>
+          <li><a href="<?cs var:toroot ?>training/appbar/actions.html"
+            >Adding and Handling Actions</a>
+          </li>
+          <li><a href="<?cs var:toroot ?>training/appbar/up-action.html"
+            >Adding an Up Action</a>
+          </li>
+        </ul>
+      </li>
+
       <li class="nav-section">
         <div class="nav-section-header">
           <a href="<?cs var:toroot ?>training/custom-views/index.html"