Which resources take precedence?
If multiple resource files match a device's configuration, Android follows a set of rules in deciding which file to use. Among the qualifiers that can be specified in a resource directory name, locale almost always takes precedence.
Example:
Assume that an app includes a default set of graphics and two other sets of graphics, each optimized for a different device setup:
Ø res/drawable/
Contains default graphics.
Ø res/drawable-small-land-stylus/
Contains graphics optimized for use with a device that expects input from a
stylus and has a QVGA low-density screen in landscape orientation.
Ø res/drawable-ja/
Contains graphics optimized for use with Japanese.
If the app runs on a device that is configured to use Japanese, Android loads graphics from res/drawable-ja/, even if the device happens to be one that expects input from a stylus and has a QVGA low-density screen in landscape orientation.
Exception: The only qualifiers that take precedence over locale in the selection process are MCC and MNC (mobile country code and mobile network code).
Example:
Assume that you have the following situation:
Ø The app code calls for R.string.text_a
Ø Two relevant resource files are available:
o res/values-mcc404/strings.xml, which includes text_a in the app's default language, in this case English.
o res/values-hi/strings.xml, which includes text_a in Hindi.
Ø The app is running on a device that has the following configuration:
o The SIM card is connected to a mobile network in India (MCC 404).
o The language is set to Hindi (hi).
Android loads text_a from res/values-mcc404/strings.xml (in English), even if the device is configured for Hindi. That is because in the resource-selection process, Android prefers an MCC match over a language match.
The selection process isn't always as straightforward as these examples suggest.
Table 2
|
Configuration |
|
Qualifier Values |
Description |
|
MCC and MNC |
|
Examples: |
The mobile country code (MCC), optionally followed by mobile network code (MNC) from the SIM card in the device. For example, mcc310 is U.S. on any carrier, mcc310-mnc004 is U.S. on Verizon, and mcc208-mnc00 is France on Orange. If the device uses a radio connection (GSM phone), the MCC and MNC values come from the SIM card. You can also use the MCC alone (for example, to include country-specific legal resources in your app). If you need to specify based on the language only, then use the language and regionqualifier instead (discussed next). If you decide to use the MCC and MNC qualifier, you should do so with care and test that it works as expected. |
|
Language and region |
|
Examples: |
The language is defined by a two-letter ISO 639-1 language code, optionally followed by a two letter ISO 3166-1-alpha-2 region code (preceded by lowercase r). The codes are not case-sensitive; the r prefix is used to distinguish the region portion. You cannot specify a region alone. Android 7.0 (API level 24) introduced support for BCP 47 language tags, which you can use to qualify language- and region-specific resources. A language tag is composed from a sequence of one or more subtags, each of which refines or narrows the range of language identified by the overall tag. For more information about language tags, see Tags for Identifying Languages. To use a BCP 47 language tag, concatenate b+ and a two-letter ISO 639-1 language code, optionally followed by additional subtags separated by +. The language tag can change during the life of your app if the users change their language in the system settings. |
|
Layout Direction |
|
ldrtl |
The layout direction of your app. ldrtl means "layout-direction-right-to-left". ldltr means "layout-direction-left-to-right" and is the default implicit value. This can apply to any resource such as layouts, drawables, or values. For example, if you want to provide some specific layout for the Arabic language and some generic layout for any other "right-to-left" language (like Persian or Hebrew) then you would have: res/ layout/ main.xml (Default layout) layout-ar/ main.xml (Specific layout for Arabic) layout-ldrtl/ main.xml (Any "right-to-left" language, except for Arabic, because the "ar" language qualifier has a higher precedence.) Note: To enable right-to-left layout features for your app, you must set supportsRtl to "true" and set targetSdkVersion to 17 or higher. |
|
smallestWidth |
|
sw<N>dp |
The fundamental size of a screen, as indicated by the shortest dimension of the available screen area. Specifically, the device's smallestWidth is the shortest of the screen's available height and width (you may also think of it as the "smallest possible width" for the screen). You can use this qualifier to ensure that, regardless of the screen's current orientation, your app's has at least <N>dps of width available for its UI. For example, if your layout requires that its smallest dimension of screen area be at least 600 dp at all times, then you can use this qualifier to create the layout resources, res/layout-sw600dp/. The system uses these resources only when the smallest dimension of available screen is at least 600dp, regardless of whether the 600dp side is the user-perceived height or width. The smallest width is a fixed screen size characteristic of the device; the device's smallest width doesn't change when the screen's orientation changes. Using smallest width to determine the general screen size is useful because width is often the driving factor in designing a layout. A UI will often scroll vertically, but have fairly hard constraints on the minimum space it needs horizontally. The available width is also the key factor in determining whether to use a one-pane layout for handsets or multi-pane layout for tablets. Thus, you likely care most about what the smallest possible width will be on each device. The smallest width of a device takes into account screen decorations and system UI. For example, if the device has some persistent UI elements on the screen that account for space along the axis of the smallest width, the system declares the smallest width to be smaller than the actual screen size, because those are screen pixels not available for your UI. Some values you might use here for common screen sizes: · 320, for devices with screen configurations such as: · 240x320 ldpi (QVGA handset) · 320x480 mdpi (handset) · 480x800 hdpi (high-density handset) · 480, for screens such as 480x800 mdpi (tablet/handset). · 600, for screens such as 600x1024 mdpi (7" tablet). · 720, for screens such as 720x1280 mdpi (10" tablet). When your app provides multiple resource directories with different values for the smallestWidth qualifier, the system uses the one closest to (without exceeding) the device's smallestWidth. Added in API level 13. Also see the android:requiresSmallestWidthDp attribute, which declares the minimum smallestWidth with which your app is compatible, and the smallestScreenWidthDpconfiguration field, which holds the device's smallestWidth value. For more information about designing for different screens and using this qualifier, see the Supporting Multiple Screens developer guide. |
|
Available width |
|
w<N>dp |
Specifies a minimum available screen width, in dp units at which the resource should be used—defined by the <N> value. This configuration value changes when the orientation changes between landscape and portrait to match the current actual width. This is often useful to determine whether to use a multi-pane layout, because even on a tablet device, you often won't want the same multi-pane layout for portrait orientation as you do for landscape. Thus, you can use this to specify the minimum width required for the layout, instead of using both the screen size and orientation qualifiers together. When your app provides multiple resource directories with different values for this configuration, the system uses the one closest to (without exceeding) the device's current screen width. The value here takes into account screen decorations, so if the device has some persistent UI elements on the left or right edge of the display, it uses a value for the width that is smaller than the real screen size, accounting for these UI elements and reducing the app's available space. |
|
Available height |
|
h<N>dp |
Specifies a minimum available screen height, in "dp" units at which the resource should be used—defined by the <N> value. This configuration value changes when the orientation changes between landscape and portrait to match the current actual height. Using this to define the height required by your layout is useful in the same way as w<N>dp is for defining the required width, instead of using both the screen size and orientation qualifiers. However, most apps won't need this qualifier, considering that UIs often scroll vertically and are thus more flexible with how much height is available, whereas the width is more rigid. When your app provides multiple resource directories with different values for this configuration, the system uses the one closest to (without exceeding) the device's current screen height. The value here takes into account screen decorations, so if the device has some persistent UI elements on the top or bottom edge of the display, it uses a value for the height that is smaller than the real screen size, accounting for these UI elements and reducing the app's available space. Screen decorations that aren't fixed (such as a phone status bar that can be hidden when full screen) are not accounted for here, nor are window decorations like the title bar or action bar, so apps must be prepared to deal with a somewhat smaller space than they specify. |
|
Screen size |
|
small |
· small: Screens that are of similar size to a low-density QVGA screen. The minimum layout size for a small screen is approximately 320x426 dp units. Examples are QVGA low-density and VGA high density. · normal: Screens that are of similar size to a medium-density HVGA screen. The minimum layout size for a normal screen is approximately 320x470 dp units. Examples of such screens a WQVGA low-density, HVGA medium-density, WVGA high-density. · large: Screens that are of similar size to a medium-density VGA screen. The minimum layout size for a large screen is approximately 480x640 dp units. Examples are VGA and WVGA medium-density screens. · xlarge: Screens that are considerably larger than the traditional medium-density HVGA screen. The minimum layout size for an xlarge screen is approximately 720x960 dp units. In most cases, devices with extra-large screens would be too large to carry in a pocket and would most likely be tablet-style devices. Added in API level 9. Note: Using a size qualifier does not imply that the resources are only for screens of that size. If you do not provide alternative resources with qualifiers that better match the current device configuration, the system may use whichever resources are the best match. Caution: If all your resources use a size qualifier that is larger than the current screen, the system will not use them and your app will crash at runtime (for example, if all layout resources are tagged with the xlarge qualifier, but the device is a normal-size screen). |
|
Screen aspect |
|
long |
· long: Long screens, such as WQVGA, WVGA, FWVGA · notlong: Not long screens, such as QVGA, HVGA, and VGA This is based purely on the aspect ratio of the screen (a "long" screen is wider). This isn't related to the screen orientation. |
|
Round screen |
|
round |
· round: Round screens, such as a round wearable device · notround: Rectangular screens, such as phones or tablets |
|
Wide Color Gamut |
|
widecg |
· {@code widecg}: Displays with a wide color gamut such as Display P3 or AdobeRGB · {@code nowidecg}: Displays with a narrow color gamut such as sRGB |
|
High Dynamic Range (HDR) |
|
highdr |
· {@code highdr}: Displays with a high-dynamic range · {@code lowdr}: Displays with a low/standard dynamic range |
|
Screen orientation |
|
port |
· port: Device is in portrait orientation (vertical) · land: Device is in landscape orientation (horizontal) This can change during the life of your app if the user rotates the screen. |
|
UI mode |
|
car |
· car: Device is displaying in a car dock · desk: Device is displaying in a desk dock · television: Device is displaying on a television, providing a "ten foot" experience where its UI is on a large screen that the user is far away from, primarily oriented around DPAD or other non-pointer interaction · appliance: Device is serving as an appliance, with no display · watch: Device has a display and is worn on the wrist · vrheadset: Device is displaying in a virtual reality headset Added in API level 8, television added in API 13, watch added in API 20. For information about how your app can respond when the device is inserted into or removed from a dock, read Determining and Monitoring the Docking State and Type. This can change during the life of your app if the user places the device in a dock. You can enable or disable some of these modes using UiModeManager. See Handling Runtime Changesfor information about how this affects your app during runtime. |
|
Night mode |
|
night |
· night: Night time · notnight: Day time This can change during the life of your app if night mode is left in auto mode (default), in which case the mode changes based on the time of day. You can enable or disable this mode using UiModeManager. |
|
Screen pixel density (dpi) |
|
ldpi |
· ldpi: Low-density screens; approximately 120dpi. · mdpi: Medium-density (on traditional HVGA) screens; approximately 160dpi. · hdpi: High-density screens; approximately 240dpi. · xhdpi: Extra-high-density screens; approximately 320dpi. Added in API Level 8 · xxhdpi: Extra-extra-high-density screens; approximately 480dpi. Added in API Level 16 · xxxhdpi: Extra-extra-extra-high-density uses (launcher icon only, see the note in Supporting Multiple Screens); approximately 640dpi. Added in API Level 18 · nodpi: This can be used for bitmap resources that you don't want to be scaled to match the device density. · tvdpi: Screens somewhere between mdpi and hdpi; approximately 213dpi. This isn't considered a "primary" density group. It is mostly intended for televisions and most apps shouldn't need it—providing mdpi and hdpi resources is sufficient for most apps and the system scales them as appropriate. Added in API Level 13 · anydpi: This qualifier matches all screen densities and takes precedence over other qualifiers. This is useful for vector drawables. Added in API Level 21 · nnndpi: Used to represent non-standard densities, where nnn is a positive integer screen density. This shouldn't be used in most cases. Use standard density buckets, which greatly reduces the overhead of supporting the various device screen densities on the market. There is a 3:4:6:8:12:16 scaling ratio between the six primary densities (ignoring the tvdpi density). So, a 9x9 bitmap in ldpi is 12x12 in mdpi, 18x18 in hdpi, 24x24 in xhdpi and so on. If you decide that your image resources don't look good enough on a television or other certain devices and want to try tvdpi resources, the scaling factor is 1.33*mdpi. For example, a 100px x 100px image for mdpi screens should be 133px x 133px for tvdpi. Note: Using a density qualifier doesn't imply that the resources are only for screens of that density. If you don't provide alternative resources with qualifiers that better match the current device configuration, the system may use whichever resources are the best match. |
|
Touchscreen type |
|
notouch |
· notouch: Device doesn't have a touchscreen. · finger: Device has a touchscreen that is intended to be used through direction interaction of the user's finger. |
|
Keyboard availability |
|
keysexposed |
· keysexposed: Device has a keyboard available. If the device has a software keyboard enabled (which is likely), this may be used even when the hardware keyboard isn't exposed to the user, even if the device has no hardware keyboard. If no software keyboard is provided or it's disabled, then this is only used when a hardware keyboard is exposed. · keyshidden: Device has a hardware keyboard available but it is hidden and the device does not have a software keyboard enabled. · keyssoft: Device has a software keyboard enabled, whether it's visible or not. If you provide keysexposed resources, but not keyssoft resources, the system uses the keysexposed resources regardless of whether a keyboard is visible, as long as the system has a software keyboard enabled. This can change during the life of your app if the user opens a hardware keyboard. See Handling Runtime Changes for information about how this affects your app during runtime. |
|
Primary text input method |
|
nokeys |
· nokeys: Device has no hardware keys for text input. · qwerty: Device has a hardware qwerty keyboard, whether it's visible to the user or not. · 12key: Device has a hardware 12-key keyboard, whether it's visible to the user or not. |
|
Navigation key availability |
|
navexposed |
· navexposed: Navigation keys are available to the user. · navhidden: Navigation keys aren't available (such as behind a closed lid). This can change during the life of your app if the user reveals the navigation keys. See Handling Runtime Changes for information about how this affects your app during runtime. |
|
Primary non-touch navigation method |
|
nonav |
· nonav: Device has no navigation facility other than using the touchscreen. · dpad: Device has a directional-pad (d-pad) for navigation. · trackball: Device has a trackball for navigation. · wheel: Device has a directional wheel(s) for navigation (uncommon). |
|
Platform Version (API level) |
|
Examples: |
The API level supported by the device. For example, v1 for API level 1 (devices with Android 1.0 or higher) and v4 for API level 4 (devices with Android 1.6 or higher). |