From 60e5e432d902e72d387860ad975157145ad53ae5 Mon Sep 17 00:00:00 2001 From: Scott Main Date: Mon, 2 Apr 2012 13:11:23 -0700 Subject: [PATCH] docs: Add 101 class about supporting various devices Change-Id: Iafeb99c9dab8462236a41cc4991085062ff7fa14 --- .../basics/supporting-devices/index.jd | 49 +++++ .../basics/supporting-devices/languages.jd | 134 +++++++++++++ .../basics/supporting-devices/platforms.jd | 138 ++++++++++++++ .../basics/supporting-devices/screens.jd | 180 ++++++++++++++++++ 4 files changed, 501 insertions(+) create mode 100644 docs/html/training/basics/supporting-devices/index.jd create mode 100644 docs/html/training/basics/supporting-devices/languages.jd create mode 100644 docs/html/training/basics/supporting-devices/platforms.jd create mode 100644 docs/html/training/basics/supporting-devices/screens.jd 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 0000000000000..49ea81d27d727 --- /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 + +
+
+ +

Dependencies and prerequisites

+
    +
  • Android 1.6 or higher
    • +
+ +

You should also read

+ + + +
+
+ +

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.

+ +

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).

+ +

Lessons

+ +
+
Supporting Different Languages
+
Learn how to support multiple languages with alternative string resources.
+
Supporting Different Screens
+
Learn how to optimize the user experience for different screen sizes and densities.
+
Supporting Different Platform Versions
+
Learn how to use APIs available in new versions of Android while continuing to support +older versions of Android.
+
+ 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 0000000000000..fcc95c2a7f946 --- /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 + + +
+
+

This class teaches you to

+
    +
  1. Create Locale Directories and String Files
    2. +
  2. Use the String Resources
    3. +
+

You should also read

+ +
+
+ +

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.

+ +

If you created your project using the Android SDK +Tools (read Creating an +Android Project), the tools create a res/ directory in the top level of +the project. Within this res/ directory are subdirectories for various resource +types. There are also a few default files such as res/values/strings.xml, which holds +your string values.

+ + +

Create Locale Directories and String Files

+ +

To add support for more languages, create additional values directories inside +res/ that include a hyphen and the ISO country code at the end of the +directory name. For example, values-es/ 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.

+ +

Once you’ve decided on the languages you will support, create the resource subdirectories and +string resource files. For example:

+ +
+MyProject/
+    res/
+       values/
+           strings.xml
+       values-es/
+           strings.xml
+       values-fr/
+           strings.xml
+
+ +

Add the string values for each locale into the appropriate file.

+ +

At runtime, the Android system uses the appropriate set of string resources based on the +locale currently set for the user's device.

+ +

For example, the following are some different string resource files for different languages.

+ + +

English (default locale), /values/strings.xml:

+ +
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <string name="title">My Application</string>
+    <string name="hello_world">Hello World!</string>
+</resources>
+
+ + +

Spanish, /values-es/strings.xml:

+ +
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <string name="title">Mi Aplicación</string>
+    <string name="hello_world">Hola Mundo!</string>
+</resources>
+
+ + +

French, /values-fr/strings.xml:

+ +
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <string name="title">Ma Application</string>
+    <string name="hello_world">Bonjour tout le Monde!</string>
+</resources>
+
+ + +

Use the String Resources

+ +

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.

+ +

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.

+ +

For example:

+ +
+// 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);
+
+ +

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.

+ +

For example:

+ +
+<TextView
+    android:layout_width="wrap_content"
+    android:layout_height="wrap_content"
+    android:text="@string/hello_world" />
+
+ + + 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 0000000000000..0d4e7d98303a3 --- /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 + + +
+ +
+ +

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.

+ +

The dashboard for Platform Versions +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.

+ +

Tip: In order to provide the best features and +functionality across several Android versions, you should use the Android Support Library in your app, +which allows you to use several recent platform APIs on older versions.

+ + + +

Specify Minimum and Target API Levels

+ +

The AndroidManifest.xml file +describes details about your app and +identifies which versions of Android it supports. Specifically, the minSdkVersion +and targetSdkVersion attributes for the {@code <uses-sdk} 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.

+ +

For example:

+ +
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" ... >
+    <uses-sdk android:minSdkVersion="4" android:targetSdkVersion="15" />
+    ...
+</manifest>
+
+ +

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 +{@code targetSdkVersion} +value to match the latest Android version +available.

+ + + +

Check System Version at Runtime

+ +

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.

+ +
+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);
+    }
+}
+
+ + + +

Note: 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 +targetSdkVersion="11", 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 +android:showAsAction="ifRoom" 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 +showAsAction attribute (that is, you do not need a separate +version in res/menu-v11/).

+ + + +

Use Platform Styles and Themes

+ +

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.

+ +

To make your activity look like a dialog box:

+ +
<activity android:theme="@android:style/Theme.Dialog">
+ +

To make your activity have a transparent background:

+ +
<activity android:theme="@android:style/Theme.Translucent">
+ +

To apply your own custom theme defined in /res/values/styles.xml:

+ +
<activity android:theme="@style/CustomTheme">
+ +

To apply a theme to your entire app (all activities), add the android:theme +attribute +to the {@code +<application>} element:

+ +
<application android:theme="@style/CustomTheme">
+ +

For more about creating and using themes, read the Styles and Themes guide.

+ 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 0000000000000..8697cd5e4cf70 --- /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 + +
+ +
+ +

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.

+ + + +

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.

+ +

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.

+ + +

Create Different Layouts

+ +

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 -<screen_size> +suffix. For example, a unique layout for large screens should be saved under +res/layout-large/.

+ +

Note: 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).

+ +

For example, this project includes a default layout and an alternative layout for large +screens:

+ +
+MyProject/
+    res/
+        layout/
+            main.xml
+        layout-large/
+            main.xml
+
+ +

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.

+ +

Simply reference the layout file in your app as usual:

+ +
+@Override
+ protected void onCreate(Bundle savedInstanceState) {
+     super.onCreate(savedInstanceState);
+     setContentView(R.layout.main);
+}
+
+ +

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 Providing Resources +guide.

+ +

As another example, here's a project with an alternative layout for landscape orientation:

+ +
+MyProject/
+    res/
+        layout/
+            main.xml
+        layout-land/
+            main.xml
+
+ +

By default, the layout/main.xml file is used for portrait orientation.

+ +

If you want a provide a special layout for landscape, including while on large screens, then +you need to use both the large and land qualifier:

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

Note: 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 Designing for Multiple +Screens.

+ + + +

Create Different Bitmaps

+ +

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.

+ +

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:

+ + +

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.

+ +

Then, place the files in the appropriate drawable resource directory:

+ +
+MyProject/
+    res/
+        drawable-xhdpi/
+            awesomeimage.png
+        drawable-hdpi/
+            awesomeimage.png
+        drawable-mdpi/
+            awesomeimage.png
+        drawable-ldpi/
+            awesomeimage.png
+
+ +

Any time you reference @drawable/awesomeimage, the system selects the +appropriate bitmap based on the screen's density.

+ +

Note: 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.

+ +

For more tips and guidelines about creating icon assets for your app, see the +Iconography design guide.

+ + +