Action Bar in Android

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.

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:

1. Create your activity by extending ActionBarActivity.
2. 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.

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

Figure 2. Action bar with three action buttons and the overflow button.

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.

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 showAsActionattribute. 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