1page.title=Support Library
2page.metaDescription=The Android Support Library offers backward-compatible versions of a number of features that are not built into the framework.
3
4@jd:body
5
6<div id="qv-wrapper">
7  <div id="qv">
8
9    <h2>In this document</h2>
10    <ol>
11      <li><a href="#overview">Overview</a></li>
12      <li><a href="#backward">Backward Compatibility</a></li>
13      <li><a href="#layout-patterns">Support for General Layout Patterns</a></li>
14      <li><a href="#form-factors">Support for Different Form Factors</a></li>
15      <li><a href="#utils">General Utilities</a></li>
16    </ol>
17
18    <h2>See also</h2>
19    <ol>
20      <li><a href="{@docRoot}topic/libraries/support-library/features.html">
21        Support Library Features</a></li>
22      <li><a href="{@docRoot}topic/libraries/support-library/setup.html">
23        Support Library Setup</a></li>
24      <li><a href="{@docRoot}topic/libraries/support-library/revisions.html">
25        Support Library Revision History</a></li>
26
27    </ol>
28
29  </div>
30</div>
31
32<p>
33  The Android Support Library offers a number of features that are not built
34  into the framework. These libraries offer backward-compatible versions of
35  new features, provide useful UI elements that are not included in the
36  framework, and provide a range of utilities that apps can draw on.
37</p>
38
39<h2 id="overview">Overview</h2>
40
41<p>
42  In many cases, a feature may be valuable to many app developers, but not
43  appropriate to include in the Android framework itself. For example, an app
44  might only need a feature for specialized use cases, such as to smooth the
45  transition between different versions of the Android system.
46</p>
47
48<p>
49  To address these situations, the Android SDK includes several libraries
50  collectively called the <em>Android Support Library</em>. App developers
51  can include any of these libraries if they want to incorporate the
52  library functionality into their apps.
53</p>
54
55<p>
56  Support libraries provide a range of different features:
57</p>
58
59<ul>
60  <li>
61    <a href="#backward">Backward-compatible</a> versions of framework
62    components.
63  </li>
64
65  <li>UI elements to implement the recommended Android <a href=
66  "#layout-patterns">layout patterns</a>.
67  </li>
68
69  <li>Support for different <a href="#form-factors">form factors</a>.
70  </li>
71
72  <li>Miscellaneous <a href="#utils">utility</a> functions.
73  </li>
74</ul>
75
76<h2 id="backward">Backward Compatibility</h2>
77
78<div class="figure" style="width:300px">
79  <img src="{@docRoot}images/tools/support-library/appbar-kitkat.png"
80    srcset="{@docRoot}images/tools/support-library/appbar-kitkat.png 1x,
81        {@docRoot}images/tools/support-library/appbar-kitkat_2x.png 2x"
82    alt="" width="300">
83  <p class="img-caption">
84    <strong>Figure 1.</strong> Because this app uses support library UI
85    elements its interface incorporates material design principles, even though
86    it is running on Android 4.4, which does not include native support for
87    material design.
88  </p>
89</div>
90
91<p>
92  Support libraries allow apps running on older versions of the Android
93  platform to support features made available on newer versions of the
94  platform. For example, an app running on a version of Android lower than 5.0
95  (API level 21) that relies on framework classes cannot display
96  material-design elements, as that version of the Android framework doesn't
97  support material design. However, if the app incorporates the Support
98  Library's <a href="{@docRoot}tools/support-library/features.html">appcompat
99  library</a>, the app has access to many of the features available in API
100  level 21, including support for material design. As a result, your app can
101  deliver a more consistent experience across a broader range of platform
102  versions.
103</p>
104
105
106<p>
107  In some cases, the support library version of a class depends as much as
108  possible on the functionality that the framework provides. In these cases,
109  if an app calls one of the support class's methods, the support library's
110  behavior depends on what version of Android the app is running on. If the
111  framework provides the necessary functionality, the support library calls on
112  the framework to perform the task. If the app is running on an earlier
113  version of Android, and the framework doesn't expose the needed
114  functionality, the support library may try to provide the functionality
115  itself, or may act as a no-op. In either case, the app generally doesn't
116  need to check what version of Android it's running on; instead, the app
117  can rely on the support library to do those checks and choose appropriate
118  behavior. Generally, classes whose names end in
119  <code>…Compat</code> (like {@link android.support.v4.app.ActivityCompat})
120  behave this way.
121</p>
122
123<p>
124  In other cases, the support library class provides a complete, standalone
125  version of a framework class that does not rely on the availability of
126  any framework APIs. These
127  methods provide consistent behavior across all supported platforms.
128</p>
129
130<p>
131  In either case, the app does not need to check the system version at run
132  time. The app can rely on the support library class to do the appropriate
133  system checks, and modify its behavior as necessary.
134</p>
135
136<h2 id="layout-patterns">Support for General Layout Patterns</h2>
137
138<p>
139  Support libraries provide user interface elements not offered by
140  the Android framework. For example, the Android Support Library offers additional
141  layout classes, like {@link android.support.v4.widget.DrawerLayout}. These
142  classes follow recommended Android design practices; for example, the Design
143  Library follows the principles of material design in a way that works across
144  many versions of Android.
145</p>
146
147<p>
148  By using these support library classes, you can avoid having to reinvent the
149  wheel; if your app has a particular user interface requirement, you can draw
150  on existing code, which provides a user interface that users will already be
151  familiar with. These elements also help you build an app that looks and feels
152  like a part of the Android ecosystem. For example, many apps need to display
153  arbitrarily long lists of elements, and need to be able to quickly and
154  efficiently reuse those elements as the list changes; this might be a list of
155  emails, contacts, music albums, and so on. Those apps can use the support
156  library {@link android.support.v7.widget.RecyclerView} widget to display the
157  list. This saves the app developer from having to develop the list from
158  scratch, and also ensures that the user will see a list that looks and
159  behaves like lists in other apps.
160</p>
161
162<h2 id="form-factors">Support for Different Form Factors</h2>
163
164<p>
165  The Android SDK provides libraries for a number of different form factors,
166  such as TV and wearables. An app can depend on the appropriate support
167  library to provide functionality across a wide range of platform versions,
168  and can provide content on external screens, speakers, and other destination
169  devices.
170</p>
171
172<h2 id="utils">General Utilities</h2>
173
174<p>
175  The Android Support Library provides backward-compatible utility functions.
176  Apps can use these utility functions to provide an appropriate user
177  experience across a wide range of Android system versions. For example,
178  support library permission methods behave appropriately depending on what
179  platform version your app is running on. If the platform supports the
180  runtime permissions model, these methods request the appropriate permission
181  from the user; on platform versions that do not support the runtime
182  permissions model, the methods check whether the appropriate permission was
183  granted at install time.
184</p>
185