+ + Figure 1. Because this app uses support library UI + elements its interface incorporates material design principles, even though + it is running on Android 4.4, which does not include native support for + material design. +
+The Android Support Library package is a set of code libraries that provide - backward-compatible versions of Android framework APIs as well as features that are only available - through the library APIs. 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 Support Libraries, - how to use them in your development environment and information about library releases.
- ++ The Android Support Library offers a number of features that are not built + into the framework. These libraries offer backward-compatible versions of + new features, provide useful UI elements that are not included in the + framework, and provide a range of utilities that apps can draw on. +
Including the Support Libraries in your Android project is considered a best practice for - application developers, depending on the range of platform versions your app is targeting - and the APIs that it uses. Using the features the libraries 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.
++ In many cases, a feature may be valuable to many app developers, but not + appropriate to include in the Android framework itself. For example, an app + might only need a feature for specialized use cases, such as to smooth the + transition between different versions of the Android system. +
-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.
++ To address these situations, the Android SDK includes several libraries + collectively called the Android Support Library. App developers + can include any of these libraries if they want to incorporate the + library functionality into their apps. +
+ ++ Support libraries provide a range of different features: +
+ +
+ + Figure 1. Because this app uses support library UI + elements its interface incorporates material design principles, even though + it is running on Android 4.4, which does not include native support for + material design. +
++ 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 Support + Library's appcompat + library, the 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. +
-
+ In some cases, the support library version of a class depends as much as
+ possible on the functionality that the framework provides. In these cases,
+ if an app calls one of the support class's methods, the support library's
+ behavior depends on what version of Android the app is running on. If the
+ framework provides the necessary functionality, the support library calls on
+ the framework to perform the task. If the app is running on an earlier
+ version of Android, and the framework doesn't expose the needed
+ functionality, the support library may try to provide the functionality
+ itself, or may act as a no-op. In either case, the app generally doesn't
+ need to check what version of Android it's running on; instead, the app
+ can rely on the support library to do those checks and choose appropriate
+ behavior. Generally, classes whose names end in
+ …Compat (like {@link android.support.v4.app.ActivityCompat})
+ behave this way.
+
+ In other cases, the support library class provides a complete, standalone + version of a framework class that does not rely on the availability of + any framework APIs. These + methods provide consistent behavior across all supported platforms. +
+ ++ In either case, the app does not need to check the system version at run + time. The app can rely on the support library class to do the appropriate + system checks, and modify its behavior as necessary. +
+ ++ Support libraries provide user interface elements not offered by + the Android framework. For example, the Android Support Library offers additional + layout classes, like {@link android.support.v4.widget.DrawerLayout}. These + classes follow recommended Android design practices; for example, the Design + Library follows the principles of material design in a way that works across + many versions of Android. +
+ ++ By using these support library classes, you can avoid having to reinvent the + wheel; if your app has a particular user interface requirement, you can draw + on existing code, which provides a user interface that users will already be + familiar with. These elements also help you build an app that looks and feels + like a part of the Android ecosystem. For example, many apps need to display + arbitrarily long lists of elements, and need to be able to quickly and + efficiently reuse those elements as the list changes; this might be a list of + emails, contacts, music albums, and so on. Those apps can use the support + library {@link android.support.v7.widget.RecyclerView} widget to display the + list. This saves the app developer from having to develop the list from + scratch, and also ensures that the user will see a list that looks and + behaves like lists in other apps. +
+ ++ The Android SDK provides libraries for a number of different form factors, + such as TV and wearables. An app can depend on the appropriate support + library to provide functionality across a wide range of platform versions, + and can provide content on external screens, speakers, and other destination + devices. +
+ ++ The Android Support Library provides backward-compatible utility functions. + Apps can use these utility functions to provide an appropriate user + experience across a wide range of Android system versions. For example, + support library permission methods behave appropriately depending on what + platform version your app is running on. If the platform supports the + runtime permissions model, these methods request the appropriate permission + from the user; on platform versions that do not support the runtime + permissions model, the methods check whether the appropriate permission was + granted at install time. +
+ +This section provides details about the Support Library package releases.
diff --git a/docs/image_sources/tools/support-library/appbar-kitkat-orig.png b/docs/image_sources/tools/support-library/appbar-kitkat-orig.png new file mode 100644 index 0000000000000..ab680ce67f754 Binary files /dev/null and b/docs/image_sources/tools/support-library/appbar-kitkat-orig.png differ