From 821ca51857f4d21b231cd9ead786227b771fe759 Mon Sep 17 00:00:00 2001
From: Scott Main
-Figure 1. Two device configurations, both using default +Figure 1. Two different devices, both using default resources.
-Figure 2. Two device configurations, one using alternative +Figure 2. Two different devices, one using alternative resources.
For example, while your default UI layout is saved in the {@code res/layout/} directory, you might specify a different UI layout to be used when the screen is in landscape orientation, by saving it in the {@code res/layout-land/} -directory. The Android system will automatically apply the appropriate resources by matching the +directory. Android automatically applies the appropriate resources by matching the device's current configuration to your resource directory names.
-Figure 1 demonstrates how a collection of default resources from an application will be applied +
Figure 1 demonstrates how a collection of default resources from an application are applied to two different devices when there are no alternative resources available. Figure 2 shows the same application with a set of alternative resources that qualify for one of the device configurations, thus, the two devices uses different resources.
diff --git a/docs/html/guide/topics/resources/providing-resources.jd b/docs/html/guide/topics/resources/providing-resources.jd index 6d98385..66154cb 100644 --- a/docs/html/guide/topics/resources/providing-resources.jd +++ b/docs/html/guide/topics/resources/providing-resources.jd @@ -9,7 +9,8 @@ parent.link=index.htmlYou should always externalize application resources such as images and strings from your -code, so that you can maintain them independently. You can also provide alternative resources for -specific device configurations, by grouping them in specially-named resource directories. Android -then applies the appropriate resource based on the current configuration. For -instance, you might want to provide a different UI layout depending on the screen size.
+code, so that you can maintain them independently. You should also provide alternative resources for +specific device configurations, by grouping them in specially-named resource directories. At +runtime, Android uses uses the appropriate resource based on the current configuration. For +example, you might want to provide a different UI layout depending on the screen size or different +strings depending on the language setting.Once you externalize your application resources, you can access them using resource IDs that are generated in your project's {@code R} class. How to use @@ -185,7 +192,7 @@ For example, if a device has a larger than normal screen, then you should provid different layout resources that take advantage of the extra screen space. Or, if a device has a different language setting, then you should provide different string resources that translate the text in your user interface. To provide these different resources for different device -configurations, you need to provide "alternative" resources, in addition to your default +configurations, you need to provide alternative resources, in addition to your default resources.
@@ -195,7 +202,7 @@ resources.-Figure 1. Two device configurations, one using alternative resources.
+Figure 1. Two different devices, one using alternative resources.Almost every application should provide alternative resources to support specific device @@ -211,10 +218,10 @@ resources for your application.
You can append more than one {@code <config_qualifier>}. Separate each +
You can append more than one {@code <qualifier>}. Separate each one with a dash.
Note: Some resource qualifiers were added after Android 1.0, so not +
Note: Some configuration qualifiers were added after Android 1.0, +so not all versions of Android support all the qualifiers listed in table 2. New qualifiers indicate the version in which they were added. To avoid any issues, always include a set of default resources for resources that your application uses. For more information, see the section about Providing the Best Device Compatibility with Resources.
-Table 2. Alternative resource qualifier +
Table 2. Configuration qualifier names.
Wider/taller screens | +|
Screen aspect |
long notlong
@@ -602,7 +610,7 @@ href="#KnownIssues">Known Issues for more information.
Qualifier name rules-Here are some rules about using resource qualifier names: +Here are some rules about using configuration qualifier names:
Creating alias resourcesWhen you have a resource that you'd like to use for more than one device -configuration (but not for all configurations), you do not need to put the same resource in -each alternative resource directory. Instead, you can (in some cases) create an alternative +configuration (but do not want to provide as a default resource), you do not need to put the same +resource in more than one alternative resource directory. Instead, you can (in some cases) create an +alternative resource that acts as an alias for a resource saved in your default resource directory. Note: Not all resources offer a mechanism by which you can @@ -723,7 +735,6 @@ same way. For example, a color: -Providing the Best Device Compatibility with ResourcesIn order for your application to support multiple device configurations, it's very important that @@ -744,7 +755,7 @@ layout-land/} for landscape and {@code layout-port/} for portrait, leave one as Providing default resources is important not only because your application might run on a
configuration you had not anticipated, but also because new versions of Android sometimes add
-resource qualifiers that older versions do not support. If you use a new resource qualifier,
+configuration qualifiers that older versions do not support. If you use a new resource qualifier,
but maintain code compatibility with older versions of Android, then when an older version of
Android runs your application, it will crash if you do not provide default resources, because it
cannot use the resources named with the new qualifier. For example, if your
- The bottom line is: For every type of resource your application uses,
-provide a set of default resources that allow your application to perform well, then create
-variations of those resources for specific device configurations. So, in order to provide the best device compatibility, always provide default
+resources for the resources your application needs to perform properly. Then create alternative
+resources for specific device configurations using the configuration qualifiers. There is one exception to this rule: If your application's {@code minSdkVersion} is 4 or
@@ -765,12 +776,71 @@ greater, you do not need default drawable resources when you provide al
resources with the screen density qualifier. Even without default
drawable resources, Android can find the best match among the alternative screen densities and scale
the bitmaps as necessary. However, for the best experience on all types of devices, you should
-provide alternative drawables for all three types of density. (If your {@code minSdkVersion} is
-less than 4, see the section below about known issues for
-information about how to support multiple screen densities.) Providing screen resource compatibility for Android 1.5+ +Android 1.5 (and lower) does not support the following resource qualifers: +
These resource qualifiers were introduced in Android 1.6, so Android 1.5 (API Level 3) and lower +does not support them. If you use these configuration qualifiers and do not provide +corresponding default resources, then an Android 1.5 device might use any one of the resource +directories named with the above screen qualifiers, because it ignores the screen qualifiers and +uses whichever otherwise-matching drawable resource it finds first. + +For example, if your application supports Android 1.5 and includes drawable resources for +each density type ({@code drawable-ldpi/}, {@code drawable-mdpi/}, and {@code drawable-ldpi/}), +and does not include default drawable resources ({@code drawable/}), then +an Android 1.5 will use drawables from any one of the alternative resource directories, which +can result in a user interface that's less than ideal. + + So, to provide compatibility with Android 1.5 (and lower) when using the screen configuration +qualifiers: +
Note: Later versions of Android, such as API Level 8, +introduce other configuration qualifiers that older version do not support. To provide the best +compatibility, you should always include a set of default resources for each type of resource +that your application uses, as discussed above to provide the best device compatibility. +How Android Finds the Best-matching Resource@@ -894,62 +964,7 @@ href="accessing-resources.html">Accessing Resources.Known Issues-The following are known issues in terms of how Android finds the best-matching resource on -certain versions of Android. - -Android 1.5 (and lower)- -Density and screen size qualifiers are not supported- -Android 1.5 (and lower) does not support the following resource qualifers: -
These resource qualifiers were introduced in Android 1.6, so Android 1.5 (API Level 3) and lower -does not support them. If your application supports Android 1.5 and includes drawable resources for -each density type ({@code drawable-ldpi/}, {@code drawable-mdpi/}, and {@code drawable-ldpi/}), then -an Android 1.5 device might use any one of them, because it doesn't support the density qualifier, -will ignore it, and will use which ever otherwise-matching drawable resource it finds first. This -caveat applies the same to screen size and screen length resources. - - The fix: Ensure that your SDK Tools version -is r6 or greater and provide default drawable resources. For example, to support Android 1.5 -while providing resources for all screen densities, include a set of drawable resources that does -not use the screen density qualifier. In fact, because all Android 1.5 devices have a medium-density -screen, you can remove the {@code mdpi} qualifer and put all medium density images in {@code -drawable/} (instead of {@code drawable-mdpi/}). For the screen size, put your {@code normal} size -resources in the default resource directory, and for the screen length, put your {@code notlong} -resources in the default resource directory (because all Android 1.5 devices have medium-density, -normal, not-long screens). - -You need SDK Tools, Revision 6 (or greater), because it includes a new packaging tool that -automatically applies an appropriate version qualifier to any -resource directory named with a qualifier that did not exist in Android 1.0. For example, because -the density qualifier was introduced in Android 1.6 (API Level 4), when the packaging tool -encounters a resource directory using the density qualifier, it adds {@code v4} to the directory -name to ensure that older versions do not use those resources (only API Level 4 and higher support -that qualifier). Thus, by putting your medium-density resources in a directory without the -{@code mdpi} qualifier, they are still accessible by Android 1.5, and any device that supports the -density qualifer and has a medium-density screen also uses these resources because they are the best -match for the device (instead of using the {@code ldpi} or {@code hdpi} resources). - -Note: Later versions of Android, such as API Level 8, -introduce other resource qualifiers that older version do not support. To provide the best -compatibility, you should always include a set of default resources for each type of resource -that your application uses. See the section about Providing the Best Device -Compatibility with Resources for more information. - - - -Android 1.5 and 1.6- -Version qualifier performs exact match, instead of best match+Android 1.5 and 1.6: Version qualifier performs exact match, instead of best matchThe correct behavior is for the system to match resources marked with a version qualifier equal @@ -957,8 +972,8 @@ to or less than the system version on the device, but on Android 1.5 and 1.6, (A there is a bug that causes the system to match resources marked with the version qualifier only when it exactly matches the version on the device. -The fix: To provide version-specific resources, abide by this behavior. However, because -this bug is fixed in versions of Android available after 1.6, if + The workaround: To provide version-specific resources, abide by this behavior. However, +because this bug is fixed in versions of Android available after 1.6, if you need to differentiate resources between Android 1.5, 1.6, and later versions, then you only need to apply the version qualifier to the 1.6 resources and one to match all later versions. Thus, this is effectively a non-issue. -- cgit v1.1 |