1page.title=Overlaying the Action Bar
2page.tags=actionbar
3helpoutsWidget=true
4
5trainingnavtop=true
6
7@jd:body
8
9
10<div id="tb-wrapper">
11  <div id="tb">
12
13<h2>This lesson teaches you to</h2>
14<ol>
15  <li><a href="#EnableOverlay">Enable Overlay Mode</a>
16    <ol>
17      <li><a href="#Overlay11">For Android 3.0 and higher only</a></li>
18      <li><a href="#Overlay7">For Android 2.1 and higher</a></li>
19    </ol>
20  </li>
21  <li><a href="#TopMargin">Specify Layout Top-margin</a></li>
22</ol>
23
24<h2>You should also read</h2>
25<ul>
26  <li><a href="{@docRoot}guide/topics/ui/themes.html">Styles and Themes</a></li>
27</ul>
28  </div>
29</div>
30
31
32<p>By default, the action bar appears at the top of your activity window,
33slightly reducing the amount of space available for the rest of your activity's layout.
34If, during the course of user interaction, you want to hide and show the action bar, you can do so
35by calling {@link android.app.ActionBar#hide()} and
36{@link android.app.ActionBar#show()} on the {@link android.app.ActionBar}. However,
37this causes your activity to recompute and redraw the layout based on its new size.</p>
38
39
40<div class="figure" style="width:280px">
41  <img src="{@docRoot}images/training/basics/actionbar-overlay@2x.png" width="280" alt="" />
42  <p class="img-caption"><strong>Figure 1.</strong> Gallery's action bar in overlay mode.</p>
43</div>
44
45<p>To avoid resizing your layout when the action bar hides and shows, you can enable <em>overlay
46mode</em> for the action bar. When in overlay mode, your activity layout uses all the space
47available as if the action bar is not there and the system draws the action bar in front of
48your layout. This obscures some of the layout at the top, but now when the action bar hides or
49appears, the system does not need to resize your layout and the transition is seamless.</p>
50
51<p class="note"><strong>Tip:</strong>
52If you want your layout to be partially visible behind the action bar, create a custom
53style for the action bar with a partially transparent background, such as the one shown
54in figure 1. For information about how to define the action bar background, read
55<a href="{@docRoot}training/basics/actionbar/styling.html">Styling the Action Bar</a>.</p>
56
57
58<h2 id="EnableOverlay">Enable Overlay Mode</h2>
59
60<p>To enable overlay mode for the action bar, you need to create a custom theme that
61extends an existing action bar theme and set the {@code android:windowActionBarOverlay} property to
62{@code true}.</p>
63
64
65<h3 id="Overlay11">For Android 3.0 and higher only</h3>
66
67<p>If your
68<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a>
69is set to {@code 11} or higher, your custom theme should use
70{@link android.R.style#Theme_Holo Theme.Holo} theme (or one of its descendants) as your parent
71theme. For example:</p>
72
73<pre>
74&lt;resources>
75    &lt;!-- the theme applied to the application or activity -->
76    &lt;style name="CustomActionBarTheme"
77           parent="&#64;android:style/Theme.Holo">
78        &lt;item name="android:windowActionBarOverlay">true&lt;/item>
79    &lt;/style>
80&lt;/resources>
81</pre>
82
83
84<h3 id="Overlay7">For Android 2.1 and higher</h3>
85
86<p>If your app is using the Support Library for compatibility on devices
87running versions lower than Android 3.0, your custom theme should use
88{@link android.support.v7.appcompat.R.style#Theme_AppCompat Theme.AppCompat} theme
89(or one of its descendants) as your parent theme. For example:</p>
90
91<pre>
92&lt;resources>
93    &lt;!-- the theme applied to the application or activity -->
94    &lt;style name="CustomActionBarTheme"
95           parent="&#64;android:style/Theme.<strong>AppCompat</strong>">
96        &lt;item name="android:windowActionBarOverlay">true&lt;/item>
97
98        &lt;!-- Support library compatibility -->
99        &lt;item name="windowActionBarOverlay">true&lt;/item>
100    &lt;/style>
101&lt;/resources>
102</pre>
103
104<p>Also notice that this theme includes two definitions for the {@code windowActionBarOverlay}
105style: one with the {@code android:} prefix and one without. The one with the {@code android:}
106prefix is for versions of Android that include the style in the platform and the one
107without the prefix is for older versions that read the style from the Support Library.</p>
108
109
110
111
112
113<h2 id="TopMargin">Specify Layout Top-margin</h2>
114
115<p>When the action bar is in overlay mode, it might obscure some of your layout that should
116remain visible. To ensure that such items remain below the action bar at all times,
117add either margin or padding to the top of the view(s)
118using the height specified by {@link android.R.attr#actionBarSize}. For example:</p>
119
120<pre>
121&lt;RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
122    android:layout_width="match_parent"
123    android:layout_height="match_parent"
124    android:paddingTop="?android:attr/actionBarSize">
125    ...
126&lt;/RelativeLayout>
127</pre>
128
129<p>If you're using the Support Library for the action bar, you need to remove the
130{@code android:} prefix. For example:</p>
131
132<pre>
133&lt;!-- Support library compatibility -->
134&lt;RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
135    android:layout_width="match_parent"
136    android:layout_height="match_parent"
137    android:paddingTop="?attr/actionBarSize">
138    ...
139&lt;/RelativeLayout>
140</pre>
141
142<p>In this case, the {@code ?attr/actionBarSize} value without the
143prefix works on all versions, including Android 3.0 and higher.</p>