1page.title=Maintaining Compatibility
2
3@jd:body
4
5<div id="tb-wrapper">
6<div id="tb">
7<h2>This lesson teaches you to</h2>
8<ol>
9  <li><a href="#Theme">Define Alternative Styles</a></li>
10  <li><a href="#Layouts">Provide Alternative Layouts</a></li>
11  <li><a href="#SupportLib">Use the Support Library</a></li>
12  <li><a href="#CheckVersion">Check the System Version</a></li>
13</ol>
14<h2>You should also read</h2>
15<ul>
16  <li><a href="http://www.google.com/design/spec">Material design specification</a></li>
17  <li><a href="{@docRoot}design/material/index.html">Material design on Android</a></li>
18</ul>
19</div>
20</div>
21
22
23<p>Some material design features like the material theme and custom activity transitions are
24only available on Android 5.0 (API level 21) and above. However, you can design your apps to make
25use of these features when running on devices that support material design and still be compatible
26with devices running previous releases of Android.</p>
27
28
29<h2 id="Theme">Define Alternative Styles</h2>
30
31<p>You can configure your app to use the material theme on devices that support it and revert
32to an older theme on devices running earlier versions of Android:</p>
33
34<ol>
35<li>Define a theme that inherits from an older theme (like Holo) in
36    <code>res/values/styles.xml</code>.</li>
37<li>Define a theme with the same name that inherits from the material theme in
38    <code>res/values-v21/styles.xml</code>.</li>
39<li>Set this theme as your app's theme in the manifest file.</li>
40</ol>
41
42<p class="note"><strong>Note:</strong>
43If your app uses the material theme but does not provide an alternative theme in this manner,
44your app will not run on versions of Android earlier than 5.0.
45</p>
46
47
48<h2 id="Layouts">Provide Alternative Layouts</h2>
49
50<p>If the layouts that you design according to the material design guidelines do not use any of
51the new XML attributes introduced in Android 5.0 (API level 21), they will work on previous
52versions of Android. Otherwise, you can provide alternative layouts. You can also provide
53alternative layouts to customize how your app looks on earlier versions of Android.</p>
54
55<p>Create your layout files for Android 5.0 (API level 21) inside <code>res/layout-v21/</code> and
56your alternative layout files for earlier versions of Android inside <code>res/layout/</code>.
57For example, <code>res/layout/my_activity.xml</code> is an alternative layout for
58<code>res/layout-v21/my_activity.xml</code>.</p>
59
60<p>To avoid duplication of code, define your styles inside <code>res/values/</code>, modify the
61styles in <code>res/values-v21/</code> for the new APIs, and use style inheritance, defining base
62styles in <code>res/values/</code> and inheriting from those in <code>res/values-v21/</code>.</p>
63
64
65<h2 id="SupportLib">Use the Support Library</h2>
66
67<p>The <a href="{@docRoot}tools/support-library/features.html#v7">v7 Support Libraries</a>
68r21 and above includes the following material design features:</p>
69
70<ul>
71<li><a href="{@docRoot}training/material/theme.html">Material design styles</a> for some system
72    widgets when you apply one of the <code>Theme.AppCompat</code> themes.</li>
73<li><a href="{@docRoot}training/material/theme.html#ColorPalette">Color palette theme attributes</a>
74    in the <code>Theme.AppCompat</code> themes.</li>
75<li>The {@link android.support.v7.widget.RecyclerView} widget to <a
76    href="{@docRoot}training/material/lists-cards.html#RecyclerView">display data
77    collections</a>.</li>
78<li>The {@link android.support.v7.widget.CardView} widget to <a
79    href="{@docRoot}training/material/lists-cards.html#CardView">create cards</a>.</li>
80<li>The {@link android.support.v7.graphics.Palette} class to <a
81    href="{@docRoot}training/material/drawables.html#ColorExtract">extract prominent colors from
82    images</a>.</li>
83</ul>
84
85<h3>System widgets</h3>
86
87<p>The <code>Theme.AppCompat</code> themes provide material design styles for these widgets:</p>
88
89<ul>
90  <li>{@link android.widget.EditText}</li>
91  <li>{@link android.widget.Spinner}</li>
92  <li>{@link android.widget.CheckBox}</li>
93  <li>{@link android.widget.RadioButton}</li>
94  <li>{@link android.support.v7.widget.SwitchCompat}</li>
95  <li>{@link android.widget.CheckedTextView}</li>
96</ul>
97
98<h3>Color Palette</h3>
99
100<p>To obtain material design styles and customize the color palette with the Android v7 Support
101Library, apply one of the <code>Theme.AppCompat</code> themes:</p>
102
103<pre>
104&lt;!-- extend one of the Theme.AppCompat themes -->
105&lt;style name="Theme.MyTheme" parent="Theme.AppCompat.Light">
106    &lt;!-- customize the color palette -->
107    &lt;item name="colorPrimary">@color/material_blue_500&lt;/item>
108    &lt;item name="colorPrimaryDark">@color/material_blue_700&lt;/item>
109    &lt;item name="colorAccent">@color/material_green_A200&lt;/item>
110&lt;/style>
111</pre>
112
113<h3>Lists and Cards</h3>
114
115<p>The {@link android.support.v7.widget.RecyclerView} and {@link
116android.support.v7.widget.CardView} widgets are available in earlier versions of Android through
117the Android v7 Support Library with these limitations:</p>
118<ul>
119<li>{@link android.support.v7.widget.CardView} falls back to a programmatic shadow implementation
120    using additional padding.</li>
121<li>{@link android.support.v7.widget.CardView} does not clip its children views that intersect
122    with rounded corners.</li>
123</ul>
124
125
126<h3>Dependencies</h3>
127
128<p>To use these features in versions of Android earlier than 5.0 (API level 21), include the
129Android v7 Support Library in your project as a <a
130href="{@docRoot}/sdk/installing/studio-build.html#dependencies">Gradle dependency</a>:</p>
131
132<pre>
133dependencies {
134    compile 'com.android.support:appcompat-v7:21.0.+'
135    compile 'com.android.support:cardview-v7:21.0.+'
136    compile 'com.android.support:recyclerview-v7:21.0.+'
137}
138</pre>
139
140
141<h2 id="CheckVersion">Check the System Version</h2>
142
143<p>The following features are available only in Android 5.0 (API level 21) and above:</p>
144
145<ul>
146<li>Activity transitions</li>
147<li>Touch feedback</li>
148<li>Reveal animations</li>
149<li>Path-based animations</li>
150<li>Vector drawables</li>
151<li>Drawable tinting</li>
152</ul>
153
154<p>To preserve compatibility with earlier versions of Android, check the system {@link
155android.os.Build.VERSION#SDK_INT version} at runtime before you invoke the APIs for any of these
156features:</p>
157
158<pre>
159// Check if we're running on Android 5.0 or higher
160if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
161    // Call some material design APIs here
162} else {
163    // Implement this feature without material design
164}
165</pre>
166
167<p class="note"><strong>Note:</strong> To specify which versions of Android your app supports,
168use the <code>android:minSdkVersion</code> and <code>android:targetSdkVersion</code>
169attributes in your manifest file. To use the material design features in Android 5.0, set
170the <code>android:targetSdkVersion</code> attribute to <code>21</code>. For more information, see
171the <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">&lt;uses-sdk&gt; API
172guide</a>.</p>
173