1093 lines
52 KiB
Plaintext
1093 lines
52 KiB
Plaintext
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">
|
|
icon.png </span>
|
|
layout/ <span style="color:black">
|
|
main.xml
|
|
info.xml</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, and a string resource file. The resource
|
|
directory names are important and are described in table 1.</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>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="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>
|
|
</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>
|
|
</ul>
|
|
<p><em>Added in API level 8, television added in API 13.</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>nodpi</code><br/>
|
|
<code>tvdpi</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 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. This qualifier was introduced with API level 13.</li>
|
|
</ul>
|
|
<p>There is a 3:4:6:8 scaling ratio between the four primary densities (ignoring the
|
|
tvdpi density). So, a 9x9 bitmap in ldpi is 12x12 in mdpi, 18x18 in hdpi and 24x24 in xhdpi.</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="yellow">#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>
|