Follow Techotopia on Twitter

On-line Guides
All Guides
eBook Store
iOS / Android
Linux for Beginners
Office Productivity
Linux Installation
Linux Security
Linux Utilities
Linux Virtualization
Linux Kernel
System/Network Admin
Programming
Scripting Languages
Development Tools
Web Development
GUI Toolkits/Desktop
Databases
Mail Systems
openSolaris
Eclipse Documentation
Techotopia.com
Virtuatopia.com

How To Guides
Virtualization
General System Admin
Linux Security
Linux Filesystems
Web Servers
Graphics & Desktop
PC Hardware
Windows
Problem Solutions

  




 

 

Android Development
Previous Page Home Next Page

Alternate Resources (for alternate languages and configurations)

You can supply different resources for your application to use depending on the UI language or hardware configuration on the device. Note that although you can include different string, layout, and other resources, the SDK does not expose methods to let you specify which alternate resource set to load. Android detects the proper set for the hardware and location, and loads them as appropriate. Users can select alternate language settings using the settings panel on the device.

To include alternate resources, create parallel resource folders with qualifiers appended to the folder names, indicating the configuration it applies to (language, screen orientation, and so on). For example, here is a project that holds one string resource file for English, and another for French:

MyApp/
    res/
        values-en/
            strings.xml
        values-fr/
            strings.xml

Android supports several types of qualifiers, with various values for each. Append these to the end of the resource folder name, separated by dashes. You can add multiple qualifiers to each folder name, but they must appear in the order they are listed here. For example, a folder containing drawable resources for a fully specified configuration would look like this:

MyApp/
    res/
        drawable-en-rUS-port-160dpi-finger-keysexposed-qwerty-dpad-480x320/

More typically, you will only specify a few specific configuration options. You may drop any of the values from the complete list, as long as the remaining values are still in the same order:

MyApp/
    res/
        drawable-en-rUS-finger/
        drawable-port/
        drawable-port-160dpi/
        drawable-qwerty/

Table 2 lists the valid folder-name qualifiers, in order of precedence. Qualifiers that are listed higher in the table take precedence over those listed lower, as described in How Android finds the best matching directory.

Table 2

Qualifier Values
MCC and MNC The mobile country code and mobile network code from the SIM in the device. For example mcc310-mnc004 (U.S., Verizon brand); mcc208-mnc00 (France, Orange brand); mcc234-mnc00 (U.K., BT brand).

If the device uses a radio connection (GSM phone), the MCC will come from the SIM, and the MNC will come from the network to which the device is attached. You might sometimes use the MCC alone, for example to include country-specific legal resources in your application. If your application specifies resources for a MCC/MNC combination, those resources can only be used if both the MCC and the MNC match.
Language and region The two letter ISO 639-1 language code and two letter ISO 3166-1-alpha-2 region code (preceded by lowercase "r"). For example en-rUS, fr-rFR, es-rES.

The codes are case-sensitive: The language code is lowercase, and the country code is uppercase. You cannot specify a region alone, but you can specify a language alone, for example en, fr, es.
Screen orientation port, land, square
Screen pixel density 92dpi, 108dpi, etc. When Android selects which resource files to use, it handles screen density differently than the other qualifiers. In step 1 of How Android finds the best matching directory (below), screen density is always considered to be a match. In step 4, if the qualifier being considered is screen density, Android will select the best final match at that point, without any need to move on to step 5.
Touchscreen type notouch, stylus, finger
Whether the keyboard is available to the user keysexposed, keyshidden, keyssoft
If your application has specific resources that should only be used with a soft keyboard, use the keyssoft value. If no keyssoft resources are available (only keysexposed and keyshidden) and the device shows a soft keyboard, the system will use keysexposed resources.
Primary text input method nokeys, qwerty, 12key
Primary non-touchscreen
navigation method
nonav, dpad, trackball, wheel
Screen dimensions 320x240, 640x480, etc. The larger dimension must be specified first.
SDK version The SDK version supported by the device, for example v3. The Android 1.0 SDK is v1, the 1.1 SDK is v2, and the 1.5 SDK is v3.
(Minor version) (You cannot currently specify minor version. It is always set to 0.)

