topics/resources/resources-i18n.jd

page.title=Resources and Internationalization
parent.title=Resources and Assets
parent.link=index.html
@jd:body

<div id="qv-wrapper">
<div id="qv">

  <h2>Key classes</h2>
  <ol>
    <li>{@link android.content.res.Resources}</li>
  </ol>

  <h2>In this document</h2>
  <ol>
    <li><a href="#intro">Introduction</a></li>
    <li><a href="#CreatingResources">Creating Resources</a></li>
    <li><a href="#UsingResources">Using Resources</a>
      <ol>
        <li><a href="#ResourcesInCode">Using Resources in Code</a></li>
        <li><a href="#ReferencesToResources">References to Resources</a></li>
        <li><a href="#ReferencesToThemeAttributes">References to Theme Attributes</a></li>
        <li><a href="#UsingSystemResources">Using System Resources</a></li>
      </ol>
    </li>
    <li><a href="#AlternateResources">Alternate Resources</a></li>
    <li><a href="#ResourcesTerminology">Terminology</a></li>
    <li><a href="#i18n">Internationalization (I18N)</a></li>
  </ol>
</div>
</div>

<p>Resources are external files (that is, non-code files) that are used by
your code and compiled into your application at build time. Android
supports a number of different kinds of resource files, including XML,
PNG, and JPEG files. The XML files have very different formats depending
on what they describe. This document describes what kinds of files are
supported, and the syntax or format of each.</p>
<p>Resources are externalized from source code, and XML files are compiled into
a binary, fast loading format for efficiency reasons. Strings, likewise are compressed
into a more efficient storage form. It is for these reasons that we have these
different resource types in the Android platform.</p>

<p>This is a fairly technically dense document, and together with the
<a href="available-resources.html">Available Resources</a>
document, they cover a lot of information about resources. It is not necessary
to know this document by heart to use Android, but rather to know that the
information is here when you need it.</p>

<a name="intro"></a>
<h2>Introduction</h2>

<p>This topic includes a terminology list associated with resources, and a series
    of examples of using resources in code. For a complete guide to the supported
    Android resource types, see
    <a href="available-resources.html">Available Resources</a>.
    </p>
