diff options
Diffstat (limited to 'docs/html/guide/topics/resources/accessing-resources.jd')
| -rw-r--r-- | docs/html/guide/topics/resources/accessing-resources.jd | 284 |
1 files changed, 284 insertions, 0 deletions
diff --git a/docs/html/guide/topics/resources/accessing-resources.jd b/docs/html/guide/topics/resources/accessing-resources.jd new file mode 100644 index 0000000..e3e4055 --- /dev/null +++ b/docs/html/guide/topics/resources/accessing-resources.jd @@ -0,0 +1,284 @@ +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="#ResourcesInCode">Accessing Resources in Code</a></li> + <li><a href="#ReferencesToResources">Accessing Resources in Other XML Resources</a> + <ol> + <li><a href="#ReferencesToThemeAttributes">Referencing style attributes</a></li> + </ol> + </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>There are two ways you can reference your resources for use in your application:</p> +<ul> + <li><strong>From your code:</strong> Using an integer from a sub-class in your {@code R} class, +such as: + <p>{@code R.string.hello}</p> + <p>You will see Android APIs that accept this kind of resource identifier as a method parameter +(usually defined as the {@code id} parameter).</p> + </li> + <li><strong>From another resource:</strong> Using a special XML syntax that corresponds to the +{@code R} sub-class, such as: + <p>{@code @string/hello}</p> + <p>You can use this syntax in an XML resource any place where a value is expected that is +matched by the existing resource. For example, if you need to provide a string in either an XML +attribute or element value, you can reference a resource instead of providing a hard-coded +string.</p> + </li> +</ul> + + + +<h2 id="ResourcesInCode">Accessing Resources in Code </h2> + +<p>When your application is compiled, Android generates the {@code R.java} file (inside +the {@code gen/} directory), which contains resource +identifiers to all the resources in your {@code res/} directory. For each type of resource, a +specific subclass is added to the {@code R} class (for example, +{@code R.drawable}) and for each resource of that type, a static +integer is added to the subclass (for example, +{@code R.drawable.icon}). This integer is the resource ID and you can use it to retrieve +your resource from your application code.</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. Instead, you can save your resources in the +{@code assets/} directory.</p> +<p>Files saved in the {@code assets/} directory will <em>not</em> be 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)}.</p> + +</div> +</div> + + +<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 will be overridden next time you compile.</p> + +<p>Here is the syntax to reference a resource in code:</p> +<p> +<code>[<em><package_name></em>.]R.<em><resource_type></em>.<em><resource_name></em></code> +</p> + +<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 {@code +android:name} attribute value (for some resources defined in XML files) or the resource filename +without the extension.</li> +</ul> +<p>See <a href="resource-types.html">Resource Types</a> for +more information about each resource type and how to reference them.</p> + +<p>In many cases, you can supply an API method with the resource ID. For example, to set the image +for an {@link android.widget.ImageView}:</p> +<pre> +ImageView iv = (ImageView) findViewById(R.id.myimageview); +iv.setImageResource(R.drawable.myimage); +</pre> + +<p>You can also retrieve your +resource objects using methods in {@link android.content.res.Resources}, which you can create an +instance of with {@link android.content.Context#getResources Context.getResources()}. For example, +to get a string:</p> +<pre> +Resources res = this.getResources(); +String string = res.getString(R.string.mystring); +</pre> + +<p>You can also access resources from the platform by prefixing the {@code android} +namespace. Android contains a number of standard resources, such as styles and themes for your +layout, button backgrounds, and layouts. To refer to these in code, qualify your reference with the +<code>android</code> package name. For example, +<code>android.R.layout.simple_gallery_item</code>.</p> + +<p>Here are some examples of using 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}(R.drawable.my_background_image) ; + +// 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}(R.string.main_title)); + +// Load a custom layout for the current screen +{@link android.app.Activity#setContentView(int) +setContentView}(R.layout.main_screen); + +// Set a slide in animation by getting an Animation from the Resources object +mFlipper.{@link android.widget.ViewAnimator#setInAnimation(Animation) +setInAnimation}(AnimationUtils.loadAnimation(this, + R.anim.hyperspace_in)); + +// Set the text on a TextView object using a resource ID +TextView msgTextView = (TextView) findViewById(R.id.msg); +msgTextView.{@link android.widget.TextView#setText(int) setText}(R.string.hello_message); +</pre> + + + + + + +<h2 id="ReferencesToResources">Accessing Resources in other XML Resources</h2> + +<p>When creating an XML resource, some values for attributes and elements can be a reference to +an existing resource. This is often used in layout files to supply strings and images.</p> + +<p>Here is the syntax to reference a resource in an XML resource:</p> +<p><code>@[<em><package_name></em>:]<em><resource_type></em>/<em><resource_name></em></code></p> + +<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 {@code +android:name} attribute value (for some resources defined in XML files) or the resource filename +without the extension</li> +</ul> + +<p>See <a href="resource-types.html">Resource Types</a> for +more information about each resource type and how to reference them.</p> + +<p>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" + <strong>android:textColor="@color/opaque_red" + android:text="@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" + <strong>android:textColor="@android:color/secondary_text_dark"</strong> + android:text="@string/hello" /> +</pre> + +<p class="note"><strong>Note:</strong> You should always use a string resource when supplying +strings in a layout file, as demonstrated above, so that the strings can be localized. For +information about creating alternative resources (such as localized strings), see <a +href="providing-resources.html#AlternativeResources">Providing Alternative +Resources</a>.</p> + +<p>This facility for referencing resources between resources can also be used to create +alias resources. For example, you can create new drawable resources that is an alias for an existing +image:</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 is discussed further in <a href="providing-resources.html#AliasResources">Creating +alias resources</a>.</p> + + + + +<h3 id="ReferencesToThemeAttributes">Referencing style attributes</h3> + +<p>A style attribute resource is another type of resource that 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> + +<p> +<code> +?[<em><package_name></em>:][<em><resource_type></em>/]<em><resource_name></em> +</code> +</p> + +<p>For example, here's how you might reference an attribute in a layout, +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" + <strong>android:textColor="?android:textColorSecondary"</strong> + android:text="@string/hello_world" /> +</pre> + +<p>Using this markup, you are +supplying the name of an attribute resource that will be looked up in the theme. +Because the system resource tool knows that an attribute resource is expected, +you do not need to explicitly state the type (which would be +<code>?android:attr/textColorSecondary</code>), so you can exclude the {@code attr} type.</p> + + + |