docs/html/sdk/compatibility-library.jd

page.title=Compatibility Package

@jd:body

<div id="qv-wrapper">
<div id="qv">
  
<h2>In this document</h2>
<ol>
  <li><a href="#Notes">Revisions</a></li>
  <li><a href="#Downloading">Downloading the Compatibility Package</a></li>
  <li><a href="#SettingUp">Setting Up a Project to Use a Library</a></li>
  <li><a href="#Using">Using the v4 Library APIs</a></li>
  <li><a href="#Docs">Reference Docs</a></li>
  <li><a href="#Samples">Samples</a></li>
</ol>

<h2>See also</h2>
<ol>
  <li><a
href="{@docRoot}guide/practices/optimizing-for-3.0.html">Optimizing Apps for Android 3.0</a></li>
  <li><a href="http://code.google.com/p/iosched/">Google I/O App source code</a></li>
</ol>

</div>
</div>

<p><em>Minimum API level supported:</em> <b>4</b></p>

<p>The Compatibility Package includes static "support libraries" that you can add to your Android
application in order to use APIs that are either not available for older platform versions or that
offer "utility" APIs that aren't a part of the framework APIs. The goal is to simplify your
development by offering more APIs that you can bundle with your application so you can
worry less about platform versions.</p>

<p class="note"><strong>Note:</strong> The Compatibility Package includes more than one support
library. Each one has a different <em>minimum API level</em>. For example, one library requires API
level 4 or higher, while another requires API level 13 or higher. The minimum version is indicated
by the directory name, such as {@code v4/} and {@code v13/}.</p>


<h2 id="Notes">Revisions</h2>

<p>The sections below provide notes about successive releases of
the Compatibility Package, as denoted by revision number.</p>


<div class="toggle-content open">

  <p><a href="#" onclick="return toggleContent(this)">
    <img src="{@docRoot}assets/images/triangle-opened.png" class="toggle-content-img" />
    Compatibility Package, revision 3 (July 2011)
  </a></p>

  <div class="toggle-content-toggleme" style="padding-left:2em"> 
    <dl>
      <dt>Changes for v4 support library:</dt>
      <dd>
        <ul>
          <li>Adds support for {@link android.app.Fragment.SavedState}</li>
          <li>Adds {@code MotionEventCompat} to support newer {@link
android.view.MotionEvent} APIs</li>
          <li>Adds {@code VelocityTrackerCompat} to support a newer {@link
android.view.VelocityTracker} APIs</li>
          <li>Adds {@code ViewConfigurationCompat} to support a newer {@link
android.view.ViewConfiguration} APIs</li>
          <li>All new APIs (available only in the support library) that allow you to create UIs
with horizontal paging, allowing users to swipe left and right between content views. Classes to
support this include:
            <ul>
              <li>{@code ViewPager}: A {@link android.view.ViewGroup} that manages the
layout for the child views, which the user can swipe between.</li>
              <li>{@code PagerAdapter}: An adapter that populates the {@code ViewPager} with the
views that represent each page.</li>
              <li>{@code FragmentPagerAdapter}: An extension of {@code PagerAdapter} for flipping
between fragments.</li>
              <li>{@code FragmentStatePagerAdapter}: An extension of {@code PagerAdapter} for
flipping between fragments that uses the library's support for {@link
android.app.Fragment.SavedState}.</li>
            </ul>
          </li>
        </ul>
      </dd>
      <dt>New v13 support library:</dt>
      <dd>
        <ul>
          <li>Includes the {@code FragmentPagerAdapter} and {@code FragmentStatePagerAdapter}
to support the horizontal paging.
          <p>These are exactly the same as the APIs added to the v4 support library, but rely on
other platform components in Android 3.2. Use this library instead of v4 if you're developing for
Android 3.2 and higher (all other APIs in the v4 library are already available with API level
13).</p>
          </li>
        </ul>
      </dd>
    </dl>
  </div>

</div>


<div class="toggle-content closed">

  <p><a href="#" onclick="return toggleContent(this)">
    <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" />
    Compatibility Package, revision 2 (May 2011)
  </a></p>

  <div class="toggle-content-toggleme" style="padding-left:2em"> 
    <dl>
    <dt>Changes for v4 library:</dt>
    <dd>
      <ul>
        <li>Support for fragment animations</li>
        <li>Fix {@code Fragment.onActivityResult()} bug</li>
      </ul>
    </dd>
    </dl>
  </div>

</div>


<div class="toggle-content closed">

  <p><a href="#" onclick="return toggleContent(this)">
    <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" />
    Compatibility Package, revision 1 (March 2011)
  </a></p>

  <div class="toggle-content-toggleme" style="padding-left:2em"> 
      <p>Initial release with the v4 library.</p>
  </div>

</div>



<h2 id="Downloading">Downloading the Compatibility Package</h2>

<p>The Compatibility Package is provided as a downloadable package from the Android SDK and AVD
Manager. To install:</p>

<ol>
  <li>Launch the SDK and AVD Manager. 
    <p>From Eclipse, you can select <strong>Window</strong>
&gt; <strong>Android SDK and AVD Manager</strong>. Or, launch {@code SDK Manager.exe} from
the {@code &lt;sdk&gt;/} directory (on Windows only) or {@code android} from the {@code
&lt;sdk&gt;/tools/} directory.</p></li>
  <li>Expand the Android Repository, check <strong>Android Compatibility package</strong>
and click <strong>Install selected</strong>.</li>
  <li>Proceed to install the package.</li>
</ol>

