Merge "docs: Updated support library overview" into mnc-mr-docs

4 files changed, 156 insertions, 30 deletions

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 000000000000..c89fd87d667f
--- /dev/null
+++ b/docs/html/images/tools/support-library/appbar-kitkat.png
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 000000000000..c9718e6f548e
--- /dev/null
+++ b/docs/html/images/tools/support-library/appbar-kitkat_2x.png
diff --git a/docs/html/tools/support-library/index.jd b/docs/html/tools/support-library/index.jd
index a9390b0dae80..64d43b80975f 100644
--- a/docs/html/tools/support-library/index.jd
+++ b/docs/html/tools/support-library/index.jd
@@ -8,7 +8,11 @@ page.title=Support Library
     <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 @@ page.title=Support Library
   </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>
+  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>
 
-<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>
+<h2 id="overview">Overview</h2>
 
+<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>
 
-<h2 id="overview">Overview</h2>
+<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>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>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>
-
-
-<h2 id="revisions">Revisions</h2>
+<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>
+
+
+<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 000000000000..ab680ce67f75
--- /dev/null
+++ b/docs/image_sources/tools/support-library/appbar-kitkat-orig.png