This list does not include device-specific parameters such as carrier, branding, device/hardware, or manufacturer. Everything that an application needs to know about the device that it is running on is encoded via the resource qualifiers in the table above.

All resource directories, qualified and unqualified, live under the res/ folder. Here are some guidelines on qualified resource directory names:

  • You can specify multiple qualifiers, separated by dashes. For example, drawable-en-rUS-land will apply to US-English devices in landscape orientation.
  • The qualifiers must be in the order listed in Table 2 above. For example:
    • Correct: values-mcc460-nokeys/
    • Incorrect: values-nokeys-mcc460/
  • Values are case-sensitive. For example, a portrait-specific drawable directory must be named drawable-port, not drawable-PORT or drawable-Port.
  • Only one value for each qualifier type is supported. For example, if you want to use exactly the same drawable files for Spain and France, you will need two resource directories, such as drawable-rES/ and drawable-rFR/, containing identical files. You cannot have a directory named drawable-rES-rFR/.
  • Qualified directories cannot be nested. For example, you cannot have res/drawable/drawable-en.

How resources are referenced in code

All resources will be referenced in code or resource reference syntax by their simple, undecorated names. So if a resource were named this:
      MyApp/res/drawable-port-92dpi/myimage.png
It would be referenced as this:
      R.drawable.myimage (code)
      @drawable/myimage (XML)

If several drawable directories are available, Android will select one of them (as described below) and load myimage.png from it.

How Android finds the best matching directory

Android will pick which of the various underlying resource files should be used at runtime, depending on the current configuration of the device. The example used here assumes the following device configuration:

Locale = en-GB
Screen orientation = port
Screen pixel density = 108dpi
Touchscreen type = notouch
Primary text input method = 12key

Here is how Android makes the selection:

  1. Eliminate resource files that contradict the device configuration. For example, assume that the following resource directories are available for drawables. The drawable-fr-rCA/ directory will be eliminated, because it contradicts the locale of the device.
    MyApp/res/drawable/
    MyApp/res/drawable-en/
    MyApp/res/drawable-fr-rCA/
    MyApp/res/drawable-en-port/
    MyApp/res/drawable-en-notouch-12key/
    MyApp/res/drawable-port-92dpi/
    MyApp/res/drawable-port-notouch-12key
    Exception: Screen pixel density is the one qualifier that is not used to eliminate files. Even though the screen density of the device is 108 dpi, drawable-port-92dpi/ is not eliminated from the list, because every screen density is considered to be a match at this point.
  2. From Table 2, pick the highest-precedence qualifier that remains in the list. (Start with MCC, then move down through the list.)
  3. Do any of the available resource directories include this qualifier?
    • If No, return to step 2 and look at the next qualifier listed in Table 2. In our example, the answer is "no" until we reach Language.
    • If Yes, move on to step 4.
  4. Eliminate resource directories that do not include this qualifier. In our example, we eliminate all the directories that do not include a language qualifier.
  5. MyApp/res/drawable/
    MyApp/res/drawable-en/
    MyApp/res/drawable-en-port/
    MyApp/res/drawable-en-notouch-12key/
    MyApp/res/drawable-port-92dpi/
    MyApp/res/drawable-port-notouch-12key
    Exception: If the qualifier in question is screen pixel density, Android will select the option that most closely matches the device, and the selection process will be complete. In general, Android will prefer scaling down a larger original image to scaling up a smaller original image.

  6. Go back and repeat steps 2, 3, and 4 until only one choice remains. In the example, screen orientation is the next qualifier in the table for which we have any matches. Eliminate resources that do not specify a screen orientation.

    MyApp/res/drawable-en/
    MyApp/res/drawable-en-port/
    MyApp/res/drawable-en-notouch-12key/
    Only one choice remains, so that's it. When drawables are called for in this example application, the Android system will load resources from the MyApp/res/drawable-en-port/ directory.

Tip: The precedence of the qualifiers is more important than the number of qualifiers that exactly match the device. For example, in step 4 above, the last choice on the list includes three qualifiers that exactly match the device (orientation, touchscreen type, and input method), while drawable-en has only one parameter that matches (language). However, language has a higher precedence, so drawable-port-notouch-12key is out.

