drgreen/android_frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
* commit 'a5894871b2a64f8ef80089a8ca962227c4d77155':
  docs: Add 101 class about supporting various devices
This commit is contained in:
Scott Main
2012-04-09 17:08:09 -07:00
committed by Android Git Automerger
parent e1d6c080f0 a5894871b2
commit 14d3b807b7
4 changed files with 501 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
docs/html/training/basics/supporting-devices/index.jd Normal file
View File

@ -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>

134
docs/html/training/basics/supporting-devices/languages.jd Normal file
View File

@ -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>

138
docs/html/training/basics/supporting-devices/platforms.jd Normal file
View File

@ -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>

180
docs/html/training/basics/supporting-devices/screens.jd Normal file
View File

@ -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>