Support Library

In this document

Revisions
Downloading the Support Package
Setting Up a Project to Use a Library
Using the v4 Library APIs
Reference Docs
Samples

Revisions

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

Support Package, revision 9 (June 2012)

Changes for v4 support library:

User Interface Support
- Added PagerTabStrip support, providing enhanced functionality beyond PagerTitleStrip.
- Fixed various bugs for PagerTitleStrip and PagerTabStrip, including setAllCaps option, title alignment, appearance improvements, minimum width constraints and touch navigation issues.
- Added support for ViewPager page gutters, which helps the ViewPager class provide paging support for content with a large horizontal scroll range, such as a map.
- Fixed numerous bugs for ViewPager, including size and data set change problems, page positioning, user interaction, scroll tracking and keyboard navigation problems.
- Fixed many bugs for Fragment, including proper handling of onActivityResult() when the target fragment no longer exists, dispatching selection events to invisible fragments, improved FragmentTransaction.replace() behavior and added better state handling for fragments being moved out of view.
- Added support for the postOnAnimation() method in ViewCompat.
- Updated NavUtils to use Android 4.1 (API level 16) Up navigation functionality when available.
Accessibility
- Updated accessibility support classes, including AccessibilityNodeInfoCompat, to follow fixes made in Android 4.1 (API level 16).
- Added support for accessibility scroll actions in ViewPager.
General improvements
- Updated TaskStackBuilder to reflect API changes in Android 4.1 (API level 16).
- Enhanced TaskStackBuilder to allow it to be used from a Service.
- Added support for EXTRA_HTML_TEXT to ShareCompat.
- Updated NotificationCompat.Builder to support the setNumber() method.
- Added support in ConnectivityManagerCompat for the isActiveNetworkMetered() method.

Support Package, revision 8 (April 2012)

Changes for v4 support library:

Fixed intent flags for PendingIntent objects generated by TaskStackBuilder.
Removed unused attributes from the gridlayout library projects to make sure the library can be built with API Level 7 and higher.
Added .classpath and .project files for the gridlayout library project.

Support Package, revision 7 (March 2012)

Changes for v4 support library:

Added ShareCompat, which provides helper classes for sending and receiving content for social sharing applications, including new metadata for attributing shared data to the source app. This class also provides compatible integration with the new ShareActionProvider in Android 4.0.
Added NavUtils and TaskStackBuilder to provide support for implementing the Android Design guidelines for navigation. These additions include a way to implement the action bar's Up button across versions. For an example implementation of this pattern, see the AppNavigation sample in (<sdk>/samples/<platform>/AppNavigation).
Added NotificationCompat.Builder to provide a compatibility implementation of Android 3.0's Notification.Builder helper class for creating standardized system notifications.

Support Package, revision 6 (December 2011)

Note: Reference for support library APIs are now available with the framework references, for example: android.support.v4.app.

Changes for v4 support library:

Changes to ViewPager:
- Added extra decorative view support for ViewPager. Decorative views may be supplied as child views of a pager in XML layout.
- Added PagerAdapter.getPageTitle() to supply title strings for pages, which defaults to no title for each page.
- Added PagerTitleStrip, a non-interactive title strip, that can be added as a child of ViewPager. Developers can supply text appearance and color, as well as layout sizing and gravity information.
- Updated PagerAdapter methods to take ViewGroup objects, rather than View to avoid class casting in adapter implementations.
- Updated ViewPager to use Launcher-style fling behavior.
- Bug fixes for user interface interaction and test automation.
Support for Fragments:
- Changed setStartDeferred() method to setUserVisibleHint(boolean).
- Added deferred start for off-screen pages to improve performance.
Support for Accessiblity APIs:
- Updated AccessibilityDelegateCompat methods to return empty lists instead of null.
- Added new APIs needed by the v4 samples.

Support Package, revision 5 (December 2011)

Changes for v4 support library:

