providing-resources.jd revision db909162b2c26d12f56a7c0615977b83578c4acf
1page.title=Providing 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>Different types of resources belong in different subdirectories of {@code res/}</li> 11 <li>Alternative resources provide configuration-specific resource files</li> 12 <li>Always include default resources so your app does not depend on specific 13device configurations</li> 14 </ul> 15 <h2>In this document</h2> 16 <ol> 17 <li><a href="#ResourceTypes">Grouping Resource Types</a></li> 18 <li><a href="#AlternativeResources">Providing Alternative Resources</a> 19 <ol> 20 <li><a href="#QualifierRules">Qualifier name rules</a></li> 21 <li><a href="#AliasResources">Creating alias resources</a></li> 22 </ol> 23 </li> 24 <li><a href="#Compatibility">Providing the Best Device Compatibility with Resources</a> 25 <ol> 26 <li><a href="#ScreenCompatibility">Providing screen resource compatibility for Android 271.5</a></li> 28 </ol> 29 </li> 30 <li><a href="#BestMatch">How Android Finds the Best-matching Resource</a></li> 31 <li><a href="#KnownIssues">Known Issues</a></li> 32 </ol> 33 34 <h2>See also</h2> 35 <ol> 36 <li><a href="accessing-resources.html">Accessing Resources</a></li> 37 <li><a href="available-resources.html">Resource Types</a></li> 38 <li><a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple 39Screens</a></li> 40 </ol> 41</div> 42</div> 43 44<p>You should always externalize application resources such as images and strings from your 45code, so that you can maintain them independently. You should also provide alternative resources for 46specific device configurations, by grouping them in specially-named resource directories. At 47runtime, Android uses uses the appropriate resource based on the current configuration. For 48example, you might want to provide a different UI layout depending on the screen size or different 49strings depending on the language setting.</p> 50 51<p>Once you externalize your application resources, you can access them 52using resource IDs that are generated in your project's {@code R} class. How to use 53resources in your application is discussed in <a href="accessing-resources.html">Accessing 54Resources</a>. This document shows you how to group your resources in your Android project and 55provide alternative resources for specific device configurations.</p> 56 57 58<h2 id="ResourceTypes">Grouping Resource Types</h2> 59 60<p>You should place each type of resource in a specific subdirectory of your project's 61{@code res/} directory. For example, here's the file hierarchy for a simple project:</p> 62 63<pre class="classic no-pretty-print"> 64MyProject/ 65 src/ <span style="color:black"> 66 MyActivity.java </span> 67 res/ 68 drawable/ <span style="color:black"> 69 icon.png </span> 70 layout/ <span style="color:black"> 71 main.xml 72 info.xml</span> 73 values/ <span style="color:black"> 74 strings.xml </span> 75</pre> 76 77<p>As you can see in this example, the {@code res/} directory contains all the resources (in 78subdirectories): an image resource, two layout resources, and a string resource file. The resource 79directory names are important and are described in table 1.</p> 80 81<p class="table-caption" id="table1"><strong>Table 1.</strong> Resource directories 82supported inside project {@code res/} directory.</p> 83 84<table> 85 <tr> 86 <th scope="col">Directory</th> 87 <th scope="col">Resource Type</th> 88 </tr> 89 90 <tr> 91 <td><code>animator/</code></td> 92 <td>XML files that define <a href="{@docRoot}guide/topics/graphics/animation.html">property 93animations</a>.</td> 94 </tr> 95 96 <tr> 97 <td><code>anim/</code></td> 98 <td>XML files that define <a 99href="{@docRoot}guide/topics/graphics/view-animation.html#tween-animation">tween 100animations</a>. (Property animations can also be saved in this directory, but 101the {@code animator/} directory is preferred for property animations to distinguish between the two 102types.)</td> 103 </tr> 104 105 <tr> 106 <td><code>color/</code></td> 107 <td>XML files that define a state list of colors. See <a href="color-list-resource.html">Color 108State List Resource</a></td> 109 </tr> 110 111 <tr> 112 <td><code>drawable/</code></td> 113 <td><p>Bitmap files ({@code .png}, {@code .9.png}, {@code .jpg}, {@code .gif}) or XML files that 114are compiled into the following drawable resource subtypes:</p> 115 <ul> 116 <li>Bitmap files</li> 117 <li>Nine-Patches (re-sizable bitmaps)</li> 118 <li>State lists</li> 119 <li>Shapes</li> 120 <li>Animation drawables</li> 121 <li>Other drawables</li> 122 </ul> 123 <p>See <a href="drawable-resource.html">Drawable Resources</a>.</p> 124 </td> 125 </tr> 126 127 <tr> 128 <td><code>layout/</code></td> 129 <td>XML files that define a user interface layout. 130 See <a href="layout-resource.html">Layout Resource</a>.</td> 131 </tr> 132 133 <tr> 134 <td><code>menu/</code></td> 135 <td>XML files that define application menus, such as an Options Menu, Context Menu, or Sub 136Menu. See <a href="menu-resource.html">Menu Resource</a>.</td> 137 </tr> 138 139 <tr> 140 <td><code>raw/</code></td> 141 <td><p>Arbitrary files to save in their raw form. To open these resources with a raw 142{@link java.io.InputStream}, call {@link android.content.res.Resources#openRawResource(int) 143Resources.openRawResource()} with the resource ID, which is {@code R.raw.<em>filename</em>}.</p> 144 <p>However, if you need access to original file names and file hierarchy, you might consider 145saving some resources in the {@code 146assets/} directory (instead of {@code res/raw/}). Files in {@code assets/} are not given a 147resource ID, so you can read them only using {@link android.content.res.AssetManager}.</p></td> 148 </tr> 149 150 <tr> 151 <td><code>values/</code></td> 152 <td><p>XML files that contain simple values, such as strings, integers, and colors.</p> 153 <p>Whereas XML resource files in other {@code res/} subdirectories define a single resource 154based on the XML filename, files in the {@code values/} directory describe multiple resources. 155For a file in this directory, each child of the {@code <resources>} element defines a single 156resource. For example, a {@code <string>} element creates an 157{@code R.string} resource and a {@code <color>} element creates an {@code R.color} 158resource.</p> 159 <p>Because each resource is defined with its own XML element, you can name the file 160whatever you want and place different resource types in one file. However, for clarity, you might 161want to place unique resource types in different files. For example, here are some filename 162conventions for resources you can create in this directory:</p> 163 <ul> 164 <li>arrays.xml for resource arrays (<a 165href="more-resources.html#TypedArray">typed arrays</a>).</li> 166 <li>colors.xml for <a 167href="more-resources.html#Color">color values</a></li> 168 <li>dimens.xml for <a 169href="more-resources.html#Dimension">dimension values</a>.</li> 170 <li>strings.xml for <a href="string-resource.html">string 171values</a>.</li> 172 <li>styles.xml for <a href="style-resource.html">styles</a>.</li> 173 </ul> 174 <p>See <a href="string-resource.html">String Resources</a>, 175 <a href="style-resource.html">Style Resource</a>, and 176 <a href="more-resources.html">More Resource Types</a>.</p> 177 </td> 178 </tr> 179 180 <tr> 181 <td><code>xml/</code></td> 182 <td>Arbitrary XML files that can be read at runtime by calling {@link 183android.content.res.Resources#getXml(int) Resources.getXML()}. Various XML configuration files 184must be saved here, such as a <a 185href="{@docRoot}guide/topics/search/searchable-config.html">searchable configuration</a>. 186<!-- or preferences configuration. --></td> 187 </tr> 188</table> 189 190<p class="caution"><strong>Caution:</strong> Never save resource files directly inside the 191{@code res/} directory—it will cause a compiler error.</p> 192 193<p>For more information about certain types of resources, see the <a 194href="available-resources.html">Resource Types</a> documentation.</p> 195 196<p>The resources that you save in the subdirectories defined in table 1 are your "default" 197resources. That is, these resources define the default design and content for your application. 198However, different types of Android-powered devices might call for different types of resources. 199For example, if a device has a larger than normal screen, then you should provide 200different layout resources that take advantage of the extra screen space. Or, if a device has a 201different language setting, then you should provide different string resources that translate the 202text in your user interface. To provide these different resources for different device 203configurations, you need to provide alternative resources, in addition to your default 204resources.</p> 205 206 207<h2 id="AlternativeResources">Providing Alternative Resources</h2> 208 209 210<div class="figure" style="width:421px"> 211<img src="{@docRoot}images/resources/resource_devices_diagram2.png" height="137" alt="" /> 212<p class="img-caption"> 213<strong>Figure 1.</strong> Two different devices, one using alternative resources.</p> 214</div> 215 216<p>Almost every application should provide alternative resources to support specific device 217configurations. For instance, you should include alternative drawable resources for different 218screen densities and alternative string resources for different languages. At runtime, Android 219detects the current device configuration and loads the appropriate 220resources for your application.</p> 221 222<p>To specify configuration-specific alternatives for a set of resources:</p> 223<ol> 224 <li>Create a new directory in {@code res/} named in the form {@code 225<em><resources_name></em>-<em><config_qualifier></em>}. 226 <ul> 227 <li><em>{@code <resources_name>}</em> is the directory name of the corresponding default 228resources (defined in table 1).</li> 229 <li><em>{@code <qualifier>}</em> is a name that specifies an individual configuration 230for which these resources are to be used (defined in table 2).</li> 231 </ul> 232 <p>You can append more than one <em>{@code <qualifier>}</em>. Separate each 233one with a dash.</p> 234 </li> 235 <li>Save the respective alternative resources in this new directory. The resource files must be 236named exactly the same as the default resource files.</li> 237</ol> 238 239<p>For example, here are some default and alternative resources:</p> 240 241<pre class="classic no-pretty-print"> 242res/ 243 drawable/ <span style="color:black"> 244 icon.png 245 background.png </span> 246 drawable-hdpi/ <span style="color:black"> 247 icon.png 248 background.png </span> 249</pre> 250 251<p>The {@code hdpi} qualifier indicates that the resources in that directory are for devices with a 252high-density screen. The images in each of these drawable directories are sized for a specific 253screen density, but the filenames are exactly 254the same. This way, the resource ID that you use to reference the {@code icon.png} or {@code 255background.png} image is always the same, but Android selects the 256version of each resource that best matches the current device, by comparing the device 257configuration information with the qualifiers in the alternative resource directory name.</p> 258 259<p>Android supports several configuration qualifiers and you can 260add multiple qualifiers to one directory name, by separating each qualifier with a dash. Table 2 261lists the valid configuration qualifiers, in order of precedence—if you use multiple 262qualifiers for one resource directory, they must be added to the directory name in the order they 263are listed in the table.</p> 264 265<p class="note"><strong>Note:</strong> Some configuration qualifiers were added after Android 1.0, 266so not 267all versions of Android support all the qualifiers listed in table 2. New qualifiers 268indicate the version in which they were added. To avoid any issues, always include a set of default 269resources for resources that your application uses. For more information, see the section about <a 270href="#Compatibility">Providing the Best Device Compatibility with Resources</a>.</p> 271 272<p class="table-caption" id="table2"><strong>Table 2.</strong> Configuration qualifier 273names.</p> 274<table> 275 <tr> 276 <th>Configuration</th> 277 <th>Qualifier Values</th> 278 <th>Description</th> 279 </tr> 280 <tr id="MccQualifier"> 281 <td>MCC and MNC</td> 282 <td>Examples:<br/> 283 <code>mcc310</code><br/> 284 <code><nobr>mcc310-mnc004</nobr></code><br/> 285 <code>mcc208-mnc00</code><br/> 286 etc. 287 </td> 288 <td> 289 <p>The mobile country code (MCC), optionally followed by mobile network code (MNC) 290 from the SIM card in the device. For example, <code>mcc310</code> is U.S. on any carrier, 291 <code>mcc310-mnc004</code> is U.S. on Verizon, and <code>mcc208-mnc00</code> is France on 292 Orange.</p> 293 <p>If the device uses a radio connection (GSM phone), the MCC comes 294 from the SIM, and the MNC comes from the network to which the 295 device is connected.</p> 296 <p>You can also use the MCC alone (for example, to include country-specific legal 297resources in your application). If you need to specify based on the language only, then use the 298<em>language and region</em> qualifier instead (discussed next). If you decide to use the MCC and 299MNC qualifier, you should do so with care and test that it works as expected.</p> 300 <p>Also see the configuration fields {@link 301android.content.res.Configuration#mcc}, and {@link 302android.content.res.Configuration#mnc}, which indicate the current mobile country code 303and mobile network code, respectively.</p> 304 </td> 305 </tr> 306 <tr id="LocaleQualifier"> 307 <td>Language and region</td> 308 <td>Examples:<br/> 309 <code>en</code><br/> 310 <code>fr</code><br/> 311 <code>en-rUS</code><br/> 312 <code>fr-rFR</code><br/> 313 <code>fr-rCA</code><br/> 314 etc. 315 </td> 316 <td><p>The language is defined by a two-letter <a 317href="http://www.loc.gov/standards/iso639-2/php/code_list.php">ISO 318 639-1</a> language code, optionally followed by a two letter 319 <a 320href="http://www.iso.org/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html">ISO 321 3166-1-alpha-2</a> region code (preceded by lowercase "{@code r}"). 322 </p><p> 323 The codes are <em>not</em> case-sensitive; the {@code r} prefix is used to 324 distinguish the region portion. 325 You cannot specify a region alone.</p> 326 <p>This can change during the life 327of your application if the user changes his or her language in the system settings. See <a 328href="runtime-changes.html">Handling Runtime Changes</a> for information about 329how this can affect your application during runtime.</p> 330 <p>See <a href="localization.html">Localization</a> for a complete guide to localizing 331your application for other languages.</p> 332 <p>Also see the {@link android.content.res.Configuration#locale} configuration field, which 333indicates the current locale.</p> 334 </td> 335 </tr> 336 <tr id="SmallestScreenWidthQualifier"> 337 <td>Smallest available width</td> 338 <td><code>sw<N>dp</code><br/><br/> 339 Examples:<br/> 340 <code>sw320dp</code><br/> 341 <code>sw600dp</code><br/> 342 <code>sw720dp</code><br/> 343 etc. 344 </td> 345 <td> 346 <p>Specifies the "smallest width" in {@code dp} units that must be available to your 347 application in order for the resources to be used, regardless of the screen's current 348 orientation. For example, if your layout requires that its shortest side be at least 600 349 dp in length at all times, then you can use this to create the layout resources, {@code 350 res/layout-sw600dp/}, and the system will use them only when the shortest side of 351 available screen space it at least 600dp.</p> 352 <p>The width against which the system compares your value takes into account screen 353 decorations and system UI. For example, if the device has some persistent UI elements on the 354 left or right edge of the display, the system declares its own available width as one that 355 is smaller than the actual screen size, accounting for these UI elements because those are 356 screen pixels not available for your UI. Thus, the value you use should be the actual 357 smallest width required by your layout.</p> 358 <p>Some values you might use here for common screen sizes:</p> 359 <ul> 360 <li>320, for devices with screen configurations such as: 361 <ul> 362 <li>240x320 ldpi (QVGA handset)</li> 363 <li>320x480 mdpi (handset)</li> 364 <li>480x800 hdpi (high density handset)</li> 365 </ul> 366 </li> 367 <li>480, for screens such as 480x800 mdpi (tablet/handset).</li> 368 <li>600, for screens such as 600x1024 mdpi (7" tablet).</li> 369 <li>720, for screens such as 720x1280 mdpi (10" tablet).</li> 370 </ul> 371 <p>When your application provides multiple resource directories with different values for 372 this qualifier, the system uses the one closest to (without exceeding) the smallest width 373 for the available space. </p> 374 <p><em>Added in API level 13.</em></p> 375 <p>Also see the <a 376 href="{@docRoot}guide/topics/manifest/supports-screens-element.html#requiresSmallest">{@code 377 android:requiresSmallestWidthDp}</a> attribute, which declares the smallest available width 378 with which your application is compatible, and the {@link 379 android.content.res.Configuration#smallestScreenWidthDp} configuration field, which holds 380 the current smallest screen width for the device.</p> 381 </td> 382 </tr> 383 <tr id="ScreenWidthQualifier"> 384 <td>Available width</td> 385 <td><code>w<N>dp</code><br/><br/> 386 Examples:<br/> 387 <code>w720dp</code><br/> 388 <code>w1024dp</code><br/> 389 etc. 390 </td> 391 <td> 392 <p>Specifies a minimum available screen width, in {@code dp} units at which the resource 393 should be used—defined by the <code><N></code> value. This 394 configuration value will change when the orientation 395 changes between landscape and portrait to match the current actual width.</p> 396 <p>When your application provides multiple resource directories with different values 397 for this configuration, the system uses the one closest to (without exceeding) 398 the device's current screen width. The 399 value here takes into account screen decorations, so if the device has some 400 persistent UI elements on the left or right edge of the display, it 401 uses a value for the width that is smaller than the real screen size, accounting 402 for these UI elements and reducing the application's available space.</p> 403 <p><em>Added in API level 13.</em></p> 404 <p>Also see the {@link android.content.res.Configuration#screenWidthDp} 405 configuration field, which holds the current screen width.</p> 406 </td> 407 </tr> 408 <tr id="ScreenHeightQualifier"> 409 <td>Available height</td> 410 <td><code>h<N>dp</code><br/><br/> 411 Examples:<br/> 412 <code>h720dp</code><br/> 413 <code>h1024dp</code><br/> 414 etc. 415 </td> 416 <td> 417 <p>Specifies a minimum available screen height, in "dp" units at which the resource 418 should be used—defined by the <code><N></code> value. This 419 configuration value will change when the orientation 420 changes between landscape and portrait to match the current actual height.</p> 421 <p>When your application provides multiple resource directories with different values 422 for this configuration, the system uses the one closest to (without exceeding) 423 the device's current screen height. The 424 value here takes into account screen decorations, so if the device has some 425 persistent UI elements on the top or bottom edge of the display, it uses 426 a value for the height that is smaller than the real screen size, accounting 427 for these UI elements and reducing the application's available space. Screen 428 decorations that are not fixed (such as a phone status bar that can be 429 hidden when full screen) are <em>not</em> accounted for here, nor are 430 window decorations like the title bar or action bar, so applications must be prepared to 431 deal with a somewhat smaller space than they specify. 432 <p><em>Added in API level 13.</em></p> 433 <p>Also see the {@link android.content.res.Configuration#screenHeightDp} 434 configuration field, which holds the current screen width.</p> 435 </td> 436 </tr> 437 <tr id="ScreenSizeQualifier"> 438 <td>Screen size</td> 439 <td> 440 <code>small</code><br/> 441 <code>normal</code><br/> 442 <code>large</code><br/> 443 <code>xlarge</code> 444 </td> 445 <td> 446 <ul class="nolist"> 447 <li>{@code small}: Screens based on the space available on a 448 low-density QVGA screen. Considering a portrait HVGA display, this has 449 the same available width but less height—it is 3:4 vs. HVGA's 450 2:3 aspect ratio. The minimum layout size for this screen configuration 451 is approximately 320x426 dp units. Examples are QVGA low density and VGA high 452 density.</li> 453 <li>{@code normal}: Screens based on the traditional 454 medium-density HVGA screen. A screen is considered to be normal if it is 455 at least this size (independent of density) and not larger. The minimum 456 layout size for this screen configuration is approximately 320x470 dp units. Examples 457 of such screens a WQVGA low density, HVGA medium density, WVGA 458 high density.</li> 459 <li>{@code large}: Screens based on the space available on a 460 medium-density VGA screen. Such a screen has significantly more 461 available space in both width and height than an HVGA display. 462 The minimum layout size for this screen configuration is approximately 480x640 dp units. 463 Examples are VGA and WVGA medium density screens.</li> 464 <li>{@code xlarge}: Screens that are considerably larger than the traditional 465 medium-density HVGA screen. The minimum layout size for this screen configuration 466 is approximately 720x960 dp units. In most cases, devices with extra large 467 screens would be too large to carry in a pocket and would most likely 468 be tablet-style devices. <em>Added in API level 9.</em></li> 469 </ul> 470 <p><em>Added in API level 4.</em></p> 471 <p>See <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple 472Screens</a> for more information.</p> 473 <p>Also see the {@link android.content.res.Configuration#screenLayout} configuration field, 474which indicates whether the screen is small, normal, 475or large.</p> 476 </td> 477 </tr> 478 <tr id="ScreenAspectQualifier"> 479 <td>Screen aspect</td> 480 <td> 481 <code>long</code><br/> 482 <code>notlong</code> 483 </td> 484 <td> 485 <ul class="nolist"> 486 <li>{@code long}: Long screens, such as WQVGA, WVGA, FWVGA</li> 487 <li>{@code notlong}: Not long screens, such as QVGA, HVGA, and VGA</li> 488 </ul> 489 <p><em>Added in API level 4.</em></p> 490 <p>This is based purely on the aspect ratio of the screen (a "long" screen is wider). This 491is not related to the screen orientation.</p> 492 <p>Also see the {@link android.content.res.Configuration#screenLayout} configuration field, 493which indicates whether the screen is long.</p> 494 </td> 495 </tr> 496 <tr id="OrientationQualifier"> 497 <td>Screen orientation</td> 498 <td> 499 <code>port</code><br/> 500 <code>land</code> <!-- <br/> 501 <code>square</code> --> 502 </td> 503 <td> 504 <ul class="nolist"> 505 <li>{@code port}: Device is in portrait orientation (vertical)</li> 506 <li>{@code land}: Device is in landscape orientation (horizontal)</li> 507 <!-- Square mode is currently not used. --> 508 </ul> 509 <p>This can change during the life of your application if the user rotates the 510screen. See <a href="runtime-changes.html">Handling Runtime Changes</a> for information about 511how this affects your application during runtime.</p> 512 <p>Also see the {@link android.content.res.Configuration#orientation} configuration field, 513which indicates the current device orientation.</p> 514 </td> 515 </tr> 516 <tr id="DockQualifier"> 517 <td>Dock mode</td> 518 <td> 519 <code>car</code><br/> 520 <code>desk</code> 521 </td> 522 <td> 523 <ul class="nolist"> 524 <li>{@code car}: Device is in a car dock</li> 525 <li>{@code desk}: Device is in a desk dock</li> 526 </ul> 527 <p><em>Added in API level 8.</em></p> 528 <p>This can change during the life of your application if the user places the device in a 529dock. You can enable or disable this mode using {@link 530android.app.UiModeManager}. See <a href="runtime-changes.html">Handling Runtime Changes</a> for 531information about how this affects your application during runtime.</p> 532 </td> 533 </tr> 534 <tr id="NightQualifier"> 535 <td>Night mode</td> 536 <td> 537 <code>night</code><br/> 538 <code>notnight</code> 539 </td> 540 <td> 541 <ul class="nolist"> 542 <li>{@code night}: Night time</li> 543 <li>{@code notnight}: Day time</li> 544 </ul> 545 <p><em>Added in API level 8.</em></p> 546 <p>This can change during the life of your application if night mode is left in 547auto mode (default), in which case the mode changes based on the time of day. You can enable 548or disable this mode using {@link android.app.UiModeManager}. See <a 549href="runtime-changes.html">Handling Runtime Changes</a> for information about how this affects your 550application during runtime.</p> 551 </td> 552 </tr> 553 <tr id="DensityQualifier"> 554 <td>Screen pixel density (dpi)</td> 555 <td> 556 <code>ldpi</code><br/> 557 <code>mdpi</code><br/> 558 <code>hdpi</code><br/> 559 <code>xhdpi</code><br/> 560 <code>nodpi</code> 561 </td> 562 <td> 563 <ul class="nolist"> 564 <li>{@code ldpi}: Low-density screens; approximately 120dpi.</li> 565 <li>{@code mdpi}: Medium-density (on traditional HVGA) screens; approximately 566160dpi.</li> 567 <li>{@code hdpi}: High-density screens; approximately 240dpi.</li> 568 <li>{@code xhdpi}: Extra high-density screens; approximately 320dpi. <em>Added in API 569Level 8</em></li> 570 <li>{@code nodpi}: This can be used for bitmap resources that you do not want to be scaled 571to match the device density.</li> 572 </ul> 573 <p><em>Added in API level 4.</em></p> 574 <p>There is thus a 3:4:6:8 scaling ratio between the four densities, so a 9x9 bitmap 575 in ldpi is 12x12 in mdpi, 18x18 in hdpi and 24x24 in xhdpi.</p> 576 <p>When Android selects which resource files to use, 577 it handles screen density differently than the other qualifiers. 578 In step 1 of <a href="#BestMatch">How Android finds the best 579 matching directory</a> (below), screen density is always considered to 580 be a match. In step 4, if the qualifier being considered is screen 581 density, Android selects the best final match at that point, 582 without any need to move on to step 5. 583 </p> 584 <p>See <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple 585Screens</a> for more information about how to handle screen sizes and how Android might scale 586your bitmaps.</p> 587 </td> 588 </tr> 589 <tr id="TouchscreenQualifier"> 590 <td>Touchscreen type</td> 591 <td> 592 <code>notouch</code><br/> 593 <code>stylus</code><br/> 594 <code>finger</code> 595 </td> 596 <td> 597 <ul class="nolist"> 598 <li>{@code notouch}: Device does not have a touchscreen.</li> 599 <li>{@code stylus}: Device has a resistive touchscreen that's suited for use with a 600stylus.</li> 601 <li>{@code finger}: Device has a touchscreen.</li> 602 </ul> 603 <p>Also see the {@link android.content.res.Configuration#touchscreen} configuration field, 604which indicates the type of touchscreen on the device.</p> 605 </td> 606 </tr> 607 <tr id="KeyboardAvailQualifier"> 608 <td>Keyboard availability</td> 609 <td> 610 <code>keysexposed</code><br/> 611 <code>keyshidden</code><br/> 612 <code>keyssoft</code> 613 </td> 614 <td> 615 <ul class="nolist"> 616 <li>{@code keysexposed}: Device has a keyboard available. If the device has a 617software keyboard enabled (which is likely), this may be used even when the hardware keyboard is 618<em>not</em> exposed to the user, even if the device has no hardware keyboard. If no software 619keyboard is provided or it's disabled, then this is only used when a hardware keyboard is 620exposed.</li> 621 <li>{@code keyshidden}: Device has a hardware keyboard available but it is 622hidden <em>and</em> the device does <em>not</em> have a software keyboard enabled.</li> 623 <li>{@code keyssoft}: Device has a software keyboard enabled, whether it's 624visible or not.</li> 625 </ul> 626 <p>If you provide <code>keysexposed</code> resources, but not <code>keyssoft</code> 627resources, the system uses the <code>keysexposed</code> resources regardless of whether a 628keyboard is visible, as long as the system has a software keyboard enabled.</p> 629 <p>This can change during the life of your application if the user opens a hardware 630keyboard. See <a href="runtime-changes.html">Handling Runtime Changes</a> for information about how 631this affects your application during runtime.</p> 632 <p>Also see the configuration fields {@link 633android.content.res.Configuration#hardKeyboardHidden} and {@link 634android.content.res.Configuration#keyboardHidden}, which indicate the visibility of a hardware 635keyboard and and the visibility of any kind of keyboard (including software), respectively.</p> 636 </td> 637 </tr> 638 <tr id="ImeQualifier"> 639 <td>Primary text input method</td> 640 <td> 641 <code>nokeys</code><br/> 642 <code>qwerty</code><br/> 643 <code>12key</code> 644 </td> 645 <td> 646 <ul class="nolist"> 647 <li>{@code nokeys}: Device has no hardware keys for text input.</li> 648 <li>{@code qwerty}: Device has a hardware qwerty keyboard, whether it's visible to the 649user 650or not.</li> 651 <li>{@code 12key}: Device has a hardware 12-key keyboard, whether it's visible to the user 652or not.</li> 653 </ul> 654 <p>Also see the {@link android.content.res.Configuration#keyboard} configuration field, 655which indicates the primary text input method available.</p> 656 </td> 657 </tr> 658 <tr id="NavAvailQualifier"> 659 <td>Navigation key availability</td> 660 <td> 661 <code>navexposed</code><br/> 662 <code>navhidden</code> 663 </td> 664 <td> 665 <ul class="nolist"> 666 <li>{@code navexposed}: Navigation keys are available to the user.</li> 667 <li>{@code navhidden}: Navigation keys are not available (such as behind a closed 668lid).</li> 669 </ul> 670 <p>This can change during the life of your application if the user reveals the navigation 671keys. See <a href="runtime-changes.html">Handling Runtime Changes</a> for 672information about how this affects your application during runtime.</p> 673 <p>Also see the {@link android.content.res.Configuration#navigationHidden} configuration 674field, which indicates whether navigation keys are hidden.</p> 675 </td> 676 </tr> 677 <tr id="TouchQualifier"> 678 <td>Primary non-touch navigation method</td> 679 <td> 680 <code>nonav</code><br/> 681 <code>dpad</code><br/> 682 <code>trackball</code><br/> 683 <code>wheel</code> 684 </td> 685 <td> 686 <ul class="nolist"> 687 <li>{@code nonav}: Device has no navigation facility other than using the 688touchscreen.</li> 689 <li>{@code dpad}: Device has a directional-pad (d-pad) for navigation.</li> 690 <li>{@code trackball}: Device has a trackball for navigation.</li> 691 <li>{@code wheel}: Device has a directional wheel(s) for navigation (uncommon).</li> 692 </ul> 693 <p>Also see the {@link android.content.res.Configuration#navigation} configuration field, 694which indicates the type of navigation method available.</p> 695 </td> 696 </tr> 697<!-- DEPRECATED 698 <tr> 699 <td>Screen dimensions</td> 700 <td>Examples:<br/> 701 <code>320x240</code><br/> 702 <code>640x480</code><br/> 703 etc. 704 </td> 705 <td> 706 <p>The larger dimension must be specified first. <strong>This configuration is deprecated 707and should not be used</strong>. Instead use "screen size," "wider/taller screens," and "screen 708orientation" described above.</p> 709 </td> 710 </tr> 711--> 712 <tr id="VersionQualifier"> 713 <td>Platform Version (API level)</td> 714 <td>Examples:<br/> 715 <code>v3</code><br/> 716 <code>v4</code><br/> 717 <code>v7</code><br/> 718 etc.</td> 719 <td> 720 <p>The API level supported by the device. For example, <code>v1</code> for API level 7211 (devices with Android 1.0 or higher) and <code>v4</code> for API level 4 (devices with Android 7221.6 or higher). See the <a 723href="{@docRoot}guide/appendix/api-levels.html">Android API levels</a> document for more information 724about these values.</p> 725 <p class="caution"><strong>Caution:</strong> Android 1.5 and 1.6 only match resources 726with this qualifier when it exactly matches the platform version. See the section below about <a 727href="#KnownIssues">Known Issues</a> for more information.</p> 728 </td> 729 </tr> 730</table> 731 732 733<h3 id="QualifierRules">Qualifier name rules</h3> 734 735<p>Here are some rules about using configuration qualifier names:</p> 736 737<ul> 738 <li>You can specify multiple qualifiers for a single set of resources, separated by dashes. For 739example, <code>drawable-en-rUS-land</code> applies to US-English devices in landscape 740orientation.</li> 741 <li>The qualifiers must be in the order listed in <a href="#table2">table 2</a>. For 742example: 743 <ul> 744 <li>Wrong: <code>drawable-hdpi-port/</code></li> 745 <li>Correct: <code>drawable-port-hdpi/</code></li> 746 </ul> 747 </li> 748 <li>Alternative resource directories cannot be nested. For example, you cannot have 749<code>res/drawable/drawable-en/</code>.</li> 750 <li>Values are case-insensitive. The resource compiler converts directory names 751 to lower case before processing to avoid problems on case-insensitive 752 file systems. Any capitalization in the names is only to benefit readability.</li> 753 <li>Only one value for each qualifier type is supported. For example, if you want to use 754the same drawable files for Spain and France, you <em>cannot</em> have a directory named 755<code>drawable-rES-rFR/</code>. Instead you need two resource directories, such as 756<code>drawable-rES/</code> and <code>drawable-rFR/</code>, which contain the appropriate files. 757However, you are not required to actually duplicate the same files in both locations. Instead, you 758can create an alias to a resource. See <a href="#AliasResources">Creating 759alias resources</a> below.</li> 760</ul> 761 762<p>After you save alternative resources into directories named with 763these qualifiers, Android automatically applies the resources in your application based on the 764current device configuration. Each time a resource is requested, Android checks for alternative 765resource directories that contain the requested resource file, then <a href="#BestMatch">finds the 766best-matching resource</a> (discussed below). If there are no alternative resources that match 767a particular device configuration, then Android uses the corresponding default resources (the 768set of resources for a particular resource type that does not include a configuration 769qualifier).</p> 770 771 772 773<h3 id="AliasResources">Creating alias resources</h3> 774 775<p>When you have a resource that you'd like to use for more than one device 776configuration (but do not want to provide as a default resource), you do not need to put the same 777resource in more than one alternative resource directory. Instead, you can (in some cases) create an 778alternative 779resource that acts as an alias for a resource saved in your default resource directory.</p> 780 781<p class="note"><strong>Note:</strong> Not all resources offer a mechanism by which you can 782create an alias to another resource. In particular, animation, menu, raw, and other unspecified 783resources in the {@code xml/} directory do not offer this feature.</p> 784 785<p>For example, imagine you have an application icon, {@code icon.png}, and need unique version of 786it for different locales. However, two locales, English-Canadian and French-Canadian, need to 787use the same version. You might assume that you need to copy the same image 788into the resource directory for both English-Canadian and French-Canadian, but it's 789not true. Instead, you can save the image that's used for both as {@code icon_ca.png} (any 790name other than {@code icon.png}) and put 791it in the default {@code res/drawable/} directory. Then create an {@code icon.xml} file in {@code 792res/drawable-en-rCA/} and {@code res/drawable-fr-rCA/} that refers to the {@code icon_ca.png} 793resource using the {@code <bitmap>} element. This allows you to store just one version of the 794PNG file and two small XML files that point to it. (An example XML file is shown below.)</p> 795 796 797<h4>Drawable</h4> 798 799<p>To create an alias to an existing drawable, use the {@code <bitmap>} element. 800For example:</p> 801 802<pre> 803<?xml version="1.0" encoding="utf-8"?> 804<bitmap xmlns:android="http://schemas.android.com/apk/res/android" 805 android:src="@drawable/icon_ca" /> 806</pre> 807 808<p>If you save this file as {@code icon.xml} (in an alternative resource directory, such as 809{@code res/drawable-en-rCA/}), it is compiled into a resource that you 810can reference as {@code R.drawable.icon}, but is actually an alias for the {@code 811R.drawable.icon_ca} resource (which is saved in {@code res/drawable/}).</p> 812 813 814<h4>Layout</h4> 815 816<p>To create an alias to an existing layout, use the {@code <include>} 817element, wrapped in a {@code <merge>}. For example:</p> 818 819<pre> 820<?xml version="1.0" encoding="utf-8"?> 821<merge> 822 <include layout="@layout/main_ltr"/> 823</merge> 824</pre> 825 826<p>If you save this file as {@code main.xml}, it is compiled into a resource you can reference 827as {@code R.layout.main}, but is actually an alias for the {@code R.layout.main_ltr} 828resource.</p> 829 830 831<h4>Strings and other simple values</h4> 832 833<p>To create an alias to an existing string, simply use the resource ID of the desired 834string as the value for the new string. For example:</p> 835 836<pre> 837<?xml version="1.0" encoding="utf-8"?> 838<resources> 839 <string name="hello">Hello</string> 840 <string name="hi">@string/hello</string> 841</resources> 842</pre> 843 844<p>The {@code R.string.hi} resource is now an alias for the {@code R.string.hello}.</p> 845 846<p> <a href="{@docRoot}guide/topics/resources/more-resources.html">Other simple values</a> work the 847same way. For example, a color:</p> 848 849<pre> 850<?xml version="1.0" encoding="utf-8"?> 851<resources> 852 <color name="yellow">#f00</color> 853 <color name="highlight">@color/red</color> 854</resources> 855</pre> 856 857 858 859 860<h2 id="Compatibility">Providing the Best Device Compatibility with Resources</h2> 861 862<p>In order for your application to support multiple device configurations, it's very important that 863you always provide default resources for each type of resource that your application uses.</p> 864 865<p>For example, if your application supports several languages, always include a {@code 866values/} directory (in which your strings are saved) <em>without</em> a <a 867href="#LocaleQualifier">language and region qualifier</a>. If you instead put all your string files 868in directories that have a language and region qualifier, then your application will crash when run 869on a device set to a language that your strings do not support. But, as long as you provide default 870{@code values/} resources, then your application will run properly (even if the user doesn't 871understand that language—it's better than crashing).</p> 872 873<p>Likewise, if you provide different layout resources based on the screen orientation, you should 874pick one orientation as your default. For example, instead of providing layout resources in {@code 875layout-land/} for landscape and {@code layout-port/} for portrait, leave one as the default, such as 876{@code layout/} for landscape and {@code layout-port/} for portrait.</p> 877 878<p>Providing default resources is important not only because your application might run on a 879configuration you had not anticipated, but also because new versions of Android sometimes add 880configuration qualifiers that older versions do not support. If you use a new resource qualifier, 881but maintain code compatibility with older versions of Android, then when an older version of 882Android runs your application, it will crash if you do not provide default resources, because it 883cannot use the resources named with the new qualifier. For example, if your <a 884href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code 885minSdkVersion}</a> is set to 4, and you qualify all of your drawable resources using <a 886href="#NightQualifier">night mode</a> ({@code night} or {@code notnight}, which were added in API 887Level 8), then an API level 4 device cannot access your drawable resources and will crash. In this 888case, you probably want {@code notnight} to be your default resources, so you should exclude that 889qualifier so your drawable resources are in either {@code drawable/} or {@code drawable-night/}.</p> 890 891<p>So, in order to provide the best device compatibility, always provide default 892resources for the resources your application needs to perform properly. Then create alternative 893resources for specific device configurations using the configuration qualifiers.</p> 894 895<p>There is one exception to this rule: If your application's <a 896href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> is 4 or 897greater, you <em>do not</em> need default drawable resources when you provide alternative drawable 898resources with the <a href="#DensityQualifier">screen density</a> qualifier. Even without default 899drawable resources, Android can find the best match among the alternative screen densities and scale 900the bitmaps as necessary. However, for the best experience on all types of devices, you should 901provide alternative drawables for all three types of density. If your <a 902href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> is 903<em>less than</em> 4 (Android 1.5 or lower), be aware that the screen size, density, and aspect 904qualifiers are not supported on Android 1.5 or lower, so you might need to perform additional 905compatibility for these versions.</p> 906 907 908<h3 id="ScreenCompatibility">Providing screen resource compatibility for Android 1.5</h3> 909 910<p>Android 1.5 (and lower) does not support the following configuration qualifers:</p> 911<dl> 912 <dt><a href="#DensityQualifier">Density</a></dt> 913 <dd>{@code ldpi}, {@code mdpi}, {@code ldpi}, and {@code nodpi}</dd> 914 <dt><a href="#ScreenSizeQualifier">Screen size</a></dt> 915 <dd>{@code small}, {@code normal}, and {@code large}</dd> 916 <dt><a href="#ScreenAspectQualifier">Screen aspect</a></dt> 917 <dd>{@code long} and {@code notlong}</dd> 918</dl> 919 920<p>These configuration qualifiers were introduced in Android 1.6, so Android 1.5 (API level 3) and 921lower does not support them. If you use these configuration qualifiers and do not provide 922corresponding default resources, then an Android 1.5 device might use any one of the resource 923directories named with the above screen configuration qualifiers, because it ignores these 924qualifiers and uses whichever otherwise-matching drawable resource it finds first.</p> 925 926<p>For example, if your application supports Android 1.5 and includes drawable resources for 927each density type ({@code drawable-ldpi/}, {@code drawable-mdpi/}, and {@code drawable-ldpi/}), 928and does <em>not</em> include default drawable resources ({@code drawable/}), then 929an Android 1.5 will use drawables from any one of the alternative resource directories, which 930can result in a user interface that's less than ideal.<p> 931 932<p>So, to provide compatibility with Android 1.5 (and lower) when using the screen configuration 933qualifiers:</p> 934<ol> 935 <li>Provide default resources that are for medium-density, normal, and notlong screens. 936 937 <p>Because all Android 1.5 devices have medium-density, normal, not-long screens, you can 938place these kinds of resources in the corresponding default resource directory. For example, put all 939medium density drawable resources in {@code drawable/} (instead of {@code drawable-mdpi/}), 940put {@code normal} size resources in the corresponding default resource directory, and {@code 941notlong} resources in the corresponding default resource directory.</p> 942 </li> 943 944 <li>Ensure that your <a href="{@docRoot}sdk/tools-notes.html">SDK Tools</a> version 945is r6 or greater. 946 947 <p>You need SDK Tools, Revision 6 (or greater), because it includes a new packaging tool that 948automatically applies an appropriate <a href="#VersionQualifier">version qualifier</a> to any 949resource directory named with a qualifier that does not exist in Android 1.0. For example, because 950the density qualifier was introduced in Android 1.6 (API level 4), when the packaging tool 951encounters a resource directory using the density qualifier, it adds {@code v4} to the directory 952name to ensure that older versions do not use those resources (only API level 4 and higher support 953that qualifier). Thus, by putting your medium-density resources in a directory <em>without</em> the 954{@code mdpi} qualifier, they are still accessible by Android 1.5, and any device that supports the 955density qualifer and has a medium-density screen also uses the default resources (which are mdpi) 956because they are the best match for the device (instead of using the {@code ldpi} or {@code hdpi} 957resources).</p> 958</li> 959</ol> 960 961<p class="note"><strong>Note:</strong> Later versions of Android, such as API level 8, 962introduce other configuration qualifiers that older version do not support. To provide the best 963compatibility, you should always include a set of default resources for each type of resource 964that your application uses, as discussed above to provide the best device compatibility.</p> 965 966 967 968<h2 id="BestMatch">How Android Finds the Best-matching Resource</h2> 969 970<p>When you request a resource for which you provide alternatives, Android selects which 971alternative resource to use at runtime, depending on the current device configuration. To 972demonstrate how Android selects an alternative resource, assume the following drawable directories 973each contain different versions of the same images:</p> 974 975<pre class="classic no-pretty-print"> 976drawable/ 977drawable-en/ 978drawable-fr-rCA/ 979drawable-en-port/ 980drawable-en-notouch-12key/ 981drawable-port-ldpi/ 982drawable-port-notouch-12key/ 983</pre> 984 985<p>And assume the following is the device configuration:</p> 986 987<p style="margin-left:1em;"> 988Locale = <code>en-GB</code> <br/> 989Screen orientation = <code>port</code> <br/> 990Screen pixel density = <code>hdpi</code> <br/> 991Touchscreen type = <code>notouch</code> <br/> 992Primary text input method = <code>12key</code> 993</p> 994 995<p>By comparing the device configuration to the available alternative resources, Android selects 996drawables from {@code drawable-en-port}. It arrives at this decision using the following logic:</p> 997 998 999<div class="figure" style="width:280px"> 1000<img src="{@docRoot}images/resources/res-selection-flowchart.png" alt="" height="590" /> 1001<p class="img-caption"><strong>Figure 2.</strong> Flowchart of how Android finds the 1002best-matching resource.</p> 1003</div> 1004 1005 1006<ol> 1007 <li>Eliminate resource files that contradict the device configuration. 1008 <p>The <code>drawable-fr-rCA/</code> directory is eliminated, because it 1009contradicts the <code>en-GB</code> locale.</p> 1010<pre class="classic no-pretty-print"> 1011drawable/ 1012drawable-en/ 1013<strike>drawable-fr-rCA/</strike> 1014drawable-en-port/ 1015drawable-en-notouch-12key/ 1016drawable-port-ldpi/ 1017drawable-port-notouch-12key/ 1018</pre> 1019<p class="note"><strong>Exception:</strong> Screen pixel density is the one qualifier that is not 1020eliminated due to a contradiction. Even though the screen density of the device is hdpi, 1021<code>drawable-port-ldpi/</code> is not eliminated because every screen density is 1022considered to be a match at this point. More information is available in the <a 1023href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple 1024Screens</a> document.</p></li> 1025 1026 <li>Pick the (next) highest-precedence qualifier in the list (<a href="#table2">table 2</a>). 1027(Start with MCC, then move down.) </li> 1028 <li>Do any of the resource directories include this qualifier? </li> 1029 <ul> 1030 <li>If No, return to step 2 and look at the next qualifier. (In the example, 1031 the answer is "no" until the language qualifier is reached.)</li> 1032 <li>If Yes, continue to step 4.</li> 1033 </ul> 1034 </li> 1035 1036 <li>Eliminate resource directories that do not include this qualifier. In the example, the system 1037eliminates all the directories that do not include a language qualifier:</li> 1038<pre class="classic no-pretty-print"> 1039<strike>drawable/</strike> 1040drawable-en/ 1041drawable-en-port/ 1042drawable-en-notouch-12key/ 1043<strike>drawable-port-ldpi/</strike> 1044<strike>drawable-port-notouch-12key/</strike> 1045</pre> 1046<p class="note"><strong>Exception:</strong> If the qualifier in question is screen pixel density, 1047Android selects the option that most closely matches the device screen density. 1048In general, Android prefers scaling down a larger original image to scaling up a smaller 1049original image. See <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple 1050Screens</a>.</p> 1051 </li> 1052 1053 <li>Go back and repeat steps 2, 3, and 4 until only one directory remains. In the example, screen 1054orientation is the next qualifier for which there are any matches. 1055So, resources that do not specify a screen orientation are eliminated: 1056<pre class="classic no-pretty-print"> 1057<strike>drawable-en/</strike> 1058drawable-en-port/ 1059<strike>drawable-en-notouch-12key/</strike> 1060</pre> 1061<p>The remaining directory is {@code drawable-en-port}.</p> 1062 </li> 1063</ol> 1064 1065<p>Though this procedure is executed for each resource requested, the system further optimizes 1066some aspects. One such optimization is that once the device configuration is known, it might 1067eliminate alternative resources that can never match. For example, if the configuration 1068language is English ("en"), then any resource directory that has a language qualifier set to 1069something other than English is never included in the pool of resources checked (though a 1070resource directory <em>without</em> the language qualifier is still included).</p> 1071 1072<p class="note"><strong>Note:</strong> The <em>precedence</em> of the qualifier (in <a 1073href="#table2">table 2</a>) is more important 1074than the number of qualifiers that exactly match the device. For example, in step 4 above, the last 1075choice on the list includes three qualifiers that exactly match the device (orientation, touchscreen 1076type, and input method), while <code>drawable-en</code> has only one parameter that matches 1077(language). However, language has a higher precedence than these other qualifiers, so 1078<code>drawable-port-notouch-12key</code> is out.</p> 1079 1080<p>To learn more about how to use resources in your application, continue to <a 1081href="accessing-resources.html">Accessing Resources</a>.</p> 1082 1083 1084 1085 1086<h2 id="KnownIssues">Known Issues</h2> 1087 1088<h3>Android 1.5 and 1.6: Version qualifier performs exact match, instead of best match</h3> 1089 1090<p>The correct behavior is for the system to match resources marked with a <a 1091href="#VersionQualifier">version qualifier</a> equal 1092to or less than the platform version on the device, but on Android 1.5 and 1.6, (API level 3 and 4), 1093there is a bug that causes the system to match resources marked with the version qualifier 1094only when it exactly matches the version on the device.</p> 1095 1096<p><b>The workaround:</b> To provide version-specific resources, abide by this behavior. However, 1097because this bug is fixed in versions of Android available after 1.6, if 1098you need to differentiate resources between Android 1.5, 1.6, and later versions, then you only need 1099to apply the version qualifier to the 1.6 resources and one to match all later versions. Thus, this 1100is effectively a non-issue.</p> 1101 1102<p>For example, if you want drawable resources that are different on each Android 1.5, 1.6, 1103and 2.0.1 (and later), create three drawable directories: {@code drawable/} (for 1.5 and lower), 1104{@code drawable-v4} (for 1.6), and {@code drawable-v6} (for 2.0.1 and later—version 2.0, v5, 1105is no longer available).</p> 1106 1107 1108