
Figure 1. An action bar that includes the [1] app icon, [2] two action items, and [3] action overflow.
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).
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:
import android.support.v7.app.ActionBar
- If supporting only API level 11 and higher:
import android.app.ActionBar
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:<activity android:theme="@style/Theme.AppCompat.Light" ... >
Now your activity includes the action bar when running on Android 2.1 (API level 7) or higher.
On API level 11 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();
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'sonCreateOptionsMenu()
method. Use this method to inflate a menu resource that defines all the action items. For example, here's a menu resource defining a couple of menu items:
res/menu/main_activity_actions.xml
<menu xmlns:android="http://schemas.android.com/apk/res/android" >
<item android:id="@+id/action_search"
android:icon="@drawable/ic_action_search"
android:title="@string/action_search"/>
<item android:id="@+id/action_compose"
android:icon="@drawable/ic_action_compose"
android:title="@string/action_compose" />
</menu>
Then in your activity's onCreateOptionsMenu()
method, inflate the menu resource into the given Menu
to add each item to the action bar:
@Override
public boolean onCreateOptionsMenu(Menu menu) {
// Inflate the menu items for use in the action bar
MenuInflater inflater = getMenuInflater();
inflater.inflate(R.menu.main_activity_actions, menu);
return super.onCreateOptionsMenu(menu);
}
To request that an item appear directly in the action bar as an action button, include showAsAction="ifRoom"
in the <item>
tag. For example:
<menu xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:yourapp="http://schemas.android.com/apk/res-auto" >
<item android:id="@+id/action_search"
android:icon="@drawable/ic_action_search"
android:title="@string/action_search"
yourapp:showAsAction="ifRoom" />
...
</menu>
If there's not enough room for the item in the action bar, it will appear in the action overflow.
Using XML attributes from the support library
Notice that the
showAsAction
attribute above uses a custom namespace defined in the
<menu>
tag. This is necessary when using any XML attributes defined by the support library, because these attributes do not exist in the Android framework on older devices. So you must use your own namespace as a prefix for all attributes defined by the support library.
If your menu item supplies both a title and an icon—with the title
and icon
attributes—then the action item shows only the icon by default. If you want to display the text title, add "withText"
to the showAsAction
attribute. For example:
<item yourapp:showAsAction="ifRoom|withText" ... />
Note: The "withText"
value is a hint to the action bar that the text title should appear. The action bar will show the title when possible, but might not if an icon is available and the action bar is constrained for space.
You should always define the title
for each item even if you don't declare that the title appear with the action item, for the following reasons:
- If there's not enough room in the action bar for the action item, the menu item appears in the overflow where only the title appears.
- Screen readers for sight-impaired users read the menu item's title.
- If the action item appears with only the icon, a user can long-press the item to reveal a tool-tip that displays the action title.
The icon
is optional, but recommended. For icon design recommendations, see the Iconography design guide. You can also download a set of standard action bar icons (such as for Search or Discard) from the Downloadspage.
You can also use "always"
to declare that an item always appear as an action button. However, you should notforce an item to appear in the action bar this way. Doing so can create layout problems on devices with a narrow screen. It's best to instead use "ifRoom"
to request that an item appear in the action bar, but allow the system to move it into the overflow when there's not enough room. However, it might be necessary to use this value if the item includes an action view that cannot be collapsed and must always be visible to provide access to a critical feature.
Handling clicks on action items
When the user presses an action, the system calls your activity's onOptionsItemSelected()
method. Using the MenuItem
passed to this method, you can identify the action by calling getItemId()
. This returns the unique ID provided by the <item>
tag's id
attribute so you can perform the appropriate action. For example:
@Override
public boolean onOptionsItemSelected(MenuItem item) {
// Handle presses on the action bar items
switch (item.getItemId()) {
case R.id.action_search:
openSearch();
return true;
case R.id.action_compose:
composeMessage();
return true;
default:
return super.onOptionsItemSelected(item);
}
}
Note: If you inflate menu items from a fragment, via the Fragment
class's onCreateOptionsMenu()
callback, the system calls onOptionsItemSelected()
for that fragment when the user selects one of those items. However, the activity gets a chance to handle the event first, so the system first callsonOptionsItemSelected()
on the activity, before calling the same callback for the fragment. To ensure that any fragments in the activity also have a chance to handle the callback, always pass the call to the superclass as the default behavior instead of returning false
when you do not handle the item.
Original Post :developer.android.com/guide/topics/ui/actionbar.html