<p>When done, all files (including source code, samples, and the {@code .jar} files) are saved
into the <code>&lt;sdk&gt;/extras/android/compatibility/</code> directory. This directory contains
each of the different support libraries, such as the library for API level 4 and up and the library
for API level 13 and up, each named with the respective version (such as {@code v4/}).</p>


<h2 id="SettingUp">Setting Up a Project to Use a Library</h2>

<p>To add one of the libraries to your Android project:</p>
<ol>
  <li>In your Android project, create a directory named {@code libs} at the root of your
project (next to {@code src/}, {@code res/}, etc.)</li>
  <li>Locate the JAR file for the library you want to use and copy it into the {@code
libs/} directory.
    <p>For example, the library that supports API level 4 and up is located at {@code
&lt;sdk&gt;/extras/android/compatibility/v4/android-support-v4.jar}.</p>
  </li>
  <li>Add the JAR to your project build path. 
    <p>In Eclipse, right-click the JAR file in the Package Explorer, select <strong>Build
Path</strong> &gt; <strong>Add to Build Path</strong>. You should then see the JAR file appear in a
new directory called Referenced Libraries.</p>
  </li>
</ol>

<p>Your application is now ready to use the library APIs. All the
provided APIs are available in the {@code android.support} package (for
example, {@code android.support.v4}).</p>

<p class="note"><strong>Tip:</strong> To see the library APIs in action, take a look at the sample
apps in {@code extras/android/compatibility/&lt;version&gt;/samples/}.</p>

<p class="warning"><strong>Warning:</strong> Be certain that you not confuse the standard
{@code android} packages with those in {@code android.support} library. Some code completion tools
might
get this wrong, especially if you're building against recent versions of the platform. To be safe,
keep your build target set to the same version as you have defined for your <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a>
and double check the import statements for classes that also exist in the support library, such as
{@code SimpleCursorAdapter}.</p>


<h2 id="Using">Using the v4 Library APIs</h2>

<p>The support library for v4 provides access to several classes introduced with Android 3.0 and
beyond, plus some updated version of existing classes, and even some APIs that currently don't
exist in the Android platform. Some of the most useful and notable classes that have
counterparts in the v4 support library are:</p>

<ul>
  <li>{@link android.app.Fragment}</li>
  <li>{@link android.app.FragmentManager}</li>
  <li>{@link android.app.FragmentTransaction}</li>
  <li>{@link android.app.ListFragment}</li>
  <li>{@link android.app.DialogFragment}</li>
  <li>{@link android.app.LoaderManager}</li>
  <li>{@link android.content.Loader}</li>
  <li>{@link android.content.AsyncTaskLoader}</li>
  <li>{@link android.content.CursorLoader}</li>
</ul>

<p>For each of the classes above (and others not listed), the APIs work almost exactly the same
as the counterparts in the latest Android platform. Thus, you can usually refer to
the online documentation for information about the supported APIs. There are some
differences, however. Most notably:</p>

<ul>
  <li>When creating an activity to use fragments, you must declare your activity to extend the
{@code FragmentActivity} class (instead of the traditional {@link android.app.Activity}
class).</li>
  <li>To manage your fragments and loaders, you must use the methods {@code
FragmentActivity.getSupportFragmentManager()} and {@code
FragmentActivity.getSupportLoaderManager()} (instead of the {@link
android.app.Activity#getFragmentManager()} and {@link android.app.Activity#getLoaderManager()}
methods).</li>
  <li>The {@link android.app.ActionBar} is <strong>not supported</strong> by the library.
However, when creating your <a href="{@docRoot}guide/topics/ui/menus.html#options-menu">Options
Menu</a>, you can declare which items should be added to the Action Bar when it's available (on
Android 3.0 or later). You can do so with the {@code MenuCompat.setShowAsAction()} method. For
example:
<pre>
public boolean onCreateOptionsMenu(Menu menu) {
    MenuInflater inflater = getMenuInflater();
    inflater.inflate(R.menu.options, menu);
    MenuCompat.setShowAsAction(menu.findItem(R.id.action_search), 1);
    return true;
}
</pre>
</li>
</ul>

<div class="note"><p><strong>Tip:</strong> To enable the Holographic theme on devices
running Android 3.0 or higher, declare in your manifest file that your application targets
API level 11. For example:</p>
<pre>
&lt;uses-sdk android:minSdkVersion="4" android:targetSdkVersion="11" /&gt;
</pre>
<p>This way, your application automatically receives the Holographic theme and the Action Bar for 
each activity when running on Android 3.0 and higher.</p>
</div>

<p>For more information about how you can optimize your application for the latest
Android-powered devices, read <a href="{@docRoot}guide/practices/optimizing-for-3.0.html">Optimizing
Apps for Android 3.0</a>.</p>


<h2 id="Docs">Reference Docs</h2>

<p>The libraries currently do not provide reference documentation for the included APIs. To generate
your own set using the {@code javadoc} tool, perform the following from a command (as appropriate
for the library version you're using). In this example, documentation is generated for the v4
library:</p>

<pre class="no-pretty-print">
cd &lt;sdk&gt;/extras/android/compatibility/v4/
mkdir docs
javadoc -sourcepath src/java/ -subpackages android.support.v4 -d docs
</pre>
<p>Open the {@code docs/index.html} file to begin browsing the generated documentation.</p>


<h2 id="Samples">Samples</h2>

<p>If you want to see some code that uses the support libraries, samples are included with the
Compatibility Package, inside each support library directory. For example, at {@code
extras/android/compatibility/v4/samples/}.</p>

<p>Additionally, the <a href="http://code.google.com/p/iosched/">Google I/O App</a> is a complete
application that uses the v4 support library to provide a single APK for both handsets and tablets
and also demonstrates some of Android's best practices in Android UI design.</p>