1b10b48f62d3cac684424e4181d4e8ec61f227e95Scott Mainpage.title=Action Bar 233baa5ad7d8cdcc89ce4fbc3bc8cd537d5f5d639Joe Fernandezpage.tags=actionbar,menu,tabs 3f213415175ec83df7b39089d559eb9d02b72883aScott Main 418439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main@jd:body 518439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 6e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 7e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<a class="notice-designers top" href="{@docRoot}design/patterns/actionbar.html"> 8e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <div> 9e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <h3>Design Guide</h3> 10e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <p>Action Bar</p> 11e04c4543027df129cd7c004c1b21b01a7f4928adScott Main </div> 12e04c4543027df129cd7c004c1b21b01a7f4928adScott Main</a> 13e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 1418439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main<div id="qv-wrapper"> 1518439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main<div id="qv"> 1618439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 1718439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main <h2>In this document</h2> 18258a51e3e687d4d469de501f17dd937cdc29019aScott Main<ol> 19258a51e3e687d4d469de501f17dd937cdc29019aScott Main <li><a href="#Adding">Adding the Action Bar</a> 20258a51e3e687d4d469de501f17dd937cdc29019aScott Main <ol> 21258a51e3e687d4d469de501f17dd937cdc29019aScott Main <li><a href="#Removing">Removing the action bar</a></li> 22e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <li><a href="#Logo">Using a logo instead of an icon</a></li> 23258a51e3e687d4d469de501f17dd937cdc29019aScott Main </ol> 24258a51e3e687d4d469de501f17dd937cdc29019aScott Main </li> 25258a51e3e687d4d469de501f17dd937cdc29019aScott Main <li><a href="#ActionItems">Adding Action Items</a> 26258a51e3e687d4d469de501f17dd937cdc29019aScott Main <ol> 27e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <li><a href="#ActionEvents">Handling clicks on action items</a></li> 28258a51e3e687d4d469de501f17dd937cdc29019aScott Main <li><a href="#SplitBar">Using split action bar</a></li> 29258a51e3e687d4d469de501f17dd937cdc29019aScott Main </ol> 30258a51e3e687d4d469de501f17dd937cdc29019aScott Main </li> 31e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <li><a href="#Home">Navigating Up with the App Icon</a></li> 32258a51e3e687d4d469de501f17dd937cdc29019aScott Main <li><a href="#ActionView">Adding an Action View</a> 33258a51e3e687d4d469de501f17dd937cdc29019aScott Main <ol> 34258a51e3e687d4d469de501f17dd937cdc29019aScott Main <li><a href="#ActionViewCollapsing">Handling collapsible action views</a></li> 35e04c4543027df129cd7c004c1b21b01a7f4928adScott Main </ol> 36258a51e3e687d4d469de501f17dd937cdc29019aScott Main </li> 37258a51e3e687d4d469de501f17dd937cdc29019aScott Main <li><a href="#ActionProvider">Adding an Action Provider</a> 38258a51e3e687d4d469de501f17dd937cdc29019aScott Main <ol> 39258a51e3e687d4d469de501f17dd937cdc29019aScott Main <li><a href="#ShareActionProvider">Using the ShareActionProvider</a></li> 40258a51e3e687d4d469de501f17dd937cdc29019aScott Main <li><a href="#CreatingActionProvider">Creating a custom action provider</a></li> 41258a51e3e687d4d469de501f17dd937cdc29019aScott Main </ol> 42258a51e3e687d4d469de501f17dd937cdc29019aScott Main </li> 43258a51e3e687d4d469de501f17dd937cdc29019aScott Main <li><a href="#Tabs">Adding Navigation Tabs</a></li> 44258a51e3e687d4d469de501f17dd937cdc29019aScott Main <li><a href="#Dropdown">Adding Drop-down Navigation</a></li> 45258a51e3e687d4d469de501f17dd937cdc29019aScott Main <li><a href="#Style">Styling the Action Bar</a> 46258a51e3e687d4d469de501f17dd937cdc29019aScott Main <ol> 47258a51e3e687d4d469de501f17dd937cdc29019aScott Main <li><a href="#GeneralStyles">General appearance</a></li> 48258a51e3e687d4d469de501f17dd937cdc29019aScott Main <li><a href="#ActionItemStyles">Action items</a></li> 49258a51e3e687d4d469de501f17dd937cdc29019aScott Main <li><a href="#NavigationStyles">Navigation tabs</a></li> 50258a51e3e687d4d469de501f17dd937cdc29019aScott Main <li><a href="#DropDownStyles">Drop-down lists</a></li> 51e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <li><a href="#StyleExample">Example theme</a></li> 52258a51e3e687d4d469de501f17dd937cdc29019aScott Main </ol> 53258a51e3e687d4d469de501f17dd937cdc29019aScott Main </li> 54258a51e3e687d4d469de501f17dd937cdc29019aScott Main</ol> 5518439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 5618439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main <h2>Key classes</h2> 5718439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main <ol> 58e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <li>{@link android.support.v7.app.ActionBar}</li> 5918439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main <li>{@link android.view.Menu}</li> 6018439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main </ol> 61258a51e3e687d4d469de501f17dd937cdc29019aScott Main 6218439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main</div> 6318439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main</div> 6418439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 65e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>The action bar is a window feature that identifies the user location, and 66e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainprovides user actions and navigation modes. Using the action bar offers your users a 67e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainfamiliar interface across applications that the system gracefully adapts 68e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainfor different screen configurations.</p> 69258a51e3e687d4d469de501f17dd937cdc29019aScott Main 70e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<img src="{@docRoot}images/ui/actionbar@2x.png" alt="" width="428" height="215" /> 71e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p class="img-caption"><strong>Figure 1.</strong> An action bar that includes the [1] app icon, 72e04c4543027df129cd7c004c1b21b01a7f4928adScott Main[2] two action items, and [3] action overflow.</p> 7318439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 74e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>The action bar provides several key functions:</p> 7518439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 76e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<ul> 77e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <li>Provides a dedicated space for giving your app an identity and indicating the user's 78e04c4543027df129cd7c004c1b21b01a7f4928adScott Main location in the app.</li> 79e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <li>Makes important actions prominent and accessible in a predictable way 80e04c4543027df129cd7c004c1b21b01a7f4928adScott Main (such as <em>Search</em>).</li> 81e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <li>Supports consistent navigation and view switching within apps (with tabs or drop-down 82e04c4543027df129cd7c004c1b21b01a7f4928adScott Main lists).</li> 83258a51e3e687d4d469de501f17dd937cdc29019aScott Main</ul> 846ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 85e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>For more information about the action bar's interaction patterns and design guidelines, 86e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainsee the <a href="{@docRoot}design/patterns/actionbar.html">Action Bar</a> 87e04c4543027df129cd7c004c1b21b01a7f4928adScott Maindesign guide.</p> 88258a51e3e687d4d469de501f17dd937cdc29019aScott Main 89e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>The {@link android.app.ActionBar} APIs were first added in Android 3.0 (API level 11) but they 90e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainare also available in the <a href="{@docRoot}tools/support-library/index.html">Support Library</a> 91f213415175ec83df7b39089d559eb9d02b72883aScott Mainfor compatibility with Android 2.1 (API level 7) and above.</p> 92e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 93e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p><b>This guide focuses on how to use the 94e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainsupport library's action bar</b>, but if your app supports <em>only</em> Android 3.0 or higher, you 95e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainshould use the {@link android.app.ActionBar} APIs in the framework. Most of the APIs are 96e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainthe same—but reside in a different package namespace—with a few exceptions to method 97e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainnames or signatures that are noted in the sections below.</p> 985e0959393426371dadef2c7905d5c915a1ac2dd4Scott Main 99258a51e3e687d4d469de501f17dd937cdc29019aScott Main 100e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<div class="caution"> 101e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p><strong>Caution:</strong> Be certain you import 102e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainthe {@code ActionBar} class (and related APIs) from the appropriate package:</p> 103e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<ul> 104e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<li>If supporting API levels <em>lower than</em> 11: <br> 105e04c4543027df129cd7c004c1b21b01a7f4928adScott Main{@code import android.support.v7.app.ActionBar}</li> 106e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<li>If supporting <em>only</em> API level 11 and higher: <br> 107e04c4543027df129cd7c004c1b21b01a7f4928adScott Main{@code import android.app.ActionBar}</li> 108e04c4543027df129cd7c004c1b21b01a7f4928adScott Main</ul> 109eb5dacddc443db0752529a69a9c48dab1b129a18Scott Main</div> 110eb5dacddc443db0752529a69a9c48dab1b129a18Scott Main 111eb5dacddc443db0752529a69a9c48dab1b129a18Scott Main 112e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p class="note"><strong>Note:</strong> If you're looking for information about the <em>contextual 113e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainaction bar</em> for displaying contextual action items, see the <a 114e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainhref="{@docRoot}guide/topics/ui/menus.html#context-menu">Menu</a> guide.</p> 115eb5dacddc443db0752529a69a9c48dab1b129a18Scott Main 11618439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 11718439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 11818439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main<h2 id="Adding">Adding the Action Bar</h2> 11918439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 120e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>As mentioned above, this guide focuses on how to use the {@link 121e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.support.v7.app.ActionBar} APIs in the support library. So before you can add the action 122e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainbar, you must set up your project with the <strong>appcompat v7</strong> support library by 123e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainfollowing the instructions in the <a href="{@docRoot}tools/support-library/setup.html">Support 124e04c4543027df129cd7c004c1b21b01a7f4928adScott MainLibrary Setup</a>.</p> 12518439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 126e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>Once your project is set up with the support library, here's how to add the action bar:</p> 127e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<ol> 128e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <li>Create your activity by extending {@link android.support.v7.app.ActionBarActivity}.</li> 129e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <li>Use (or extend) one of the {@link android.support.v7.appcompat.R.style#Theme_AppCompat 130e04c4543027df129cd7c004c1b21b01a7f4928adScott Main Theme.AppCompat} themes for your activity. For example: 131e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <pre><activity android:theme="@style/Theme.AppCompat.Light" ... ></pre> 132e04c4543027df129cd7c004c1b21b01a7f4928adScott Main </li> 133e04c4543027df129cd7c004c1b21b01a7f4928adScott Main</ol> 13418439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 135f213415175ec83df7b39089d559eb9d02b72883aScott Main<p>Now your activity includes the action bar when running on Android 2.1 (API level 7) or higher. 136e04c4543027df129cd7c004c1b21b01a7f4928adScott Main</p> 1376ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 138e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<div class="note"> 139e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p><b>On API level 11 or higher</b></p> 140e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>The action bar is included in all activities that use the 141e04c4543027df129cd7c004c1b21b01a7f4928adScott Main{@link android.R.style#Theme_Holo Theme.Holo} theme (or one of its 142e04c4543027df129cd7c004c1b21b01a7f4928adScott Maindescendants), which is the default theme when either the <a 143e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainhref="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> or 144e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> 145e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainattribute is set to {@code "11"} or higher. If you don't want the action bar for an 146e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainactivity, set the activity theme to {@link android.R.style#Theme_Holo_NoActionBar 147e04c4543027df129cd7c004c1b21b01a7f4928adScott MainTheme.Holo.NoActionBar}.</p> 148e04c4543027df129cd7c004c1b21b01a7f4928adScott Main</div> 14950403a203357ec9e003b198728f89278c88d4f0fScott Main 15050403a203357ec9e003b198728f89278c88d4f0fScott Main 151258a51e3e687d4d469de501f17dd937cdc29019aScott Main<h3 id="Removing">Removing the action bar</h3> 1526ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 153e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>You can hide the action bar at runtime by calling {@link android.support.v7.app.ActionBar#hide}. 154e04c4543027df129cd7c004c1b21b01a7f4928adScott MainFor example:</p> 15550403a203357ec9e003b198728f89278c88d4f0fScott Main 15650403a203357ec9e003b198728f89278c88d4f0fScott Main<pre> 157e04c4543027df129cd7c004c1b21b01a7f4928adScott MainActionBar actionBar = {@link android.support.v7.app.ActionBarActivity#getSupportActionBar()}; 1586ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott MainactionBar.hide(); 15950403a203357ec9e003b198728f89278c88d4f0fScott Main</pre> 16018439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 161e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<div class="note"> 162e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p><b>On API level 11 or higher</b></p> 163e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>Get the {@link android.app.ActionBar} with the {@link android.app.Activity#getActionBar} 164e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainmethod.</p> 165e04c4543027df129cd7c004c1b21b01a7f4928adScott Main</div> 166e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 167e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>When the action bar hides, the system adjusts your layout to fill the 168e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainscreen space now available. You can bring the action bar back by calling {@link 169e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.support.v7.app.ActionBar#show()}.</p> 170258a51e3e687d4d469de501f17dd937cdc29019aScott Main 171258a51e3e687d4d469de501f17dd937cdc29019aScott Main<p>Beware that hiding and removing the action bar causes your activity to re-layout in order to 172e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainaccount for the space consumed by the action bar. If your activity often hides and shows the 173e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainaction bar, you might want to enable <em>overlay mode</em>. Overlay mode 174e04c4543027df129cd7c004c1b21b01a7f4928adScott Maindraws the action bar in front of your activity layout, obscuring the top portion. This 175258a51e3e687d4d469de501f17dd937cdc29019aScott Mainway, your layout remains fixed when the action bar hides and re-appears. To enable overlay mode, 176e04c4543027df129cd7c004c1b21b01a7f4928adScott Maincreate a custom theme for your activity and set {@link 177e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.support.v7.appcompat.R.attr#windowActionBarOverlay 178e04c4543027df129cd7c004c1b21b01a7f4928adScott MainwindowActionBarOverlay} to {@code true}. For more information, see the section below about <a 179258a51e3e687d4d469de501f17dd937cdc29019aScott Mainhref="#Style">Styling the Action Bar</a>.</p> 180258a51e3e687d4d469de501f17dd937cdc29019aScott Main 181e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 182e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<h3 id="Logo">Using a logo instead of an icon</h3> 183e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 184e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>By default, the system uses your application icon in the action bar, as specified by the <a 185e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainhref="{@docRoot}guide/topics/manifest/application-element.html#icon">{@code icon}</a> 186e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainattribute in the <a href="{@docRoot}guide/topics/manifest/application-element.html">{@code 187e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<application>}</a> or <a 188e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainhref="{@docRoot}guide/topics/manifest/activity-element.html">{@code 189e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<activity>}</a> element. However, if you also specify the <a 190e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainhref="{@docRoot}guide/topics/manifest/application-element.html#logo">{@code logo}</a> 191e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainattribute, then the action bar uses the logo image instead of the icon.</p> 192e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 193e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>A logo should usually be wider than the icon, but should not include unnecessary text. You 194e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainshould generally use a logo only when it represents your brand in a traditional format that users 195e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainrecognize. A good example is the YouTube app's logo—the logo represents the expected user 196e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainbrand, whereas the app's icon is a modified version that conforms to the square requirement 197e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainfor the launcher icon.</p> 198e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 1996ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 2006ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 20118439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 20218439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main<h2 id="ActionItems">Adding Action Items</h2> 20318439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 204e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<div class="figure" style="width:340px"> 205e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <img src="{@docRoot}images/ui/actionbar-item-withtext.png" width="340" alt="" /> 206e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <p class="img-caption"><strong>Figure 2.</strong> Action bar with three action buttons and 207e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainthe overflow button.</p> 20818439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main</div> 20918439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 210e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>The action bar provides users access to the most important action 211e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainitems relating to the app's current 212e04c4543027df129cd7c004c1b21b01a7f4928adScott Maincontext. Those that appear directly in the action bar with an icon and/or text are known 213e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainas <em>action buttons</em>. Actions that can't fit in the action bar or aren't 214e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainimportant enough are hidden in the action overflow. 215e04c4543027df129cd7c004c1b21b01a7f4928adScott MainThe user can reveal a list of the other actions by pressing the overflow button 216e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainon the right side (or the device <em>Menu</em> button, if available).</p> 217e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 218e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>When your activity starts, the system populates the action items by calling your activity's 219e04c4543027df129cd7c004c1b21b01a7f4928adScott Main{@link android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} method. Use this 220e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainmethod to inflate a <a 221e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainhref="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a> that defines all the 222e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainaction items. For example, here's a menu resource defining a couple of menu items:</p> 223e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 224e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p class="code-caption">res/menu/main_activity_actions.xml</p> 225e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<pre> 226e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<menu xmlns:android="http://schemas.android.com/apk/res/android" > 227e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <item android:id="@+id/action_search" 228e04c4543027df129cd7c004c1b21b01a7f4928adScott Main android:icon="@drawable/ic_action_search" 229e04c4543027df129cd7c004c1b21b01a7f4928adScott Main android:title="@string/action_search"/> 230e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <item android:id="@+id/action_compose" 231e04c4543027df129cd7c004c1b21b01a7f4928adScott Main android:icon="@drawable/ic_action_compose" 232e04c4543027df129cd7c004c1b21b01a7f4928adScott Main android:title="@string/action_compose" /> 233e04c4543027df129cd7c004c1b21b01a7f4928adScott Main</menu> 234e04c4543027df129cd7c004c1b21b01a7f4928adScott Main</pre> 235e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 236e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>Then in your activity's {@link android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} 237e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainmethod, inflate the menu resource into the given {@link android.view.Menu} 238e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainto add each item to the action bar:</p> 2396ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 240258a51e3e687d4d469de501f17dd937cdc29019aScott Main<pre> 241258a51e3e687d4d469de501f17dd937cdc29019aScott Main@Override 242258a51e3e687d4d469de501f17dd937cdc29019aScott Mainpublic boolean onCreateOptionsMenu(Menu menu) { 243e04c4543027df129cd7c004c1b21b01a7f4928adScott Main // Inflate the menu items for use in the action bar 244258a51e3e687d4d469de501f17dd937cdc29019aScott Main MenuInflater inflater = getMenuInflater(); 245e04c4543027df129cd7c004c1b21b01a7f4928adScott Main inflater.inflate(R.menu.main_activity_actions, menu); 246e04c4543027df129cd7c004c1b21b01a7f4928adScott Main return super.onCreateOptionsMenu(menu); 247258a51e3e687d4d469de501f17dd937cdc29019aScott Main} 248258a51e3e687d4d469de501f17dd937cdc29019aScott Main</pre> 249258a51e3e687d4d469de501f17dd937cdc29019aScott Main 250e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>To request that an item appear directly in the action bar 251e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainas an action button, include {@code 252e04c4543027df129cd7c004c1b21b01a7f4928adScott MainshowAsAction="ifRoom"} in the {@code <item>} tag. For example:</p> 253258a51e3e687d4d469de501f17dd937cdc29019aScott Main 254e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<pre> 255e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<menu xmlns:android="http://schemas.android.com/apk/res/android" 25684f2a0f5e7a2ae63f4bc64f494b2aa6c94e7eb5aScott Main <strong>xmlns:yourapp="http://schemas.android.com/apk/res-auto"</strong> > 257e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <item android:id="@+id/action_search" 258e04c4543027df129cd7c004c1b21b01a7f4928adScott Main android:icon="@drawable/ic_action_search" 259e04c4543027df129cd7c004c1b21b01a7f4928adScott Main android:title="@string/action_search" 26084f2a0f5e7a2ae63f4bc64f494b2aa6c94e7eb5aScott Main <strong>yourapp:showAsAction="ifRoom"</strong> /> 261e04c4543027df129cd7c004c1b21b01a7f4928adScott Main ... 262e04c4543027df129cd7c004c1b21b01a7f4928adScott Main</menu> 263e04c4543027df129cd7c004c1b21b01a7f4928adScott Main</pre> 264e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 265e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>If there's not enough room for the item in the action bar, it will appear in the action 266e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainoverflow.</p> 267e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 268e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 269e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<div class="note" id="XmlAttributes"> 270e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p><strong>Using XML attributes from the support library</strong></p> 271e04c4543027df129cd7c004c1b21b01a7f4928adScott MainNotice that the {@code showAsAction} attribute above uses a custom namespace defined in the 272e04c4543027df129cd7c004c1b21b01a7f4928adScott Main{@code <menu>} tag. This is necessary when using any XML attributes defined by the support 273e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainlibrary, because these attributes do not exist in the Android framework on older devices. 274e04c4543027df129cd7c004c1b21b01a7f4928adScott MainSo you must use your own namespace as a prefix for all attributes defined by the support library. 275e04c4543027df129cd7c004c1b21b01a7f4928adScott Main</p> 276e04c4543027df129cd7c004c1b21b01a7f4928adScott Main</div> 277e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 278e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>If your menu item supplies both a title and an icon—with the {@code title} and 279e04c4543027df129cd7c004c1b21b01a7f4928adScott Main{@code icon} attributes—then the action item shows only the icon by default. If you 280e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainwant to display the text title, add {@code "withText"} to the {@code showAsAction} 281258a51e3e687d4d469de501f17dd937cdc29019aScott Mainattribute. For example:</p> 282258a51e3e687d4d469de501f17dd937cdc29019aScott Main 28318439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main<pre> 28484f2a0f5e7a2ae63f4bc64f494b2aa6c94e7eb5aScott Main<item yourapp:showAsAction="ifRoom|withText" ... /> 28518439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main</pre> 28618439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 287258a51e3e687d4d469de501f17dd937cdc29019aScott Main<p class="note"><strong>Note:</strong> The {@code "withText"} value is a <em>hint</em> to the 288258a51e3e687d4d469de501f17dd937cdc29019aScott Mainaction bar that the text title should appear. The action bar will show the title when possible, but 289258a51e3e687d4d469de501f17dd937cdc29019aScott Mainmight not if an icon is available and the action bar is constrained for space.</p> 29018439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 291e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>You should always define the {@code title} for each item even if you don't declare that 292e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainthe title appear with the action item, for the following reasons:</p> 293258a51e3e687d4d469de501f17dd937cdc29019aScott Main<ul> 294258a51e3e687d4d469de501f17dd937cdc29019aScott Main <li>If there's not enough room in the action bar for the action item, the menu item appears 295e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainin the overflow where only the title appears.</li> 296258a51e3e687d4d469de501f17dd937cdc29019aScott Main <li>Screen readers for sight-impaired users read the menu item's title.</li> 297258a51e3e687d4d469de501f17dd937cdc29019aScott Main <li>If the action item appears with only the icon, a user can long-press the item to reveal a 298e04c4543027df129cd7c004c1b21b01a7f4928adScott Maintool-tip that displays the action title.</li> 299258a51e3e687d4d469de501f17dd937cdc29019aScott Main</ul> 30018439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 301e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>The {@code icon} is optional, but recommended. For icon design recommendations, 302e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainsee the <a href="{@docRoot}design/style/iconography.html#action-bar">Iconography</a> design 303e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainguide. You can also download a set of standard action bar icons (such as for Search or Discard) 304e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainfrom the <a href="{@docRoot}design/downloads/index.html">Downloads</a> page.</p> 3056ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 306e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>You can also use {@code "always"} to declare that an item always appear as an action button. 307e04c4543027df129cd7c004c1b21b01a7f4928adScott MainHowever, you <strong>should not</strong> force an item to appear in the action bar this 308e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainway. Doing so can create layout problems on devices with a narrow screen. It's best to instead 309e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainuse {@code "ifRoom"} to request that an item appear in the action bar, but allow the system to move 310e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainit into the overflow when there's not enough room. However, it might be necessary to use this value 311e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainif the item includes an <a href="#ActionView">action view</a> that cannot be collapsed and 312e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainmust always be visible to provide access to a critical feature.</p> 3136ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 314258a51e3e687d4d469de501f17dd937cdc29019aScott Main 315258a51e3e687d4d469de501f17dd937cdc29019aScott Main 316258a51e3e687d4d469de501f17dd937cdc29019aScott Main 317e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<h3 id="ActionEvents">Handling clicks on action items</h3> 318258a51e3e687d4d469de501f17dd937cdc29019aScott Main 319e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>When the user presses an action, the system calls your activity's {@link 320e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} method. Using the 321e04c4543027df129cd7c004c1b21b01a7f4928adScott Main{@link android.view.MenuItem} passed to this method, you can identify the action by calling {@link 322e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.view.MenuItem#getItemId()}. This returns the unique ID provided by the {@code <item>} 323e04c4543027df129cd7c004c1b21b01a7f4928adScott Maintag's {@code id} attribute so you can perform the appropriate action. For example:</p> 324258a51e3e687d4d469de501f17dd937cdc29019aScott Main 325e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<pre> 326e04c4543027df129cd7c004c1b21b01a7f4928adScott Main@Override 327e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainpublic boolean onOptionsItemSelected(MenuItem item) { 328e04c4543027df129cd7c004c1b21b01a7f4928adScott Main // Handle presses on the action bar items 329e04c4543027df129cd7c004c1b21b01a7f4928adScott Main switch (item.getItemId()) { 330e04c4543027df129cd7c004c1b21b01a7f4928adScott Main case R.id.action_search: 331e04c4543027df129cd7c004c1b21b01a7f4928adScott Main openSearch(); 332e04c4543027df129cd7c004c1b21b01a7f4928adScott Main return true; 333e04c4543027df129cd7c004c1b21b01a7f4928adScott Main case R.id.action_compose: 334e04c4543027df129cd7c004c1b21b01a7f4928adScott Main composeMessage(); 335e04c4543027df129cd7c004c1b21b01a7f4928adScott Main return true; 336e04c4543027df129cd7c004c1b21b01a7f4928adScott Main default: 337e04c4543027df129cd7c004c1b21b01a7f4928adScott Main return super.onOptionsItemSelected(item); 338e04c4543027df129cd7c004c1b21b01a7f4928adScott Main } 339e04c4543027df129cd7c004c1b21b01a7f4928adScott Main} 340e04c4543027df129cd7c004c1b21b01a7f4928adScott Main</pre> 341258a51e3e687d4d469de501f17dd937cdc29019aScott Main 342e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p class="note"><strong>Note:</strong> If you inflate menu items from a fragment, via the {@link 343e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.app.Fragment} class's {@link android.app.Fragment#onCreateOptionsMenu onCreateOptionsMenu()} 344e04c4543027df129cd7c004c1b21b01a7f4928adScott Maincallback, the system calls {@link 345e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.app.Fragment#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} for that 346e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainfragment when the user selects one of those items. However, the activity gets a chance to 347e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainhandle the event first, so the system first calls {@link 348e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} on the activity, 349e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainbefore calling the same callback for the fragment. To ensure that any fragments in the 350e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainactivity also have a chance to handle the callback, always pass the call to the superclass 351e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainas the default behavior instead of returning {@code false} when you do not handle the item.</p> 352e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 353e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 354e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 355e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<div class="figure" style="width:420px;margin-top:0"> 356e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<img src="{@docRoot}images/ui/actionbar-splitaction@2x.png" alt="" width="420"/> 357e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p class="img-caption"><strong>Figure 3.</strong> Mock-ups showing an action bar with 358e04c4543027df129cd7c004c1b21b01a7f4928adScott Maintabs (left), then with split action bar (middle); and with the app icon and title disabled 359e04c4543027df129cd7c004c1b21b01a7f4928adScott Main(right).</p> 360e04c4543027df129cd7c004c1b21b01a7f4928adScott Main</p> 361e04c4543027df129cd7c004c1b21b01a7f4928adScott Main</div> 362258a51e3e687d4d469de501f17dd937cdc29019aScott Main 363258a51e3e687d4d469de501f17dd937cdc29019aScott Main<h3 id="SplitBar">Using split action bar</h3> 364258a51e3e687d4d469de501f17dd937cdc29019aScott Main 365e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>Split action bar provides a separate 366e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainbar at the bottom of the screen to display all action items when the activity is running on 367e04c4543027df129cd7c004c1b21b01a7f4928adScott Maina narrow screen (such as a portrait-oriented handset).</p> 368e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 369e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>Separating the action items this way 370e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainensures that a reasonable amount of space is available to display all your action 371258a51e3e687d4d469de501f17dd937cdc29019aScott Mainitems on a narrow screen, while leaving room for navigation and title elements at the top.</p> 372258a51e3e687d4d469de501f17dd937cdc29019aScott Main 373e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>To enable split action bar when using the support library, you must do two things:</p> 374e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<ol> 37584f2a0f5e7a2ae63f4bc64f494b2aa6c94e7eb5aScott Main <li>Add {@code uiOptions="splitActionBarWhenNarrow"} to each 37684f2a0f5e7a2ae63f4bc64f494b2aa6c94e7eb5aScott Main<a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> 37784f2a0f5e7a2ae63f4bc64f494b2aa6c94e7eb5aScott Mainelement or to the 378258a51e3e687d4d469de501f17dd937cdc29019aScott Main<a href="{@docRoot}guide/topics/manifest/application-element.html">{@code <application>}</a> 37984f2a0f5e7a2ae63f4bc64f494b2aa6c94e7eb5aScott Mainelement. This attribute is understood only by API level 14 and higher (it is ignored 38084f2a0f5e7a2ae63f4bc64f494b2aa6c94e7eb5aScott Mainby older versions).</li> 38184f2a0f5e7a2ae63f4bc64f494b2aa6c94e7eb5aScott Main <li>To support older versions, add a <a 38284f2a0f5e7a2ae63f4bc64f494b2aa6c94e7eb5aScott Main href="{@docRoot}guide/topics/manifest/meta-data-element.html">{@code <meta-data>}</a> 38384f2a0f5e7a2ae63f4bc64f494b2aa6c94e7eb5aScott Main element as a child of each 38484f2a0f5e7a2ae63f4bc64f494b2aa6c94e7eb5aScott Main <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> 38584f2a0f5e7a2ae63f4bc64f494b2aa6c94e7eb5aScott Main element that declares the same value for {@code "android.support.UI_OPTIONS"}.</li> 38684f2a0f5e7a2ae63f4bc64f494b2aa6c94e7eb5aScott Main</ol> 387258a51e3e687d4d469de501f17dd937cdc29019aScott Main 38884f2a0f5e7a2ae63f4bc64f494b2aa6c94e7eb5aScott Main<p>For example:</p> 389258a51e3e687d4d469de501f17dd937cdc29019aScott Main 39084f2a0f5e7a2ae63f4bc64f494b2aa6c94e7eb5aScott Main<pre> 391e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<manifest ...> 39284f2a0f5e7a2ae63f4bc64f494b2aa6c94e7eb5aScott Main <activity uiOptions="splitActionBarWhenNarrow" ... > 39384f2a0f5e7a2ae63f4bc64f494b2aa6c94e7eb5aScott Main <meta-data android:name="android.support.UI_OPTIONS" 39484f2a0f5e7a2ae63f4bc64f494b2aa6c94e7eb5aScott Main android:value="splitActionBarWhenNarrow" /> 39584f2a0f5e7a2ae63f4bc64f494b2aa6c94e7eb5aScott Main </activity> 396943895bee93c411803f2775179b9a4137b0ddf75Scott Main</manifest> 397e04c4543027df129cd7c004c1b21b01a7f4928adScott Main</pre> 398258a51e3e687d4d469de501f17dd937cdc29019aScott Main 399258a51e3e687d4d469de501f17dd937cdc29019aScott Main 400e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>Using split action bar also allows <a href="#Tabs">navigation tabs</a> to collapse into the 401e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainmain action bar if you remove the icon and title (as shown on the right in figure 3). 402e04c4543027df129cd7c004c1b21b01a7f4928adScott MainTo create this effect, disable the action bar 403e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainicon and title with {@link android.support.v7.app.ActionBar#setDisplayShowHomeEnabled 404e04c4543027df129cd7c004c1b21b01a7f4928adScott MainsetDisplayShowHomeEnabled(false)} and {@link 405e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.support.v7.app.ActionBar#setDisplayShowTitleEnabled setDisplayShowTitleEnabled(false)}.</p> 406258a51e3e687d4d469de501f17dd937cdc29019aScott Main 407258a51e3e687d4d469de501f17dd937cdc29019aScott Main 408258a51e3e687d4d469de501f17dd937cdc29019aScott Main 409e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<h2 id="Home">Navigating Up with the App Icon</h2> 410258a51e3e687d4d469de501f17dd937cdc29019aScott Main 411e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<a class="notice-designers" href="{@docRoot}design/patterns/navigation.html"> 412e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <div> 413e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <h3>Design Guide</h3> 414e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <p>Navigation with Back and Up</p> 415e04c4543027df129cd7c004c1b21b01a7f4928adScott Main </div> 416e04c4543027df129cd7c004c1b21b01a7f4928adScott Main</a> 417258a51e3e687d4d469de501f17dd937cdc29019aScott Main 418e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<div class="figure" style="width:240px"> 419e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <img src="{@docRoot}images/ui/actionbar-up.png" width="240" alt="" /> 420e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <p class="img-caption"><strong>Figure 4.</strong> The <em>Up</em> button in Gmail.</p> 421258a51e3e687d4d469de501f17dd937cdc29019aScott Main</div> 422258a51e3e687d4d469de501f17dd937cdc29019aScott Main 423e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>Enabling the app icon as an <em>Up</em> button allows the user to navigate your app based 424e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainon the hierarchical relationships between screens. For instance, if screen A displays a list of 425e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainitems, and selecting an item leads to screen B, then 426e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainscreen B should include the <em>Up</em> button, which returns to screen A.</p> 427258a51e3e687d4d469de501f17dd937cdc29019aScott Main 428e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p class="note"><strong>Note:</strong> Up navigation is distinct from the back navigation provided 429e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainby the system <em>Back</em> button. The <em>Back</em> button is used to navigate in reverse 430e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainchronological order through the history of screens the user has recently worked with. It is 431e04c4543027df129cd7c004c1b21b01a7f4928adScott Maingenerally based on the temporal relationships between screens, rather than the app's hierarchy 432e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainstructure (which is the basis for up navigation).</p> 43318439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 434e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>To enable the app icon as an <em>Up</em> button, call {@link 435e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.support.v7.app.ActionBar#setDisplayHomeAsUpEnabled setDisplayHomeAsUpEnabled()}. 436e04c4543027df129cd7c004c1b21b01a7f4928adScott MainFor example:</p> 43718439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 43818439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main<pre> 43918439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main@Override 440e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainprotected void onCreate(Bundle savedInstanceState) { 441e04c4543027df129cd7c004c1b21b01a7f4928adScott Main super.onCreate(savedInstanceState); 442e04c4543027df129cd7c004c1b21b01a7f4928adScott Main setContentView(R.layout.activity_details); 443e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 444e04c4543027df129cd7c004c1b21b01a7f4928adScott Main ActionBar actionBar = getSupportActionBar(); 445e04c4543027df129cd7c004c1b21b01a7f4928adScott Main actionBar.setDisplayHomeAsUpEnabled(true); 446e04c4543027df129cd7c004c1b21b01a7f4928adScott Main ... 44718439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main} 44818439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main</pre> 44918439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 450e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>Now the icon in the action bar appears with the <em>Up</em> caret (as shown in figure 4). 451e04c4543027df129cd7c004c1b21b01a7f4928adScott MainHowever, it won't do anything by default. To specify the activity to open when the 452e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainuser presses <em>Up</em> button, you have two options:</p> 453258a51e3e687d4d469de501f17dd937cdc29019aScott Main 454e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<ul> 455e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <li><b>Specify the parent activity in the manifest file.</b> 456e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <p>This is the best option when <strong>the parent activity is always the same</strong>. By 457e04c4543027df129cd7c004c1b21b01a7f4928adScott Maindeclaring in the manifest which activity is the parent, the action bar automatically performs the 458e04c4543027df129cd7c004c1b21b01a7f4928adScott Maincorrect action when the user presses the <em>Up</em> button.</p> 459e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 460e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <p>Beginning in Android 4.1 (API level 16), you can declare the parent with the <a href= 461e04c4543027df129cd7c004c1b21b01a7f4928adScott Main"{@docRoot}guide/topics/manifest/activity-element.html#parent">{@code parentActivityName}</a> 462e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainattribute in the <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code 463e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<activity>}</a> element.</p> 464e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <p>To support older devices with the support library, also 465e04c4543027df129cd7c004c1b21b01a7f4928adScott Maininclude a <a href="{@docRoot}guide/topics/manifest/meta-data-element.html">{@code 466e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<meta-data>}</a> element that specifies 467e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainthe parent activity as the value for {@code android.support.PARENT_ACTIVITY}. For example:</p> 468258a51e3e687d4d469de501f17dd937cdc29019aScott Main<pre> 469e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<application ... > 470e04c4543027df129cd7c004c1b21b01a7f4928adScott Main ... 471e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <!-- The main/home activity (has no parent activity) --> 472e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <activity 473e04c4543027df129cd7c004c1b21b01a7f4928adScott Main android:name="com.example.myfirstapp.MainActivity" ...> 474e04c4543027df129cd7c004c1b21b01a7f4928adScott Main ... 475e04c4543027df129cd7c004c1b21b01a7f4928adScott Main </activity> 476e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <!-- A child of the main activity --> 477e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <activity 478e04c4543027df129cd7c004c1b21b01a7f4928adScott Main android:name="com.example.myfirstapp.DisplayMessageActivity" 479e04c4543027df129cd7c004c1b21b01a7f4928adScott Main android:label="@string/title_activity_display_message" 480e04c4543027df129cd7c004c1b21b01a7f4928adScott Main android:parentActivityName="com.example.myfirstapp.MainActivity" > 481e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <!-- Parent activity meta-data to support API level 7+ --> 482e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <meta-data 483e04c4543027df129cd7c004c1b21b01a7f4928adScott Main android:name="android.support.PARENT_ACTIVITY" 484e04c4543027df129cd7c004c1b21b01a7f4928adScott Main android:value="com.example.myfirstapp.MainActivity" /> 485e04c4543027df129cd7c004c1b21b01a7f4928adScott Main </activity> 486e04c4543027df129cd7c004c1b21b01a7f4928adScott Main</application> 487258a51e3e687d4d469de501f17dd937cdc29019aScott Main</pre> 4886ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 489e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <p>Once the parent activity is specified in the manifest like this and you enable the <em>Up</em> 490e04c4543027df129cd7c004c1b21b01a7f4928adScott Main button with {@link 491e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.support.v7.app.ActionBar#setDisplayHomeAsUpEnabled setDisplayHomeAsUpEnabled()}, your work 492e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainis done and the action bar properly navigates up.</p> 493e04c4543027df129cd7c004c1b21b01a7f4928adScott Main </li> 494eb5dacddc443db0752529a69a9c48dab1b129a18Scott Main 49518439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 496e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <li><strong>Or, override {@link 497e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.support.v7.app.ActionBarActivity#getSupportParentActivityIntent()} and {@link 498e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.support.v7.app.ActionBarActivity#onCreateSupportNavigateUpTaskStack 499e04c4543027df129cd7c004c1b21b01a7f4928adScott MainonCreateSupportNavigateUpTaskStack()} in your activity</strong>.</li> 500e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 501e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <p>This is appropriate when <strong>the parent activity may be different</strong> depending 502e04c4543027df129cd7c004c1b21b01a7f4928adScott Main on how the user arrived at the current screen. That is, if there are many paths that the user 503e04c4543027df129cd7c004c1b21b01a7f4928adScott Main could have taken to reach the current screen, the <em>Up</em> button should navigate 504e04c4543027df129cd7c004c1b21b01a7f4928adScott Main backward along the path the user actually followed to get there.</p> 505e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 506e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <p>The system calls {@link 507e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.support.v7.app.ActionBarActivity#getSupportParentActivityIntent()} when the user presses 508e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainthe <em>Up</em> button while navigating your app (within your app's own task). If the activity that 509e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainshould open upon up navigation differs depending on how the user arrived at the current location, 510e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainthen you should override this method to return the {@link 511e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.content.Intent} that starts the appropriate parent activity.</p> 512e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 513e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <p>The system calls {@link 514e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.support.v7.app.ActionBarActivity#onCreateSupportNavigateUpTaskStack 515e04c4543027df129cd7c004c1b21b01a7f4928adScott MainonCreateSupportNavigateUpTaskStack()} for your activity when the user presses the <em>Up</em> 516e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainbutton while your activity is running in a task that does <em>not</em> belong to your app. Thus, 517e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainyou must use the {@link android.support.v4.app.TaskStackBuilder} passed to this method to construct 518e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainthe appropriate back stack that should be synthesized when the user navigates up.</p> 519e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 520e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <p>Even if you override {@link 521e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.support.v7.app.ActionBarActivity#getSupportParentActivityIntent()} to specify up navigation 522e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainas the user navigates your app, you can avoid the need to implement {@link 523e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.support.v7.app.ActionBarActivity#onCreateSupportNavigateUpTaskStack 524e04c4543027df129cd7c004c1b21b01a7f4928adScott MainonCreateSupportNavigateUpTaskStack()} by declaring "default" parent activities in the manifest file 525e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainas shown above. Then the default implementation of {@link 526e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.support.v7.app.ActionBarActivity#onCreateSupportNavigateUpTaskStack 527e04c4543027df129cd7c004c1b21b01a7f4928adScott MainonCreateSupportNavigateUpTaskStack()} will synthesize a back stack based on the parent activities 528e04c4543027df129cd7c004c1b21b01a7f4928adScott Maindeclared in the manifest.</p> 529258a51e3e687d4d469de501f17dd937cdc29019aScott Main 530e04c4543027df129cd7c004c1b21b01a7f4928adScott Main </li> 531e04c4543027df129cd7c004c1b21b01a7f4928adScott Main</ul> 532258a51e3e687d4d469de501f17dd937cdc29019aScott Main 533e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p class="note"><strong>Note:</strong> 534e04c4543027df129cd7c004c1b21b01a7f4928adScott MainIf you've built your app hierarchy using a series of fragments instead of multiple 535e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainactivities, then neither of the above options will work. Instead, to navigate up through your 536e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainfragments, override {@link android.support.v7.app.ActionBarActivity#onSupportNavigateUp()} 537e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainto perform the appropriate fragment transaction—usually by popping 538e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainthe current fragment from the back stack by calling {@link 539e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.support.v4.app.FragmentManager#popBackStack()}.</p> 5406ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 541e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>For more information about implementing <em>Up</em> navigation, read 542e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<a href="{@docRoot}training/implementing-navigation/ancestral.html">Providing Up Navigation</a>.</p> 54318439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 54418439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 54550403a203357ec9e003b198728f89278c88d4f0fScott Main 54650403a203357ec9e003b198728f89278c88d4f0fScott Main<h2 id="ActionView">Adding an Action View</h2> 54750403a203357ec9e003b198728f89278c88d4f0fScott Main 548e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<div class="figure" style="width:340px"> 549e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<img src="/images/ui/actionbar-searchview@2x.png" alt="" width="340" /> 550e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p class="img-caption"><strong>Figure 5.</strong> An action bar with a collapsible 551e04c4543027df129cd7c004c1b21b01a7f4928adScott Main{@link android.support.v7.widget.SearchView}.</p> 55250403a203357ec9e003b198728f89278c88d4f0fScott Main</div> 55350403a203357ec9e003b198728f89278c88d4f0fScott Main 5546ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 555e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>An <em>action view</em> is a widget that appears in the action bar as a substitute for an action 556e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainbutton. An action view provides fast access to rich actions without changing activities or 557e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainfragments, and without replacing the action bar. For example, if you have an action for Search, you 558e04c4543027df129cd7c004c1b21b01a7f4928adScott Maincan add an action view to 559e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainembeds a {@link android.support.v7.widget.SearchView} widget in the action bar, as shown in figure 560e04c4543027df129cd7c004c1b21b01a7f4928adScott Main5.</p> 56150403a203357ec9e003b198728f89278c88d4f0fScott Main 562e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>To declare an action view, use either the {@code 563e04c4543027df129cd7c004c1b21b01a7f4928adScott MainactionLayout} or {@code actionViewClass} attribute to specify either a layout 564e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainresource or widget class to use, respectively. For example, here's how to add 565e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainthe {@link android.support.v7.widget.SearchView} widget:</p> 56650403a203357ec9e003b198728f89278c88d4f0fScott Main 56750403a203357ec9e003b198728f89278c88d4f0fScott Main<pre> 5686ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main<?xml version="1.0" encoding="utf-8"?> 569e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<menu xmlns:android="http://schemas.android.com/apk/res/android" 57084f2a0f5e7a2ae63f4bc64f494b2aa6c94e7eb5aScott Main xmlns:yourapp="http://schemas.android.com/apk/res-auto" > 571e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <item android:id="@+id/action_search" 572e04c4543027df129cd7c004c1b21b01a7f4928adScott Main android:title="@string/action_search" 573e04c4543027df129cd7c004c1b21b01a7f4928adScott Main android:icon="@drawable/ic_action_search" 57484f2a0f5e7a2ae63f4bc64f494b2aa6c94e7eb5aScott Main yourapp:showAsAction="ifRoom|collapseActionView" 57584f2a0f5e7a2ae63f4bc64f494b2aa6c94e7eb5aScott Main <b>yourapp:actionViewClass="android.support.v7.widget.SearchView"</b> /> 5766ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main</menu> 5776ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main</pre> 5786ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 579e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>Notice that the {@code showAsAction} attribute also includes the {@code "collapseActionView"} 580e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainvalue. This is optional and declares that the action view should be collapsed into a 581e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainbutton. (This behavior is explained further in the following section about 582e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<a href="#ActionViewCollapsing">Handling collapsible action views</a>.)</p> 583e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 584e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>If you need to configure the action view (such as to add event listeners), you can do so during 585e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainthe {@link android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} callback. You can 586e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainacquire the action view object by calling the static method {@link 587e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.support.v4.view.MenuItemCompat#getActionView MenuItemCompat.getActionView()} and passing it 588e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainthe corresponding {@link android.view.MenuItem}. For example, the search widget from the above 589e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainsample is acquired like this:</p> 590258a51e3e687d4d469de501f17dd937cdc29019aScott Main 591258a51e3e687d4d469de501f17dd937cdc29019aScott Main 592258a51e3e687d4d469de501f17dd937cdc29019aScott Main<pre> 593258a51e3e687d4d469de501f17dd937cdc29019aScott Main@Override 594258a51e3e687d4d469de501f17dd937cdc29019aScott Mainpublic boolean onCreateOptionsMenu(Menu menu) { 595e04c4543027df129cd7c004c1b21b01a7f4928adScott Main getMenuInflater().inflate(R.menu.main_activity_actions, menu); 596e04c4543027df129cd7c004c1b21b01a7f4928adScott Main MenuItem searchItem = menu.findItem(R.id.action_search); 597e04c4543027df129cd7c004c1b21b01a7f4928adScott Main SearchView searchView = (SearchView) MenuItemCompat.getActionView(searchItem); 598258a51e3e687d4d469de501f17dd937cdc29019aScott Main // Configure the search info and add any event listeners 599258a51e3e687d4d469de501f17dd937cdc29019aScott Main ... 600258a51e3e687d4d469de501f17dd937cdc29019aScott Main return super.onCreateOptionsMenu(menu); 601258a51e3e687d4d469de501f17dd937cdc29019aScott Main} 602258a51e3e687d4d469de501f17dd937cdc29019aScott Main</pre> 603258a51e3e687d4d469de501f17dd937cdc29019aScott Main 604e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<div class="note"> 605e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p><b>On API level 11 or higher</b></p> 606e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>Get the action view by calling {@link android.view.MenuItem#getActionView} on the 607e04c4543027df129cd7c004c1b21b01a7f4928adScott Maincorresponding {@link android.view.MenuItem}:</p> 608e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<pre>menu.findItem(R.id.action_search).getActionView()</pre> 609e04c4543027df129cd7c004c1b21b01a7f4928adScott Main</div> 610e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 611258a51e3e687d4d469de501f17dd937cdc29019aScott Main<p>For more information about using the search widget, see <a 612258a51e3e687d4d469de501f17dd937cdc29019aScott Mainhref="{@docRoot}guide/topics/search/search-dialog.html">Creating a Search Interface</a>.</p> 613258a51e3e687d4d469de501f17dd937cdc29019aScott Main 614258a51e3e687d4d469de501f17dd937cdc29019aScott Main 615258a51e3e687d4d469de501f17dd937cdc29019aScott Main 616e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<h3 id="ActionViewCollapsing">Handling collapsible action views</h3> 617258a51e3e687d4d469de501f17dd937cdc29019aScott Main 618e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>To preserve the action bar space, you can collapse your action view into an action button. 619e04c4543027df129cd7c004c1b21b01a7f4928adScott MainWhen collapsed, the system might place the action 620e04c4543027df129cd7c004c1b21b01a7f4928adScott Maininto the action overflow, but the 621e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainaction view still appears in the action bar when the user selects it. You can make your action 622e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainview collapsible by adding {@code "collapseActionView"} to the {@code showAsAction} 623258a51e3e687d4d469de501f17dd937cdc29019aScott Mainattribute, as shown in the XML above.</p> 624258a51e3e687d4d469de501f17dd937cdc29019aScott Main 625e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>Because the system expands the action view when the user selects the action, you 626258a51e3e687d4d469de501f17dd937cdc29019aScott Main<em>do not</em> need to respond to the item in the {@link 627e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.app.Activity#onOptionsItemSelected onOptionsItemSelected()} callback. The system still calls 628e04c4543027df129cd7c004c1b21b01a7f4928adScott Main{@link android.app.Activity#onOptionsItemSelected onOptionsItemSelected()}, but if 629e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainyou return {@code true} (indicating you've handled the event instead), then the 630e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainaction view will <em>not</em> expand.</p> 631e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 632e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>The system also collapses your action view when the user presses the <em>Up</em> button 633e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainor <em>Back</em> button.</p> 634258a51e3e687d4d469de501f17dd937cdc29019aScott Main 635258a51e3e687d4d469de501f17dd937cdc29019aScott Main<p>If you need to update your activity based on the visibility of your action view, you can receive 636e04c4543027df129cd7c004c1b21b01a7f4928adScott Maincallbacks when the action is expanded and collapsed by defining an {@link 637e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.support.v4.view.MenuItemCompat.OnActionExpandListener OnActionExpandListener} and 638e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainpassing it to {@link android.support.v4.view.MenuItemCompat#setOnActionExpandListener 639e04c4543027df129cd7c004c1b21b01a7f4928adScott MainsetOnActionExpandListener()}. For example:</p> 640e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 641258a51e3e687d4d469de501f17dd937cdc29019aScott Main 642258a51e3e687d4d469de501f17dd937cdc29019aScott Main<pre> 643258a51e3e687d4d469de501f17dd937cdc29019aScott Main@Override 644258a51e3e687d4d469de501f17dd937cdc29019aScott Mainpublic boolean onCreateOptionsMenu(Menu menu) { 645258a51e3e687d4d469de501f17dd937cdc29019aScott Main getMenuInflater().inflate(R.menu.options, menu); 646258a51e3e687d4d469de501f17dd937cdc29019aScott Main MenuItem menuItem = menu.findItem(R.id.actionItem); 647258a51e3e687d4d469de501f17dd937cdc29019aScott Main ... 648258a51e3e687d4d469de501f17dd937cdc29019aScott Main 649e04c4543027df129cd7c004c1b21b01a7f4928adScott Main // When using the support library, the setOnActionExpandListener() method is 650e04c4543027df129cd7c004c1b21b01a7f4928adScott Main // static and accepts the MenuItem object as an argument 651e04c4543027df129cd7c004c1b21b01a7f4928adScott Main MenuItemCompat.setOnActionExpandListener(menuItem, new OnActionExpandListener() { 652258a51e3e687d4d469de501f17dd937cdc29019aScott Main @Override 653258a51e3e687d4d469de501f17dd937cdc29019aScott Main public boolean onMenuItemActionCollapse(MenuItem item) { 654258a51e3e687d4d469de501f17dd937cdc29019aScott Main // Do something when collapsed 655258a51e3e687d4d469de501f17dd937cdc29019aScott Main return true; // Return true to collapse action view 656258a51e3e687d4d469de501f17dd937cdc29019aScott Main } 657258a51e3e687d4d469de501f17dd937cdc29019aScott Main 658258a51e3e687d4d469de501f17dd937cdc29019aScott Main @Override 659258a51e3e687d4d469de501f17dd937cdc29019aScott Main public boolean onMenuItemActionExpand(MenuItem item) { 660258a51e3e687d4d469de501f17dd937cdc29019aScott Main // Do something when expanded 661258a51e3e687d4d469de501f17dd937cdc29019aScott Main return true; // Return true to expand action view 662258a51e3e687d4d469de501f17dd937cdc29019aScott Main } 663258a51e3e687d4d469de501f17dd937cdc29019aScott Main }); 664258a51e3e687d4d469de501f17dd937cdc29019aScott Main} 665258a51e3e687d4d469de501f17dd937cdc29019aScott Main</pre> 666258a51e3e687d4d469de501f17dd937cdc29019aScott Main 667258a51e3e687d4d469de501f17dd937cdc29019aScott Main 668258a51e3e687d4d469de501f17dd937cdc29019aScott Main 669258a51e3e687d4d469de501f17dd937cdc29019aScott Main 670258a51e3e687d4d469de501f17dd937cdc29019aScott Main<h2 id="ActionProvider">Adding an Action Provider</h2> 671258a51e3e687d4d469de501f17dd937cdc29019aScott Main 672e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<div class="figure" style="width:240px"> 673e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <img src="{@docRoot}images/ui/actionbar-shareaction@2x.png" alt="" width="240" /> 674e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <p class="img-caption"><strong>Figure 6.</strong> An action bar with 675e04c4543027df129cd7c004c1b21b01a7f4928adScott Main {@link android.widget.ShareActionProvider} expanded to show share targets.</p> 676258a51e3e687d4d469de501f17dd937cdc29019aScott Main</div> 677258a51e3e687d4d469de501f17dd937cdc29019aScott Main 678e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>Similar to an <a href="#ActionView">action view</a>, an <em>action provider</em> 679e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainreplaces an action button with a customized layout. However, 680e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainunlike an action view, an action provider takes control of all the action's behaviors 681e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainand an action provider can display a submenu when pressed.</p> 682258a51e3e687d4d469de501f17dd937cdc29019aScott Main 683e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>To declare an action provider, supply the {@code actionViewClass} attribute in the 684e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainmenu {@code <item>} tag with a fully-qualified class name for an 685e04c4543027df129cd7c004c1b21b01a7f4928adScott Main{@link android.support.v4.view.ActionProvider}.</p> 686258a51e3e687d4d469de501f17dd937cdc29019aScott Main 687e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>You can build your own action provider by extending the {@link 688e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.support.v4.view.ActionProvider} class, but Android provides some pre-built action providers 689e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainsuch as {@link android.support.v7.widget.ShareActionProvider}, which facilitates a "share" action 690e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainby showing a list of possible apps for sharing directly in the action bar (as shown in figure 691e04c4543027df129cd7c004c1b21b01a7f4928adScott Main6).</p> 692258a51e3e687d4d469de501f17dd937cdc29019aScott Main 693e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>Because each {@link android.support.v4.view.ActionProvider} class defines its own action 694e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainbehaviors, you don't need to listen for the action in the {@link 695e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.app.Activity#onOptionsItemSelected onOptionsItemSelected()} method. If necessary though, 696e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainyou can still listen for the click event in the {@link android.app.Activity#onOptionsItemSelected 697e04c4543027df129cd7c004c1b21b01a7f4928adScott MainonOptionsItemSelected()} method in case you need to simultaneously perform another action. But be 698e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainsure to return {@code false} so that the the action provider still receives the {@link 699e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.support.v4.view.ActionProvider#onPerformDefaultAction()} callback to perform its intended 700e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainaction.</p> 701e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 702e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 703e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>However, if the action provider provides a submenu of actions, then your 704e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainactivity does not receive a call to {@link android.app.Activity#onOptionsItemSelected 705e04c4543027df129cd7c004c1b21b01a7f4928adScott MainonOptionsItemSelected()} when the user opens the list or selects one of the submenu items.</p> 706258a51e3e687d4d469de501f17dd937cdc29019aScott Main 707258a51e3e687d4d469de501f17dd937cdc29019aScott Main 708258a51e3e687d4d469de501f17dd937cdc29019aScott Main 709258a51e3e687d4d469de501f17dd937cdc29019aScott Main<h3 id="ShareActionProvider">Using the ShareActionProvider</h3> 710258a51e3e687d4d469de501f17dd937cdc29019aScott Main 711e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>To add a "share" action with {@link android.support.v7.widget.ShareActionProvider}, 712e04c4543027df129cd7c004c1b21b01a7f4928adScott Maindefine the {@code actionProviderClass} for an {@code <item>} tag with 713e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainthe {@link android.support.v7.widget.ShareActionProvider} class. For example:</p> 714258a51e3e687d4d469de501f17dd937cdc29019aScott Main 715e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<pre> 716e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<?xml version="1.0" encoding="utf-8"?> 717e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<menu xmlns:android="http://schemas.android.com/apk/res/android" 71884f2a0f5e7a2ae63f4bc64f494b2aa6c94e7eb5aScott Main xmlns:yourapp="http://schemas.android.com/apk/res-auto" > 719e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <item android:id="@+id/action_share" 720e04c4543027df129cd7c004c1b21b01a7f4928adScott Main android:title="@string/share" 72184f2a0f5e7a2ae63f4bc64f494b2aa6c94e7eb5aScott Main yourapp:showAsAction="ifRoom" 72284f2a0f5e7a2ae63f4bc64f494b2aa6c94e7eb5aScott Main <strong>yourapp:actionProviderClass="android.support.v7.widget.ShareActionProvider"</strong> 723e04c4543027df129cd7c004c1b21b01a7f4928adScott Main /> 724e04c4543027df129cd7c004c1b21b01a7f4928adScott Main ... 725e04c4543027df129cd7c004c1b21b01a7f4928adScott Main</menu> 726e04c4543027df129cd7c004c1b21b01a7f4928adScott Main</pre> 727258a51e3e687d4d469de501f17dd937cdc29019aScott Main 728e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>Now the action provider takes control of the action item and handles both 729e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainits appearance and behavior. But you must 730e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainstill provide a title for the item to be used when it appears in the action overflow.</p> 731e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 732e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>The only thing left to do is define 733e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainthe {@link android.content.Intent} you want to use for sharing. To do so, edit 734e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainyour {@link 735e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} method to call {@link 736e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.support.v4.view.MenuItemCompat#getActionProvider MenuItemCompat.getActionProvider()} 737e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainand pass it the {@link android.view.MenuItem} holding the action provider. Then call {@link 738e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.support.v7.widget.ShareActionProvider#setShareIntent setShareIntent()} on the 739e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainreturned {@link android.support.v7.widget.ShareActionProvider} and pass it an 740e04c4543027df129cd7c004c1b21b01a7f4928adScott Main{@link android.content.Intent#ACTION_SEND} intent with the appropriate content attached.</p> 741e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 742e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>You should call {@link 743e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.support.v7.widget.ShareActionProvider#setShareIntent setShareIntent()} once during {@link 744e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} to initialize the share action, 745e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainbut because the user context might change, you must update the intent any time the shareable 746e04c4543027df129cd7c004c1b21b01a7f4928adScott Maincontent changes by again calling {@link 747e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.support.v7.widget.ShareActionProvider#setShareIntent setShareIntent()}.</p> 748e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 749e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>For example:</p> 75050403a203357ec9e003b198728f89278c88d4f0fScott Main 751258a51e3e687d4d469de501f17dd937cdc29019aScott Main<pre> 752258a51e3e687d4d469de501f17dd937cdc29019aScott Mainprivate ShareActionProvider mShareActionProvider; 7536ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 754258a51e3e687d4d469de501f17dd937cdc29019aScott Main@Override 755258a51e3e687d4d469de501f17dd937cdc29019aScott Mainpublic boolean onCreateOptionsMenu(Menu menu) { 756e04c4543027df129cd7c004c1b21b01a7f4928adScott Main getMenuInflater().inflate(R.menu.main_activity_actions, menu); 757258a51e3e687d4d469de501f17dd937cdc29019aScott Main 758e04c4543027df129cd7c004c1b21b01a7f4928adScott Main // Set up ShareActionProvider's default share intent 759e04c4543027df129cd7c004c1b21b01a7f4928adScott Main MenuItem shareItem = menu.findItem(R.id.action_share); 760e04c4543027df129cd7c004c1b21b01a7f4928adScott Main mShareActionProvider = (ShareActionProvider) 761e04c4543027df129cd7c004c1b21b01a7f4928adScott Main MenuItemCompat.getActionProvider(shareItem); 762e04c4543027df129cd7c004c1b21b01a7f4928adScott Main mShareActionProvider.setShareIntent(getDefaultIntent()); 763258a51e3e687d4d469de501f17dd937cdc29019aScott Main 764e04c4543027df129cd7c004c1b21b01a7f4928adScott Main return super.onCreateOptionsMenu(menu); 765e04c4543027df129cd7c004c1b21b01a7f4928adScott Main} 766258a51e3e687d4d469de501f17dd937cdc29019aScott Main 767e04c4543027df129cd7c004c1b21b01a7f4928adScott Main/** Defines a default (dummy) share intent to initialize the action provider. 768e04c4543027df129cd7c004c1b21b01a7f4928adScott Main * However, as soon as the actual content to be used in the intent 769e04c4543027df129cd7c004c1b21b01a7f4928adScott Main * is known or changes, you must update the share intent by again calling 7702edf372ed2a7f6e640591dbb76b429eecd5e31d0Scott Main * mShareActionProvider.{@link android.support.v7.widget.ShareActionProvider#setShareIntent setShareIntent()} 771e04c4543027df129cd7c004c1b21b01a7f4928adScott Main */ 772e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainprivate Intent getDefaultIntent() { 773e04c4543027df129cd7c004c1b21b01a7f4928adScott Main Intent intent = new Intent(Intent.ACTION_SEND); 774e04c4543027df129cd7c004c1b21b01a7f4928adScott Main intent.setType("image/*"); 775e04c4543027df129cd7c004c1b21b01a7f4928adScott Main return intent; 776258a51e3e687d4d469de501f17dd937cdc29019aScott Main} 777258a51e3e687d4d469de501f17dd937cdc29019aScott Main</pre> 778258a51e3e687d4d469de501f17dd937cdc29019aScott Main 779e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>The {@link android.support.v7.widget.ShareActionProvider} now handles all user interaction with 780e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainthe item and you <em>do not</em> need to handle click events from the {@link 781abdf0d533c292709e51cee2c1213d5e44baca963Scott Mainandroid.app.Activity#onOptionsItemSelected onOptionsItemSelected()} callback method.</p> 78250403a203357ec9e003b198728f89278c88d4f0fScott Main 783e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 784e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>By default, the {@link android.support.v7.widget.ShareActionProvider} retains a ranking for each 785e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainshare target based on how often the user selects each one. The share targets used more frequently 786e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainappear at the top of the drop-down list and the target used most often appears directly in the 787e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainaction bar as the default share target. By default, the ranking information is saved in a private 788e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainfile with a name specified by {@link 789e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.support.v7.widget.ShareActionProvider#DEFAULT_SHARE_HISTORY_FILE_NAME}. If you use the 790e04c4543027df129cd7c004c1b21b01a7f4928adScott Main{@link android.support.v7.widget.ShareActionProvider} or an extension of it for only one type of 791e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainaction, then you should continue to use this default history file and there's nothing you need to 792e04c4543027df129cd7c004c1b21b01a7f4928adScott Maindo. However, if you use {@link android.support.v7.widget.ShareActionProvider} or an extension of it 793e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainfor multiple actions with semantically different meanings, then each {@link 794e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.support.v7.widget.ShareActionProvider} should specify its own history file in order to 795e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainmaintain its own history. To specify a different history file for the {@link 796e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.support.v7.widget.ShareActionProvider}, call {@link 797e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.support.v7.widget.ShareActionProvider#setShareHistoryFileName setShareHistoryFileName()} 798e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainand provide an XML file name (for example, {@code "custom_share_history.xml"}).</p> 799e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 800e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 801e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p class="note"><strong>Note:</strong> Although the {@link 802e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.support.v7.widget.ShareActionProvider} ranks share targets based on frequency of use, the 803e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainbehavior is extensible and extensions of {@link android.support.v7.widget.ShareActionProvider} can 804e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainperform different behaviors and ranking based on the history file (if appropriate).</p> 805e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 806258a51e3e687d4d469de501f17dd937cdc29019aScott Main 807258a51e3e687d4d469de501f17dd937cdc29019aScott Main 808258a51e3e687d4d469de501f17dd937cdc29019aScott Main 809258a51e3e687d4d469de501f17dd937cdc29019aScott Main<h3 id="CreatingActionProvider">Creating a custom action provider</h3> 810258a51e3e687d4d469de501f17dd937cdc29019aScott Main 811e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>Creating your own action provider allows you to re-use and manage dynamic action item 812e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainbehaviors in a self-contained module, rather than handle action item transformations and 813e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainbehaviors in your fragment or activity 814e04c4543027df129cd7c004c1b21b01a7f4928adScott Maincode. As shown in the previous section, Android already provides an implementation of {@link 815e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.support.v4.view.ActionProvider} for share actions: the {@link 816e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.support.v7.widget.ShareActionProvider}.</p> 81750403a203357ec9e003b198728f89278c88d4f0fScott Main 818e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>To create your own action provider for a different action, simply extend the 819e04c4543027df129cd7c004c1b21b01a7f4928adScott Main{@link android.support.v4.view.ActionProvider} class and implement 820258a51e3e687d4d469de501f17dd937cdc29019aScott Mainits callback methods as appropriate. Most importantly, you should implement the following:</p> 821258a51e3e687d4d469de501f17dd937cdc29019aScott Main 822258a51e3e687d4d469de501f17dd937cdc29019aScott Main<dl> 823e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <dt>{@link android.support.v4.view.ActionProvider#ActionProvider ActionProvider()}</dt> 824258a51e3e687d4d469de501f17dd937cdc29019aScott Main <dd>This constructor passes you the application {@link android.content.Context}, which you 825258a51e3e687d4d469de501f17dd937cdc29019aScott Mainshould save in a member field to use in the other callback methods.</dd> 826258a51e3e687d4d469de501f17dd937cdc29019aScott Main 827e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <dt>{@link android.support.v4.view.ActionProvider#onCreateActionView(MenuItem)}</dt> 828258a51e3e687d4d469de501f17dd937cdc29019aScott Main <dd>This is where you define the action view for the item. Use the {@link 829258a51e3e687d4d469de501f17dd937cdc29019aScott Mainandroid.content.Context} acquired from the constructor to instantiate a {@link 830258a51e3e687d4d469de501f17dd937cdc29019aScott Mainandroid.view.LayoutInflater} and inflate your action view layout from an XML resource, then hook 831258a51e3e687d4d469de501f17dd937cdc29019aScott Mainup event listeners. For example: 83250403a203357ec9e003b198728f89278c88d4f0fScott Main<pre> 833e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainpublic View onCreateActionView(MenuItem forItem) { 834258a51e3e687d4d469de501f17dd937cdc29019aScott Main // Inflate the action view to be shown on the action bar. 835258a51e3e687d4d469de501f17dd937cdc29019aScott Main LayoutInflater layoutInflater = LayoutInflater.from(mContext); 836258a51e3e687d4d469de501f17dd937cdc29019aScott Main View view = layoutInflater.inflate(R.layout.action_provider, null); 837258a51e3e687d4d469de501f17dd937cdc29019aScott Main ImageButton button = (ImageButton) view.findViewById(R.id.button); 838258a51e3e687d4d469de501f17dd937cdc29019aScott Main button.setOnClickListener(new View.OnClickListener() { 839258a51e3e687d4d469de501f17dd937cdc29019aScott Main @Override 840258a51e3e687d4d469de501f17dd937cdc29019aScott Main public void onClick(View v) { 841258a51e3e687d4d469de501f17dd937cdc29019aScott Main // Do something... 842258a51e3e687d4d469de501f17dd937cdc29019aScott Main } 843258a51e3e687d4d469de501f17dd937cdc29019aScott Main }); 844258a51e3e687d4d469de501f17dd937cdc29019aScott Main return view; 84550403a203357ec9e003b198728f89278c88d4f0fScott Main} 84650403a203357ec9e003b198728f89278c88d4f0fScott Main</pre> 847258a51e3e687d4d469de501f17dd937cdc29019aScott Main</dd> 848258a51e3e687d4d469de501f17dd937cdc29019aScott Main 849e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <dt>{@link android.support.v4.view.ActionProvider#onPerformDefaultAction()}</dt> 850e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <dd>The system calls this when the menu item is selected from the action overflow and the 851258a51e3e687d4d469de501f17dd937cdc29019aScott Mainaction provider should perform a default action for the menu item. 852258a51e3e687d4d469de501f17dd937cdc29019aScott Main <p>However, if your action provider provides a submenu, through the {@link 853e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.support.v4.view.ActionProvider#onPrepareSubMenu onPrepareSubMenu()} callback, then the 854e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainsubmenu appears even when the action provider is placed in the action overflow. Thus, {@link 855e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.support.v4.view.ActionProvider#onPerformDefaultAction()} is never called when there is a 856258a51e3e687d4d469de501f17dd937cdc29019aScott Mainsubmenu.</p> 857e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 858258a51e3e687d4d469de501f17dd937cdc29019aScott Main <p class="note"><strong>Note:</strong> An activity or a fragment that implements {@link 859258a51e3e687d4d469de501f17dd937cdc29019aScott Mainandroid.app.Activity#onOptionsItemSelected onOptionsItemSelected()} can override the action 860e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainprovider's default behavior (unless it uses a submenu) by handling the item-selected event (and 861e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainreturning <code>true</code>), in which case, the system does not call {@link 862e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.support.v4.view.ActionProvider#onPerformDefaultAction()}.</p> 863e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 864258a51e3e687d4d469de501f17dd937cdc29019aScott Main</dd> 865258a51e3e687d4d469de501f17dd937cdc29019aScott Main</dl> 86650403a203357ec9e003b198728f89278c88d4f0fScott Main 867258a51e3e687d4d469de501f17dd937cdc29019aScott Main<p>For an example extension of {@link android.view.ActionProvider}, see <a 868258a51e3e687d4d469de501f17dd937cdc29019aScott Mainhref="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/ActionBarSettingsActionProviderActivity.html" 869258a51e3e687d4d469de501f17dd937cdc29019aScott Main>ActionBarSettingsActionProviderActivity</a>.</p> 87050403a203357ec9e003b198728f89278c88d4f0fScott Main 87150403a203357ec9e003b198728f89278c88d4f0fScott Main 87250403a203357ec9e003b198728f89278c88d4f0fScott Main 8736ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 874258a51e3e687d4d469de501f17dd937cdc29019aScott Main<h2 id="Tabs">Adding Navigation Tabs</h2> 87518439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 876e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<img src="{@docRoot}images/ui/actionbar-tabs@2x.png" width="760" alt="" /> 877e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p class="img-caption"><strong>Figure 7.</strong> Action bar tabs on a wide screen.</p> 87818439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 879e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<a class="notice-designers" href="{@docRoot}design/building-blocks/tabs.html"> 880e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <div> 881e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <h3>Design Guide</h3> 882e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <p>Tabs</p> 883e04c4543027df129cd7c004c1b21b01a7f4928adScott Main </div> 884e04c4543027df129cd7c004c1b21b01a7f4928adScott Main</a> 885e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 886e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<a class="notice-developers" href="{@docRoot}training/implementing-navigation/lateral.html"> 887e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <div> 888e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <h3>Also read</h3> 889e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <p>Creating Swipe Views with Tabs</p> 890e04c4543027df129cd7c004c1b21b01a7f4928adScott Main </div> 891e04c4543027df129cd7c004c1b21b01a7f4928adScott Main</a> 8926ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 893e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 894e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<div class="figure" style="width:240px"> 895e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <img src="{@docRoot}images/ui/actionbar-tabs-stacked@2x.png" width="240" alt="" /> 896e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <p class="img-caption"><strong>Figure 8.</strong> Tabs on a narrow screen.</p> 897258a51e3e687d4d469de501f17dd937cdc29019aScott Main</div> 898258a51e3e687d4d469de501f17dd937cdc29019aScott Main 899e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>Tabs in the action bar make it easy for users to explore and switch between different views in 900e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainyour app. The tabs provided by the {@link android.support.v7.app.ActionBar} are ideal because they 901e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainadapt to different screen sizes. For example, when the screen is wide enough the tabs appear in the 902e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainaction bar alongside the action buttons (such as when on a tablet, shown in figure 7), while when 903e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainon a narrow screen they appear in a separate bar (known as the "stacked action bar", shown in 904e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainfigure 8). In some cases, the Android system will instead show your tab items as a drop-down list 905e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainto ensure the best fit in the action bar.</p> 906e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 907e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>To get started, your layout must include a {@link android.view.ViewGroup} in which you place 908e04c4543027df129cd7c004c1b21b01a7f4928adScott Maineach {@link android.app.Fragment} associated with a tab. Be sure the {@link android.view.ViewGroup} 909e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainhas a resource ID so you can reference it from your code and swap the tabs within it. 910e04c4543027df129cd7c004c1b21b01a7f4928adScott MainAlternatively, if the tab content will fill the activity layout, then your activity doesn't need a 911e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainlayout at all (you don't even need to call {@link android.app.Activity#setContentView 912e04c4543027df129cd7c004c1b21b01a7f4928adScott MainsetContentView()}). Instead, you can place each fragment in the default root view, which you can 913e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainrefer to with the {@code android.R.id.content} ID.</p> 914e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 915258a51e3e687d4d469de501f17dd937cdc29019aScott Main 916258a51e3e687d4d469de501f17dd937cdc29019aScott Main<p>Once you determine where the fragments appear in the layout, the basic procedure to add tabs 917258a51e3e687d4d469de501f17dd937cdc29019aScott Mainis:</p> 91818439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main<ol> 919e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <li>Implement the {@link android.support.v7.app.ActionBar.TabListener} interface. This interface 920e04c4543027df129cd7c004c1b21b01a7f4928adScott Main provides callbacks for tab events, such as when the user presses one so you can swap the 921e04c4543027df129cd7c004c1b21b01a7f4928adScott Main tabs.</li> 922e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <li>For each tab you want to add, instantiate an {@link android.support.v7.app.ActionBar.Tab} 923e04c4543027df129cd7c004c1b21b01a7f4928adScott Main and set the {@link android.support.v7.app.ActionBar.TabListener} by calling {@link 924e04c4543027df129cd7c004c1b21b01a7f4928adScott Main android.support.v7.app.ActionBar.Tab#setTabListener setTabListener()}. Also set the tab's title 925e04c4543027df129cd7c004c1b21b01a7f4928adScott Main and with {@link android.app.ActionBar.Tab#setText setText()} (and optionally, an icon with 926e04c4543027df129cd7c004c1b21b01a7f4928adScott Main {@link android.app.ActionBar.Tab#setIcon setIcon()}).</li> 927e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <li>Then add each tab to the action bar by calling {@link android.support.v7.app.ActionBar#addTab 928e04c4543027df129cd7c004c1b21b01a7f4928adScott Main addTab()}.</li> 929258a51e3e687d4d469de501f17dd937cdc29019aScott Main</ol> 93018439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 931e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>Notice that the {@link android.support.v7.app.ActionBar.TabListener} 932e04c4543027df129cd7c004c1b21b01a7f4928adScott Maincallback methods don't specify which fragment is associated with the tab, but merely which 933e04c4543027df129cd7c004c1b21b01a7f4928adScott Main{@link android.support.v7.app.ActionBar.Tab} was selected. 934e04c4543027df129cd7c004c1b21b01a7f4928adScott MainYou must define your own association 935258a51e3e687d4d469de501f17dd937cdc29019aScott Mainbetween each {@link android.app.ActionBar.Tab} and the appropriate {@link android.app.Fragment} that 936e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainit represents. There are several ways you 937e04c4543027df129cd7c004c1b21b01a7f4928adScott Maincan define the association, depending on your design.</p> 938258a51e3e687d4d469de501f17dd937cdc29019aScott Main 939258a51e3e687d4d469de501f17dd937cdc29019aScott Main<p>For example, here's how you might implement the {@link android.app.ActionBar.TabListener} 940258a51e3e687d4d469de501f17dd937cdc29019aScott Mainsuch that each tab uses its own instance of the listener:</p> 941258a51e3e687d4d469de501f17dd937cdc29019aScott Main<pre> 942258a51e3e687d4d469de501f17dd937cdc29019aScott Mainpublic static class TabListener<T extends Fragment> implements ActionBar.TabListener { 943258a51e3e687d4d469de501f17dd937cdc29019aScott Main private Fragment mFragment; 944258a51e3e687d4d469de501f17dd937cdc29019aScott Main private final Activity mActivity; 945258a51e3e687d4d469de501f17dd937cdc29019aScott Main private final String mTag; 946258a51e3e687d4d469de501f17dd937cdc29019aScott Main private final Class<T> mClass; 947258a51e3e687d4d469de501f17dd937cdc29019aScott Main 948258a51e3e687d4d469de501f17dd937cdc29019aScott Main /** Constructor used each time a new tab is created. 949258a51e3e687d4d469de501f17dd937cdc29019aScott Main * @param activity The host Activity, used to instantiate the fragment 950258a51e3e687d4d469de501f17dd937cdc29019aScott Main * @param tag The identifier tag for the fragment 951258a51e3e687d4d469de501f17dd937cdc29019aScott Main * @param clz The fragment's Class, used to instantiate the fragment 952258a51e3e687d4d469de501f17dd937cdc29019aScott Main */ 953258a51e3e687d4d469de501f17dd937cdc29019aScott Main public TabListener(Activity activity, String tag, Class<T> clz) { 954258a51e3e687d4d469de501f17dd937cdc29019aScott Main mActivity = activity; 955258a51e3e687d4d469de501f17dd937cdc29019aScott Main mTag = tag; 956258a51e3e687d4d469de501f17dd937cdc29019aScott Main mClass = clz; 95718439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main } 95818439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 959258a51e3e687d4d469de501f17dd937cdc29019aScott Main /* The following are each of the {@link android.app.ActionBar.TabListener} callbacks */ 960258a51e3e687d4d469de501f17dd937cdc29019aScott Main 96118439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main public void onTabSelected(Tab tab, FragmentTransaction ft) { 962258a51e3e687d4d469de501f17dd937cdc29019aScott Main // Check if the fragment is already initialized 963258a51e3e687d4d469de501f17dd937cdc29019aScott Main if (mFragment == null) { 964258a51e3e687d4d469de501f17dd937cdc29019aScott Main // If not, instantiate and add it to the activity 965258a51e3e687d4d469de501f17dd937cdc29019aScott Main mFragment = Fragment.instantiate(mActivity, mClass.getName()); 966258a51e3e687d4d469de501f17dd937cdc29019aScott Main ft.add(android.R.id.content, mFragment, mTag); 967258a51e3e687d4d469de501f17dd937cdc29019aScott Main } else { 968258a51e3e687d4d469de501f17dd937cdc29019aScott Main // If it exists, simply attach it in order to show it 969258a51e3e687d4d469de501f17dd937cdc29019aScott Main ft.attach(mFragment); 970258a51e3e687d4d469de501f17dd937cdc29019aScott Main } 97118439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main } 97218439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 97318439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main public void onTabUnselected(Tab tab, FragmentTransaction ft) { 974258a51e3e687d4d469de501f17dd937cdc29019aScott Main if (mFragment != null) { 975258a51e3e687d4d469de501f17dd937cdc29019aScott Main // Detach the fragment, because another one is being attached 976258a51e3e687d4d469de501f17dd937cdc29019aScott Main ft.detach(mFragment); 977258a51e3e687d4d469de501f17dd937cdc29019aScott Main } 97818439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main } 97918439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 98018439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main public void onTabReselected(Tab tab, FragmentTransaction ft) { 981258a51e3e687d4d469de501f17dd937cdc29019aScott Main // User selected the already selected tab. Usually do nothing. 98218439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main } 98318439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main} 98418439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main</pre> 985258a51e3e687d4d469de501f17dd937cdc29019aScott Main 986258a51e3e687d4d469de501f17dd937cdc29019aScott Main<p class="caution"><strong>Caution:</strong> You <strong>must not</strong> call {@link 987258a51e3e687d4d469de501f17dd937cdc29019aScott Mainandroid.app.FragmentTransaction#commit} for the fragment transaction in each of these 988258a51e3e687d4d469de501f17dd937cdc29019aScott Maincallbacks—the system calls it for you and it may throw an exception if you call it yourself. 989258a51e3e687d4d469de501f17dd937cdc29019aScott MainYou also <strong>cannot</strong> add these fragment transactions to the back stack.</p> 990258a51e3e687d4d469de501f17dd937cdc29019aScott Main 991258a51e3e687d4d469de501f17dd937cdc29019aScott Main<p>In this example, the listener simply attaches ({@link android.app.FragmentTransaction#attach 992258a51e3e687d4d469de501f17dd937cdc29019aScott Mainattach()}) a fragment to the activity layout—or if not instantiated, creates the fragment and 993258a51e3e687d4d469de501f17dd937cdc29019aScott Mainadds ({@link android.app.FragmentTransaction#add add()}) it to the layout (as a child of the {@code 994258a51e3e687d4d469de501f17dd937cdc29019aScott Mainandroid.R.id.content} view group)—when the respective tab is selected, and detaches ({@link 995258a51e3e687d4d469de501f17dd937cdc29019aScott Mainandroid.app.FragmentTransaction#detach detach()}) it when the tab is unselected.</p> 996258a51e3e687d4d469de501f17dd937cdc29019aScott Main 997e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>All that remains is to create each {@link android.app.ActionBar.Tab} and add it to the {@link 998258a51e3e687d4d469de501f17dd937cdc29019aScott Mainandroid.app.ActionBar}. Additionally, you must call {@link 999258a51e3e687d4d469de501f17dd937cdc29019aScott Mainandroid.app.ActionBar#setNavigationMode(int) setNavigationMode(NAVIGATION_MODE_TABS)} to make the 1000e04c4543027df129cd7c004c1b21b01a7f4928adScott Maintabs visible.</p> 1001258a51e3e687d4d469de501f17dd937cdc29019aScott Main 1002258a51e3e687d4d469de501f17dd937cdc29019aScott Main<p>For example, the following code adds two tabs using the listener defined above:</p> 1003258a51e3e687d4d469de501f17dd937cdc29019aScott Main 100418439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main<pre> 100518439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main@Override 100618439bee6f8b525abe3f1fac69bc4cea184e1565Scott Mainprotected void onCreate(Bundle savedInstanceState) { 100718439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main super.onCreate(savedInstanceState); 1008258a51e3e687d4d469de501f17dd937cdc29019aScott Main // Notice that setContentView() is not used, because we use the root 1009258a51e3e687d4d469de501f17dd937cdc29019aScott Main // android.R.id.content as the container for each fragment 101018439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 1011258a51e3e687d4d469de501f17dd937cdc29019aScott Main // setup action bar for tabs 1012e04c4543027df129cd7c004c1b21b01a7f4928adScott Main ActionBar actionBar = getSupportActionBar(); 101318439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main actionBar.setNavigationMode(ActionBar.NAVIGATION_MODE_TABS); 10146ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main actionBar.setDisplayShowTitleEnabled(false); 101518439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 1016258a51e3e687d4d469de501f17dd937cdc29019aScott Main Tab tab = actionBar.newTab() 1017e04c4543027df129cd7c004c1b21b01a7f4928adScott Main .setText(R.string.artist) 1018e04c4543027df129cd7c004c1b21b01a7f4928adScott Main .setTabListener(new TabListener<ArtistFragment>( 1019e04c4543027df129cd7c004c1b21b01a7f4928adScott Main this, "artist", ArtistFragment.class)); 1020258a51e3e687d4d469de501f17dd937cdc29019aScott Main actionBar.addTab(tab); 1021258a51e3e687d4d469de501f17dd937cdc29019aScott Main 1022258a51e3e687d4d469de501f17dd937cdc29019aScott Main tab = actionBar.newTab() 1023e04c4543027df129cd7c004c1b21b01a7f4928adScott Main .setText(R.string.album) 1024e04c4543027df129cd7c004c1b21b01a7f4928adScott Main .setTabListener(new TabListener<AlbumFragment>( 1025e04c4543027df129cd7c004c1b21b01a7f4928adScott Main this, "album", AlbumFragment.class)); 1026258a51e3e687d4d469de501f17dd937cdc29019aScott Main actionBar.addTab(tab); 102718439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main} 102818439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main</pre> 102918439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 103018439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 1031e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>If your activity stops, you should retain the currently selected tab with the <a href= 1032e04c4543027df129cd7c004c1b21b01a7f4928adScott Main"{@docRoot}guide/components/activities.html#SavingActivityState">saved instance state</a> so you 1033e04c4543027df129cd7c004c1b21b01a7f4928adScott Maincan open the appropriate tab when the user returns. When it's time to save the state, you can query 1034e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainthe currently selected tab with {@link 1035e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.support.v7.app.ActionBar#getSelectedNavigationIndex()}. This returns the index position of 1036e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainthe selected tab.</p> 103718439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 103818439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 1039258a51e3e687d4d469de501f17dd937cdc29019aScott Main<p class="caution"><strong>Caution:</strong> It's important that you save the state of each fragment 1040e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainso when users switch fragments with the tabs and then return to a previous 1041e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainfragment, it looks the way it did when they left. Some of the state is saved by default, but you 1042e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainmay need to manually save state for customized views. For information about saving the state of your 104350e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainfragment, see the <a href="{@docRoot}guide/components/fragments.html">Fragments</a> 1044e04c4543027df129cd7c004c1b21b01a7f4928adScott MainAPI guide.</p> 1045e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 1046e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p class="note"><strong>Note:</strong> The above implementation for {@link 1047e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.support.v7.app.ActionBar.TabListener} is one of several possible techniques. Another popular 1048e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainoption is to use {@link android.support.v4.view.ViewPager} to manage the fragments so users 1049e04c4543027df129cd7c004c1b21b01a7f4928adScott Maincan also use a swipe gesture to switch tabs. In this case, you simply tell the 1050e04c4543027df129cd7c004c1b21b01a7f4928adScott Main{@link android.support.v4.view.ViewPager} the current tab position in the 1051e04c4543027df129cd7c004c1b21b01a7f4928adScott Main{@link android.support.v7.app.ActionBar.TabListener#onTabSelected onTabSelected()} callback. 1052e04c4543027df129cd7c004c1b21b01a7f4928adScott MainFor more information, read 1053e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<a href="{@docRoot}training/implementing-navigation/lateral.html" 1054e04c4543027df129cd7c004c1b21b01a7f4928adScott Main>Creating Swipe Views with Tabs</a>.</p> 105518439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 105618439bee6f8b525abe3f1fac69bc4cea184e1565Scott Main 105750403a203357ec9e003b198728f89278c88d4f0fScott Main 10586ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 105950403a203357ec9e003b198728f89278c88d4f0fScott Main 1060e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<h2 id="Dropdown">Adding Drop-down Navigation</h2> 106150403a203357ec9e003b198728f89278c88d4f0fScott Main 1062e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<div class="figure" style="width:240px"> 1063e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <img src="{@docRoot}images/ui/actionbar-dropdown@2x.png" alt="" width="240" /> 1064e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <p class="img-caption"><strong>Figure 9.</strong> A drop-down navigation list in the 1065258a51e3e687d4d469de501f17dd937cdc29019aScott Mainaction bar.</p> 106650403a203357ec9e003b198728f89278c88d4f0fScott Main</div> 1067e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 1068e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>As another mode of navigation (or filtering) for your activity, the action bar offers a built 1069e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainin drop-down list (also known as a "spinner"). For example, the drop-down list can offer different 1070e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainmodes by which content in the activity is sorted.</p> 1071e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 1072e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>Using the drop-down list is useful when changing the content is important but not necessarily a 1073e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainfrequent occurrence. In cases where switching the content is more frequent, 1074e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainyou should use <a href="#Tabs">navigation tabs</a> instead.</p> 1075e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 107650403a203357ec9e003b198728f89278c88d4f0fScott Main 1077258a51e3e687d4d469de501f17dd937cdc29019aScott Main<p>The basic procedure to enable drop-down navigation is:</p> 107850403a203357ec9e003b198728f89278c88d4f0fScott Main 107950403a203357ec9e003b198728f89278c88d4f0fScott Main<ol> 108050403a203357ec9e003b198728f89278c88d4f0fScott Main <li>Create a {@link android.widget.SpinnerAdapter} that provides the 10816ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Mainlist of selectable items for the drop-down and the layout to use when drawing each item in the 10826ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Mainlist.</li> 1083e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <li>Implement {@link android.support.v7.app.ActionBar.OnNavigationListener} to define the 1084e04c4543027df129cd7c004c1b21b01a7f4928adScott Main behavior that occurs when the user selects an item from the list.</li> 1085e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <li>During your activity's {@link android.app.Activity#onCreate 1086e04c4543027df129cd7c004c1b21b01a7f4928adScott MainonCreate()} method, enable the action bar's drop-down list by calling {@link 1087e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.support.v7.app.ActionBar#setNavigationMode setNavigationMode(NAVIGATION_MODE_LIST)}. 108850403a203357ec9e003b198728f89278c88d4f0fScott Main </li> 1089258a51e3e687d4d469de501f17dd937cdc29019aScott Main <li>Set the callback for the drop-down list with {@link 1090e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.support.v7.app.ActionBar#setListNavigationCallbacks setListNavigationCallbacks()}. 1091e04c4543027df129cd7c004c1b21b01a7f4928adScott MainFor example: 109250403a203357ec9e003b198728f89278c88d4f0fScott Main<pre> 109350403a203357ec9e003b198728f89278c88d4f0fScott MainactionBar.setListNavigationCallbacks(mSpinnerAdapter, mNavigationCallback); 109450403a203357ec9e003b198728f89278c88d4f0fScott Main</pre> 109550403a203357ec9e003b198728f89278c88d4f0fScott Main<p>This method takes your {@link android.widget.SpinnerAdapter} and {@link 1096e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.support.v7.app.ActionBar.OnNavigationListener}.</p> 109750403a203357ec9e003b198728f89278c88d4f0fScott Main</li> 109850403a203357ec9e003b198728f89278c88d4f0fScott Main</ol> 109950403a203357ec9e003b198728f89278c88d4f0fScott Main 1100e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>This procedure is relatively short, but implementing the {@link android.widget.SpinnerAdapter} 1101e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainand {@link android.app.ActionBar.OnNavigationListener} is where most of the work is done. There are 1102e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainmany ways you can implement these to define the functionality for your drop-down navigation and 11036ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Mainimplementing various types of {@link android.widget.SpinnerAdapter} is beyond the scope of this 11046ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Maindocument (you should refer to the {@link android.widget.SpinnerAdapter} class reference for more 1105e04c4543027df129cd7c004c1b21b01a7f4928adScott Maininformation). However, below is an example for a {@link android.widget.SpinnerAdapter} and {@link 1106e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainandroid.app.ActionBar.OnNavigationListener} to get you started (click the title to reveal the 1107e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainsample).</p> 11086ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 11096ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 11106ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 11116ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main<div class="toggle-content closed"> 111250403a203357ec9e003b198728f89278c88d4f0fScott Main 11136ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main <h3 id="Spinner"><a href="#" onclick="return toggleContent(this)"> 11146ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt="" /> 11156ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main Example SpinnerAdapter and OnNavigationListener 11166ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main </a></h3> 111750403a203357ec9e003b198728f89278c88d4f0fScott Main 11186ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main <div class="toggle-content-toggleme"> 111950403a203357ec9e003b198728f89278c88d4f0fScott Main 11206ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main<p>{@link android.widget.SpinnerAdapter} is an adapter that provides data for a spinner widget, 1121258a51e3e687d4d469de501f17dd937cdc29019aScott Mainsuch as the drop-down list in the action bar. {@link android.widget.SpinnerAdapter} is an interface 11226ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Mainthat you can implement, but Android includes some useful implementations that you can extend, such 11236ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Mainas {@link android.widget.ArrayAdapter} and {@link 112450403a203357ec9e003b198728f89278c88d4f0fScott Mainandroid.widget.SimpleCursorAdapter}. For example, here's an easy way to create a {@link 11256ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Mainandroid.widget.SpinnerAdapter} by using {@link android.widget.ArrayAdapter} implementation, which 11266ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Mainuses a string array as the data source:</p> 112750403a203357ec9e003b198728f89278c88d4f0fScott Main 112850403a203357ec9e003b198728f89278c88d4f0fScott Main<pre> 1129026c82b1916a9e2b48b9ff62ffeb935d63935a68Andrew SolovaySpinnerAdapter mSpinnerAdapter = ArrayAdapter.createFromResource(this, 1130026c82b1916a9e2b48b9ff62ffeb935d63935a68Andrew Solovay R.array.action_list, android.R.layout.simple_spinner_dropdown_item); 113150403a203357ec9e003b198728f89278c88d4f0fScott Main</pre> 113250403a203357ec9e003b198728f89278c88d4f0fScott Main 11336ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main<p>The {@link android.widget.ArrayAdapter#createFromResource createFromResource()} method takes 11346ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Mainthree parameters: the application {@link android.content.Context}, the resource ID for the string 11356ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Mainarray, and the layout to use for each list item.</p> 113650403a203357ec9e003b198728f89278c88d4f0fScott Main 113750403a203357ec9e003b198728f89278c88d4f0fScott Main<p>A <a href="{@docRoot}guide/topics/resources/string-resource.html#StringArray">string array</a> 11386ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Maindefined in a resource looks like this:</p> 113950403a203357ec9e003b198728f89278c88d4f0fScott Main 114050403a203357ec9e003b198728f89278c88d4f0fScott Main<pre> 114150403a203357ec9e003b198728f89278c88d4f0fScott Main<?xml version="1.0" encoding="utf-8"?> 114250403a203357ec9e003b198728f89278c88d4f0fScott Main<resources> 114350403a203357ec9e003b198728f89278c88d4f0fScott Main <string-array name="action_list"> 114450403a203357ec9e003b198728f89278c88d4f0fScott Main <item>Mercury</item> 114550403a203357ec9e003b198728f89278c88d4f0fScott Main <item>Venus</item> 114650403a203357ec9e003b198728f89278c88d4f0fScott Main <item>Earth</item> 114750403a203357ec9e003b198728f89278c88d4f0fScott Main </string-array> 11483555e4aef0d5664645e35d33779bf1bd140a7e50Andrew Solovay</resources> 114950403a203357ec9e003b198728f89278c88d4f0fScott Main</pre> 115050403a203357ec9e003b198728f89278c88d4f0fScott Main 11516ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main<p>The {@link android.widget.ArrayAdapter} returned by {@link 11526ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Mainandroid.widget.ArrayAdapter#createFromResource createFromResource()} is complete and ready for you 11536ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Mainto pass it to {@link android.app.ActionBar#setListNavigationCallbacks setListNavigationCallbacks()} 11546ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main(in step 4 from above). Before you do, though, you need to create the {@link 11556ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Mainandroid.app.ActionBar.OnNavigationListener OnNavigationListener}.</p> 115650403a203357ec9e003b198728f89278c88d4f0fScott Main 115750403a203357ec9e003b198728f89278c88d4f0fScott Main 11588515ee846bd76aee86ec5ddfcc4dd1e626dd999cAdam Powell<p>Your implementation of {@link android.app.ActionBar.OnNavigationListener} is where you handle 115950403a203357ec9e003b198728f89278c88d4f0fScott Mainfragment changes or other modifications to your activity when the user selects an item from the 11606ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Maindrop-down list. There's only one callback method to implement in the listener: {@link 11618515ee846bd76aee86ec5ddfcc4dd1e626dd999cAdam Powellandroid.app.ActionBar.OnNavigationListener#onNavigationItemSelected onNavigationItemSelected()}.</p> 116250403a203357ec9e003b198728f89278c88d4f0fScott Main 116350403a203357ec9e003b198728f89278c88d4f0fScott Main<p>The {@link 11648515ee846bd76aee86ec5ddfcc4dd1e626dd999cAdam Powellandroid.app.ActionBar.OnNavigationListener#onNavigationItemSelected onNavigationItemSelected()} 11656ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Mainmethod receives the position of the item in the list and a unique item ID provided by the {@link 116650403a203357ec9e003b198728f89278c88d4f0fScott Mainandroid.widget.SpinnerAdapter}.</p> 116750403a203357ec9e003b198728f89278c88d4f0fScott Main 116850403a203357ec9e003b198728f89278c88d4f0fScott Main<p>Here's an example that instantiates an anonymous implementation of {@link 11696ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Mainandroid.app.ActionBar.OnNavigationListener OnNavigationListener}, which inserts a {@link 11706ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Mainandroid.app.Fragment} into the 117150403a203357ec9e003b198728f89278c88d4f0fScott Mainlayout container identified by {@code R.id.fragment_container}:</p> 117250403a203357ec9e003b198728f89278c88d4f0fScott Main 117350403a203357ec9e003b198728f89278c88d4f0fScott Main<pre> 11748515ee846bd76aee86ec5ddfcc4dd1e626dd999cAdam PowellmOnNavigationListener = new OnNavigationListener() { 117550403a203357ec9e003b198728f89278c88d4f0fScott Main // Get the same strings provided for the drop-down's ArrayAdapter 117650403a203357ec9e003b198728f89278c88d4f0fScott Main String[] strings = getResources().getStringArray(R.array.action_list); 117750403a203357ec9e003b198728f89278c88d4f0fScott Main 117850403a203357ec9e003b198728f89278c88d4f0fScott Main @Override 117950403a203357ec9e003b198728f89278c88d4f0fScott Main public boolean onNavigationItemSelected(int position, long itemId) { 118050403a203357ec9e003b198728f89278c88d4f0fScott Main // Create new fragment from our own Fragment class 118150403a203357ec9e003b198728f89278c88d4f0fScott Main ListContentFragment newFragment = new ListContentFragment(); 1182026c82b1916a9e2b48b9ff62ffeb935d63935a68Andrew Solovay FragmentTransaction ft = getSupportFragmentManager().beginTransaction(); 1183026c82b1916a9e2b48b9ff62ffeb935d63935a68Andrew Solovay 118450403a203357ec9e003b198728f89278c88d4f0fScott Main // Replace whatever is in the fragment container with this fragment 1185026c82b1916a9e2b48b9ff62ffeb935d63935a68Andrew Solovay // and give the fragment a tag name equal to the string at the position 1186026c82b1916a9e2b48b9ff62ffeb935d63935a68Andrew Solovay // selected 118750403a203357ec9e003b198728f89278c88d4f0fScott Main ft.replace(R.id.fragment_container, newFragment, strings[position]); 1188026c82b1916a9e2b48b9ff62ffeb935d63935a68Andrew Solovay 118950403a203357ec9e003b198728f89278c88d4f0fScott Main // Apply changes 119050403a203357ec9e003b198728f89278c88d4f0fScott Main ft.commit(); 119150403a203357ec9e003b198728f89278c88d4f0fScott Main return true; 119250403a203357ec9e003b198728f89278c88d4f0fScott Main } 119350403a203357ec9e003b198728f89278c88d4f0fScott Main}; 119450403a203357ec9e003b198728f89278c88d4f0fScott Main</pre> 119550403a203357ec9e003b198728f89278c88d4f0fScott Main 11966ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main<p>This instance of {@link android.app.ActionBar.OnNavigationListener OnNavigationListener} is 11976ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Maincomplete and you can now call {@link android.app.ActionBar#setListNavigationCallbacks 11986ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott MainsetListNavigationCallbacks()} (in step 4), passing the {@link android.widget.ArrayAdapter} and this 11996ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main{@link android.app.ActionBar.OnNavigationListener OnNavigationListener}.</p> 120050403a203357ec9e003b198728f89278c88d4f0fScott Main 12016ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main<p>In this example, when the user selects an item from the drop-down list, a fragment is added to 12026ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Mainthe layout (replacing the current fragment in the {@code R.id.fragment_container} view). The 12036ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Mainfragment added is given a tag that uniquely identifies it, which is the same string used to 12046ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Mainidentify the fragment in the drop-down list.</p> 12056ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 12066ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main<p>Here's a look at the {@code ListContentFragment} class that defines each fragment in this 12076ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Mainexample:</p> 120850403a203357ec9e003b198728f89278c88d4f0fScott Main 120950403a203357ec9e003b198728f89278c88d4f0fScott Main<pre> 121050403a203357ec9e003b198728f89278c88d4f0fScott Mainpublic class ListContentFragment extends Fragment { 121150403a203357ec9e003b198728f89278c88d4f0fScott Main private String mText; 121250403a203357ec9e003b198728f89278c88d4f0fScott Main 121350403a203357ec9e003b198728f89278c88d4f0fScott Main @Override 121450403a203357ec9e003b198728f89278c88d4f0fScott Main public void onAttach(Activity activity) { 121550403a203357ec9e003b198728f89278c88d4f0fScott Main // This is the first callback received; here we can set the text for 1216026c82b1916a9e2b48b9ff62ffeb935d63935a68Andrew Solovay // the fragment as defined by the tag specified during the fragment 1217026c82b1916a9e2b48b9ff62ffeb935d63935a68Andrew Solovay // transaction 121850403a203357ec9e003b198728f89278c88d4f0fScott Main super.onAttach(activity); 121950403a203357ec9e003b198728f89278c88d4f0fScott Main mText = getTag(); 122050403a203357ec9e003b198728f89278c88d4f0fScott Main } 122150403a203357ec9e003b198728f89278c88d4f0fScott Main 122250403a203357ec9e003b198728f89278c88d4f0fScott Main @Override 122350403a203357ec9e003b198728f89278c88d4f0fScott Main public View onCreateView(LayoutInflater inflater, ViewGroup container, 122450403a203357ec9e003b198728f89278c88d4f0fScott Main Bundle savedInstanceState) { 122550403a203357ec9e003b198728f89278c88d4f0fScott Main // This is called to define the layout for the fragment; 122650403a203357ec9e003b198728f89278c88d4f0fScott Main // we just create a TextView and set its text to be the fragment tag 122750403a203357ec9e003b198728f89278c88d4f0fScott Main TextView text = new TextView(getActivity()); 122850403a203357ec9e003b198728f89278c88d4f0fScott Main text.setText(mText); 122950403a203357ec9e003b198728f89278c88d4f0fScott Main return text; 123050403a203357ec9e003b198728f89278c88d4f0fScott Main } 123150403a203357ec9e003b198728f89278c88d4f0fScott Main} 123250403a203357ec9e003b198728f89278c88d4f0fScott Main</pre> 123350403a203357ec9e003b198728f89278c88d4f0fScott Main 12346ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main </div><!-- end toggle-content-toggleme --> 12356ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 12366ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main</div><!-- end toggle-content --> 12376ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 12386ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 12396ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 12406ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 12416ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 12426ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 12436ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 1244e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<h2 id="Style">Styling the Action Bar</h2> 1245e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 1246e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>If you want to implement a visual design that represents your app's brand, the action bar allows 1247e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainyou to customize each detail of its appearance, including the action bar color, text colors, button 1248e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainstyles, and more. To do so, you need to use Android's <a href= 1249e04c4543027df129cd7c004c1b21b01a7f4928adScott Main"{@docRoot}guide/topics/ui/themes.html">style and theme</a> framework to restyle the action bar 1250e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainusing special style properties.</p> 12516ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 1252e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p class="caution"><strong>Caution:</strong> For all background drawables you provide, be sure to 1253e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainuse <a href="{@docRoot}guide/topics/graphics/2d-graphics.html#nine-patch">Nine-Patch drawables</a> 1254e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainto allow stretching. The nine-patch image should be <em>smaller</em> than 40dp tall and 30dp 1255e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainwide.</p> 12566ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 12576ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 12586ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 1259258a51e3e687d4d469de501f17dd937cdc29019aScott Main<h3 id="GeneralStyles">General appearance</h3> 12606ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 1261258a51e3e687d4d469de501f17dd937cdc29019aScott Main<dl> 1262e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <dt>{@link android.R.attr#actionBarStyle 1263e04c4543027df129cd7c004c1b21b01a7f4928adScott Main actionBarStyle}</dt> 1264e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <dd>Specifies a style resource that defines various style properties 1265e04c4543027df129cd7c004c1b21b01a7f4928adScott Main for the action bar. 1266e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <p>The default for this style for this 1267e04c4543027df129cd7c004c1b21b01a7f4928adScott Main is {@link android.support.v7.appcompat.R.style#Widget_AppCompat_ActionBar 1268e04c4543027df129cd7c004c1b21b01a7f4928adScott Main Widget.AppCompat.ActionBar}, which is what you should use as the parent style.</p> 1269e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <p>Supported styles include:</p> 1270e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <dl> 1271e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <dt>{@link android.R.attr#background}</dt> 1272e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <dd>Defines a drawable resource for the action bar background.</dd> 1273e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <dt>{@link android.R.attr#backgroundStacked}</dt> 1274e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <dd>Defines a drawable resource for the stacked action bar 1275e04c4543027df129cd7c004c1b21b01a7f4928adScott Main (the <a href="#Tabs">tabs</a>).</dd> 1276e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <dt>{@link android.R.attr#backgroundSplit}</dt> 1277e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <dd>Defines a drawable resource for the <a href="#SplitBar">split action bar</a>.</dd> 1278e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <dt>{@link android.R.attr#actionButtonStyle}</dt> 1279e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <dd>Defines a style resource for action buttons. 1280e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <p>The default for this style for this 1281e04c4543027df129cd7c004c1b21b01a7f4928adScott Main is {@link android.support.v7.appcompat.R.style#Widget_AppCompat_ActionButton 1282e04c4543027df129cd7c004c1b21b01a7f4928adScott Main Widget.AppCompat.ActionButton}, which is what you should use as the parent style.</p> 1283e04c4543027df129cd7c004c1b21b01a7f4928adScott Main </dd> 1284e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <dt>{@link android.R.attr#actionOverflowButtonStyle}</dt> 1285e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <dd>Defines a style resource for overflow action items. 1286e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <p>The default for this style for this 1287e04c4543027df129cd7c004c1b21b01a7f4928adScott Main is {@link android.support.v7.appcompat.R.style#Widget_AppCompat_ActionButton_Overflow 1288e04c4543027df129cd7c004c1b21b01a7f4928adScott Main Widget.AppCompat.ActionButton.Overflow}, which is what you should use as the parent style.</p> 1289e04c4543027df129cd7c004c1b21b01a7f4928adScott Main </dd> 1290e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <dt>{@link android.R.attr#displayOptions}</dt> 1291e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <dd>Defines one or more action bar display options, such as whether to use the app logo, 1292e04c4543027df129cd7c004c1b21b01a7f4928adScott Main show the activity title, or enable the <em>Up</em> action. See {@link 1293e04c4543027df129cd7c004c1b21b01a7f4928adScott Main android.R.attr#displayOptions} for all possible values. 1294e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <dt>{@link android.R.attr#divider}</dt> 1295e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <dd>Defines a drawable resource for the divider between action items.</dd> 1296e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <dt>{@link android.R.attr#titleTextStyle}</dt> 1297e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <dd>Defines a style resource for the action bar title. 1298e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <p>The default for this style for this 1299e04c4543027df129cd7c004c1b21b01a7f4928adScott Main is {@link android.support.v7.appcompat.R.style#TextAppearance_AppCompat_Widget_ActionBar_Title 1300e04c4543027df129cd7c004c1b21b01a7f4928adScott Main TextAppearance.AppCompat.Widget.ActionBar.Title}, which is what you should use as the parent 1301e04c4543027df129cd7c004c1b21b01a7f4928adScott Main style.</p></dd> 1302e04c4543027df129cd7c004c1b21b01a7f4928adScott Main </dl> 1303e04c4543027df129cd7c004c1b21b01a7f4928adScott Main </dd> 1304258a51e3e687d4d469de501f17dd937cdc29019aScott Main 1305258a51e3e687d4d469de501f17dd937cdc29019aScott Main <dt>{@link android.R.attr#windowActionBarOverlay 1306e04c4543027df129cd7c004c1b21b01a7f4928adScott Main windowActionBarOverlay}</dt> 1307258a51e3e687d4d469de501f17dd937cdc29019aScott Main <dd>Declares whether the action bar should overlay the activity layout rather than offset the 1308258a51e3e687d4d469de501f17dd937cdc29019aScott Mainactivity's layout position (for example, the Gallery app uses overlay mode). This is 1309258a51e3e687d4d469de501f17dd937cdc29019aScott Main{@code false} by default. 1310258a51e3e687d4d469de501f17dd937cdc29019aScott Main <p>Normally, the action bar requires its own space on the screen and your activity layout fills in 1311258a51e3e687d4d469de501f17dd937cdc29019aScott Mainwhat's left over. When the action bar is in overlay mode, your activity layout uses all the 1312258a51e3e687d4d469de501f17dd937cdc29019aScott Mainavailable space and the system draws the action bar on top. Overlay mode can be useful if you want 1313258a51e3e687d4d469de501f17dd937cdc29019aScott Mainyour content to keep a fixed size and position when the action bar is hidden and shown. You might 1314258a51e3e687d4d469de501f17dd937cdc29019aScott Mainalso like to use it purely as a visual effect, because you can use a semi-transparent background 1315258a51e3e687d4d469de501f17dd937cdc29019aScott Mainfor the action bar so the user can still see some of your activity layout behind the action 1316258a51e3e687d4d469de501f17dd937cdc29019aScott Mainbar.</p> 1317258a51e3e687d4d469de501f17dd937cdc29019aScott Main <p class="note"><strong>Note:</strong> The {@link android.R.style#Theme_Holo Holo} theme families 1318258a51e3e687d4d469de501f17dd937cdc29019aScott Maindraw the action bar with a semi-transparent background by default. However, you can modify it with 1319258a51e3e687d4d469de501f17dd937cdc29019aScott Mainyour own styles and the {@link android.R.style#Theme_DeviceDefault DeviceDefault} theme on 1320258a51e3e687d4d469de501f17dd937cdc29019aScott Maindifferent devices might use an opaque background by default.</p> 1321e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <p>When overlay mode is enabled, your activity layout has no awareness of the action bar lying on 1322258a51e3e687d4d469de501f17dd937cdc29019aScott Maintop of it. So, you must be careful not to place any important information or UI components in the 1323e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainarea overlaid by the action bar. If appropriate, you can refer to the platform's value for {@link 1324258a51e3e687d4d469de501f17dd937cdc29019aScott Mainandroid.R.attr#actionBarSize} to determine the height of the action bar, by referencing it 1325258a51e3e687d4d469de501f17dd937cdc29019aScott Mainin your XML layout. For example:</p> 13266ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main<pre> 1327258a51e3e687d4d469de501f17dd937cdc29019aScott Main<SomeView 1328258a51e3e687d4d469de501f17dd937cdc29019aScott Main ... 1329258a51e3e687d4d469de501f17dd937cdc29019aScott Main android:layout_marginTop="?android:attr/actionBarSize" /> 13306ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main</pre> 1331258a51e3e687d4d469de501f17dd937cdc29019aScott Main <p>You can also retrieve the action bar height at runtime with {@link 1332258a51e3e687d4d469de501f17dd937cdc29019aScott Mainandroid.app.ActionBar#getHeight()}. This reflects the height of the action bar at the time it's 1333e04c4543027df129cd7c004c1b21b01a7f4928adScott Maincalled, which might not include the stacked action bar (due to navigation tabs) if called during 1334e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainearly activity lifecycle methods. To see how you can determine the total height at runtime, 1335e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainincluding the stacked action bar, see the <a href= 1336e04c4543027df129cd7c004c1b21b01a7f4928adScott Main"{@docRoot}resources/samples/HoneycombGallery/src/com/example/android/hcgallery/TitlesFragment.html"> 1337e04c4543027df129cd7c004c1b21b01a7f4928adScott Main{@code TitlesFragment}</a> class in the <a href= 1338e04c4543027df129cd7c004c1b21b01a7f4928adScott Main"{@docRoot}resources/samples/HoneycombGallery/index.html">Honeycomb Gallery</a> sample app.</p> 1339e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 1340258a51e3e687d4d469de501f17dd937cdc29019aScott Main</dd> 1341258a51e3e687d4d469de501f17dd937cdc29019aScott Main 1342258a51e3e687d4d469de501f17dd937cdc29019aScott Main</dl> 13436ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 1344258a51e3e687d4d469de501f17dd937cdc29019aScott Main 1345258a51e3e687d4d469de501f17dd937cdc29019aScott Main<h3 id="ActionItemStyles">Action items</h3> 13466ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 13476ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main<dl> 1348258a51e3e687d4d469de501f17dd937cdc29019aScott Main <dt>{@link android.R.attr#actionButtonStyle 1349e04c4543027df129cd7c004c1b21b01a7f4928adScott Main actionButtonStyle}</dt> 1350e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <dd>Defines a style resource for the action item buttons. 1351e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <p>The default for this style for this 1352e04c4543027df129cd7c004c1b21b01a7f4928adScott Main is {@link android.support.v7.appcompat.R.style#Widget_AppCompat_ActionButton 1353e04c4543027df129cd7c004c1b21b01a7f4928adScott Main Widget.AppCompat.ActionButton}, which is what you should use as the parent style.</p></dd> 1354258a51e3e687d4d469de501f17dd937cdc29019aScott Main 1355258a51e3e687d4d469de501f17dd937cdc29019aScott Main <dt>{@link android.R.attr#actionBarItemBackground 1356e04c4543027df129cd7c004c1b21b01a7f4928adScott Main actionBarItemBackground}</dt> 1357e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <dd>Defines a drawable resource for each action item's background. 1358e04c4543027df129cd7c004c1b21b01a7f4928adScott Main This should be a <a href="{@docRoot}guide/topics/resources/drawable-resource.html#StateList" 1359e04c4543027df129cd7c004c1b21b01a7f4928adScott Main >state-list drawable</a> to indicate different selected states.</dd> 1360258a51e3e687d4d469de501f17dd937cdc29019aScott Main 1361258a51e3e687d4d469de501f17dd937cdc29019aScott Main <dt>{@link android.R.attr#itemBackground 1362e04c4543027df129cd7c004c1b21b01a7f4928adScott Main itemBackground}</dt> 1363e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <dd>Defines a drawable resource for each action overflow item's background. 1364e04c4543027df129cd7c004c1b21b01a7f4928adScott Main This should be a <a href="{@docRoot}guide/topics/resources/drawable-resource.html#StateList" 1365e04c4543027df129cd7c004c1b21b01a7f4928adScott Main >state-list drawable</a> to indicate different selected states.</dd> 1366258a51e3e687d4d469de501f17dd937cdc29019aScott Main 1367258a51e3e687d4d469de501f17dd937cdc29019aScott Main <dt>{@link android.R.attr#actionBarDivider 1368e04c4543027df129cd7c004c1b21b01a7f4928adScott Main actionBarDivider}</dt> 1369e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <dd>Defines a drawable resource for the divider between action items.</dd> 1370258a51e3e687d4d469de501f17dd937cdc29019aScott Main 1371258a51e3e687d4d469de501f17dd937cdc29019aScott Main <dt>{@link android.R.attr#actionMenuTextColor 1372e04c4543027df129cd7c004c1b21b01a7f4928adScott Main actionMenuTextColor}</dt> 1373258a51e3e687d4d469de501f17dd937cdc29019aScott Main <dd>Defines a color for text that appears in an action item.</dd> 1374258a51e3e687d4d469de501f17dd937cdc29019aScott Main 1375258a51e3e687d4d469de501f17dd937cdc29019aScott Main <dt>{@link android.R.attr#actionMenuTextAppearance 1376e04c4543027df129cd7c004c1b21b01a7f4928adScott Main actionMenuTextAppearance}</dt> 1377258a51e3e687d4d469de501f17dd937cdc29019aScott Main <dd>Defines a style resource for text that appears in an action item.</dd> 1378258a51e3e687d4d469de501f17dd937cdc29019aScott Main 1379258a51e3e687d4d469de501f17dd937cdc29019aScott Main <dt>{@link android.R.attr#actionBarWidgetTheme 1380e04c4543027df129cd7c004c1b21b01a7f4928adScott Main actionBarWidgetTheme}</dt> 1381258a51e3e687d4d469de501f17dd937cdc29019aScott Main <dd>Defines a theme resource for widgets that are inflated into the action bar as <a 1382e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainhref="#ActionView">action views</a>.</dd> 1383258a51e3e687d4d469de501f17dd937cdc29019aScott Main</dl> 1384258a51e3e687d4d469de501f17dd937cdc29019aScott Main 1385258a51e3e687d4d469de501f17dd937cdc29019aScott Main 1386258a51e3e687d4d469de501f17dd937cdc29019aScott Main<h3 id="NavigationStyles">Navigation tabs</h3> 1387258a51e3e687d4d469de501f17dd937cdc29019aScott Main 1388258a51e3e687d4d469de501f17dd937cdc29019aScott Main<dl> 1389258a51e3e687d4d469de501f17dd937cdc29019aScott Main <dt>{@link android.R.attr#actionBarTabStyle 1390e04c4543027df129cd7c004c1b21b01a7f4928adScott Main actionBarTabStyle}</dt> 1391e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <dd>Defines a style resource for tabs in the action bar. 1392e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <p>The default for this style for this 1393e04c4543027df129cd7c004c1b21b01a7f4928adScott Main is {@link android.support.v7.appcompat.R.style#Widget_AppCompat_ActionBar_TabView 1394e04c4543027df129cd7c004c1b21b01a7f4928adScott Main Widget.AppCompat.ActionBar.TabView}, which is what you should use as the parent style.</p></dd> 13956ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 1396258a51e3e687d4d469de501f17dd937cdc29019aScott Main <dt>{@link android.R.attr#actionBarTabBarStyle 1397e04c4543027df129cd7c004c1b21b01a7f4928adScott Main actionBarTabBarStyle}</dt> 1398e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <dd>Defines a style resource for the thin bar that appears below the navigation tabs. 1399e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <p>The default for this style for this 1400e04c4543027df129cd7c004c1b21b01a7f4928adScott Main is {@link android.support.v7.appcompat.R.style#Widget_AppCompat_ActionBar_TabBar 1401e04c4543027df129cd7c004c1b21b01a7f4928adScott Main Widget.AppCompat.ActionBar.TabBar}, which is what you should use as the parent style.</p></dd> 14026ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 1403258a51e3e687d4d469de501f17dd937cdc29019aScott Main <dt>{@link android.R.attr#actionBarTabTextStyle 1404e04c4543027df129cd7c004c1b21b01a7f4928adScott Main actionBarTabTextStyle}</dt> 1405e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <dd>Defines a style resource for text in the navigation tabs. 1406e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <p>The default for this style for this 1407e04c4543027df129cd7c004c1b21b01a7f4928adScott Main is {@link android.support.v7.appcompat.R.style#Widget_AppCompat_ActionBar_TabText 1408e04c4543027df129cd7c004c1b21b01a7f4928adScott Main Widget.AppCompat.ActionBar.TabText}, which is what you should use as the parent style.</p></dd> 1409258a51e3e687d4d469de501f17dd937cdc29019aScott Main</dl> 14106ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 14116ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 1412258a51e3e687d4d469de501f17dd937cdc29019aScott Main<h3 id="DropDownStyles">Drop-down lists</h3> 14136ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 1414258a51e3e687d4d469de501f17dd937cdc29019aScott Main<dl> 1415258a51e3e687d4d469de501f17dd937cdc29019aScott Main <dt>{@link android.R.attr#actionDropDownStyle 1416e04c4543027df129cd7c004c1b21b01a7f4928adScott Main actionDropDownStyle}</dt> 1417e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <dd>Defines a style for the drop-down navigation (such as the background and text styles). 1418e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <p>The default for this style for this 1419e04c4543027df129cd7c004c1b21b01a7f4928adScott Main is {@link android.support.v7.appcompat.R.style#Widget_AppCompat_Spinner_DropDown_ActionBar 1420e04c4543027df129cd7c004c1b21b01a7f4928adScott Main Widget.AppCompat.Spinner.DropDown.ActionBar}, which is what you should use as the parent 1421e04c4543027df129cd7c004c1b21b01a7f4928adScott Main style.</p></dd> 14226ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main</dl> 14236ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 1424258a51e3e687d4d469de501f17dd937cdc29019aScott Main 1425e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<h3 id="StyleExample">Example theme</h3> 1426e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 1427e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>Here's an example that defines a custom theme for an activity, {@code CustomActivityTheme}, 1428e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainthat includes several styles to customize the action bar.</p> 1429258a51e3e687d4d469de501f17dd937cdc29019aScott Main 14301e5bb861265072b9af555d09202e49cb38a3c4f1Natalie Masse<p>Notice that there are two versions for each action bar style property. The first one 1431e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainincludes the {@code android:} prefix on the property name to support API levels 11 and higher 1432e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainthat include these properties in the framework. The second version does <em>not</em> 1433e04c4543027df129cd7c004c1b21b01a7f4928adScott Maininclude the {@code android:} prefix and is for older versions of the platform, on which 1434e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainthe system uses the style property from the support library. The effect for each is the same.</p> 14356ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 14366ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main<pre> 14376ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main<?xml version="1.0" encoding="utf-8"?> 14386ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main<resources> 14396ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main <!-- the theme applied to the application or activity --> 1440e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <style name="CustomActionBarTheme" 1441e04c4543027df129cd7c004c1b21b01a7f4928adScott Main parent="@style/Theme.AppCompat.Light"> 1442e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <item name="android:actionBarStyle">@style/MyActionBar</item> 1443e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <item name="android:actionBarTabTextStyle">@style/TabTextStyle</item> 1444e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <item name="android:actionMenuTextColor">@color/actionbar_text</item> 1445e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 1446e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <!-- Support library compatibility --> 1447e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <item name="actionBarStyle">@style/MyActionBar</item> 1448e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <item name="actionBarTabTextStyle">@style/TabTextStyle</item> 1449e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <item name="actionMenuTextColor">@color/actionbar_text</item> 14506ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main </style> 14516ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 1452e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <!-- general styles for the action bar --> 1453e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <style name="MyActionBar" 1454e04c4543027df129cd7c004c1b21b01a7f4928adScott Main parent="@style/Widget.AppCompat.ActionBar"> 1455e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <item name="android:titleTextStyle">@style/TitleTextStyle</item> 1456e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <item name="android:background">@drawable/actionbar_background</item> 1457e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <item name="android:backgroundStacked">@drawable/actionbar_background</item> 1458e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <item name="android:backgroundSplit">@drawable/actionbar_background</item> 1459e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 1460e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <!-- Support library compatibility --> 1461e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <item name="titleTextStyle">@style/TitleTextStyle</item> 1462e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <item name="background">@drawable/actionbar_background</item> 1463e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <item name="backgroundStacked">@drawable/actionbar_background</item> 1464e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <item name="backgroundSplit">@drawable/actionbar_background</item> 14656ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main </style> 14666ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 1467e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <!-- action bar title text --> 1468e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <style name="TitleTextStyle" 1469e04c4543027df129cd7c004c1b21b01a7f4928adScott Main parent="@style/TextAppearance.AppCompat.Widget.ActionBar.Title"> 1470e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <item name="android:textColor">@color/actionbar_text</item> 1471e04c4543027df129cd7c004c1b21b01a7f4928adScott Main </style> 14726ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 1473e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <!-- action bar tab text --> 1474e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <style name="TabTextStyle" 1475e04c4543027df129cd7c004c1b21b01a7f4928adScott Main parent="@style/Widget.AppCompat.ActionBar.TabText"> 1476e04c4543027df129cd7c004c1b21b01a7f4928adScott Main <item name="android:textColor">@color/actionbar_text</item> 1477e04c4543027df129cd7c004c1b21b01a7f4928adScott Main </style> 1478e04c4543027df129cd7c004c1b21b01a7f4928adScott Main</resources> 14796ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 14806ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main</pre> 14816ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 1482e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>In your manifest file, you can apply the theme to your entire app:</p> 1483258a51e3e687d4d469de501f17dd937cdc29019aScott Main 1484e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<pre> 1485e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<application android:theme="@style/CustomActionBarTheme" ... /> 1486e04c4543027df129cd7c004c1b21b01a7f4928adScott Main</pre> 1487258a51e3e687d4d469de501f17dd937cdc29019aScott Main 1488e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>Or to individual activities:</p> 1489258a51e3e687d4d469de501f17dd937cdc29019aScott Main 1490258a51e3e687d4d469de501f17dd937cdc29019aScott Main<pre> 1491e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<activity android:theme="@style/CustomActionBarTheme" ... /> 1492258a51e3e687d4d469de501f17dd937cdc29019aScott Main</pre> 1493258a51e3e687d4d469de501f17dd937cdc29019aScott Main 14946ea0d2c0455ea43ffaf90c1e239cb7d6a3d49d2aScott Main 1495e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p class="caution"><strong>Caution:</strong> Be certain that each theme and style declares a parent 1496e04c4543027df129cd7c004c1b21b01a7f4928adScott Maintheme in the {@code <style>} tag, from which it inherits all styles not explicitly declared 1497e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainby your theme. When modifying the action bar, using a parent theme is important so that you can 1498e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainsimply override the action bar styles you want to change without re-implementing the styles you 1499e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainwant to leave alone (such as text size or padding in action items).</p> 1500e04c4543027df129cd7c004c1b21b01a7f4928adScott Main 1501e04c4543027df129cd7c004c1b21b01a7f4928adScott Main<p>For more information about using style and theme resources in your application, read <a 1502e04c4543027df129cd7c004c1b21b01a7f4928adScott Mainhref="{@docRoot}guide/topics/ui/themes.html">Styles and Themes</a>.</p> 150350403a203357ec9e003b198728f89278c88d4f0fScott Main 150450403a203357ec9e003b198728f89278c88d4f0fScott Main 150550403a203357ec9e003b198728f89278c88d4f0fScott Main 1506