This flowchart summarizes how Android selects resource directories to load.

resource-selection

Terminology

The resource system brings a number of different pieces together to form the final complete resource functionality. To help understand the overall system, here are some brief definitions of the core concepts and components you will encounter in using it:

Asset: A single blob of data associated with an application. This includes object files compiled from the Java source code, graphics (such as PNG images), XML files, etc. These files are organized in a directory hierarchy that, during final packaging of the application, is bundled together into a single ZIP file.

aapt: Android Asset Packaging Tool. The tool that generates the final ZIP file of application assets. In addition to collecting raw assets together, it also parses resource definitions into binary asset data.

Resource Table: A special asset that aapt generates for you, describing all of the resources contained in an application/package. This file is accessed for you by the Resources class; it is not touched directly by applications.

Resource: An entry in the Resource Table describing a single named value. Broadly, there are two types of resources: primitives and bags.

Resource Identifier: In the Resource Table all resources are identified by a unique integer number. In source code (resource descriptions, XML files, Java source code) you can use symbolic names that stand as constants for the actual resource identifier integer.

Primitive Resource: All primitive resources can be written as a simple string, using formatting to describe a variety of primitive types included in the resource system: integers, colors, strings, references to other resources, etc. Complex resources, such as bitmaps and XML describes, are stored as a primitive string resource whose value is the path of the underlying Asset holding its actual data.

Bag Resource: A special kind of resource entry that, instead of a simple string, holds an arbitrary list of name/value pairs. Each name is itself a resource identifier, and each value can hold the same kinds of string formatted data as a normal resource. Bags also support inheritance: a bag can inherit the values from another bag, selectively replacing or extending them to generate its own contents.

Kind: The resource kind is a way to organize resource identifiers for various purposes. For example, drawable resources are used to instantiate Drawable objects, so their data is a primitive resource containing either a color constant or string path to a bitmap or XML asset. Other common resource kinds are string (localized string primitives), color (color primitives), layout (a string path to an XML asset describing a view layout), and style (a bag resource describing user interface attributes). There is also a standard "attr" resource kind, which defines the resource identifiers to be used for naming bag items and XML attributes

Style: The name of the resource kind containing bags that are used to supply a set of user interface attributes. For example, a TextView class may be given a style resource that defines its text size, color, and alignment. In a layout XML file, you associate a style with a bag using the "style" attribute, whose value is the name of the style resource.

Style Class: Specifies a related set of attribute resources. This data is not placed in the resource table itself, but used to generate constants in the source code that make it easier for you to retrieve values out of a style resource and/or XML tag's attributes. For example, the Android platform defines a "View" style class that contains all of the standard view attributes: padding, visibility, background, etc.; when View is inflated it uses this style class to retrieve those values from the XML file (at which point style and theme information is applied as approriate) and load them into its instance.

Configuration: For any particular resource identifier, there may be multiple different available values depending on the current configuration. The configuration includes the locale (language and country), screen orientation, etc. The current configuration is used to select which resource values are in effect when the resource table is loaded.

Theme: A standard style resource that supplies global attribute values for a particular context. For example, when writing an Activity the application developer can select a standard theme to use, such as the Theme.White or Theme.Black styles; this style supplies information such as the screen background image/color, default text color, button style, text editor style, text size, etc. When inflating a layout resource, most values for widgets (the text color, selector, background) if not explicitly set will come from the current theme; style and attribute values supplied in the layout can also assign their value from explicitly named values in the theme attributes if desired.

Overlay: A resource table that does not define a new set of resources, but instead replaces the values of resources that are in another resource table. Like a configuration, this is applied at load time to the resource data; it can add new configuration values (for example strings in a new locale), replace existing values (for example change the standard white background image to a "Hello Kitty" background image), and modify resource bags (for example change the font size of the Theme.White style to have an 18 pt font size). This is the facility that allows the user to select between different global appearances of their device, or download files with new appearances.

Resource Reference

The Available Resources document provides a detailed list of the various types of resource and how to use them from within the Java source code, or from other references.

Android Development
Previous Page Home Next Page

 
 
  Published under the terms fo the Apache 2.0 License Design by Interspire