blob: 7c63952de11525821ec17fd070f0db069f69fa17 [file] [log] [blame]
page.title=Styling the Action Bar
page.tags=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="#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://www.actionbarstylegenerator.com">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;android: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;android: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="http://www.actionbarstylegenerator.com">Android Action Bar Style
Generator</a>.</li>
</ul>
</div>