diff options
| author | Scott Main <smain@google.com> | 2010-02-09 18:48:27 -0800 |
|---|---|---|
| committer | Scott Main <smain@google.com> | 2010-04-08 17:10:06 -0700 |
| commit | f940a1f316ddbed760f6f3ab9a3e4f2112909381 (patch) | |
| tree | e6f8e43848d440592adef52c0ffcca95df47f0d3 /docs/html/guide/topics/resources/providing-resources.jd | |
| parent | 5945579e4ed8fbe6dae6adaa4c222b321c2ec80b (diff) | |
| download | frameworks_base-f940a1f316ddbed760f6f3ab9a3e4f2112909381.zip frameworks_base-f940a1f316ddbed760f6f3ab9a3e4f2112909381.tar.gz frameworks_base-f940a1f316ddbed760f6f3ab9a3e4f2112909381.tar.bz2 | |
cherry-pick from master: Icf079f5f45b1745a8d54f504e28dbbb52c6f7c96
docs: rewrite resources documentation
Huge overhaul. Includes all new dev guides about how resources are used
on Android and how to provide alternatives, including how to handle
runtime configuration changes (restarts). Plus all new reference
docs for all the resource types (drawables, strings, menus, etc.).
Change-Id: I12e819d2c5fc11e062281d8fe442c3037e92000a
Diffstat (limited to 'docs/html/guide/topics/resources/providing-resources.jd')
| -rw-r--r-- | docs/html/guide/topics/resources/providing-resources.jd | 723 |
1 files changed, 723 insertions, 0 deletions
diff --git a/docs/html/guide/topics/resources/providing-resources.jd b/docs/html/guide/topics/resources/providing-resources.jd new file mode 100644 index 0000000..b495eb8 --- /dev/null +++ b/docs/html/guide/topics/resources/providing-resources.jd @@ -0,0 +1,723 @@ +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 sub-directories of {@code res/}</li> + <li>Alternative resources provide configuration-specific resource files</li> + </ul> + <h2>In this document</h2> + <ol> + <li><a href="#AlternativeResources">Providing Alternative Resources</a> + <ol> + <li><a href="#AliasResources">Creating alias resources</a></li> + </ol> + </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> + </ol> +</div> +</div> + +<p>There are several types of resource files you can +include in your application and each type belongs in a specific sub-directory of your project's +{@code res/} directory. Absolutely no files should be saved directly inside {@code res/}.</p> + +<p>For example, here's the file hierarchy for a simple project:</p> + +<pre class="no-pretty-print"> +MyProject/ + src/ <span style="color:black"> + MyActivity.java </span> + res/ + drawable/ <span style="color:black"> + icon.png </span> + layout/ <span style="color:black"> + main_layout.xml </span> + values/ <span style="color:black"> + strings.xml </span> +</pre> + +<p>This project includes an image resource, a layout resource, and string resource file.</p> + +<p>Table 1 lists the different {@code res/} sub-directories supported +and describes the types of resource files that belong in each one.</p> + +<p class="table-caption" id="table1"><strong>Table 1.</strong> Resource directories. Each directory +belongs inside the project {@code res/} directory.</p> + +<table> + <tr> + <th scope="col">Directory</th> + <th scope="col">Resource Types</th> + </tr> + + <tr> + <td><code>anim/</code></td> + <td>XML files that define tween animations. See <a +href="animation-resource.html">Animation Resources</a>.</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 Resources</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>Color drawables</li> + <li>Shapes</li> + <li>Animation drawables</li> + </ul> + <p>See <a href="drawable-resource.html">Drawable Resources</a>.</p> + </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. Files in here are not compressed by the +system. 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 require direct access to original file names and file hierarchy, instead of +using a resource ID to access your files, you might consider saving some resources in the {@code +assets/} directory, instead of {@code res/raw/}. You can query data in the {@code assets/} directory +like an ordinary file system, search through the directory and read raw data 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>Unlike the other {@code res/} subdirectories, this one + can hold files that contain descriptions of more than one resource, rather than +just one resource for the file. The XML element types of an XML file in {@code values/} control +how these resources are defined in the {@code R} class. For example, a {@code <string>} +element will create an +{@code R.string} resource, and a {@code <color>} element will create an {@code R.color} +resource.</p> + <p>While the name of a file in this directory is arbitrary and not related to the name given +to a resource produced, you might want to separate different types of resources into different +files for easier maintenance. Here are some filename conventions for some of the different types +of resources you can save here:</p> + <ul> + <li>arrays.xml to define resource arrays (<a +href="more-resources.html#TypedArray">typed arrays</a>).</li> + <li>colors.xml to define <a +href="more-resources.html#Color">color values</a></li> + <li>dimens.xml to define <a +href="more-resources.html#Dimension">dimension values</a>.</li> + <li>strings.xml to define <a href="string-resource.html">string +values</a>.</li> + <li>styles.xml to define <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 are compiled and can be read at runtime by calling {@link +android.content.res.Resources#getXml(int) Resources.getXML()}. Various XML configuration files +must also 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>For more information about certain types of resources, see the <a +href="available-resources.html">Resource Types</a> documentation.</p> + + + + + + +<h2 id="AlternativeResources">Providing Alternative Resources</h2> + + +<div class="figure" style="width:441px"> +<img src="{@docRoot}images/resources/resource_devices_diagram2.png" height="137" alt="" /> +<p class="img-caption"> +<strong>Figure 1.</strong> Two device configurations, one using alternative resources.</p> +</div> + +<p>Almost every application should provide alternative resources to support specific device +configurations. For instance, you should include different drawable resources for different +screen densities and different string resources for different languages. At runtime, Android +will automatically detect the current device configuration and then load the appropriate +resources.</p> + +<p>For each set of resources for which you want to provide configuration-specific alternatives:</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.</li> + <li><em>{@code <config_qualifier>}</em> is a name that specifies a configuration +for which these resources are to be used.</li> + </ul> + <p>You can append more than one <em>{@code <config_qualifier>}</em>. Separate each +one with a dash.</p> + </li> + <li>Save your alternative resources in this directory, named exactly the same as the default +resource files.</li> +</ol> + +<p>For example, here are some default and alternative resources:</p> + +<pre class="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 are for devices with a high-density +screen. While the images in each directory are different, the filenames are +identical. This way, the resource ID that you use to reference the {@code icon.png} image is +always the same. When you request the {@code icon} drawable, Android will select the +version of that drawable that best matches the current device configuration.</p> + +<p>Android supports several configuration qualifiers and you can +add multiple qualifiers to one directory name in order to further specify the configuration, by +separating the qualifiers with dashes. Table 2 lists the valid configuration qualifiers, in order +of precedence—they must be specified in the directory name in the order that they are listed +in the table.</p> + + +<p class="table-caption" id="table2"><strong>Table 2.</strong> Alternative resource qualifier +names.</p> +<table border="1"> + <tr> + <th>Qualifier</th> + <th>Values</th> + <th>Description</th> + </tr> + <tr> + <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>Specifies resources based on the mobile country code (MCC), optionally followed by mobile +network code (MNC) + from the SIM 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 will come + from the SIM, and the MNC will come from the network to which the + device is attached.</p> + <p>You might sometimes use the MCC alone, for example to include country-specific legal +resources in your application, but if you only need to specify based on language, then use the +language and region qualifier below. If you decide to use the MCC and MNC qualifier, you +should do so with great care and completely test that it works as expected.</p></td> + </tr> + <tr> + <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>This 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 "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 their 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 langauges.</p> + </td> + </tr> + <tr> + <td>Screen size</td> + <td> + <code>small</code><br/> + <code>normal</code><br/> + <code>large</code> + </td> + <td> + <ul> + <li> <b>Small screens</b> are based on the space available on a + QVGA low density screen. Considering a portrait HVGA display, this has + the same available width but less height -- it is 3:4 vs. HVGA's + 2:3 aspect ratio. Examples are QVGA low density and VGA high + density.</li> + <li> <b>Normal screens</b> are based on the traditional Android HVGA + medium density screen. A screen is considered to be normal if it is + at least this size (independent of density) and not larger. Examples + of such screens a WQVGA low density, HVGA medium density, WVGA + high density.</li> + <li> <b>Large screens</b> are based on the space available on a + VGA medium density screen. Such a screen has significantly more + available space in both width and height than an HVGA display. + Examples are VGA and WVGA medium density screens.</li> + </ul> + <p>See <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple +Screens</a> for more information.</p> + </td> + </tr> + <tr> + <td>Wider/taller screens</td> + <td> + <code>long</code><br/> + <code>notlong</code> + </td> + <td> + <p>This is based purely on the aspect ratio of the screen (a "long" screen is wider): + <ul> + <li><strong>Long</strong>: WQVGA, WVGA, FWVGA</li> + <li><strong>Not long</strong>: QVGA, HVGA, and VGA</li> + </ul> + <p>This is not related to the screen orientation.</p> + </td> + </tr> + <tr> + <td>Screen orientation</td> + <td> + <code>port</code><br/> + <code>land</code> <!-- <br/> + <code>square</code> --> + </td> + <td> + <p>Portrait orientation ({@code port}) is vertical and landscape orientation +({@code land}) is horizontal. <!-- Square mode is currently not used. --> </p> + <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> + </td> + </tr> + <tr> + <td>Dock mode</td> + <td> + <code>car</code><br/> + <code>desk</code> + </td> + <td> + <p>These configurations can be initiated when the device is placed in a dock.</p> + <p><em>Added in API Level 8.</em></p> + <p>This can change during the life of your application if the user places the device in a +dock. See <a href="runtime-changes.html">Handling Runtime Changes</a> for +information about how this affects your application during runtime. Also see {@link +android.app.UiModeManager}.</p> + </td> + </tr> + <tr> + <td>Night mode</td> + <td> + <code>night</code><br/> + <code>notnight</code> + </td> + <td> + <p> + These configurations can be initiated by the device light sensor (if available).</p> + <p><em>Added in API Level 8.</em></p> + <p>This can change during the life of your application if the device determines that the +user environment is a "night" (dark) setting. See <a href="runtime-changes.html">Handling Runtime +Changes</a> for information about how this affects your application during runtime. You can +also explicitly set this mode using {@link android.app.UiModeManager}.</p> + </td> + </tr> + <tr> + <td>Screen pixel density (dpi)</td> + <td> + <code>ldpi</code><br/> + <code>mdpi</code><br/> + <code>hdpi</code><br/> + <code>nodpi</code> + </td> + <td> + <p>The medium + density of traditional HVGA screens (mdpi) is defined to be approximately + 160dpi; low density (ldpi) is 120, and high density (hdpi) is 240. There + is thus a 4:3 scaling factor between each density, so a 9x9 bitmap + in ldpi would be 12x12 in mdpi and 16x16 in hdpi. The special + <code>nodpi</code> density can be used with bitmap resources to prevent + them from being scaled at load time to match the device density. + </p><p> + When Android selects which resource files to use, + it handles screen density differently than the other qualifiers. + In step 1 of <a href="#BestMatch">How Android finds the best + matching directory</a> (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. + </p> + <p>See <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple +Screens</a> for more information.</p> + </td> + </tr> + <tr> + <td>Touchscreen type</td> + <td> + <code>notouch</code><br/> + <code>stylus</code><br/> + <code>finger</code> + </td> + <td><p>If the device has a resistive touch screen that's suited for use with a stylus, +then it may use the {@code stylus} resources.</p> + </td> + </tr> + <tr> + <td>Keyboard availability</td> + <td> + <code>keysexposed</code><br/> + <code>keyshidden</code><br/> + <code>keyssoft</code> + </td> + <td> + <p>If your application has specific resources that should only be used with a soft keyboard, +use the <code>keyssoft</code> value. If you do not provide <code>keyssoft</code> resources, but do +provide <code>keysexposed</code> and <code>keyshidden</code>, and the device shows a soft keyboard, +the system will use <code>keysexposed</code> resources.</p> + <p>This can change during the life of your application if the user opens a keyboard. See <a +href="runtime-changes.html">Handling Runtime Changes</a> for information about how this affects your +application during runtime.</p> + </td> + </tr> + <tr> + <td>Primary text input method</td> + <td> + <code>nokeys</code><br/> + <code>qwerty</code><br/> + <code>12key</code> + </td> + <td><p>If the device has no hardware keys for text input, then it may use the {@code +nokeys} resources. Even if the device has a QWERTY keyboard but it is currently hidden, it may use +the {@code qwerty} resources.</td> + </tr> + <tr> + <td>Navigation key availability</td> + <td> + <code>navexposed</code><br/> + <code>navhidden</code> + </td> + <td> + <p> + If the device's navigation keys are currently available to + the user, it may use the {@code navexposed} resources; if they are not + available (such as behind a closed lid), it may use the {@code navhidden} resources.</p> + <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> + </td> + </tr> + <tr> + <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><p>If the device has no navigation facility other than using the touchscreen, then it +may use the {@code nonav} resources.</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> + <td>API Level</td> + <td>Examples:<br/> + <code>v4</code><br/> + <code>v5</code><br/> + <code>v6</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 +(Android 1.0) or <code>v5</code> for API Level 5 (Android 2.0). See the <a +href="{@docRoot}guide/appendix/api-levels.html">Android API Levels</a> document for more information +about these values.</p> + </td> + </tr> +</table> + +<p>Here are some important rules about using resource 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> above. For +example: + <ul> + <li>Wrong: <code>drawable-hdpi-port/</code></li> + <li>Correct: <code>drawable-port-hdpi/</code></li> + </ul> + </li> + <li>Qualified 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 (which +could multiply the size of your package if the files are large). Instead, you can create a +reference to one instance of the resources. See <a href="#AliasResources">Creating +alias resources</a>, below.</li> +</ul> + + + +<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 not for all configurations), you <em>don't</em> have to put the same resource in +each of the alternative resource directories. 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>For example, imagine you have an image, {@code icon.png}, and you have different versions of it +for different locales, but two locales, English-Canadian and French-Canadian, need to +use the same version. You might assume that you need to copy the Canadian version of the +icon into the alternative resource directory for both English-Canadian and French-Canadian, but it's +not true. What you can do instead is save the Canadian version 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> + +<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 don't provide this kind of feature.</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}, it will be 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.</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 will be 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="yellow">#f00</color> + <color name="highlight">@color/red</color> +</resources> +</pre> + + + + + + +<h2 id="BestMatch">How Android Finds the Best-matching Resource</h2> + +<p>Once you have saved alternative resources for your application, Android will pick which of the +various underlying resource files should be used at runtime for each resource +requested, depending on the current device configuration. To demonstrate how Android will select the +resource to use, assume the following drawables are available:</p> + +<pre class="no-pretty-print"> +res/drawable/ +res/drawable-en/ +res/drawable-fr-rCA/ +res/drawable-en-port/ +res/drawable-en-notouch-12key/ +res/drawable-port-ldpi/ +res/drawable-port-notouch-12key +</pre> + +<p>And assume the following is the device configuration:</p> + +<p style="margin-left:2em;"> +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>Here is how Android makes the drawable selection and how a drawable will be selected from the +configuration above: </p> + +<ol> + <li>Eliminate resource files that contradict the device configuration. + <p>The <code>drawable-fr-rCA/</code> directory will be eliminated, because it +contradicts the locale of the device.</p> +<pre class="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 +used to eliminate files. Even though the screen density of the device is mdpi, +<code>drawable-port-ldpi/</code> is not eliminated because every screen density is +considered to be a match at this point.</p></li> + + <li>From <a href="#table2">Table 2</a>, pick the (next) highest-precedence qualifier in +the list. (Start with MCC, then move down through the list.) </li> + <li>Do any of the available 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, move on 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="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 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.</p> + </li> + + <li>Go back and repeat steps 2, 3, and 4 until only one choice 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="no-pretty-print"> +<strike>drawable-en/</strike> +drawable-en-port/ +<strike>drawable-en-notouch-12key/</strike> +</pre> +<p>Only one choice remains, so the drawable will be taken from the {@code drawable-en-port} +directory.</p> + </li> +</ol> + +<p>Though this procedure is executed for each resource requested, the system will further optimize +some aspects. One such optimization is that once the device configuration is known, it might +completely 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 will never be included in the pool of resources checked (though a +resource directory <em>without</em> the language qualifier is still included).</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>The following flowchart summarizes how Android selects the resource directory to use.</p> +<p><img src="{@docRoot}images/resources/res-selection-flowchart.png" alt="" +height="471" /></p> + |