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