Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 208b9c5c authored by Scott Main's avatar Scott Main
Browse files

docs: rewrite resources documentation 

Huge overhaul. Includes all new dev guides about how resources are used
on Android and how to provide alternatives, including how to handle
runtime configuration changes (restarts). Plus all new reference
docs for all the resource types (drawables, strings, menus, etc.).

Change-Id: Icf079f5f45b1745a8d54f504e28dbbb52c6f7c96
parent 0381bc1f

docs/html/guide/guide_toc.cs

+23 −5
Original line number Diff line number Diff line
@@ -99,18 +99,36 @@ 
      </li>

      <li class="toggle-list">

        <div><a href="<?cs var:toroot ?>guide/topics/resources/index.html">

               <span class="en">Resources and Assets</span> 

               <span class="en">Application Resources</span>

             </a></div>

        <ul>

          <li><a href="<?cs var:toroot ?>guide/topics/resources/resources-i18n.html">

                <span class="en">Resources and I18n</span>

          <li><a href="<?cs var:toroot ?>guide/topics/resources/providing-resources.html">

                <span class="en">Providing Resources</span>

              </a></li>

          <li><a href="<?cs var:toroot ?>guide/topics/resources/available-resources.html">

                <span class="en">Available Resource Types</span>

          <li><a href="<?cs var:toroot ?>guide/topics/resources/accessing-resources.html">

                <span class="en">Accessing Resources</span>

              </a></li>

          <li><a href="<?cs var:toroot ?>guide/topics/resources/runtime-changes.html">

                <span class="en">Handling Runtime Changes</span>

              </a></li>

          <li><a href="<?cs var:toroot ?>guide/topics/resources/localization.html">

                <span class="en">Localization</span>

              </a></li>

          <li class="toggle-list">

            <div><a href="<?cs var:toroot ?>guide/topics/resources/available-resources.html">

              <span class="en">Resource Types</span>

            </a></div>

            <ul>

              <li><a href="<?cs var:toroot ?>guide/topics/resources/animation-resource.html">Animation</a></li>

              <li><a href="<?cs var:toroot ?>guide/topics/resources/color-list-resource.html">Color State List</a></li>

              <li><a href="<?cs var:toroot ?>guide/topics/resources/drawable-resource.html">Drawable</a></li>

              <li><a href="<?cs var:toroot ?>guide/topics/resources/layout-resource.html">Layout</a></li>

              <li><a href="<?cs var:toroot ?>guide/topics/resources/menu-resource.html">Menu</a></li>

              <li><a href="<?cs var:toroot ?>guide/topics/resources/string-resource.html">String</a></li>

              <li><a href="<?cs var:toroot ?>guide/topics/resources/style-resource.html">Style</a></li>

              <li><a href="<?cs var:toroot ?>guide/topics/resources/more-resources.html">More Types</a></li>

            </ul>

          </li>

        </ul>

      </li>

      <li><a href="<?cs var:toroot ?>guide/topics/intents/intents-filters.html">

docs/html/guide/topics/graphics/2d-graphics.jd

+3 −3
Original line number Diff line number Diff line
@@ -442,7 +442,7 @@ class is the basis for frame animations.</p> 
<p>While you can define the frames of an animation in your code, using the 

{@link android.graphics.drawable.AnimationDrawable} class API, it's more simply accomplished with a single XML 

file that lists the frames that compose the animation. Like the tween animation above, the XML file for this kind 

of animation belongs in the <code>res/anim/</code> directory of your Android project. In this case, 

of animation belongs in the <code>res/drawable/</code> directory of your Android project. In this case,

the instructions are the order and duration for each frame of the animation.</p>



<p>The XML file consists of an <code>&lt;animation-list></code> element as the root node and a series
@@ -459,7 +459,7 @@ Here's an example XML file for a frame-by-frame animation:</p> 


<p>This animation runs for just three frames. By setting the <code>android:oneshot</code> attribute of the 

