---
title: Usage
layout: default
---


<div class="row">
	<div class="three-fourths">
		<h1>Usage</h1>
		<p>Sticking with the theme of the official compatability library, ActionBarSherlock aims to allow the use of the action bar design pattern by mimicking the experience that would be found natively on Android 3.0+ with as little effort as required.</p>

		<h3>Requirements</h3>
		<p>All of the requirements of implementing the compatability libary are present in this library. If you are unfamiliar with them please read its &quot;<a href="http://developer.android.com/sdk/compatibility-library.html#Using">Using Some of the Library APIs</a>&quot; guide.</p>
		<p><strong>The only additional requirement that ActionBarSherlock imposes is that any activity on which you would like the action bar attached define a theme in the manifest that is either one of the two provided or be a custom theme whose parent is one of the two provided. See the <a href="theming.html">theming page</a> for more details on implementing this.</strong></p>

		<h3>Action Bar API</h3>
		<p>When creating an activity to use the action bar on all versions of Android, you must declare your activity to extend the <code>FragmentActivity</code> class (instead of the traditional <a href="http://developer.android.com/reference/android/app/Activity.html"><code>Activity</code></a> class). Interaction with the action bar is handled by calling <code>FragmentActivity.getSupportActionBar()</code> (instead of <a href="http://developer.android.com/reference/android/app/Activity.html#getActionBar()"><code>getActionBar()</code></a>).</p>
		<p>The API exposed by the <code>ActionBar</code> instance is an exact duplicate of <a href="http://developer.android.com/reference/android/app/ActionBar.html">that which the native method exposes</a>. Refer to its documentation as well as the articles on how to utilize its functionality in the &quot;Related Links&quot; section.</p>

		<h3>Imports</h3>
		<p>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:</p>
		<ul>
			<li><code>android.support.v4.app.ActionBar</code></li>
			<li><code>android.support.v4.view.Menu</code></li>
			<li><code>android.support.v4.view.MenuItem</code></li>
		</ul>
		<p>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.</p>
		<p><strong>NOTE</strong>: The majority of errors regarding the <code>@Override</code>-ing of methods from <code>FragmentActivity</code> are a result of using the incorrect imports. All of the classes which exist in the <code>android.support.v4</code> package whose names match that of a native class extend from that native class and as such can be used in their place.</p>

		<!--TODO: Display Differences -->

		<h3>Including In Your Project</h3>
		<p>For details on including the library in your application please see the <a href="download.html">download</a> page.</p>

		<h3>See Also...</h3>
		<p>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.</p>
		<p>Be sure to also visit the following pages:</p>
		<ul>
			<li><a href="theming.html">Theming</a></li>
			<li><a href="samples.html">Samples</a></li>
			<li><a href="faq.html">Frequently Asked Questions</a></li>
		</ul>
	</div>
	<div class="fourth last">
		<h1>Related Links</h1>
		<p>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.</p>

		<h3>Class APIs</h3>
		<dl>
			<dt><a href="http://developer.android.com/reference/android/app/ActionBar.html">ActionBar</a></dt>
			<dd>Main API for nearly all interaction with the action bar. <strong>This is the exact API <code>getSupportActionBar()</code> exposes.</strong></dd>
			<dt><a href="http://developer.android.com/reference/android/app/Fragment.html">Fragment</a></dt>
			<dd>New fundamental building block of layouts which enable your to provide rich experiences on a range of different devices without code duplication.</dd>
		</dl>

		<h3>Articles</h3>
		<dl>
			<dt><a href="http://developer.android.com/guide/topics/ui/actionbar.html">Using the ActionBar</a></dt>
			<dd>Broad introduction on the action bar design paradign, the API, and common use cases.</dd>
			<dt><a href="http://developer.android.com/guide/topics/ui/menus.html">Creating Menus</a></dt>
			<dd>Menus drive the action bar's items.</dd>
			<dt><a href="http://developer.android.com/sdk/compatibility-library.html#Using">Using the Compatability Libary</a></dt>
			<dd>ActionBarSherlock is a superset of the official compatability library. All features in the Google library are also available for use through this library.</dd>
			<dt><a href="http://developer.android.com/guide/topics/fundamentals/fragments.html">Fragments</a></dt>
			<dd>Introduction to utilizing this new modularized view and its lifecycle.</dd>
		</dl>
	</div>
</div>