Support for Accessiblity APIs:
- Added AccessibilityDelegateCompat to support View.AccessibilityDelegate.
- Added AccessibilityEventCompat to support AccessibilityEvent.
- Added AccessibilityManagerCompat to support AccessibilityManager.
- Added AccessibilityNodeInfoCompat to support AccessibilityNodeInfo.
- Added AccessibilityRecordCompat to support AccessibilityRecord.
- Added AccessibilityServiceInfoCompat to support AccessibilityServiceInfo.
- Added ViewGroupCompat to support accessibility features in ViewGroup.
- Modified ViewCompat to support accessibility features in View.
Changes to ViewPager:
- Added support for margins between pages. An optional Drawable can be provided to fill the margins.
- Added support for EdgeEffect.
- Added support for keyboard navigation
- Added support to control how many pages are kept to either side of the current page.
- Improved touch physics.
- Bug fixes for user interface behavior.

Support Package, revision 4 (October 2011)

Changes for v4 support library:

Added EdgeEffectCompat to support EdgeEffect.
Added LocalBroadcastManager to allow applications to easily register for and receive intents within a single application without broadcasting them globally.
Added support in ViewCompat to check for and set overscroll modes for Views on Android 2.3 and later.
Changes to Fragment APIs:
- Added new APIs to control the visibility of new menus.
- Added custom animation APIs.
- Added APIs in FragmentActivity to retain custom, non-configuration instance data.
- Various bug fixes.
Fixed a Loader bug that caused issues in canceling AsyncTasks when running on Froyo and older versions of the platform. The support code now uses its own version of AsyncTask to keep the same behavior on all platform versions.

Compatibility Package, revision 3 (July 2011)

Changes for v4 support library:

Adds support for Fragment.SavedState
Adds MotionEventCompat to support newer MotionEvent APIs
Adds VelocityTrackerCompat to support a newer VelocityTracker APIs
Adds ViewConfigurationCompat to support a newer ViewConfiguration APIs
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:
- ViewPager: A ViewGroup that manages the layout for the child views, which the user can swipe between.
- PagerAdapter: An adapter that populates the ViewPager with the views that represent each page.
- FragmentPagerAdapter: An extension of PagerAdapter for flipping between fragments.
- FragmentStatePagerAdapter: An extension of PagerAdapter for flipping between fragments that uses the library's support for Fragment.SavedState.

New v13 support library:

Includes the FragmentPagerAdapter and FragmentStatePagerAdapter to support the horizontal paging.
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).

Compatibility Package, revision 2 (May 2011)

Changes for v4 library:

Support for fragment animations
Fix android.support.v4.app.Fragment#onActivityResult Fragment.onActivityResult() bug

Compatibility Package, revision 1 (March 2011)

Initial release with the v4 library.

Downloading the Support Package

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

Launch the Android SDK Manager.
From Eclipse, you can select Window > Android SDK Manager. Or, launch SDK Manager.exe from the <sdk>/ directory (on Windows only) or android from the <sdk>/tools/ directory.
Expand the Android Repository, check Android Support package and click Install selected.
Proceed to install the package.

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

In your Android project, create a directory named libs at the root of your project (next to src/, res/, etc.)
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/support/v4/android-support-v4.jar.
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.

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 <sdk>/extras/android/support/<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:

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;
}
```
Also see the Action Bar Compatibility sample for a demonstration of how to use ActionBar on Android 3.0+ and also support action bar functionality on older versions.

Tip: 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:

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

This way, your application automatically receives the Holographic theme and the Action Bar for each activity when running on Android 3.0 and higher.

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 reference documentation for the Support Packages is included as part of the Android online developer documentation:

Samples

If you want to see some code that uses the support libraries, samples are included with the Support Package, inside each support library directory, for example; <sdk>/extras/android/support/v4/samples/. You can also view these samples as part of the Android online developer documentation:

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.

Results

In this document

See also

Revisions

Downloading the Support Package

Setting Up a Project to Use a Library

Using the v4 Library APIs

Reference Docs

Samples