am 14d3b807: am a5894871: Merge "docs: Add 101 class about supporting various devices" into ics-mr1

* commit '14d3b807b730e04d90d6dd9c9569decdf12cc9cb':
  docs: Add 101 class about supporting various devices

4 files changed, 501 insertions, 0 deletions

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>
+&lt;?xml version="1.0" encoding="utf-8"?>
+&lt;resources>
+    &lt;string name="title">My Application&lt;/string>
+    &lt;string name="hello_world">Hello World!&lt;/string>
+&lt;/resources>
+</pre>
+
+
+<p>Spanish, <code>/values-es/strings.xml</code>:</p>
+
+<pre>
+&lt;?xml version="1.0" encoding="utf-8"?>
+&lt;resources>
+    &lt;string name="title">Mi Aplicación&lt;/string>
+    &lt;string name="hello_world">Hola Mundo!&lt;/string>
+&lt;/resources>
+</pre>
+
+
+<p>French, <code>/values-fr/strings.xml</code>:</p>
+
+<pre>
+&lt;?xml version="1.0" encoding="utf-8"?>
+&lt;resources>
+    &lt;string name="title">Ma Application&lt;/string>
+    &lt;string name="hello_world">Bonjour tout le Monde!&lt;/string>
+&lt;/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 &lt;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.&lt;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
+&#64;string/&lt;string_name>} whenever the XML attribute accepts a string value.</p>
+
+<p>For example:</p>
+
+<pre>
+&lt;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 &lt;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>
+&lt;manifest xmlns:android="http://schemas.android.com/apk/res/android" ... >
+    &lt;uses-sdk android:minSdkVersion="4" android:targetSdkVersion="15" />
+    ...
+&lt;/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>&lt;activity android:theme="@android:style/Theme.Dialog"></pre>
+
+<p>To make your activity have a transparent background:</p>
+
+<pre>&lt;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>&lt;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
+&lt;application>}</a> element:</p>
+
+<pre>&lt;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>-&lt;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>
+&#64;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>
+
+
+