docs: revisions to the new resources doc based on editorial feedback (c6cb8a78) · Commits · e / os / android_frameworks_base

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

+152 −95

Original line number	Diff line number	Diff line
		@@ -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 @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">@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—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><package_name></em>.]R.<em><resource_type></em>.<em><resource_name></em></code>
		</p>
		<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 {@code
		android:name} attribute value (for some resources defined in XML files) or the resource filename
		without the extension.</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="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—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>

		<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><package_name></em>:]<em><resource_type></em>/<em><resource_name></em></code></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 {@code
		android:name} attribute value (for some resources defined in XML files) or the resource filename
		without the extension</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="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>
		<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> />
		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
		@@ -219,19 +260,18 @@ reference a system resource, you would need to include the package name. For exa
		<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:textColor="<strong>@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
		<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>
		<?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 @}), use a question-mark ({@code ?}), and the
		resource type portion is optional. For instance:</p>

		<p>
		<code>
		<pre class="classic">
		?[<em><package_name></em>:][<em><resource_type></em>/]<em><resource_name></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>
		<EditText id="text"
		android:layout_width="fill_parent"
		android:layout_height="wrap_content"
		<strong>android:textColor="?android:textColorSecondary"</strong>
		android:textColor="<strong>?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,
		<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>)—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>

docs/html/guide/topics/resources/animation-resource.jd

+30 −26