<p>The Android resource system keeps track of all non-code
    assets associated with an application.  You use the
    {@link android.content.res.Resources Resources} class to access your
    application's resources; the Resources instance associated with your
    application can generally be found through
    {@link android.content.Context#getResources Context.getResources()}.</p>
<p>An application's resources are compiled into the application
binary at build time for you by the build system.  To use a resource,
you must install it correctly in the source tree and build your
application.  As part of the build process, symbols for each
of the resources are generated that you can use in your source
code -- this allows the compiler to verify that your application code matches
up with the resources you defined.</p>

<p>The rest of this section is organized as a tutorial on how to
use resources in an application.</p>

<a name="CreatingResources" id="CreatingResources"></a>
<h2>Creating Resources</h2>

<p>Android supports string, bitmap, and many other types of resource. The syntax and format
of each, and where they're stored, depends upon the type of object. In
general, though, you create resources from three types of files: XML files
(everything but bitmaps and raw), bitmap files(for images) and Raw files (anything
else, for example sound files, etc.). In fact, there are two different types of
XML file as well, those that get compiled as-is into the package, and those that
are used to generate resources by aapt. Here is a list of each
resource type, the format of the file, a description of the file, and details
of any XML files. </p>

<p>You will create and store your resource files under the appropriate
subdirectory under the <code>res/</code> directory in your project. Android
has a resource compiler (aapt) that compiles resources according to which
subfolder they are in, and the format of the file. Here is a list of the file
types for each resource. See the
<a href="available-resources.html">Available Resources</a> for
descriptions of each type of object, the syntax, and the format or syntax of
the containing file.</p>

<table width="100%" border="1">
    <tr>
        <th scope="col">Directory</th>
        <th scope="col">Resource Types </th>
    </tr>
    <tr>
        <td><code>res/anim/</code></td>
        <td>XML files that are compiled into
        <a href="available-resources.html#animationdrawable">frame by
        frame animation</a> or
        <a href="available-resources.html#tweenedanimation">tweened
        animation</a> objects </td>
    </tr>
    <tr>
        <td><code>res/drawable/</code></td>
        <td><p>.png, .9.png, .jpg files that are compiled into the following
                Drawable resource subtypes:</p>
            <p>To get a resource of this type, use <code>Resource.getDrawable(<em>id</em>)</code>
            <ul>
                <li><a href="available-resources.html#imagefileresources">bitmap files</a></li>
                <li><a href="available-resources.html#ninepatch">9-patches (resizable bitmaps)</a></li>
            </ul></td>
    </tr>
    <tr>
        <td><code>res/layout/</code></td>
        <td>XML files that are compiled into screen layouts (or part of a screen).
            See <a href="{@docRoot}guide/topics/ui/declaring-layout.html">Declaring Layout</a></td>
    </tr>
    <tr>
        <td><code>res/values/</code></td>
        <td><p>XML files that can be compiled into many kinds of resource.</p>
            <p class="note"><strong>Note:</strong> unlike the other res/ folders, this one
            can hold any number of files that hold descriptions of resources to create
            rather than the resources themselves. The XML element types control
            where these resources are placed under the R class.</p>
            <p>While the files can be named anything, these are
                the typical files in this folder (the convention is to name
                the file after the type of elements defined within):</p>
            <ul>
                <li><strong>arrays.xml</strong> to define arrays </li>
                <!-- TODO: add section on arrays -->
                <li><strong>colors.xml</strong> to define <a href="available-resources.html#colordrawableresources">color
                        drawables</a> and <a  href="#colorvals">color string values</a>.
                        Use <code>Resources.getDrawable()</code> and
                        <code>Resources.getColor(), respectively,</code>
                to get these resources.</li>
                <li><strong>dimens.xml</strong> to define <a href="available-resources.html#dimension">dimension value</a>. Use <code>Resources.getDimension()</code> to get
                these resources.</li>
                <li><strong>strings.xml</strong> to define <a href="available-resources.html#stringresources">string</a> values (use either
                <code>Resources.getString</code> or preferably <code>Resources.getText()</code>
                to get
                these resources. <code>getText()</code> will retain any rich text styling
                which is usually desirable for UI strings.</li>
                <li><strong>styles.xml</strong> to define <a href="available-resources.html#stylesandthemes">style</a> objects.</li>
            </ul></td>
    </tr>
    <tr>
        <td><code>res/xml/</code></td>
        <td>Arbitrary XML files that are compiled and can be read at run time by
            calling {@link android.content.res.Resources#getXml(int) Resources.getXML()}.</td>
    </tr>
    <tr>
        <td><code>res/raw/</code></td>
        <td>Arbitrary files to copy directly to the device. They are added uncompiled
            to the compressed file that your application build produces. To use these
            resources in your application, call {@link android.content.res.Resources#openRawResource(int)
            Resources.openRawResource()} with the resource ID, which is R.raw.<em>somefilename</em>.</td>
    </tr>
</table>
<p>Resources are compiled into the final APK file. Android creates a wrapper class,
    called R, that you can use to refer to these resources in your code. R contains subclasses
    named according to the path and file name of the source file</p>
<a name="colorvals" id="colorvals"></a>
<h3>Global Resource Notes</h3>
<ul>
    <li>Several resources allow you to define colors. Android accepts color values
        written in various web-style formats -- a hexadecimal constant in any of the
        following forms: #RGB, #ARGB, #RRGGBB, #AARRGGBB. </li>
    <li>All color values support setting an alpha channel value, where the first
        two hexadecimal numbers specify the transparency. Zero in the alpha channel
        means transparent. The default value is opaque. </li>
</ul>
<a name="UsingResources" id="UsingResources"></a>
<h2>Using Resources </h2>
<p>This section describes how to use the resources you've created. It includes the
    following topics:</p>
<ul>
    <li><a href="#ResourcesInCode">Using resources in code</a>&nbsp;- How to call
        resources in your code to instantiate them. </li>
    <li><a href="#ReferencesToResources">Referring to resources from other resources</a> &nbsp;-
        You can reference resources from other resources. This lets you reuse common
        resource values inside resources. </li>
    <li><a href="#AlternateResources">Supporting Alternate Resources for Alternate
            Configurations</a> - You can specify different resources
            to load, depending on the language or display configuration of the host
            hardware. </li>
</ul>
<p>At compile time, Android generates a class named R that contains resource identifiers
    to all the resources in your program. This class contains several subclasses,
    one for each type of resource supported by Android, and for which you provided
    a resource file. Each class contains one or more identifiers for the compiled resources,
    that you use in your code to load the resource. Here is a small resource file
    that contains string, layout (screens or parts of screens), and image resources.</p>
<p class="note"><strong>Note:</strong> the R class is an auto-generated file and is not
designed to be edited by hand. It will be automatically re-created as needed when
the resources are updated.</p>
<pre class="prettyprint">package com.android.samples;
public final class R {
    public static final class string {
        public static final int greeting=0x0204000e;
        public static final int start_button_text=0x02040001;
        public static final int submit_button_text=0x02040008;
        public static final int main_screen_title=0x0204000a;
    };
    public static final class layout {
        public static final int start_screen=0x02070000;
        public static final int new_user_pane=0x02070001;
        public static final int select_user_list=0x02070002;

    };
    public static final class drawable {
        public static final int company_logo=0x02020005;
        public static final int smiling_cat=0x02020006;
        public static final int yellow_fade_background=0x02020007;
        public static final int stretch_button_1=0x02020008;

    };
};
</pre>
<a name="ResourcesInCode" id="ResourcesInCode"></a>
<h3>Using Resources in Code </h3>

<p>Using resources in code is just a matter of knowing the full resource ID
and what type of object your resource has been compiled into. Here is the
syntax for referring to a resource:</p>
<p><code>R.<em>resource_type</em>.<em>resource_name</em></code></p>
<p>or</p>
<p><code>android.R.<em>resource_type</em>.<em>resource_name</em></code></p>

<p>Where <code>resource_type</code> is the R subclass that holds a specific type
of resource. <code>resource_name</code> is the <em>name</em> attribute for resources
defined in XML files, or the file name (without the extension) for resources
defined by other file types. Each type of resource will be added to a specific
R subclass, depending on the type of resource it is; to learn which R subclass
hosts your compiled resource type, consult the
<a href="available-resources.html">Available Resources</a> document. Resources compiled by your own application can
be referred to without a package name (simply as
<code>R.<em>resource_type</em>.<em>resource_name</em></code>). Android contains
a number of standard resources, such as screen styles and button backgrounds. To
refer to these in code, you must qualify them with <code>android</code>, as in
<code>android.R.drawable.button_background</code>.</p>

<p>Here are some good and bad examples of using compiled resources in code:</p>

<pre class="prettyprint">// Load a background for the current screen from a drawable resource.
this.getWindow().setBackgroundDrawableResource(R.drawable.my_background_image);

// WRONG Sending a string resource reference into a
// method that expects a string.
this.getWindow().setTitle(R.string.main_title);

// RIGHT Need to get the title from the Resources wrapper.
this.getWindow().setTitle(Resources.getText(R.string.main_title));

// Load a custom layout for the current screen.
setContentView(R.layout.main_screen);

// Set a slide in animation for a ViewFlipper object.
mFlipper.setInAnimation(AnimationUtils.loadAnimation(this,
        R.anim.hyperspace_in));

// Set the text on a TextView object.
TextView msgTextView = (TextView)findViewByID(R.id.msg);
msgTextView.setText(R.string.hello_message); </pre>

<a name="ReferencesToResources" id="ReferencesToResources"></a>
<h3>References to Resources</h3>

<p>A value supplied in an attribute (or resource) can also be a reference to
a resource.  This is often used in layout files to supply strings (so they
can be localized) and images (which exist in another file), though a reference
can be any resource type including colors and integers.</p>

<p>For example, if we have
<a href="available-resources.html#colordrawableresources">color
resources</a>, we can write a layout file that sets the text color size to be
the value contained in one of those resources:</p>

<pre>
&lt;?xml version=&quot;1.0&quot; encoding=&quot;utf-8&quot;?&gt;
&lt;EditText id=&quot;text&quot;
    xmlns:android=&quot;http://schemas.android.com/apk/res/android";
    android:layout_width=&quot;fill_parent&quot; android:layout_height=&quot;fill_parent&quot;
    <strong>android:textColor=&quot;&#64;color/opaque_red&quot;</strong>
    android:text=&quot;Hello, World!&quot; /&gt;
</pre>

<p>Note here the use of the '@' prefix to introduce a resource reference -- the
text following that is the name of a resource in the form
of <code>@[package:]type/name</code>.  In this case we didn't need to specify
the package because we are referencing a resource in our own package.  To
reference a system resource, you would need to write:</p>

<pre>
&lt;?xml version=&quot;1.0&quot; encoding=&quot;utf-8&quot;?&gt;
&lt;EditText id=&quot;text&quot;
    xmlns:android=&quot;http://schemas.android.com/apk/res/android";
    android:layout_width=&quot;fill_parent&quot; android:layout_height=&quot;fill_parent&quot;
    android:textColor=&quot;&#64;<strong>android:</strong>color/opaque_red&quot;
    android:text=&quot;Hello, World!&quot; /&gt;
</pre>

<p>As another example, you should always use resource references when supplying
strings in a layout file so that they can be localized:</p>

<pre>
&lt;?xml version=&quot;1.0&quot; encoding=&quot;utf-8&quot;?&gt;
&lt;EditText id=&quot;text&quot;
    xmlns:android=&quot;http://schemas.android.com/apk/res/android";
    android:layout_width=&quot;fill_parent&quot; android:layout_height=&quot;fill_parent&quot;
    android:textColor=&quot;&#64;android:color/opaque_red&quot;
    android:text=&quot;&#64;string/hello_world&quot; /&gt;
</pre>

<p>This facility can also be used to create references between resources.
For example, we can create new drawable resources that are aliases for
existing images:</p>

<pre>
&lt;?xml version=&quot;1.0&quot; encoding=&quot;utf-8&quot;?&gt;
&lt;resources&gt;
    &lt;drawable id=&quot;my_background&quot;&gt;&#64;android:drawable/theme2_background&lt;/drawable&gt;
&lt;/resources&gt;
</pre>

<a name="ReferencesToThemeAttributes"></a>
<h3>References to Theme Attributes</h3>

<p>Another kind of resource value allows you to reference the value of an
attribute in the current theme.  This attribute reference can <em>only</em>
be used in style resources and XML attributes; it allows you to customize the
look of UI elements by changing them to standard variations supplied by the
current theme, instead of supplying more concrete values.</p>

<p>As an example, we can use this in our layout to set the text color to
one of the standard colors defined in the base system theme:</p>

<pre>
&lt;?xml version=&quot;1.0&quot; encoding=&quot;utf-8&quot;?&gt;
&lt;EditText id=&quot;text&quot;
    xmlns:android=&quot;http://schemas.android.com/apk/res/android";
    android:layout_width=&quot;fill_parent&quot; android:layout_height=&quot;fill_parent&quot;
    <strong>android:textColor=&quot;?android:textDisabledColor&quot;</strong>
    android:text=&quot;&#64;string/hello_world&quot; /&gt;
</pre>

<p>Note that this is very similar to a resource reference, except we are using
an '?' prefix instead of '@'.  When you use this markup, you are supplying
the name of an attribute resource that will be looked up in the theme --
because the resource tool knows that an attribute resource is expected,
you do not need to explicitly state the type (which would be
<code>?android:attr/android:textDisabledColor</code>).</p>

<p>Other than using this resource identifier to find the value in the
theme instead of raw resources, the name syntax is identical to the '@' format:
<code>?[namespace:]type/name</code> with the type here being optional.</p>

<a name="UsingSystemResources"></a>
<h3>Using System Resources</h3>

<p>Many resources included with the system are available to applications.
All such resources are defined under the class "android.R".  For example,
you can display the standard application icon in a screen with the following
code:</p>

<pre class="prettyprint">
public class MyActivity extends Activity
{
    public void onStart()
    {
        requestScreenFeatures(FEATURE_BADGE_IMAGE);

        super.onStart();

        setBadgeResource(android.R.drawable.sym_def_app_icon);
    }
}
</pre>

<p>In a similar way, this code will apply to your screen the standard
"green background" visual treatment defined by the system:</p>

<pre class="prettyprint">
public class MyActivity extends Activity
{
    public void onStart()
    {
        super.onStart();

        setTheme(android.R.style.Theme_Black);
    }
}
</pre>

<a name="AlternateResources" id="AlternateResources"></a>
<h2>Alternate Resources (for alternate languages and configurations)</h2>

<p>You can supply different resources for your product according to the UI
language or hardware configuration on the device. Note that although you can
include different string, layout, and other resources, the SDK does not expose
methods to let you specify which alternate resource set to load. Android
detects the proper set for the hardware and location, and loads them as
appropriate. Users can select alternate language settings using the settings
panel on the device. </p>
<p>To include alternate resources, create parallel resource folders with
qualifiers appended to the folder names, indicating the configuration it
applies to (language, screen orientation, and so on). For example, here is a
project that holds one string resource file for English, and another for
French:</p>

<pre>
MyApp/
    res/
        values-en/
            strings.xml
        values-fr/
            strings.xml
</pre>

<p>Android supports several types of qualifiers, with various values for each.
Append these to the end of the resource folder name, separated by dashes. You
can add multiple qualifiers to each folder name, but they must appear in the
order they are listed here. For example, a folder containing drawable
resources for a fully specified configuration would look like:</p>

<pre>
MyApp/
    res/
        drawable-en-rUS-port-160dpi-finger-keysexposed-qwerty-dpad-480x320/
</pre>

<p>More typically, you will only specify a few specific configuration options
that a resource is defined for. You may drop any of the values from the
complete list, as long as the remaining values are still in the same
order:</p>

<pre>
MyApp/
    res/
        drawable-en-rUS-finger/
        drawable-port/
        drawable-port-160dpi/
        drawable-qwerty/
</pre>

<table border="1">
    <tr>
        <th> Qualifier </th>
        <th> Values </th>
    </tr>
    <tr>
        <td>Language</td>
        <td>The two letter <a href="http://www.loc.gov/standards/iso639-2/php/code_list.php">ISO
                639-1</a> language code in lowercase. For example:
                <code>en</code>, <code>fr</code>, <code>es</code> </td>
    </tr>
    <tr>
        <td>Region</td>
        <td>The 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> language code in uppercase preceded by a lowercase
            &quot;r&quot;. For example: <code>rUS</code>, <code>rFR</code>, <code>rES</code></td>
    </tr>
    <tr>
        <td>Screen orientation</td>
        <td><code>port</code>, <code>land</code>, <code>square</code> </td>
    </tr>
    <tr>
        <td>Screen pixel density</td>
        <td><code>92dpi</code>, <code>108dpi</code>, etc. </td>
    </tr>
    <tr>
        <td>Touchscreen type</td>
        <td><code>notouch</code>, <code>stylus</code>, <code>finger</code></td>
    </tr>
    <tr>
        <td>Whether the keyboard is available to the user</td>
        <td><code>keysexposed</code>, <code>keyshidden</code> </td>
    </tr>
    <tr>
        <td>Primary text input method</td>
        <td><code>nokeys</code>, <code>qwerty</code>, <code>12key</code> </td>
    </tr>
    <tr>
        <td>Primary non-touchscreen<br />
            navigation method</td>
        <td><code>nonav</code>, <code>dpad</code>, <code>trackball</code>, <code>wheel</code> </td>
    </tr>
    <tr>
        <td>Screen dimensions</td>
        <td><code>320x240</code>, <code>640x480</code>, etc. The larger dimension
            must be specified first. </td>
    </tr>
</table>

<p>This list does not include device-specific parameters such as carrier,
branding, device/hardware, or manufacturer. Everything that an application
needs to know about the device that it is running on is encoded via the
resource qualifiers in the table above.</p>

<p>Here are some general guidelines on qualified resource directory names:</p>

<ul>
    <li>Values are separated by a dash (as well as a dash after the base directory
        name) </li>
    <li>Values are case-sensitive (even though they must be unique across all folder
        names in a case-insensitive way)<br />For example,</li>
    <ul>
        <li>A portrait-specific <code>drawable</code> directory must be named
            <code>drawable-port</code>, not <code>drawable-PORT</code>.</li>
        <li>You may not have two directories named <code>drawable-port</code>
            and <code>drawable-PORT</code>, even if you had intended "port" and
            "PORT" to refer to different parameter values.</li>
    </ul>
    <li>Only one value for each qualifier type is supported (that is, you cannot
        specify <code>drawable-rEN-rFR/</code>)</li>
    <li>You can specify multiple parameters to define specific configurations,
        but they must always be in the order listed above.
        For example, <code>drawable-en-rUS-land</code> will apply to landscape view,
        US-English devices. </li>
    <li>Android will try to find the most specific matching directory for the current
        configuration, as described below</li>
    <li>The order of parameters listed in this table is used to break a tie in case
        of multiple qualified directories (see the example given below) </li>
    <li>All directories, both qualified and unqualified, live under the <code>res/</code> folder.
        Qualified directories cannot be nested (you cannot have <code>res/drawable/drawable-en</code>) </li>
    <li>All resources will be referenced in code or resource reference syntax by
        their simple, undecorated name. So if a resource is named this:<br />
        &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<code>MyApp/res/drawable-port-92dp/myimage.png</code><br />
        It would be referenced as this:<br />
        &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<code>R.drawable.myimage</code> (code)<br />
        &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<code>&#064;drawable/myimage</code> (XML)</li>
</ul>

<h3>How Android finds the best matching directory </h3>

<p>Android will pick which of the various underlying resource files should be
used at runtime, depending on the current configuration. The selection process
is as follows:</p>

<ol>
    <li>
            Eliminate any resources whose configuration does not match the current
            device configuration. For example, if the screen pixel density is 108dpi,
            this would eliminate only <code>MyApp/res/drawable-port-92dpi/</code>.
        <blockquote>
            <pre>
MyApp/res/drawable/myimage.png
MyApp/res/drawable-en/myimage.png
MyApp/res/drawable-port/myimage.png
<strike>MyApp/res/drawable-port-92dpi/myimage.png</strike>
</pre>
        </blockquote>
    </li>
    <li>
            Pick the resources with the highest number of matching configurations.
            For example, if our locale is en-GB and orientation is port, then we
            have two candidates with one matching configuration each:
            <code>MyApp/res/drawable-en/</code> and <code>MyApp/res/drawable-port/</code>.
            The directory <code>MyApp/res/drawable/</code> is eliminated because
            it has zero matching configurations, while the others have one matching
            configuration.
        <blockquote>
            <pre>
<strike>MyApp/res/drawable/myimage.png</strike>
MyApp/res/drawable-en/myimage.png
MyApp/res/drawable-port/myimage.png
</pre>
        </blockquote>
    </li>
    <li>
            Pick the final matching file based on configuration precedence, which
            is the order of parameters listed in the table above. That is, it is
            more important to match the language than the orientation, so we break
            the tie by picking the language-specific file, <code>MyApp/res/drawable-en/</code>.
        <blockquote>
            <pre>MyApp/res/drawable-en/myimage.png
<strike>MyApp/res/drawable-port/myimage.png</strike>
</pre>
        </blockquote>
    </li>
</ol>

<a name="ResourcesTerminology"></a>
<h2>Terminology</h2>

<p>The resource system brings a number of different pieces together to
form the final complete resource functionality.  To help understand the
overall system, here are some brief definitions of the core concepts and
components you will encounter in using it:</p>

<p><strong>Asset</strong>: A single blob of data associated with an application. This
includes object files compiled from the Java source code, graphics (such as PNG
images), XML files, etc. These files are organized in a directory hierarchy
that, during final packaging of the application, is bundled together into a
single ZIP file.</p>

<p><strong>aapt</strong>: Android Asset Packaging Tool. The tool that generates the
final ZIP file of application assets.  In addition to collecting raw assets
together, it also parses resource definitions into binary asset data.</p>

<p><strong>Resource Table</strong>: A special asset that aapt generates for you,
describing all of the resources contained in an application/package.
This file is accessed for you by the Resources class; it is not touched
directly by applications.</p>

<p><strong>Resource</strong>: An entry in the Resource Table describing a single
named value.  Broadly, there are two types of resources: primitives and
bags.</p>

<p><strong>Resource Identifier</strong>: In the Resource Table all resources are
identified by a unique integer number.  In source code (resource descriptions,
XML files, Java source code) you can use symbolic names that stand as constants for
the actual resource identifier integer.</p>

<p><strong>Primitive Resource</strong>: All primitive resources can be written as a
simple string, using formatting to describe a variety of primitive types
included in the resource system: integers, colors, strings, references to
other resources, etc.  Complex resources, such as bitmaps and XML
describes, are stored as a primitive string resource whose value is the path
of the underlying Asset holding its actual data.</p>

<p><strong>Bag Resource</strong>: A special kind of resource entry that, instead of a
simple string, holds an arbitrary list of name/value pairs.  Each name is
itself a resource identifier, and each value can hold
the same kinds of string formatted data as a normal resource.  Bags also
support inheritance: a bag can inherit the values from another bag, selectively
replacing or extending them to generate its own contents.</p>

<p><strong>Kind</strong>: The resource kind is a way to organize resource identifiers
for various purposes.  For example, drawable resources are used to
instantiate Drawable objects, so their data is a primitive resource containing
either a color constant or string path to a bitmap or XML asset.  Other
common resource kinds are string (localized string primitives), color
(color primitives), layout (a string path to an XML asset describing a view
layout), and style (a bag resource describing user interface attributes).
There is also a standard "attr" resource kind, which defines the resource
identifiers to be used for naming bag items and XML attributes</p>

<p><strong>Style</strong>: The name of the resource kind containing bags that are used
to supply a set of user interface attributes.  For example, a TextView class may
be given a style resource that defines its text size, color, and alignment.
In a layout XML file, you associate a style with a bag using the "style"
attribute, whose value is the name of the style resource.</p>

<p><strong>Style Class</strong>: Specifies a related set of attribute resources.
This data is not placed in the resource table itself, but used to generate
constants in the source code that make it easier for you to retrieve values out of
a style resource and/or XML tag's attributes.  For example, the
Android platform defines a "View" style class that
contains all of the standard view attributes: padding, visibility,
background, etc.; when View is inflated it uses this style class to
retrieve those values from the XML file (at which point style and theme
information is applied as approriate) and load them into its instance.</p>

<p><strong>Configuration</strong>: For any particular resource identifier, there may be
multiple different available values depending on the current configuration.
The configuration includes the locale (language and country), screen
orientation, screen density, etc.  The current configuration is used to
select which resource values are in effect when the resource table is
loaded.</p>

<p><strong>Theme</strong>: A standard style resource that supplies global
attribute values for a particular context.  For example, when writing an
Activity the application developer can select a standard theme to use, such
as the Theme.White or Theme.Black styles; this style supplies information
such as the screen background image/color, default text color, button style,
text editor style, text size, etc.  When inflating a layout resource, most
values for widgets (the text color, selector, background) if not explicitly
set will come from the current theme; style and attribute
values supplied in the layout can also assign their value from explicitly
named values in the theme attributes if desired.</p>

<p><strong>Overlay</strong>: A resource table that does not define a new set of resources,
but instead replaces the values of resources that are in another resource table.
Like a configuration, this is applied at load time
to the resource data; it can add new configuration values (for example
strings in a new locale), replace existing values (for example change
the standard white background image to a "Hello Kitty" background image),
and modify resource bags (for example change the font size of the Theme.White
style to have an 18 pt font size).  This is the facility that allows the
user to select between different global appearances of their device, or
download files with new appearances.</p>

<h2>Resource Reference</h2>
<p>The <a href="available-resources.html">Available Resources</a>
document provides a detailed list of the various types of resource and how to use them
from within the Java source code, or from other references.</p>

<a name="i18n" id="i18n"></a>
<h2>Internationalization and Localization</h2>
<p class="note"><strong>Coming Soon:</strong> Internationalization and Localization are
critical, but are also not quite ready yet in the current SDK. As the
SDK matures, this section will contain information on the Internationalization
and Localization features of the Android platform. In the meantime, it is a good
idea to start by externalizing all strings, and practicing good structure in
creating and using resources.</p>