docs: Add 101 class about supporting various devices
Change-Id: Iafeb99c9dab8462236a41cc4991085062ff7fa14
diff --git a/docs/html/training/basics/supporting-devices/index.jd b/docs/html/training/basics/supporting-devices/index.jd
new file mode 100644
index 0000000..49ea81d
--- /dev/null
+++ b/docs/html/training/basics/supporting-devices/index.jd
@@ -0,0 +1,49 @@
+page.title=Supporting Different Devices
+
+trainingnavtop=true
+startpage=true
+next.title=Supporting Multiple Languages
+next.link=languages.html
+
+@jd:body
+
+<div id="tb-wrapper">
+<div id="tb">
+
+<h2>Dependencies and prerequisites</h2>
+<ul>
+ <li>Android 1.6 or higher</li>
+</ul>
+
+<h2>You should also read</h2>
+<ul>
+ <li><a href="{@docRoot}guide/topics/resources/index.html">Application Resources</a></li>
+ <li><a href="{@docRoot}training/multiscreen/index.html">Designing for Multiple Screens</a></li>
+</ul>
+
+
+</div>
+</div>
+
+<p>Android devices come in many shapes and sizes all around the world. With a wide range of device
+types, you have an opportunity to reach a huge audience with your app. In order to be as successful
+as possible on Android, your app needs to adapt to various device configurations. Some of the
+important variations that you should consider include different languages, screen sizes, and
+versions of the Android platform.</p>
+
+<p>This class teaches you how to use basic platform features that leverage alternative
+resources and other features so your app can provide an optimized user experience on a
+variety of Android-compatible devices, using a single application package (APK).</p>
+
+<h2>Lessons</h2>
+
+<dl>
+ <dt><b><a href="languages.html">Supporting Different Languages</a></b></dt>
+ <dd>Learn how to support multiple languages with alternative string resources.</dd>
+ <dt><b><a href="screens.html">Supporting Different Screens</a></b></dt>
+ <dd>Learn how to optimize the user experience for different screen sizes and densities.</dd>
+ <dt><b><a href="platforms.html">Supporting Different Platform Versions</a></b></dt>
+ <dd>Learn how to use APIs available in new versions of Android while continuing to support
+older versions of Android.</dd>
+</dl>
+
diff --git a/docs/html/training/basics/supporting-devices/languages.jd b/docs/html/training/basics/supporting-devices/languages.jd
new file mode 100644
index 0000000..fcc95c2
--- /dev/null
+++ b/docs/html/training/basics/supporting-devices/languages.jd
@@ -0,0 +1,134 @@
+page.title=Supporting Different Languages
+parent.title=Supporting Different Devices
+parent.link=index.html
+
+trainingnavtop=true
+next.title=Supporting Different Screens
+next.link=screens.html
+
+@jd:body
+
+
+<div id="tb-wrapper">
+ <div id="tb">
+ <h2>This class teaches you to</h2>
+ <ol>
+ <li><a href="#CreateDirs">Create Locale Directories and String Files</a></li>
+ <li><a href="#UseString">Use the String Resources</a></li>
+ </ol>
+ <h2>You should also read</h2>
+ <ul>
+ <li><a href="{@docRoot}guide/topics/resources/localization.html">Localization</a></li>
+ </ul>
+ </div>
+</div>
+
+<p>It’s always a good practice to extract UI strings from your app code and keep them
+in an external file. Android makes this easy with a resources directory in each Android
+project.</p>
+
+<p>If you created your project using the Android SDK
+Tools (read <a href="{@docRoot}training/basics/firstapp/creating-project.html">Creating an
+Android Project</a>), the tools create a <code>res/</code> directory in the top level of
+the project. Within this <code>res/</code> directory are subdirectories for various resource
+types. There are also a few default files such as <code>res/values/strings.xml</code>, which holds
+your string values.</p>
+
+
+<h2 id="CreateDirs">Create Locale Directories and String Files</h2>
+
+<p>To add support for more languages, create additional <code>values</code> directories inside
+<code>res/</code> that include a hyphen and the ISO country code at the end of the
+directory name. For example, <code>values-es/</code> is the directory containing simple
+resourcess for the Locales with the language code "es". Android loads the appropriate resources
+according to the locale settings of the device at run time.</p>
+
+<p>Once you’ve decided on the languages you will support, create the resource subdirectories and
+string resource files. For example:</p>
+
+<pre class="classic no-pretty-print">
+MyProject/
+ res/
+ values/
+ strings.xml
+ values-es/
+ strings.xml
+ values-fr/
+ strings.xml
+</pre>
+
+<p>Add the string values for each locale into the appropriate file.</p>
+
+<p>At runtime, the Android system uses the appropriate set of string resources based on the
+locale currently set for the user's device.</p>
+
+<p>For example, the following are some different string resource files for different languages.</p>
+
+
+<p>English (default locale), <code>/values/strings.xml</code>:</p>
+
+<pre>
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+ <string name="title">My Application</string>
+ <string name="hello_world">Hello World!</string>
+</resources>
+</pre>
+
+
+<p>Spanish, <code>/values-es/strings.xml</code>:</p>
+
+<pre>
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+ <string name="title">Mi Aplicación</string>
+ <string name="hello_world">Hola Mundo!</string>
+</resources>
+</pre>
+
+
+<p>French, <code>/values-fr/strings.xml</code>:</p>
+
+<pre>
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+ <string name="title">Ma Application</string>
+ <string name="hello_world">Bonjour tout le Monde!</string>
+</resources>
+</pre>
+
+
+<h2 id="UseString">Use the String Resources</h2>
+
+<p>You can reference your string resources in your source code and other XML files using the
+resource name defined by the {@code <string>} element's {@code name} attribute.</p>
+
+<p>In your source code, you can refer to a string resource with the syntax {@code
+R.string.<string_name>}. There are a variety of methods that accept a string resource this
+way.</p>
+
+<p>For example:</p>
+
+<pre>
+// Get a string resource from your app's {@link android.content.res.Resources}
+String hello = {@link android.content.Context#getResources()}.getString(R.string.hello_world);
+
+// Or supply a string resource to a method that requires a string
+TextView textView = new TextView(this);
+textView.setText(R.string.hello_world);
+</pre>
+
+<p>In other XML files, you can refer to a string resource with the syntax {@code
+@string/<string_name>} whenever the XML attribute accepts a string value.</p>
+
+<p>For example:</p>
+
+<pre>
+<TextView
+ android:layout_width="wrap_content"
+ android:layout_height="wrap_content"
+ android:text="@string/hello_world" />
+</pre>
+
+
+
diff --git a/docs/html/training/basics/supporting-devices/platforms.jd b/docs/html/training/basics/supporting-devices/platforms.jd
new file mode 100644
index 0000000..0d4e7d9
--- /dev/null
+++ b/docs/html/training/basics/supporting-devices/platforms.jd
@@ -0,0 +1,138 @@
+page.title=Supporting Different Platform Versions
+parent.title=Supporting Different Devices
+parent.link=index.html
+
+trainingnavtop=true
+previous.title=Supporting Different Screens
+previous.link=screens.html
+
+@jd:body
+
+
+<div id="tb-wrapper">
+ <div id="tb">
+
+ <h2>This lesson teaches you to</h2>
+ <ol>
+ <li><a href="#sdk-versions">Specify Minimum and Target API Levels</a></li>
+ <li><a href="#version-codes">Check System Version at Runtime</a></li>
+ <li><a href="#style-themes">Use Platform Styles and Themes</a></li>
+ </ol>
+
+ <h2>You should also read</h2>
+ <ul>
+ <li><a href="{@docRoot}guide/appendix/api-levels.html">Android API Levels</a></li>
+ <li><a
+href="{@docRoot}sdk/compatibility-library.html">Android Support Library</a></li>
+ </ul>
+ </div>
+</div>
+
+<p>While the latest versions of Android often provide great APIs for your app, you should continue
+to support older versions of Android until more devices get updated. This
+lesson shows you how to take advantage of the latest APIs while continuing to support older
+versions as well.</p>
+
+<p>The dashboard for <a
+href="http://developer.android.com/resources/dashboard/platform-versions.html">Platform Versions</a>
+is updated regularly to show the distribution of active
+devices running each version of Android, based on the number of devices that visit the Google Play
+Store. Generally, it’s a good practice to support about 90% of the active devices, while
+targeting your app to the latest version.</p>
+
+<p class="note"><strong>Tip:</strong> In order to provide the best features and
+functionality across several Android versions, you should use the <a
+href="{@docRoot}sdk/compatibility-library.html">Android Support Library</a> in your app,
+which allows you to use several recent platform APIs on older versions.</p>
+
+
+
+<h2 id="sdk-versions">Specify Minimum and Target API Levels</h2>
+
+<p>The <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a> file
+describes details about your app and
+identifies which versions of Android it supports. Specifically, the <code>minSdkVersion</code>
+and <code>targetSdkVersion</code> attributes for the <a
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code <uses-sdk}</a> element
+identify the lowest API level with which your app is compatible and the highest API level against
+which you’ve designed and tested your app.</p>
+
+<p>For example:</p>
+
+<pre>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" ... >
+ <uses-sdk android:minSdkVersion="4" android:targetSdkVersion="15" />
+ ...
+</manifest>
+</pre>
+
+<p>As new versions of Android are released, some style and behaviors may change.
+To allow your app to take advantage of these changes and ensure that your app fits the style of
+each user's device, you should set the
+<a
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a>
+value to match the latest Android version
+available.</p>
+
+
+
+<h2 id="version-codes">Check System Version at Runtime</h2>
+
+<p>Android provides a unique code for each platform version in the {@link android.os.Build}
+constants class. Use these codes within your app to build conditions that ensure the code that
+depends on higher API levels is executed only when those APIs are available on the system.</p>
+
+<pre>
+private void setUpActionBar() {
+ // Make sure we're running on Honeycomb or higher to use ActionBar APIs
+ if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.HONEYCOMB) {
+ ActionBar actionBar = getActionBar();
+ actionBar.setDisplayHomeAsUpEnabled(true);
+ }
+}
+</pre>
+
+
+
+<p class="note"><strong>Note:</strong> When parsing XML resources, Android ignores XML
+attributes that aren’t supported by the current device. So you can safely use XML attributes that
+are only supported by newer versions without worrying about older versions breaking when they
+encounter that code. For example, if you set the
+<code>targetSdkVersion="11"</code>, your app includes the {@link android.app.ActionBar} by default
+on Android 3.0 and higher. To then add menu items to the action bar, you need to set
+<code>android:showAsAction="ifRoom"</code> in your menu resource XML. It's safe to do this
+in a cross-version XML file, because the older versions of Android simply ignore the
+<code>showAsAction</code> attribute (that is, you <em>do not</em> need a separate
+version in <code>res/menu-v11/</code>).</p>
+
+
+
+<h2 id="style-themes">Use Platform Styles and Themes</h2>
+
+<p>Android provides user experience themes that give apps the look and feel of the
+underlying operating system. These themes can be applied to your app within the
+manifest file. By using these built in styles and themes, your app will
+naturally follow the latest look and feel of Android with each new release.</p>
+
+<p>To make your activity look like a dialog box:</p>
+
+<pre><activity android:theme="@android:style/Theme.Dialog"></pre>
+
+<p>To make your activity have a transparent background:</p>
+
+<pre><activity android:theme="@android:style/Theme.Translucent"></pre>
+
+<p>To apply your own custom theme defined in <code>/res/values/styles.xml</code>:</p>
+
+<pre><activity android:theme="@style/CustomTheme"></pre>
+
+<p>To apply a theme to your entire app (all activities), add the <code>android:theme</code>
+attribute
+to the <a href="{@docRoot}guide/topics/manifest/application-element.html">{@code
+<application>}</a> element:</p>
+
+<pre><application android:theme="@style/CustomTheme"></pre>
+
+<p>For more about creating and using themes, read the <a
+href="{@docRoot}guide/topics/ui/themes.html">Styles and Themes</a> guide.</p>
+
diff --git a/docs/html/training/basics/supporting-devices/screens.jd b/docs/html/training/basics/supporting-devices/screens.jd
new file mode 100644
index 0000000..8697cd5
--- /dev/null
+++ b/docs/html/training/basics/supporting-devices/screens.jd
@@ -0,0 +1,180 @@
+page.title=Supporting Different Screens
+parent.title=Supporting Different Devices
+parent.link=index.html
+
+trainingnavtop=true
+previous.title=Supporting Different Languages
+previous.link=languages.html
+next.title=Supporting Different Platform Versions
+next.link=platforms.html
+
+@jd:body
+
+<div id="tb-wrapper">
+ <div id="tb">
+
+ <h2>This lesson teaches you to</h2>
+ <ol>
+ <li><a href="#create-layouts">Create Different Layouts</a></li>
+ <li><a href="#create-bitmaps">Create Different Bitmaps</a></li>
+ </ol>
+
+ <h2>You should also read</h2>
+ <ul>
+ <li><a href="{@docRoot}training/multiscreen/index.html">Designing for Multiple
+Screens</a></li>
+ <li><a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple
+Screens</a></li>
+ <li><a href="{@docRoot}design/style/iconography.html">Iconography design guide</a></li>
+ </ul>
+ </div>
+</div>
+
+<p>Android categorizes device screens using two general properties: size and density. You should
+expect that your app will be installed on devices with screens that range in both size
+and density. As such, you should include some alternative resources that optimize your app’s
+appearance for different screen sizes and densities.</p>
+
+<ul>
+ <li>There are four generalized sizes: small, normal, large, xlarge</li>
+ <li>And four generalized densities: low (ldpi), medium (mdpi), high (hdpi), extra high
+(xhdpi)</li>
+</ul>
+
+<p>To declare different layouts and bitmaps you'd like to use for different screens, you must place
+these alternative resources in separate directories, similar to how you do for different language
+strings.</p>
+
+<p>Also be aware that the screens orientation (landscape or portrait) is considered a variation of
+screen size, so many apps should revise the layout to optimize the user experience in each
+orientation.</p>
+
+
+<h2 id="create-layouts">Create Different Layouts</h2>
+
+<p>To optimize your user experience on different screen sizes, you should create a unique layout XML
+file for each screen size you want to support. Each layout should be
+saved into the appropriate resources directory, named with a <code>-<screen_size></code>
+suffix. For example, a unique layout for large screens should be saved under
+<code>res/layout-large/</code>.</p>
+
+<p class="note"><strong>Note:</strong> Android automatically scales your layout in order to
+properly fit the screen. Thus, your layouts for different screen sizes don't
+need to worry about the absolute size of UI elements but instead focus on the layout structure that
+affects the user experience (such as the size or position of important views relative to sibling
+views).</p>
+
+<p>For example, this project includes a default layout and an alternative layout for <em>large</em>
+screens:</p>
+
+<pre class="classic no-pretty-print">
+MyProject/
+ res/
+ layout/
+ main.xml
+ layout-large/
+ main.xml
+</pre>
+
+<p>The file names must be exactly the same, but their contents are different in order to provide
+an optimized UI for the corresponding screen size.</p>
+
+<p>Simply reference the layout file in your app as usual:</p>
+
+<pre>
+@Override
+ protected void onCreate(Bundle savedInstanceState) {
+ super.onCreate(savedInstanceState);
+ setContentView(R.layout.main);
+}
+</pre>
+
+<p>The system loads the layout file from the appropriate layout directory based on screen size of
+the device on which your app is running. More information about how Android selects the
+appropriate resource is available in the <a
+href="{@docRoot}guide/topics/resources/providing-resources.html#BestMatch">Providing Resources</a>
+guide.</p>
+
+<p>As another example, here's a project with an alternative layout for landscape orientation:</p>
+
+<pre class="classic no-pretty-print">
+MyProject/
+ res/
+ layout/
+ main.xml
+ layout-land/
+ main.xml
+</pre>
+
+<p>By default, the <code>layout/main.xml</code> file is used for portrait orientation.</p>
+
+<p>If you want a provide a special layout for landscape, including while on large screens, then
+you need to use both the <code>large</code> and <code>land</code> qualifier:</p>
+
+<pre class="classic no-pretty-print">
+MyProject/
+ res/
+ layout/ # default (portrait)
+ main.xml
+ layout-land/ # landscape
+ main.xml
+ layout-large/ # large (portrait)
+ main.xml
+ layout-large-land/ # large landscape
+ main.xml
+</pre>
+
+<p class="note"><strong>Note:</strong> Android 3.2 and above supports an advanced method of
+defining screen sizes that allows you to specify resources for screen sizes based on
+the minimum width and height in terms of density-independent pixels. This lesson does not cover
+this new technique. For more information, read <a
+href="{@docRoot}training/multiscreen/index.html">Designing for Multiple
+Screens</a>.</p>
+
+
+
+<h2 id="create-bitmaps">Create Different Bitmaps</h2>
+
+<p>You should always provide bitmap resources that are properly scaled to each of the generalized
+density buckets: low, medium, high and extra-high density. This helps you achieve good graphical
+quality and performance on all screen densities.</p>
+
+<p>To generate these images, you should start with your raw resource in vector format and generate
+the images for each density using the following size scale:</p>
+<ul>
+<li>xhdpi: 2.0</li>
+<li>hdpi: 1.5</li>
+<li>mdpi: 1.0 (baseline)</li>
+<li>ldpi: 0.75</li>
+</ul>
+
+<p>This means that if you generate a 200x200 image for xhdpi devices, you should generate the same
+resource in 150x150 for hdpi, 100x100 for mdpi, and 75x75 for ldpi devices.</p>
+
+<p>Then, place the files in the appropriate drawable resource directory:</p>
+
+<pre class="classic no-pretty-print">
+MyProject/
+ res/
+ drawable-xhdpi/
+ awesomeimage.png
+ drawable-hdpi/
+ awesomeimage.png
+ drawable-mdpi/
+ awesomeimage.png
+ drawable-ldpi/
+ awesomeimage.png
+</pre>
+
+<p>Any time you reference <code>@drawable/awesomeimage</code>, the system selects the
+appropriate bitmap based on the screen's density.</p>
+
+<p class="note"><strong>Note:</strong> Low-density (ldpi) resources aren’t always necessary. When
+you provide hdpi assets, the system scales them down by one half to properly fit ldpi
+screens.</p>
+
+<p>For more tips and guidelines about creating icon assets for your app, see the
+<a href="{@docRoot}design/style/iconography.html">Iconography design guide</a>.</p>
+
+
+