Original line number	Diff line number	Diff line
		@@ -62,18 +62,18 @@ In XML: <code>@[<em>package</em>:]anim/<em>filename</em></code>
		android:toXScale="<em>float</em>"
		android:fromYScale="<em>float</em>"
		android:toYScale="<em>float</em>"
		android:pivotX="<em>string</em>"
		android:pivotY="<em>string</em>" />
		android:pivotX="<em>float</em>"
		android:pivotY="<em>float</em>" />
		<<a href="#translate-element">translate</a>
		android:fromX="<em>string</em>"
		android:toX="<em>string</em>"
		android:fromY="<em>string</em>"
		android:toY="<em>string</em>" />
		android:fromX="<em>float</em>"
		android:toX="<em>float</em>"
		android:fromY="<em>float</em>"
		android:toY="<em>float</em>" />
		<<a href="#rotate-element">rotate</a>
		android:fromDegrees="<em>float</em>"
		android:toDegrees="<em>float</em>"
		android:pivotX="<em>string</em>"
		android:pivotY="<em>string</em>" />
		android:pivotX="<em>float</em>"
		android:pivotY="<em>float</em>" />
		<<a href="#set-element">set</a>>
		...
		</set>
		@@ -158,21 +158,21 @@ android.view.animation.TranslateAnimation}.
		<p class="caps">attributes:</p>
		<dl class="atn-list">
		<dt><code>android:fromXDelta</code></dt>
		<dd><em>Float or percentage</em>. Starting X offset. Either in: pixels relative to the
		normal position, in percentage relative to the element width (%), or relative to the parent width
		(%p).</dd>
		<dd><em>Float or percentage</em>. Starting X offset. Expressed either: in pixels relative
		to the normal position (such as {@code "5"}), in percentage relative to the element width (such as
		{@code "5%"}), or in percentage relative to the parent width (such as {@code "5%p"}).</dd>
		<dt><code>android:toXDelta</code></dt>
		<dd><em>Float or percentage</em>. Ending X offset. Either in: pixels relative to the
		normal position, in percentage relative to the element width (%), or relative to the parent width
		(%p).</dd>
		<dd><em>Float or percentage</em>. Ending X offset. Expressed either: in pixels relative
		to the normal position (such as {@code "5"}), in percentage relative to the element width (such as
		{@code "5%"}), or in percentage relative to the parent width (such as {@code "5%p"}).</dd>
		<dt><code>android:fromYDelta</code></dt>
		<dd><em>Float or percentage</em>. Starting Y offset. Either in: pixels relative to the
		normal position, in percentage relative to the element height (%), or relative to the parent height
		(%p).</dd>
		<dd><em>Float or percentage</em>. Starting Y offset. Expressed either: in pixels relative
		to the normal position (such as {@code "5"}), in percentage relative to the element height (such as
		{@code "5%"}), or in percentage relative to the parent height (such as {@code "5%p"}).</dd>
		<dt><code>android:toYDelta</code></dt>
		<dd><em>Float or percentage</em>. Ending Y offset. Either in: pixels relative to the
		normal position, in percentage relative to the element height (%), or relative to the parent height
		(%p).</dd>
		<dd><em>Float or percentage</em>. Ending Y offset. Expressed either: in pixels relative
		to the normal position (such as {@code "5"}), in percentage relative to the element height (such as
		{@code "5%"}), or in percentage relative to the parent height (such as {@code "5%p"}).</dd>
		</dl>
		<p>For more attributes supported by <code><translate></code>, see the
		{@link android.view.animation.Animation} class reference (of which, all XML attributes are
		@@ -183,15 +183,19 @@ inherrited by this element).</p>
		<p class="caps">attributes:</p>
		<dl class="atn-list">
		<dt><code>android:fromDegrees</code></dt>
		<dd><em>Integer</em>. Starting angular position, in degrees.</dd>
		<dd><em>Float</em>. Starting angular position, in degrees.</dd>
		<dt><code>android:toDegrees</code></dt>
		<dd><em>Integer</em>. Ending angular position, in degrees.</dd>
		<dd><em>Float</em>. Ending angular position, in degrees.</dd>
		<dt><code>android:pivotX</code></dt>
		<dd><em>Integer or percentage</em>. The X coordinate of the center of rotation, in total
		pixels (where 0 is the left edge) or percentage of the screen width.</dd>
		<dd><em>Float or percentage</em>. The X coordinate of the center of rotation. Expressed
		either: in pixels relative to the object's left edge (such as {@code "5"}), in percentage relative
		to the object's left edge (such as {@code "5%"}), or in percentage relative to the parent
		container's left edge (such as {@code "5%p"}).</dd>
		<dt><code>android:pivotY</code></dt>
		<dd><em>Integer or percentage</em>. The Y coordinate of the center of rotation, in total
		pixels (where 0 is the top edge) or percentage of the screen height.</dd>
		<dd><em>Float or percentage</em>. The Y coordinate of the center of rotation. Expressed
		either: in pixels relative to the object's top edge (such as {@code "5"}), in percentage relative
		to the object's top edge (such as {@code "5%"}), or in percentage relative to the parent
		container's top edge (such as {@code "5%p"}).</dd>
		</dl>
		<p>For more attributes supported by <code><rotate></code>, see the
		{@link android.view.animation.Animation} class reference (of which, all XML attributes are

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

+17 −0

File changed.

Preview size limit exceeded, changes collapsed.

docs/html/guide/topics/resources/drawable-resource.jd

+21 −21

File changed.

Preview size limit exceeded, changes collapsed.

docs/html/guide/topics/resources/index.jd

+2 −2

Original line number	Diff line number	Diff line
		@@ -27,14 +27,14 @@ important as more Android-powered devices become available with different config
		to provide this functionality, you must organize resources in your project's {@code res/}
		directory, using various sub-directories that group resources by type and configuration.</p>

		<div class="figure" style="width:441px">
		<div class="figure" style="width:421px">
		<img src="{@docRoot}images/resources/resource_devices_diagram1.png" height="137" alt="" />
		<p class="img-caption">
		<strong>Figure 1.</strong> Two device configurations, both using default
		resources.</p>
		</div>

		<div class="figure" style="width:441px">
		<div class="figure" style="width:421px">
		<img src="{@docRoot}images/resources/resource_devices_diagram2.png" height="137" alt="" />
		<p class="img-caption">
		<strong>Figure 2.</strong> Two device configurations, one using alternative