Defining The ActionBar

Overview

The ActionBar is a consistent navigation element that is standard throughout modern Android applications. The ActionBar can consist of:

• An application icon
• An application or activity-specific title
• Primary action buttons for an activity
• Consistent navigation (including tabbed UI)

Important to note that prior to 3.0, there was no ActionBar although there is a compatibility library that comes bundled that provides limited ActionBar functionality to older versions. There is also a very popular library called ActionBarSherlock which provides much better compatibility for older versions (including support for tabbed interfaces).

ActionBar Basics

Every application unless otherwise specified has an ActionBar by default. The ActionBar by default just has the application icon and an activity title.

Changing the ActionBar Icon or Title

The ActionBar icon and title displayed at the top of the screen is governed by the AndroidManifest.xml file in the application and activity nodes. In the example below, the activity "FirstActivity" will have an ActionBar with the string value of the resource identified by @string/app_name. If the value of that resource is "Foo," the string displayed in the ActionBar for this activity will be "Foo." (The description in the preceding sentences relating to the "application" node is unclear. Perhaps the author was suggesting that the android:icon attribute is relevant, but it's not clear if an android:label attribute can appear, should appear, or may not appear, nor whether the android:icon attribute must be at the top level or may also be in lower levels and what happens in such a case. It would be helpful to have a screenshot next to the XML, with arrows linking the XML fields and the resulting rendering in the screenshot.)

<application
        android:icon="@drawable/ic_launcher"
        android:label="@string/app_name"
        android:theme="@style/AppTheme">
        <activity
            android:name="com.codepath.example.simpleapp.FirstActivity"
            android:label="@string/app_name" >
        </activity>
</application>

Change the android:label or android:icon to modify the ActionBar icon or title for a given activity or for the application as a whole. Note: if you reference an icon that doesn't exist, the Eclipse Integrated Development Environment may fail with an error message that "aadt.exe" has stopped. To avoid this, follow the instructions below under "IconSet Generator" to generate your new icons before referencing them. In any Java activity, you can call getActionBar() to retrieve a reference to the ActionBar and modify or access properties. (It is not clear why one would want to do this.)

ActionBar actionBar = getActionBar();
String title = actionBar.getTitle();
actionBar.hide();

You can also change many other properties of the ActionBar not covered here. See the Extended ActionBar Guide for more details.

Adding Action Items

When you want to add primary actions to the ActionBar, you add the items to the activity context menu and if properly specified, they will automatically appear at the top.

An activity populates the action bar in its onCreateOptionsMenu() method:

public class MainActivity extends Activity {
    @Override
    public boolean onCreateOptionsMenu(Menu menu) {
        // Inflate the menu; this adds items to the action bar if it is present.
        getMenuInflater().inflate(R.menu.main, menu);
        return true;
    }
}

(The information above is incomplete. The inflate() call may return successfully but nothing is displayed. Something else is required but it isn't clear what that is: changes to the manifest.xml file, changes to Eclipse project settings, or something else.)

Entries in the action bar are typically called actions. Use this method to inflate a menu resource that defines all the action items within a res/menu xml file, as shown in the example below. Do not copy the example below into your own code unless the icon referred to, "@drawable/ic_compose," exists, or you will cause the "aadt.exe" error message described above. Do not copy the code into your own code unless you have defined a Java method to receive the onClick event, "onComposeAction" or your program will fail with an exception caused by the missing method. You would define this method in the Activity file. For the example below, a minimal declaration would be "public void onComposeAction(MenuItem menuItem) { }."

<menu xmlns:android="http://schemas.android.com/apk/res/android" >
    <item
        android:id="@+id/miCompose"
        android:icon="@drawable/ic_compose"
        android:onClick="onComposeAction"
        android:showAsAction="ifRoom"
        android:title="Compose">
    </item>
    <item
        android:id="@+id/miProfile"
        android:icon="@drawable/ic_profile"
        android:onClick="onProfileView"
        android:showAsAction="ifRoom|withText"
        android:title="Profile">
    </item>
</menu>

Notice that to request that an item appear directly in the action bar as an action button, include showAsAction="ifRoom" in the <item> tag. If there's not enough room for the item in the action bar, it will appear in the action overflow. If withText is specified as well (as in the second item), the text will be displayed with the icon.

Note: To generate ActionBar icons, be sure to use the IconSet Generator to create the icons. Follow this step-by-step guide to generate icons by selecting File => New => Other => Android => Android Icon Set.

Handling ActionBar Clicks

There are two ways to handle the click for an ActionBar item. (It is not clear why there are two ways or how to choose which one to use.) First, you can use the android:onClick handler in the menu XML, similar to handling button clicks:

<menu xmlns:android="http://schemas.android.com/apk/res/android" >
    <item
        android:id="@+id/item1"
        android:icon="@drawable/ic_compose"
        android:onClick="onComposeAction"
        android:showAsAction="ifRoom"
        android:title="Compose">
    </item>
</menu>

and then define the method onComposeAction in the parent activity. Note that you must define the method before attempting to run the application or an exception will be thrown for the missing method--the error is detected at runtime, not within the Eclipse Integrated Development Environment.

public class MainActivity extends Activity {
  public void onComposeAction(MenuItem mi) {
     // handle click here
  }
}

The second way is to use the 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 tag's id attribute so you can perform the appropriate action:

@Override
public boolean onOptionsItemSelected(MenuItem item) {
    // Handle presses on the action bar items
    switch (item.getItemId()) {
        case R.id.miCompose:
            composeMessage();
            return true;
        case R.id.miProfile:
            showProfileView();
            return true;
        default:
            return super.onOptionsItemSelected(item);
    }
}

and then you can handle all the action buttons in this single method.

References

• http://developer.android.com/guide/topics/ui/actionbar.html
• http://developer.android.com/design/patterns/actionbar.html
• http://developer.android.com/reference/android/app/ActionBar.html
• http://www.vogella.com/articles/AndroidActionBar/article.html
• http://jgilfelt.github.io/android-actionbarstylegenerator