342 lines
14 KiB
Plaintext
342 lines
14 KiB
Plaintext
page.title=Accessing Resources
|
|
parent.title=Application Resources
|
|
parent.link=index.html
|
|
@jd:body
|
|
|
|
<div id="qv-wrapper">
|
|
<div id="qv">
|
|
<h2>Quickview</h2>
|
|
<ul>
|
|
<li>Resources can be referenced from code using integers from {@code R.java}, such as
|
|
{@code R.drawable.myimage}</li>
|
|
<li>Resources can be referenced from resources using a special XML syntax, such as {@code
|
|
@drawable/myimage}</li>
|
|
<li>You can also access your app resources with methods in
|
|
{@link android.content.res.Resources}</li>
|
|
</ul>
|
|
|
|
<h2>Key classes</h2>
|
|
<ol>
|
|
<li>{@link android.content.res.Resources}</li>
|
|
</ol>
|
|
|
|
<h2>In this document</h2>
|
|
<ol>
|
|
<li><a href="#ResourcesFromCode">Accessing Resources from Code</a></li>
|
|
<li><a href="#ResourcesFromXml">Accessing Resources from XML</a>
|
|
<ol>
|
|
<li><a href="#ReferencesToThemeAttributes">Referencing style attributes</a></li>
|
|
</ol>
|
|
</li>
|
|
<li><a href="#PlatformResources">Accessing Platform Resources</a></li>
|
|
</ol>
|
|
|
|
<h2>See also</h2>
|
|
<ol>
|
|
<li><a href="providing-resources.html">Providing Resources</a></li>
|
|
<li><a href="available-resources.html">Resource Types</a></li>
|
|
</ol>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<p>Once you provide a resource in your application (discussed in <a
|
|
href="providing-resources.html">Providing Resources</a>), you can apply it by
|
|
referencing its resource ID. All resource IDs are defined in your project's {@code R} class, which
|
|
the {@code aapt} tool automatically generates.</p>
|
|
|
|
<p>When your application is compiled, {@code aapt} generates the {@code R} class, which contains
|
|
resource IDs for all the resources in your {@code
|
|
res/} directory. For each type of resource, there is an {@code R} subclass (for example,
|
|
{@code R.drawable} for all drawable resources) and for each resource of that type, there is a static
|
|
integer (for example, {@code R.drawable.icon}). This integer is the resource ID that you can use
|
|
to retrieve your resource.</p>
|
|
|
|
<p>Although the {@code R} class is where resource IDs are specified, you should never need to
|
|
look there to discover a resource ID. A resource ID is always composed of:</p>
|
|
<ul>
|
|
<li>The <em>resource type</em>: Each resource is grouped into a "type," such as {@code
|
|
string}, {@code drawable}, and {@code layout}. For more about the different types, see <a
|
|
href="available-resources.html">Resource Types</a>.
|
|
</li>
|
|
<li>The <em>resource name</em>, which is either: the filename,
|
|
excluding the extension; or the value in the XML {@code android:name} attribute, if the
|
|
resource is a simple value (such as a string).</li>
|
|
</ul>
|
|
|
|
<p>There are two ways you can access a resource:</p>
|
|
<ul>
|
|
<li><strong>In code:</strong> Using an static integer from a sub-class of your {@code R}
|
|
class, such as:
|
|
<pre class="classic no-pretty-print">R.string.hello</pre>
|
|
<p>{@code string} is the resource type and {@code hello} is the resource name. There are many
|
|
Android APIs that can access your resources when you provide a resource ID in this format. See
|
|
<a href="#ResourcesFromCode">Accessing Resources in Code</a>.</p>
|
|
</li>
|
|
<li><strong>In XML:</strong> Using a special XML syntax that also corresponds to
|
|
the resource ID defined in your {@code R} class, such as:
|
|
<pre class="classic no-pretty-print">@string/hello</pre>
|
|
<p>{@code string} is the resource type and {@code hello} is the resource name. You can use this
|
|
syntax in an XML resource any place where a value is expected that you provide in a resource. See <a
|
|
href="#ResourcesFromXml">Accessing Resources from XML</a>.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
|
|
<h2 id="ResourcesFromCode">Accessing Resources in Code </h2>
|
|
|
|
<p>You can use a resource in code by passing the resource ID as a method parameter. For
|
|
example, you can set an {@link android.widget.ImageView} to use the {@code res/drawable/myimage.png}
|
|
resource using {@link android.widget.ImageView#setImageResource(int) setImageResource()}:</p>
|
|
<pre>
|
|
ImageView imageView = (ImageView) findViewById(R.id.myimageview);
|
|
imageView.setImageResource(<strong>R.drawable.myimage</strong>);
|
|
</pre>
|
|
|
|
<p>You can also retrieve individual resources using methods in {@link
|
|
android.content.res.Resources}, which you can get an instance of
|
|
with {@link android.content.Context#getResources()}.</p>
|
|
|
|
<div class="sidebox-wrapper">
|
|
<div class="sidebox">
|
|
<h2>Access to Original Files</h2>
|
|
|
|
<p>While uncommon, you might need access your original files and directories. If you do, then
|
|
saving your files in {@code res/} won't work for you, because the only way to read a resource from
|
|
{@code res/} is with the resource ID. Instead, you can save your resources in the
|
|
{@code assets/} directory.</p>
|
|
<p>Files saved in the {@code assets/} directory are <em>not</em> given a resource
|
|
ID, so you can't reference them through the {@code R} class or from XML resources. Instead, you can
|
|
query files in the {@code assets/} directory like a normal file system and read raw data using
|
|
{@link android.content.res.AssetManager}.</p>
|
|
<p>However, if all you require is the ability to read raw data (such as a video or audio file),
|
|
then save the file in the {@code res/raw/} directory and read a stream of bytes using {@link
|
|
android.content.res.Resources#openRawResource(int) openRawResource()}.</p>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
|
|
<h3>Syntax</h3>
|
|
|
|
<p>Here's the syntax to reference a resource in code:</p>
|
|
|
|
<pre class="classic no-pretty-print">
|
|
[<em><package_name></em>.]R.<em><resource_type></em>.<em><resource_name></em>
|
|
</pre>
|
|
|
|
<ul>
|
|
<li><em>{@code <package_name>}</em> is the name of the package in which the resource is located (not
|
|
required when referencing resources from your own package).</li>
|
|
<li><em>{@code <resource_type>}</em> is the {@code R} subclass for the resource type.</li>
|
|
<li><em>{@code <resource_name>}</em> is either the resource filename
|
|
without the extension or the {@code android:name} attribute value in the XML element (for simple
|
|
values).</li>
|
|
</ul>
|
|
<p>See <a href="available-resources.html">Resource Types</a> for
|
|
more information about each resource type and how to reference them.</p>
|
|
|
|
|
|
<h3>Use cases</h3>
|
|
|
|
<p>There are many methods that accept a resource ID parameter and you can retrieve resources using
|
|
methods in {@link android.content.res.Resources}. You can get an instance of {@link
|
|
android.content.res.Resources} with {@link android.content.Context#getResources
|
|
Context.getResources()}.</p>
|
|
|
|
|
|
<p>Here are some examples of accessing resources in code:</p>
|
|
|
|
<pre>
|
|
// Load a background for the current screen from a drawable resource
|
|
{@link android.app.Activity#getWindow()}.{@link
|
|
android.view.Window#setBackgroundDrawableResource(int)
|
|
setBackgroundDrawableResource}(<strong>R.drawable.my_background_image</strong>) ;
|
|
|
|
// Set the Activity title by getting a string from the Resources object, because
|
|
// this method requires a CharSequence rather than a resource ID
|
|
{@link android.app.Activity#getWindow()}.{@link android.view.Window#setTitle(CharSequence)
|
|
setTitle}(getResources().{@link android.content.res.Resources#getText(int)
|
|
getText}(<strong>R.string.main_title</strong>));
|
|
|
|
// Load a custom layout for the current screen
|
|
{@link android.app.Activity#setContentView(int)
|
|
setContentView}(<strong>R.layout.main_screen</strong>);
|
|
|
|
// Set a slide in animation by getting an Animation from the Resources object
|
|
mFlipper.{@link android.widget.ViewAnimator#setInAnimation(Animation)
|
|
setInAnimation}(AnimationUtils.loadAnimation(this,
|
|
<strong>R.anim.hyperspace_in</strong>));
|
|
|
|
// Set the text on a TextView object using a resource ID
|
|
TextView msgTextView = (TextView) findViewById(<strong>R.id.msg</strong>);
|
|
msgTextView.{@link android.widget.TextView#setText(int)
|
|
setText}(<strong>R.string.hello_message</strong>);
|
|
</pre>
|
|
|
|
|
|
<p class="caution"><strong>Caution:</strong> You should never modify the {@code
|
|
R.java} file by hand—it is generated by the {@code aapt} tool when your project is
|
|
compiled. Any changes are overridden next time you compile.</p>
|
|
|
|
|
|
|
|
<h2 id="ResourcesFromXml">Accessing Resources from XML</h2>
|
|
|
|
<p>You can define values for some XML attributes and elements using a
|
|
reference to an existing resource. You will often do this when creating layout files, to
|
|
supply strings and images for your widgets.</p>
|
|
|
|
<p>For example, if you add a {@link android.widget.Button} to your layout, you should use
|
|
a <a href="string-resource.html">string resource</a> for the button text:</p>
|
|
|
|
<pre>
|
|
<Button
|
|
android:layout_width="fill_parent"
|
|
android:layout_height="wrap_content"
|
|
android:text="<strong>@string/submit</strong>" />
|
|
</pre>
|
|
|
|
|
|
<h3>Syntax</h3>
|
|
|
|
<p>Here is the syntax to reference a resource in an XML resource:</p>
|
|
|
|
<pre class="classic no-pretty-print">
|
|
@[<em><package_name></em>:]<em><resource_type></em>/<em><resource_name></em>
|
|
</pre>
|
|
|
|
<ul>
|
|
<li>{@code <package_name>} is the name of the package in which the resource is located (not
|
|
required when referencing resources from the same package)</li>
|
|
<li>{@code <resource_type>} is the
|
|
{@code R} subclass for the resource type</li>
|
|
<li>{@code <resource_name>} is either the resource filename
|
|
without the extension or the {@code android:name} attribute value in the XML element (for simple
|
|
values).</li>
|
|
</ul>
|
|
|
|
<p>See <a href="available-resources.html">Resource Types</a> for
|
|
more information about each resource type and how to reference them.</p>
|
|
|
|
|
|
<h3>Use cases</h3>
|
|
|
|
<p>In some cases you must use a resource for a value in XML (for example, to apply a drawable image
|
|
to a widget), but you can also use a resource in XML any place that accepts a simple value. For
|
|
example, if you have the following resource file that includes a <a
|
|
href="more-resources.html#Color">color resource</a> and a <a
|
|
href="string-resource.html">string resource</a>:</p>
|
|
|
|
<pre>
|
|
<?xml version="1.0" encoding="utf-8"?>
|
|
<resources>
|
|
<color name="opaque_red">#f00</color>
|
|
<string name="hello">Hello!</string>
|
|
</resources>
|
|
</pre>
|
|
|
|
<p>You can use these resources in the following layout file to set the text color and
|
|
text string:</p>
|
|
|
|
<pre>
|
|
<?xml version="1.0" encoding="utf-8"?>
|
|
<EditText xmlns:android="http://schemas.android.com/apk/res/android"
|
|
android:layout_width="fill_parent"
|
|
android:layout_height="fill_parent"
|
|
android:textColor="<strong>@color/opaque_red</strong>"
|
|
android:text="<strong>@string/hello</strong>" />
|
|
</pre>
|
|
|
|
<p>In this case you don't need to specify the package name in the resource reference because the
|
|
resources are from your own package. To
|
|
reference a system resource, you would need to include the package name. For example:</p>
|
|
|
|
<pre>
|
|
<?xml version="1.0" encoding="utf-8"?>
|
|
<EditText xmlns:android="http://schemas.android.com/apk/res/android"
|
|
android:layout_width="fill_parent"
|
|
android:layout_height="fill_parent"
|
|
android:textColor="<strong>@android:color/secondary_text_dark</strong>"
|
|
android:text="@string/hello" />
|
|
</pre>
|
|
|
|
<p class="note"><strong>Note:</strong> You should use string resources at all times, so that your
|
|
application can be localized for other languages. For information about creating alternative
|
|
resources (such as localized strings), see <a
|
|
href="providing-resources.html#AlternativeResources">Providing Alternative
|
|
Resources</a>.</p>
|
|
|
|
<p>You can even use resources in XML to create aliases. For example, you can create a
|
|
drawable resource that is an alias for another drawable resource:</p>
|
|
|
|
<pre>
|
|
<?xml version="1.0" encoding="utf-8"?>
|
|
<bitmap xmlns:android="http://schemas.android.com/apk/res/android"
|
|
android:src="@drawable/other_drawable" />
|
|
</pre>
|
|
|
|
<p>This sounds redundant, but can be very useful when using alternative resource. Read more about
|
|
<a href="providing-resources.html#AliasResources">Creating alias resources</a>.</p>
|
|
|
|
|
|
|
|
<h3 id="ReferencesToThemeAttributes">Referencing style attributes</h3>
|
|
|
|
<p>A style attribute resource allows you to reference the value
|
|
of an attribute in the currently-applied theme. Referencing a style attribute allows you to
|
|
customize the look of UI elements by styling them to match standard variations supplied by the
|
|
current theme, instead of supplying a hard-coded value. Referencing a style attribute
|
|
essentially says, "use the style that is defined by this attribute, in the current theme."</p>
|
|
|
|
<p>To reference a style attribute, the name syntax is almost identical to the normal resource
|
|
format, but instead of the at-symbol ({@code @}), use a question-mark ({@code ?}), and the
|
|
resource type portion is optional. For instance:</p>
|
|
|
|
<pre class="classic">
|
|
?[<em><package_name></em>:][<em><resource_type></em>/]<em><resource_name></em>
|
|
</pre>
|
|
|
|
<p>For example, here's how you can reference an attribute to set the text color to match the
|
|
"primary" text color of the system theme:</p>
|
|
|
|
<pre>
|
|
<EditText id="text"
|
|
android:layout_width="fill_parent"
|
|
android:layout_height="wrap_content"
|
|
android:textColor="<strong>?android:textColorSecondary</strong>"
|
|
android:text="@string/hello_world" />
|
|
</pre>
|
|
|
|
<p>Here, the {@code android:textColor} attribute specifies the name of a style attribute
|
|
in the current theme. Android now uses the value applied to the {@code android:textColorSecondary}
|
|
style attribute as the value for {@code android:textColor} in this widget. Because the system
|
|
resource tool knows that an attribute resource is expected in this context,
|
|
you do not need to explicitly state the type (which would be
|
|
<code>?android:attr/textColorSecondary</code>)—you can exclude the {@code attr} type.</p>
|
|
|
|
|
|
|
|
|
|
<h2 id="PlatformResources">Accessing Platform Resources</h2>
|
|
|
|
<p>Android contains a number of standard resources, such as styles, themes, and layouts. To
|
|
access these resource, qualify your resource reference with the
|
|
<code>android</code> package name. For example, Android provides a layout resource you can use for
|
|
list items in a {@link android.widget.ListAdapter}:</p>
|
|
|
|
<pre>
|
|
{@link android.app.ListActivity#setListAdapter(ListAdapter)
|
|
setListAdapter}(new {@link
|
|
android.widget.ArrayAdapter}<String>(this, <strong>android.R.layout.simple_list_item_1</strong>, myarray));
|
|
</pre>
|
|
|
|
<p>In this example, {@link android.R.layout#simple_list_item_1} is a layout resource defined by the
|
|
platform for items in a {@link android.widget.ListView}. You can use this instead of creating
|
|
your own layout for list items. (For more about using {@link android.widget.ListView}, see the
|
|
<a href="{@docRoot}resources/tutorials/views/hello-listview.html">List View Tutorial</a>.)</p>
|
|
|