3.3: The Android Support Library

Contents:

In this chapter you explore the Android Support Library, which is part of the Android SDK tools. You can use the Android Support Library to get backward-compatible versions of new Android features, plus user interface (UI) elements not included in the standard Android framework.

About the Android Support Library

The Android SDK tools include a number libraries collectively called the Android Support Library. This package of libraries provides several features that are not built into the standard Android framework, and provides backward compatibility for older devices. Include any of these libraries in your app to incorporate that library's functionality.

Note: The Android Support library is a different package from the Android Testing Support library you learned about in another chapter. The testing support library provides tools and APIs just for testing, whereas the more general support library provides features of all kinds (but no testing).

Features

The features of the Android Support Library include:

  • Backward-compatible versions of framework components. These compatibility libraries allow you to use features and components available on newer versions of the Android platform even when your app is running on an older platform version. For example, older devices may not have access to newer features such as fragments, app bars (also known as action bars), or Material Design elements. The support library provides access to those features on older devices.
  • Additional layout and UI elements. The support library includes views and layouts that can be useful for your app, but are not included in the standard Android framework. For example, the RecyclerView view that you will use in another chapter is part of the support library.
  • Support for different device form factors, such as TV or wearables: For example, the Leanback library includes components specific to app development on TV devices.
  • Design support: The design support library includes components to support Material Design elements in your app, including floating action buttons (FAB). You'll learn more about Material Design in a later chapter.
  • Various other features such as palette support, annotations, percentage-based layout dimensions, and preferences.

Backward Compatibility

Support libraries allow apps running on older versions of the Android platform to support features made available on newer versions of the platform. For example, an app running on a version of Android lower than 5.0 (API level 21) that relies on framework classes cannot display Material Design elements, as that version of the Android framework doesn't support Material Design. However, if the app incorporates the v7 appcompat library, that app has access to many of the features available in API level 21, including support for Material Design. As a result, your app can deliver a more consistent experience across a broader range of platform versions.

The support library APIs also provide a compatibility layer between different versions of the framework APIs. This compatibility layer transparently intercepts API calls and changes either the arguments passed, handles the operation itself, or redirects the operation. In the case of the support libraries, by using the compatibility layer's methods, you can ensure interoperability between older and newer Android releases. Each new release of Android adds new classes and methods, and possibly deprecates some older classes and methods. The support libraries include compatibility classes that can be used for backward compatibility.You can identify these classes by their names, which include "Compat" (such as ActivityCompat).

When an app calls one of the support class's methods, the behavior of that method depends on the underlying Android version. If the device includes the necessary framework functionality, the support library uses the framework. If the device is running an older version of Android, the support library makes an attempt to implement similar compatible behavior with the APIs it has available.

For most cases you do not need to write complex code that checks the version of Android and performs different operations based on that version. You can rely on the support library to do those checks and choose appropriate behavior.

When in doubt, choose a support library compatibility class over the framework class.

Versions

Each package in the support library has a version number in three parts (x.y.z) that corresponds to an Android API level, and to a particular revision of that library. For example, a support library version number of 22.3.4 is version 3.4 of the support library for API 22.

As a general rule, use the most recent version of the support library for the API your app is compiled and targeted for, or a newer version. For example, if your app targets API 26, use the version 26.x.x of the support library.

You can always use a newer support library than the one for your targeted API. For example, if your app targets API 22 you can use version 25 or higher of the support library. The reverse is not true—you cannot use an older support library with a newer API. As a general rule, you should try to use the most up-to-date API and support libraries in your app.

API Levels

In addition to the actual version number, the name of the support library itself indicates the API level that the library is backward-compatible with. You cannot use a support library in your app for an API higher than the minimum API your app supports. For example, if the minimum API your app supports is 10, you cannot use the v13 support library or v14 preferences support library in your app. If your app uses multiple support libraries, your minimum API must be higher than the largest number—that is, if you include support libraries for v7, v13, and v14 your minimum API must be at least 14.

All of the support libraries, including the v4 and v7 libraries, require a minimum SDK of API 9.

Support libraries and features

This section describes the important features provided by the libraries in the Android Support Library. You'll learn about many of the features described in this section in other chapters.

v4 support library

The v4 support libraries include the largest set of APIs compared to the other libraries, including support for app components, user interface features, accessibility, data handling, network connectivity, and programming utilities.

The v4 support libraries include these specific components:

  • v4 compat library: Compatibility wrappers (classes that include the word "Compat") for a number of core framework APIs.
  • v4 core-utils library: Provides a number of utility classes
  • v4 core-ui library: Implements a variety of UI-related components.
  • v4 media-compat library: Backports portions of the media framework from API 21.
  • v4 fragment library: Adds support for Android fragments.

v7 support library

The v7 support library includes both compatibility libraries and additional features.

The v7 support library includes all the v4 support libraries, so you don't have to add those separately. A dependency on the v7 support library is included in every new Android Studio project, and new activities in your project extend from AppCompatActivity.

The v7 support libraries include these specific components:

  • v7 appcompat library: Adds support for the app bar UI design pattern and support for Material Design UI implementations.
  • v7 cardview library: Provides the CardView class, a view that lets you show information inside cards.
  • v7 gridlayout library: Includes the GridLayout class, which allows you to arrange UI elements using a grid of rectangular cells
  • v7 mediarouter library: Provides MediaRouter and related media classes that support Google Cast.
  • v7 palette library: Implements the Palette class, which lets you extract prominent colors from an image.
  • v7 recyclerview library: Provides the RecyclerView class, a view for efficiently displaying large data sets by providing a limited window of data items.
  • v7 preference library: Provides APIs to support preference objects in app settings.

