From 821ca51857f4d21b231cd9ead786227b771fe759 Mon Sep 17 00:00:00 2001 From: Scott Main Date: Wed, 16 Jun 2010 11:06:43 -0700 Subject: [PATCH] docs: edits to resources doc Change-Id: I1dbe5d213d8f85b2ecaeed45ddbe215f199e2c9e --- docs/html/guide/topics/resources/index.jd | 13 +- .../topics/resources/providing-resources.jd | 183 ++++++++++-------- 2 files changed, 106 insertions(+), 90 deletions(-) diff --git a/docs/html/guide/topics/resources/index.jd b/docs/html/guide/topics/resources/index.jd index 2aa697e1402fb..84eac735e32d9 100644 --- a/docs/html/guide/topics/resources/index.jd +++ b/docs/html/guide/topics/resources/index.jd @@ -24,20 +24,21 @@ code, so that you can maintain them independently. Externalizing your resources also allows you to provide alternative resources that support specific device configurations such as different languages or screen sizes, which becomes increasingly important as more Android-powered devices become available with different configurations. In order -to provide this functionality, you must organize resources in your project's {@code res/} -directory, using various sub-directories that group resources by type and configuration.

+to provide compatibility with different configurations, you must organize resources in your +project's {@code res/} directory, using various sub-directories that group resources by type and +configuration.

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

@@ -55,10 +56,10 @@ append an appropriate configuration qualifier to the directory name.

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 6d983851d024b..66154cbe57789 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.html

In this document

    @@ -20,7 +21,12 @@ parent.link=index.html
  1. Creating alias resources
-
  • Providing the Best Device Compatibility with Resources
    • +
  • Providing the Best Device Compatibility with Resources +
      +
    1. Providing screen resource compatibility for Android +1.5
      2. +
    +
  • How Android Finds the Best-matching Resource
  • Known Issues
    • @@ -36,10 +42,11 @@ Screens

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

  • Save the respective alternative resources in this new directory. The resource files must be @@ -247,13 +254,14 @@ lists the valid configuration qualifiers, in order of precedence—if you us qualifiers for one resource directory, they must be added to the directory name in the order they are listed in the table.

    -

    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.

    @@ -349,8 +357,8 @@ which indicates whether the screen is small, normal, or large.

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

    • You can specify multiple qualifiers for a single set of resources, separated by dashes. For @@ -633,15 +641,19 @@ alias resources below.
      • these qualifiers, Android automatically applies the resources in your application based on the current device configuration. Each time a resource is requested, Android checks for alternative resource directories that contain the requested resource file, then finds the -best-matching resource (discussed below).

      +best-matching resource (discussed below). If there are no alternative resources that match +a particular device configuration, then Android uses the corresponding default resources (the +set of resources for a particular resource type that does not include a configuration +qualifier).

      Creating alias resources

      When 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 Resources

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

      +less than 4 (Android 1.5 or lower), be aware that the screen size, density, and aspect +qualifiers are not supported on Android 1.5 or lower, so you might need to perform additional +compatibility for these versions.

      +

      Providing screen resource compatibility for Android 1.5

      + +

      Android 1.5 (and lower) does not support the following resource qualifers:

      +
      +
      Density
      +
      {@code ldpi}, {@code mdpi}, {@code ldpi}, and {@code nodpi}
      +
      Screen size
      +
      {@code small}, {@code normal}, and {@code large}
      +
      Screen aspect
      +
      {@code long} and {@code notlong}
      +
      + +

      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:

      +
        +
      1. Provide default resources that are for medium-density, normal, and notlong screens. + +

        Because all Android 1.5 devices have medium-density, normal, not-long screens, you can +place these kinds of resources in the corresponding default resource directory. For example, put all +medium density drawable resources in {@code drawable/} (instead of {@code drawable-mdpi/}), +put {@code normal} size resources in the corresponding default resource directory, and {@code +notlong} resources in the corresponding default resource directory.

        +
        2. + +
      2. Ensure that your SDK Tools version +is r6 or greater. + +

        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 does 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 the default resources (which are mdpi) +because they are the best match for the device (instead of using the {@code ldpi} or {@code hdpi} +resources).

        +
        3. +
      + +

      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:

      -
      -
      Density
      -
      {@code ldpi}, {@code mdpi}, {@code ldpi}, and {@code nodpi}
      -
      Screen size
      -
      {@code small}, {@code normal}, and {@code large}
      -
      Screen length
      -
      {@code long} and {@code notlong}
      -
      - -

      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 match

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