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:
-
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.
- From
Table 2, pick the highest-precedence qualifier that remains in the list. (Start with MCC, then move down through the list.)
- 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.
- Eliminate resource directories that do not include this qualifier. In our example, we eliminate all the directories that do not include a language qualifier.
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.
- 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.
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.
