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