diff options
Diffstat (limited to 'docs')
18 files changed, 1012 insertions, 2 deletions
diff --git a/docs/html/images/training/basics/actionbar-actions.png b/docs/html/images/training/basics/actionbar-actions.png Binary files differnew file mode 100644 index 0000000..5195a8c --- /dev/null +++ b/docs/html/images/training/basics/actionbar-actions.png diff --git a/docs/html/images/training/basics/actionbar-basic.png b/docs/html/images/training/basics/actionbar-basic.png Binary files differnew file mode 100644 index 0000000..ba77659 --- /dev/null +++ b/docs/html/images/training/basics/actionbar-basic.png diff --git a/docs/html/images/training/basics/actionbar-overlay@2x.png b/docs/html/images/training/basics/actionbar-overlay@2x.png Binary files differnew file mode 100644 index 0000000..7014a19 --- /dev/null +++ b/docs/html/images/training/basics/actionbar-overlay@2x.png diff --git a/docs/html/images/training/basics/actionbar-theme-custom-tabs@2x.png b/docs/html/images/training/basics/actionbar-theme-custom-tabs@2x.png Binary files differnew file mode 100644 index 0000000..ea8c93b --- /dev/null +++ b/docs/html/images/training/basics/actionbar-theme-custom-tabs@2x.png diff --git a/docs/html/images/training/basics/actionbar-theme-custom@2x.png b/docs/html/images/training/basics/actionbar-theme-custom@2x.png Binary files differnew file mode 100644 index 0000000..bb6f1a4 --- /dev/null +++ b/docs/html/images/training/basics/actionbar-theme-custom@2x.png diff --git a/docs/html/images/training/basics/actionbar-theme-dark-solid@2x.png b/docs/html/images/training/basics/actionbar-theme-dark-solid@2x.png Binary files differnew file mode 100644 index 0000000..bd16ffe --- /dev/null +++ b/docs/html/images/training/basics/actionbar-theme-dark-solid@2x.png diff --git a/docs/html/images/training/basics/actionbar-theme-dark@2x.png b/docs/html/images/training/basics/actionbar-theme-dark@2x.png Binary files differnew file mode 100644 index 0000000..88c3b22 --- /dev/null +++ b/docs/html/images/training/basics/actionbar-theme-dark@2x.png diff --git a/docs/html/images/training/basics/actionbar-theme-light-darkactionbar@2x.png b/docs/html/images/training/basics/actionbar-theme-light-darkactionbar@2x.png Binary files differnew file mode 100644 index 0000000..5509e16 --- /dev/null +++ b/docs/html/images/training/basics/actionbar-theme-light-darkactionbar@2x.png diff --git a/docs/html/images/training/basics/actionbar-theme-light-solid@2x.png b/docs/html/images/training/basics/actionbar-theme-light-solid@2x.png Binary files differnew file mode 100644 index 0000000..810ef46 --- /dev/null +++ b/docs/html/images/training/basics/actionbar-theme-light-solid@2x.png diff --git a/docs/html/images/training/basics/actionbar-theme-light@2x.png b/docs/html/images/training/basics/actionbar-theme-light@2x.png Binary files differnew file mode 100644 index 0000000..a0af43a --- /dev/null +++ b/docs/html/images/training/basics/actionbar-theme-light@2x.png diff --git a/docs/html/tools/support-library/setup.jd b/docs/html/tools/support-library/setup.jd index a7f068e..73d9468 100644 --- a/docs/html/tools/support-library/setup.jd +++ b/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)"> diff --git a/docs/html/training/basics/actionbar/adding-buttons.jd b/docs/html/training/basics/actionbar/adding-buttons.jd new file mode 100644 index 0000000..5fb0d59 --- /dev/null +++ b/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 <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> +<menu xmlns:android="http://schemas.android.com/apk/res/android" > + <!-- Search, should appear as action button --> + <item android:id="@+id/action_search" + android:icon="@drawable/ic_action_search" + android:title="@string/action_search" + android:showAsAction="ifRoom" /> + <!-- Settings, should always be in the overflow --> + <item android:id="@+id/action_settings" + android:title="@string/action_settings" + android:showAsAction="never" /> +</menu> +</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> +<menu xmlns:android="http://schemas.android.com/apk/res/android" + <strong>xmlns:yourapp="http://schemas.android.com/apk/res-auto"</strong> > + <!-- Search, should appear as action button --> + <item android:id="@+id/action_search" + android:icon="@drawable/ic_action_search" + android:title="@string/action_search" + <strong>yourapp:showAsAction="ifRoom"</strong> /> + ... +</menu> +</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> +@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—the returned ID matches the value you declared in the +corresponding {@code <item>} element's {@code android:id} attribute.</p> + +<pre> +@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> +<application ... > + ... + <!-- The main/home activity (it has no parent activity) --> + <activity + android:name="com.example.myfirstapp.MainActivity" ...> + ... + </activity> + <!-- A child of the main activity --> + <activity + android:name="com.example.myfirstapp.DisplayMessageActivity" + android:label="@string/title_activity_display_message" + android:parentActivityName="com.example.myfirstapp.MainActivity" > + <!-- Parent activity meta-data to support 4.0 and lower --> + <meta-data + android:name="android.support.PARENT_ACTIVITY" + android:value="com.example.myfirstapp.MainActivity" /> + </activity> +</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—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>.
\ No newline at end of file diff --git a/docs/html/training/basics/actionbar/index.jd b/docs/html/training/basics/actionbar/index.jd new file mode 100644 index 0000000..f0de758 --- /dev/null +++ b/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> + diff --git a/docs/html/training/basics/actionbar/overlaying.jd b/docs/html/training/basics/actionbar/overlaying.jd new file mode 100644 index 0000000..800cd44 --- /dev/null +++ b/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> +<resources> + <!-- the theme applied to the application or activity --> + <style name="CustomActionBarTheme" + parent="@android:style/Theme.Holo"> + <item name="android:windowActionBarOverlay">true</item> + </style> +</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> +<resources> + <!-- the theme applied to the application or activity --> + <style name="CustomActionBarTheme" + parent="@android:style/Theme.<strong>AppCompat</strong>"> + <item name="android:windowActionBarOverlay">true</item> + + <!-- Support library compatibility --> + <item name="windowActionBarOverlay">true</item> + </style> +</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> +<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"> + ... +</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> +<!-- Support library compatibility --> +<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:layout_width="match_parent" + android:layout_height="match_parent" + android:paddingTop="?attr/actionBarSize"> + ... +</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>
\ No newline at end of file diff --git a/docs/html/training/basics/actionbar/setting-up.jd b/docs/html/training/basics/actionbar/setting-up.jd new file mode 100644 index 0000000..158ce92 --- /dev/null +++ b/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> +<manifest ... > + <uses-sdk android:minSdkVersion="11" ... /> + ... +</manifest> +</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 + <application>}</a> element or individual + <a href="{@docRoot}guide/topics/manifest/application-element.html">{@code <activity>}</a> + elements to use one of the {@link android.support.v7.appcompat.R.style#Theme_AppCompat + Theme.AppCompat} themes. For example: + <pre><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> +<manifest ... > + <uses-sdk android:minSdkVersion="7" android:targetSdkVersion="18" /> + ... +</manifest> +</pre>
\ No newline at end of file diff --git a/docs/html/training/basics/actionbar/styling.jd b/docs/html/training/basics/actionbar/styling.jd new file mode 100644 index 0000000..a1cc10c --- /dev/null +++ b/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—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 +<application>}</a> element or individual +<a href="{@docRoot}guide/topics/manifest/application-element.html">{@code <activity>}</a> +elements.</p> + +<p>For example:</p> +<pre> +<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> +<?xml version="1.0" encoding="utf-8"?> +<resources> + <!-- the theme applied to the application or activity --> + <style name="CustomActionBarTheme" + parent="@style/Theme.Holo.Light.DarkActionBar"> + <item name="android:actionBarStyle">@style/MyActionBar</item> + <style> + + <!-- ActionBar styles --> + <style name="MyActionBar" + parent="@style/Widget.Holo.Light.ActionBar.Solid.Inverse"> + <item name="android:background">@drawable/actionbar_background</item> + <style> +</resources> +</pre> + +<p>Then apply your theme to your entire app or individual activities:</p> +<pre> +<application android:theme="@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> +<?xml version="1.0" encoding="utf-8"?> +<resources> + <!-- the theme applied to the application or activity --> + <style name="CustomActionBarTheme" + parent="@style/Theme.<strong>AppCompat</strong>.Light.DarkActionBar"> + <item name="android:actionBarStyle">@style/MyActionBar</item> + + <!-- Support library compatibility --> + <item name="actionBarStyle">@style/MyActionBar</item> + <style> + + <!-- ActionBar styles --> + <style name="MyActionBar" + parent="@style/Widget.<strong>AppCompat</strong>.Light.ActionBar.Solid.Inverse"> + <item name="android:background">@drawable/actionbar_background</item> + + <!-- Support library compatibility --> + <item name="background">@drawable/actionbar_background</item> + <style> +</resources> +</pre> + +<p>Then apply your theme to your entire app or individual activities:</p> +<pre> +<application android:theme="@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> +<?xml version="1.0" encoding="utf-8"?> +<resources> + <!-- the theme applied to the application or activity --> + <style name="CustomActionBarTheme" + parent="@style/Theme.Holo"> + <item name="android:actionBarStyle">@style/MyActionBar</item> + <item name="android:actionBarTabTextStyle">@style/MyActionBarTabText</item> + <item name="android:actionMenuTextColor">@color/actionbar_text</item> + <style> + + <!-- ActionBar styles --> + <style name="MyActionBar" + parent="@style/Widget.Holo.ActionBar"> + <item name="android:titleTextStyle">@style/MyActionBarTitleText</item> + <style> + + <!-- ActionBar title text --> + <style name="MyActionBarTitleText" + parent="@style/TextAppearance.Holo.Widget.ActionBar.Title"> + <item name="android:textColor">@color/actionbar_text</item> + <style> + + <!-- ActionBar tabs text styles --> + <style name="MyActionBarTabText" + parent="@style/Widget.Holo.ActionBar.TabText"> + <item name="android:textColor">@color/actionbar_text</item> + <style> +</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> +<?xml version="1.0" encoding="utf-8"?> +<resources> + <!-- the theme applied to the application or activity --> + <style name="CustomActionBarTheme" + parent="@style/Theme.<strong>AppCompat</strong>"> + <item name="android:actionBarStyle">@style/MyActionBar</item> + <item name="android:actionBarTabTextStyle">@style/MyActionBarTabText</item> + <item name="android:actionMenuTextColor">@color/actionbar_text</item> + + <!-- Support library compatibility --> + <item name="actionBarStyle">@style/MyActionBar</item> + <item name="actionBarTabTextStyle">@style/MyActionBarTabText</item> + <item name="actionMenuTextColor">@color/actionbar_text</item> + <style> + + <!-- ActionBar styles --> + <style name="MyActionBar" + parent="@style/Widget.<strong>AppCompat</strong>.ActionBar"> + <item name="android:titleTextStyle">@style/MyActionBarTitleText</item> + + <!-- Support library compatibility --> + <item name="titleTextStyle">@style/MyActionBarTitleText</item> + <style> + + <!-- ActionBar title text --> + <style name="MyActionBarTitleText" + parent="@style/TextAppearance.<strong>AppCompat</strong>.Widget.ActionBar.Title"> + <item name="android:textColor">@color/actionbar_text</item> + <!-- The textColor property is backward compatible with the Support Library --> + <style> + + <!-- ActionBar tabs text --> + <style name="MyActionBarTabText" + parent="@style/Widget.<strong>AppCompat</strong>.ActionBar.TabText"> + <item name="android:textColor">@color/actionbar_text</item> + <!-- The textColor property is backward compatible with the Support Library --> + <style> +</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> +<?xml version="1.0" encoding="utf-8"?> +<selector xmlns:android="http://schemas.android.com/apk/res/android"> + +<!-- STATES WHEN BUTTON IS NOT PRESSED --> + + <!-- Non focused states --> + <item android:state_focused="false" android:state_selected="false" + android:state_pressed="false" + android:drawable="@drawable/tab_unselected" /> + <item android:state_focused="false" android:state_selected="true" + android:state_pressed="false" + android:drawable="@drawable/tab_selected" /> + + <!-- Focused states (such as when focused with a d-pad or mouse hover) --> + <item android:state_focused="true" android:state_selected="false" + android:state_pressed="false" + android:drawable="@drawable/tab_unselected_focused" /> + <item android:state_focused="true" android:state_selected="true" + android:state_pressed="false" + android:drawable="@drawable/tab_selected_focused" /> + + +<!-- STATES WHEN BUTTON IS PRESSED --> + + <!-- Non focused states --> + <item android:state_focused="false" android:state_selected="false" + android:state_pressed="true" + android:drawable="@drawable/tab_unselected_pressed" /> + <item android:state_focused="false" android:state_selected="true" + android:state_pressed="true" + android:drawable="@drawable/tab_selected_pressed" /> + + <!-- Focused states (such as when focused with a d-pad or mouse hover) --> + <item android:state_focused="true" android:state_selected="false" + android:state_pressed="true" + android:drawable="@drawable/tab_unselected_pressed" /> + <item android:state_focused="true" android:state_selected="true" + android:state_pressed="true" + android:drawable="@drawable/tab_selected_pressed" /> +</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> +<?xml version="1.0" encoding="utf-8"?> +<resources> + <!-- the theme applied to the application or activity --> + <style name="CustomActionBarTheme" + parent="@style/Theme.Holo"> + <item name="android:actionBarTabStyle">@style/MyActionBarTabs</item> + <style> + + <!-- ActionBar tabs styles --> + <style name="MyActionBarTabs" + parent="@style/Widget.Holo.ActionBar.TabView"> + <!-- tab indicator --> + <item name="android:background">@drawable/actionbar_tab_indicator</item> + <style> +</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> +<?xml version="1.0" encoding="utf-8"?> +<resources> + <!-- the theme applied to the application or activity --> + <style name="CustomActionBarTheme" + parent="@style/Theme.<strong>AppCompat</strong>"> + <item name="android:actionBarTabStyle">@style/MyActionBarTabs</item> + + <!-- Support library compatibility --> + <item name="actionBarTabStyle">@style/MyActionBarTabs</item> + <style> + + <!-- ActionBar tabs styles --> + <style name="MyActionBarTabs" + parent="@style/Widget.<strong>AppCompat</strong>.ActionBar.TabView"> + <!-- tab indicator --> + <item name="android:background">@drawable/actionbar_tab_indicator</item> + + <!-- Support library compatibility --> + <item name="background">@drawable/actionbar_tab_indicator</item> + <style> +</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>
\ No newline at end of file diff --git a/docs/html/training/basics/intents/sending.jd b/docs/html/training/basics/intents/sending.jd index 1646b91..aba3896 100644 --- a/docs/html/training/basics/intents/sending.jd +++ b/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); diff --git a/docs/html/training/training_toc.cs b/docs/html/training/training_toc.cs index cb57752..6661889 100644 --- a/docs/html/training/training_toc.cs +++ b/docs/html/training/training_toc.cs @@ -39,6 +39,35 @@ <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" description= "How Android activities live and die and how to create |
