1 page.title=Accessing Resources 2 parent.title=Application Resources 3 parent.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 {@code 13 @drawable/myimage}</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 46 href="providing-resources.html">Providing Resources</a>), you can apply it by 47 referencing its resource ID. All resource IDs are defined in your project's {@code R} class, which 48 the {@code aapt} tool automatically generates.</p> 49 50 <p>When your application is compiled, {@code aapt} generates the {@code R} class, which contains 51 resource IDs for all the resources in your {@code 52 res/} 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 54 integer (for example, {@code R.drawable.icon}). This integer is the resource ID that you can use 55 to retrieve your resource.</p> 56 57 <p>Although the {@code R} class is where resource IDs are specified, you should never need to 58 look 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 61 string}, {@code drawable}, and {@code layout}. For more about the different types, see <a 62 href="available-resources.html">Resource Types</a>. 63 </li> 64 <li>The <em>resource name</em>, which is either: the filename, 65 excluding the extension; or the value in the XML {@code android:name} attribute, if the 66 resource 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} 72 class, 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 75 Android 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 79 the 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 82 syntax in an XML resource any place where a value is expected that you provide in a resource. See <a 83 href="#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 92 example, you can set an {@link android.widget.ImageView} to use the {@code res/drawable/myimage.png} 93 resource using {@link android.widget.ImageView#setImageResource(int) setImageResource()}:</p> 94 <pre> 95 ImageView imageView = (ImageView) findViewById(R.id.myimageview); 96 imageView.setImageResource(<strong>R.drawable.myimage</strong>); 97 </pre> 98 99 <p>You can also retrieve individual resources using methods in {@link 100 android.content.res.Resources}, which you can get an instance of 101 with {@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 108 saving 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 112 ID, so you can't reference them through the {@code R} class or from XML resources. Instead, you can 113 query 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), 116 then save the file in the {@code res/raw/} directory and read a stream of bytes using {@link 117 android.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 133 required 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 136 without the extension or the {@code android:name} attribute value in the XML element (for simple 137 values).</li> 138 </ul> 139 <p>See <a href="available-resources.html">Resource Types</a> for 140 more 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 146 methods in {@link android.content.res.Resources}. You can get an instance of {@link 147 android.content.res.Resources} with {@link android.content.Context#getResources 148 Context.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 156 android.view.Window#setBackgroundDrawableResource(int) 157 setBackgroundDrawableResource}(<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) 162 setTitle}(getResources().{@link android.content.res.Resources#getText(int) 163 getText}(<strong>R.string.main_title</strong>)); 164 165 // Load a custom layout for the current screen 166 {@link android.app.Activity#setContentView(int) 167 setContentView}(<strong>R.layout.main_screen</strong>); 168 169 // Set a slide in animation by getting an Animation from the Resources object 170 mFlipper.{@link android.widget.ViewAnimator#setInAnimation(Animation) 171 setInAnimation}(AnimationUtils.loadAnimation(this, 172 <strong>R.anim.hyperspace_in</strong>)); 173 174 // Set the text on a TextView object using a resource ID 175 TextView msgTextView = (TextView) findViewById(<strong>R.id.msg</strong>); 176 msgTextView.{@link android.widget.TextView#setText(int) 177 setText}(<strong>R.string.hello_message</strong>); 178 </pre> 179 180 181 <p class="caution"><strong>Caution:</strong> You should never modify the {@code 182 R.java} file by hand—it is generated by the {@code aapt} tool when your project is 183 compiled. 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 190 reference to an existing resource. You will often do this when creating layout files, to 191 supply 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 194 a <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 214 required 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 218 without the extension or the {@code android:name} attribute value in the XML element (for simple 219 values).</li> 220 </ul> 221 222 <p>See <a href="available-resources.html">Resource Types</a> for 223 more 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 229 to a widget), but you can also use a resource in XML any place that accepts a simple value. For 230 example, if you have the following resource file that includes a <a 231 href="more-resources.html#Color">color resource</a> and a <a 232 href="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 243 text 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 255 resources are from your own package. To 256 reference 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 268 all times, so that your application can be localized for other languages. 269 For information about creating alternative 270 resources (such as localized strings), see <a 271 href="providing-resources.html#AlternativeResources">Providing Alternative 272 Resources</a>. For a complete guide to localizing your application for other languages, 273 see <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 276 drawable 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 292 of an attribute in the currently-applied theme. Referencing a style attribute allows you to 293 customize the look of UI elements by styling them to match standard variations supplied by the 294 current theme, instead of supplying a hard-coded value. Referencing a style attribute 295 essentially 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 298 format, but instead of the at-symbol ({@code @}), use a question-mark ({@code ?}), and the 299 resource 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 317 in the current theme. Android now uses the value applied to the {@code android:textColorSecondary} 318 style attribute as the value for {@code android:textColor} in this widget. Because the system 319 resource tool knows that an attribute resource is expected in this context, 320 you 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 329 access 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 331 list items in a {@link android.widget.ListAdapter}:</p> 332 333 <pre> 334 {@link android.app.ListActivity#setListAdapter(ListAdapter) 335 setListAdapter}(new {@link 336 android.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 340 platform for items in a {@link android.widget.ListView}. You can use this instead of creating 341 your 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
