Migrating From Version 3.x to Version 4.0

The migration path between ActionBarSherlock version 3 and version 4 is very straightforward and can be accomplished in four distinct steps: activities/fragments, imports, methods, and themes. Finally we'll found up some common 'gotchas' that detail differences in interaction between the two versions.

Activites / Fragments

All of the activities in this version are now prefixed with 'Sherlock'. Each one is named after the type of framework activity that it extends. You should be able to update the base activity of all your classes by only adding the prefix.

  • SherlockActivity extends Activity
  • SherlockListActivity extends ListActivity
  • SherlockFragmentActivity extends FragmentActivity

All of these classes are in the com.actionbarsherlock.app package.

When using SherlockFragmentActivity you should also use the 'Sherlock'-prefixed fragment classes which follow the same naming rules (e.g., SherlockFragment, SherlockListFragment).

Imports

Since the library no longer is tightly coupled with the Android support library the package has changed from being in android.support.v4 to a much more appropriate com.actionbarsherlock.

Because of this change, you will need to update all of your Sherlock-related imports in every class. Some of the key offenders are:

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

Methods

Very few APIs have actually changed between versions. There are only two which you should be aware of:

  • getSherlockActivity() in any base fragment. This returns an instance of you activity that has already been cast to SherlockFragmentActivity.
  • getSherlock() in any base activity. This will allow access to the ActionBarSherlock interface which allows for interaction with all of the features of the library. Normally you would not need access to this unless you want to programmatically set the activity's UI options.

Themes

Theming now more closely mirrors that of the native action bar and it should be much easier to now create them.

Updating your old themes consists of moving any 'ab'-prefixed theme attributes to the action bar style and any 'am'-prefixed theme attributes to the action mode style.

Themes must now also mirror their attributes to contain both the attributes with the 'android' namespace and ones without. The easiest way to show this comes from the 'Styled' example in the demos sample:

<style name="Theme.Styled" parent="Theme.Sherlock.Light.DarkActionBar">
    <item name="actionBarStyle">@style/Widget.Styled.ActionBar</item>
    <item name="android:actionBarStyle">@style/Widget.Styled.ActionBar</item>
</style>

<style name="Widget.Styled.ActionBar" parent="Widget.Sherlock.Light.ActionBar.Solid.Inverse">
    <item name="background">@drawable/bg_striped</item>
    <item name="android:background">@drawable/bg_striped</item>

    <item name="backgroundSplit">@drawable/bg_striped_split</item>
    <item name="android:backgroundSplit">@drawable/bg_striped_split</item>
</style>

Gotchas

  • If you application targets API 14 or newer in your AndroidManifest.xml the home icon will automatically be disabled. You can re-enable it to register click events by calling setHomeButtonEnabled(true). As always, the callback will have an ID of android.R.id.home.
  • If you are using list navigation pay special attention to the 'List Navigation' example in the demos sample for direction on proper use. You need to use the library-provided layouts for both the item view and dropdown view as well as use the themed context from the action bar.

Learning By Example

Since there is only so much that a guide like this can convey it is strongly recommended that you study the source code to the sample applications. They have been engineered to showcase all of the features of the action bar and their correct usage.

The samples are included in your library download in the samples/ folder. You can also always find them by going to the repository directly.

If you have any ideas for additional samples please contact Jake Wharton or send a pull request to the dev branch.