Skip to content

Commit a589487

Browse files
scottamainAndroid (Google) Code Review
scottamain
authored and
Android (Google) Code Review
committed
Merge "docs: Add 101 class about supporting various devices" into ics-mr1
2 parents ede62bb + 60e5e43 commit a589487

File tree

4 files changed

+501
-0
lines changed

4 files changed

+501
-0
lines changed

‎docs/html/training/basics/supporting-devices/index.jd‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
page.title=Supporting Different Devices
2+
3+
trainingnavtop=true
4+
startpage=true
5+
next.title=Supporting Multiple Languages
6+
next.link=languages.html
7+
8+
@jd:body
9+
10+
<div id="tb-wrapper">
11+
<div id="tb">
12+
13+
<h2>Dependencies and prerequisites</h2>
14+
<ul>
15+
<li>Android 1.6 or higher</li>
16+
</ul>
17+
18+
<h2>You should also read</h2>
19+
<ul>
20+
<li><a href="{@docRoot}guide/topics/resources/index.html">Application Resources</a></li>
21+
<li><a href="{@docRoot}training/multiscreen/index.html">Designing for Multiple Screens</a></li>
22+
</ul>
23+
24+
25+
</div>
26+
</div>
27+
28+
<p>Android devices come in many shapes and sizes all around the world. With a wide range of device
29+
types, you have an opportunity to reach a huge audience with your app. In order to be as successful
30+
as possible on Android, your app needs to adapt to various device configurations. Some of the
31+
important variations that you should consider include different languages, screen sizes, and
32+
versions of the Android platform.</p>
33+
34+
<p>This class teaches you how to use basic platform features that leverage alternative
35+
resources and other features so your app can provide an optimized user experience on a
36+
variety of Android-compatible devices, using a single application package (APK).</p>
37+
38+
<h2>Lessons</h2>
39+
40+
<dl>
41+
<dt><b><a href="languages.html">Supporting Different Languages</a></b></dt>
42+
<dd>Learn how to support multiple languages with alternative string resources.</dd>
43+
<dt><b><a href="screens.html">Supporting Different Screens</a></b></dt>
44+
<dd>Learn how to optimize the user experience for different screen sizes and densities.</dd>
45+
<dt><b><a href="platforms.html">Supporting Different Platform Versions</a></b></dt>
46+
<dd>Learn how to use APIs available in new versions of Android while continuing to support
47+
older versions of Android.</dd>
48+
</dl>
49+

