1page.title=Accessing Resources 2parent.title=Application Resources 3parent.link=index.html 4@jd:body 5 6<div id="qv-wrapper"> 7<div id="qv"> 8 <h2>Quickview</h2> 9 <ul> 10 <li>Resources can be referenced from code using integers from {@code R.java}, such as 11{@code R.drawable.myimage}</li> 12 <li>Resources can be referenced from resources using a special XML syntax, such as 13<code>@drawable/myimage</code></li> 14 <li>You can also access your app resources with methods in 15{@link android.content.res.Resources}</li> 16 </ul> 17 18 <h2>Key classes</h2> 19 <ol> 20 <li>{@link android.content.res.Resources}</li> 21 </ol> 22 23 <h2>In this document</h2> 24 <ol> 25 <li><a href="#ResourcesFromCode">Accessing Resources from Code</a></li> 26 <li><a href="#ResourcesFromXml">Accessing Resources from XML</a> 27 <ol> 28 <li><a href="#ReferencesToThemeAttributes">Referencing style attributes</a></li> 29 </ol> 30 </li> 31 <li><a href="#PlatformResources">Accessing Platform Resources</a></li> 32 </ol> 33 34 <h2>See also</h2> 35 <ol> 36 <li><a href="providing-resources.html">Providing Resources</a></li> 37 <li><a href="available-resources.html">Resource Types</a></li> 38 </ol> 39</div> 40</div> 41 42 43 44 45<p>Once you provide a resource in your application (discussed in <a 46href="providing-resources.html">Providing Resources</a>), you can apply it by 47referencing its resource ID. All resource IDs are defined in your project's {@code R} class, which 48the {@code aapt} tool automatically generates.</p> 49 50<p>When your application is compiled, {@code aapt} generates the {@code R} class, which contains 51resource IDs for all the resources in your {@code 52res/} directory. For each type of resource, there is an {@code R} subclass (for example, 53{@code R.drawable} for all drawable resources), and for each resource of that type, there is a static 54integer (for example, {@code R.drawable.icon}). This integer is the resource ID that you can use 55to retrieve your resource.</p> 56 57<p>Although the {@code R} class is where resource IDs are specified, you should never need to 58look there to discover a resource ID. A resource ID is always composed of:</p> 59<ul> 60 <li>The <em>resource type</em>: Each resource is grouped into a "type," such as {@code 61string}, {@code drawable}, and {@code layout}. For more about the different types, see <a 62href="available-resources.html">Resource Types</a>. 63 </li> 64 <li>The <em>resource name</em>, which is either: the filename, 65excluding the extension; or the value in the XML {@code android:name} attribute, if the 66resource is a simple value (such as a string).</li> 67</ul> 68 69<p>There are two ways you can access a resource:</p> 70<ul> 71 <li><strong>In code:</strong> Using a static integer from a sub-class of your {@code R} 72class, such as: 73 <pre class="classic no-pretty-print">R.string.hello</pre> 74 <p>{@code string} is the resource type and {@code hello} is the resource name. There are many 75Android APIs that can access your resources when you provide a resource ID in this format. See 76<a href="#ResourcesFromCode">Accessing Resources in Code</a>.</p> 77 </li> 78 <li><strong>In XML:</strong> Using a special XML syntax that also corresponds to 79the resource ID defined in your {@code R} class, such as: 80 <pre class="classic no-pretty-print">@string/hello</pre> 81 <p>{@code string} is the resource type and {@code hello} is the resource name. You can use this 82syntax in an XML resource any place where a value is expected that you provide in a resource. See <a 83href="#ResourcesFromXml">Accessing Resources from XML</a>.</p> 84 </li> 85</ul> 86 87 88 89<h2 id="ResourcesFromCode">Accessing Resources in Code </h2> 90 91<p>You can use a resource in code by passing the resource ID as a method parameter. For 92example, you can set an {@link android.widget.ImageView} to use the {@code res/drawable/myimage.png} 93resource using {@link android.widget.ImageView#setImageResource(int) setImageResource()}:</p> 94<pre> 95ImageView imageView = (ImageView) findViewById(R.id.myimageview); 96imageView.setImageResource(<strong>R.drawable.myimage</strong>); 97</pre> 98 99<p>You can also retrieve individual resources using methods in {@link 100android.content.res.Resources}, which you can get an instance of 101with {@link android.content.Context#getResources()}.</p> 102 103<div class="sidebox-wrapper"> 104<div class="sidebox"> 105<h2>Access to Original Files</h2> 106 107<p>While uncommon, you might need access your original files and directories. If you do, then 108saving your files in {@code res/} won't work for you, because the only way to read a resource from 109{@code res/} is with the resource ID. Instead, you can save your resources in the 110{@code assets/} directory.</p> 111<p>Files saved in the {@code assets/} directory are <em>not</em> given a resource 112ID, so you can't reference them through the {@code R} class or from XML resources. Instead, you can 113query files in the {@code assets/} directory like a normal file system and read raw data using 114{@link android.content.res.AssetManager}.</p> 115<p>However, if all you require is the ability to read raw data (such as a video or audio file), 116then save the file in the {@code res/raw/} directory and read a stream of bytes using {@link 117android.content.res.Resources#openRawResource(int) openRawResource()}.</p> 118 119</div> 120</div> 121 122 123<h3>Syntax</h3> 124 125<p>Here's the syntax to reference a resource in code:</p> 126 127<pre class="classic no-pretty-print"> 128[<em><package_name></em>.]R.<em><resource_type></em>.<em><resource_name></em> 129</pre> 130 131<ul> 132 <li><em>{@code <package_name>}</em> is the name of the package in which the resource is located (not 133required when referencing resources from your own package).</li> 134 <li><em>{@code <resource_type>}</em> is the {@code R} subclass for the resource type.</li> 135 <li><em>{@code <resource_name>}</em> is either the resource filename 136without the extension or the {@code android:name} attribute value in the XML element (for simple 137values).</li> 138</ul> 139<p>See <a href="available-resources.html">Resource Types</a> for 140more information about each resource type and how to reference them.</p> 141 142 143<h3>Use cases</h3> 144 145<p>There are many methods that accept a resource ID parameter and you can retrieve resources using 146methods in {@link android.content.res.Resources}. You can get an instance of {@link 147android.content.res.Resources} with {@link android.content.Context#getResources 148Context.getResources()}.</p> 149 150 151<p>Here are some examples of accessing resources in code:</p> 152 153<pre> 154// Load a background for the current screen from a drawable resource 155{@link android.app.Activity#getWindow()}.{@link 156android.view.Window#setBackgroundDrawableResource(int) 157setBackgroundDrawableResource}(<strong>R.drawable.my_background_image</strong>) ; 158 159// Set the Activity title by getting a string from the Resources object, because 160// this method requires a CharSequence rather than a resource ID 161{@link android.app.Activity#getWindow()}.{@link android.view.Window#setTitle(CharSequence) 162setTitle}(getResources().{@link android.content.res.Resources#getText(int) 163getText}(<strong>R.string.main_title</strong>)); 164 165// Load a custom layout for the current screen 166{@link android.app.Activity#setContentView(int) 167setContentView}(<strong>R.layout.main_screen</strong>); 168 169// Set a slide in animation by getting an Animation from the Resources object 170mFlipper.{@link android.widget.ViewAnimator#setInAnimation(Animation) 171setInAnimation}(AnimationUtils.loadAnimation(this, 172 <strong>R.anim.hyperspace_in</strong>)); 173 174// Set the text on a TextView object using a resource ID 175TextView msgTextView = (TextView) findViewById(<strong>R.id.msg</strong>); 176msgTextView.{@link android.widget.TextView#setText(int) 177setText}(<strong>R.string.hello_message</strong>); 178</pre> 179 180 181<p class="caution"><strong>Caution:</strong> You should never modify the {@code 182R.java} file by hand—it is generated by the {@code aapt} tool when your project is 183compiled. Any changes are overridden next time you compile.</p> 184 185 186 187<h2 id="ResourcesFromXml">Accessing Resources from XML</h2> 188 189<p>You can define values for some XML attributes and elements using a 190reference to an existing resource. You will often do this when creating layout files, to 191supply strings and images for your widgets.</p> 192 193<p>For example, if you add a {@link android.widget.Button} to your layout, you should use 194a <a href="string-resource.html">string resource</a> for the button text:</p> 195 196<pre> 197<Button 198 android:layout_width="fill_parent" 199 android:layout_height="wrap_content" 200 android:text="<strong>@string/submit</strong>" /> 201</pre> 202 203 204<h3>Syntax</h3> 205 206<p>Here is the syntax to reference a resource in an XML resource:</p> 207 208<pre class="classic no-pretty-print"> 209@[<em><package_name></em>:]<em><resource_type></em>/<em><resource_name></em> 210</pre> 211 212<ul> 213 <li>{@code <package_name>} is the name of the package in which the resource is located (not 214required when referencing resources from the same package)</li> 215 <li>{@code <resource_type>} is the 216{@code R} subclass for the resource type</li> 217 <li>{@code <resource_name>} is either the resource filename 218without the extension or the {@code android:name} attribute value in the XML element (for simple 219values).</li> 220</ul> 221 222<p>See <a href="available-resources.html">Resource Types</a> for 223more information about each resource type and how to reference them.</p> 224 225 226<h3>Use cases</h3> 227 228<p>In some cases you must use a resource for a value in XML (for example, to apply a drawable image 229to a widget), but you can also use a resource in XML any place that accepts a simple value. For 230example, if you have the following resource file that includes a <a 231href="more-resources.html#Color">color resource</a> and a <a 232href="string-resource.html">string resource</a>:</p> 233 234<pre> 235<?xml version="1.0" encoding="utf-8"?> 236<resources> 237 <color name="opaque_red">#f00</color> 238 <string name="hello">Hello!</string> 239</resources> 240</pre> 241 242<p>You can use these resources in the following layout file to set the text color and 243text string:</p> 244 245<pre> 246<?xml version="1.0" encoding="utf-8"?> 247<EditText xmlns:android="http://schemas.android.com/apk/res/android" 248 android:layout_width="fill_parent" 249 android:layout_height="fill_parent" 250 android:textColor="<strong>@color/opaque_red</strong>" 251 android:text="<strong>@string/hello</strong>" /> 252</pre> 253 254<p>In this case you don't need to specify the package name in the resource reference because the 255resources are from your own package. To 256reference a system resource, you would need to include the package name. For example:</p> 257 258<pre> 259<?xml version="1.0" encoding="utf-8"?> 260<EditText xmlns:android="http://schemas.android.com/apk/res/android" 261 android:layout_width="fill_parent" 262 android:layout_height="fill_parent" 263 android:textColor="<strong>@android:color/secondary_text_dark</strong>" 264 android:text="@string/hello" /> 265</pre> 266 267<p class="note"><strong>Note:</strong> You should use string resources at 268all times, so that your application can be localized for other languages. 269For information about creating alternative 270resources (such as localized strings), see <a 271href="providing-resources.html#AlternativeResources">Providing Alternative 272Resources</a>. For a complete guide to localizing your application for other languages, 273see <a href="localization.html">Localization</a>.</p> 274 275<p>You can even use resources in XML to create aliases. For example, you can create a 276drawable resource that is an alias for another drawable resource:</p> 277 278<pre> 279<?xml version="1.0" encoding="utf-8"?> 280<bitmap xmlns:android="http://schemas.android.com/apk/res/android" 281 android:src="@drawable/other_drawable" /> 282</pre> 283 284<p>This sounds redundant, but can be very useful when using alternative resource. Read more about 285<a href="providing-resources.html#AliasResources">Creating alias resources</a>.</p> 286 287 288 289<h3 id="ReferencesToThemeAttributes">Referencing style attributes</h3> 290 291<p>A style attribute resource allows you to reference the value 292of an attribute in the currently-applied theme. Referencing a style attribute allows you to 293customize the look of UI elements by styling them to match standard variations supplied by the 294current theme, instead of supplying a hard-coded value. Referencing a style attribute 295essentially says, "use the style that is defined by this attribute, in the current theme."</p> 296 297<p>To reference a style attribute, the name syntax is almost identical to the normal resource 298format, but instead of the at-symbol (<code>@</code>), use a question-mark ({@code ?}), and the 299resource type portion is optional. For instance:</p> 300 301<pre class="classic"> 302?[<em><package_name></em>:][<em><resource_type></em>/]<em><resource_name></em> 303</pre> 304 305<p>For example, here's how you can reference an attribute to set the text color to match the 306"primary" text color of the system theme:</p> 307 308<pre> 309<EditText id="text" 310 android:layout_width="fill_parent" 311 android:layout_height="wrap_content" 312 android:textColor="<strong>?android:textColorSecondary</strong>" 313 android:text="@string/hello_world" /> 314</pre> 315 316<p>Here, the {@code android:textColor} attribute specifies the name of a style attribute 317in the current theme. Android now uses the value applied to the {@code android:textColorSecondary} 318style attribute as the value for {@code android:textColor} in this widget. Because the system 319resource tool knows that an attribute resource is expected in this context, 320you do not need to explicitly state the type (which would be 321<code>?android:attr/textColorSecondary</code>)—you can exclude the {@code attr} type.</p> 322 323 324 325 326<h2 id="PlatformResources">Accessing Platform Resources</h2> 327 328<p>Android contains a number of standard resources, such as styles, themes, and layouts. To 329access these resource, qualify your resource reference with the 330<code>android</code> package name. For example, Android provides a layout resource you can use for 331list items in a {@link android.widget.ListAdapter}:</p> 332 333<pre> 334{@link android.app.ListActivity#setListAdapter(ListAdapter) 335setListAdapter}(new {@link 336android.widget.ArrayAdapter}<String>(this, <strong>android.R.layout.simple_list_item_1</strong>, myarray)); 337</pre> 338 339<p>In this example, {@link android.R.layout#simple_list_item_1} is a layout resource defined by the 340platform for items in a {@link android.widget.ListView}. You can use this instead of creating 341your own layout for list items. For more information, see the 342<a href="{@docRoot}guide/topics/ui/layout/listview.html">List View</a> developer guide.</p> 343 344
