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