From 7ef674b596ba1bac6b26350a6c478d5e6a16bfd7 Mon Sep 17 00:00:00 2001 From: Scott Main Date: Thu, 10 Jun 2010 18:05:13 -0700 Subject: docs: add information about known issues in resource matching for screen density and system version. Add section about providing compatibility for multiple devices bug: 2760561 Change-Id: I9b3a515a14d53923a15b1931f6dd24f295874362 --- .../guide/topics/resources/providing-resources.jd | 243 +++++++++++++++++---- 1 file changed, 196 insertions(+), 47 deletions(-) (limited to 'docs') diff --git a/docs/html/guide/topics/resources/providing-resources.jd b/docs/html/guide/topics/resources/providing-resources.jd index 0f3d389..6d98385 100644 --- a/docs/html/guide/topics/resources/providing-resources.jd +++ b/docs/html/guide/topics/resources/providing-resources.jd @@ -9,6 +9,7 @@ parent.link=index.html

In this document

    @@ -19,7 +20,9 @@ parent.link=index.html
  1. Creating alias resources
+
  • Providing the Best Device Compatibility with Resources
  • How Android Finds the Best-matching Resource
    • +
  • Known Issues

    • See also

    @@ -35,13 +38,14 @@ 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 -will then automatically apply the appropriate resource based on the current configuration. For +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.

    -

    Once you save your resources external to your application code, you can access them +

    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 resources in your application is discussed in Accessing -Resources.

    +Resources. This document shows you how to group your resources in your Android project and +provide alternative resources for specific device configurations.

    Grouping Resource Types

    @@ -63,9 +67,9 @@ MyProject/ strings.xml -

    The {@code res/} directory contains all the resources (in subdirectories): an image resource, two -layout resources, and a string resource file. The resource directory names are important and are -described in table 1.

    +

    As you can see in this example, the {@code res/} directory contains all the resources (in +subdirectories): an image resource, two layout resources, and a string resource file. The resource +directory names are important and are described in table 1.

    Table 1. Resource directories supported inside project {@code res/} directory.

    @@ -96,9 +100,9 @@ are compiled into the following drawable resource subtypes:

  • Bitmap files
  • Nine-Patches (re-sizable bitmaps)
  • State lists
    • -
  • Color drawables
  • Shapes
  • Animation drawables
    • +
  • Other drawables

    • See Drawable Resources.

    @@ -168,16 +172,21 @@ href="{@docRoot}guide/topics/search/searchable-config.html">searchable configura -

    Note: You should never save resource files directly inside the -{@code res/} directory.

    +

    Caution: Never save resource files directly inside the +{@code res/} directory—it will cause a compiler error.

    For more information about certain types of resources, see the Resource Types documentation.

    -

    How to access resources in the {@code res/} subdirectories is discussed in Accessing Resources. -

    - +

    The resources that you save in the subdirectories defined in table 1 are your "default" +resources. That is, these resources define the default design and content for your application. +However, different types of Android-powered devices might call for different types of resources. +For example, if a device has a larger than normal screen, then you should provide +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 +resources.

    Providing Alternative Resources

    @@ -192,8 +201,8 @@ href="accessing-resources.html">Accessing Resources.

    Almost every application should provide alternative resources to support specific device configurations. For instance, you should include alternative drawable resources for different screen densities and alternative string resources for different languages. At runtime, Android -automatically detects the current device configuration and loads the appropriate -resources.

    +detects the current device configuration and loads the appropriate +resources for your application.

    To specify configuration-specific alternatives for a set of resources:

      @@ -201,15 +210,15 @@ resources.

      <resources_name>-<config_qualifier>}.

      You can append more than one {@code <config_qualifier>}. Separate each one with a dash.

      -
    1. Save your alternative resources in this new directory. The resource files must be named -exactly the same as the default resource files.
      2. +
    2. Save the respective alternative resources in this new directory. The resource files must be +named exactly the same as the default resource files.

    For example, here are some default and alternative resources:

    @@ -225,18 +234,24 @@ res/

    The {@code hdpi} qualifier indicates that the resources in that directory are for devices with a -high-density screen. While the images in each drawable directory are sized for a specific screen -density, the filenames are +high-density screen. The images in each of these drawable directories are sized for a specific +screen density, but the filenames are exactly the same. This way, the resource ID that you use to reference the {@code icon.png} or {@code background.png} image is always the same, but Android selects the -version of that drawable that best matches the current device configuration.

    +version of each resource that best matches the current device, by comparing the device +configuration information with the qualifiers in the alternative resource directory name.

    Android supports several configuration qualifiers and you can add multiple qualifiers to one directory name, by separating each qualifier with a dash. Table 2 lists the valid configuration qualifiers, in order of precedence—if you use multiple -qualifiers, they must be added to the directory name in the order they are listed in the -table.

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

    @@ -246,7 +261,7 @@ names.

    Values Description - + MCC and MNC Examples:
    mcc310
    @@ -272,7 +287,7 @@ android.content.res.Configuration#mnc}, which indicate the current mobile countr and mobile network code, respectively.

    - + Language and region Examples:
    en
    @@ -297,12 +312,12 @@ of your application if the user changes his or her language in the system settin href="runtime-changes.html">Handling Runtime Changes for information about how this can affect your application during runtime.

    See Localization for a complete guide to localizing -your application for other langauges.

    +your application for other languages.

    Also see the {@link android.content.res.Configuration#locale} configuration field, which indicates the current locale.

    - + Screen size small
    @@ -326,6 +341,7 @@ indicates the current locale.

    available space in both width and height than an HVGA display. Examples are VGA and WVGA medium density screens. +

    Added in API Level 4.

    See Supporting Multiple Screens for more information.

    Also see the {@link android.content.res.Configuration#screenLayout} configuration field, @@ -333,7 +349,7 @@ which indicates whether the screen is small, normal, or large.

    - + Wider/taller screens long
    @@ -344,13 +360,14 @@ or large.

  • {@code long}: Long screens, such as WQVGA, WVGA, FWVGA
  • {@code notlong}: Not long screens, such as QVGA, HVGA, and VGA
    • +

    Added in API Level 4.

    This is based purely on the aspect ratio of the screen (a "long" screen is wider). This is not related to the screen orientation.

    Also see the {@link android.content.res.Configuration#screenLayout} configuration field, which indicates whether the screen is long.

    - + Screen orientation port
    @@ -370,7 +387,7 @@ how this affects your application during runtime.

    which indicates the current device orientation.

    - + Dock mode car
    @@ -383,12 +400,12 @@ which indicates the current device orientation.

    Added in API Level 8.

    This can change during the life of your application if the user places the device in a -dock. You can eneable or disable this mode using {@link +dock. You can enable or disable this mode using {@link android.app.UiModeManager}. See Handling Runtime Changes for information about how this affects your application during runtime.

    - + Night mode night
    @@ -401,13 +418,13 @@ information about how this affects your application during runtime.

    Added in API Level 8.

    This can change during the life of your application if night mode is left in -auto mode (default), in which case the mode changes based on the time of day. You can eneable +auto mode (default), in which case the mode changes based on the time of day. You can enable or disable this mode using {@link android.app.UiModeManager}. See Handling Runtime Changes for information about how this affects your application during runtime.

    - + Screen pixel density (dpi) ldpi
    @@ -424,6 +441,7 @@ application during runtime.

  • {@code nodpi}: This can be used for bitmap resources that you do not want to be scaled to match the device density.
    • +

    Added in API Level 4.

    There is thus a 4:3 scaling factor between each density, so a 9x9 bitmap in ldpi is 12x12 in mdpi and 16x16 in hdpi.

    When Android selects which resource files to use, @@ -439,7 +457,7 @@ Screens for more information about how to handle screen sizes and how Androi your bitmaps.

    - + Touchscreen type notouch
    @@ -457,7 +475,7 @@ stylus. which indicates the type of touchscreen on the device.

    - + Keyboard availability keysexposed
    @@ -487,7 +505,7 @@ android.content.res.Configuration#keyboardHidden}, which indicate the visibility keyboard and and the visibility of any kind of keyboard (including software), respectively.

    - + Primary text input method nokeys
    @@ -497,7 +515,8 @@ keyboard and and the visibility of any kind of keyboard (including software), re