The action bar provides several key functions:
- Provides a dedicated space for giving your app an identity and indicating the user’s location in the app.
- Makes important actions prominent and accessible in a predictable way (such as Search).
- Supports consistent navigation and view switching within apps (with tabs or drop-down lists).
For more information about the action bar’s interaction patterns and design guidelines, see the Action Bar design guide.
The ActionBar APIs were first added in Android 3.0 (API level 11) but they are also available in the Support Library for compatibility with Android 2.1 (API level 7) and above.
This guide focuses on how to use the support library’s action bar, but if your app supports only Android 3.0 or higher, you should use the ActionBar APIs in the framework. Most of the APIs are the same—but reside in a different package namespace—with a few exceptions to method names or signatures that are noted in the sections below.
Caution: Be certain you import the ActionBar class (and related APIs) from the appropriate package:
- If supporting API levels lower than 11:
- If supporting only API level 11 and higher:
Adding the Action Bar
As mentioned above, this guide focuses on how to use the ActionBar APIs in the support library. So before you can add the action bar, you must set up your project with the appcompat v7 support library by following the instructions in the Support Library Setup.
Once your project is set up with the support library, here’s how to add the action bar:
- Create your activity by extending ActionBarActivity.
- Use (or extend) one of the Theme.AppCompat themes for your activity. For example:<activityandroid:theme=”@style/Theme.AppCompat.Light” … >
Now your activity includes the action bar when running on Android 2.1 (API level 7) or higher.
The action bar is included in all activities that use the Theme.Holo theme (or one of its descendants), which is the default theme when either the targetSdkVersion or minSdkVersion attribute is set to “11” or higher. If you don’t want the action bar for an activity, set the activity theme to Theme.Holo.NoActionBar.
Removing the action bar
You can hide the action bar at runtime by calling hide(). For example:
ActionBar actionBar = getSupportActionBar(); actionBar.hide();
Get the ActionBar with the getActionBar() method.
When the action bar hides, the system adjusts your layout to fill the screen space now available. You can bring the action bar back by calling show().
Beware that hiding and removing the action bar causes your activity to re-layout in order to account for the space consumed by the action bar. If your activity often hides and shows the action bar, you might want to enable overlay mode. Overlay mode draws the action bar in front of your activity layout, obscuring the top portion. This way, your layout remains fixed when the action bar hides and re-appears. To enable overlay mode, create a custom theme for your activity and set windowActionBarOverlay to true. For more information, see the section below about Styling the Action Bar.
Using a logo instead of an icon
By default, the system uses your application icon in the action bar, as specified by the icon attribute in the <application> or <activity> element. However, if you also specify the logo attribute, then the action bar uses the logo image instead of the icon.
A logo should usually be wider than the icon, but should not include unnecessary text. You should generally use a logo only when it represents your brand in a traditional format that users recognize. A good example is the YouTube app’s logo—the logo represents the expected user brand, whereas the app’s icon is a modified version that conforms to the square requirement for the launcher icon.
Adding Action Items
The action bar provides users access to the most important action items relating to the app’s current context. Those that appear directly in the action bar with an icon and/or text are known as action buttons. Actions that can’t fit in the action bar or aren’t important enough are hidden in the action overflow. The user can reveal a list of the other actions by pressing the overflow button on the right side (or the device Menu button, if available).
When your activity starts, the system populates the action items by calling your activity’s onCreateOptionsMenu() method. Use this method to inflate a menu resource that defines all the action items.