Usage

Sticking with the theme of the official compatibility library, ActionBarSherlock aims to allow the use of the action bar design pattern by mimicking the experience that would be found natively on Android Ice Cream Sandwich with as little effort as required.

Requirements

Due to its use of the native action bar and its related classes on Ice Cream Sandwich, the library requires that both it and your project are compiled with Android 4.0 or newer. The project also requires that you are compiling with JDK 1.6 in both your editor and any build systems that you may be using.

Since the library is an extension of the official support library you must also have the android-support-v4.jar referenced by your project.

Including In Your Project

There are a few ways to leverage ActionBarSherlock in your projects:

  1. If you’re using the Eclipse Development Environment with the ADT plugin version 0.9.7 or greater you can include ActionBarSherlock as a library project. Create a new Android project in Eclipse using the actionbarsherlock/ folder as the existing source. Then, in your project properties, add the created project under the ‘Libraries’ section of the ‘Android’ category.

  2. If you use ant to compile from the command line you will need to run android update project -p . inside the actionbarsherlock/ folder of the project. Once completed, you can reference the actionbarsherlock/ folder of ActionBarSherlock from your application's project.properties file. For more information please see the Android developer guide for referencing library projects.

  3. If you use maven to build your Android project you can simply add a dependency for this library.

    <dependency>
      <groupId>com.actionbarsherlock</groupId>
      <artifactId>actionbarsherlock</artifactId>
      <version>4.1.0</version>
      <type>apklib</type>
    </dependency>
    
  4. If you use gradle to build your Android project, you must manually specify the packaging type of 'aar' and the support library dependency:

    dependencies {
      compile 'com.actionbarsherlock:actionbarsherlock:4.4.0@aar'
      compile 'com.android.support:support-v4:18.0.+'
    }
    

Action Bar API

When creating an activity to use the action bar on all versions of Android, you must declare your activity to extend any of the activity classes that start with 'Sherlock' (e.g., SherlockActivity, SherlockFragmentActivity). Interaction with the action bar is handled by calling getSupportActionBar() (instead of getActionBar()).

The API exposed by the ActionBar instance is an exact duplicate of that which the native method exposes. Refer to its documentation as well as the articles on how to utilize its functionality in the "Related Links" section.

NOTE: When using SherlockFragmentActivity there are also 'Sherlock'-prefixed fragment classes which you should use to ensure proper functionality (e.g. SherlockFragment, SherlockListFragment). The activity will still function with the normal fragment classes but you will not be able to use any of the menu-related methods.

Required Theming

Since the action bar widget is very complex it requires a set of default themes. The library provides three core themes—one of which must be applied to each activity on which you want the action bar present.

See the theming page for more information.

Imports

In order to provide functionality that was not available on version of Android prior to 3.0, the library includes and uses a lot of classes that are named the same as their native counterparts. The three most common are:

In order to provide functionality that was not available on version of Android prior to 3.0, the library includes and uses a lot of classes that are named the same as their native counterparts. The most common of these are:

  • com.actionbarsherlock.app.ActionBar
  • com.actionbarsherlock.view.Menu
  • com.actionbarsherlock.view.MenuItem
  • com.actionbarsherlock.view.MenuInflater

It is important to ensure that you are using these types where appropriate since they contain the additional functionality required to support the action bar.

NOTE: The majority of errors regarding the @Override-ing of methods from the activities are a result of using the incorrect imports. All of the classes which exist in the com.actionbarsherlock.* package whose names match that of a native class extend from that native class and as such can be used in their place.

NOTE: In order to inflate your menu from XML you should call getSupportMenuInflater() in your activities. The fragment callbacks will already have an instance of the inflater as an argument.

See Also...

This library was meant to be as behind-the-scenes as possible and require a minimal amount of changes to support. The core usage of the action bar itself is no different than if you were interacting with the native action bar.

Be sure to also visit the following pages:

Related Links

The following links are useful information on how to operate the native action bar. Other than the small tweaks mentioned on this page, the entire API is exactly the same.

Class APIs

ActionBar
Main API for nearly all interaction with the action bar. This is the exact API getSupportActionBar() exposes.
Fragment
New fundamental building block of layouts which enable you to provide rich experiences on a range of different devices without code duplication.

Articles

Using the ActionBar
Broad introduction on the action bar design paradigm, the API, and common use cases.
Creating Menus
Menus drive the action bar's items.
Using the Compatibility Libary
ActionBarSherlock is a superset of the official compatibility library. All features in the Google library are also available for use through this library.
Fragments
Introduction to utilizing this new modularized view and its lifecycle.