list to <var>true</var>, it will cycle just once then stop and hold on the last frame. If it is set <var>false</var> then

the animation will loop. With this XML saved as <code>rocket_thrust.xml</code> in the <code>res/anim/</code> directory

the animation will loop. With this XML saved as <code>rocket_thrust.xml</code> in the <code>res/drawable/</code> directory

of the project, it can be added as the background image to a View and then called to play. Here's an example Activity,

in which the animation is added to an {@link android.widget.ImageView} and then animated when the screen is touched:</p>

<pre>
@@ -470,7 +470,7 @@ public void onCreate(Bundle savedInstanceState) { 
  setContentView(R.layout.main);



  ImageView rocketImage = (ImageView) findViewById(R.id.rocket_image);

  rocketImage.setBackgroundResource(R.anim.rocket_thrust);

  rocketImage.setBackgroundResource(R.drawable.rocket_thrust);

  rocketAnimation = (AnimationDrawable) rocketImage.getBackground();

}

docs/html/guide/topics/resources/accessing-resources.jd

0 → 100644
+284 −0
Original line number Diff line number Diff line 
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

&#64;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 &#64;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&mdash;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>&lt;package_name&gt;</em>.]R.<em>&lt;resource_type&gt;</em>.<em>&lt;resource_name&gt;</em></code>

</p>



<ul>

  <li><em>{@code &lt;package_name&gt;}</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 &lt;resource_type&gt;}</em> is the {@code R} subclass for the resource type.</li>

  <li><em>{@code &lt;resource_name&gt;}</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>&lt;package_name&gt;</em>:]<em>&lt;resource_type&gt;</em>/<em>&lt;resource_name&gt;</em></code></p>



<ul>

  <li>{@code &lt;package_name&gt;} is the name of the package in which the resource is located (not

required when referencing resources from the same package)</li>

  <li>{@code &lt;resource_type&gt;} is the

{@code R} subclass for the resource type</li>

  <li>{@code &lt;resource_name&gt;} 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>

&lt;?xml version="1.0" encoding="utf-8"?>

&lt;resources>

   &lt;color name="opaque_red">#f00&lt;/color>

   &lt;string name="hello">Hello!&lt;/string>

&lt;/resources>

</pre>



<p>You can use these resources in the following layout file to set the text color and

text string:</p>



<pre>

&lt;?xml version=&quot;1.0&quot; encoding=&quot;utf-8&quot;?&gt;

&lt;EditText xmlns:android=&quot;http://schemas.android.com/apk/res/android&quot;

    android:layout_width=&quot;fill_parent&quot;

    android:layout_height=&quot;fill_parent&quot;

    <strong>android:textColor=&quot;&#64;color/opaque_red&quot;

    android:text=&quot;&#64;string/hello&quot;</strong> /&gt;

</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>

&lt;?xml version=&quot;1.0&quot; encoding=&quot;utf-8&quot;?&gt;

&lt;EditText xmlns:android=&quot;http://schemas.android.com/apk/res/android&quot;

    android:layout_width=&quot;fill_parent&quot;

    android:layout_height=&quot;fill_parent&quot;

    <strong>android:textColor=&quot;&#64;android:color/secondary_text_dark&quot;</strong>

    android:text=&quot;&#64;string/hello&quot; /&gt;

</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>

&lt;?xml version="1.0" encoding="utf-8"?>

&lt;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 &#64;}), use a question-mark ({@code ?}), and the

resource type portion is optional. For instance:</p>



<p>

<code>

?[<em>&lt;package_name&gt;</em>:][<em>&lt;resource_type&gt;</em>/]<em>&lt;resource_name&gt;</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>

&lt;EditText id=&quot;text&quot;

    android:layout_width=&quot;fill_parent&quot;

    android:layout_height=&quot;wrap_content&quot;

    <strong>android:textColor=&quot;?android:textColorSecondary&quot;</strong>

    android:text=&quot;&#64;string/hello_world&quot; /&gt;

</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>