1page.title=Supporting Different Platform Versions
2page.metaDescription=Training on how to declare support for minimum and target API levels.
3page.tags=styles
4helpoutsWidget=true
5
6trainingnavtop=true
7
8@jd:body
9
10
11<div id="tb-wrapper">
12  <div id="tb">
13
14    <h2>This lesson teaches you to</h2>
15    <ol>
16      <li><a href="#sdk-versions">Specify Minimum and Target API Levels</a></li>
17      <li><a href="#version-codes">Check System Version at Runtime</a></li>
18      <li><a href="#style-themes">Use Platform Styles and Themes</a></li>
19    </ol>
20
21    <h2>You should also read</h2>
22    <ul>
23      <li><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#ApiLevels">Android API Levels</a></li>
24      <li><a
25href="{@docRoot}tools/support-library/index.html">Android Support Library</a></li>
26    </ul>
27  </div>
28</div>
29
30<p>While the latest versions of Android often provide great APIs for your app, you should continue
31to support older versions of Android until more devices get updated. This
32lesson shows you how to take advantage of the latest APIs while continuing to support older
33versions as well.</p>
34
35<p>The dashboard for <a
36href="http://developer.android.com/about/dashboards/index.html">Platform Versions</a>
37is updated regularly to show the distribution of active
38devices running each version of Android, based on the number of devices that visit the Google Play
39Store.  Generally, it’s a good practice to support about 90% of the active devices, while
40targeting your app to the latest version.</p>
41
42<p class="note"><strong>Tip:</strong> In order to provide the best features and
43functionality across several Android versions, you should use the <a
44href="{@docRoot}tools/support-library/index.html">Android Support Library</a> in your app,
45which allows you to use several recent platform APIs on older versions.</p>
46
47
48
49<h2 id="sdk-versions">Specify Minimum and Target API Levels</h2>
50
51<p>The <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a> file
52describes details about your app and
53identifies which versions of Android it supports.   Specifically, the <code>minSdkVersion</code>
54and <code>targetSdkVersion</code> attributes for the <a
55href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code <uses-sdk>}</a> element
56identify the lowest API level with which your app is compatible and the highest API level against
57which you’ve designed and tested your app.</p>
58
59<p>For example:</p>
60
61<pre>
62&lt;manifest xmlns:android="http://schemas.android.com/apk/res/android" ... >
63    &lt;uses-sdk android:minSdkVersion="4" android:targetSdkVersion="15" />
64    ...
65&lt;/manifest>
66</pre>
67
68<p>As new versions of Android are released, some style and behaviors may change.
69To allow your app to take advantage of these changes and ensure that your app fits the style of
70each user's device, you should set the
71<a
72href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a>
73value to match the latest Android version
74available.</p>
75
76
77
78<h2 id="version-codes">Check System Version at Runtime</h2>
79
80<p>Android provides a unique code for each platform version in the {@link android.os.Build}
81constants class. Use these codes within your app to build conditions that ensure the code that
82depends on higher API levels is executed only when those APIs are available on the system.</p>
83
84<pre>
85private void setUpActionBar() {
86    // Make sure we're running on Honeycomb or higher to use ActionBar APIs
87    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.HONEYCOMB) {
88        ActionBar actionBar = getActionBar();
89        actionBar.setDisplayHomeAsUpEnabled(true);
90    }
91}
92</pre>
93
94
95
96<p class="note"><strong>Note:</strong> When parsing XML resources, Android ignores XML
97attributes that aren’t supported by the current device. So you can safely use XML attributes that
98are only supported by newer versions without worrying about older versions breaking when they
99encounter that code. For example, if you set the
100<code>targetSdkVersion="11"</code>, your app includes the {@link android.app.ActionBar} by default
101on Android 3.0 and higher. To then add menu items to the action bar, you need to set
102<code>android:showAsAction="ifRoom"</code> in your menu resource XML. It's safe to do this
103in a cross-version XML file, because the older versions of Android simply ignore the
104<code>showAsAction</code> attribute (that is, you <em>do not</em> need a separate
105version in <code>res/menu-v11/</code>).</p>
106
107
108
109<h2 id="style-themes">Use Platform Styles and Themes</h2>
110
111<p>Android provides user experience themes that give apps the look and feel of the
112underlying operating system.  These themes can be applied to your app within the
113manifest file.  By using these built in styles and themes, your app will
114naturally follow the latest look and feel of Android with each new release.</p>
115
116<p>To make your activity look like a dialog box:</p>
117
118<pre>&lt;activity android:theme="@android:style/Theme.Dialog"></pre>
119
120<p>To make your activity have a transparent background:</p>
121
122<pre>&lt;activity android:theme="@android:style/Theme.Translucent"></pre>
123
124<p>To apply your own custom theme defined in <code>/res/values/styles.xml</code>:</p>
125
126<pre>&lt;activity android:theme="@style/CustomTheme"></pre>
127
128<p>To apply a theme to your entire app (all activities), add the <code>android:theme</code>
129attribute
130to the <a href="{@docRoot}guide/topics/manifest/application-element.html">{@code
131<application>}</a> element:</p>
132
133<pre>&lt;application android:theme="@style/CustomTheme"></pre>
134
135<p>For more about creating and using themes, read the <a
136href="{@docRoot}guide/topics/ui/themes.html">Styles and Themes</a> guide.</p>
137
138