993 lines
45 KiB
Plaintext
993 lines
45 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>
|
|
<ol>
|
|
<li><a href="#ScreenCompatibility">Providing screen resource compatibility for Android
|
|
1.5</a></li>
|
|
</ol>
|
|
</li>
|
|
<li><a href="#BestMatch">How Android Finds the Best-matching Resource</a></li>
|
|
<li><a href="#KnownIssues">Known Issues</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 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>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 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:421px">
|
|
<img src="{@docRoot}images/resources/resource_devices_diagram2.png" height="137" alt="" />
|
|
<p class="img-caption">
|
|
<strong>Figure 1.</strong> Two different devices, one using alternative 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>
|
|
</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 alternative 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 one resource directory, they must be added to the directory name in the order they
|
|
are listed in the table.</p>
|
|
|
|
<p class="note"><strong>Note:</strong> Some configuration qualifiers were added after Android 1.0,
|
|
so not
|
|
all versions of Android support all the qualifiers listed in table 2. New qualifiers
|
|
indicate the version in which they were added. To avoid any issues, always include a set of default
|
|
resources for resources that your application uses. For more information, see the section about <a
|
|
href="#Compatibility">Providing the Best Device Compatibility with Resources</a>.</p>
|
|
|
|
<p class="table-caption" id="table2"><strong>Table 2.</strong> Configuration qualifier
|
|
names.</p>
|
|
<table>
|
|
<tr>
|
|
<th>Qualifier</th>
|
|
<th>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 comes
|
|
from the SIM, and the MNC comes from the network to which the
|
|
device is connected.</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="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 based on the space available on a
|
|
low-density QVGA 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>{@code normal}: Screens based on the traditional
|
|
medium-density HVGA 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>{@code large}: Screens based on the space available on a
|
|
medium-density VGA 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>
|
|
<li>{@code xlarge}: Screens that are considerably larger than the traditional
|
|
medium-density HVGA screen. 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><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="DockQualifier">
|
|
<td>Dock mode</td>
|
|
<td>
|
|
<code>car</code><br/>
|
|
<code>desk</code>
|
|
</td>
|
|
<td>
|
|
<ul class="nolist">
|
|
<li>{@code car}: Device is in a car dock</li>
|
|
<li>{@code desk}: Device is in a desk dock</li>
|
|
</ul>
|
|
<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. 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="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>
|
|
</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>
|
|
</ul>
|
|
<p><em>Added in API Level 4.</em></p>
|
|
<p>There is thus a 3:4:6 scaling ratio between the three densities, so a 9x9 bitmap
|
|
in ldpi is 12x12 in mdpi and 18x18 in hdpi.</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 selects 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 about how to handle screen sizes and how Android might scale
|
|
your bitmaps.</p>
|
|
</td>
|
|
</tr>
|
|
<tr id="TouchscreenQualifier">
|
|
<td>Touchscreen type</td>
|
|
<td>
|
|
<code>notouch</code><br/>
|
|
<code>stylus</code><br/>
|
|
<code>finger</code>
|
|
</td>
|
|
<td>
|
|
<ul class="nolist">
|
|
<li>{@code notouch}: Device does not have a touchscreen.</li>
|
|
<li>{@code stylus}: Device has a resistive touchscreen that's suited for use with a
|
|
stylus.</li>
|
|
<li>{@code finger}: Device has a touchscreen.</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>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="TouchQualifier">
|
|
<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>System 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/appendix/api-levels.html">Android API Levels</a> document for more information
|
|
about these values.</p>
|
|
<p class="caution"><strong>Caution:</strong> Android 1.5 and 1.6 only match resources
|
|
with this qualifier when it exactly matches the system version. See the section below about <a
|
|
href="#KnownIssues">Known Issues</a> for more information.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
|
|
<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. If your <a
|
|
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> is
|
|
<em>less than</em> 4 (Android 1.5 or lower), be aware that the screen size, density, and aspect
|
|
qualifiers are not supported on Android 1.5 or lower, so you might need to perform additional
|
|
compatibility for these versions.</p>
|
|
|
|
|
|
<h3 id="ScreenCompatibility">Providing screen resource compatibility for Android 1.5</h3>
|
|
|
|
<p>Android 1.5 (and lower) does not support the following configuration qualifers:</p>
|
|
<dl>
|
|
<dt><a href="#DensityQualifier">Density</a></dt>
|
|
<dd>{@code ldpi}, {@code mdpi}, {@code ldpi}, and {@code nodpi}</dd>
|
|
<dt><a href="#ScreenSizeQualifier">Screen size</a></dt>
|
|
<dd>{@code small}, {@code normal}, and {@code large}</dd>
|
|
<dt><a href="#ScreenAspectQualifier">Screen aspect</a></dt>
|
|
<dd>{@code long} and {@code notlong}</dd>
|
|
</dl>
|
|
|
|
<p>These configuration qualifiers were introduced in Android 1.6, so Android 1.5 (API Level 3) and
|
|
lower does not support them. If you use these configuration qualifiers and do not provide
|
|
corresponding default resources, then an Android 1.5 device might use any one of the resource
|
|
directories named with the above screen configuration qualifiers, because it ignores these
|
|
qualifiers and uses whichever otherwise-matching drawable resource it finds first.</p>
|
|
|
|
<p>For example, if your application supports Android 1.5 and includes drawable resources for
|
|
each density type ({@code drawable-ldpi/}, {@code drawable-mdpi/}, and {@code drawable-ldpi/}),
|
|
and does <em>not</em> include default drawable resources ({@code drawable/}), then
|
|
an Android 1.5 will use drawables from any one of the alternative resource directories, which
|
|
can result in a user interface that's less than ideal.<p>
|
|
|
|
<p>So, to provide compatibility with Android 1.5 (and lower) when using the screen configuration
|
|
qualifiers:</p>
|
|
<ol>
|
|
<li>Provide default resources that are for medium-density, normal, and notlong screens.
|
|
|
|
<p>Because all Android 1.5 devices have medium-density, normal, not-long screens, you can
|
|
place these kinds of resources in the corresponding default resource directory. For example, put all
|
|
medium density drawable resources in {@code drawable/} (instead of {@code drawable-mdpi/}),
|
|
put {@code normal} size resources in the corresponding default resource directory, and {@code
|
|
notlong} resources in the corresponding default resource directory.</p>
|
|
</li>
|
|
|
|
<li>Ensure that your <a href="{@docRoot}sdk/tools-notes.html">SDK Tools</a> version
|
|
is r6 or greater.
|
|
|
|
<p>You need SDK Tools, Revision 6 (or greater), because it includes a new packaging tool that
|
|
automatically applies an appropriate <a href="#VersionQualifier">version qualifier</a> to any
|
|
resource directory named with a qualifier that does not exist in Android 1.0. For example, because
|
|
the density qualifier was introduced in Android 1.6 (API Level 4), when the packaging tool
|
|
encounters a resource directory using the density qualifier, it adds {@code v4} to the directory
|
|
name to ensure that older versions do not use those resources (only API Level 4 and higher support
|
|
that qualifier). Thus, by putting your medium-density resources in a directory <em>without</em> the
|
|
{@code mdpi} qualifier, they are still accessible by Android 1.5, and any device that supports the
|
|
density qualifer and has a medium-density screen also uses the default resources (which are mdpi)
|
|
because they are the best match for the device (instead of using the {@code ldpi} or {@code hdpi}
|
|
resources).</p>
|
|
</li>
|
|
</ol>
|
|
|
|
<p class="note"><strong>Note:</strong> Later versions of Android, such as API Level 8,
|
|
introduce other configuration qualifiers that older version do not support. To provide the best
|
|
compatibility, you should always include a set of default resources for each type of resource
|
|
that your application uses, as discussed above to provide the best device compatibility.</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}. It arrives at this decision using the following logic:</p>
|
|
|
|
|
|
<div class="figure" style="width:280px">
|
|
<img src="{@docRoot}images/resources/res-selection-flowchart.png" alt="" height="590" />
|
|
<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 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>
|
|
|
|
|
|
|
|
|
|
<h2 id="KnownIssues">Known Issues</h2>
|
|
|
|
<h3>Android 1.5 and 1.6: Version qualifier performs exact match, instead of best match</h3>
|
|
|
|
<p>The correct behavior is for the system to match resources marked with a <a
|
|
href="#VersionQualifier">version qualifier</a> equal
|
|
to or less than the system version on the device, but on Android 1.5 and 1.6, (API Level 3 and 4),
|
|
there is a bug that causes the system to match resources marked with the version qualifier
|
|
only when it exactly matches the version on the device.</p>
|
|
|
|
<p><b>The workaround:</b> To provide version-specific resources, abide by this behavior. However,
|
|
because this bug is fixed in versions of Android available after 1.6, if
|
|
you need to differentiate resources between Android 1.5, 1.6, and later versions, then you only need
|
|
to apply the version qualifier to the 1.6 resources and one to match all later versions. Thus, this
|
|
is effectively a non-issue.</p>
|
|
|
|
<p>For example, if you want drawable resources that are different on each Android 1.5, 1.6,
|
|
and 2.0.1 (and later), create three drawable directories: {@code drawable/} (for 1.5 and lower),
|
|
{@code drawable-v4} (for 1.6), and {@code drawable-v6} (for 2.0.1 and later—version 2.0, v5,
|
|
is no longer available).</p>
|
|
|
|
|