Other libraries

  • v8 renderscript library: Adds support for the RenderScript, a framework for running computationally intensive tasks at high performance.
  • v13 support library: Provides support for using a Fragment with the FragmentCompat class and additional Fragment support classes.
  • v14 preference support library, and v17 preference support library for TV: provides APIs to add support for preference interfaces on mobile devices and TV.
  • v17 leanback library: Provides APIs to support building UIs on TV devices.
  • Annotations support library: Contains APIs to support adding annotation metadata to your apps.
  • Design support library: Adds support for various Material Design components and patterns such as navigation drawers, floating action buttons (FAB), snackbars, and tabs.
  • Custom Tabs support library: Adds support for adding and managing custom tabs in your apps.
  • Percent support library: Enables you to add and manage percentage based dimensions in your app.
  • App recommendation support library for TV: Provides APIs to support adding content recommendations in your app running on TV devices.

Setting up and using the Android Support Library

The Android Support Library package is part of the Android SDK, and available to download in the Android SDK manager. To set up your project to use any of the support libraries, use these steps:

  1. Download the support library with the Android SDK manager, or verify that the support libraries are already available.
  2. Find the library dependency statement for the support library you're interested in.
  3. Add that dependency statement to the dependencies section of your build.gradle (Module: app) file.

Download the support library

In Android Studio, you'll use the Android Support Repository—the repository in the SDK manager for all support libraries—to get access to the library from within your project.

You may already have the Android support libraries downloaded and installed with Android Studio. To verify that you have the support libraries available, follow these steps:

  1. In Android Studio, select Tools > Android > SDK Manager, or click the SDK Manager SDK Manager icon icon. The SDK Manager preference pane appears.

  2. Click the SDK Tools tab and expand Support Repository, as shown in the figure below. SDK Manager

  3. Look for Android Support Repository in the list. If Installed appears in the Status column, you're all set. Click Cancel.

    If Not installed or Update Available appears, click the checkbox next to Android Support Repository. A download icon should appear next to the checkbox. Click OK.

  4. Click OK again, and then Finish when the support repository has been installed.

Find a library dependency statement

To provide access to a support library from your project, you add that library to your Gradle build file as a dependency. Dependency statements have a specific format that includes the name and version number of the library.

  1. Visit the Support Library Features page on developer.android.com.
  2. Find the library you're interested in on that page, for example, the Design Support Library for Material Design support.
  3. Copy the dependency statement shown at the end of the section. For example, the dependency for the design support library looks like this:

com.android.support:design:26.1.0

The version number at the end of the line may vary from the one shown above. You will update the version number when you add the dependency to the build.gradle file in the next step.

Add the dependency to your build.gradle file

The Gradle scripts for your project manage how your app is built, including specifying the dependencies your app has on other libraries. To add a support library to your project, modify your Gradle build files to include the dependency to that library you found in the previous section.

  1. In Android Studio, make sure the Project > Android pane is open.

  2. Expand Gradle Scripts and open the build.gradle (Module: app) file.

    Note that build.gradle for the overall project (build.gradle (Project: app_name )) is a different file from the build.gradle for the app module.

  3. Locate the dependencies section near the end of the file.

    The dependencies section for a new project already includes dependencies for several other libraries.

  4. Add a dependency for the support library that includes the statement you copied in the previous task. For example, a complete dependency on the design support library looks like this:

compile 'com.android.support:design:26.1.0'

  1. Update the version number, if necessary.

    If the version number you specified is lower than the currently available library version number, Android Studio warns you that an updated version is available. ("a newer version of com.android.support:design is available"). Edit the version number to the updated version, or enter Alt-Enter (Option-Return on a Mac) and select Change to xx.xx.x from the menu, where xx.xx.x is the most up-to-date version available.

  2. Click Sync Now to sync your updated gradle files with the project, if prompted.

Using the support library APIs

All the support library classes are contained in the android.support packages. For example, android.support.v7.app.AppCompatActivity is the fully qualified name for the AppCompatActivity class, from which all of your activities extend.

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. Make sure that when you import those classes you use the right package name for the class you're interested in. For example, when applying the ActionBar class, use one of:

  • android.support.v7.app.ActionBar when using the Support Library.
  • android.app.ActionBar when developing only for API level 11 or higher.

The support library also includes several View classes used in XML layout files. In the case of the View elements (such as CoordinatorLayout), you must always use the fully qualified name in the XML element for that View:

<android.support.design.widget.CoordinatorLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical">
</android.support.design.widget.CoordinatorLayout>

You'll learn about CoordinatorLayout in another chapter.

Checking system versions

Although the support library can help you implement single apps that work across Android platform versions, there may be times when you need to check for the version of Android your app is running on, and provide the correct code for that version.

Android provides a unique code for each platform version in the Build constants class. Use these codes within your app to test for the version and to ensure that the code that depends on higher API levels is executed only when those APIs are available on the system.

private void setUpActionBar() {
    // Make sure we're running on Honeycomb or higher to use ActionBar APIs
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.HONEYCOMB) {
        ActionBar actionBar = getActionBar();
        actionBar.setDisplayHomeAsUpEnabled(true);
    } else { // do something else }
}

The related practical is 3.3: Support libraries.

Learn more

Android Studio documentation:

Android developer documentation:

Other:

results matching ""

    No results matching ""