‎docs/html/training/basics/supporting-devices/languages.jd‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
page.title=Supporting Different Languages
2+
parent.title=Supporting Different Devices
3+
parent.link=index.html
4+
5+
trainingnavtop=true
6+
next.title=Supporting Different Screens
7+
next.link=screens.html
8+
9+
@jd:body
10+
11+
12+
<div id="tb-wrapper">
13+
<div id="tb">
14+
<h2>This class teaches you to</h2>
15+
<ol>
16+
<li><a href="#CreateDirs">Create Locale Directories and String Files</a></li>
17+
<li><a href="#UseString">Use the String Resources</a></li>
18+
</ol>
19+
<h2>You should also read</h2>
20+
<ul>
21+
<li><a href="{@docRoot}guide/topics/resources/localization.html">Localization</a></li>
22+
</ul>
23+
</div>
24+
</div>
25+
26+
<p>It’s always a good practice to extract UI strings from your app code and keep them
27+
in an external file. Android makes this easy with a resources directory in each Android
28+
project.</p>
29+
30+
<p>If you created your project using the Android SDK
31+
Tools (read <a href="{@docRoot}training/basics/firstapp/creating-project.html">Creating an
32+
Android Project</a>), the tools create a <code>res/</code> directory in the top level of
33+
the project. Within this <code>res/</code> directory are subdirectories for various resource
34+
types. There are also a few default files such as <code>res/values/strings.xml</code>, which holds
35+
your string values.</p>
36+
37+
38+
<h2 id="CreateDirs">Create Locale Directories and String Files</h2>
39+
40+
<p>To add support for more languages, create additional <code>values</code> directories inside
41+
<code>res/</code> that include a hyphen and the ISO country code at the end of the
42+
directory name. For example, <code>values-es/</code> is the directory containing simple
43+
resourcess for the Locales with the language code "es". Android loads the appropriate resources
44+
according to the locale settings of the device at run time.</p>
45+
46+
<p>Once you’ve decided on the languages you will support, create the resource subdirectories and
47+
string resource files. For example:</p>
48+
49+
<pre class="classic no-pretty-print">
50+
MyProject/
51+
res/
52+
values/
53+
strings.xml
54+
values-es/
55+
strings.xml
56+
values-fr/
57+
strings.xml
58+
</pre>
59+
60+
<p>Add the string values for each locale into the appropriate file.</p>
61+
62+
<p>At runtime, the Android system uses the appropriate set of string resources based on the
63+
locale currently set for the user's device.</p>
64+
65+
<p>For example, the following are some different string resource files for different languages.</p>
66+
67+
68+
<p>English (default locale), <code>/values/strings.xml</code>:</p>
69+
70+
<pre>
71+
&lt;?xml version="1.0" encoding="utf-8"?>
72+
&lt;resources>
73+
&lt;string name="title">My Application&lt;/string>
74+
&lt;string name="hello_world">Hello World!&lt;/string>
75+
&lt;/resources>
76+
</pre>
77+
78+
79+
<p>Spanish, <code>/values-es/strings.xml</code>:</p>
80+
81+
<pre>
82+
&lt;?xml version="1.0" encoding="utf-8"?>
83+
&lt;resources>
84+
&lt;string name="title">Mi Aplicación&lt;/string>
85+
&lt;string name="hello_world">Hola Mundo!&lt;/string>
86+
&lt;/resources>
87+
</pre>
88+
89+
90+
<p>French, <code>/values-fr/strings.xml</code>:</p>
91+
92+
<pre>
93+
&lt;?xml version="1.0" encoding="utf-8"?>
94+
&lt;resources>
95+
&lt;string name="title">Ma Application&lt;/string>
96+
&lt;string name="hello_world">Bonjour tout le Monde!&lt;/string>
97+
&lt;/resources>
98+
</pre>
99+
100+
101+
<h2 id="UseString">Use the String Resources</h2>
102+
103+
<p>You can reference your string resources in your source code and other XML files using the
104+
resource name defined by the {@code &lt;string>} element's {@code name} attribute.</p>
105+
106+
<p>In your source code, you can refer to a string resource with the syntax {@code
107+
R.string.&lt;string_name>}. There are a variety of methods that accept a string resource this
108+
way.</p>
109+
110+
<p>For example:</p>
111+
112+
<pre>
113+
// Get a string resource from your app's {@link android.content.res.Resources}
114+
String hello = {@link android.content.Context#getResources()}.getString(R.string.hello_world);
115+
116+
// Or supply a string resource to a method that requires a string
117+
TextView textView = new TextView(this);
118+
textView.setText(R.string.hello_world);
119+
</pre>
120+
121+
<p>In other XML files, you can refer to a string resource with the syntax {@code
122+
&#64;string/&lt;string_name>} whenever the XML attribute accepts a string value.</p>
123+
124+
<p>For example:</p>
125+
126+
<pre>
127+
&lt;TextView
128+
android:layout_width="wrap_content"
129+
android:layout_height="wrap_content"
130+
android:text="@string/hello_world" />
131+
</pre>
132+
133+
134+

‎docs/html/training/basics/supporting-devices/platforms.jd‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
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/appendix/api-levels.html">Android API Levels</a></li>
25+
<li><a
26+
href="{@docRoot}sdk/compatibility-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/resources/dashboard/platform-versions.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, it’s 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}sdk/compatibility-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 you’ve 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 aren’t 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+

0 commit comments

Comments
 (0)