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