Merge "new class on using action bar for training basics" into jb-mr2-docs

docs/html/tools/support-library/setup.jd

@@ -149,7 +149,9 @@ dependencies {
 
 <h3 id="libs-with-res">Adding libraries with resources</h3>
 
-<p>To add a Support Library with resources to your application project:</p>
+<p>To add a Support Library with resources (such as
+  <a href="{@docRoot}tools/support-library/features.html#v7-appcompat">v7
+  appcompat</a> for action bar) to your application project:</p>
 
 <div class="toggle-content closed">
   <p style="margin-top:5px"><a href="#" onclick="return toggleContent(this)">

docs/html/training/basics/actionbar/adding-buttons.jd

@@ -0,0 +1,210 @@
+page.title=Adding Action Buttons
+
+trainingnavtop=true
+
+@jd:body
+
+<div id="tb-wrapper">
+  <div id="tb">
+
+<h2>This lesson teaches you to</h2>
+<ol>
+  <li><a href="#XML">Specify the Actions in XML</a></li>
+  <li><a href="#AddActions">Add the Actions to the Action Bar</a></li>
+  <li><a href="#Respond">Respond to Action Buttons</a></li>
+  <li><a href="#UpNav">Add Up Button for Low-level Activities</a></li>
+</ol>
+
+<h2>You should also read</h2>
+<ul>
+  <li><a href="{@docRoot}training/implementing-navigation/ancestral.html">Providing Up
+  Navigation</a></li>
+  </div>
+</div>
+
+
+
+<p>The action bar allows you to add buttons for the most important action
+items relating to the app's current
+context. Those that appear directly in the action bar with an icon and/or text are known
+as <em>action buttons</em>. Actions that can't fit in the action bar or aren't
+important enough are hidden in the action overflow.</p>
+
+<img src="{@docRoot}images/training/basics/actionbar-actions.png" height="100" alt=""/>
+<p class="img-caption"><strong>Figure 1.</strong> An action bar with an action button
+for Search and the action overflow, which reveals additional actions.</a>
+
+
+<h2 id="XML">Specify the Actions in XML</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/} directory.</p>
+
+<p>Add an {@code &lt;item>} element for each item you want to include in the action bar.
+For example:</p>
+
+<p class="code-caption">res/menu/main_activity_actions.xml</p>
+<pre>
+&lt;menu xmlns:android="http://schemas.android.com/apk/res/android" >
+    &lt;!-- Search, should appear as action button -->
+    &lt;item android:id="@+id/action_search"
+          android:icon="@drawable/ic_action_search"
+          android:title="@string/action_search"
+          android:showAsAction="ifRoom" /&gt;
+    &lt;!-- Settings, should always be in the overflow -->
+    &lt;item android:id="@+id/action_settings"
+          android:title="@string/action_settings"
+          android:showAsAction="never" /&gt;
+&lt;/menu&gt;
+</pre>
+
+<div class="sidebox">
+<h3>Download action bar icons</h3>
+<p>To best match the Android <a
+href="{@docRoot}design/style/iconography.html#action-bar">iconography</a> guidelines, you should
+use icons provided in the
+<a href="{@docRoot}design/downloads/index.html#action-bar-icon-pack">Action Bar Icon Pack</a>.</p>
+</div>
+
+<p>This declares that the Search action should appear as an action button when room
+is available in the action bar, but the
+Settings action should always appear in the overflow. (By default, all actions appear in the
+overflow, but it's good practice to explicitly declare your design intentions for each action.)
+
+<p>However, <strong>if your app is using the Support Library</strong> for compatibility on versions
+as low as Android 2.1, the {@code showAsAction} attribute is not available from
+the {@code android:} namespace. Instead this attribute is provided by the Support Library
+and you must define your own XML namespace and use that namespace as the attribute prefix.
+(A custom XML namespace should be based on your app name, but it can be any
+name you want and is only accessible within the scope of the file in which you declare it.)
+For example:</p>
+
+<p class="code-caption">res/menu/main_activity_actions.xml</p>
+<pre>
+&lt;menu xmlns:android="http://schemas.android.com/apk/res/android"
+      <strong>xmlns:yourapp="http://schemas.android.com/apk/res-auto"</strong> >
+    &lt;!-- Search, should appear as action button -->
+    &lt;item android:id="@+id/action_search"
+          android:icon="@drawable/ic_action_search"
+          android:title="@string/action_search"
+          <strong>yourapp:showAsAction="ifRoom"</strong>  /&gt;
+    ...
+&lt;/menu&gt;
+</pre>
+
+
+
+<h2 id="AddActions">Add the Actions to the Action Bar</h2>
+
+<p>To place the menu items into the action bar, implement the
+{@link android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} callback
+method in your activity to inflate the menu resource into the given {@link android.view.Menu}
+object. For example:</p>
+
+<pre>
+&#64;Override
+public boolean onCreateOptionsMenu(Menu menu) {
+    // Inflate the menu items for use in the action bar
+    MenuInflater inflater = getMenuInflater();
+    inflater.inflate(R.menu.main_activity_actions, menu);
+    return super.onCreateOptionsMenu(menu);
+}
+</pre>
+
+
+
+<h2 id="Respond">Respond to Action Buttons</h2>
+
+<p>When the user presses one of the action buttons or another item in the action overflow,
+the system calls your activity's {@link android.app.Activity#onOptionsItemSelected
+onOptionsItemSelected()} callback method. In your implementation of this method,
+call {@link android.view.MenuItem#getItemId getItemId()} on the given {@link android.view.MenuItem} to
+determine which item was pressed&mdash;the returned ID matches the value you declared in the
+corresponding {@code &lt;item>} element's {@code android:id} attribute.</p>
+
+<pre>
+&#64;Override
+public boolean onOptionsItemSelected(MenuItem item) {
+    // Handle presses on the action bar items
+    switch (item.getItemId()) {
+        case R.id.action_search:
+            openSearch();
+            return true;
+        case R.id.action_settings:
+            openSettings();
+            return true;
+        default:
+            return super.onOptionsItemSelected(item);
+    }
+}
+</pre>
+
+
+
+<h2 id="UpNav">Add Up Button for Low-level Activities</h2>
+
+<div class="figure" style="width:240px">
+  <img src="{@docRoot}images/ui/actionbar-up.png" width="240" alt="">
+  <p class="img-caption"><strong>Figure 4.</strong> The <em>Up</em> button in Gmail.</p>
+</div>
+
+<p>All screens in your app that are not the main entrance to your app
+(activities that are not the "home" screen) should
+offer the user a way to navigate to the logical parent screen in the app's hierarchy by pressing
+the <em>Up</em> button in the action bar.</p>
+
+<p>When running on Android 4.1 (API level 16) or higher, or when using {@link
+android.support.v7.app.ActionBarActivity} from the Support Library, performing <em>Up</em>
+navigation simply requires that you declare the parent activity in the manifest file and enable
+the <em>Up</em> button for the action bar.</p>
+
+<p>For example, here's how you can declare an activity's parent in the manifest:</p>
+
+<pre>
+&lt;application ... >
+    ...
+    &lt;!-- The main/home activity (it has no parent activity) -->
+    &lt;activity
+        android:name="com.example.myfirstapp.MainActivity" ...>
+        ...
+    &lt;/activity>
+    &lt;!-- A child of the main activity -->
+    &lt;activity
+        android:name="com.example.myfirstapp.DisplayMessageActivity"
+        android:label="@string/title_activity_display_message"
+        android:parentActivityName="com.example.myfirstapp.MainActivity" >
+        &lt;!-- Parent activity meta-data to support 4.0 and lower -->
+        &lt;meta-data
+            android:name="android.support.PARENT_ACTIVITY"
+            android:value="com.example.myfirstapp.MainActivity" />
+    &lt;/activity>
+&lt;/application>
+</pre>
+
+  <p>Then enable the app icon as the <em>Up</em> button by calling
+{@link android.app.ActionBar#setDisplayHomeAsUpEnabled setDisplayHomeAsUpEnabled()}:</p>
+
+<pre>
+{@literal @}Override
+public void onCreate(Bundle savedInstanceState) {
+    super.onCreate(savedInstanceState);
+    setContentView(R.layout.activity_displaymessage);
+
+    getSupportActionBar().setDisplayHomeAsUpEnabled(true);
+    // If your minSdkVersion is 11 or higher, instead use:
+    // getActionBar().setDisplayHomeAsUpEnabled(true);
+}
+</pre>
+
+<p>Because the system now knows {@code MainActivity} is the parent activity for
+{@code DisplayMessageActivity}, when the user presses the
+<em>Up</em> button, the system navigates to
+the parent activity as appropriate&mdash;you <strong>do not</strong> need to handle the
+<em>Up</em> button's event.</p>
+
+<p>For more information about up navigation, see
+<a href="{@docRoot}training/implementing-navigation/ancestral.html">Providing Up
+  Navigation</a>.

docs/html/training/basics/actionbar/index.jd

@@ -0,0 +1,68 @@
+page.title=Adding the Action Bar
+page.tags="actionbar"
+
+trainingnavtop=true
+startpage=true
+
+@jd:body
+
+<div id="tb-wrapper">
+<div id="tb">
+
+<h2>Dependencies and prerequisites</h2>
+<ul>
+  <li>Android 2.1 or higher</li>
+</ul>
+
+
+<h2>You should also read</h2>
+<ul>
+  <li><a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a></li>
+  <li><a href="{@docRoot}training/implementing-navigation/index.html">Implementing
+  Effective Navigation</a></li>
+</ul>
+
+</div>
+</div>
+
+<a class="notice-designers wide" href="{@docRoot}design/patterns/actionbar.html">
+  <div>
+    <h3>Design Guide</h3>
+    <p>Action Bar</p>
+  </div>
+</a>
+
+<p>The action bar is one of the most important design elements you can implement for your
+app's activities. It provides several user interface features that make your app immediately
+familiar to users by offering consistency between other Android apps. Key functions include:</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/basics/actionbar-actions.png" height="100" alt="">
+
+<p>This training class offers a quick guide to the action bar's basics. For more information
+about action bar's various features, see the
+<a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> guide.</p>
+
+
+<h2>Lessons</h2>
+
+<dl>
+  <dt><b><a href="setting-up.html">Setting Up the Action Bar</a></b></dt>
+  <dd>Learn how to add a basic action bar to your activity, whether your app
+  supports only Android 3.0 and higher or also supports versions as low as Android 2.1
+  (by using the Android Support Library).</dd>
+  <dt><b><a href="adding-buttons.html">Adding Action Buttons</a></b></dt>
+  <dd>Learn how to add and respond to user actions in the action bar.</dd>
+  <dt><b><a href="styling.html">Styling the Action Bar</a></b></dt>
+  <dd>Learn how to customize the appearance of your action bar.</dd>
+  <dt><b><a href="overlaying.html">Overlaying the Action Bar</a></b></dt>
+  <dd>Learn how to overlay the action bar in front of your layout, allowing for
+  seamless transitions when hiding the action bar.</dd>
+</dl>
+

docs/html/training/basics/actionbar/overlaying.jd

@@ -0,0 +1,141 @@
+page.title=Overlaying the Action Bar
+
+trainingnavtop=true
+
+@jd:body
+
+
+<div id="tb-wrapper">
+  <div id="tb">
+
+<h2>This lesson teaches you to</h2>
+<ol>
+  <li><a href="#EnableOverlay">Enable Overlay Mode</a>
+    <ol>
+      <li><a href="#Overlay11">For Android 3.0 and higher only</a></li>
+      <li><a href="#Overlay7">For Android 2.1 and higher</a></li>
+    </ol>
+  </li>
+  <li><a href="#TopMargin">Specify Layout Top-margin</a></li>
+</ol>
+
+<h2>You should also read</h2>
+<ul>
+  <li><a href="{@docRoot}guide/topics/ui/themes.html">Styles and Themes</a></li>
+</ul>
+  </div>
+</div>
+
+
+<p>By default, the action bar appears at the top of your activity window,
+slightly reducing the amount of space available for the rest of your activity's layout.
+If, during the course of user interaction, you want to hide and show the action bar, you can do so
+by calling {@link android.app.ActionBar#hide()} and
+{@link android.app.ActionBar#show()} on the {@link android.app.ActionBar}. However,
+this causes your activity to recompute and redraw the layout based on its new size.</p>
+
+
+<div class="figure" style="width:280px">
+  <img src="{@docRoot}images/training/basics/actionbar-overlay@2x.png" width="280" alt="" />
+  <p class="img-caption"><strong>Figure 1.</strong> Gallery's action bar in overlay mode.</p>
+</div>
+
+<p>To avoid resizing your layout when the action bar hides and shows, you can enable <em>overlay
+mode</em> for the action bar. When in overlay mode, your activity layout uses all the space
+available as if the action bar is not there and the system draws the action bar in front of
+your layout. This obscures some of the layout at the top, but now when the action bar hides or
+appears, the system does not need to resize your layout and the transition is seamless.</p>
+
+<p class="note"><strong>Tip:</strong>
+If you want your layout to be partially visible behind the action bar, create a custom
+style for the action bar with a partially transparent background, such as the one shown
+in figure 1. For information about how to define the action bar background, read
+<a href="{@docRoot}training/basics/actionbar/styling.html">Styling the Action Bar</a>.</p>
+
+
+<h2 id="EnableOverlay">Enable Overlay Mode</h2>
+
+<p>To enable overlay mode for the action bar, you need to create a custom theme that
+extends an existing action bar theme and set the {@code android:windowActionBarOverlay} property to
+{@code true}.</p>
+
+
+<h3 id="Overlay11">For Android 3.0 and higher only</h3>
+
+<p>If your
+<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a>
+is set to {@code 11} or higher, your custom theme should use
+{@link android.R.style#Theme_Holo Theme.Holo} theme (or one of its descendants) as your parent
+theme. For example:</p>
+
+<pre>
+&lt;resources>
+    &lt;!-- the theme applied to the application or activity -->
+    &lt;style name="CustomActionBarTheme"
+           parent="&#64;android:style/Theme.Holo">
+        &lt;item name="android:windowActionBarOverlay">true&lt;/item>
+    &lt;/style>
+&lt;/resources>
+</pre>
+
+
+<h3 id="Overlay7">For Android 2.1 and higher</h3>
+
+<p>If your app is using the Support Library for compatibility on devices
+running versions lower than Android 3.0, your custom theme should use
+{@link android.support.v7.appcompat.R.style#Theme_AppCompat Theme.AppCompat} theme
+(or one of its descendants) as your parent theme. For example:</p>
+
+<pre>
+&lt;resources>
+    &lt;!-- the theme applied to the application or activity -->
+    &lt;style name="CustomActionBarTheme"
+           parent="&#64;android:style/Theme.<strong>AppCompat</strong>">
+        &lt;item name="android:windowActionBarOverlay">true&lt;/item>
+
+        &lt;!-- Support library compatibility -->
+        &lt;item name="windowActionBarOverlay">true&lt;/item>
+    &lt;/style>
+&lt;/resources>
+</pre>
+
+<p>Also notice that this theme includes two definitions for the {@code windowActionBarOverlay}
+style: one with the {@code android:} prefix and one without. The one with the {@code android:}
+prefix is for versions of Android that include the style in the platform and the one
+without the prefix is for older versions that read the style from the Support Library.</p>
+
+
+
+
+
+<h2 id="TopMargin">Specify Layout Top-margin</h2>
+
+<p>When the action bar is in overlay mode, it might obscure some of your layout that should
+remain visible. To ensure that such items remain below the action bar at all times,
+add either margin or padding to the top of the view(s)
+using the height specified by {@link android.R.attr#actionBarSize}. For example:</p>
+
+<pre>
+&lt;RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
+    android:layout_width="match_parent"
+    android:layout_height="match_parent"
+    android:paddingTop="?android:attr/actionBarSize">
+    ...
+&lt;/RelativeLayout>
+</pre>
+
+<p>If you're using the Support Library for the action bar, you need to remove the
+{@code android:} prefix. For example:</p>
+
+<pre>
+&lt;!-- Support library compatibility -->
+&lt;RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
+    android:layout_width="match_parent"
+    android:layout_height="match_parent"
+    android:paddingTop="?attr/actionBarSize">
+    ...
+&lt;/RelativeLayout>
+</pre>
+
+<p>In this case, the {@code ?attr/actionBarSize} value without the
+prefix works on all versions, including Android 3.0 and higher.</p>

docs/html/training/basics/actionbar/setting-up.jd

@@ -0,0 +1,112 @@
+page.title=Setting Up the Action Bar
+
+trainingnavtop=true
+
+@jd:body
+
+<div id="tb-wrapper">
+  <div id="tb">
+
+<h2>This lesson teaches you to</h2>
+<ol>
+  <li><a href="#ApiLevel11">Support Android 3.0 and Above Only</a></li>
+  <li><a href="#ApiLevel7">Support Android 2.1 and Above</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
+and the app icon on the left. Even in this simple form, the action bar
+is useful for all activities to inform
+users about where they are and to maintain a consistent identity for your app.</p>
+
+<img src="{@docRoot}images/training/basics/actionbar-basic.png" height="100" alt=""/>
+<p class="img-caption"><strong>Figure 1.</strong> An action bar with the app icon and
+activity title.</a>
+
+<p>Setting up a basic action bar requires that your app use an activity theme that enables
+the action bar. How to request such a theme depends on which version of Android is the
+lowest supported by your app. So this
+lesson is divided into two sections depending on which Android
+version is your lowest supported.</p>
+
+
+<h2 id="ApiLevel11">Support Android 3.0 and Above Only</h2>
+
+<p>Beginning with Android 3.0 (API level 11), the action bar is included in all
+activities that use the {@link android.R.style#Theme_Holo Theme.Holo} theme (or one of its
+descendants), which is the default theme when either the <a
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> or
+<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a>
+attribute is set to <code>"11"</code> or greater.</p>
+
+<p>So to add the action bar to your activities, simply set either attribute to
+{@code 11} or higher. For example:</p>
+
+<pre>
+&lt;manifest ... &gt;
+    &lt;uses-sdk android:minSdkVersion="11" ... /&gt;
+    ...
+&lt;/manifest&gt;
+</pre>
+
+<p class="note"><strong>Note:</strong> If you've created a custom theme, be sure it uses one
+of the {@link android.R.style#Theme_Holo Theme.Holo} themes as its parent. For details,
+see <a href="{@docRoot}training/basics/actionbar/styling.html">Styling the Action Bar</a>.</p>
+
+<p>Now the {@link android.R.style#Theme_Holo Theme.Holo} theme is applied to your app and
+all activities show the action bar. That's it.</p>
+
+
+
+<h2 id="ApiLevel7">Support Android 2.1 and Above</h2>
+
+<p>Adding the action bar when running on versions older than Android 3.0 (down to Android 2.1)
+requires that you include the Android Support Library in your application.</p>
+
+<p>To get started, read the <a href="{@docRoot}tools/support-library/setup.html"
+>Support Library Setup</a> document and set up the <strong>v7 appcompat</strong>
+library (once you've downloaded the library package, follow the instructions for <a
+href="{@docRoot}tools/support-library/setup.html#libs-with-res">Adding libraries with
+resources</a>).</p>
+
+<p>Once you have the Support Library integrated with your app project:</p>
+
+<ol>
+  <li>Update your activity so that it extends {@link android.support.v7.app.ActionBarActivity}.
+  For example:
+<pre>
+public class MainActivity extends ActionBarActivity { ... }
+</pre>
+  </li>
+  <li>In your manifest file, update either the <a
+  href="{@docRoot}guide/topics/manifest/application-element.html">{@code
+  &lt;application>}</a> element or individual
+  <a href="{@docRoot}guide/topics/manifest/application-element.html">{@code &lt;activity>}</a>
+  elements to use one of the {@link android.support.v7.appcompat.R.style#Theme_AppCompat
+  Theme.AppCompat} themes. For example:
+  <pre>&lt;activity android:theme="@style/Theme.AppCompat.Light" ... ></pre>
+  <p class="note"><strong>Note:</strong> If you've created a custom theme, be sure it uses one
+of the {@link android.support.v7.appcompat.R.style#Theme_AppCompat Theme.AppCompat} themes as
+its parent. For details, see <a href="{@docRoot}training/basics/actionbar/styling.html">Styling
+the Action Bar</a>.</p>
+  </li>
+</ol>
+
+<p>Now your activity includes the action bar when running on Android 2.1 (API level 7) or higher.
+</p>
+
+<p>Remember to properly set your app's API level support in the manifest:</p>
+<pre>
+&lt;manifest ... &gt;
+    &lt;uses-sdk android:minSdkVersion="7"  android:targetSdkVersion="18" /&gt;
+    ...
+&lt;/manifest&gt;
+</pre>

docs/html/training/basics/actionbar/styling.jd

@@ -0,0 +1,448 @@
+page.title=Styling the Action Bar
+
+trainingnavtop=true
+
+@jd:body
+
+
+<div id="tb-wrapper">
+  <div id="tb">
+
+<h2>This lesson teaches you to</h2>
+<ol>
+  <li><a href="#AndroidThemes">Use an Android Theme</a></li>
+  <li><a href="#CustomBackground">Customize the Background</a></li>
+  <li><a href="#CustomText">Customize the Text Color</a></li>
+  <li><a href="#CustomTabs">Customize the Tab Indicator</a></li>
+</ol>
+
+<h2>You should also read</h2>
+<ul>
+  <li><a href="{@docRoot}guide/topics/ui/themes.html">Styles and Themes</a></li>
+  <li><a class="external-link" target="_blank"
+  href="http://jgilfelt.github.io/android-actionbarstylegenerator/">Android Action Bar Style
+  Generator</a></li>
+</ul>
+
+  </div>
+</div>
+
+
+
+<p>The action bar provides your users a familiar and predictable way to perform
+actions and navigate your app, but that doesn't mean it needs to look exactly the
+same as it does in other apps. If you want to style the action bar to better fit your product
+brand, you can easily do so using Android's <a href="{@docRoot}guide/topics/ui/themes.html">style
+and theme</a> resources.</p>
+
+<p>Android includes a few built-in activity themes that include "dark" or "light" action bar
+styles. You can also extend these themes to further customize the look for your action bar.</p>
+
+<p class="note" style="clear:left"><strong>Note:</strong> If you are using the Support Library APIs
+for the action bar, then you must use (or override) the {@link
+android.support.v7.appcompat.R.style#Theme_AppCompat Theme.AppCompat} family of styles (rather
+than the {@link android.R.style#Theme_Holo Theme.Holo} family, available in API level 11 and
+higher). In doing so, each style property that you declare must be declared twice: once using
+the platform's style properties (the
+{@link android.R.attr android:} properties) and once using the
+style properties included in the Support Library (the {@link android.support.v7.appcompat.R.attr
+appcompat.R.attr} properties&mdash;the context for these properties is actually
+<em>your app</em>). See the examples below for details.</p>
+
+
+
+<h2 id="AndroidThemes">Use an Android Theme</h2>
+
+<div class="figure" style="width:340px">
+  <img src="{@docRoot}images/training/basics/actionbar-theme-dark@2x.png" width="340" alt="" />
+</div>
+
+<div class="figure" style="width:340px">
+  <img src="{@docRoot}images/training/basics/actionbar-theme-light-solid@2x.png" width="340" alt="" />
+</div>
+
+<p>Android includes two baseline activity themes that dictate the color for the action bar:
+</p>
+<ul>
+  <li>{@link android.R.style#Theme_Holo Theme.Holo} for a "dark" theme.
+  </li>
+  <li>{@link android.R.style#Theme_Holo_Light Theme.Holo.Light} for a "light" theme.
+  </li>
+</ul>
+
+<p>You can apply these themes to your entire app or to individual activities by
+declaring them in your manifest file with the {@code android:theme} attribute
+for the <a href="{@docRoot}guide/topics/manifest/application-element.html">{@code
+&lt;application>}</a> element or individual
+<a href="{@docRoot}guide/topics/manifest/application-element.html">{@code &lt;activity>}</a>
+elements.</p>
+
+<p>For example:</p>
+<pre>
+&lt;application android:theme="@android:style/Theme.Holo.Light" ... />
+</pre>
+
+<div class="figure" style="width:340px">
+  <img src="{@docRoot}images/training/basics/actionbar-theme-light-darkactionbar@2x.png" width="340" alt="" />
+</div>
+
+<p>You can also use a dark action bar while the rest of the activity uses the light
+color scheme by declaring the {@link android.R.style#Theme_Holo_Light_DarkActionBar
+Theme.Holo.Light.DarkActionBar} theme.</p>
+
+<p>When using the Support Library, you must instead use the
+{@link android.support.v7.appcompat.R.style#Theme_AppCompat Theme.AppCompat} themes:</p>
+<ul>
+  <li>{@link android.support.v7.appcompat.R.style#Theme_AppCompat Theme.AppCompat} for the
+  "dark" theme.</li>
+  <li>{@link android.support.v7.appcompat.R.style#Theme_AppCompat_Light Theme.AppCompat.Light}
+  for the "light" theme.</li>
+  <li>{@link android.support.v7.appcompat.R.style#Theme_AppCompat_Light_DarkActionBar
+Theme.AppCompat.Light.DarkActionBar} for the light theme with a dark action bar.
+</ul>
+
+<p>Be sure that you use action bar icons that properly contrast with the color of your action
+bar. To help you, the <a href="{@docRoot}design/downloads/index.html#action-bar-icon-pack">Action
+Bar Icon Pack</a> includes standard action icons for use with both the Holo light and Holo dark
+action bar.</p>
+
+
+
+
+
+<h2 id="CustomBackground">Customize the Background</h2>
+
+<div class="figure" style="width:340px">
+  <img src="{@docRoot}images/training/basics/actionbar-theme-custom@2x.png" width="340" alt="" />
+</div>
+
+<p>To change the action bar background, create a custom theme for your activity that overrides the
+{@link android.R.attr#actionBarStyle} property. This property points to another style
+in which you can override the {@link android.R.attr#background} property to specify
+a drawable resource for the action bar background.</p>
+
+<p>If your app uses <a href="{@docRoot}guide/topics/ui/actionbar.html#Tabs">navigation tabs</a>
+or the <a href="{@docRoot}guide/topics/ui/actionbar.html#SplitBar">split
+action bar</a>, then you can also specify the background for these bars using
+the {@link android.R.attr#backgroundStacked} and
+{@link android.R.attr#backgroundSplit} properties, respectively.</p>
+
+<p class="caution"><strong>Caution:</strong> It's important that you declare an appropriate
+parent theme from which your custom theme and style inherit their styles. Without a parent
+style, your action bar will be without many style properties unless you explicitly declare
+them yourself.</p>
+
+
+<h3 id="CustomBackground11">For Android 3.0 and higher only</h3>
+
+<p>When supporting Android 3.0 and higher only, you can define the action bar's
+background like this:</p>
+
+<p class="code-caption">res/values/themes.xml</p>
+<pre>
+&lt;?xml version="1.0" encoding="utf-8"?>
+&lt;resources>
+    &lt;!-- the theme applied to the application or activity -->
+    &lt;style name="CustomActionBarTheme"
+           parent="&#64;style/Theme.Holo.Light.DarkActionBar">
+        &lt;item name="android:actionBarStyle">&#64;style/MyActionBar&lt;/item>
+    &lt;style>
+
+    &lt;!-- ActionBar styles -->
+    &lt;style name="MyActionBar"
+           parent="&#64;style/Widget.Holo.Light.ActionBar.Solid.Inverse">
+        &lt;item name="android:background">&#64;drawable/actionbar_background&lt;/item>
+    &lt;style>
+&lt;/resources>
+</pre>
+
+<p>Then apply your theme to your entire app or individual activities:</p>
+<pre>
+&lt;application android:theme="&#64;style/CustomActionBarTheme" ... />
+</pre>
+
+
+
+<h3 id="CustomBackground7">For Android 2.1 and higher</h3>
+
+<p>When using the Support Library, the same theme as above must instead look like this:</p>
+
+<p class="code-caption">res/values/themes.xml</p>
+<pre>
+&lt;?xml version="1.0" encoding="utf-8"?>
+&lt;resources>
+    &lt;!-- the theme applied to the application or activity -->
+    &lt;style name="CustomActionBarTheme"
+           parent="&#64;style/Theme.<strong>AppCompat</strong>.Light.DarkActionBar">
+        &lt;item name="android:actionBarStyle">&#64;style/MyActionBar&lt;/item>
+
+        &lt;!-- Support library compatibility -->
+        &lt;item name="actionBarStyle">&#64;style/MyActionBar&lt;/item>
+    &lt;style>
+
+    &lt;!-- ActionBar styles -->
+    &lt;style name="MyActionBar"
+           parent="&#64;style/Widget.<strong>AppCompat</strong>.Light.ActionBar.Solid.Inverse">
+        &lt;item name="android:background">&#64;drawable/actionbar_background&lt;/item>
+
+        &lt;!-- Support library compatibility -->
+        &lt;item name="background">&#64;drawable/actionbar_background&lt;/item>
+    &lt;style>
+&lt;/resources>
+</pre>
+
+<p>Then apply your theme to your entire app or individual activities:</p>
+<pre>
+&lt;application android:theme="&#64;style/CustomActionBarTheme" ... />
+</pre>
+
+
+
+
+
+
+
+<h2 id="CustomText">Customize the Text Color</h2>
+
+<p>To modify the color of text in the action bar, you need to override separate properties
+for each text element:</p>
+<ul>
+  <li>Action bar title: Create a custom style that specifies the {@code textColor} property and
+  specify that style for the {@link android.R.attr#titleTextStyle} property in your custom
+  {@link android.R.attr#actionBarStyle}.
+    <p class="note"><strong>Note:</strong>
+    The custom style applied to {@link android.R.attr#titleTextStyle} should use
+    {@link android.R.style#TextAppearance_Holo_Widget_ActionBar_Title
+    TextAppearance.Holo.Widget.ActionBar.Title} as the parent style.</p>
+  </li>
+  <li>Action bar tabs: Override {@link android.R.attr#actionBarTabTextStyle} in your
+  activity theme.</li>
+  <li>Action buttons: Override {@link android.R.attr#actionMenuTextColor} in your
+  activity theme.</li>
+</ul>
+
+
+<h3 id="CustomText11">For Android 3.0 and higher only</h3>
+
+<p>When supporting Android 3.0 and higher only, your style XML file might look like this:</p>
+
+<p class="code-caption">res/values/themes.xml</p>
+<pre>
+&lt;?xml version="1.0" encoding="utf-8"?>
+&lt;resources>
+    &lt;!-- the theme applied to the application or activity -->
+    &lt;style name="CustomActionBarTheme"
+           parent="&#64;style/Theme.Holo">
+        &lt;item name="android:actionBarStyle">&#64;style/MyActionBar&lt;/item>
+        &lt;item name="android:actionBarTabTextStyle">&#64;style/MyActionBarTabText&lt;/item>
+        &lt;item name="android:actionMenuTextColor">&#64;color/actionbar_text&lt;/item>
+    &lt;style>
+
+    &lt;!-- ActionBar styles -->
+    &lt;style name="MyActionBar"
+           parent="&#64;style/Widget.Holo.ActionBar">
+        &lt;item name="android:titleTextStyle">&#64;style/MyActionBarTitleText&lt;/item>
+    &lt;style>
+
+    &lt;!-- ActionBar title text -->
+    &lt;style name="MyActionBarTitleText"
+           parent="&#64;style/TextAppearance.Holo.Widget.ActionBar.Title">
+        &lt;item name="android:textColor">&#64;color/actionbar_text&lt;/item>
+    &lt;style>
+
+    &lt;!-- ActionBar tabs text styles -->
+    &lt;style name="MyActionBarTabText"
+           parent="&#64;style/Widget.Holo.ActionBar.TabText">
+        &lt;item name="android:textColor">&#64;color/actionbar_text&lt;/item>
+    &lt;style>
+&lt;/resources>
+</pre>
+
+
+
+
+<h3 id="CustomText7">For Android 2.1 and higher</h3>
+
+<p>When using the Support Library, your style XML file might look like this:</p>
+
+<p class="code-caption">res/values/themes.xml</p>
+<pre>
+&lt;?xml version="1.0" encoding="utf-8"?>
+&lt;resources>
+    &lt;!-- the theme applied to the application or activity -->
+    &lt;style name="CustomActionBarTheme"
+           parent="&#64;style/Theme.<strong>AppCompat</strong>">
+        &lt;item name="android:actionBarStyle">&#64;style/MyActionBar&lt;/item>
+        &lt;item name="android:actionBarTabTextStyle">&#64;style/MyActionBarTabText&lt;/item>
+        &lt;item name="android:actionMenuTextColor">&#64;color/actionbar_text&lt;/item>
+
+        &lt;!-- Support library compatibility -->
+        &lt;item name="actionBarStyle">&#64;style/MyActionBar&lt;/item>
+        &lt;item name="actionBarTabTextStyle">&#64;style/MyActionBarTabText&lt;/item>
+        &lt;item name="actionMenuTextColor">&#64;color/actionbar_text&lt;/item>
+    &lt;style>
+
+    &lt;!-- ActionBar styles -->
+    &lt;style name="MyActionBar"
+           parent="&#64;style/Widget.<strong>AppCompat</strong>.ActionBar">
+        &lt;item name="android:titleTextStyle">&#64;style/MyActionBarTitleText&lt;/item>
+
+        &lt;!-- Support library compatibility -->
+        &lt;item name="titleTextStyle">&#64;style/MyActionBarTitleText&lt;/item>
+    &lt;style>
+
+    &lt;!-- ActionBar title text -->
+    &lt;style name="MyActionBarTitleText"
+           parent="&#64;style/TextAppearance.<strong>AppCompat</strong>.Widget.ActionBar.Title">
+        &lt;item name="android:textColor">&#64;color/actionbar_text&lt;/item>
+        &lt;!-- The textColor property is backward compatible with the Support Library -->
+    &lt;style>
+
+    &lt;!-- ActionBar tabs text -->
+    &lt;style name="MyActionBarTabText"
+           parent="&#64;style/Widget.<strong>AppCompat</strong>.ActionBar.TabText">
+        &lt;item name="android:textColor">&#64;color/actionbar_text&lt;/item>
+        &lt;!-- The textColor property is backward compatible with the Support Library -->
+    &lt;style>
+&lt;/resources>
+</pre>
+
+
+
+
+
+
+<h2 id="CustomTabs">Customize the Tab Indicator</h2>
+
+<div class="figure" style="width:340px">
+  <img src="{@docRoot}images/training/basics/actionbar-theme-custom-tabs@2x.png" width="340" alt="" />
+</div>
+
+<p>To change the indicator used for the <a
+href="{@docRoot}guide/topics/ui/actionbar.html#Tabs">navigation tabs</a>,
+create an activity theme that overrides the
+{@link android.R.attr#actionBarTabStyle} property. This property points to another style
+resource in which you override the {@link android.R.attr#background} property that should specify
+a state-list drawable.</p>
+
+<p class="note"><strong>Note:</strong> A state-list drawable is important so that the tab currently
+selected indicates its state with a background different than the other tabs. For more information
+about how to create a drawable resource that handles multiple button states, read the
+<a href="{@docRoot}guide/topics/resources/drawable-resource.html#StateList">State List</a>
+documentation.</p>
+
+<p>For example, here's a state-list drawable that declares a specific background image
+for several different states of an action bar tab:</p>
+
+<p class="code-caption">res/drawable/actionbar_tab_indicator.xml</p>
+<pre>
+&lt;?xml version="1.0" encoding="utf-8"?>
+&lt;selector xmlns:android="http://schemas.android.com/apk/res/android">
+
+&lt;!-- STATES WHEN BUTTON IS NOT PRESSED -->
+
+    &lt;!-- Non focused states -->
+    &lt;item android:state_focused="false" android:state_selected="false"
+          android:state_pressed="false"
+          android:drawable="&#64;drawable/tab_unselected" />
+    &lt;item android:state_focused="false" android:state_selected="true"
+          android:state_pressed="false"
+          android:drawable="&#64;drawable/tab_selected" />
+
+    &lt;!-- Focused states (such as when focused with a d-pad or mouse hover) -->
+    &lt;item android:state_focused="true" android:state_selected="false"
+          android:state_pressed="false"
+          android:drawable="&#64;drawable/tab_unselected_focused" />
+    &lt;item android:state_focused="true" android:state_selected="true"
+          android:state_pressed="false"
+          android:drawable="&#64;drawable/tab_selected_focused" />
+
+
+&lt;!-- STATES WHEN BUTTON IS PRESSED -->
+
+    &lt;!-- Non focused states -->
+    &lt;item android:state_focused="false" android:state_selected="false"
+          android:state_pressed="true"
+          android:drawable="&#64;drawable/tab_unselected_pressed" />
+    &lt;item android:state_focused="false" android:state_selected="true"
+        android:state_pressed="true"
+        android:drawable="&#64;drawable/tab_selected_pressed" />
+
+    &lt;!-- Focused states (such as when focused with a d-pad or mouse hover) -->
+    &lt;item android:state_focused="true" android:state_selected="false"
+          android:state_pressed="true"
+          android:drawable="&#64;drawable/tab_unselected_pressed" />
+    &lt;item android:state_focused="true" android:state_selected="true"
+          android:state_pressed="true"
+          android:drawable="&#64;drawable/tab_selected_pressed" />
+&lt;/selector>
+</pre>
+
+
+
+<h3 id="CustomTabs11">For Android 3.0 and higher only</h3>
+
+<p>When supporting Android 3.0 and higher only, your style XML file might look like this:</p>
+
+<p class="code-caption">res/values/themes.xml</p>
+<pre>
+&lt;?xml version="1.0" encoding="utf-8"?>
+&lt;resources>
+    &lt;!-- the theme applied to the application or activity -->
+    &lt;style name="CustomActionBarTheme"
+           parent="&#64;style/Theme.Holo">
+        &lt;item name="android:actionBarTabStyle">&#64;style/MyActionBarTabs&lt;/item>
+    &lt;style>
+
+    &lt;!-- ActionBar tabs styles -->
+    &lt;style name="MyActionBarTabs"
+           parent="&#64;style/Widget.Holo.ActionBar.TabView">
+        &lt;!-- tab indicator -->
+        &lt;item name="android:background">&#64;drawable/actionbar_tab_indicator&lt;/item>
+    &lt;style>
+&lt;/resources>
+</pre>
+
+
+
+<h3 id="CustomTabs7">For Android 2.1 and higher</h3>
+
+<p>When using the Support Library, your style XML file might look like this:</p>
+
+<p class="code-caption">res/values/themes.xml</p>
+<pre>
+&lt;?xml version="1.0" encoding="utf-8"?>
+&lt;resources>
+    &lt;!-- the theme applied to the application or activity -->
+    &lt;style name="CustomActionBarTheme"
+           parent="&#64;style/Theme.<strong>AppCompat</strong>">
+        &lt;item name="android:actionBarTabStyle">&#64;style/MyActionBarTabs&lt;/item>
+
+        &lt;!-- Support library compatibility -->
+        &lt;item name="actionBarTabStyle">&#64;style/MyActionBarTabs&lt;/item>
+    &lt;style>
+
+    &lt;!-- ActionBar tabs styles -->
+    &lt;style name="MyActionBarTabs"
+           parent="&#64;style/Widget.<strong>AppCompat</strong>.ActionBar.TabView">
+        &lt;!-- tab indicator -->
+        &lt;item name="android:background">&#64;drawable/actionbar_tab_indicator&lt;/item>
+
+        &lt;!-- Support library compatibility -->
+        &lt;item name="background">&#64;drawable/actionbar_tab_indicator&lt;/item>
+    &lt;style>
+&lt;/resources>
+</pre>
+
+<div class="note"><p><strong>More resources</strong></p>
+<ul>
+  <li>See more style properties for the action bar are listed in the <a
+  href="{@docRoot}guide/topics/ui/actionbar.html#Style">Action Bar</a> guide.</li>
+  <li>Learn more about how themes work in the <a
+  href="{@docRoot}guide/topics/ui/themes.html">Styles and Themes</a> guide.</li>
+  <li>For even more complete styling for the action bar,
+try the <a class="external-link" target="_blank"
+  href="www://http.actionbarstylegenerator.com">Android Action Bar Style
+  Generator</a>.</li>
+</ul>
+</div>

docs/html/training/basics/intents/sending.jd

@@ -240,7 +240,7 @@ Intent intent = new Intent(Intent.ACTION_SEND);
 
 // Always use string resources for UI text.
 // This says something like "Share this photo with"
-String title = (String) getResources().getText(R.string.chooser_title);
+String title = getResources().getString(R.string.chooser_title);
 // Create and start the chooser
 Intent chooser = Intent.createChooser(intent, title);
 startActivity(chooser);

docs/html/training/training_toc.cs

@@ -37,6 +37,35 @@
         </ul>
       </li>
 
+      <li class="nav-section">
+        <div class="nav-section-header">
+          <a href="<?cs var:toroot ?>training/basics/actionbar/index.html"
+             description=
+             "The action bar is one of the most important design elements you can implement for your
+app's activities. Although first introduced with API level 11, you can use the Support Library to
+include the action bar on devices running Android 2.1 or higher."
+            >Adding the Action Bar</a>
+        </div>
+        <ul>
+          <li><a href="<?cs var:toroot ?>training/basics/actionbar/setting-up.html">
+            Setting Up the Action Bar
+          </a>
+          </li>
+          <li><a href="<?cs var:toroot ?>training/basics/actionbar/adding-buttons.html">
+            Adding Action Buttons
+          </a>
+          </li>
+          <li><a href="<?cs var:toroot ?>training/basics/actionbar/styling.html">
+            Styling the Action Bar
+          </a>
+          </li>
+          <li><a href="<?cs var:toroot ?>training/basics/actionbar/overlaying.html">
+            Overlaying the Action Bar
+          </a>
+          </li>
+        </ul>
+      </li>
+
       <li class="nav-section">
         <div class="nav-section-header">
           <a href="<?cs var:toroot ?>training/basics/activity-lifecycle/index.html"