docs: revisions to the new resources doc based on editorial feedback

plus some fixes to resource references and other misc revisions

Change-Id: I7b498858d9d0ecfd8cf9bad48c08c93047d597b8

1 files changed, 152 insertions, 95 deletions

diff --git a/docs/html/guide/topics/resources/accessing-resources.jd b/docs/html/guide/topics/resources/accessing-resources.jd
index e3e4055..cf8970c 100644
--- a/docs/html/guide/topics/resources/accessing-resources.jd
+++ b/docs/html/guide/topics/resources/accessing-resources.jd
@@ -22,12 +22,13 @@ parent.link=index.html
 
   <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>
+    <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>
@@ -39,154 +40,194 @@ parent.link=index.html
 </div>
 
 
-<p>There are two ways you can reference your resources for use in your application:</p>
+
+
+<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>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><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>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><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">&#64;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="ResourcesInCode">Accessing Resources in Code </h2>
+<h2 id="ResourcesFromCode">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>
+<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. Instead, you can save your resources in the
+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 will <em>not</em> be given a resource
+<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)}.</p>
+android.content.res.Resources#openRawResource(int) openRawResource()}.</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>
+<h3>Syntax</h3>
 
-<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>
+<p>Here's the syntax to reference a resource in code:</p>
+
+<pre class="classic no-pretty-print">
+[<em>&lt;package_name&gt;</em>.]R.<em>&lt;resource_type&gt;</em>.<em>&lt;resource_name&gt;</em>
+</pre>
 
 <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>
+  <li><em>{@code &lt;resource_name&gt;}</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="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>
+<h3>Use cases</h3>
 
-<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>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 using resources in code:</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}(R.drawable.my_background_image) ;
+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}(R.string.main_title));
+getText}(<strong>R.string.main_title</strong>));
 
 // Load a custom layout for the current screen
 {@link android.app.Activity#setContentView(int)
-setContentView}(R.layout.main_screen);
+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,
-        R.anim.hyperspace_in));
+        <strong>R.anim.hyperspace_in</strong>));
 
 // 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);
+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&mdash;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>
+&lt;Button
+    android:layout_width="fill_parent"
+    android:layout_height="wrap_content"
+    android:text="<strong>@string/submit</strong>" /&gt;
+</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>
+<h3>Syntax</h3>
 
 <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>
+
+<pre class="classic no-pretty-print">
+&#64;[<em>&lt;package_name&gt;</em>:]<em>&lt;resource_type&gt;</em>/<em>&lt;resource_name&gt;</em>
+</pre>
 
 <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>
+  <li>{@code &lt;resource_name&gt;} 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="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
+
+<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>
 
@@ -206,8 +247,8 @@ text string:</p>
 &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;
+    android:textColor=&quot;<strong>&#64;color/opaque_red</strong>&quot;
+    android:text=&quot;<strong>&#64;string/hello</strong>&quot; /&gt;
 </pre>
 
 <p>In this case you don't need to specify the package name in the resource reference because the
@@ -219,19 +260,18 @@ reference a system resource, you would need to include the package name. For exa
 &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:textColor=&quot;<strong>&#64;android:color/secondary_text_dark</strong>&quot;
     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
+<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>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>
+<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>
 &lt;?xml version="1.0" encoding="utf-8"?>
@@ -239,15 +279,14 @@ image:</p>
     android:src="@drawable/other_drawable" />
 </pre>
 
-<p>This is discussed further in <a href="providing-resources.html#AliasResources">Creating
-alias resources</a>.</p>
-
+<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 is another type of resource that allows you to reference the value
+<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
@@ -257,28 +296,46 @@ essentially says, "use the style that is defined by this attribute, in the curre
 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>
+<pre class="classic">
 ?[<em>&lt;package_name&gt;</em>:][<em>&lt;resource_type&gt;</em>/]<em>&lt;resource_name&gt;</em>
-</code>
-</p>
+</pre>
 
-<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>
+<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>
 &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:textColor=&quot;<strong>?android:textColorSecondary</strong>&quot;
     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,
+<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>), so you can exclude the {@code attr} type.</p>
+<code>?android:attr/textColorSecondary</code>)&mdash;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}&lt;String&gt;(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>