Figure 2. A screenshot from an action bar with two action items.
The action bar is a widget for activities that replaces the traditional title bar at the top of an activity. By default, the action bar includes the application logo on the left side, followed by the activity title. The action bar offers several useful features for applications—especially those targeted to tablet devices. The action bar features include the ability to:
Figure 1. A screenshot of the action bar in the NotePad sample application, containing action items to save and delete the note.
To add the Action Bar to your activity, apply the holographic theme—{@code Theme.Holo}—or the action bar theme—{@code Theme.WithActionBar}—in your manifest file. For example:
<activity android:theme="@android:style/Theme.Holo" >
The activity now appears with the action bar in place of the traditional title bar.
For each action item you want to add to the action bar, you must add a menu item to the activity's options menu and declare that the item be shown as an action, using the {@code android:showAsAction} attribute in the menu XML or with {@link android.view.MenuItem#setShowAsAction setShowAsAction()} on the {@link android.view.MenuItem}.
Figure 2. A screenshot from an action bar with two action items.
You can specify a menu item to appear as an action item in the action bar—if there is room for it—from the menu resource by declaring {@code android:showAsAction="ifRoom"} for the {@code <item>} element. This way, the item will display in the action bar for quick access only if there is room available for it—if there's not enough room, the item is placed the options menu (revealed by the drop-down icon on the right side of the action bar). From your application code, you can specify the item to appear as an action item by calling {@link android.view.MenuItem#setShowAsAction setShowAsAction()} on the {@link android.view.MenuItem} and passing {@link android.view.MenuItem#SHOW_AS_ACTION_IF_ROOM}.
If your item supplies both a title and an icon, then the action item shows only the icon by defult. If you want to include the text with the action item, add the with text flag—in XML, add {@code withText} to the {@code android:showAsAction} attribute or, in your application code, use the {@link android.view.MenuItem#SHOW_AS_ACTION_WITH_TEXT} flag when calling {@link android.view.MenuItem#setShowAsAction setShowAsAction()}. Figure 2 shows a screenshot of an action bar with two action items that include text.
Here's an example of how you can declare a menu item as an action item in a menu resource file:
<?xml version="1.0" encoding="utf-8"?>
<menu xmlns:android="http://schemas.android.com/apk/res/android">
<item android:id="@+id/menu_add"
android:icon="@drawable/ic_menu_save"
android:title="@string/menu_save"
android:showAsAction="ifRoom|withText" />
</menu>
In this case, both the {@code ifRoom} and {@code withText} flags are set, so that when this item appears as an action item, it includes the title text along with the icon.
A menu item placed in the action bar triggers the same callback methods as other items in the options menu. When the user selects an item in the action bar, your activity receives a call to {@link android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()}, passing the item ID. (If you added the item from a fragment, then the respective {@link android.app.Fragment#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} method is called for that fragment.)
Note: Even menu items that are contained in the options menu (and not shown as action items) will show an icon, so when using the action bar, you should provide an icon for every item in the options menu.
You can also declare an item to always appear as an action item, but you should avoid doing so. Most of the time, there will be enough room for several action items and they will appear in the order you declare them. If you set items to always appear as action items (instead of if room), then they are added without discrimination and there is a risk that they will collide with other elements in the action bar, such as tabs or custom views.
For more information about menus, see the Creating Menus developer guide.
By default, the application icon appears in the action bar on the left side, but does nothing when tapped. To use the application icon as an action item when tapped, you simply need to add a condition to your {@link android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} method that performs an action when the {@link android.view.MenuItem} ID is {@code android.R.id.home}. This ID is delivered every time the user taps the application icon.
For example, here's an implementation of {@link android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} that returns to the application's "home" activity:
@Override
public boolean onOptionsItemSelected(MenuItem item) {
switch (item.getItemId()) {
case android.R.id.home:
// app icon in action bar clicked; go home
Intent intent = new Intent(this, HomeActivity.class);
startActivity(intent);
break;
}
return super.onOptionsItemSelected(item);
}
Figure 3. The standard icon for the Email application (top) and the "up navigation" icon (bottom).
You can also use the application icon to provide "up" navigation. The way you handle the event when a user taps the icon is the same, but if the user experience for the event is to navigate up to the parent activity, then you should indicate this behavior by setting the action bar to "show home as up." You can do so by calling {@link android.app.ActionBar#setDisplayOptions setDisplayOptions()} on your activity's {@link android.app.ActionBar}, and passing the {@link android.app.ActionBar#DISPLAY_HOME_AS_UP} display option.
To get the {@link android.app.ActionBar}, call {@link android.app.Activity#getActionBar} from your {@link android.app.Activity} during {@link android.app.Activity#onCreate onCreate()} (but be sure you do so after you've called {@link android.app.Activity#setContentView setContentView()}).
For example, here's how you can change the action bar display mode to show the application icon as an "up" action:
@Override
protected void onStart() {
super.onStart();
ActionBar actionBar = this.getActionBar();
actionBar.setDisplayOptions(ActionBar.DISPLAY_HOME_AS_UP, ActionBar.DISPLAY_HOME_AS_UP);
}
Caution: If your activity does not have an action bar (if you did not set the theme of your activity or application to the holographic or action bar theme), then {@link android.app.Activity#getActionBar} returns null.
The action bar can display tabs that allow the user navigate between different fragments in the activity. Each tab can include a title and/or an icon.
To begin, your layout must include a {@link android.view.View} in which each {@link android.app.Fragment} associated with a tab is displayed. Be sure the view has an ID that you can use to reference it from your code.
To add tabs to the action bar:
Each callback method passes the {@link android.app.ActionBar.Tab} that received the event and a {@link android.app.FragmentTransaction} for you to perform the fragment transactions (add or remove fragments).
For example:
private class MyTabListener implements ActionBar.TabListener {
private TabContentFragment mFragment;
// Called to create an instance of the listener when adding a new tab
public TabListener(TabContentFragment fragment) {
mFragment = fragment;
}
@Override
public void onTabSelected(Tab tab, FragmentTransaction ft) {
ft.add(R.id.fragment_content, mFragment, null);
}
@Override
public void onTabUnselected(Tab tab, FragmentTransaction ft) {
ft.remove(mFragment);
}
@Override
public void onTabReselected(Tab tab, FragmentTransaction ft) {
// do nothing
}
}
This implementation of {@link android.app.ActionBar.TabListener} adds a constructor that saves the {@link android.app.Fragment} associated with a tab so that each callback can add or remove that fragment.
Tip: These methods return the same {@link android.app.ActionBar.Tab} instance, so you can chain the calls together.
For example, the following code combines steps 2 - 5 to create two tabs and add them to the action bar:
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
// setup action bar for tabs
final ActionBar actionBar = getActionBar();
actionBar.setNavigationMode(ActionBar.NAVIGATION_MODE_TABS);
// remove the activity title to make space for tabs
actionBar.setDisplayOptions(0, ActionBar.DISPLAY_SHOW_TITLE);
// instantiate fragment for the tab
Fragment artistsFragment = new ArtistsFragment();
// add a new tab and set its title text and tab listener
bar.addTab(bar.newTab().setText(R.string.tab_artists)
.setTabListener(new TabListener(artistsFragment)));
Fragment albumsFragment = new AlbumsFragment();
bar.addTab(bar.newTab().setText(R.string.tab_albums)
.setTabListener(new TabListener(albumsFragment)));
}
All the behaviors that occur when a tab is selected must be defined by your {@link android.app.ActionBar.TabListener} callback methods. When a tab is selected, it receives a call to {@link android.app.ActionBar.TabListener#onTabSelected onTabSelected()} and that's where you should add the appropriate fragment to the designated view in your layout, using {@link android.app.FragmentTransaction#add add()} with the provided {@link android.app.FragmentTransaction}. Likewise, when a tab is deselected (because another tab becomes selected), you should remove that fragment from the layout, using {@link android.app.FragmentTransaction#remove remove()}.
Note: You do not need to call {@link android.app.FragmentTransaction#commit} for these transactions. You also cannot add these fragment transactions to the back stack.
If your activity is stopped, you should retain the currently selected tab with the saved state so that when the user returns to your application, you can open the tab. When it's time to save the state, you can query the currently selected tab with {@link android.app.ActionBar#getSelectedNavigationItem()}. This returns the index position of the selected tab.
Caution: It's important that you save the state of each fragment as necessary, so when the user switches fragments with the tabs, then returns to a previous fragment, it appears the way they left. For information about saving the state of your fragment, see the Fragments developer guide.