Configuration Qualifiers

You have now seen and used several configuration qualifiers for providing alternative resources: language (such as values-es), screen orientation (layout-land), and screen density (drawable-mdpi).

The device configurations that Android provides configuration qualifiers to target resources for are:

  1. mobile country code (MCC), optionally followed by mobile network code (MNC)

  2. language code, optionally followed by region code

  3. layout direction

  4. smallest width

  5. available width

  6. available height

  7. screen size

  8. screen aspect

  9. round screen (API level 23 and above)

  10. wide color gamut

  11. high dynamic range

  12. screen orientation

  13. UI mode

  14. night mode

  15. screen density (dpi)

  16. touchscreen type

  17. keyboard availability

  18. primary text input method

  19. navigation key availability

  20. primary non-touch navigation method

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

Prioritizing alternative resources

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, 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 text box before the user enters any text. When CriminalIntent is running on a screen that is at least 600dp (such as 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 values resource file called strings. Follow the steps from the section called Localizing Resources earlier in this chapter to create the resource file, but select Screen Width in the Available qualifiers list and click the >> button to move Screen Width to the Chosen qualifiers section. In the Screen width box that appears, enter 600. The directory name will automatically be set to values-w600dp; -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. (To learn more about screen size qualifiers, read the section called For the More Curious: More on Determining Device Size near the end of this chapter.) Your dialog should look like Figure 17.8.

Figure 17.8  Adding strings for a wider screen

Adding strings for a wider screen

Now, add a longer value for crime_title_hint to res/values-w600dp/strings.xml.

Listing 17.3  Creating an alternative string resource for a wider screen (res/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. As we said earlier, you should provide alternatives for only those string resources (and other values resources) that will be different based on some configuration qualification. You do not need to duplicate strings when they are the same. More than that, you should not: 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 res/values/strings.xml, a Spanish alternative in res/values-es/strings.xml, and a wide-screen alternative in res/values-w600dp/strings.xml.

With your device’s language set to Spanish, run CriminalIntent and rotate to landscape (Figure 17.9). The Spanish language alternative has precedence, so you see the string from res/values-es/strings.xml instead of res/values-w600dp/strings.xml.

Figure 17.9  Android prioritizes language over available screen width

Android prioritizes language over available screen width

If you like, change your settings back to English and check the app again to confirm that the alternative wide-screen string appears as expected.

Multiple qualifiers

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

Listing 17.4  Creating a wide-screen Spanish string resource (res/values-es-w600dp/strings.xml)

<resources>
    <string name="crime_title_hint">
        Introduzca un título significativo y memorable para el crimen.
    </string>
</resources>

Now, with your language set to Spanish, run CriminalIntent to confirm that your new alternative resource appears on cue (Figure 17.10).

Figure 17.10  Spanish wide-screen string resource

Spanish wide-screen string resource

Finding the best-matching resources

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 landscape device configuration for a Pixel 2 set to Spanish language and with an available screen width greater than 600dp:

Device configuration

App values for crime_title_hint

  • Language: es (Spanish)

  • values

  • Available height: 411dp

  • values-es

  • Available width: 731dp

  • values-es-w600dp

  • (etc.)

  • values-w600dp

Ruling out incompatible directories

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

Stepping through the precedence table

After the incompatible resource directories have been ruled out, Android starts working through the precedence table shown in the section called Configuration Qualifiers earlier in this chapter, 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 the matching language qualifier -es. The values and values-w600dp directories do not contain a language qualifier and thus are ruled out.

(However, as you read earlier in this chapter, the unqualified values directory serves as the default resource, or fallback. So while it is ruled out for now due to lack of a language qualifier, values could still end up being the best match if the other values directories have a mismatch in one or more of the lower-order qualifiers.)

Device configuration

App values for crime_title_hint

  • Language: es (Spanish)

  • values (not language specific)

  • Available height: 411dp

  • values-es

  • Available width: 731dp

  • values-es-w600dp

  • (etc.)

  • values-w600dp (not language specific)

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 one without. It rules out values-es, leaving only values-es-w600dp:

Device configuration

App values for crime_title_hint

  • Language: es (Spanish)

  • values (not language or width specific)

  • Available height: 411dp

  • values-es (not width specific)

  • Available width: 731dp

  • values-es-w600dp (best match)

  • (etc.)

  • values-w600dp (not language specific)

Thus, Android uses the resource in values-es-w600dp.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
3.238.107.238