• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1page.title=Supporting Multiple Screens
2page.metaDescription=Managing UIs for the best display on multiple screen sizes.
3meta.tags="multiple screens"
4
5@jd:body
6
7<div id="qv-wrapper">
8<div id="qv">
9
10  <h2>Quickview</h2>
11  <ul>
12    <li>Android runs on devices that have different screen sizes and densities.</li>
13    <li>The screen on which your application is displayed can affect its user interface.</li>
14    <li>The system handles most of the work of adapting your app to the current screen.</li>
15    <li>You should create screen-specific resources for precise control of your UI. </li>
16  </ul>
17
18  <h2>In this document</h2>
19  <ol>
20    <li><a href="#overview">Overview of Screen Support</a>
21      <ol>
22        <li><a href="#terms">Terms and concepts</a></li>
23        <li><a href="#range">Range of screens supported</a></li>
24        <li><a href="#density-independence">Density independence</a></li>
25      </ol></li>
26    <li><a href="#support">How to Support Multiple Screens</a>
27      <ol>
28        <li><a href="#qualifiers">Using configuration qualifiers</a></li>
29        <li><a href="#DesigningResources">Designing alternative layouts and drawables</a></li>
30      </ol></li>
31    <li><a href="#DeclaringTabletLayouts">Declaring Tablet Layouts for Android 3.2</a>
32      <ol>
33        <li><a href="#NewQualifiers">Using new size qualifiers</a></li>
34        <li><a href="#ConfigurationExamples">Configuration examples</a></li>
35        <li><a href="#DeclaringScreenSizeSupport">Declaring screen size support</a></li>
36      </ol></li>
37    <li><a href="#screen-independence">Best Practices</a></li>
38    <li><a href="#DensityConsiderations">Additional Density Considerations</a>
39      <ol>
40        <li><a href="#scaling">Scaling Bitmap objects created at runtime</a></li>
41        <li><a href="#dips-pels">Converting dp units to pixel units</a></li>
42      </ol></li>
43    <li><a href="#testing">How to Test Your Application on Multiple Screens</a></li>
44  </ol>
45
46  <h2>Related samples</h2>
47  <ol>
48    <li><a href="{@docRoot}resources/samples/MultiResolution/index.html">Multiple
49Resolutions</a></li>
50  </ol>
51
52  <h2>See also</h2>
53  <ol>
54    <li><a
55href="http://android-developers.blogspot.com/2011/09/thinking-like-web-designer.html">Thinking
56Like a Web Designer</a></li>
57    <li><a
58href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">
59Providing Alternative Resources</a></li>
60    <li><a href="{@docRoot}guide/practices/ui_guidelines/icon_design.html">Icon Design
61Guidelines</a></li>
62    <li><a href="{@docRoot}tools/devices/index.html">Managing Virtual Devices</a></li>
63  </ol>
64
65</div>
66</div>
67
68<p>Android runs on a variety of devices that offer different screen sizes and densities. For
69applications, the Android system provides a consistent development environment across devices and
70handles most of the work to adjust each application's user interface to the screen on which it is
71displayed. At the same time, the system provides APIs that allow you to control your
72application's UI for specific screen sizes and densities, in order to optimize your UI
73design for different screen configurations. For example, you might want a UI for tablets
74that's different from the UI for handsets.</p>
75
76<p>Although the system performs scaling and resizing to make your application work on
77different screens, you should make the effort to optimize your application for different screen
78sizes and densities. In doing so, you maximize the user experience for all devices and your users
79believe that your application was actually designed for <em>their</em> devices&mdash;rather than
80simply stretched to fit the screen on their devices.</p>
81
82<p>By following the practices described in this document, you can create an application that
83displays properly and provides an optimized user experience on all supported screen configurations,
84using a single {@code .apk} file.</p>
85
86<p class="note"><strong>Note:</strong> The information in this document assumes that your
87application is designed for Android 1.6 (API Level 4) or higher. If your application supports
88Android 1.5 or lower, please first read <a
89href="{@docRoot}guide/practices/screens-support-1.5.html">Strategies for Android 1.5</a>.
90<br/><br/>
91Also, be aware that <strong>Android 3.2 has introduced new APIs</strong> that allow you to more
92precisely control the layout resources your application uses for different screen sizes. These new
93features are especially important if you're developing an application that's optimized for tablets.
94For details, see the section about <a href="#DeclaringTabletLayouts">Declaring Tablet Layouts for
95Android 3.2</a>.
96</p>
97
98
99
100<h2 id="overview">Overview of Screens Support</h2>
101
102<p>This section provides an overview of Android's support for multiple screens, including: an
103introduction to the terms and concepts used in this document and in the API, a summary of the screen
104configurations that the system supports, and an overview of the API and underlying
105screen-compatibility features.</p>
106
107<h3 id="terms">Terms and concepts</h3>
108
109<dl>
110<dt><em>Screen size</em></dt>
111  <dd>Actual physical size, measured as the screen's diagonal.
112
113  <p>For simplicity, Android groups all actual screen sizes into four generalized sizes: small,
114normal, large, and extra-large.</p></dd>
115
116<dt><em>Screen density</em></dt>
117  <dd>The quantity of pixels within a physical area of the screen; usually referred to as dpi (dots
118per inch). For example, a "low" density screen has fewer pixels within a given physical area,
119compared to a "normal" or "high" density screen.</p>
120
121  <p>For simplicity, Android groups all actual screen densities into six generalized densities:
122low, medium, high, extra-high, extra-extra-high, and extra-extra-extra-high.</p></dd>
123
124<dt><em>Orientation</em></dt>
125  <dd>The orientation of the screen from the user's point of view. This is either landscape or
126portrait, meaning that the screen's aspect ratio is either wide or tall, respectively. Be aware
127that not only do different devices operate in different orientations by default, but the
128orientation can change at runtime when the user rotates the device.
129</dd>
130
131<dt><em>Resolution</em></dt>
132  <dd>The total number of physical pixels on a screen. When adding support for multiple screens,
133applications do not work directly with resolution; applications should be concerned only with screen
134size and density, as specified by the generalized size and density groups.</dd>
135
136<dt><em>Density-independent pixel (dp)</em></dt>
137  <dd>A virtual pixel unit that you should use when defining UI layout, to express layout dimensions
138or position in a density-independent way.
139  <p>The density-independent pixel is equivalent to one physical pixel on a 160 dpi screen, which is
140the baseline density assumed by the system for a "medium" density screen. At runtime, the system
141transparently handles any scaling of the dp units, as necessary, based on the actual density of the
142screen in use. The conversion of dp units to screen pixels is simple:
143<nobr><code>px = dp * (dpi / 160)</code></nobr>.
144For example, on a 240 dpi screen, 1 dp equals 1.5 physical pixels. You should always use dp units
145when defining your application's UI, to ensure proper display of your UI on screens with different
146densities. </p></dd>
147</dl>
148
149
150<h3 id="range">Range of screens supported</h3>
151
152<p>Starting with Android 1.6 (API Level 4), Android provides support for multiple screen sizes and
153densities, reflecting the many different screen configurations that a device may have. You can use
154features of the Android system to optimize your application's user interface for each screen
155configuration and ensure that your application not only renders properly, but provides the best
156user experience possible on each screen.</p>
157
158<p>To simplify the way that you design your user interfaces for multiple screens, Android divides
159the range of actual screen sizes and densities into:</p>
160
161<ul>
162<li>A set of four generalized <strong>sizes</strong>: <em>small</em>, <em>normal</em>,
163<em>large</em>,
164and <em>xlarge</em></em>
165<p class="note"><strong>Note:</strong> Beginning with Android 3.2 (API level 13), these size groups
166are deprecated in favor of a new technique for managing screen sizes based on the available screen
167width. If you're developing for Android 3.2 and greater, see <a
168href="#DeclaringTabletLayouts">Declaring Tablet Layouts for Android 3.2</a> for more
169information.</p>
170</li>
171<li>A set of six generalized <strong>densities</strong>:
172  <ul>
173    <li><em>ldpi</em> (low) ~120dpi</li>
174    <li><em>mdpi</em> (medium) ~160dpi</li>
175    <li><em>hdpi</em> (high) ~240dpi</li>
176    <li><em>xhdpi</em> (extra-high) ~320dpi</li>
177    <li><em>xxhdpi</em> (extra-extra-high) ~480dpi</li>
178    <li><em>xxxhdpi</em> (extra-extra-extra-high) ~640dpi</li>
179  </ul>
180</li>
181</ul>
182
183<p>The generalized sizes and densities are arranged around a
184baseline configuration that is a <em>normal</em> size and <em>mdpi</em> (medium) density. This
185baseline is based upon the screen configuration for the first Android-powered device, the T-Mobile
186G1, which has an HVGA screen (until Android 1.6, this was the only screen configuration that Android
187supported).</p>
188
189<p>Each generalized size and density spans a range of actual screen sizes and densities. For example,
190two devices that both report a screen size of <em>normal</em> might have actual screen sizes and
191aspect ratios that are slightly different when measured by hand. Similarly, two devices that report
192a screen density of <em>hdpi</em> might have real pixel densities that are slightly different.
193Android makes these differences abstract to applications, so you can provide UI designed for the
194generalized sizes and densities and let the system handle any final adjustments as necessary. Figure
1951 illustrates how different sizes and densities are roughly categorized into the different size
196and density groups.</p>
197
198<img src="{@docRoot}images/screens_support/screens-ranges.png" style="padding:1em 0 0" alt="" />
199<p class="img-caption"><strong>Figure 1.</strong>
200Illustration of how Android roughly maps actual sizes and densities
201to generalized sizes and densities (figures are not exact).</p>
202
203<p>As you design your UI for different screen sizes, you'll discover that each design requires a
204minimum amount of space. So, each generalized screen size above has an associated minimum
205resolution that's defined by the system. These minimum sizes are in "dp" units&mdash;the same units
206you should use when defining your layouts&mdash;which allows the system to avoid worrying about
207changes in screen density.</p>
208
209<ul>
210  <li><em>xlarge</em> screens are at least 960dp x 720dp</li>
211  <li><em>large</em> screens are at least 640dp x 480dp</li>
212  <li><em>normal</em> screens are at least 470dp x 320dp</li>
213  <li><em>small</em> screens are at least 426dp x 320dp</li>
214</ul>
215
216<p class="note"><strong>Note:</strong> These minimum screen sizes were not as well defined prior to
217Android 3.0, so you may encounter some devices that are mis-classified between normal and large.
218These are also based on the physical resolution of the screen, so may vary across devices&mdash;for
219example a 1024x720 tablet with a system bar actually has a bit less space available to the
220application due to it being used by the system bar.</p>
221
222<p>To optimize your application's UI for the different screen sizes and densities, you can provide
223<a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">alternative
224resources</a> for any of the generalized sizes and densities. Typically, you should
225provide alternative layouts for some of the different screen sizes and alternative bitmap images for
226different screen densities. At runtime, the system uses the appropriate resources
227for your application, based on the generalized size or density of the current device screen.</p>
228
229<p>You do not need to provide alternative resources for every combination of screen size and
230density. The system provides robust compatibility features that can handle most of the work of
231rendering your application on any device screen, provided that you've implemented your UI using
232techniques that allow it to gracefully resize (as described in the <a
233href="#screen-independence">Best Practices</a>, below).</p>
234
235<p class="note"><strong>Note:</strong> The characteristics that define a device's generalized screen
236size and density are independent from each other. For example, a WVGA high-density screen is
237considered a normal size screen because its physical size is about the same as the T-Mobile G1
238(Android's first device and baseline screen configuration). On the other hand, a WVGA medium-density
239screen is considered a large size screen. Although it offers the same resolution (the same number of
240pixels), the WVGA medium-density screen has a lower screen density, meaning that each pixel is
241physically larger and, thus, the entire screen is larger than the baseline (normal size) screen.</p>
242
243
244
245<h3 id="density-independence">Density independence</h3>
246
247<p>Your application achieves "density independence" when it preserves the physical size (from
248the user's point of view) of user interface elements when displayed on screens with different
249densities.</p>
250
251<p>Maintaining density independence is important because, without it, a UI element (such as a
252button) appears physically larger on a low-density screen and smaller on a high-density screen. Such
253density-related size changes can cause problems in your application layout and usability. Figures 2
254and 3 show the difference between an application when it does not provide density independence and
255when it does, respectively.</p>
256
257<img src="{@docRoot}images/screens_support/density-test-bad.png" alt=""  />
258<p class="img-caption"><strong>Figure 2.</strong> Example application without support for
259different densities, as shown on low, medium, and high-density screens.</p>
260
261<img src="{@docRoot}images/screens_support/density-test-good.png" alt="" />
262<p class="img-caption"><strong>Figure 3.</strong> Example application with good support for
263different densities (it's density independent), as shown on low, medium, and high
264density screens.</p>
265
266<p>The Android system helps your application achieve density independence in two ways: </p>
267
268<ul>
269<li>The system scales dp units as appropriate for the current screen density</li>
270<li>The system scales drawable resources to the appropriate size, based on the current screen
271density, if necessary</li>
272</ul>
273
274<p>In figure 2, the text view and bitmap drawable have dimensions specified in pixels ({@code px}
275units), so the views are physically larger on a low-density screen and smaller on a high-density
276screen. This is because although the actual screen sizes may be the same, the high-density screen
277has more pixels per inch (the same amount of pixels fit in a smaller area). In figure 3, the layout
278dimensions are specified in density-independent pixels ({@code dp} units). Because the baseline for
279density-independent pixels is a medium-density screen, the device with a medium-density screen looks
280the same as it does in figure 2. For the low-density and high-density screens, however, the system
281scales the density-independent pixel values down and up, respectively, to fit the screen as
282appropriate.</p>
283
284<p>In most cases, you can ensure density independence in your application simply by specifying all
285layout dimension values in density-independent pixels (<code>dp</code> units) or with {@code
286"wrap_content"}, as appropriate. The system then scales bitmap drawables as appropriate in order to
287display at the appropriate size, based on the appropriate scaling factor for the current screen's
288density.</p>
289
290<p>However, bitmap scaling can result in blurry or pixelated bitmaps, which you might notice in the
291above screenshots. To avoid these artifacts, you should provide alternative bitmap resources for
292different densities. For example, you should provide higher-resolution bitmaps for high-density
293screens and the system will use those instead of resizing the bitmap designed for medium-density
294screens. The following section describes more about how to supply alternative resources for
295different screen configurations.</p>
296
297
298
299<h2 id="support">How to Support Multiple Screens</h2>
300
301<p>The foundation of Android's support for multiple screens is its ability to manage the rendering
302of an application's layout and bitmap drawables in an appropriate way for the current screen
303configuration. The system handles most of the work to render your application properly on each
304screen configuration by scaling layouts to fit the screen size/density and scaling bitmap drawables
305for the screen density, as appropriate. To more gracefully handle different screen configurations,
306however, you should also:</p>
307
308<ul>
309  <li><strong>Explicitly declare in the manifest which screen sizes your application
310supports</strong>
311    <p>By declaring which screen sizes your application supports, you can ensure that only
312devices with the screens you support can download your application. Declaring support for
313different screen sizes can also affect how the system draws your application on larger
314screens&mdash;specifically, whether your application runs in <a
315href="{@docRoot}guide/practices/screen-compat-mode.html">screen compatibility mode</a>.</p>
316    <p>To declare the screen sizes your application supports, you should include the
317<a href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
318<supports-screens>}</a> element in your manifest file.</p>
319  </li>
320
321  <li><strong>Provide different layouts for different screen sizes</strong>
322    <p>By default, Android resizes your application layout to fit the current device screen. In most
323cases, this works fine. In other cases, your UI might not look as good and might need adjustments
324for different screen sizes. For example, on a larger screen, you might want to adjust the position
325and size of some elements to take advantage of the additional screen space, or on a smaller screen,
326you might need to adjust sizes so that everything can fit on the screen.</p>
327    <p>The configuration qualifiers you can use to provide size-specific resources are
328<code>small</code>, <code>normal</code>, <code>large</code>, and <code>xlarge</code>. For
329example, layouts for an extra-large screen should go in {@code layout-xlarge/}.</p>
330    <p>Beginning with Android 3.2 (API level 13), the above size groups are deprecated and you
331should instead use the {@code sw<N>dp} configuration qualifier to define the smallest
332available width required by your layout resources. For example, if your multi-pane tablet layout
333requires at least 600dp of screen width, you should place it in {@code layout-sw600dp/}. Using the
334new techniques for declaring layout resources is discussed further in the section about <a
335href="#DeclaringTabletLayouts">Declaring Tablet Layouts for Android 3.2</a>.</p>
336  </li>
337
338  <li><strong>Provide different bitmap drawables for different screen densities</strong>
339    <p>By default, Android scales your bitmap drawables ({@code .png}, {@code .jpg}, and {@code
340.gif} files) and Nine-Patch drawables ({@code .9.png} files) so that they render at the appropriate
341physical size on each device. For example, if your application provides bitmap drawables only for
342the baseline, medium screen density (mdpi), then the system scales them up when on a high-density
343screen, and scales them down when on a low-density screen. This scaling can cause artifacts in the
344bitmaps. To ensure your bitmaps look their best, you should include alternative versions at
345different resolutions for different screen densities.</p>
346    <p>The <a href="#qualifiers">configuration qualifiers</a> (described in detail below) that you
347can use for density-specific resources are <code>ldpi</code> (low), <code>mdpi</code> (medium),
348<code>hdpi</code> (high), <code>xhdpi</code> extra-high), <code>xxhdpi</code>
349(extra-extra-high), and <code>xxxhdpi</code> (extra-extra-extra-high). For example, bitmaps
350for high-density screens should go in {@code drawable-hdpi/}.</p>
351    <p class="note" id="xxxhdpi-note"><strong>Note:</strong>  The <code>mipmap-xxxhdpi</code>
352qualifier is necessary only to provide a launcher icon that can appear larger than usual on an
353xxhdpi device. You do not need to provide xxxhdpi assets for all your app's images.</p>
354    <p>Some devices scale-up the launcher icon by as much as 25%. For example, if your highest
355density launcher icon image is already extra-extra-high-density, the scaling process will make it
356appear less crisp. So you should provide a higher density launcher icon in the
357<code>mipmap-xxxhdpi</code> directory, which the system uses instead of scaling up a smaller
358version of the icon.</p>
359    <p>See <a href="{@docRoot}design/style/iconography.html#xxxhdpi-launcher">Provide an
360xxx-high-density launcher icon</a> for more information. You should not use the
361<code>xxxhdpi</code> qualifier for UI elements other than the launcher icon.</p>
362  </li>
363</ul>
364
365<p class="note"><strong>Note:</strong> Place all your launcher icons in the
366<code>res/mipmap-[density]/</code> folders, rather than the <code>res/drawable-[density]/</code>
367folders. The Android system retains the resources in these density-specific folders, such as
368mipmap-xxxhdpi, regardless of the screen resolution of the device where your app is installed. This
369behavior allows launcher apps to pick the best resolution icon for your app to display on the home
370screen. For more information about using the mipmap folders, see
371<a href="{@docRoot}tools/projects/index.html#mipmap">Managing Projects Overview</a>.
372</p>
373
374
375<p>The size and density configuration qualifiers correspond to the generalized sizes and densities
376described in <a href="#range">Range of screens supported</a>, above.</p>
377
378<p class="note"><strong>Note:</strong> If you're not familiar with configuration qualifiers and how
379the system uses them to apply alternative resources, read <a
380href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">Providing
381Alternative Resources</a> for more information.</p>
382
383<p>At runtime, the system ensures the best possible display on the current screen with
384the following procedure for any given resource:</p>
385
386<ol>
387<li>The system uses the appropriate alternative resource
388  <p>Based on the size and density of the current screen, the system uses any size- and
389density-specific resource provided in your application. For example, if the device has a
390high-density screen and the application requests a drawable resource, the system looks for a
391drawable resource directory that best matches the device configuration. Depending on the other
392alternative resources available, a resource directory with the {@code hdpi} qualifier (such as
393{@code drawable-hdpi/}) might be the best match, so the system uses the drawable resource from this
394directory.</p>
395</li>
396
397<li>If no matching resource is available, the system uses the default resource and scales it up
398or down as needed to match the current screen size and density
399  <p>The "default" resources are those that are not tagged with a configuration qualifier. For
400example, the resources in {@code drawable/} are the default drawable resources. The system
401assumes that default resources are designed for the baseline screen size and density, which is a
402normal screen size and a medium-density. As such, the system scales default density
403resources up for high-density screens and down for low-density screens, as appropriate.</p>
404  <p>However, when the system is looking for a density-specific resource and does not find it in
405the density-specific directory, it won't always use the default resources. The system may
406instead use one of the other density-specific resources in order to provide better results
407when scaling. For example, when looking for a low-density resource and it is not available, the
408system prefers to scale-down the high-density version of the resource, because the
409system can easily scale a high-density resource down to low-density by a factor of 0.5, with
410fewer artifacts, compared to scaling a medium-density resource by a factor of 0.75.</p>
411</li>
412</ol>
413
414  <p>For more information about how Android selects alternative resources by matching configuration
415qualifiers to the device configuration, read
416<a href="{@docRoot}guide/topics/resources/providing-resources.html#BestMatch">How Android
417Finds the Best-matching Resource</a>.</p>
418
419
420
421
422<h3 id="qualifiers">Using configuration qualifiers</h3>
423
424<p>Android supports several configuration qualifiers that allow you to control how the system
425selects your alternative resources based on the characteristics of the current device screen. A
426configuration qualifier is a string that you can append to a resource directory in your Android
427project and specifies the configuration for which the resources inside are designed.</p>
428
429<p>To use a configuration qualifier:</p>
430<ol>
431  <li>Create a new directory in your project's {@code res/} directory and name it using the
432format: <nobr>{@code <resources_name>-<qualifier>}</nobr>
433    <ul>
434      <li>{@code <resources_name>} is the standard resource name (such as {@code drawable} or
435{@code layout}).</li>
436      <li>{@code <qualifier>} is a configuration qualifier from table 1, below, specifying the
437screen configuration for which these resources are to be used (such as {@code hdpi} or {@code
438xlarge}).</li>
439    </ul>
440    <p>You can use more than one {@code <qualifier>} at a time&mdash;simply separate each
441qualifier with a dash.</p>
442  </li>
443  <li>Save the appropriate configuration-specific resources in this new directory. The resource
444files must be named exactly the same as the default resource files.</li>
445</ol>
446
447<p>For example, {@code xlarge} is a configuration qualifier for extra-large screens. When you append
448this string to a resource directory name (such as {@code layout-xlarge}), it indicates to the
449system that these resources are to be used on devices that have an extra-large screen.</p>
450
451<p class="table-caption"><strong>Table 1.</strong> Configuration qualifiers that allow you to
452provide special resources for different screen configurations.</p>
453
454<table>
455<tr>
456<th>Screen characteristic</th>
457<th>Qualifier</th>
458<th>Description</th>
459</tr>
460
461<tr>
462  <td rowspan="4">Size</td>
463  <td><code>small</code></td>
464  <td>Resources for <em>small</em> size screens.</td>
465</tr>
466<tr>
467  <td><code>normal</code></td>
468  <td>Resources for <em>normal</em> size screens. (This is the baseline size.)</td>
469</tr>
470<tr>
471<td><code>large</code></td>
472<td>Resources for <em>large</em> size screens.</td>
473</tr>
474<tr>
475<td><code>xlarge</code></td>
476<td>Resources for <em>extra-large</em> size screens.</td>
477</tr>
478
479<tr>
480<td rowspan="8">Density</td>
481<td><code>ldpi</code></td>
482<td>Resources for low-density (<em>ldpi</em>) screens (~120dpi).</td>
483</tr>
484<tr>
485<td><code>mdpi</code></td>
486<td>Resources for medium-density (<em>mdpi</em>) screens (~160dpi). (This is the baseline
487density.)</td>
488</tr>
489<tr>
490<td><code>hdpi</code></td>
491<td>Resources for high-density (<em>hdpi</em>) screens (~240dpi).</td>
492</tr>
493<tr>
494<td><code>xhdpi</code></td>
495<td>Resources for extra-high-density (<em>xhdpi</em>) screens (~320dpi).</td>
496</tr>
497<td><code>xxhdpi</code></td>
498<td>Resources for extra-extra-high-density (<em>xxhdpi</em>) screens (~480dpi).</td>
499</tr>
500<td><code>xxxhdpi</code></td>
501<td>Resources for extra-extra-extra-high-density (<em>xxxhdpi</em>) uses (~640dpi). Use this for the
502  launcher icon only, see <a href="#xxxhdpi-note">note</a> above.</td>
503</tr>
504<tr>
505<td><code>nodpi</code></td>
506<td>Resources for all densities. These are density-independent resources. The system does not
507scale resources tagged with this qualifier, regardless of the current screen's density.</td>
508</tr>
509<tr>
510<td><code>tvdpi</code></td>
511<td>Resources for screens somewhere between mdpi and hdpi; approximately 213dpi. This is not
512considered a "primary" density group. It is mostly intended for televisions and most apps shouldn't
513need it&mdash;providing mdpi and hdpi resources is sufficient for most apps and the system will
514scale them as appropriate. If you find it necessary to provide tvdpi resources, you should size them
515at a factor of 1.33*mdpi. For example, a 100px x 100px image for mdpi screens should be 133px x
516133px for tvdpi.</td>
517</tr>
518<tr>
519<td rowspan="2">Orientation</td>
520<td><code>land</code></td>
521<td>Resources for screens in the landscape orientation (wide aspect ratio).</td>
522</tr>
523<tr>
524<td><code>port</code></td>
525<td>Resources for screens in the portrait orientation (tall aspect ratio).</td>
526</tr>
527
528<tr>
529<td rowspan="2">Aspect ratio</td>
530<td><code>long</code></td>
531<td>Resources for screens that have a significantly taller or wider aspect ratio (when in portrait
532or landscape orientation, respectively) than the baseline screen configuration.</td>
533</tr>
534<tr>
535<td><code>notlong</code></td>
536<td>Resources for use screens that have an aspect ratio that is similar to the baseline screen
537configuration.</td>
538</tr>
539</table>
540
541<p class="note"><strong>Note:</strong> If you're developing your application for Android 3.2 and
542higher, see the section about <a
543href="#DeclaringTabletLayouts">Declaring Tablet Layouts for Android 3.2</a> for information about
544new configuration qualifiers that you should use when declaring layout resources for specific
545screen sizes (instead of using the size qualifiers in table 1).</p></p>
546
547<p>For more information about how these qualifiers roughly correspond to real screen
548sizes and densities, see <a href="#range">Range of Screens Supported</a>, earlier in this
549document.</p>
550
551<p>For example, the following application resource directories provide different layout designs
552for different screen sizes and different drawables. Use the <code>mipmap/</code> folders for
553launcher icons.</p>
554
555<pre class="classic">
556res/layout/my_layout.xml              // layout for normal screen size ("default")
557res/layout-large/my_layout.xml        // layout for large screen size
558res/layout-xlarge/my_layout.xml       // layout for extra-large screen size
559res/layout-xlarge-land/my_layout.xml  // layout for extra-large in landscape orientation
560
561res/drawable-mdpi/graphic.png         // bitmap for medium-density
562res/drawable-hdpi/graphic.png         // bitmap for high-density
563res/drawable-xhdpi/graphic.png        // bitmap for extra-high-density
564res/drawable-xxhdpi/graphic.png       // bitmap for extra-extra-high-density
565
566res/mipmap-mdpi/my_icon.png         // launcher icon for medium-density
567res/mipmap-hdpi/my_icon.png         // launcher icon for high-density
568res/mipmap-xhdpi/my_icon.png        // launcher icon for extra-high-density
569res/mipmap-xxhdpi/my_icon.png       // launcher icon for extra-extra-high-density
570res/mipmap-xxxhdpi/my_icon.png      // launcher icon for extra-extra-extra-high-density
571</pre>
572
573<p>For more information about how to use alternative resources and a complete list of
574configuration qualifiers (not just for screen configurations), see
575<a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">
576Providing Alternative Resources</a>.</p>
577
578<p>Be aware that, when the Android system picks which resources to use at runtime, it uses
579certain logic to determine the "best matching" resources. That is, the qualifiers you use don't
580have to exactly match the current screen configuration in all cases in order for the system to
581use them. Specifically, when selecting resources based on the size qualifiers, the system will
582use resources designed for a screen smaller than the current screen if there are no resources
583that better match (for example, a large-size screen will use normal-size screen resources if
584necessary). However, if the only available resources are <em>larger</em> than the current screen,
585the system will not use them and your application will crash if no other resources match the device
586configuration (for example, if all layout resources are tagged with the {@code xlarge} qualifier,
587but the device is a normal-size screen). For more information about how the system selects
588resources, read <a
589href="{@docRoot}guide/topics/resources/providing-resources.html#BestMatch">How Android Finds the
590Best-matching Resource</a>.</p>
591
592  <p class="note"><strong>Tip:</strong> If you have some drawable resources that the system
593should never scale (perhaps because you perform some adjustments to the image yourself at
594runtime), you should place them in a directory with the {@code nodpi} configuration qualifier.
595Resources with this qualifier are considered density-agnostic and the system will not scale
596them.</p>
597
598
599<h3 id="DesigningResources">Designing alternative layouts and drawables</h3>
600
601<p>The types of alternative resources you should create depends on your application's needs.
602Usually, you should use the size and orientation qualifiers to provide alternative layout resources
603and use the density qualifiers to provide alternative bitmap drawable resources.</p>
604
605<p>The following sections summarize how you might want to use the size and density qualifiers to
606provide alternative layouts and drawables, respectively.</p>
607
608
609<h4>Alternative layouts</h4>
610
611<p>Generally, you'll know whether you need alternative layouts for different screen sizes once
612you test your application on different screen configurations. For example:</p>
613
614<ul>
615  <li>When testing on a small screen, you might discover that your layout doesn't quite fit on the
616screen. For example, a row of buttons might not fit within the width of the screen on a small screen
617device. In this case you should provide an alternative layout for small screens that adjusts the
618size or position of the buttons.</li>
619  <li>When testing on an extra-large screen, you might realize that your layout doesn't make
620efficient use of the big screen and is obviously stretched to fill it.
621In this case, you should provide an alternative layout for extra-large screens that provides a
622redesigned UI that is optimized for bigger screens such as tablets.
623    <p>Although your application should work fine without an alternative layout on big screens, it's
624quite important to users that your application looks as though it's designed specifically for their
625devices. If the UI is obviously stretched, users are more likely to be unsatisfied with the
626application experience.</p></li>
627  <li>And, when testing in the landscape orientation compared to the portrait orientation, you
628might notice that UI elements placed at the bottom of the screen for the portrait orientation
629should instead be on the right side of the screen in landscape orientation.</li>
630</ul>
631
632<p>To summarize, you should be sure that your application layout:</p>
633<ul>
634  <li>Fits on small screens (so users can actually use your application)</li>
635  <li>Is optimized for bigger screens to take advantage of the additional screen space</li>
636  <li>Is optimized for both landscape and portrait orientations</li>
637</ul>
638
639<p>If your UI uses bitmaps that need to fit the size of a view even after the system scales
640the layout (such as the background image for a button), you should use <a
641href="{@docRoot}guide/topics/graphics/2d-graphics.html#nine-patch">Nine-Patch</a> bitmap files. A
642Nine-Patch file is basically a PNG file in which you specify two-dimensional regions that are
643stretchable. When the system needs to scale the view in which the bitmap is used, the system
644stretches the Nine-Patch bitmap, but stretches only the specified regions. As such, you don't
645need to provide different drawables for different screen sizes, because the Nine-Patch bitmap can
646adjust to any size. You should, however, provide alternate versions of your Nine-Patch files for
647different screen densities.</p>
648
649
650<h4>Alternative drawables</h4>
651
652<div class="figure" style="width:223px;margin:0">
653<img src="{@docRoot}images/screens_support/screens-densities.png" alt="" />
654<p class="img-caption"><strong>Figure 4.</strong> Relative sizes for bitmap drawables
655that support each density.</p>
656</div>
657
658<p>Almost every application should have alternative drawable resources for different screen
659densities, because almost every application has a launcher icon and that icon should look good on
660all screen densities. Likewise, if you include other bitmap drawables in your application (such
661as for menu icons or other graphics in your application), you should provide alternative versions or
662each one, for different densities.</p>
663
664<p class="note"><strong>Note:</strong> You only need to provide density-specific drawables for
665bitmap files ({@code .png}, {@code .jpg}, or {@code .gif}) and Nine-Patch files ({@code
666.9.png}). If you use XML files to define shapes, colors, or other <a
667href="{@docRoot}guide/topics/resources/drawable-resource.html">drawable resources</a>, you should
668put one copy in the default drawable directory ({@code drawable/}).</p>
669
670<p>To create alternative bitmap drawables for different densities, you should follow the
671<b>3:4:6:8:12:16 scaling ratio</b> between the six generalized densities. For example, if you have
672a bitmap drawable that's 48x48 pixels for medium-density screens, all the different sizes should be:
673</p>
674
675<ul>
676  <li>36x36 (0.75x) for low-density</li>
677  <li>48x48 (1.0x baseline) for medium-density</li>
678  <li>72x72 (1.5x) for high-density</li>
679  <li>96x96 (2.0x) for extra-high-density</li>
680  <li>144x144 (3.0x) for extra-extra-high-density</li>
681  <li>192x192 (4.0x) for extra-extra-extra-high-density (launcher icon only; see
682    <a href="#xxxhdpi-note">note</a> above)</li>
683</ul>
684
685<p>For more information about designing icons, see the <a
686href="{@docRoot}guide/practices/ui_guidelines/icon_design.html">Icon Design Guidelines</a>,
687which includes size information for various bitmap drawables, such as launcher icons, menu
688icons, status bar icons, tab icons, and more.</p>
689
690
691
692
693<h2 id="DeclaringTabletLayouts">Declaring Tablet Layouts for Android 3.2</h2>
694
695<p>For the first generation of tablets running Android 3.0, the proper way to declare tablet
696layouts was to put them in a directory with the {@code xlarge} configuration qualifier (for example,
697 {@code res/layout-xlarge/}). In order to accommodate other types of tablets and screen
698sizes&mdash;in particular, 7" tablets&mdash;Android 3.2 introduces a new way to specify resources
699for more discrete screen sizes. The new technique is based on the amount of space your layout needs
700(such as 600dp of width), rather than trying to make your layout fit the generalized size groups
701(such as <em>large</em> or <em>xlarge</em>).</p>
702
703<p>The reason designing for 7" tablets is tricky when using the generalized size groups is
704that a 7" tablet is technically in the same group as a 5" handset (the <em>large</em> group). While
705these two devices are seemingly close to each other in size, the amount of space for an
706application's UI is significantly different, as is the style of user interaction. Thus, a 7" and 5"
707screen should not always use the same layout. To make it possible for you to provide different
708layouts for these two kinds of screens, Android now allows you to specify your layout resources
709based on the width and/or height that's actually available for your application's layout, specified
710in dp units.</p>
711
712<p>For example, after you've designed the layout you want to use for tablet-style devices, you might
713determine that the layout stops working well when the screen is less than 600dp wide. This threshold
714thus becomes the minimum size that you require for your tablet layout. As
715such, you can now specify that these layout resources should be used only when there is at least
716600dp of width available for your application's UI.</p>
717
718<p>You should either pick a width and design to it as your minimum size, or test what is the
719smallest width your layout supports once it's complete.</p>
720
721<p class="note"><strong>Note:</strong> Remember that all the figures used with these new size APIs
722are density-independent pixel (dp) values and your layout dimensions should also always be defined
723using dp units, because what you care about is the amount of screen space available after the system
724accounts for screen density (as opposed to using raw pixel resolution). For more information about
725density-independent pixels, read <a href="#terms">Terms and concepts</a>, earlier in this
726document.</p>
727
728
729<h3 id="NewQualifiers">Using new size qualifiers</h3>
730
731<p>The different resource configurations that you can specify based on the space available for your
732layout are summarized in table 2. These new qualifiers offer you more control over the specific
733screen sizes your application supports, compared to the traditional screen size groups (small,
734normal, large, and xlarge).</p>
735
736<p class="note"><strong>Note:</strong> The sizes that you specify using these qualifiers are
737<strong>not the actual screen sizes</strong>. Rather, the sizes are for the width or height in dp
738units that are <strong>available to your activity's window</strong>. The Android system
739might use some of the screen for system UI (such as the system bar at the bottom of the screen or
740the status bar at the top), so some of the screen might not be available for your layout. Thus, the
741sizes you declare should be specifically about the sizes needed by your activity&mdash;the system
742accounts for any space used by system UI when declaring how much space it provides for your layout.
743Also beware that the <a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> is considered
744a part of your application's window space, although your layout does not declare it, so it reduces
745the space available for your layout and you must account for it in your design.</p>
746
747<p class="table-caption"><strong>Table 2.</strong> New configuration qualifiers for screen size
748(introduced in Android 3.2).</p>
749<table>
750  <tr><th>Screen configuration</th><th>Qualifier values</th><th>Description</th></tr>
751  <tr><td>smallestWidth</td>
752      <td><code>sw&lt;N&gt;dp</code><br/><br/>
753        Examples:<br/>
754        <code>sw600dp</code><br/>
755        <code>sw720dp</code><br/>
756      </td>
757      <td>
758        <p>The fundamental size of a screen, as indicated by the shortest dimension of the available
759screen area. Specifically, the device's smallestWidth is the shortest of the screen's available
760height and width (you may also think of it as the "smallest possible width" for the screen). You can
761use this qualifier to ensure that, regardless of the screen's current orientation, your
762application's has at least {@code <N>} dps of width available for its UI.</p>
763        <p>For example, if your layout requires that its smallest dimension of screen area be at
764least 600 dp at all times, then you can use this qualifier to create the layout resources, {@code
765res/layout-sw600dp/}. The system will use these resources only when the smallest dimension of
766available screen is at least 600dp, regardless of whether the 600dp side is the user-perceived
767height or width. The smallestWidth is a fixed screen size characteristic of the device; <strong>the
768device's smallestWidth does not change when the screen's orientation changes</strong>.</p>
769  <p>The smallestWidth of a device takes into account screen decorations and system UI. For
770example, if the device has some persistent UI elements on the screen that account for space along
771the axis of the smallestWidth, the system declares the smallestWidth to be smaller than the actual
772screen size, because those are screen pixels not available for your UI.</p>
773  <p>This is an alternative to the generalized screen size qualifiers (small, normal, large, xlarge)
774that allows you to define a discrete number for the effective size available for your UI.
775Using smallestWidth to determine the general screen size is useful because width is
776often the driving factor in designing a layout. A UI will often scroll vertically, but have fairly
777hard constraints on the minimum space it needs horizontally. The available width is also the key
778factor in determining whether to use a one-pane layout for handsets or multi-pane layout for
779tablets. Thus, you likely care most about what the smallest possible width will be on each
780device.</p>
781    </td>
782  </tr>
783    <tr>
784      <td>Available screen width</td>
785      <td><code>w&lt;N&gt;dp</code><br/><br/>
786        Examples:<br/>
787        <code>w720dp</code><br/>
788        <code>w1024dp</code><br/>
789      </td>
790      <td>
791        <p>Specifies a minimum available width in dp units at which the resources should be
792used&mdash;defined by the <code>&lt;N&gt;</code> value. The system's corresponding value for the
793width changes when the screen's orientation switches between landscape and portrait to
794reflect the current actual width that's available for your UI.</p>
795        <p>This is often useful to determine whether to use a multi-pane layout, because even on a
796tablet device, you often won't want the same multi-pane layout for portrait orientation as you do
797for landscape. Thus, you can use this to specify the minimum width required for the layout, instead
798of using both the screen size and orientation qualifiers together.</p>
799      </td>
800    </tr>
801    <tr>
802      <td>Available screen height</td>
803      <td><code>h&lt;N&gt;dp</code><br/><br/>
804        Examples:<br/>
805        <code>h720dp</code><br/>
806        <code>h1024dp</code><br/>
807        etc.
808      </td>
809      <td>
810        <p>Specifies a minimum screen height in dp units at which the resources should be
811used&mdash;defined by the <code>&lt;N&gt;</code> value. The system's corresponding value for
812the height changes when the screen's orientation switches between landscape and portrait to
813reflect the current actual height that's available for your UI.</p>
814        <p>Using this to define the
815height required by your layout is useful in the same way as <code>w&lt;N&gt;dp</code> is for
816defining the required width, instead of using both the screen size and orientation qualifiers.
817However, most apps won't need this qualifier, considering that UIs often scroll vertically and are
818thus more flexible with how much height is available, whereas the width is more rigid.</p>
819      </td>
820    </tr>
821</table>
822
823<p>While using these qualifiers might seem more complicated than using screen size groups, it should
824actually be simpler once you determine the requirements for your UI.  When you design your UI,
825the main thing you probably care about is the actual size at which your application switches between
826a handset-style UI and a tablet-style UI that uses multiple panes. The exact point of this switch
827will depend on your particular design&mdash;maybe you need a 720dp width for your tablet layout,
828maybe 600dp is enough, or 480dp, or some number between these. Using these qualifiers in table 2,
829you are in control of the precise size at which your layout changes.</p>
830
831<p>For more discussion about these size configuration qualifiers, see the <a
832href="{@docRoot}guide/topics/resources/providing-resources.html#SmallestScreenWidthQualifier">
833Providing Resources</a> document.</p>
834
835
836<h3 id="ConfigurationExamples">Configuration examples</h3>
837
838<p>To help you target some of your designs for different types of devices, here are some
839numbers for typical screen widths:</p>
840
841<ul>
842  <li>320dp: a typical phone screen (240x320 ldpi, 320x480 mdpi, 480x800 hdpi, etc).</li>
843  <li>480dp: a tweener tablet like the Streak (480x800 mdpi).</li>
844  <li>600dp: a 7” tablet (600x1024 mdpi).</li>
845  <li>720dp: a 10” tablet (720x1280 mdpi, 800x1280 mdpi, etc).</li>
846</ul>
847
848<p>Using the size qualifiers from table 2, your application can switch between your different layout
849resources for handsets and tablets using any number you want for width and/or height.  For example,
850if 600dp is the smallest available width supported by your tablet layout, you can provide these two
851sets of layouts:</p>
852
853<pre class="classic">
854res/layout/main_activity.xml           # For handsets
855res/layout-sw600dp/main_activity.xml   # For tablets
856</pre>
857
858<p>In this case, the smallest width of the available screen space must be 600dp in order for the
859tablet layout to be applied.</p>
860
861<p>For other cases in which you want to further customize your UI to differentiate between sizes
862such as 7” and 10” tablets, you can define additional smallest width layouts:</p>
863
864<pre class="classic">
865res/layout/main_activity.xml           # For handsets (smaller than 600dp available width)
866res/layout-sw600dp/main_activity.xml   # For 7” tablets (600dp wide and bigger)
867res/layout-sw720dp/main_activity.xml   # For 10” tablets (720dp wide and bigger)
868</pre>
869
870<p>Notice that the previous two sets of example resources use the "smallest width" qualifier, {@code
871sw<N>dp}, which specifies the smallest of the screen's two sides, regardless of the
872device's current orientation. Thus, using {@code sw<N>dp} is a simple way to specify the
873overall screen size available for your layout by ignoring the screen's orientation.</p>
874
875<p>However, in some cases, what might be
876important for your layout is exactly how much width or height is <em>currently</em> available. For
877example, if you have a two-pane layout with two fragments side by side, you might want to use it
878whenever the screen provides at least 600dp of width, whether the device is in landscape or
879portrait orientation. In this case, your resources might look like this:</p>
880
881<pre class="classic">
882res/layout/main_activity.xml         # For handsets (smaller than 600dp available width)
883res/layout-w600dp/main_activity.xml  # Multi-pane (any screen with 600dp available width or more)
884</pre>
885
886<p>Notice that the second set is using the "available width" qualifier, {@code w<N>dp}. This
887way, one device may actually use both layouts, depending on the orientation of the screen (if
888the available width is at least 600dp in one orientation and less than 600dp in the other
889orientation).</p>
890
891<p>If the available height is a concern for you, then you can do the same using the {@code
892h<N>dp} qualifier. Or, even combine the {@code w<N>dp} and {@code h<N>dp}
893qualifiers if you need to be really specific.</p>
894
895
896<h3 id="DeclaringScreenSizeSupport">Declaring screen size support</h3>
897
898<p>Once you've implemented your layouts for different screen sizes, it's equally important that you
899declare in your manifest file which screens your application supports.</p>
900
901<p>Along with the new configuration qualifiers for screen size, Android 3.2 introduces new
902attributes for the <a
903href="{@docRoot}guide/topics/manifest/supports-screens-element.html">&lt;supports-screens&gt;</a>
904manifest element:</p>
905
906<dl>
907
908  <dt><a
909href="{@docRoot}guide/topics/manifest/supports-screens-element.html#requiresSmallest">
910{@code android:requiresSmallestWidthDp}</a></dt>
911  <dd>Specifies the minimum smallestWidth required. The smallestWidth is the shortest dimension of
912the screen space (in {@code dp} units) that must be available to your application UI&mdash;that is,
913the shortest of the available screen's two dimensions. So, in order for a device to be considered
914compatible with your application, the device's smallestWidth must be equal to or greater than this
915value. (Usually, the value you supply for this is the "smallest width" that your layout supports,
916regardless of the screen's current orientation.)
917  <p>For example, if your application is only for tablet-style devices with a 600dp
918smallest available width:</p>
919<pre>
920&lt;manifest ... &gt;
921    &lt;supports-screens android:requiresSmallestWidthDp="600" /&gt;
922    ...
923&lt;/manifest&gt;
924</pre>
925  <p>However, if your application supports all screen sizes supported by Android (as small as
926426dp x 320dp), then you don't need to declare this attribute, because the smallest width your
927application requires is the smallest possible on any device.</p>
928
929  <p class="caution"><strong>Caution:</strong> The Android system does not pay attention to this
930attribute, so it does not affect how your application behaves at runtime. Instead, it is used
931to enable filtering for your application on services such as Google Play. However,
932<strong>Google Play currently does not support this attribute for filtering</strong> (on Android
9333.2), so you should continue using the other size attributes if your application does not support
934small screens.</p>
935</dd>
936
937  <dt><a
938href="{@docRoot}guide/topics/manifest/supports-screens-element.html#compatibleWidth">
939{@code android:compatibleWidthLimitDp}</a></dt>
940  <dd>This attribute allows you to enable <a
941href="{@docRoot}guide/practices/screen-compat-mode.html">screen compatibility mode</a> as a
942user-optional feature by specifying the maximum "smallest width" that your application
943supports. If the smallest side of a device's available screen is greater than your value here,
944users can still install your application, but are offered to run it in screen compatibility mode. By
945default, screen compatibility mode is disabled and your layout is resized to fit the screen as
946usual, but a button is available in the system bar that allows users to toggle screen compatibility
947mode on and off.
948  <p class="note"><strong>Note:</strong> If your application's layout properly resizes for large
949screens, you do not need to use this attribute. We recommend that you avoid using this
950attribute and instead ensure your layout resizes for larger screens by following the
951recommendations in this document.</p></dd>
952
953  <dt><a
954href="{@docRoot}guide/topics/manifest/supports-screens-element.html#largestWidth">
955{@code android:largestWidthLimitDp}</a></dt>
956  <dd>This attribute allows you to force-enable <a
957href="{@docRoot}guide/practices/screen-compat-mode.html">screen compatibility mode</a> by specifying
958the maximum "smallest width" that your application supports. If the smallest
959side of a device's available screen is greater than your value here, the application runs in screen
960compatibility mode with no way for the user to disable it.
961  <p class="note"><strong>Note:</strong> If your application's layout properly resizes for large
962screens, you do not need to use this attribute.  We recommend that you avoid using this
963attribute and instead ensure your layout resizes for larger screens by following the
964recommendations in this document.</p></dd>
965</dl>
966
967<p class="caution"><strong>Caution:</strong> When developing for Android 3.2 and higher, you
968should not use the older screen size attributes in combination with the attributes
969listed above. Using both the new attributes and the older size attributes might cause
970unexpected behavior.</p>
971
972<p>For more information about each of these attributes, follow the respective links above.</p>
973
974
975
976
977<h2 id="screen-independence">Best Practices</h2>
978
979<p>The objective of supporting multiple screens is to create an application that can function
980properly and look good on any of the generalized screen configurations supported by Android. The
981previous sections of this document provide information about how Android adapts your
982application to screen configurations and how you can customize the look of your application on
983different screen configurations. This section provides some additional tips and an overview of
984techniques that help ensure that your application scales properly for different screen
985configurations.</p>
986
987<p>Here is a quick checklist about how you can ensure that your application displays properly
988on different screens:</p>
989
990<ol>
991  <li>Use {@code wrap_content}, {@code match_parent}, or {@code dp} units when specifying
992dimensions in an XML layout file</li>
993  <li>Do not use hard coded pixel values in your application code</li>
994  <li>Do not use {@code AbsoluteLayout} (it's deprecated)</li>
995  <li>Supply alternative bitmap drawables for different screen densities</li>
996</ol>
997
998<p>The following sections provide more details.</p>
999
1000
1001<h3 id="use-relative">1. Use wrap_content, match_parent, or the dp unit for layout dimensions</h3>
1002
1003<p>When defining the <a
1004href="{@docRoot}reference/android/view/ViewGroup.LayoutParams.html#attr_android:layout_width"
1005>{@code android:layout_width}</a> and <a
1006href="{@docRoot}reference/android/view/ViewGroup.LayoutParams.html#attr_android:layout_height"
1007>{@code android:layout_height}</a> for
1008views in an XML layout file, using <code>"wrap_content"</code>,
1009<code>"match_parent"</code> or <code>dp</code> units guarantees that the view is
1010given an appropriate size on the current device screen.</p>
1011
1012<p>For instance, a view with a <code>layout_width="100dp"</code> measures 100 pixels wide on
1013medium-density screen and the system scales it up to 150 pixels wide on high-density screen, so
1014that the view occupies approximately the same physical space on the screen.</p>
1015
1016<p>Similarly, you should prefer the <code>sp</code> (scale-independent pixel) to define text
1017sizes. The <code>sp</code> scale factor depends on a user setting and the system scales the
1018size the same as it does for {@code dp}.</p>
1019
1020
1021<h3>2. Do not use hard-coded pixel values in your application code</h3>
1022
1023<p>For performance reasons and to keep the code simpler, the Android system uses pixels as the
1024standard unit for expressing dimension or coordinate values. That means that the dimensions of a
1025view are always expressed in the code using pixels, but always based on the current screen density.
1026For instance, if <code>myView.getWidth()</code> returns 10, the view is 10 pixels wide on the
1027current screen, but on a device with a higher density screen, the value returned might be 15. If you
1028use pixel values in your application code to work with bitmaps that are not pre-scaled for the
1029current screen density, you might need to scale the pixel values that you use in your code to match
1030the un-scaled bitmap source.</p>
1031
1032<p>If your application manipulates bitmaps or deals with pixel values at runtime, see the section
1033below about <a href="#DensityConsiderations">Additional Density Considerations</a>.</p>
1034
1035
1036<h3 id="avoid-absolute">3. Do not use AbsoluteLayout </h3>
1037
1038<p>Unlike the other layouts widgets, {@link android.widget.AbsoluteLayout} enforces
1039the use of fixed positions to lay out its child views, which can easily lead to user interfaces that
1040do not work well on different displays. Because of this, {@link android.widget.AbsoluteLayout} was
1041deprecated in Android 1.5 (API Level 3).</p>
1042
1043<p>You should instead use {@link android.widget.RelativeLayout}, which uses relative positioning
1044to lay out its child views. For instance, you can specify that a button widget should appear "to
1045the right of" a text widget.</p>
1046
1047
1048<h3>4. Use size and density-specific resources</h3>
1049
1050<p>Although the system scales your layout and drawable resources based on the current screen
1051configuration, you may want to make adjustments to the UI on different screen sizes and provide
1052bitmap drawables that are optimized for different densities. This essentially reiterates the
1053information from earlier in this document.</p>
1054
1055<p>If you need to control exactly how your application will look on various
1056screen configurations, adjust your layouts and bitmap drawables in configuration-specific
1057resource directories. For example, consider an icon that you want to display on
1058medium and high-density screens. Simply create your icon at two different sizes
1059(for instance 100x100 for medium-density and 150x150 for high-density) and put
1060the two variations in the appropriate directories, using the proper
1061qualifiers:</p>
1062
1063<pre class="classic">
1064res/drawable-mdpi/icon.png&nbsp;&nbsp;&nbsp;//for medium-density screens
1065res/drawable-hdpi/icon.png&nbsp;&nbsp;&nbsp;//for high-density screens
1066</pre>
1067
1068<p class="note"><strong>Note:</strong> If a density qualifier is not defined in a directory name,
1069the system assumes that the resources in that directory are designed for the baseline medium
1070density and will scale for other densities as appropriate.</p>
1071
1072<p>For more information about valid configuration qualifiers, see <a href="#qualifiers">Using
1073configuration qualifiers</a>, earlier in this document.</p>
1074
1075
1076
1077
1078
1079<h2 id="DensityConsiderations">Additional Density Considerations</h2>
1080
1081<p>This section describes more about how Android performs scaling for bitmap drawables on different
1082screen densities and how you can further control how bitmaps are drawn on different densities. The
1083information in this section shouldn't be important to most applications, unless you have encountered
1084problems in your application when running on different screen densities or your application
1085manipulates graphics.</p>
1086
1087<p>To better understand how you can support multiple densities when manipulating graphics at
1088runtime, you should understand that the system helps ensure the proper scale for bitmaps in the
1089following ways:</p>
1090
1091<ol>
1092<li><em>Pre-scaling of resources (such as bitmap drawables)</em>
1093
1094  <p>Based on the density of the current screen, the system uses any size- or density-specific
1095resources from your application and displays them without scaling. If resources are not available in
1096the correct density, the system loads the default resources and scales them up or down as needed to
1097match the current screen's density. The system assumes that default resources (those from a
1098directory without configuration qualifiers) are designed for the baseline screen density (mdpi),
1099unless they are loaded from a density-specific resource directory. Pre-scaling is, thus, what the
1100system does when resizing a bitmap to the appropriate size for the current screen
1101density.</p>
1102
1103  <p>If you request the dimensions of a pre-scaled resource, the system returns values
1104representing the dimensions <em>after</em> scaling. For example, a bitmap designed at 50x50 pixels
1105for an mdpi screen is scaled to 75x75 pixels on an hdpi screen (if there is no alternative resource
1106for hdpi) and the system reports the size as such.</p>
1107
1108<p>There are some situations in which you might not want Android to pre-scale
1109a resource. The easiest way to avoid pre-scaling is to put the resource in a resource directory
1110with the {@code nodpi} configuration qualifier. For example:</p>
1111
1112<pre class="classic">res/drawable-nodpi/icon.png</pre>
1113
1114<p>When the system uses the {@code icon.png} bitmap from this folder, it does not scale it
1115based on the current device density.</p>
1116</li>
1117
1118<li><em>Auto-scaling of pixel dimensions and coordinates</em>
1119
1120  <p>An application can disable pre-scaling by setting <a
1121href="{@docRoot}guide/topics/manifest/supports-screens-element.html#any">{@code
1122android:anyDensity}</a> to {@code "false"} in the manifest or programmatically for a {@link
1123android.graphics.Bitmap} by setting {@link android.graphics.BitmapFactory.Options#inScaled} to
1124{@code "false"}. In this case, the system auto-scales any absolute pixel coordinates and pixel
1125dimension values at draw time. It does this to ensure that pixel-defined screen elements are still
1126displayed at approximately the same physical size as they would be at the baseline screen density
1127(mdpi). The system handles this scaling transparently to the application and reports the scaled
1128pixel dimensions to the application, rather than physical pixel dimensions.</p>
1129
1130  <p>For instance, suppose a device has a WVGA high-density screen, which is 480x800 and about the
1131same size as a traditional HVGA screen, but it's running an application that has disabled
1132pre-scaling. In this case, the system will "lie" to the application when it queries for screen
1133dimensions, and report 320x533 (the approximate mdpi translation for the screen density). Then, when
1134the application does drawing operations, such as invalidating the rectangle from (10,10) to (100,
1135100), the system transforms the coordinates by scaling them the appropriate amount, and actually
1136invalidate the region (15,15) to (150, 150). This discrepancy may cause unexpected behavior if
1137your application directly manipulates the scaled bitmap, but this is considered a reasonable
1138trade-off to keep the performance of applications as good as possible. If you encounter this
1139situation, read the following section about <a href="#dips-pels">Converting dp units to pixel
1140units</a>.</p>
1141
1142  <p>Usually, <strong>you should not disable pre-scaling</strong>. The best way to support multiple
1143screens is to follow the basic techniques described above in <a href="#support">How to Support
1144Multiple Screens</a>.<p>
1145</li>
1146
1147</ol>
1148
1149
1150<p>If your application manipulates bitmaps or directly interacts with pixels on the screen in some
1151other way, you might need to take additional steps to support different screen densities. For
1152example, if you respond to touch gestures by counting the number of pixels that a finger
1153crosses, you need to use the appropriate density-independent pixel values, instead of actual
1154pixels.</p>
1155
1156
1157<h3 id="scaling">Scaling Bitmap objects created at runtime</h3>
1158
1159<div class="figure" style="width:300px">
1160<img src="{@docRoot}images/screens_support/scale-test.png" alt="" />
1161<p class="img-caption"><strong>Figure 5.</strong> Comparison of pre-scaled and auto-scaled
1162bitmaps.
1163</p>
1164</div>
1165
1166<p>If your application creates an in-memory bitmap (a {@link android.graphics.Bitmap} object), the
1167system assumes that the bitmap is designed for the baseline medium-density screen, by default, and
1168auto-scales the bitmap at draw time. The system applies "auto-scaling" to a {@link
1169android.graphics.Bitmap} when the bitmap has unspecified density properties. If you don't properly
1170account for the current device's screen density and specify the bitmap's density properties, the
1171auto-scaling can result in scaling artifacts the same as when you don't provide alternative
1172resources.</p>
1173
1174<p>To control whether a {@link android.graphics.Bitmap} created at runtime is scaled or not, you can
1175specify the density of the bitmap with {@link android.graphics.Bitmap#setDensity setDensity()},
1176passing a density constant from {@link android.util.DisplayMetrics}, such as {@link
1177android.util.DisplayMetrics#DENSITY_HIGH} or {@link android.util.DisplayMetrics#DENSITY_LOW}.</p>
1178
1179<p>If you're creating a {@link android.graphics.Bitmap} using {@link
1180android.graphics.BitmapFactory}, such as from a file or a stream, you can use {@link
1181android.graphics.BitmapFactory.Options BitmapFactory.Options} to define properties of the bitmap as
1182it already exists, which determine if or how the system will scale it. For example, you can use the
1183{@link android.graphics.BitmapFactory.Options#inDensity} field to define the density for which the
1184bitmap is designed and the {@link
1185android.graphics.BitmapFactory.Options#inScaled} field to specify whether the bitmap should scale to
1186match the current device's screen density.</p>
1187
1188<p>If you set the {@link
1189android.graphics.BitmapFactory.Options#inScaled} field to {@code false}, then you disable any
1190pre-scaling that the system may apply to the bitmap and the system will then auto-scale it at draw
1191time. Using auto-scaling instead of pre-scaling can be more CPU expensive, but uses
1192less memory.</p>
1193
1194<p>Figure 5 demonstrates the results of the pre-scale and auto-scale mechanisms when loading low
1195(120), medium (160) and high (240) density bitmaps on a high-density screen. The differences are
1196subtle, because all of the bitmaps are being scaled to match the current screen density, however the
1197scaled bitmaps have slightly different appearances depending on whether they are pre-scaled or
1198auto-scaled at draw time.</p>
1199
1200<p class="note"><strong>Note:</strong> In Android 3.0 and above, there should be no perceivable
1201difference between pre-scaled and auto-scaled bitmaps, due to improvements in the graphics
1202framework.</p>
1203
1204
1205
1206
1207
1208<h3 id="dips-pels">Converting dp units to pixel units</h3>
1209
1210<p>In some cases, you will need to express dimensions in <code>dp</code> and then convert them to
1211pixels. Imagine an application in which a scroll or fling gesture is recognized after the user's
1212finger has moved by at least 16 pixels. On a baseline screen, a user's must move by {@code 16 pixels
1213/ 160 dpi}, which equals 1/10th of an inch (or 2.5 mm) before the gesture is recognized. On a device
1214with a high-density display (240dpi), the user's must move by {@code 16 pixels / 240 dpi}, which
1215equals 1/15th of an inch (or 1.7 mm). The distance is much shorter and the application thus appears
1216more sensitive to the user.</p>
1217
1218<p>To fix this issue, the gesture threshold must be expressed in code in <code>dp</code> and then
1219converted to actual pixels. For example:</p>
1220
1221<pre>// The gesture threshold expressed in dp
1222private static final float GESTURE_THRESHOLD_DP = 16.0f;
1223
1224// Get the screen's density scale
1225final float scale = {@link android.content.ContextWrapper#getResources getResources()}.{@link
1226android.content.res.Resources#getDisplayMetrics getDisplayMetrics()}.density;
1227// Convert the dps to pixels, based on density scale
1228mGestureThreshold = (int) (GESTURE_THRESHOLD_DP * scale + 0.5f);</span>
1229
1230// Use mGestureThreshold as a distance in pixels...
1231</pre>
1232
1233<p>The {@link android.util.DisplayMetrics#density DisplayMetrics.density} field specifies the scale
1234factor you must use to convert {@code dp} units to pixels, according to the current screen density.
1235On a medium-density screen, {@link android.util.DisplayMetrics#density DisplayMetrics.density}
1236equals 1.0; on a high-density screen it equals 1.5; on an extra-high-density screen, it equals 2.0;
1237and on a low-density screen, it equals 0.75. This figure is the factor by which you should multiply
1238the {@code dp} units on order to get the actual pixel count for the current screen. (Then add {@code
12390.5f} to round the figure up to the nearest whole number, when converting to an integer.) For more
1240information, refer to the {@link android.util.DisplayMetrics DisplayMetrics} class.</p>
1241
1242<p>However, instead of defining an arbitrary threshold for this kind of event, you should
1243use pre-scaled configuration values that are available from {@link
1244android.view.ViewConfiguration}.</p>
1245
1246
1247<h4 id="pre-scaled-values">Using pre-scaled configuration values</h4>
1248
1249<p>You can use the {@link android.view.ViewConfiguration} class to access common distances,
1250speeds, and times used by the Android system. For instance, the
1251distance in pixels used by the framework as the scroll threshold can be obtained with {@link
1252android.view.ViewConfiguration#getScaledTouchSlop()}:</p>
1253
1254<pre>
1255private static final int GESTURE_THRESHOLD_DP = ViewConfiguration.get(myContext).getScaledTouchSlop();
1256</pre>
1257
1258<p>Methods in {@link android.view.ViewConfiguration} starting with the <code>getScaled</code> prefix
1259are guaranteed to return a value in pixels that will display properly regardless of the current
1260screen density.</p>
1261
1262
1263
1264
1265
1266
1267<h2 id="testing">How to Test Your Application on Multiple Screens</h2>
1268
1269<div class="figure" style="width:500px;margin:0">
1270  <img src="{@docRoot}images/screens_support/avds-config.png" alt="" />
1271  <p class="img-caption"><strong>Figure 6.</strong>
1272  A set of AVDs for testing screens support.</p>
1273</div>
1274
1275<p>Before publishing your application, you should thoroughly test it in all of the supported screen
1276sizes and densities. The Android SDK includes emulator skins you can use, which
1277replicate the sizes and densities of common screen configurations on which your application is
1278likely to run. You can also modify the default size, density, and resolution of the emulator skins
1279to replicate the characteristics of any specific screen. Using the emulator skins and additional
1280custom configurations allows you to test any possible screen configuration, so you don't
1281have to buy various devices just to test your application's screen support.</p>
1282
1283<p>To set up an environment for testing your application's screen support, you should create a
1284series of AVDs (Android Virtual Devices), using emulator skins and screen configurations that
1285emulate the screen sizes and densities you want your application to support. To do so, you can use
1286the AVD Manager to create the AVDs and launch them with a graphical interface.</p>
1287
1288<p>To launch the Android SDK Manager, execute the {@code
1289SDK Manager.exe} from your Android SDK directory (on Windows only) or execute {@code android} from
1290the {@code <sdk>/tools/} directory (on all platforms). Figure 6 shows the AVD
1291Manager with a selection of AVDs, for testing various screen configurations.</p>
1292
1293<p>Table 3 shows the various emulator skins that are available in the Android SDK, which you can use
1294to emulate some of the most common screen configurations.</p>
1295
1296<p>For more information about creating and using AVDs to test your application, see <a
1297href="{@docRoot}tools/devices/managing-avds.html">Managing AVDs with AVD
1298Manager</a>.</p>
1299
1300
1301<p class="table-caption" id="screens-table"><strong>Table 3.</strong> Various screen
1302configurations available from emulator skins in the Android SDK (indicated in bold) and other
1303representative resolutions.</p>
1304
1305  <table class="normal-headers">
1306    <tbody>
1307    <tr>
1308      <th></th>
1309      <th>
1310        <nobr>Low density (120), <em>ldpi</em></nobr>
1311      </th>
1312      <th>
1313        <nobr>Medium density (160), <em>mdpi</em></nobr>
1314      </th>
1315      <th>
1316        <nobr>High density (240), <em>hdpi</em><nobr>
1317      </th>
1318      <th>
1319        <nobr>Extra-high-density (320), <em>xhdpi</em><nobr>
1320      </th>
1321    </tr>
1322    <tr>
1323      <th>
1324        <em>Small</em> screen
1325      </th>
1326      <td><strong>QVGA (240x320)</strong></td>
1327      <td></td>
1328      <td>480x640</td>
1329      <td></td>
1330    </tr>
1331    <tr>
1332      <th>
1333        <em>Normal</em> screen
1334      </th>
1335      <td><strong>WQVGA400 (240x400)</strong>
1336        <br><strong>WQVGA432 (240x432)</strong></td>
1337      <td><strong>HVGA (320x480)</strong></td>
1338      <td><strong>WVGA800 (480x800)</strong>
1339        <br><strong>WVGA854 (480x854)</strong>
1340        <br>600x1024</td>
1341      <td>640x960</td>
1342    </tr>
1343    <tr>
1344      <th>
1345        <em>Large</em> screen
1346      </th>
1347      <td><strong>WVGA800** (480x800)</strong>
1348        <br><strong>WVGA854** (480x854)</strong></td>
1349      <td><strong>WVGA800* (480x800)</strong>
1350        <br><strong>WVGA854* (480x854)</strong>
1351        <br>600x1024</td>
1352      <td></td>
1353      <td></td>
1354    </tr>
1355    <tr>
1356      <th>
1357        <em>Extra-Large</em> screen
1358      </th>
1359      <td>1024x600</td>
1360      <td><strong>WXGA (1280x800)</strong><sup>&dagger;</sup><br>
1361          1024x768<br>1280x768</td>
1362      <td>1536x1152<br>1920x1152
1363        <br>1920x1200</td>
1364      <td>2048x1536<br>2560x1536
1365        <br>2560x1600</td>
1366    </tr>
1367    <tr>
1368      <td colspan="5" style="border:none;font-size:85%;">* To emulate this configuration, specify a
1369custom density of 160 when creating an AVD that uses a WVGA800 or WVGA854 skin.<br/>
1370        ** To emulate this configuration, specify a custom density of 120 when creating an AVD that
1371uses a WVGA800 or WVGA854 skin.<br/>
1372        &dagger; This skin is available with the Android 3.0 platform
1373      </td>
1374    </tr>
1375</table>
1376
1377<p>To see the relative numbers of active devices that support any given screen configuration, see
1378the <a href="{@docRoot}resources/dashboard/screens.html">Screen Sizes and Densities</a>
1379dashboard.</p>
1380
1381<div class="figure" style="width:204px">
1382  <img src="{@docRoot}images/screens_support/avd-start.png" alt="" />
1383  <p class="img-caption"><strong>Figure 7.</strong>
1384  Size and density options you can set, when starting an AVD from the AVD
1385Manager.</p>
1386</div>
1387
1388<p>We also recommend that you test your application in an emulator that is set
1389up to run at a physical size that closely matches an actual device. This makes
1390it a lot easier to compare the results at various sizes and densities. To
1391do so you need to know the approximate density, in dpi, of your computer
1392monitor (for instance, a 30" Dell monitor has a density of about 96 dpi). When you launch an AVD
1393from the AVD Manager, you can specify the screen size for the emulator and your
1394monitor dpi in the Launch Options, as shown in figure 7.</p>
1395
1396<p>If you would like to test your application on a screen that uses a resolution
1397or density not supported by the built-in skins, you can create an AVD that uses a custom resolution
1398or density. When creating the AVD from the AVD Manager, specify the Resolution,
1399instead of selecting a Built-in Skin.</p>
1400
1401<p>If you are launching your AVD from the command line, you can specify the scale for
1402the emulator with the <code>-scale</code> option. For example:</p>
1403
1404<pre>emulator -avd &lt;avd_name&gt; -scale 96dpi</pre>
1405
1406<p>To refine the size of the emulator, you can instead pass the {@code -scale} option a number
1407between 0.1 and 3 that represents the desired scaling factor.</p>
1408
1409<p>For more information about creating AVDs from the command line, see <a
1410href="{@docRoot}tools/devices/managing-avds-cmdline.html">Managing AVDs from the
1411Command Line</a>.</p>
1412