| page.title=Providing Resources |
| parent.title=Application Resources |
| parent.link=index.html |
| @jd:body |
| |
| <div id="qv-wrapper"> |
| <div id="qv"> |
| <h2>Quickview</h2> |
| <ul> |
| <li>Different types of resources belong in different subdirectories of {@code res/}</li> |
| <li>Alternative resources provide configuration-specific resource files</li> |
| <li>Always include default resources so your app does not depend on specific |
| device configurations</li> |
| </ul> |
| <h2>In this document</h2> |
| <ol> |
| <li><a href="#ResourceTypes">Grouping Resource Types</a></li> |
| <li><a href="#AlternativeResources">Providing Alternative Resources</a> |
| <ol> |
| <li><a href="#QualifierRules">Qualifier name rules</a></li> |
| <li><a href="#AliasResources">Creating alias resources</a></li> |
| </ol> |
| </li> |
| <li><a href="#Compatibility">Providing the Best Device Compatibility with Resources</a></li> |
| <li><a href="#BestMatch">How Android Finds the Best-matching Resource</a></li> |
| </ol> |
| |
| <h2>See also</h2> |
| <ol> |
| <li><a href="accessing-resources.html">Accessing Resources</a></li> |
| <li><a href="available-resources.html">Resource Types</a></li> |
| <li><a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple |
| Screens</a></li> |
| </ol> |
| </div> |
| </div> |
| |
| <p>You should always externalize application resources such as images and strings from your |
| code, so that you can maintain them independently. You should also provide alternative resources for |
| specific device configurations, by grouping them in specially-named resource directories. At |
| runtime, Android uses the appropriate resource based on the current configuration. For |
| example, you might want to provide a different UI layout depending on the screen size or different |
| strings depending on the language setting.</p> |
| |
| <p>Once you externalize your application resources, you can access them |
| using resource IDs that are generated in your project's {@code R} class. How to use |
| resources in your application is discussed in <a href="accessing-resources.html">Accessing |
| Resources</a>. This document shows you how to group your resources in your Android project and |
| provide alternative resources for specific device configurations.</p> |
| |
| |
| <h2 id="ResourceTypes">Grouping Resource Types</h2> |
| |
| <p>You should place each type of resource in a specific subdirectory of your project's |
| {@code res/} directory. For example, here's the file hierarchy for a simple project:</p> |
| |
| <pre class="classic no-pretty-print"> |
| MyProject/ |
| src/ <span style="color:black"> |
| MyActivity.java </span> |
| res/ |
| drawable/ <span style="color:black"> |
| graphic.png </span> |
| layout/ <span style="color:black"> |
| main.xml |
| info.xml</span> |
| mipmap/ <span style="color:black"> |
| icon.png </span> |
| values/ <span style="color:black"> |
| strings.xml </span> |
| </pre> |
| |
| <p>As you can see in this example, the {@code res/} directory contains all the resources (in |
| subdirectories): an image resource, two layout resources, {@code mipmap/} directories for launcher |
| icons, and a string resource file. The resource |
| directory names are important and are described in table 1.</p> |
| |
| <p class="note"><strong>Note:</strong> For more information about using the mipmap folders, see |
| <a href="{@docRoot}tools/projects/index.html#mipmap">Managing Projects Overview</a>.</p> |
| |
| <p class="table-caption" id="table1"><strong>Table 1.</strong> Resource directories |
| supported inside project {@code res/} directory.</p> |
| |
| <table> |
| <tr> |
| <th scope="col">Directory</th> |
| <th scope="col">Resource Type</th> |
| </tr> |
| |
| <tr> |
| <td><code>animator/</code></td> |
| <td>XML files that define <a href="{@docRoot}guide/topics/graphics/prop-animation.html">property |
| animations</a>.</td> |
| </tr> |
| |
| <tr> |
| <td><code>anim/</code></td> |
| <td>XML files that define <a |
| href="{@docRoot}guide/topics/graphics/view-animation.html#tween-animation">tween |
| animations</a>. (Property animations can also be saved in this directory, but |
| the {@code animator/} directory is preferred for property animations to distinguish between the two |
| types.)</td> |
| </tr> |
| |
| <tr> |
| <td><code>color/</code></td> |
| <td>XML files that define a state list of colors. See <a href="color-list-resource.html">Color |
| State List Resource</a></td> |
| </tr> |
| |
| <tr> |
| <td><code>drawable/</code></td> |
| |
| <td><p>Bitmap files ({@code .png}, {@code .9.png}, {@code .jpg}, {@code .gif}) or XML files that |
| are compiled into the following drawable resource subtypes:</p> |
| <ul> |
| <li>Bitmap files</li> |
| <li>Nine-Patches (re-sizable bitmaps)</li> |
| <li>State lists</li> |
| <li>Shapes</li> |
| <li>Animation drawables</li> |
| <li>Other drawables</li> |
| </ul> |
| <p>See <a href="drawable-resource.html">Drawable Resources</a>.</p> |
| </td> |
| </tr> |
| |
| <tr> |
| <td><code>mipmap/</code></td> |
| <td>Drawable files for different launcher icon densities. For more information on managing |
| launcher icons with {@code mipmap/} folders, see |
| <a href="{@docRoot}tools/projects/index.html#mipmap">Managing Projects Overview</a>.</td> |
| </tr> |
| |
| <tr> |
| <td><code>layout/</code></td> |
| <td>XML files that define a user interface layout. |
| See <a href="layout-resource.html">Layout Resource</a>.</td> |
| </tr> |
| |
| <tr> |
| <td><code>menu/</code></td> |
| <td>XML files that define application menus, such as an Options Menu, Context Menu, or Sub |
| Menu. See <a href="menu-resource.html">Menu Resource</a>.</td> |
| </tr> |
| |
| <tr> |
| <td><code>raw/</code></td> |
| <td><p>Arbitrary files to save in their raw form. To open these resources with a raw |
| {@link java.io.InputStream}, call {@link android.content.res.Resources#openRawResource(int) |
| Resources.openRawResource()} with the resource ID, which is {@code R.raw.<em>filename</em>}.</p> |
| <p>However, if you need access to original file names and file hierarchy, you might consider |
| saving some resources in the {@code |
| assets/} directory (instead of {@code res/raw/}). Files in {@code assets/} are not given a |
| resource ID, so you can read them only using {@link android.content.res.AssetManager}.</p></td> |
| </tr> |
| |
| <tr> |
| <td><code>values/</code></td> |
| <td><p>XML files that contain simple values, such as strings, integers, and colors.</p> |
| <p>Whereas XML resource files in other {@code res/} subdirectories define a single resource |
| based on the XML filename, files in the {@code values/} directory describe multiple resources. |
| For a file in this directory, each child of the {@code <resources>} element defines a single |
| resource. For example, a {@code <string>} element creates an |
| {@code R.string} resource and a {@code <color>} element creates an {@code R.color} |
| resource.</p> |
| <p>Because each resource is defined with its own XML element, you can name the file |
| whatever you want and place different resource types in one file. However, for clarity, you might |
| want to place unique resource types in different files. For example, here are some filename |
| conventions for resources you can create in this directory:</p> |
| <ul> |
| <li>arrays.xml for resource arrays (<a |
| href="more-resources.html#TypedArray">typed arrays</a>).</li> |
| <li>colors.xml for <a |
| href="more-resources.html#Color">color values</a></li> |
| <li>dimens.xml for <a |
| href="more-resources.html#Dimension">dimension values</a>.</li> |
| <li>strings.xml for <a href="string-resource.html">string |
| values</a>.</li> |
| <li>styles.xml for <a href="style-resource.html">styles</a>.</li> |
| </ul> |
| <p>See <a href="string-resource.html">String Resources</a>, |
| <a href="style-resource.html">Style Resource</a>, and |
| <a href="more-resources.html">More Resource Types</a>.</p> |
| </td> |
| </tr> |
| |
| <tr> |
| <td><code>xml/</code></td> |
| <td>Arbitrary XML files that can be read at runtime by calling {@link |
| android.content.res.Resources#getXml(int) Resources.getXML()}. Various XML configuration files |
| must be saved here, such as a <a |
| href="{@docRoot}guide/topics/search/searchable-config.html">searchable configuration</a>. |
| <!-- or preferences configuration. --></td> |
| </tr> |
| </table> |
| |
| <p class="caution"><strong>Caution:</strong> Never save resource files directly inside the |
| {@code res/} directory—it will cause a compiler error.</p> |
| |
| <p>For more information about certain types of resources, see the <a |
| href="available-resources.html">Resource Types</a> documentation.</p> |
| |
| <p>The resources that you save in the subdirectories defined in table 1 are your "default" |
| resources. That is, these resources define the default design and content for your application. |
| However, different types of Android-powered devices might call for different types of resources. |
| For example, if a device has a larger than normal screen, then you should provide |
| different layout resources that take advantage of the extra screen space. Or, if a device has a |
| different language setting, then you should provide different string resources that translate the |
| text in your user interface. To provide these different resources for different device |
| configurations, you need to provide alternative resources, in addition to your default |
| resources.</p> |
| |
| |
| <h2 id="AlternativeResources">Providing Alternative Resources</h2> |
| |
| |
| <div class="figure" style="width:429px"> |
| <img src="{@docRoot}images/resources/resource_devices_diagram2.png" height="167" alt="" /> |
| <p class="img-caption"> |
| <strong>Figure 1.</strong> Two different devices, each using different layout resources.</p> |
| </div> |
| |
| <p>Almost every application should provide alternative resources to support specific device |
| configurations. For instance, you should include alternative drawable resources for different |
| screen densities and alternative string resources for different languages. At runtime, Android |
| detects the current device configuration and loads the appropriate |
| resources for your application.</p> |
| |
| <p>To specify configuration-specific alternatives for a set of resources:</p> |
| <ol> |
| <li>Create a new directory in {@code res/} named in the form {@code |
| <em><resources_name></em>-<em><config_qualifier></em>}. |
| <ul> |
| <li><em>{@code <resources_name>}</em> is the directory name of the corresponding default |
| resources (defined in table 1).</li> |
| <li><em>{@code <qualifier>}</em> is a name that specifies an individual configuration |
| for which these resources are to be used (defined in table 2).</li> |
| </ul> |
| <p>You can append more than one <em>{@code <qualifier>}</em>. Separate each |
| one with a dash.</p> |
| <p class="caution"><strong>Caution:</strong> When appending multiple qualifiers, you must |
| place them in the same order in which they are listed in table 2. If the qualifiers are ordered |
| wrong, the resources are ignored.</p> |
| </li> |
| <li>Save the respective alternative resources in this new directory. The resource files must be |
| named exactly the same as the default resource files.</li> |
| </ol> |
| |
| <p>For example, here are some default and alternative resources:</p> |
| |
| <pre class="classic no-pretty-print"> |
| res/ |
| drawable/ <span style="color:black"> |
| icon.png |
| background.png </span> |
| drawable-hdpi/ <span style="color:black"> |
| icon.png |
| background.png </span> |
| </pre> |
| |
| <p>The {@code hdpi} qualifier indicates that the resources in that directory are for devices with a |
| high-density screen. The images in each of these drawable directories are sized for a specific |
| screen density, but the filenames are exactly |
| the same. This way, the resource ID that you use to reference the {@code icon.png} or {@code |
| background.png} image is always the same, but Android selects the |
| version of each resource that best matches the current device, by comparing the device |
| configuration information with the qualifiers in the resource directory name.</p> |
| |
| <p>Android supports several configuration qualifiers and you can |
| add multiple qualifiers to one directory name, by separating each qualifier with a dash. Table 2 |
| lists the valid configuration qualifiers, in order of precedence—if you use multiple |
| qualifiers for a resource directory, you must add them to the directory name in the order they |
| are listed in the table.</p> |
| |
| |
| <p class="table-caption" id="table2"><strong>Table 2.</strong> Configuration qualifier |
| names.</p> |
| <table> |
| <tr> |
| <th>Configuration</th> |
| <th>Qualifier Values</th> |
| <th>Description</th> |
| </tr> |
| <tr id="MccQualifier"> |
| <td>MCC and MNC</td> |
| <td>Examples:<br/> |
| <code>mcc310</code><br/> |
| <code><nobr>mcc310-mnc004</nobr></code><br/> |
| <code>mcc208-mnc00</code><br/> |
| etc. |
| </td> |
| <td> |
| <p>The mobile country code (MCC), optionally followed by mobile network code (MNC) |
| from the SIM card in the device. For example, <code>mcc310</code> is U.S. on any carrier, |
| <code>mcc310-mnc004</code> is U.S. on Verizon, and <code>mcc208-mnc00</code> is France on |
| Orange.</p> |
| <p>If the device uses a radio connection (GSM phone), the MCC and MNC values come |
| from the SIM card.</p> |
| <p>You can also use the MCC alone (for example, to include country-specific legal |
| resources in your application). If you need to specify based on the language only, then use the |
| <em>language and region</em> qualifier 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.</p> |
| <p>Also see the configuration fields {@link |
| android.content.res.Configuration#mcc}, and {@link |
| android.content.res.Configuration#mnc}, which indicate the current mobile country code |
| and mobile network code, respectively.</p> |
| </td> |
| </tr> |
| <tr id="LocaleQualifier"> |
| <td>Language and region</td> |
| <td>Examples:<br/> |
| <code>en</code><br/> |
| <code>fr</code><br/> |
| <code>en-rUS</code><br/> |
| <code>fr-rFR</code><br/> |
| <code>fr-rCA</code><br/> |
| etc. |
| </td> |
| <td><p>The language is defined by a two-letter <a |
| href="http://www.loc.gov/standards/iso639-2/php/code_list.php">ISO |
| 639-1</a> language code, optionally followed by a two letter |
| <a |
| href="http://www.iso.org/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html">ISO |
| 3166-1-alpha-2</a> region code (preceded by lowercase "{@code r}"). |
| </p><p> |
| The codes are <em>not</em> case-sensitive; the {@code r} prefix is used to |
| distinguish the region portion. |
| You cannot specify a region alone.</p> |
| <p>This can change during the life |
| of your application if the user changes his or her language in the system settings. See <a |
| href="runtime-changes.html">Handling Runtime Changes</a> for information about |
| how this can affect your application during runtime.</p> |
| <p>See <a href="localization.html">Localization</a> for a complete guide to localizing |
| your application for other languages.</p> |
| <p>Also see the {@link android.content.res.Configuration#locale} configuration field, which |
| indicates the current locale.</p> |
| </td> |
| </tr> |
| <tr id="LayoutDirectionQualifier"> |
| <td>Layout Direction</td> |
| <td><code>ldrtl</code><br/> |
| <code>ldltr</code><br/> |
| </td> |
| <td><p>The layout direction of your application. {@code ldrtl} means "layout-direction-right-to-left". |
| {@code ldltr} means "layout-direction-left-to-right" and is the default implicit value. |
| </p> |
| <p>This can apply to any resource such as layouts, drawables, or values. |
| </p> |
| <p>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: |
| </p> |
| <pre class="classic no-pretty-print"> |
| res/ |
| layout/ <span style="color:black"> |
| main.xml </span>(Default layout) |
| layout-ar/ <span style="color:black"> |
| main.xml </span>(Specific layout for Arabic) |
| layout-ldrtl/ <span style="color:black"> |
| main.xml </span>(Any "right-to-left" language, except |
| for Arabic, because the "ar" language qualifier |
| has a higher precedence.) |
| </pre> |
| <p class="note"><strong>Note:</strong> To enable right-to-left layout features |
| for your app, you must set <a |
| href="{@docRoot}guide/topics/manifest/application-element.html#supportsrtl">{@code |
| supportsRtl}</a> to {@code "true"} and set <a |
| href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target" |
| >{@code targetSdkVersion}</a> to 17 or higher.</p> |
| <p><em>Added in API level 17.</em></p> |
| </td> |
| </tr> |
| <tr id="SmallestScreenWidthQualifier"> |
| <td>smallestWidth</td> |
| <td><code>sw<N>dp</code><br/><br/> |
| Examples:<br/> |
| <code>sw320dp</code><br/> |
| <code>sw600dp</code><br/> |
| <code>sw720dp</code><br/> |
| etc. |
| </td> |
| <td> |
| <p>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 |
| application has at least {@code <N>} dps of width available for its UI.</p> |
| <p>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 qualifer to create the layout resources, {@code |
| res/layout-sw600dp/}. The system will use 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 smallestWidth is a fixed screen size characteristic of the device; <strong>the |
| device's smallestWidth does not change when the screen's orientation changes</strong>.</p> |
| <p>The smallestWidth 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 smallestWidth, the system declares the smallestWidth to be smaller than the actual |
| screen size, because those are screen pixels not available for your UI. Thus, the value you use |
| should be the actual smallest dimension <em>required by your layout</em> (usually, this value is the |
| "smallest width" that your layout supports, regardless of the screen's current orientation).</p> |
| <p>Some values you might use here for common screen sizes:</p> |
| <ul> |
| <li>320, for devices with screen configurations such as: |
| <ul> |
| <li>240x320 ldpi (QVGA handset)</li> |
| <li>320x480 mdpi (handset)</li> |
| <li>480x800 hdpi (high-density handset)</li> |
| </ul> |
| </li> |
| <li>480, for screens such as 480x800 mdpi (tablet/handset).</li> |
| <li>600, for screens such as 600x1024 mdpi (7" tablet).</li> |
| <li>720, for screens such as 720x1280 mdpi (10" tablet).</li> |
| </ul> |
| <p>When your application provides multiple resource directories with different values for |
| the smallestWidth qualifier, the system uses the one closest to (without exceeding) the |
| device's smallestWidth. </p> |
| <p><em>Added in API level 13.</em></p> |
| <p>Also see the <a |
| href="{@docRoot}guide/topics/manifest/supports-screens-element.html#requiresSmallest">{@code |
| android:requiresSmallestWidthDp}</a> attribute, which declares the minimum smallestWidth with which |
| your application is compatible, and the {@link |
| android.content.res.Configuration#smallestScreenWidthDp} configuration field, which holds the |
| device's smallestWidth value.</p> |
| <p>For more information about designing for different screens and using this |
| qualifier, see the <a href="{@docRoot}guide/practices/screens_support.html">Supporting |
| Multiple Screens</a> developer guide.</p> |
| </td> |
| </tr> |
| <tr id="ScreenWidthQualifier"> |
| <td>Available width</td> |
| <td><code>w<N>dp</code><br/><br/> |
| Examples:<br/> |
| <code>w720dp</code><br/> |
| <code>w1024dp</code><br/> |
| etc. |
| </td> |
| <td> |
| <p>Specifies a minimum available screen width, in {@code dp} units at which the resource |
| should be used—defined by the <code><N></code> value. This |
| configuration value will change when the orientation |
| changes between landscape and portrait to match the current actual width.</p> |
| <p>When your application 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 application's available space.</p> |
| <p><em>Added in API level 13.</em></p> |
| <p>Also see the {@link android.content.res.Configuration#screenWidthDp} |
| configuration field, which holds the current screen width.</p> |
| <p>For more information about designing for different screens and using this |
| qualifier, see the <a href="{@docRoot}guide/practices/screens_support.html">Supporting |
| Multiple Screens</a> developer guide.</p> |
| </td> |
| </tr> |
| <tr id="ScreenHeightQualifier"> |
| <td>Available height</td> |
| <td><code>h<N>dp</code><br/><br/> |
| Examples:<br/> |
| <code>h720dp</code><br/> |
| <code>h1024dp</code><br/> |
| etc. |
| </td> |
| <td> |
| <p>Specifies a minimum available screen height, in "dp" units at which the resource |
| should be used—defined by the <code><N></code> value. This |
| configuration value will change when the orientation |
| changes between landscape and portrait to match the current actual height.</p> |
| <p>When your application 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 application's available space. Screen |
| decorations that are not fixed (such as a phone status bar that can be |
| hidden when full screen) are <em>not</em> accounted for here, nor are |
| window decorations like the title bar or action bar, so applications must be prepared to |
| deal with a somewhat smaller space than they specify. |
| <p><em>Added in API level 13.</em></p> |
| <p>Also see the {@link android.content.res.Configuration#screenHeightDp} |
| configuration field, which holds the current screen width.</p> |
| <p>For more information about designing for different screens and using this |
| qualifier, see the <a href="{@docRoot}guide/practices/screens_support.html">Supporting |
| Multiple Screens</a> developer guide.</p> |
| </td> |
| </tr> |
| <tr id="ScreenSizeQualifier"> |
| <td>Screen size</td> |
| <td> |
| <code>small</code><br/> |
| <code>normal</code><br/> |
| <code>large</code><br/> |
| <code>xlarge</code> |
| </td> |
| <td> |
| <ul class="nolist"> |
| <li>{@code 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.</li> |
| <li>{@code 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.</li> |
| <li>{@code 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.</li> |
| <li>{@code 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. <em>Added in API level 9.</em></li> |
| </ul> |
| <p class="note"><strong>Note:</strong> Using a size qualifier does not imply that the |
| resources are <em>only</em> 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 <a href="#BestMatch">best match</a>.</p> |
| <p class="caution"><strong>Caution:</strong> If all your resources use a size qualifier that |
| is <em>larger</em> than the current screen, the system will <strong>not</strong> use them and your |
| application will crash at runtime (for example, if all layout resources are tagged with the {@code |
| xlarge} qualifier, but the device is a normal-size screen).</p> |
| <p><em>Added in API level 4.</em></p> |
| |
| <p>See <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple |
| Screens</a> for more information.</p> |
| <p>Also see the {@link android.content.res.Configuration#screenLayout} configuration field, |
| which indicates whether the screen is small, normal, |
| or large.</p> |
| </td> |
| </tr> |
| <tr id="ScreenAspectQualifier"> |
| <td>Screen aspect</td> |
| <td> |
| <code>long</code><br/> |
| <code>notlong</code> |
| </td> |
| <td> |
| <ul class="nolist"> |
| <li>{@code long}: Long screens, such as WQVGA, WVGA, FWVGA</li> |
| <li>{@code notlong}: Not long screens, such as QVGA, HVGA, and VGA</li> |
| </ul> |
| <p><em>Added in API level 4.</em></p> |
| <p>This is based purely on the aspect ratio of the screen (a "long" screen is wider). This |
| is not related to the screen orientation.</p> |
| <p>Also see the {@link android.content.res.Configuration#screenLayout} configuration field, |
| which indicates whether the screen is long.</p> |
| </td> |
| </tr> |
| <tr id="ScreenRoundQualifier"> |
| <td>Round screen</td> |
| <td> |
| <code>round</code><br/> |
| <code>notround</code> |
| </td> |
| <td> |
| <ul class="nolist"> |
| <li>{@code round}: Round screens, such as a round wearable device</li> |
| <li>{@code notround}: Rectangular screens, such as phones or tablets</li> |
| </ul> |
| <p><em>Added in API level 23.</em></p> |
| <p>Also see the {@link android.content.res.Configuration#isScreenRound()} configuration |
| method, which indicates whether the screen is round.</p> |
| </td> |
| </tr> |
| <tr id="OrientationQualifier"> |
| <td>Screen orientation</td> |
| <td> |
| <code>port</code><br/> |
| <code>land</code> <!-- <br/> |
| <code>square</code> --> |
| </td> |
| <td> |
| <ul class="nolist"> |
| <li>{@code port}: Device is in portrait orientation (vertical)</li> |
| <li>{@code land}: Device is in landscape orientation (horizontal)</li> |
| <!-- Square mode is currently not used. --> |
| </ul> |
| <p>This can change during the life of your application if the user rotates the |
| screen. See <a href="runtime-changes.html">Handling Runtime Changes</a> for information about |
| how this affects your application during runtime.</p> |
| <p>Also see the {@link android.content.res.Configuration#orientation} configuration field, |
| which indicates the current device orientation.</p> |
| </td> |
| </tr> |
| <tr id="UiModeQualifier"> |
| <td>UI mode</td> |
| <td> |
| <code>car</code><br/> |
| <code>desk</code><br/> |
| <code>television<br/> |
| <code>appliance</code> |
| <code>watch</code> |
| </td> |
| <td> |
| <ul class="nolist"> |
| <li>{@code car}: Device is displaying in a car dock</li> |
| <li>{@code desk}: Device is displaying in a desk dock</li> |
| <li>{@code 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</li> |
| <li>{@code appliance}: Device is serving as an appliance, with |
| no display</li> |
| <li>{@code watch}: Device has a display and is worn on the wrist</li> |
| </ul> |
| <p><em>Added in API level 8, television added in API 13, watch added in API 20.</em></p> |
| <p>For information about how your app can respond when the device is inserted into or |
| removed from a dock, read <a |
| href="{@docRoot}training/monitoring-device-state/docking-monitoring.html">Determining |
| and Monitoring the Docking State and Type</a>.</p> |
| <p>This can change during the life of your application if the user places the device in a |
| dock. You can enable or disable some of these modes using {@link |
| android.app.UiModeManager}. See <a href="runtime-changes.html">Handling Runtime Changes</a> for |
| information about how this affects your application during runtime.</p> |
| </td> |
| </tr> |
| <tr id="NightQualifier"> |
| <td>Night mode</td> |
| <td> |
| <code>night</code><br/> |
| <code>notnight</code> |
| </td> |
| <td> |
| <ul class="nolist"> |
| <li>{@code night}: Night time</li> |
| <li>{@code notnight}: Day time</li> |
| </ul> |
| <p><em>Added in API level 8.</em></p> |
| <p>This can change during the life of your application 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 {@link android.app.UiModeManager}. See <a |
| href="runtime-changes.html">Handling Runtime Changes</a> for information about how this affects your |
| application during runtime.</p> |
| </td> |
| </tr> |
| <tr id="DensityQualifier"> |
| <td>Screen pixel density (dpi)</td> |
| <td> |
| <code>ldpi</code><br/> |
| <code>mdpi</code><br/> |
| <code>hdpi</code><br/> |
| <code>xhdpi</code><br/> |
| <code>xxhdpi</code><br/> |
| <code>xxxhdpi</code><br/> |
| <code>nodpi</code><br/> |
| <code>tvdpi</code><br/> |
| <code>anydpi</code> |
| </td> |
| <td> |
| <ul class="nolist"> |
| <li>{@code ldpi}: Low-density screens; approximately 120dpi.</li> |
| <li>{@code mdpi}: Medium-density (on traditional HVGA) screens; approximately |
| 160dpi.</li> |
| <li>{@code hdpi}: High-density screens; approximately 240dpi.</li> |
| <li>{@code xhdpi}: Extra-high-density screens; approximately 320dpi. <em>Added in API |
| Level 8</em></li> |
| <li>{@code xxhdpi}: Extra-extra-high-density screens; approximately 480dpi. <em>Added in API |
| Level 16</em></li> |
| <li>{@code xxxhdpi}: Extra-extra-extra-high-density uses (launcher icon only, see the |
| <a href="{@docRoot}guide/practices/screens_support.html#xxxhdpi-note">note</a> |
| in <em>Supporting Multiple Screens</em>); approximately 640dpi. <em>Added in API |
| Level 18</em></li> |
| <li>{@code nodpi}: This can be used for bitmap resources that you do not want to be scaled |
| to match the device density.</li> |
| <li>{@code tvdpi}: Screens somewhere between mdpi and hdpi; approximately 213dpi. This is |
| not 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 will scale them as appropriate. <em>Added in API Level 13</em></li> |
| <li>{@code anydpi}: This qualifier matches all screen densities and takes precedence over |
| other qualifiers. This is useful for |
| <a href="{@docRoot}training/material/drawables.html#VectorDrawables">vector drawables</a>. |
| <em>Added in API Level 21</em></li> |
| </ul> |
| <p>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. |
| </p> |
| <p>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.</p> |
| <p class="note"><strong>Note:</strong> Using a density qualifier does not imply that the |
| resources are <em>only</em> for screens of that density. If you do not provide alternative |
| resources with qualifiers that better match the current device configuration, the system may use |
| whichever resources are the <a href="#BestMatch">best match</a>.</p> |
| <p>See <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple |
| Screens</a> for more information about how to handle different screen densities and how Android |
| might scale your bitmaps to fit the current density.</p> |
| </td> |
| </tr> |
| <tr id="TouchscreenQualifier"> |
| <td>Touchscreen type</td> |
| <td> |
| <code>notouch</code><br/> |
| <code>finger</code> |
| </td> |
| <td> |
| <ul class="nolist"> |
| <li>{@code notouch}: Device does not have a touchscreen.</li> |
| <li>{@code finger}: Device has a touchscreen that is intended to |
| be used through direction interaction of the user's finger.</li> |
| </ul> |
| <p>Also see the {@link android.content.res.Configuration#touchscreen} configuration field, |
| which indicates the type of touchscreen on the device.</p> |
| </td> |
| </tr> |
| <tr id="KeyboardAvailQualifier"> |
| <td>Keyboard availability</td> |
| <td> |
| <code>keysexposed</code><br/> |
| <code>keyshidden</code><br/> |
| <code>keyssoft</code> |
| </td> |
| <td> |
| <ul class="nolist"> |
| <li>{@code 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 is |
| <em>not</em> 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.</li> |
| <li>{@code keyshidden}: Device has a hardware keyboard available but it is |
| hidden <em>and</em> the device does <em>not</em> have a software keyboard enabled.</li> |
| <li>{@code keyssoft}: Device has a software keyboard enabled, whether it's |
| visible or not.</li> |
| </ul> |
| <p>If you provide <code>keysexposed</code> resources, but not <code>keyssoft</code> |
| resources, the system uses the <code>keysexposed</code> resources regardless of whether a |
| keyboard is visible, as long as the system has a software keyboard enabled.</p> |
| <p>This can change during the life of your application if the user opens a hardware |
| keyboard. See <a href="runtime-changes.html">Handling Runtime Changes</a> for information about how |
| this affects your application during runtime.</p> |
| <p>Also see the configuration fields {@link |
| android.content.res.Configuration#hardKeyboardHidden} and {@link |
| android.content.res.Configuration#keyboardHidden}, which indicate the visibility of a hardware |
| keyboard and and the visibility of any kind of keyboard (including software), respectively.</p> |
| </td> |
| </tr> |
| <tr id="ImeQualifier"> |
| <td>Primary text input method</td> |
| <td> |
| <code>nokeys</code><br/> |
| <code>qwerty</code><br/> |
| <code>12key</code> |
| </td> |
| <td> |
| <ul class="nolist"> |
| <li>{@code nokeys}: Device has no hardware keys for text input.</li> |
| <li>{@code qwerty}: Device has a hardware qwerty keyboard, whether it's visible to the |
| user |
| or not.</li> |
| <li>{@code 12key}: Device has a hardware 12-key keyboard, whether it's visible to the user |
| or not.</li> |
| </ul> |
| <p>Also see the {@link android.content.res.Configuration#keyboard} configuration field, |
| which indicates the primary text input method available.</p> |
| </td> |
| </tr> |
| <tr id="NavAvailQualifier"> |
| <td>Navigation key availability</td> |
| <td> |
| <code>navexposed</code><br/> |
| <code>navhidden</code> |
| </td> |
| <td> |
| <ul class="nolist"> |
| <li>{@code navexposed}: Navigation keys are available to the user.</li> |
| <li>{@code navhidden}: Navigation keys are not available (such as behind a closed |
| lid).</li> |
| </ul> |
| <p>This can change during the life of your application if the user reveals the navigation |
| keys. See <a href="runtime-changes.html">Handling Runtime Changes</a> for |
| information about how this affects your application during runtime.</p> |
| <p>Also see the {@link android.content.res.Configuration#navigationHidden} configuration |
| field, which indicates whether navigation keys are hidden.</p> |
| </td> |
| </tr> |
| <tr id="NavigationQualifier"> |
| <td>Primary non-touch navigation method</td> |
| <td> |
| <code>nonav</code><br/> |
| <code>dpad</code><br/> |
| <code>trackball</code><br/> |
| <code>wheel</code> |
| </td> |
| <td> |
| <ul class="nolist"> |
| <li>{@code nonav}: Device has no navigation facility other than using the |
| touchscreen.</li> |
| <li>{@code dpad}: Device has a directional-pad (d-pad) for navigation.</li> |
| <li>{@code trackball}: Device has a trackball for navigation.</li> |
| <li>{@code wheel}: Device has a directional wheel(s) for navigation (uncommon).</li> |
| </ul> |
| <p>Also see the {@link android.content.res.Configuration#navigation} configuration field, |
| which indicates the type of navigation method available.</p> |
| </td> |
| </tr> |
| <!-- DEPRECATED |
| <tr> |
| <td>Screen dimensions</td> |
| <td>Examples:<br/> |
| <code>320x240</code><br/> |
| <code>640x480</code><br/> |
| etc. |
| </td> |
| <td> |
| <p>The larger dimension must be specified first. <strong>This configuration is deprecated |
| and should not be used</strong>. Instead use "screen size," "wider/taller screens," and "screen |
| orientation" described above.</p> |
| </td> |
| </tr> |
| --> |
| <tr id="VersionQualifier"> |
| <td>Platform Version (API level)</td> |
| <td>Examples:<br/> |
| <code>v3</code><br/> |
| <code>v4</code><br/> |
| <code>v7</code><br/> |
| etc.</td> |
| <td> |
| <p>The API level supported by the device. For example, <code>v1</code> for API level |
| 1 (devices with Android 1.0 or higher) and <code>v4</code> for API level 4 (devices with Android |
| 1.6 or higher). See the <a |
| href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#ApiLevels">Android API levels</a> document for more information |
| about these values.</p> |
| </td> |
| </tr> |
| </table> |
| |
| |
| <p class="note"><strong>Note:</strong> Some configuration qualifiers have been added since Android |
| 1.0, so not all versions of Android support all the qualifiers. Using a new qualifier implicitly |
| adds the platform version qualifier so that older devices are sure to ignore it. For example, using |
| a <code>w600dp</code> qualifier will automatically include the <code>v13</code> qualifier, because |
| the available-width qualifier was new in API level 13. To avoid any issues, always include a set of |
| default resources (a set of resources with <em>no qualifiers</em>). For more information, see the |
| section about <a href="#Compatibility">Providing the Best Device Compatibility with |
| Resources</a>.</p> |
| |
| |
| |
| <h3 id="QualifierRules">Qualifier name rules</h3> |
| |
| <p>Here are some rules about using configuration qualifier names:</p> |
| |
| <ul> |
| <li>You can specify multiple qualifiers for a single set of resources, separated by dashes. For |
| example, <code>drawable-en-rUS-land</code> applies to US-English devices in landscape |
| orientation.</li> |
| <li>The qualifiers must be in the order listed in <a href="#table2">table 2</a>. For |
| example: |
| <ul> |
| <li>Wrong: <code>drawable-hdpi-port/</code></li> |
| <li>Correct: <code>drawable-port-hdpi/</code></li> |
| </ul> |
| </li> |
| <li>Alternative resource directories cannot be nested. For example, you cannot have |
| <code>res/drawable/drawable-en/</code>.</li> |
| <li>Values are case-insensitive. The resource compiler converts directory names |
| to lower case before processing to avoid problems on case-insensitive |
| file systems. Any capitalization in the names is only to benefit readability.</li> |
| <li>Only one value for each qualifier type is supported. For example, if you want to use |
| the same drawable files for Spain and France, you <em>cannot</em> have a directory named |
| <code>drawable-rES-rFR/</code>. Instead you need two resource directories, such as |
| <code>drawable-rES/</code> and <code>drawable-rFR/</code>, which contain the appropriate files. |
| However, you are not required to actually duplicate the same files in both locations. Instead, you |
| can create an alias to a resource. See <a href="#AliasResources">Creating |
| alias resources</a> below.</li> |
| </ul> |
| |
| <p>After you save alternative resources into directories named with |
| these qualifiers, Android automatically applies the resources in your application based on the |
| current device configuration. Each time a resource is requested, Android checks for alternative |
| resource directories that contain the requested resource file, then <a href="#BestMatch">finds the |
| best-matching resource</a> (discussed below). If there are no alternative resources that match |
| a particular device configuration, then Android uses the corresponding default resources (the |
| set of resources for a particular resource type that does not include a configuration |
| qualifier).</p> |
| |
| |
| |
| <h3 id="AliasResources">Creating alias resources</h3> |
| |
| <p>When you have a resource that you'd like to use for more than one device |
| configuration (but do not want to provide as a default resource), you do not need to put the same |
| resource in more than one alternative resource directory. Instead, you can (in some cases) create an |
| alternative |
| resource that acts as an alias for a resource saved in your default resource directory.</p> |
| |
| <p class="note"><strong>Note:</strong> Not all resources offer a mechanism by which you can |
| create an alias to another resource. In particular, animation, menu, raw, and other unspecified |
| resources in the {@code xml/} directory do not offer this feature.</p> |
| |
| <p>For example, imagine you have an application icon, {@code icon.png}, and need unique version of |
| it for different locales. However, two locales, English-Canadian and French-Canadian, need to |
| use the same version. You might assume that you need to copy the same image |
| into the resource directory for both English-Canadian and French-Canadian, but it's |
| not true. Instead, you can save the image that's used for both as {@code icon_ca.png} (any |
| name other than {@code icon.png}) and put |
| it in the default {@code res/drawable/} directory. Then create an {@code icon.xml} file in {@code |
| res/drawable-en-rCA/} and {@code res/drawable-fr-rCA/} that refers to the {@code icon_ca.png} |
| resource using the {@code <bitmap>} element. This allows you to store just one version of the |
| PNG file and two small XML files that point to it. (An example XML file is shown below.)</p> |
| |
| |
| <h4>Drawable</h4> |
| |
| <p>To create an alias to an existing drawable, use the {@code <bitmap>} element. |
| For example:</p> |
| |
| <pre> |
| <?xml version="1.0" encoding="utf-8"?> |
| <bitmap xmlns:android="http://schemas.android.com/apk/res/android" |
| android:src="@drawable/icon_ca" /> |
| </pre> |
| |
| <p>If you save this file as {@code icon.xml} (in an alternative resource directory, such as |
| {@code res/drawable-en-rCA/}), it is compiled into a resource that you |
| can reference as {@code R.drawable.icon}, but is actually an alias for the {@code |
| R.drawable.icon_ca} resource (which is saved in {@code res/drawable/}).</p> |
| |
| |
| <h4>Layout</h4> |
| |
| <p>To create an alias to an existing layout, use the {@code <include>} |
| element, wrapped in a {@code <merge>}. For example:</p> |
| |
| <pre> |
| <?xml version="1.0" encoding="utf-8"?> |
| <merge> |
| <include layout="@layout/main_ltr"/> |
| </merge> |
| </pre> |
| |
| <p>If you save this file as {@code main.xml}, it is compiled into a resource you can reference |
| as {@code R.layout.main}, but is actually an alias for the {@code R.layout.main_ltr} |
| resource.</p> |
| |
| |
| <h4>Strings and other simple values</h4> |
| |
| <p>To create an alias to an existing string, simply use the resource ID of the desired |
| string as the value for the new string. For example:</p> |
| |
| <pre> |
| <?xml version="1.0" encoding="utf-8"?> |
| <resources> |
| <string name="hello">Hello</string> |
| <string name="hi">@string/hello</string> |
| </resources> |
| </pre> |
| |
| <p>The {@code R.string.hi} resource is now an alias for the {@code R.string.hello}.</p> |
| |
| <p> <a href="{@docRoot}guide/topics/resources/more-resources.html">Other simple values</a> work the |
| same way. For example, a color:</p> |
| |
| <pre> |
| <?xml version="1.0" encoding="utf-8"?> |
| <resources> |
| <color name="red">#f00</color> |
| <color name="highlight">@color/red</color> |
| </resources> |
| </pre> |
| |
| |
| |
| |
| <h2 id="Compatibility">Providing the Best Device Compatibility with Resources</h2> |
| |
| <p>In order for your application to support multiple device configurations, it's very important that |
| you always provide default resources for each type of resource that your application uses.</p> |
| |
| <p>For example, if your application supports several languages, always include a {@code |
| values/} directory (in which your strings are saved) <em>without</em> a <a |
| href="#LocaleQualifier">language and region qualifier</a>. If you instead put all your string files |
| in directories that have a language and region qualifier, then your application will crash when run |
| on a device set to a language that your strings do not support. But, as long as you provide default |
| {@code values/} resources, then your application will run properly (even if the user doesn't |
| understand that language—it's better than crashing).</p> |
| |
| <p>Likewise, if you provide different layout resources based on the screen orientation, you should |
| pick one orientation as your default. For example, instead of providing layout resources in {@code |
| layout-land/} for landscape and {@code layout-port/} for portrait, leave one as the default, such as |
| {@code layout/} for landscape and {@code layout-port/} for portrait.</p> |
| |
| <p>Providing default resources is important not only because your application might run on a |
| configuration you had not anticipated, but also because new versions of Android sometimes add |
| configuration qualifiers that older versions do not support. If you use a new resource qualifier, |
| but maintain code compatibility with older versions of Android, then when an older version of |
| Android runs your application, it will crash if you do not provide default resources, because it |
| cannot use the resources named with the new qualifier. For example, if your <a |
| href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code |
| minSdkVersion}</a> is set to 4, and you qualify all of your drawable resources using <a |
| href="#NightQualifier">night mode</a> ({@code night} or {@code notnight}, which were added in API |
| Level 8), then an API level 4 device cannot access your drawable resources and will crash. In this |
| case, you probably want {@code notnight} to be your default resources, so you should exclude that |
| qualifier so your drawable resources are in either {@code drawable/} or {@code drawable-night/}.</p> |
| |
| <p>So, in order to provide the best device compatibility, always provide default |
| resources for the resources your application needs to perform properly. Then create alternative |
| resources for specific device configurations using the configuration qualifiers.</p> |
| |
| <p>There is one exception to this rule: If your application's <a |
| href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> is 4 or |
| greater, you <em>do not</em> need default drawable resources when you provide alternative drawable |
| resources with the <a href="#DensityQualifier">screen density</a> qualifier. Even without default |
| drawable resources, Android can find the best match among the alternative screen densities and scale |
| the bitmaps as necessary. However, for the best experience on all types of devices, you should |
| provide alternative drawables for all three types of density.</p> |
| |
| |
| |
| <h2 id="BestMatch">How Android Finds the Best-matching Resource</h2> |
| |
| <p>When you request a resource for which you provide alternatives, Android selects which |
| alternative resource to use at runtime, depending on the current device configuration. To |
| demonstrate how Android selects an alternative resource, assume the following drawable directories |
| each contain different versions of the same images:</p> |
| |
| <pre class="classic no-pretty-print"> |
| drawable/ |
| drawable-en/ |
| drawable-fr-rCA/ |
| drawable-en-port/ |
| drawable-en-notouch-12key/ |
| drawable-port-ldpi/ |
| drawable-port-notouch-12key/ |
| </pre> |
| |
| <p>And assume the following is the device configuration:</p> |
| |
| <p style="margin-left:1em;"> |
| Locale = <code>en-GB</code> <br/> |
| Screen orientation = <code>port</code> <br/> |
| Screen pixel density = <code>hdpi</code> <br/> |
| Touchscreen type = <code>notouch</code> <br/> |
| Primary text input method = <code>12key</code> |
| </p> |
| |
| <p>By comparing the device configuration to the available alternative resources, Android selects |
| drawables from {@code drawable-en-port}.</p> |
| |
| <p>The system arrives at its decision for which resources to use with the following |
| logic:</p> |
| |
| |
| <div class="figure" style="width:371px"> |
| <img src="{@docRoot}images/resources/res-selection-flowchart.png" alt="" height="471" /> |
| <p class="img-caption"><strong>Figure 2.</strong> Flowchart of how Android finds the |
| best-matching resource.</p> |
| </div> |
| |
| |
| <ol> |
| <li>Eliminate resource files that contradict the device configuration. |
| <p>The <code>drawable-fr-rCA/</code> directory is eliminated, because it |
| contradicts the <code>en-GB</code> locale.</p> |
| <pre class="classic no-pretty-print"> |
| drawable/ |
| drawable-en/ |
| <strike>drawable-fr-rCA/</strike> |
| drawable-en-port/ |
| drawable-en-notouch-12key/ |
| drawable-port-ldpi/ |
| drawable-port-notouch-12key/ |
| </pre> |
| <p class="note"><strong>Exception:</strong> Screen pixel density is the one qualifier that is not |
| eliminated due to a contradiction. Even though the screen density of the device is hdpi, |
| <code>drawable-port-ldpi/</code> is not eliminated because every screen density is |
| considered to be a match at this point. More information is available in the <a |
| href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple |
| Screens</a> document.</p></li> |
| |
| <li>Pick the (next) highest-precedence qualifier in the list (<a href="#table2">table 2</a>). |
| (Start with MCC, then move down.) </li> |
| <li>Do any of the resource directories include this qualifier? </li> |
| <ul> |
| <li>If No, return to step 2 and look at the next qualifier. (In the example, |
| the answer is "no" until the language qualifier is reached.)</li> |
| <li>If Yes, continue to step 4.</li> |
| </ul> |
| </li> |
| |
| <li>Eliminate resource directories that do not include this qualifier. In the example, the system |
| eliminates all the directories that do not include a language qualifier:</li> |
| <pre class="classic no-pretty-print"> |
| <strike>drawable/</strike> |
| drawable-en/ |
| drawable-en-port/ |
| drawable-en-notouch-12key/ |
| <strike>drawable-port-ldpi/</strike> |
| <strike>drawable-port-notouch-12key/</strike> |
| </pre> |
| <p class="note"><strong>Exception:</strong> If the qualifier in question is screen pixel density, |
| Android selects the option that most closely matches the device screen density. |
| In general, Android prefers scaling down a larger original image to scaling up a smaller |
| original image. See <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple |
| Screens</a>.</p> |
| </li> |
| |
| <li>Go back and repeat steps 2, 3, and 4 until only one directory remains. In the example, screen |
| orientation is the next qualifier for which there are any matches. |
| So, resources that do not specify a screen orientation are eliminated: |
| <pre class="classic no-pretty-print"> |
| <strike>drawable-en/</strike> |
| drawable-en-port/ |
| <strike>drawable-en-notouch-12key/</strike> |
| </pre> |
| <p>The remaining directory is {@code drawable-en-port}.</p> |
| </li> |
| </ol> |
| |
| <p>Though this procedure is executed for each resource requested, the system further optimizes |
| some aspects. One such optimization is that once the device configuration is known, it might |
| eliminate alternative resources that can never match. For example, if the configuration |
| language is English ("en"), then any resource directory that has a language qualifier set to |
| something other than English is never included in the pool of resources checked (though a |
| resource directory <em>without</em> the language qualifier is still included).</p> |
| |
| <p>When selecting resources based on the screen size qualifiers, the system will use resources |
| designed for a screen smaller than the current screen if there are no resources that better match |
| (for example, a large-size screen will use normal-size screen resources if necessary). However, if |
| the only available resources are <em>larger</em> than the current screen, the system will |
| <strong>not</strong> use them and your application will crash if no other resources match the device |
| configuration (for example, if all layout resources are tagged with the {@code xlarge} qualifier, |
| but the device is a normal-size screen).</p> |
| |
| <p class="note"><strong>Note:</strong> The <em>precedence</em> of the qualifier (in <a |
| href="#table2">table 2</a>) 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 <code>drawable-en</code> has only one parameter that matches |
| (language). However, language has a higher precedence than these other qualifiers, so |
| <code>drawable-port-notouch-12key</code> is out.</p> |
| |
| <p>To learn more about how to use resources in your application, continue to <a |
| href="accessing-resources.html">Accessing Resources</a>.</p> |