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