From 5ffbba6455298593a59aeb98fafd0e0ede25b2c8 Mon Sep 17 00:00:00 2001 From: Joe Fernandez Date: Mon, 15 Jul 2013 15:53:03 -0700 Subject: docs: Support Library Guide Extending the Support Library documentation to explain how to support mainstream features such as ActionBar across multiple versions of Android. Change-Id: I8ddeeb912884a39b2fb8717129d22993102ef650 --- .../html/images/tools/sdk-manager-support-libs.png | Bin 0 -> 53798 bytes docs/html/tools/extras/support-library.jd | 742 --------------------- docs/html/tools/support-library/features.jd | 249 +++++++ docs/html/tools/support-library/index.jd | 659 ++++++++++++++++++ docs/html/tools/support-library/setup.jd | 308 +++++++++ docs/html/tools/tools_toc.cs | 35 +- 6 files changed, 1235 insertions(+), 758 deletions(-) create mode 100644 docs/html/images/tools/sdk-manager-support-libs.png delete mode 100644 docs/html/tools/extras/support-library.jd create mode 100644 docs/html/tools/support-library/features.jd create mode 100644 docs/html/tools/support-library/index.jd create mode 100644 docs/html/tools/support-library/setup.jd (limited to 'docs/html') diff --git a/docs/html/images/tools/sdk-manager-support-libs.png b/docs/html/images/tools/sdk-manager-support-libs.png new file mode 100644 index 000000000000..37968005c789 Binary files /dev/null and b/docs/html/images/tools/sdk-manager-support-libs.png differ diff --git a/docs/html/tools/extras/support-library.jd b/docs/html/tools/extras/support-library.jd deleted file mode 100644 index a82a98ae4eba..000000000000 --- a/docs/html/tools/extras/support-library.jd +++ /dev/null @@ -1,742 +0,0 @@ -page.title=Support Library - -@jd:body - -
- -
- -

Minimum API level supported: 4

- -

The Support 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 Support 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 (v13 is a superset of v4 and -includes additional -support classes to work with v13 APIs). The minimum version is indicated -by the directory name, such as {@code v4/} and {@code v13/}.

- - -

Revisions

- -

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

- -
-

- Support Package, revision 13 (May 2013) -

