docs: Updated support library overview, CPd from mnc-mr-docs
Started this CL when mnc-mr-docs was the active branch, but now
the production builds come from mnc-docs.
Per feedback from the support library team, updated the support
library overview page to better explain what the libraries are
and what they're for. This is the beginning of a big overhaul of the
support library docs.
The "overview" section has been rewritten and expanded in this CL.
The "revisions" section hasn't been touched, except that the heading
was changed to "Support Library Revision History". (I'd like to
move "Revision History" to a separate page, but I'll do it in a
follow-on CL.)
See first comment for doc stage location.
bug: 27274455
Change-Id: I12ce21c948421e1bd0be5d3151845f900750e7b1
(cherry picked from commit 06ba3db93849a45df571c4730aa7a67e247c0afe)
diff --git a/docs/html/images/tools/support-library/appbar-kitkat.png b/docs/html/images/tools/support-library/appbar-kitkat.png
new file mode 100644
index 0000000..c89fd87
--- /dev/null
+++ b/docs/html/images/tools/support-library/appbar-kitkat.png
Binary files differ
diff --git a/docs/html/images/tools/support-library/appbar-kitkat_2x.png b/docs/html/images/tools/support-library/appbar-kitkat_2x.png
new file mode 100644
index 0000000..c9718e6
--- /dev/null
+++ b/docs/html/images/tools/support-library/appbar-kitkat_2x.png
Binary files differ
diff --git a/docs/html/tools/support-library/index.jd b/docs/html/tools/support-library/index.jd
index a9390b0..64d43b8 100644
--- a/docs/html/tools/support-library/index.jd
+++ b/docs/html/tools/support-library/index.jd
@@ -8,7 +8,11 @@
<h2>In this document</h2>
<ol>
<li><a href="#overview">Overview</a></li>
- <li><a href="#revisions">Revisions</a></li>
+ <li><a href="#backward">Backward Compatibility</a></li>
+ <li><a href="#layout-patterns">Support for General Layout Patterns</a></li>
+ <li><a href="#form-factors">Support for Different Form Factors</a></li>
+ <li><a href="#utils">General Utilities</a></li>
+ <li><a href="#revisions">Support Library Revision History</a></li>
</ol>
<h2>See also</h2>
@@ -22,39 +26,161 @@
</div>
</div>
-<p>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.</p>
-
-<p>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.</p>
-
+<p>
+ 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.
+</p>
<h2 id="overview">Overview</h2>
-<p>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
- <a href="{@docRoot}tools/projects/templates.html">code template</a> tools, you will notice that
- all the Android application templates include one or more of the Support Libraries by default.</p>
+<p>
+ 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.
+</p>
-<p>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
- <a href="{@docRoot}tools/support-library/features.html">Support Library Features</a> guide.
- After that, go to the
- <a href="{@docRoot}tools/support-library/setup.html">Support Library Setup</a> 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.</p>
+<p>
+ To address these situations, the Android SDK includes several libraries
+ collectively called the <em>Android Support Library</em>. App developers
+ can include any of these libraries if they want to incorporate the
+ library functionality into their apps.
+</p>
+
+<p>
+ Support libraries provide a range of different features:
+</p>
+
+<ul>
+ <li>
+ <a href="#backward">Backward-compatible</a> versions of framework
+ components.
+ </li>
+
+ <li>UI elements to implement the recommended Android <a href=
+ "#layout-patterns">layout patterns</a>.
+ </li>
+
+ <li>Support for different <a href="#form-factors">form factors</a>.
+ </li>
+
+ <li>Miscellaneous <a href="#utils">utility</a> functions.
+ </li>
+</ul>
+
+<h2 id="backward">Backward Compatibility</h2>
+
+<div class="figure" style="width:300px">
+ <img src="{@docRoot}images/tools/support-library/appbar-kitkat.png"
+ srcset="{@docRoot}images/tools/support-library/appbar-kitkat.png 1x,
+ {@docRoot}images/tools/support-library/appbar-kitkat_2x.png 2x"
+ alt="" width="300">
+ <p class="img-caption">
+ <strong>Figure 1.</strong> 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.
+ </p>
+</div>
+
+<p>
+ 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 <a href="{@docRoot}tools/support-library/features.html">appcompat
+ library</a>, 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.
+</p>
-<h2 id="revisions">Revisions</h2>
+<p>
+ 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
+ <code>…Compat</code> (like {@link android.support.v4.app.ActivityCompat})
+ behave this way.
+</p>
+
+<p>
+ 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.
+</p>
+
+<p>
+ 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.
+</p>
+
+<h2 id="layout-patterns">Support for General Layout Patterns</h2>
+
+<p>
+ 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.
+</p>
+
+<p>
+ 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.
+</p>
+
+<h2 id="form-factors">Support for Different Form Factors</h2>
+
+<p>
+ 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.
+</p>
+
+<h2 id="utils">General Utilities</h2>
+
+<p>
+ 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.
+</p>
+
+<h2 id="revisions">Support Library Revision History</h2>
<p>This section provides details about the Support Library package releases.</p>
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 0000000..ab680ce
--- /dev/null
+++ b/docs/image_sources/tools/support-library/appbar-kitkat-orig.png
Binary files differ
