resources-i18n.jd revision ff339f0b966c5ca62867689a13ea713e6cb62a15
1page.title=Resources and Internationalization 2parent.title=Resources and Assets 3parent.link=index.html 4@jd:body 5 6<div id="qv-wrapper"> 7<div id="qv"> 8 9 <h2>Key classes</h2> 10 <ol> 11 <li>{@link android.content.res.Resources}</li> 12 </ol> 13 14 <h2>In this document</h2> 15 <ol> 16 <li><a href="#intro">Introduction</a></li> 17 <li><a href="#CreatingResources">Creating Resources</a></li> 18 <li><a href="#UsingResources">Using Resources</a> 19 <ol> 20 <li><a href="#ResourcesInCode">Using Resources in Code</a></li> 21 <li><a href="#ReferencesToResources">References to Resources</a></li> 22 <li><a href="#ReferencesToThemeAttributes">References to Theme Attributes</a></li> 23 <li><a href="#UsingSystemResources">Using System Resources</a></li> 24 </ol> 25 </li> 26 <li><a href="#AlternateResources">Alternate Resources</a></li> 27 <li><a href="#ResourcesTerminology">Terminology</a></li> 28 <li><a href="#i18n">Internationalization (I18N)</a></li> 29 </ol> 30</div> 31</div> 32 33<p>Resources are external files (that is, non-code files) that are used by 34your code and compiled into your application at build time. Android 35supports a number of different kinds of resource files, including XML, 36PNG, and JPEG files. The XML files have very different formats depending 37on what they describe. This document describes what kinds of files are 38supported, and the syntax or format of each.</p> 39<p>Resources are externalized from source code, and XML files are compiled into 40a binary, fast loading format for efficiency reasons. Strings, likewise, are compressed 41into a more efficient storage form. It is for these reasons that we have these 42different resource types in the Android platform.</p> 43 44<p>This is a fairly technically dense document, and together with the 45<a href="available-resources.html">Available Resources</a> 46document, they cover a lot of information about resources. It is not necessary 47to know this document by heart to use Android, but rather to know that the 48information is here when you need it.</p> 49 50<a name="intro"></a> 51<h2>Introduction</h2> 52 53<p>This topic includes a terminology list associated with resources, and a series 54 of examples of using resources in code. For a complete guide to the supported 55 Android resource types, see 56 <a href="available-resources.html">Available Resources</a>. 57 </p> 58<p>The Android resource system keeps track of all non-code 59 assets associated with an application. You use the 60 {@link android.content.res.Resources Resources} class to access your 61 application's resources; the Resources instance associated with your 62 application can generally be found through 63 {@link android.content.Context#getResources Context.getResources()}.</p> 64<p>An application's resources are compiled into the application 65binary at build time for you by the build system. To use a resource, 66you must install it correctly in the source tree and build your 67application. As part of the build process, symbols for each 68of the resources are generated that you can use in your source 69code -- this allows the compiler to verify that your application code matches 70up with the resources you defined.</p> 71 72<p>The rest of this section is organized as a tutorial on how to 73use resources in an application.</p> 74 75<a name="CreatingResources" id="CreatingResources"></a> 76<h2>Creating Resources</h2> 77 78<p>Android supports string, bitmap, and many other types of resource. The syntax and format 79of each, and where they're stored, depends upon the type of object. In 80general, though, you create resources from three types of files: XML files 81(everything but bitmaps and raw), bitmap files(for images) and Raw files (anything 82else, for example sound files, etc.). In fact, there are two different types of 83XML file as well, those that get compiled as-is into the package, and those that 84are used to generate resources by aapt. Here is a list of each 85resource type, the format of the file, a description of the file, and details 86of any XML files. </p> 87 88<p>You will create and store your resource files under the appropriate 89subdirectory under the <code>res/</code> directory in your project. Android 90has a resource compiler (aapt) that compiles resources according to which 91subfolder they are in, and the format of the file. Table 1 shows a list of the file 92types for each resource. See the 93<a href="available-resources.html">Available Resources</a> for 94descriptions of each type of object, the syntax, and the format or syntax of 95the containing file.</p> 96<p class="caption">Table 1</p> 97<table width="100%" border="1"> 98 <tr> 99 <th scope="col">Directory</th> 100 <th scope="col">Resource Types </th> 101 </tr> 102 <tr> 103 <td><code>res/anim/</code></td> 104 <td>XML files that are compiled into 105 <a href="available-resources.html#animationdrawable">frame by 106 frame animation</a> or 107 <a href="available-resources.html#tweenedanimation">tweened 108 animation</a> objects </td> 109 </tr> 110 <tr> 111 <td><code>res/drawable/</code></td> 112 <td><p>.png, .9.png, .jpg files that are compiled into the following 113 Drawable resource subtypes:</p> 114 <ul class="nolist"> 115 <li><a href="available-resources.html#imagefileresources">bitmap files</a></li> 116 <li><a href="available-resources.html#ninepatch">9-patches (resizable bitmaps)</a></li> 117 </ul> 118 <p>To get a resource of this type, use <code>mContext.getResources().getDrawable(R.drawable.<em>imageId</em>)</code></p> 119 <p class="note"><strong>Note:</strong> Image resources placed in here may 120 be automatically optimized with lossless image compression by the 121 <a href="{@docRoot}guide/developing/tools/aapt.html">aapt</a> tool. For example, a true-color PNG 122 that does not require more than 256 colors may be converted to an 8-bit PNG with a color palette. 123 This will result in an image of equal quality but which requires less memory. So be aware that the 124 image binaries placed in this directory can change during the build. If you plan on reading 125 an image as a bit stream in order to convert it to a bitmap, put your images in the 126 <code>res/raw/</code> folder instead, where they will not be optimized.</p> 127 </td> 128 </tr> 129 <tr> 130 <td><code>res/layout/</code></td> 131 <td>XML files that are compiled into screen layouts (or part of a screen). 132 See <a href="{@docRoot}guide/topics/ui/declaring-layout.html">Declaring Layout</a>.</td> 133 </tr> 134 <tr> 135 <td><code>res/values/</code></td> 136 <td><p>XML files that can be compiled into many kinds of resource.</p> 137 <p class="note"><strong>Note:</strong> Unlike the other res/ folders, this one 138 can hold any number of files that hold descriptions of resources to create 139 rather than the resources themselves. The XML element types control 140 where these resources are placed under the R class.</p> 141 <p>While the files can be named anything, these are 142 the typical files in this folder (the convention is to name 143 the file after the type of elements defined within):</p> 144 <ul> 145 <li><strong>arrays.xml</strong> to define arrays </li> 146 <!-- TODO: add section on arrays --> 147 <li><strong>colors.xml</strong> to define <a href="available-resources.html#colordrawableresources">color 148 drawables</a> and <a href="#colorvals">color string values</a>. 149 Use <code>Resources.getDrawable()</code> and 150 <code>Resources.getColor(), respectively,</code> 151 to get these resources.</li> 152 <li><strong>dimens.xml</strong> to define <a href="available-resources.html#dimension">dimension value</a>. Use <code>Resources.getDimension()</code> to get 153 these resources.</li> 154 <li><strong>strings.xml</strong> to define <a href="available-resources.html#stringresources">string</a> values (use either 155 <code>Resources.getString</code> or preferably <code>Resources.getText()</code> 156 to get 157 these resources. <code>getText()</code> will retain any rich text styling 158 which is usually desirable for UI strings.</li> 159 <li><strong>styles.xml</strong> to define <a href="available-resources.html#stylesandthemes">style</a> objects.</li> 160 </ul></td> 161 </tr> 162 <tr> 163 <td><code>res/xml/</code></td> 164 <td>Arbitrary XML files that are compiled and can be read at run time by 165 calling {@link android.content.res.Resources#getXml(int) Resources.getXML()}.</td> 166 </tr> 167 <tr> 168 <td><code>res/raw/</code></td> 169 <td>Arbitrary files to copy directly to the device. They are added uncompiled 170 to the compressed file that your application build produces. To use these 171 resources in your application, call {@link android.content.res.Resources#openRawResource(int) 172 Resources.openRawResource()} with the resource ID, which is R.raw.<em>somefilename</em>.</td> 173 </tr> 174</table> 175<p>Resources are compiled into the final APK file. Android creates a wrapper class, 176 called R, that you can use to refer to these resources in your code. R contains subclasses 177 named according to the path and file name of the source file</p> 178<a name="colorvals" id="colorvals"></a> 179<h3>Global Resource Notes</h3> 180<ul> 181 <li>Several resources allow you to define colors. Android accepts color values 182 written in various web-style formats -- a hexadecimal constant in any of the 183 following forms: #RGB, #ARGB, #RRGGBB, #AARRGGBB. </li> 184 <li>All color values support setting an alpha channel value, where the first 185 two hexadecimal numbers specify the transparency. Zero in the alpha channel 186 means transparent. The default value is opaque. </li> 187</ul> 188<a name="UsingResources" id="UsingResources"></a> 189<h2>Using Resources </h2> 190<p>This section describes how to use the resources you've created. It includes the 191 following topics:</p> 192<ul> 193 <li><a href="#ResourcesInCode">Using resources in code</a> - How to call 194 resources in your code to instantiate them. </li> 195 <li><a href="#ReferencesToResources">Referring to resources from other resources</a> - 196 You can reference resources from other resources. This lets you reuse common 197 resource values inside resources. </li> 198 <li><a href="#AlternateResources">Supporting Alternate Resources for Alternate 199 Configurations</a> - You can specify different resources 200 to load, depending on the language or display configuration of the host 201 hardware. </li> 202</ul> 203<p>At compile time, Android generates a class named R that contains resource identifiers 204 to all the resources in your program. This class contains several subclasses, 205 one for each type of resource supported by Android, and for which you provided 206 a resource file. Each class contains one or more identifiers for the compiled resources, 207 that you use in your code to load the resource. Here is a small resource file 208 that contains string, layout (screens or parts of screens), and image resources.</p> 209<p class="note"><strong>Note:</strong> the R class is an auto-generated file and is not 210designed to be edited by hand. It will be automatically re-created as needed when 211the resources are updated.</p> 212<pre class="prettyprint">package com.android.samples; 213public final class R { 214 public static final class string { 215 public static final int greeting=0x0204000e; 216 public static final int start_button_text=0x02040001; 217 public static final int submit_button_text=0x02040008; 218 public static final int main_screen_title=0x0204000a; 219 }; 220 public static final class layout { 221 public static final int start_screen=0x02070000; 222 public static final int new_user_pane=0x02070001; 223 public static final int select_user_list=0x02070002; 224 225 }; 226 public static final class drawable { 227 public static final int company_logo=0x02020005; 228 public static final int smiling_cat=0x02020006; 229 public static final int yellow_fade_background=0x02020007; 230 public static final int stretch_button_1=0x02020008; 231 232 }; 233}; 234</pre> 235<a name="ResourcesInCode" id="ResourcesInCode"></a> 236<h3>Using Resources in Code </h3> 237 238<p>Using resources in code is just a matter of knowing the full resource ID 239and what type of object your resource has been compiled into. Here is the 240syntax for referring to a resource:</p> 241<p><code>R.<em>resource_type</em>.<em>resource_name</em></code></p> 242<p>or</p> 243<p><code>android.R.<em>resource_type</em>.<em>resource_name</em></code></p> 244 245<p>Where <code>resource_type</code> is the R subclass that holds a specific type 246of resource. <code>resource_name</code> is the <em>name</em> attribute for resources 247defined in XML files, or the file name (without the extension) for resources 248defined by other file types. Each type of resource will be added to a specific 249R subclass, depending on the type of resource it is; to learn which R subclass 250hosts your compiled resource type, consult the 251<a href="available-resources.html">Available Resources</a> document. Resources compiled by your own application can 252be referred to without a package name (simply as 253<code>R.<em>resource_type</em>.<em>resource_name</em></code>). Android contains 254a number of standard resources, such as screen styles and button backgrounds. To 255refer to these in code, you must qualify them with <code>android</code>, as in 256<code>android.R.drawable.button_background</code>.</p> 257 258<p>Here are some good and bad examples of using compiled resources in code:</p> 259 260<pre class="prettyprint">// Load a background for the current screen from a drawable resource. 261this.getWindow().setBackgroundDrawableResource(R.drawable.my_background_image); 262 263// WRONG Sending a string resource reference into a 264// method that expects a string. 265this.getWindow().setTitle(R.string.main_title); 266 267// RIGHT Need to get the title from the Resources wrapper. 268this.getWindow().setTitle(Resources.getText(R.string.main_title)); 269 270// Load a custom layout for the current screen. 271setContentView(R.layout.main_screen); 272 273// Set a slide in animation for a ViewFlipper object. 274mFlipper.setInAnimation(AnimationUtils.loadAnimation(this, 275 R.anim.hyperspace_in)); 276 277// Set the text on a TextView object. 278TextView msgTextView = (TextView)findViewByID(R.id.msg); 279msgTextView.setText(R.string.hello_message); </pre> 280 281<a name="ReferencesToResources" id="ReferencesToResources"></a> 282<h3>References to Resources</h3> 283 284<p>A value supplied in an attribute (or resource) can also be a reference to 285a resource. This is often used in layout files to supply strings (so they 286can be localized) and images (which exist in another file), though a reference 287can be any resource type including colors and integers.</p> 288 289<p>For example, if we have 290<a href="available-resources.html#colordrawableresources">color 291resources</a>, we can write a layout file that sets the text color size to be 292the value contained in one of those resources:</p> 293 294<pre> 295<?xml version="1.0" encoding="utf-8"?> 296<EditText id="text" 297 xmlns:android="http://schemas.android.com/apk/res/android" 298 android:layout_width="fill_parent" android:layout_height="fill_parent" 299 <strong>android:textColor="@color/opaque_red"</strong> 300 android:text="Hello, World!" /> 301</pre> 302 303<p>Note here the use of the '@' prefix to introduce a resource reference -- the 304text following that is the name of a resource in the form 305of <code>@[package:]type/name</code>. In this case we didn't need to specify 306the package because we are referencing a resource in our own package. To 307reference a system resource, you would need to write:</p> 308 309<pre> 310<?xml version="1.0" encoding="utf-8"?> 311<EditText id="text" 312 xmlns:android="http://schemas.android.com/apk/res/android" 313 android:layout_width="fill_parent" android:layout_height="fill_parent" 314 android:textColor="@<strong>android:</strong>color/opaque_red" 315 android:text="Hello, World!" /> 316</pre> 317 318<p>As another example, you should always use resource references when supplying 319strings in a layout file so that they can be localized:</p> 320 321<pre> 322<?xml version="1.0" encoding="utf-8"?> 323<EditText id="text" 324 xmlns:android="http://schemas.android.com/apk/res/android" 325 android:layout_width="fill_parent" android:layout_height="fill_parent" 326 android:textColor="@android:color/opaque_red" 327 android:text="@string/hello_world" /> 328</pre> 329 330<p>This facility can also be used to create references between resources. 331For example, we can create new drawable resources that are aliases for 332existing images:</p> 333 334<pre> 335<?xml version="1.0" encoding="utf-8"?> 336<resources> 337 <drawable id="my_background">@android:drawable/theme2_background</drawable> 338</resources> 339</pre> 340 341<a name="ReferencesToThemeAttributes"></a> 342<h3>References to Theme Attributes</h3> 343 344<p>Another kind of resource value allows you to reference the value of an 345attribute in the current theme. This attribute reference can <em>only</em> 346be used in style resources and XML attributes; it allows you to customize the 347look of UI elements by changing them to standard variations supplied by the 348current theme, instead of supplying more concrete values.</p> 349 350<p>As an example, we can use this in our layout to set the text color to 351one of the standard colors defined in the base system theme:</p> 352 353<pre> 354<?xml version="1.0" encoding="utf-8"?> 355<EditText id="text" 356 xmlns:android="http://schemas.android.com/apk/res/android" 357 android:layout_width="fill_parent" android:layout_height="fill_parent" 358 <strong>android:textColor="?android:textDisabledColor"</strong> 359 android:text="@string/hello_world" /> 360</pre> 361 362<p>Note that this is very similar to a resource reference, except we are using 363an '?' prefix instead of '@'. When you use this markup, you are supplying 364the name of an attribute resource that will be looked up in the theme -- 365because the resource tool knows that an attribute resource is expected, 366you do not need to explicitly state the type (which would be 367<code>?android:attr/android:textDisabledColor</code>).</p> 368 369<p>Other than using this resource identifier to find the value in the 370theme instead of raw resources, the name syntax is identical to the '@' format: 371<code>?[namespace:]type/name</code> with the type here being optional.</p> 372 373<a name="UsingSystemResources"></a> 374<h3>Using System Resources</h3> 375 376<p>Many resources included with the system are available to applications. 377All such resources are defined under the class "android.R". For example, 378you can display the standard application icon in a screen with the following 379code:</p> 380 381<pre class="prettyprint"> 382public class MyActivity extends Activity 383{ 384 public void onStart() 385 { 386 requestScreenFeatures(FEATURE_BADGE_IMAGE); 387 388 super.onStart(); 389 390 setBadgeResource(android.R.drawable.sym_def_app_icon); 391 } 392} 393</pre> 394 395<p>In a similar way, this code will apply to your screen the standard 396"green background" visual treatment defined by the system:</p> 397 398<pre class="prettyprint"> 399public class MyActivity extends Activity 400{ 401 public void onStart() 402 { 403 super.onStart(); 404 405 setTheme(android.R.style.Theme_Black); 406 } 407} 408</pre> 409 410<a name="AlternateResources" id="AlternateResources"></a> 411<h2>Alternate Resources (for alternate languages and configurations)</h2> 412 413<p>You can supply different resources for your application to use depending on the UI 414language or hardware configuration on the device. Note that although you can 415include different string, layout, and other resources, the SDK does not expose 416methods to let you specify which alternate resource set to load. Android 417detects the proper set for the hardware and location, and loads them as 418appropriate. Users can select alternate language settings using the settings 419panel on the device. </p> 420<p>To include alternate resources, create parallel resource folders with 421qualifiers appended to the folder names, indicating the configuration it 422applies to (language, screen orientation, and so on). For example, here is a 423project that holds one string resource file for English, and another for 424French:</p> 425 426<pre> 427MyApp/ 428 res/ 429 values-en/ 430 strings.xml 431 values-fr/ 432 strings.xml 433</pre> 434 435<p>Android supports several types of qualifiers, with various values for each. 436Append these to the end of the resource folder name, separated by dashes. You 437can add multiple qualifiers to each folder name, but they must appear in the 438order they are listed here. For example, a folder containing drawable 439resources for a fully specified configuration would look like this:</p> 440 441<pre> 442MyApp/ 443 res/ 444 drawable-en-rUS-port-160dpi-finger-keysexposed-qwerty-dpad-480x320/ 445</pre> 446 447<p>More typically, you will only specify a few specific configuration options. You may drop any of the values from the 448complete list, as long as the remaining values are still in the same 449order:</p> 450 451<pre> 452MyApp/ 453 res/ 454 drawable-en-rUS-finger/ 455 drawable-port/ 456 drawable-port-160dpi/ 457 drawable-qwerty/ 458</pre> 459<p>Table 2 lists the valid folder-name qualifiers, in order of precedence. Qualifiers that are listed higher in the table take precedence over those listed lower, as described in <a href="#best-match">How Android finds the best matching directory</a>. </p> 460<p class="caption" id="table2">Table 2</p> 461<table border="1"> 462 <tr> 463 <th> Qualifier </th> 464 <th> Values </th> 465 </tr> 466 <tr> 467 <td>MCC and MNC</td> 468 <td>The mobile country code and mobile network code from the SIM in the device. For example <code>mcc310-mnc004</code> (U.S., Verizon brand); <code>mcc208-mnc00</code> (France, Orange brand); <code>mcc234-mnc00</code> (U.K., BT brand). <br> 469 <br> 470 If the device uses a radio connection (GSM phone), the MCC will come from the SIM, and the MNC will come from the network to which the device is attached. You might sometimes use the MCC alone, for example to include country-specific legal resources in your application. If your application specifies resources for a MCC/MNC combination, those resources can only be used if both the MCC and the MNC match. </td> 471 </tr> 472 <tr> 473 <td>Language and region</td> 474 <td>The two letter <a href="http://www.loc.gov/standards/iso639-2/php/code_list.php">ISO 475 639-1</a> language code and two letter 476 <a href="http://www.iso.org/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html">ISO 477 3166-1-alpha-2</a> region code (preceded by lowercase "r"). For example 478 <code>en-rUS</code>, <code>fr-rFR</code>, <code>es-rES</code>. <br> 479 <br> 480 The codes are case-sensitive: The language code is lowercase, and the country code is uppercase. You cannot specify a region alone, but you can specify a language alone, for example <code>en</code>, <code>fr</code>, <code>es</code>. </td> 481 </tr> 482 <tr> 483 <td>Screen orientation</td> 484 <td><code>port</code>, <code>land</code>, <code>square</code> </td> 485 </tr> 486 <tr> 487 <td>Screen pixel density</td> 488 <td><code>92dpi</code>, <code>108dpi</code>, etc. When Android selects which resource files to use, it handles screen density differently than the other qualifiers. In step 1 of <a href="#best-match">How Android finds the best matching directory</a> (below), screen density is always considered to be a match. In step 4, if the qualifier being considered is screen density, Android will select the best final match at that point, without any need to move on to step 5. </td> 489 </tr> 490 <tr> 491 <td>Touchscreen type</td> 492 <td><code>notouch</code>, <code>stylus</code>, <code>finger</code></td> 493 </tr> 494 <tr> 495 <td>Whether the keyboard is available to the user</td> 496 <td><code>keysexposed</code>, <code>keyshidden</code>, <code>keyssoft</code> <br> 497 If your application has specific resources that should only be used with a soft keyboard, use the <code>keyssoft</code> value. If no <code>keyssoft</code> resources are available (only <code>keysexposed</code> and <code>keyshidden</code>) and the device shows a soft keyboard, the system will use <code>keysexposed</code> resources. </td> 498 </tr> 499 <tr> 500 <td>Primary text input method</td> 501 <td><code>nokeys</code>, <code>qwerty</code>, <code>12key</code> </td> 502 </tr> 503 <tr> 504 <td>Primary non-touchscreen<br /> 505 navigation method</td> 506 <td><code>nonav</code>, <code>dpad</code>, <code>trackball</code>, <code>wheel</code> </td> 507 </tr> 508 <tr> 509 <td>Screen dimensions</td> 510 <td><code>320x240</code>, <code>640x480</code>, etc. The larger dimension 511 must be specified first. </td> 512 </tr> 513 <tr> 514 <td>SDK version</td> 515 <td>The SDK version supported by the device, for example <code>v3</code>. The Android 1.0 SDK is <code>v1, </code> the 1.1 SDK is <code>v2</code>, and the 1.5 SDK is <code>v3</code>.</td> 516 </tr> 517 <tr> 518 <td>(Minor version)</td> 519 <td>(You cannot currently specify minor version. It is always set to 0.)</td> 520 </tr> 521</table> 522 523<p>This list does not include device-specific parameters such as carrier, 524branding, device/hardware, or manufacturer. Everything that an application 525needs to know about the device that it is running on is encoded via the 526resource qualifiers in the table above.</p> 527 528<p>All resource directories, qualified and unqualified, live under the <code>res/</code> folder. Here are some guidelines on qualified resource directory names:</p> 529 530<ul> 531 <li>You can specify multiple qualifiers, separated by dashes. For example, <code>drawable-en-rUS-land</code> will apply to US-English 532 devices in landscape orientation. </li> 533 <li>The qualifiers must be in the order listed in <a href="#table2">Table 2</a> above. For example: 534 <ul> 535 <li>Correct: <code>values-mcc460-nokeys/</code></li> 536 <li>Incorrect: <code>values-nokeys-mcc460/</code></li> 537 </ul> 538 </li> 539 <li>Values are case-sensitive. For example, a portrait-specific <code>drawable</code> directory must be named 540 <code>drawable-port</code>, not <code>drawable-PORT</code> or <code>drawable-Port</code>.</li> 541 <li>Only one value for each qualifier type is supported. For example, if you want to use exactly the same drawable files for Spain and France, you will need two resource directories, such as <code>drawable-rES/</code> and <code>drawable-rFR/</code>, containing identical files. You cannot 542 have a directory named <code>drawable-rES-rFR/</code>. </li> 543 <li>Qualified directories cannot be nested. For example, you cannot have <code>res/drawable/drawable-en</code>. </li> 544</ul> 545 546<h3>How resources are referenced in code</h3> 547<p>All resources will be referenced in code or resource reference syntax by 548 their simple, undecorated names. So if a resource were named this:<br /> 549 <code>MyApp/res/drawable-port-92dpi/myimage.png</code><br /> 550 It would be referenced as this:<br /> 551 <code>R.drawable.myimage</code> (code)<br /> 552 <code>@drawable/myimage</code> (XML)</p> 553<p>If several drawable directories are available, Android will select one of them (as described below) and load <code>myimage.png</code> from it.</p> 554<h3 id="best-match">How Android finds the best matching directory </h3> 555 556<p>Android will pick which of the various underlying resource files should be 557used at runtime, depending on the current configuration of the device. The example used here assumes the following device configuration:</p> 558<blockquote> 559 <p>Locale = <code>en-GB</code><br> 560 Screen orientation = <code>port</code><br> 561 Screen pixel density = <code>108dpi</code><br> 562 Touchscreen type = <code>notouch</code><br> 563 Primary text input method = <code>12key</code><br> 564 </p> 565</blockquote> 566<p>Here is how Android makes the selection: </p> 567<ol> 568 <li> 569 Eliminate resource files that contradict the 570 device configuration. For example, assume that the following resource directories are available for drawables. The <code>drawable-fr-rCA/</code> directory will be eliminated, because it contradicts the locale of the device.<br> 571<pre>MyApp/res/drawable/ 572MyApp/res/drawable-en/ 573<strike>MyApp/res/drawable-fr-rCA/</strike> 574MyApp/res/drawable-en-port/ 575MyApp/res/drawable-en-notouch-12key/ 576MyApp/res/drawable-port-92dpi/ 577MyApp/res/drawable-port-notouch-12key</pre> 578 <strong>Exception: </strong>Screen pixel density is the one qualifier that is not used to eliminate files. Even though the screen density of the device is 108 dpi, <code>drawable-port-92dpi/</code> is not eliminated from the list, because every screen density is considered to be a 579 match at this point.</li> 580 <li>From <a href="#table2">Table 2</a>, pick the highest-precedence qualifier that remains in the list. (Start with MCC, then move down through the list.) </li> 581 <li>Do any of the available resource directories include this qualifier? </li> 582 <ul> 583 <li>If No, return to step 2 and look at the next qualifier listed in Table 2. In our example, the answer is "no" until we reach Language.</li> 584 <li>If Yes, move on to step 4.</li> 585 </ul> 586 <li>Eliminate resource directories that do not include this qualifier. In our example, we eliminate all the directories that do not include a language qualifier. </li> 587 <pre><strike>MyApp/res/drawable/</strike> 588MyApp/res/drawable-en/ 589MyApp/res/drawable-en-port/ 590MyApp/res/drawable-en-notouch-12key/ 591<strike>MyApp/res/drawable-port-92dpi/</strike> 592<strike>MyApp/res/drawable-port-notouch-12key</strike></pre> 593 <strong>Exception:</strong> If the qualifier in question is screen pixel density, Android will select the option that most closely matches the device, and the selection process will be complete. In general, Android will prefer scaling down a larger original image to scaling up a smaller original image.<br><br></li> 594 595<li>Go back and repeat steps 2, 3, and 4 until only one choice remains. In the example, screen orientation is the next qualifier in the table for which we have any matches. 596 Eliminate resources that do not specify a screen orientation. </p> 597 <pre><strike>MyApp/res/drawable-en/</strike> 598MyApp/res/drawable-en-port/ 599<strike>MyApp/res/drawable-en-notouch-12key/</strike></pre> 600 Only one choice remains, so that's it. When drawables are called for in this example application, the Android system will load resources from the <code>MyApp/res/drawable-en-port/</code> directory. 601</ol> 602<p class="note"><strong>Tip:</strong> The <em>precedence</em> of the qualifiers is more important than the number of qualifiers that exactly match the device. For example, in step 4 above, the last choice on the list includes three qualifiers that exactly match the device (orientation, touchscreen type, and input method), while <code>drawable-en</code> has only one parameter that matches (language). However, language has a higher precedence, so <code>drawable-port-notouch-12key</code> is out.</p> 603<p>This flowchart summarizes how Android selects resource directories to load.</p> 604<p><img src="res-selection-flowchart.png" alt="resource-selection" width="461" height="471" style="margin:15px"></p> 605<h3>Terminology</h3> 606<p>The resource system brings a number of different pieces together to 607form the final complete resource functionality. To help understand the 608overall system, here are some brief definitions of the core concepts and 609components you will encounter in using it:</p> 610 611<p><strong>Asset</strong>: A single blob of data associated with an application. This 612includes object files compiled from the Java source code, graphics (such as PNG 613images), XML files, etc. These files are organized in a directory hierarchy 614that, during final packaging of the application, is bundled together into a 615single ZIP file.</p> 616 617<p><strong>aapt</strong>: Android Asset Packaging Tool. The tool that generates the 618final ZIP file of application assets. In addition to collecting raw assets 619together, it also parses resource definitions into binary asset data.</p> 620 621<p><strong>Resource Table</strong>: A special asset that aapt generates for you, 622describing all of the resources contained in an application/package. 623This file is accessed for you by the Resources class; it is not touched 624directly by applications.</p> 625 626<p><strong>Resource</strong>: An entry in the Resource Table describing a single 627named value. Broadly, there are two types of resources: primitives and 628bags.</p> 629 630<p><strong>Resource Identifier</strong>: In the Resource Table all resources are 631identified by a unique integer number. In source code (resource descriptions, 632XML files, Java source code) you can use symbolic names that stand as constants for 633the actual resource identifier integer.</p> 634 635<p><strong>Primitive Resource</strong>: All primitive resources can be written as a 636simple string, using formatting to describe a variety of primitive types 637included in the resource system: integers, colors, strings, references to 638other resources, etc. Complex resources, such as bitmaps and XML 639describes, are stored as a primitive string resource whose value is the path 640of the underlying Asset holding its actual data.</p> 641 642<p><strong>Bag Resource</strong>: A special kind of resource entry that, instead of a 643simple string, holds an arbitrary list of name/value pairs. Each name is 644itself a resource identifier, and each value can hold 645the same kinds of string formatted data as a normal resource. Bags also 646support inheritance: a bag can inherit the values from another bag, selectively 647replacing or extending them to generate its own contents.</p> 648 649<p><strong>Kind</strong>: The resource kind is a way to organize resource identifiers 650for various purposes. For example, drawable resources are used to 651instantiate Drawable objects, so their data is a primitive resource containing 652either a color constant or string path to a bitmap or XML asset. Other 653common resource kinds are string (localized string primitives), color 654(color primitives), layout (a string path to an XML asset describing a view 655layout), and style (a bag resource describing user interface attributes). 656There is also a standard "attr" resource kind, which defines the resource 657identifiers to be used for naming bag items and XML attributes</p> 658 659<p><strong>Style</strong>: The name of the resource kind containing bags that are used 660to supply a set of user interface attributes. For example, a TextView class may 661be given a style resource that defines its text size, color, and alignment. 662In a layout XML file, you associate a style with a bag using the "style" 663attribute, whose value is the name of the style resource.</p> 664 665<p><strong>Style Class</strong>: Specifies a related set of attribute resources. 666This data is not placed in the resource table itself, but used to generate 667constants in the source code that make it easier for you to retrieve values out of 668a style resource and/or XML tag's attributes. For example, the 669Android platform defines a "View" style class that 670contains all of the standard view attributes: padding, visibility, 671background, etc.; when View is inflated it uses this style class to 672retrieve those values from the XML file (at which point style and theme 673information is applied as approriate) and load them into its instance.</p> 674 675<p><strong>Configuration</strong>: For any particular resource identifier, there may be 676multiple different available values depending on the current configuration. 677The configuration includes the locale (language and country), screen 678orientation, etc. The current configuration is used to 679select which resource values are in effect when the resource table is 680loaded.</p> 681 682<p><strong>Theme</strong>: A standard style resource that supplies global 683attribute values for a particular context. For example, when writing an 684Activity the application developer can select a standard theme to use, such 685as the Theme.White or Theme.Black styles; this style supplies information 686such as the screen background image/color, default text color, button style, 687text editor style, text size, etc. When inflating a layout resource, most 688values for widgets (the text color, selector, background) if not explicitly 689set will come from the current theme; style and attribute 690values supplied in the layout can also assign their value from explicitly 691named values in the theme attributes if desired.</p> 692 693<p><strong>Overlay</strong>: A resource table that does not define a new set of resources, 694but instead replaces the values of resources that are in another resource table. 695Like a configuration, this is applied at load time 696to the resource data; it can add new configuration values (for example 697strings in a new locale), replace existing values (for example change 698the standard white background image to a "Hello Kitty" background image), 699and modify resource bags (for example change the font size of the Theme.White 700style to have an 18 pt font size). This is the facility that allows the 701user to select between different global appearances of their device, or 702download files with new appearances.</p> 703 704<h2>Resource Reference</h2> 705<p>The <a href="available-resources.html">Available Resources</a> 706document provides a detailed list of the various types of resource and how to use them 707from within the Java source code, or from other references.</p> 708 709<a name="i18n" id="i18n"></a> 710<h2>Internationalization and Localization</h2> 711<p class="note"><strong>Coming Soon:</strong> Internationalization and Localization are 712critical, but are also not quite ready yet in the current SDK. As the 713SDK matures, this section will contain information on the Internationalization 714and Localization features of the Android platform. In the meantime, it is a good 715idea to start by externalizing all strings, and practicing good structure in 716creating and using resources.</p> 717