-
-
-
Changes for v4 support library:
-
-
    -
  • Added {@link android.support.v4.widget.DrawerLayout} for creating a - Navigation - Drawer that can be pulled in from the edge of a window.
    • -
  • Added {@link android.support.v4.widget.SlidingPaneLayout} widget for creating linked - summary and detail views that appropriately adapt to various screen sizes.
    • -
  • Added {@link android.support.v4.app.ActionBarDrawerToggle} as a way to tie - together the functions of {@link android.support.v4.widget.DrawerLayout} and {@link - android.app.ActionBar}.
    • -
  • Added {@link android.support.v4.widget.ViewDragHelper} as a new common component - for dragging views within a parent view.
    • -
  • Added {@link android.support.v4.widget.ScrollerCompat} to provide {@link - android.widget.Scroller} and {@link android.widget.OverScroller} compatibility support. -
    • -
  • Added {@link android.support.v4.content.FileProvider} to allow sharing of private - files between applications.
    • -
  • Updated {@link android.support.v4.view.ViewPager} to throw an exception if the - associated {@link android.support.v4.view.PagerAdapter} class is modified without a call - to {@link android.support.v4.view.PagerAdapter#notifyDataSetChanged notifyDataSetChanged()}. -
    • -
  • Fixed an issue with {@link android.support.v4.view.ViewPager} children drawing sort - order.
    • -
  • Fixed {@link android.support.v4.view.GestureDetectorCompat} to dispatch missing - {@link android.view.GestureDetector.SimpleOnGestureListener#onSingleTapConfirmed} calls - between tap timeout and long press events.
    • -
-
-
-
-
- - -
-

- Support Package, revision 12 (February 2013) -

-
-
-
Changes for v4 support library:
-
-
    -
  • Improved interaction behavior for {@link android.support.v4.view.ViewPager}.
    • -
  • Fixed a bug that could cause {@link android.support.v4.view.ViewPager} to select the - wrong page.
    • -
  • Fixed use of {@link android.support.v4.view.ViewPager#removeView removeView()} method - during layout for {@link android.support.v4.view.ViewPager}.
    • -
  • Fixed issue with {@link android.support.v4.widget.SearchViewCompat} where using the - back button to dismiss does not clear the search text. This fix only applies to - host API levels 14 and higher.
    • -
-
-
-
-
- -
-

- Support Package, revision 11 (November 2012) -

-
-
-
Changes for v4 support library:
-
-
    -
  • User Interface -
      -
    • Added support for nested {@link android.support.v4.app.Fragment} classes.
      • -
    • Added improvements to {@link android.support.v4.app.FragmentManager} debugging. -
      • -
    • Fixed problem in {@link android.support.v4.app.FragmentTabHost} where fragment - and tab interaction could result in a {@link android.widget.ListView} state loss. -
      • -
    • Fixed issue with user-visible hint in - {@link android.support.v4.app.FragmentStatePagerAdapter}.
      • -
    • Added {@link android.support.v4.view.ViewPager.PageTransformer PageTransformer} - interface to {@link android.support.v4.view.ViewPager} to allow applications to - supply a custom transition behavior for scrolling.
      • -
    • Added new features and fixes to {@link android.support.v4.app.TaskStackBuilder} - from current release.
      • -
    • Fixed {@link android.support.v4.view.PagerTitleStrip} to correctly track the - {@link android.support.v4.view.PagerAdapter} currently in use.
      • -
    • Fixed display flickering, positioning, and text clipping problems with - {@link android.support.v4.view.PagerTitleStrip}.
      • -
    • Fixed {@link android.support.v4.view.PagerTabStrip} to properly respect padding - when drawing an underline.
      • -
    -
    • -
  • Accessibility -
      -
    • Added support for new accessibility gesture and touch event types in - {@link android.support.v4.view.accessibility.AccessibilityEventCompat}.
      • -
    • Added support for new accessibility APIs in - {@link android.support.v4.view.ViewCompat}.
      • -
    • Added support for {@link android.support.v4.view.ViewCompat#performAccessibilityAction - performAccessibilityAction()} method to {@link android.support.v4.view.ViewCompat}. -
      • -
    -
    • -
  • Added support for gestures with {@link android.support.v4.view.GestureDetectorCompat}. -
    • -
  • Added support for performing atomic operations on files using a new - {@link android.support.v4.util.AtomicFile} class.
    • -
  • Added support for the full set of {@code make} methods in - {@link android.support.v4.content.IntentCompat}.
    • -
  • Added {@link android.support.v4.util.LruCache#trimToSize trimToSize()} method in - {@link android.support.v4.util.LruCache} utility class.
    • -
  • Updated {@link android.support.v4.net.ConnectivityManagerCompat} to get NetworkInfo - from a {@link android.net.ConnectivityManager#CONNECTIVITY_ACTION} - broadcast.
    • -
-
-
-
-
- - -
-

- Support Package, revision 10 (August 2012) -

-
-
-
Changes for v4 support library:
-
-
    -
  • Added support for notification features introduced in Android 4.1 (API level 16) with - additions to {@link android.support.v4.app.NotificationCompat}.
    • -
-
-
-
-
- - -
-

- Support Package, revision 9 (June 2012) -

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

- Support Package, revision 8 (April 2012) -

-
-
-
Changes for v4 support library:
-
-
    -
  • Fixed intent flags for {@link android.app.PendingIntent} objects generated - by {@link android.support.v4.app.TaskStackBuilder}.
    • -
  • Removed unused attributes from the gridlayout library projects to make sure - the library can be built with API level 7 and higher.
    • -
  • Added {@code .classpath} and {@code .project} files for the gridlayout - library project.
    • -
-
-
-
-
- -
-

- Support Package, revision 7 (March 2012) -

-
-
-
Changes for v4 support library:
-
-
    -
  • Added {@link android.support.v4.app.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 {@link android.widget.ShareActionProvider} in Android 4.0.
    • -
  • Added {@link android.support.v4.app.NavUtils} and {@link -android.support.v4.app.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 -({@code <sdk>/samples/<platform>/AppNavigation}).
    • -
  • Added {@link android.support.v4.app.NotificationCompat.Builder} to provide a -compatibility implementation of Android 3.0's {@link android.app.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: {@link android.support.v4.app}.

-
-
Changes for v4 support library:
-
-
    -
  • Changes to ViewPager: -
      -
    • Added extra decorative view support for {@link android.support.v4.view.ViewPager}. - Decorative views may be supplied as child views of a pager in XML layout.
      • -
    • Added {@link android.support.v4.view.PagerAdapter#getPageTitle - PagerAdapter.getPageTitle()} to supply title strings for pages, which defaults to no - title for each page.
      • -
    • Added {@link android.support.v4.view.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 {@link android.support.v4.view.PagerAdapter} methods to take ViewGroup - objects, rather than View to avoid class casting in adapter implementations.
      • -
    • Updated {@link android.support.v4.view.ViewPager} to use Launcher-style - fling behavior.
      • -
    • Bug fixes for user interface interaction and test automation.
      • -
    -
    • - -
  • Support for Fragments: -
      -
    • Changed {@code setStartDeferred()} method to {@link - android.support.v4.app.Fragment#setUserVisibleHint}.
      • -
    • Added deferred start for off-screen pages to improve performance.
      • -
    -
    • - -
  • Support for Accessiblity APIs: -
      -
    • Updated {@link android.support.v4.view.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 {@link android.support.v4.view.AccessibilityDelegateCompat} - to support {@link android.view.View.AccessibilityDelegate}.
      • - -
    • Added {@link android.support.v4.view.accessibility.AccessibilityEventCompat} - to support {@link android.view.accessibility.AccessibilityEvent}.
      • - -
    • Added {@link android.support.v4.view.accessibility.AccessibilityManagerCompat} - to support {@link android.view.accessibility.AccessibilityManager}.
      • - -
    • Added {@link android.support.v4.view.accessibility.AccessibilityNodeInfoCompat} - to support {@link android.view.accessibility.AccessibilityNodeInfo}.
      • - -
    • Added {@link android.support.v4.view.accessibility.AccessibilityRecordCompat} - to support {@link android.view.accessibility.AccessibilityRecord}.
      • - -
    • Added {@link - android.support.v4.accessibilityservice.AccessibilityServiceInfoCompat} - to support {@link android.accessibilityservice.AccessibilityServiceInfo}.
      • - -
    • Added {@link android.support.v4.view.ViewGroupCompat} - to support accessibility features in {@link android.view.ViewGroup}. -
      • - -
    • Modified {@link android.support.v4.view.ViewCompat} - to support accessibility features in {@link android.view.View}.
      • -
    -
    • - -
  • Changes to ViewPager: -
      -
    • Added support for margins between pages. - An optional {@link android.graphics.drawable.Drawable} can be provided - to fill the margins.
      • -
    • Added support for {@link android.widget.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 {@link android.widget.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 {@link android.view.View}s 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 {@link android.content.Loader} bug that caused issues in - canceling {@link android.os.AsyncTask}s when running on Froyo and older - versions of the platform. The support - code now uses its own version of {@link android.os.AsyncTask} to keep the same - behavior on all platform versions.
    • - -
-
-
-
-
- - -
-

- Compatibility Package, revision 3 (July 2011) -

-
-
-
Changes for v4 support library:
-
-
    -
  • Adds support for {@link android.app.Fragment.SavedState}
    • -
  • Adds {@code MotionEventCompat} to support newer {@link -android.view.MotionEvent} APIs
    • -
  • Adds {@code VelocityTrackerCompat} to support a newer {@link -android.view.VelocityTracker} APIs
    • -
  • Adds {@code ViewConfigurationCompat} to support a newer {@link -android.view.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: -
      -
    • {@code ViewPager}: A {@link android.view.ViewGroup} that manages the -layout for the child views, which the user can swipe between.
      • -
    • {@code PagerAdapter}: An adapter that populates the {@code ViewPager} with the -views that represent each page.
      • -
    • {@code FragmentPagerAdapter}: An extension of {@code PagerAdapter} for flipping -between fragments.
      • -
    • {@code FragmentStatePagerAdapter}: An extension of {@code PagerAdapter} for -flipping between fragments that uses the library's support for {@link -android.app.Fragment.SavedState}.
      • -
    -
    • -
-
-
New v13 support library:
-
-
    -
  • Includes the {@code FragmentPagerAdapter} and {@code 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 {@code 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:

- -
    -
  1. Launch the Android SDK Manager. -

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

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

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 {@code v4/}).

- - -

Setting Up a Project to Use a Library

- -

To add one of the libraries to your Android project:

-
-
- Add the JAR file to your project. -
-
- Copy the JAR file for the library you want to use into your Android project. To do this: -
    -
  • - Create the directory {@code libs/} at the root of your project - (next to {@code src/}, {@code res/}, and so forth). -
    • -
  • - Locate the JAR file for the library you want to use and copy it into the - {@code libs/} directory. -

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

    -
    • -
-

- Your build system may expect to find the JAR file in a directory other than - {@code libs}. Read the documentation for your build system to learn where to put the - JAR file. -

-
-
- If necessary, add the {@code libs/} directory to your build path. -
-
- Read the documentation for your build system to learn how to add the JAR file to the - build path. -
-
-

- To confirm that you've added the JAR file to the correct directory and added it to the build - path: -

-
    -
  1. - Edit one of your source files to add an {@code import} statement that imports a - class from the {@code android.support.*} package. -
    2. -
  2. - Build your app. The code should compile cleanly. -
    3. -
  3. - As a double-check, run your app. It should run correctly, without any runtime exceptions - indicating that the class in {@code android.support.*} can't be found. -
    4. -
-

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

- -

Tip: To see the library APIs in action, take a look at the sample -apps in {@code <sdk>/extras/android/support/<version>/samples/}.

- -

Warning: 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 {@code android:minSdkVersion} -and double check the import statements for classes that also exist in the support library, such as -{@code 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:

- - - -

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 Supporting Tablets and Handsets.

- - -

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; {@code -<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.

- diff --git a/docs/html/tools/support-library/features.jd b/docs/html/tools/support-library/features.jd new file mode 100644 index 000000000000..a749a3621444 --- /dev/null +++ b/docs/html/tools/support-library/features.jd @@ -0,0 +1,249 @@ +page.title=Support Library Features + +@jd:body + +
+ +
+ +

The Android Support Library package contains several individual libraries that can be included + in your application. Each of these libraries supports a specific range of Android platform + versions and set of features.

+ +

This guide explains the important features and version support provided by the Support + Libraries, to help you decide which of them you should include in your application. In general, + we recommend including the v4 support and v7 + appcompat libraries in your application, because they support a wide range of + Android versions and provide APIs for recommended user interface patterns.

+ +

In order to use any of the following libraries, you must download the library files to your + Android SDK installation. Follow the directions for downloading the Support Libraries in + Support Library Setup to + complete this step. You must take additional steps to include a specific Support Library in + your application. See the end of each library section below for instructions on how to include + the library in your application.

+ + +

v4 Support Library

+ +

This library is designed to be used with Android 1.6 (API level 4) and higher. It includes the + largest set of APIs compared to the other packages, including support for application components, + user interface features, accessibility, data handling, network connectivity, and programming + utilities. Here are a few of the key classes included in the v4 package:

+ + + +

+ There are many other APIs included in this package. For complete, detailed information about the + v4 Support Library APIs, see the {@link android.support.v4.app android.support.v4} package in the + API reference. +

+ +

This library is located in the {@code <sdk>/extras/android/support/v4/} directory after + you download the Android Support Libraries. This library does not contain user interface + resources. To include it in your application project, follow the instructions for + adding libraries without + resources.

+ +

The Gradle build script dependency identifier for this library is as follows:

+ +
+com.android.support:support-v4:18.0.+
+
+ +

This dependency notation specifies the release version 18.0.0 or higher.

+ + + +

v7 Libraries

+ +

There are several libraries designed to be used with Android 2.1 (API level 7) and higher. + These libraries provide specific feature sets and can be included in your application + independently from each other.

+ + +

v7 appcompat library

+ +

This library adds support for the Action + Bar user interface design pattern. +

+ +

Note: + This library depends on the v4 Support Library. If you are using Ant or Eclipse, make sure + you include the v4 Support Library as part of this library's classpath. +

+ +

Here are a few of the key classes included in the v7 appcompat library:

+ + + +

This library is located in the {@code <sdk>/extras/android/support/v7/appcompat/} + directory after you download the Android Support Libraries. This library contains user + interface resources. To include it in your application project, follow the instructions for + adding libraries with + resources.

+ +

The Gradle build script dependency identifier for this library is as follows:

+ +
+com.android.support:appcompat-v7:18.0.+
+
+ +

This dependency notation specifies release version 18.0.0 or higher.

+ + + +

v7 gridlayout library

+ +

This library adds support for the {@link android.support.v7.widget.GridLayout} class, which + allows you to arrange user interface elements using a grid of rectangular cells. + For detailed information about the v7 gridlayout library APIs, see the + {@link android.support.v7.widget android.support.v7.widget} package in the API reference.

+ +

This library is located in the {@code <sdk>/extras/android/support/v7/gridlayout/} + directory after you download the Android Support Libraries. This library contains user + interface resources. To include it in your application project, follow the instructions for + adding libraries with + resources.

+ +

The Gradle build script dependency identifier for this library is as follows:

+ +
+com.android.support:gridlayout-v7:18.0.+
+
+ +

This dependency notation specifies release version 18.0.0 or higher.

+ + +

v13 Support Library

+ +

This library is designed to be used for Android 3.2 (API level 13) and higher. It adds support + for the Fragment user interface pattern + with the ({@link android.support.v13.app.FragmentCompat}) class and additional fragment support + classes For more information about fragments, see the + Fragments developer guide. For detailed + information about the v13 Support Library APIs, see the {@link android.support.v13.app + android.support.v13} package in the API reference. +

+ +

This library is located in the {@code <sdk>/extras/android/support/v13/} directory after + you download the Android Support Libraries. This library does not contain user interface + resources. To include it in your application project, follow the instructions for + adding libraries without + resources.

+ +

The Gradle build script dependency identifier for this library is as follows:

+ +
+com.android.support:support-v13:18.0.+
+
+ +

This dependency notation specifies the release version 18.0.0 or higher.

diff --git a/docs/html/tools/support-library/index.jd b/docs/html/tools/support-library/index.jd new file mode 100644 index 000000000000..e5efb8d81157 --- /dev/null +++ b/docs/html/tools/support-library/index.jd @@ -0,0 +1,659 @@ +page.title=Support Library + +@jd:body + +
+
+ +

In this document

+
    +
  1. Overview
    2. +
  2. Revisions
    3. +
+ +

See also

+
    +
  1. + Support Library Features
    2. +
  2. + Support Library Setup
    3. +
+ +
+
+ +

The Android Support Library package is a set of code libraries that provide useful and important + features for Android applications in addition to the framework APIs. These libraries provide + backward-compatible versions of framework APIs as well as features that are only available + through its API. Each Support Library is backward-compatible to a specific Android API level. + This design means that your applications can use the libraries' features and still be compatible + with devices running Android 1.6 (API level 4) and up.

+ +

This guide provides information about what features are enabled by the different libraries, + how to use them in your development environment and information about the Support Library + releases.

+ + +

Overview

+ +

Including the Support Libraries in your Android project is considered a best practice for + application developers. Using the features they provide can help you improve the look of your + application, increase performance and broaden the reach of your application to more users. + If you use the Android + code template tools, you will notice that + all the Android application templates include one or more of the Support Libraries by default.

+ +

The Support Libraries each target a base Android API level and each provides a different set + of features. In order to effectively use the libraries, it is important to consider what features + you want to support and understand what features are supported by each library at what Android + API level. To get started, review the + Support Library Features guide. + After that, go to the + Support Library Setup topic to + learn how to incorporate the Support Libraries into your application. For more details + about Support Library APIs, see the {@link android.support.v4.app android.support} + packages in the API reference.

+ + +

Revisions

+ +

This section provides details about the Support Library package releases.

+ +
+

+ Android Support Library, revision 18 (July 2013) +

+
+
+
Changes for v4 support library:
+
+
    +
  • User interface +
      +
    • Added {@link android.support.v4.text.BidiFormatter} for handling + text strings that combine right to left and left to right-formatted text.
      • +
    • Modified {@link android.support.v4.view.ViewPager} to better handle cases where the + pager has a measured width of zero in the initial layout processing.
      • +
    • Modified {@link android.support.v4.widget.DrawerLayout} and + {@link android.support.v4.widget.SlidingPaneLayout} to not throw exceptions for + measurement while the project code is being edited.
      • +
    +
    • + +
  • Accessibility +
      +
    • Added {@link android.support.v4.widget.ExploreByTouchHelper} to simplify the + implementation of accessibility for custom views.
      • +
    • Fixed a problem with {@link android.support.v4.view.ViewPager} incorrectly + populating {@link + android.support.v4.view.accessibility.AccessibilityEventCompat#TYPE_VIEW_SCROLLED + TYPE_VIEW_SCROLLED} accessibility events.
      • +
    • Fixed a null pointer exception in {@link android.support.v4.view.ViewPager} when + populating an accessibility event.
      • +
    • Simplified {@link android.support.v4.view.accessibility.AccessibilityNodeInfoCompat} + by changing {@link java.lang.CharSequence} inputs to {@link java.lang.String} objects. +
      • +
    • Deprecated an {@link android.support.v4.view.accessibility.AccessibilityRecordCompat} + constructor that used an {@link java.lang.Object} as input.
      • +
    +
    • + +
  • Media +
      +
    • Added {@link android.support.v4.media.TransportMediator} helper class to manage + media transport control, such as play, pause, skip and other media actions.
      • +
    • Added {@link android.support.v4.hardware.display.DisplayManagerCompat} for managing + display output to one or more device displays.
      • +
    +
    • + +
  • Other changes +
      +
    • Added {@link android.support.v4.content.WakefulBroadcastReceiver} helper class for + implementing a common pattern of detecting a device wakeup event and passing work off + to a {@link android.app.Service} while ensuring that the device does not go back to + sleep before the handoff is complete.
      • +
    • Added two new APIs, + {@link android.support.v4.content.AsyncTaskLoader#commitContentChanged + commitContentChanged()} and + {@link android.support.v4.content.AsyncTaskLoader#rollbackContentChanged + rollbackContentChanged()}, to {@link android.support.v4.content.AsyncTaskLoader} to + help deal with background updates for data changes that are subsequently canceled. +
      • +
    +
    • +
+
+ +
New v7 appcompat library:
+
+
    +
  • Added {@link android.support.v7.app.ActionBar} to allow implementation of the + action bar user interface design + pattern back to Android 2.1 (API level 7) and higher. Use of this class requires + that you implement your activity by extending the new + {@link android.support.v7.app.ActionBarActivity} class.
    • +
+
+ +
+
+
+ + +
+

+ Android Support Library, revision 13 (May 2013) +

+
+
+
Changes for v4 support library:
+
+
    +
  • Added {@link android.support.v4.widget.DrawerLayout} for creating a + Navigation + Drawer that can be pulled in from the edge of a window.
    • +
  • Added {@link android.support.v4.widget.SlidingPaneLayout} widget for creating linked + summary and detail views that appropriately adapt to various screen sizes.
    • +
  • Added {@link android.support.v4.app.ActionBarDrawerToggle} as a way to tie + together the functions of {@link android.support.v4.widget.DrawerLayout} and {@link + android.app.ActionBar}.
    • +
  • Added {@link android.support.v4.widget.ViewDragHelper} as a new common component + for dragging views within a parent view.
    • +
  • Added {@link android.support.v4.widget.ScrollerCompat} to provide {@link + android.widget.Scroller} and {@link android.widget.OverScroller} compatibility support. +
    • +
  • Added {@link android.support.v4.content.FileProvider} to allow sharing of private + files between applications.
    • +
  • Updated {@link android.support.v4.view.ViewPager} to throw an exception if the + associated {@link android.support.v4.view.PagerAdapter} class is modified without a + call to {@link android.support.v4.view.PagerAdapter#notifyDataSetChanged + notifyDataSetChanged()}. +
    • +
  • Fixed an issue with {@link android.support.v4.view.ViewPager} children drawing sort + order.
    • +
  • Fixed {@link android.support.v4.view.GestureDetectorCompat} to dispatch missing + {@link android.view.GestureDetector.SimpleOnGestureListener#onSingleTapConfirmed} calls + between tap timeout and long press events.
    • +
+
+ +
New v7 gridlayout library:
+
+
    +
  • Added {@link android.support.v7.widget.GridLayout} to provide support for the + {@link android.widget.GridLayout} layout object.
    • +
  • Added {@link android.support.v7.widget.Space} which can be used to create blank areas + within a {@link android.support.v7.widget.GridLayout} layout object.
    • +
+
+
+
+ + +
+

+ Android Support Library, revision 12 (February 2013) +

+
+
+
Changes for v4 support library:
+
+
    +
  • Improved interaction behavior for {@link android.support.v4.view.ViewPager}.
    • +
  • Fixed a bug that could cause {@link android.support.v4.view.ViewPager} to select the + wrong page.
    • +
  • Fixed use of {@link android.support.v4.view.ViewPager#removeView removeView()} method + during layout for {@link android.support.v4.view.ViewPager}.
    • +
  • Fixed issue with {@link android.support.v4.widget.SearchViewCompat} where using the + back button to dismiss does not clear the search text. This fix only applies to + host API levels 14 and higher.
    • +
+
+
+
+
+ + +
+

+ Android Support Library, revision 11 (November 2012) +

+
+
+
Changes for v4 support library:
+
+
    +
  • User Interface +
      +
    • Added support for nested {@link android.support.v4.app.Fragment} classes.
      • +
    • Added improvements to {@link android.support.v4.app.FragmentManager} debugging. +
      • +
    • Fixed problem in {@link android.support.v4.app.FragmentTabHost} where fragment + and tab interaction could result in a {@link android.widget.ListView} state loss. +
      • +
    • Fixed issue with user-visible hint in + {@link android.support.v4.app.FragmentStatePagerAdapter}.
      • +
    • Added {@link android.support.v4.view.ViewPager.PageTransformer PageTransformer} + interface to {@link android.support.v4.view.ViewPager} to allow applications to + supply a custom transition behavior for scrolling.
      • +
    • Added new features and fixes to {@link android.support.v4.app.TaskStackBuilder} + from current release.
      • +
    • Fixed {@link android.support.v4.view.PagerTitleStrip} to correctly track the + {@link android.support.v4.view.PagerAdapter} currently in use.
      • +
    • Fixed display flickering, positioning, and text clipping problems with + {@link android.support.v4.view.PagerTitleStrip}.
      • +
    • Fixed {@link android.support.v4.view.PagerTabStrip} to properly respect padding + when drawing an underline.
      • +
    +
    • +
  • Accessibility +
      +
    • Added support for new accessibility gesture and touch event types in + {@link android.support.v4.view.accessibility.AccessibilityEventCompat}.
      • +
    • Added support for new accessibility APIs in + {@link android.support.v4.view.ViewCompat}.
      • +
    • Added support for {@link android.support.v4.view.ViewCompat#performAccessibilityAction + performAccessibilityAction()} method to {@link android.support.v4.view.ViewCompat}. +
      • +
    +
    • +
  • Added support for gestures with {@link android.support.v4.view.GestureDetectorCompat}. +
    • +
  • Added support for performing atomic operations on files using a new + {@link android.support.v4.util.AtomicFile} class.
    • +
  • Added support for the full set of {@code make} methods in + {@link android.support.v4.content.IntentCompat}.
    • +
  • Added {@link android.support.v4.util.LruCache#trimToSize trimToSize()} method in + {@link android.support.v4.util.LruCache} utility class.
    • +
  • Updated {@link android.support.v4.net.ConnectivityManagerCompat} to get NetworkInfo + from a {@link android.net.ConnectivityManager#CONNECTIVITY_ACTION} + broadcast.
    • +
+
+
+
+
+ + +
+

+ Android Support Library, revision 10 (August 2012) +

+
+
+
Changes for v4 support library:
+
+
    +
  • Added support for notification features introduced in Android 4.1 (API level 16) with + additions to {@link android.support.v4.app.NotificationCompat}.
    • +
+
+
+
+
+ + +
+

+ Android Support Library, revision 9 (June 2012) +

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

+ Android Support Library, revision 8 (April 2012) +

+
+
+
Changes for v4 support library:
+
+
    +
  • Fixed intent flags for {@link android.app.PendingIntent} objects generated + by {@link android.support.v4.app.TaskStackBuilder}.
    • +
  • Removed unused attributes from the gridlayout library projects to make sure + the library can be built with API level 7 and higher.
    • +
  • Added {@code .classpath} and {@code .project} files for the gridlayout + library project.
    • +
+
+
+
+
+ + +
+

+ Android Support Library, revision 7 (March 2012) +

+
+
+
Changes for v4 support library:
+
+
    +
  • Added {@link android.support.v4.app.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 {@link android.widget.ShareActionProvider} in Android 4.0.
    • +
  • Added {@link android.support.v4.app.NavUtils} and {@link +android.support.v4.app.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 +({@code <sdk>/samples/<platform>/AppNavigation}).
    • +
  • Added {@link android.support.v4.app.NotificationCompat.Builder} to provide a +compatibility implementation of Android 3.0's {@link android.app.Notification.Builder} helper class +for creating standardized system notifications.
    • +
+
+
+
+
+ + +
+

+ Android Support Library, revision 6 (December 2011) +

+
+ +

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

+
+
Changes for v4 support library:
+
+
    +
  • Changes to ViewPager: +
      +
    • Added extra decorative view support for {@link android.support.v4.view.ViewPager}. + Decorative views may be supplied as child views of a pager in XML layout.
      • +
    • Added {@link android.support.v4.view.PagerAdapter#getPageTitle + PagerAdapter.getPageTitle()} to supply title strings for pages, which defaults to no + title for each page.
      • +
    • Added {@link android.support.v4.view.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 {@link android.support.v4.view.PagerAdapter} methods to take ViewGroup + objects, rather than View to avoid class casting in adapter implementations.
      • +
    • Updated {@link android.support.v4.view.ViewPager} to use Launcher-style + fling behavior.
      • +
    • Bug fixes for user interface interaction and test automation.
      • +
    +
    • + +
  • Support for Fragments: +
      +
    • Changed {@code setStartDeferred()} method to {@link + android.support.v4.app.Fragment#setUserVisibleHint}.
      • +
    • Added deferred start for off-screen pages to improve performance.
      • +
    +
    • + +
  • Support for Accessiblity APIs: +
      +
    • Updated {@link android.support.v4.view.AccessibilityDelegateCompat} methods + to return empty lists instead of null.
      • +
    • Added new APIs needed by the v4 samples.
      • +
    +
    • + +
+
+
+
+
+ +
+

+ Android Support Library, revision 5 (December 2011) +

+
+
+
Changes for v4 support library:
+
+
    +
  • Support for Accessiblity APIs: +
      +
    • Added {@link android.support.v4.view.AccessibilityDelegateCompat} + to support {@link android.view.View.AccessibilityDelegate}.
      • + +
    • Added {@link android.support.v4.view.accessibility.AccessibilityEventCompat} + to support {@link android.view.accessibility.AccessibilityEvent}.
      • + +
    • Added {@link android.support.v4.view.accessibility.AccessibilityManagerCompat} + to support {@link android.view.accessibility.AccessibilityManager}.
      • + +
    • Added {@link android.support.v4.view.accessibility.AccessibilityNodeInfoCompat} + to support {@link android.view.accessibility.AccessibilityNodeInfo}.
      • + +
    • Added {@link android.support.v4.view.accessibility.AccessibilityRecordCompat} + to support {@link android.view.accessibility.AccessibilityRecord}.
      • + +
    • Added {@link + android.support.v4.accessibilityservice.AccessibilityServiceInfoCompat} + to support {@link android.accessibilityservice.AccessibilityServiceInfo}.
      • + +
    • Added {@link android.support.v4.view.ViewGroupCompat} + to support accessibility features in {@link android.view.ViewGroup}. +
      • + +
    • Modified {@link android.support.v4.view.ViewCompat} + to support accessibility features in {@link android.view.View}.
      • +
    +
    • + +
  • Changes to ViewPager: +
      +
    • Added support for margins between pages. + An optional {@link android.graphics.drawable.Drawable} can be provided + to fill the margins.
      • +
    • Added support for {@link android.widget.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.
      • +
    +
    • +
+
+
+
+
+ +
+

+ Android Support Library, revision 4 (October 2011) +

+
+
+
Changes for v4 support library:
+
+
    +
  • Added EdgeEffectCompat to + support {@link android.widget.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 {@link android.view.View}s 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 {@link android.content.Loader} bug that caused issues in + canceling {@link android.os.AsyncTask}s when running on Froyo and older + versions of the platform. The support + code now uses its own version of {@link android.os.AsyncTask} to keep the same + behavior on all platform versions.
    • + +
+
+
+
+
+ + +
+

+ Android Support Library, revision 3 (July 2011) +

+
+
+
Changes for v4 support library:
+
+
    +
  • Adds support for {@link android.app.Fragment.SavedState}
    • +
  • Adds {@code MotionEventCompat} to support newer {@link +android.view.MotionEvent} APIs
    • +
  • Adds {@code VelocityTrackerCompat} to support a newer {@link +android.view.VelocityTracker} APIs
    • +
  • Adds {@code ViewConfigurationCompat} to support a newer {@link +android.view.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: +
      +
    • {@code ViewPager}: A {@link android.view.ViewGroup} that manages the +layout for the child views, which the user can swipe between.
      • +
    • {@code PagerAdapter}: An adapter that populates the {@code ViewPager} with the +views that represent each page.
      • +
    • {@code FragmentPagerAdapter}: An extension of {@code PagerAdapter} for flipping +between fragments.
      • +
    • {@code FragmentStatePagerAdapter}: An extension of {@code PagerAdapter} for +flipping between fragments that uses the library's support for {@link +android.app.Fragment.SavedState}.
      • +
    +
    • +
+
+
New v13 support library:
+
+
    +
  • Includes the {@code FragmentPagerAdapter} and {@code 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).

    +
    • +
+
+
+
+
+ + +
+

+ Android Support Library, revision 2 (May 2011) +

+
+
+
Changes for v4 library:
+
+
    +
  • Support for fragment animations
    • +
  • Fix {@link android.support.v4.app.Fragment#onActivityResult Fragment.onActivityResult()} + bug
    • +
+
+
+
+
+ + +
+

+ Android Support Library, revision 1 (March 2011) +

+
+

Initial release with the v4 library.

+
+
+ diff --git a/docs/html/tools/support-library/setup.jd b/docs/html/tools/support-library/setup.jd new file mode 100644 index 000000000000..a2ece159f341 --- /dev/null +++ b/docs/html/tools/support-library/setup.jd @@ -0,0 +1,308 @@ +page.title=Support Library Setup + +@jd:body + + +
+ +
+ +

How you setup the Android Support Libraries in your development project depends on what features + you want to use and what range of Android platform versions you want to support with your + application.

+ +

This document guides you through downloading the Support Library package and adding libraries + to your development environment.

+ + +

Downloading the Support Libraries

+ +

The Android Support Library package is provided as a supplemental download to the Android SDK + and is available through the Android + SDK Manager. Follow the + instructions below to obtain the Support Library files. +

+ +

To download the Support Library through the SDK Manager:

+ +
    +
  1. Start the Android SDK Manager.
    2. +
  2. In the SDK Manager window, scroll to the end of the Packages list, + find the Extras folder and, if necessary, expand to show its contents.
    3. +
  3. Select the Android Support Library item. +

    + Note: If you're developing with Android Studio, select and install the + Android Support Repository item instead. +

    +
    4. +
  4. Click the Install packages... button.
    5. +
+ + +

Figure 1. The Android SDK Manager with the +Android Support Library selected.

+ +

After downloading, the tool installs the Support Library files to your existing Android SDK + directory. The library files are located in the following subdirectory of your SDK: + {@code <sdk>/extras/android/support/} directory.

+ + +

Choosing Support Libraries

+ +

Before adding a Support Library to your application, decide what features you want to include + and the lowest Android versions you want to support. For more information on the features + provided by the different libraries, see + Support Library Features.

+ + +

Adding Support Libraries

+ +

In order to use a Support Library, you must modify your application's project's + classpath dependencies within your development environment. You must perform this procedure for + each Support Library you want to use.

+ +

Some Support Libraries contain resources beyond compiled code classes, such as images or XML + files. For example, the v7 + appcompat and v7 gridlayout + libraries include resources.

+ +

If you are not sure if a library contains resources, check the + Support Library Features page. + The following sections describe how to add a Support Library with or without resources to your + application project.

+ + +

Adding libraries without resources

+ +

To add a Support Library without resources to your application project:

+ +
+

+ Using Eclipse

+ +
+
    +
  1. Make sure you have downloaded the Android Support Library + using the SDK Manager.
    2. +
  2. Create a {@code /libs} directory in the root of your application project.
    3. +
  3. Copy the JAR file from your Android SDK installation directory (e.g., + {@code <sdk>/extras/android/support/v4/android-support-v4.jar}) into your + application's project {@code /libs} directory. +
  4. Right click the JAR file and select Build Path > Add to Build Path. +
    5. +
+
+
+ +
+

+ Using Android Studio

+ +
+
    +
  1. Make sure you have downloaded the Android Support Repository. + using the SDK Manager.
    2. +
  2. Open the {@code build.gradle} file for your application.
    3. +
  3. Add the support library to the {@code dependencies} section. For example, to add the v4 + support library, add the following lines: +
    +dependencies {
+    ...
+    compile "com.android.support:support-v4:18.0.+"
+}
+
    +
    4. +
+
+
+ + +

Adding libraries with resources

+ +

To add a Support Library with resources to your application project:

+ +
+

+ Using Eclipse

+
+ +

Create a library +project based on the support library code:

+ +
    +
  1. Make sure you have downloaded the Android Support Library + using the SDK Manager.
    2. +
  2. Create a library project and ensure the required JAR files are included in the project's + build path: +
      +
    1. Select File > Import.
      2. +
    2. Select Existing Android Code Into Workspace and click + Next.
      3. +
    3. Browse to the SDK installation directory and then to the Support Library folder. + For example, if you are adding the {@code appcompat} project, browse to + <sdk>/extras/android/support/v7/appcompat/.
      4. +
    4. Click Finish to import the project. For the v7 appcompat project, you + should now see a new project titled android-support-v7-appcompat.
      5. +
    5. In the new library project, expand the {@code /libs} folder, right-click each {@code .jar} + file and select Build Path > Add to Build Path. For example, when + creating the the v7 appcompat project, add both the {@code android-support-v4.jar} and + {@code android-support-v7-appcompat.jar} files to the build path.
      6. +
    6. Right-click the project and select Build Path > Configure Build Path. +
      7. +
    7. In the Order and Export tab, check the .jar files you just + added to the build path, so they are available to projects that depend on this library + project. For example, the {@code appcompat} project requires you to export both the + {@code android-support-v4.jar} and {@code android-support-v7-appcompat.jar} files.
      8. +
    8. Uncheck Android Dependencies.
      9. +
    9. Click OK to complete the changes.
      10. +
    +
    3. +
+ +

You now have a library project for your selected Support Library that you can use with one or + more application projects.

+ +

Add the library to your application project:

+
    +
  1. In the Project Explorer, right-click your project and select Properties. +
  2. In the Library pane, click Add. +
  3. Select the library project and click OK. For example, the + {@code appcompat} project should be listed as android-support-v7-appcompat. +
    4. +
  4. In the properties window, click OK. +
+ +
+
+ + +
+

+ Using Android Studio

+ +
+
    +
  1. Make sure you have downloaded the Android Support Repository + using the SDK Manager.
    2. +
  2. Open the {@code build.gradle} file for your application.
    3. +
  3. Add the support library feature project identifier to the {@code dependencies} section. + For example, to include the {@code appcompat} project add + {@code compile "com.android.support:appcompat-v7:18.0.+"} to the dependencies section, as + shown in the following example: +
    +dependencies {
+    ...
+    compile "com.android.support:appcompat-v7:18.0.+"
+}
+
    +
    4. +
+
+
+ + +

Using Support Library APIs

+ +

Support Library classes that provide support for existing framework APIs typically have the + same name as framework class but are located in the android.support class packages, + or have a *Compat suffix.

+ +
+

Caution: When using classes from the Support Library, be certain you import + the class from the appropriate package. For example, when applying the {@code ActionBar} + class:

+ +
+ +

+ Note: After including the Support Library in your application project, we + strongly recommend using the + ProGuard tool to prepare your application APK + for release. In addition to protecting your source code, the ProGuard tool also removes unused + classes from any libraries you include in your application, which keeps the download size of + your application as small as possible. For more information, see + ProGuard. +

+ +

Further guidance for using some Support Library features is provided in the Android developer + training classes, + guides + and samples. For more information about the individual Support Library classes and methods, see + the {@link android.support.v4.app android.support} packages in the API reference. +

+ + +

Manifest Declaration Changes

+ +

If you are increasing the backward compatibility of your existing application to an earlier + version of the Android API with the Support Library, make sure to update your application's + manifest. Specifically, you should update the android:minSdkVersion + element of the + <uses-sdk> tag in the manifest to the new, lower version number, as + shown below:

+ +
+  <uses-sdk
+      android:minSdkVersion="7"
+      android:targetSdkVersion="17" />
+
+ +

This change tells Google Play that your application can be installed on devices with Android + 2.1 (API level 7) and higher.

+ +

+ Note: If you are including the v4 support and v7 appcompat libraries in your + application, you should specify a minimum SDK version of "7" (and not + "4"). The highest support library level you include in your application determines + the lowest API version in which it can operate. +

+ + +

Code Samples

+ +

Each Support Library includes code samples to help you get started using the support +APIs. The code is included in the download from the SDK Manager and is placed inside the Android +SDK installation directory, as listed below:

+ + + diff --git a/docs/html/tools/tools_toc.cs b/docs/html/tools/tools_toc.cs index c555f9841841..8ad61ec20f53 100644 --- a/docs/html/tools/tools_toc.cs +++ b/docs/html/tools/tools_toc.cs @@ -56,7 +56,13 @@
  • Using the Emulator
    • -
  • Using Hardware Devices
    • +
  • +
    Using Hardware Devices
    + +
  • Setting Up Projects
    • - - + + + +
  • +
    Support Library
    + +
    • +
  • Tools Help
    @@ -222,19 +238,6 @@ class="en">Platforms
    • -
  • -
    Extras
    - -
    • - -
  • Samples
    -- cgit v1.2.3-59-g8ed1b