Compatibility Package

Minimum API level supported: 4

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.

Note: The Compatibility Package includes more than one support library. Each one has a different minimum API level. 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 v4/ and v13/.

Revisions

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

Downloading the Compatibility Package

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

1. Launch the SDK and AVD Manager.

   From Eclipse, you can select Window > Android SDK and AVD Manager. Or, launch SDK Manager.exe from the <sdk>/ directory (on Windows only) or android from the <sdk>/tools/ directory.

2. Expand the Android Repository, check Android Compatibility package and click Install selected.
3. Proceed to install the package.

When done, all files (including source code, samples, and the .jar files) are saved into the <sdk>/extras/android/compatibility/ 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 v4/).

Setting Up a Project to Use a Library

To add one of the libraries to your Android project:

1. In your Android project, create a directory named libs at the root of your project (next to src/, res/, etc.)
2. Locate the JAR file for the library you want to use and copy it into the libs/ directory.

   For example, the library that supports API level 4 and up is located at <sdk>/extras/android/compatibility/v4/android-support-v4.jar.

3. Add the JAR to your project build path.

   In Eclipse, right-click the JAR file in the Package Explorer, select Build Path > Add to Build Path. You should then see the JAR file appear in a new directory called Referenced Libraries.

Your application is now ready to use the library APIs. All the provided APIs are available in the android.support package (for example, android.support.v4).

Tip: To see the library APIs in action, take a look at the sample apps in extras/android/compatibility/<version>/samples/.

Warning: Be certain that you not confuse the standard android packages with those in 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 android:minSdkVersion and double check the import statements for classes that also exist in the support library, such as SimpleCursorAdapter.

Using the v4 Library APIs

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:

• Fragment
• FragmentManager
• FragmentTransaction
• ListFragment
• DialogFragment
• LoaderManager
• Loader
• AsyncTaskLoader
• CursorLoader

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:

• When creating an activity to use fragments, you must declare your activity to extend the FragmentActivity class (instead of the traditional Activity class).
• To manage your fragments and loaders, you must use the methods FragmentActivity.getSupportFragmentManager() and FragmentActivity.getSupportLoaderManager() (instead of the getFragmentManager() and getLoaderManager() methods).
• The ActionBar is not supported by the library. However, when creating your Options Menu, 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 MenuCompat.setShowAsAction() method. For example:

  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;
  }
  

<uses-sdk android:minSdkVersion="4" android:targetSdkVersion="11" />

For more information about how you can optimize your application for the latest Android-powered devices, read Optimizing Apps for Android 3.0.

Reference Docs

The libraries currently do not provide reference documentation for the included APIs. To generate your own set using the 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:

cd <sdk>/extras/android/compatibility/v4/
mkdir docs
javadoc -sourcepath src/java/ -subpackages android.support.v4 -d docs

Open the docs/index.html file to begin browsing the generated documentation.

Samples

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 extras/android/compatibility/v4/samples/.

Additionally, the Google I/O App 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.