You have now seen and used several configuration qualifiers for providing alternative resources: language (e.g., values-es/), screen orientation (e.g., layout-land/), screen density (e.g., drawable-mdpi/), and screen size (e.g., layout-sw600dp).
The device configurations for which Android provides configuration qualifiers to target resources are:
mobile country code (MCC), optionally followed by mobile network code (MNC)
language code, optionally followed by region code
layout direction
smallest width
available width
available height
screen size
screen aspect
round screen (API level 23 and above)
screen orientation
UI mode
night mode
screen density (dpi
)
touchscreen type
keyboard availability
primary text input method
navigation key availability
primary non-touch navigation method
API level
You can find descriptions of these characteristics and examples of specific configuration qualifiers at developer.android.com/guide/topics/resources/providing-resources.html#AlternativeResources.
Not all qualifiers are supported by earlier versions of Android.
Luckily the system implicitly adds a platform version qualifier to qualifiers that were introduced after Android 1.0.
So if, for example, you use the round
qualifier, Android will automatically include the v23
qualifier, because round screen qualifiers were added in API level 23.
This means you do not have to worry about problems on older devices when you introduce resources qualified for newer devices.
Given the many types of configuration qualifiers for targeting resources, there may be times when the device configuration will match more than one alternative resource. When this happens, qualifiers are given precedence in the order shown in the list above.
To see this prioritizing in action, let’s add another alternative resource to CriminalIntent – a longer English version of the crime_title_hint
string resource – to be displayed when the current configuration’s width is at least 600dp.
The crime_title_hint
resource is displayed in the crime title edit text before the user enters any text.
When CriminalIntent is running on a screen that is at least 600dp (e.g., on a tablet, or perhaps in landscape mode on a smaller device), this change will display a more descriptive, engaging hint for the title field.
Create a new string resource file and place it in a new values-w600dp directory (-w600dp
will match any device where the current available screen width is 600dp or more, meaning a device may match when in landscape mode but not in portrait mode).
Follow the same steps from the section called Localizing Resources to create the values resource file, but select Screen Width in the Available qualifiers list and click the >> button to move Screen Width to the Chosen qualifiers section.
For the rest of the fields, enter the values shown in Figure 18.11.
Add a longer value for crime_title_hint
to values-w600dp/strings.xml.
Listing 18.4 Creating alternative string resource for wider screen (values-w600dp/strings.xml
)
<resources> <string name="crime_title_hint"> Enter a meaningful, memorable title for the crime. </string> </resources>
The only string resource you want to be different on wider screens is crime_title_hint
.
That is why crime_title_hint
is the only string you specified in values-w600dp.
Alternatives for string resources (and other values resources) are provided on a per-string basis, so you do not need to duplicate strings when they are the same.
Those duplicated strings would only end up being a maintenance hassle down the road.
Now you have three versions of crime_title_hint
: a default version in values/strings.xml, a Spanish alternative in values-es/strings.xml, and a wide-screen alternative in values-w600dp/strings.xml.
With your device’s language set to Spanish, run CriminalIntent and rotate to landscape (Figure 18.12). The Spanish language alternative has precedence, so you see the string from values-es/strings.xml instead of values-w600dp/strings.xml.
If you like, you can change your settings back to English and run again to confirm that the alternative wide-screen string appears as expected.
You may have noticed that the New Resource File dialog has many available qualifiers. You can put more than one qualifier on a resource directory. When using multiple qualifiers on directories, you must put them in the order of their precedence. Thus, values-es-w600dp is a valid directory name, but values-w600dp-es is not. (When you use the New Resource File dialog, it correctly configures the directory name for you.)
Create a directory for a wide-screen Spanish string. It should be named values-es-w600dp and have a file named strings.xml.
Add a string resource for crime_title_hint
to values-es-w600dp/strings.xml (Listing 18.5).
Listing 18.5 Creating a wide-screen Spanish string resource (values-es-w600dp/strings.xml
)
<resources> <string name="crime_title_hint"> Introduzca un título significativo y memorable para el crimen. </string> </resources>
With your language set to Spanish, run CriminalIntent to confirm your new alternative resource appears on cue (Figure 18.13).
Let’s walk through how Android determined which version of crime_title_hint
to display in this run.
First, consider the four alternatives for the string resource named crime_title_hint
and an example device configuration for a Nexus 5x set to Spanish language and with an available screen width greater than 600dp:
Device configuration |
App values for |
|
|
|
|
|
|
|
|
The first step that Android takes to find the best resource is to rule out any resource directory that is incompatible with the current configuration.
None of the four choices is incompatible with the current configuration. (If you rotated the device to portrait, the available width would become 411dp, and the resource directories values-w600dp/ and values-es-w600dp/ would be incompatible and thus ruled out.)
After the incompatible resource directories have been ruled out, Android starts working through the precedence table shown in the section called Configuration Qualifiers, starting with the highest priority qualifier: MCC. If there is a resource directory with an MCC qualifier, then all resource directories that do not have an MCC qualifier are ruled out. If there is still more than one matching directory, then Android considers the next-highest precedence qualifier and continues until only one directory remains.
In our example, no directories contain an MCC qualifier, so no directories are ruled out, and Android moves down the list to the language qualifier. Two directories (values-es/ and values-es-w600dp/) contain language qualifiers. One directory (values-w600dp/) does not and is ruled out:
Device Configuration |
App values for |
|
|
|
|
|
|
|
|
Because there are multiple values still in the running, Android keeps stepping down the qualifier list. When it reaches available width, it finds one directory with an available width qualifier and two without. It rules out values and values-es/, leaving only values-es-w600dp/:
Device Configuration |
App values for |
|
|
|
|
|
|
|
|
Thus, Android uses the resource in values-es-w600dp/.