frameworks_base/docs/html/guide/practices/screens_support.jd

page.title=Supporting Multiple Screens
@jd:body

<div id="qv-wrapper">
<div id="qv">

  <h2>Quickview</h2>
  <ul>
    <li>Android runs on devices that have different screen sizes and densities.</li>
    <li>The screen on which your application is displayed can affect its user interface.</li>
    <li>The system handles most of the work of adapting your app to the current screen.</li>
    <li>You should create screen-specific resources for precise control of your UI. </li>
  </ul>

  <h2>In this document</h2>
  <ol>
    <li><a href="#overview">Overview of Screen Support</a>
      <ol>
        <li><a href="#terms">Terms and concepts</a></li>
        <li><a href="#range">Range of screens supported</a></li>
        <li><a href="#density-independence">Density independence</a></li>
      </ol></li>
    <li><a href="#support">How to Support Multiple Screens</a>
      <ol>
        <li><a href="#qualifiers">Using configuration qualifiers</a></li>
        <li><a href="#DesigningResources">Designing alternative layouts and drawables</a></li>
      </ol></li>
    <li><a href="#screen-independence">Best Practices</a></li>
    <li><a href="#DensityConsiderations">Additional Density Considerations</a>
      <ol>
        <li><a href="#scaling">Scaling Bitmap objects created at runtime</a></li>
        <li><a href="#dips-pels">Converting dp units to pixel units</a></li>
      </ol></li>
    <li><a href="#testing">How to Test Your Application on Multiple Screens</a></li>
  </ol>

  <h2>Related samples</h2>
  <ol>
    <li><a href="{@docRoot}resources/samples/MultiResolution/index.html">Multiple
Resolutions</a></li>
  </ol>

  <h2>See also</h2>
  <ol>
    <li><a
href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">
Providing Alternative Resources</a></li>
    <li><a href="{@docRoot}guide/practices/ui_guidelines/icon_design.html">Icon Design
Guidelines</a></li>
    <li><a href="{@docRoot}guide/developing/devices/index.html">Managing Virtual Devices</a></li>
  </ol>

</div>
</div>

<p>Android runs on a variety of devices that offer different screen sizes and densities. For
applications, the Android system provides a consistent development environment across devices and
handles most of the work to adjust each application's user interface to the screen on which it is
displayed. At the same time, the system provides APIs that allow you to control your
application's UI on specific screen sizes and densities, in order to modify and optimize your UI
design for different screen configurations. For example, you might want a UI for tablets
that's different from the design for handsets.</p>

<p>Although the system performs sufficient scaling and resizing to make your application work on
different screens, you should make the effort to optimize your application for different screen
sizes and densities. In doing so, you maximize the user experience for all devices and your users
believe that your application was actually designed for <em>their</em> devices&mdash;rather than
simply stretched to fit their devices.</p>

<p>By following the practices described in this document, you can create an application that
displays properly and provides an optimized user experience on all supported screen configurations,
using a single {@code .apk} file.</p>

<p class="note"><strong>Note:</strong> The information in this document assumes that your
application is designed for Android 1.6 (API Level 4) or higher. If your application supports
Android 1.5 or lower, please first read <a
href="{@docRoot}guide/practices/screens-support-1.5.html">Strategies for Android 1.5</a>.</p>



<h2 id="overview">Overview of Screens Support</h2>

<p>This section provides an overview of Android's support for multiple screens, including: an
introduction to the terms and concepts used in this document and in the API, a summary of the screen
configurations that the system supports, and an overview of the API and underlying
screen-compatibility features.</p>

<h3 id="terms">Terms and concepts</h3>

<dl>
<dt><em>Screen size</em></dt>
  <dd>Actual physical size, measured as the screen's diagonal.

  <p>For simplicity, Android groups all actual screen sizes into four generalized sizes: small,
normal, large, and extra large.</p></dd>

<dt><em>Screen density</em></dt>
  <dd>The quantity of pixels within a physical area of the screen; usually referred to as dpi (dots
per inch). For example, a "low" density screen has fewer pixels within a given physical area,
compared to a "normal" or "high" density screen.</p>

  <p>For simplicity, Android groups all actual screen densities into four generalized densities:
low, medium, high, and extra high.</p></dd>

<dt><em>Orientation</em></dt>
  <dd>The orientation of the screen from the user's point of view. This is either landscape or
portrait, meaning that the screen's aspect ratio is either wide or tall, respectively. Be aware
that not only do different devices operate in different orientations by default, but the
orientation can change at runtime when the user rotates the device.
</dd>

<dt><em>Resolution</em></dt>
  <dd>The total number of physical pixels on a screen. When adding support for multiple screens,
applications do not work directly with resolution; applications should be concerned only with screen
size and density, as specified by the generalized size and density groups.</dd>

<dt><em>Density-independent pixel (dp)</em></dt>
  <dd>A virtual pixel unit that you should use when defining UI layout, to express layout dimensions
or position in a density-independent way.
  <p>The density-independent pixel is equivalent to one physical pixel on a 160 dpi screen, which is
the baseline density assumed by the system for a "medium" density screen. At runtime, the system
transparently handles any scaling of the dp units, as necessary, based on the actual density of the
screen in use. The conversion of dp units to screen pixels is simple: 
<nobr><code>px = dp * (dpi / 160)</code></nobr>.
For example, on a 240 dpi screen, 1 dp equals 1.5 physical pixels. You should always use dp units
when defining your application's UI, to ensure proper display of your UI on screens with different
densities. </p></dd>
</dl>


<h3 id="range">Range of screens supported</h3>

<p>Starting with Android 1.6 (API Level 4), Android provides support for multiple screen sizes and
densities, reflecting the many different screen configurations that a device may have. You can use
features of the Android system to optimize your application's user interface for each screen
configuration and ensure that your application not only renders properly, but provides the best
user experience possible on each screen.</p>

<p>To simplify the way that you design your user interfaces for multiple screens, Android divides
the range of actual screen sizes and densities into:</p>

<ul>
<li>A set of four generalized <strong>sizes</strong>: <em>small</em>, <em>normal</em>,
<em>large</em>,
and <em>xlarge</em></em>
<li>A set of four generalized <strong>densities</strong>: <em>ldpi</em> (low), <em>mdpi</em>
(medium),
<em>hdpi</em> (high), and <em>xhdpi</em> (extra high)
</ul>

<p>The generalized sizes and densities are arranged around a
baseline configuration that is a <em>normal</em> size and <em>mdpi</em> (medium) density. This
baseline is based upon the screen configuration for the first Android-powered device, the T-Mobile
G1, which has an HVGA screen (until Android 1.6, this was the only screen configuration that Android
supported).</p>

<p>Each generalized size or density spans a range of actual screen sizes or density. For example,
two devices that both report a screen size of <em>normal</em> might have actual screen sizes and
aspect ratios that are slightly different when measured by hand. Similarly, two devices that report
a screen density of <em>hdpi</em> might have real pixel densities that are slightly different.
Android makes these differences abstract to applications, so you can provide UI designed for the
generalized sizes and densities and let the system handle any final adjustments as necessary. Figure
1 illustrates how different sizes and densities are roughly categorized into the different size
and density groups.</p>

<img src="{@docRoot}images/screens_support/screens-ranges.png" style="padding:1em 0 0" alt="" />
<p class="img-caption"><strong>Figure 1.</strong>
Illustration of how Android roughly maps actual sizes and densities
to generalized sizes and densities (figures are not exact).</p>

<p>To optimize your application's UI for the different screen sizes and densities, you can provide
<a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">alternative
resources</a> for any of the generalized sizes and densities. Typically, you should
provide alternative layouts for some of the different screen sizes and alternative bitmap images for
different screen densities. At runtime, the system uses the appropriate size or density resources
for your application, based on the generalized size or density of the current device screen.</p>

<p>You do not need to provide alternative resources for every combination of screen size and
density. The system provides robust compatibility features that can handle most of the work of
rendering your application on any device screen, provided that you've implemented your UI using
techniques that allow it to gracefully resize (as described in the <a
href="#screen-independence">Best Practices</a>, below).</p>

<p class="note"><strong>Note:</strong> The characteristics that define a device's generalized screen
size and density are independent from each other. For example, a WVGA high-density screen is
considered a normal size screen because its physical size is about the same as the T-Mobile G1
(Android's first device and baseline screen configuration). On the other hand, a WVGA medium-density
screen is considered a large size screen. Although it offers the same resolution (the same number of
pixels), the WVGA medium-density screen has a lower screen density, meaning that each pixel is
physically larger and, thus, the entire screen is larger than the baseline (normal size) screen.</p>



<h3 id="density-independence">Density independence</h3>

<p>Your application achieves "density independence" when it preserves the physical size (from
the user's point of view) of user interface elements when displayed on screens with different
densities.</p>

<p>Maintaining density independence is important because, without it, a UI element (such as a
button) appears physically larger on a low density screen and smaller on a high density screen. Such
density-related size changes can cause problems in your application layout and usability. Figures 2
and 3 show the difference between an application when it does not provide density independence and
when it does, respectively.</p>

<img src="{@docRoot}images/screens_support/density-test-bad.png" alt=""  />
<p class="img-caption"><strong>Figure 2.</strong> Example application without support for
different densities, as shown on low, medium, and high density screens.</p>

<img src="{@docRoot}images/screens_support/density-test-good.png" alt="" />
<p class="img-caption"><strong>Figure 3.</strong> Example application with good support for
different densities (it's density independent), as shown on low, medium, and high
density screens.</p>

<p>The Android system helps your application achieve density independence in two ways: </p>

<ul>
<li>The system scales dp units as appropriate for the current screen density</li>
<li>The system scales drawable resources to the appropriate size, based on the current screen
density, if necessary</li>
</ul>

<p>In figure 2, the text view and bitmap drawable have dimensions specified in pixels ({@code px}
units), so the elements are physically larger on a low density screen and smaller on a high density
screen. This is because although the actual screen sizes may be the same, the high density screen
has more pixels per inch (the same amount of pixels fit in a smaller area). In figure 3, the layout
dimensions are specified in density-independent pixels ({@code dp} units). Because the baseline for
density-independent pixels is a medium-density screen, the device with a medium-density screen looks
the same as it does in figure 2. For the low-density and high-density screens, however, the system
scales the density-independent pixel values down and up, respectively, to fit the screen as
appropriate.</p>

<p>In most cases, you can ensure density independence in your application simply by specifying all
layout dimension values in density-independent pixels (<code>dp</code> units) or with {@code
"wrap_content"}, as appropriate. The system then scales bitmap drawables as appropriate in order to
display at the appropriate size, based on the appropriate scaling factor for the current screen's
density.</p>

<p>However, bitmap scaling can result in blurry or pixelated bitmaps, which you might notice in the
above screenshots. To avoid these artifacts, you should provide alternative bitmap resources for
different densities. For example, you should provide higher-resolution bitmaps for high-density
screens and the system will use those instead of resizing the bitmap designed for medium-density
screens. The following section describes more about how to supply alternative resources for
different screen configurations.</p>



<h2 id="support">How to Support Multiple Screens</h2>

<p>The foundation of Android's support for multiple screens is its ability to manage the rendering
of an application's layout and bitmap drawables in an appropriate way for the current screen
configuration. The system handles most of the work to render your application properly on each
screen configuration by scaling layouts to fit the screen size/density and scaling bitmap drawables
for the screen density, as appropriate. To more gracefully handle different screen configurations,
however, you should also:</p>

<ul>
  <li><strong>Provide different layouts for different screen sizes</strong>
    <p>By default, Android resizes your application layout to fit the current device screen. In most
cases, this works fine. In other cases, your UI might not look as good and might need adjustments
for different screen sizes. For example, on a larger screen, you might want to adjust the position
and size of some elements to take advantage of the additional screen space, or on a smaller screen,
you might need to adjust sizes so that everything can fit on the screen.</p>
    <p>The configuration qualifiers you can use to provide size-specific resources are
<code>small</code>, <code>normal</code>, <code>large</code>, and <code>xlarge</code>. For
example, layouts for an extra large screen should go in {@code layout-xlarge/}.</p>
  </li>
  
  <li><strong>Provide different bitmap drawables for different screen densities</strong>
    <p>By default, Android scales your bitmap drawables ({@code .png}, {@code .jpg}, and {@code
.gif} files) and Nine-Patch drawables ({@code .9.png} files) so that they render at the appropriate
physical size on each device. For example, if your application provides bitmap drawables only for
the baseline, medium screen density (mdpi), then the system scales them up when on a high-density
screen, and scales them down when on a low-density screen. This scaling can cause artifacts in the
bitmaps. To ensure your bitmaps look their best, you should include alternative versions at
different resolutions for different screen densities.</p>
    <p>The configuration qualifiers you can use for density-specific resources are
<code>ldpi</code> (low), <code>mdpi</code> (medium), <code>hdpi</code> (high), and
<code>xhdpi</code> (extra high). For example, bitmaps for high-density screens should go in
{@code drawable-hdpi/}.</p>
  </li>
</ul>

<p>The size and density configuration qualifiers correspond to the generalized sizes and densities
described in <a href="#range">Range of screens supported</a>, above.</p>

<p class="note"><strong>Note:</strong> If you're not familiar with configuration qualifiers and how
the system uses them to apply alternative resources, read <a
href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">Providing
Alternative Resources</a> for more information.</p>

<p>At runtime, the system ensures the best possible display on the current screen with
the following procedure for any given resource:</p>

<ol>
<li>The system uses the appropriate alternative resource
  <p>Based on the size and density of the current screen, the system uses any size- and
density-specific resource provided in your application. For example, if the device has a
high-density screen and the application requests a drawable resource, the system looks for a
drawable resource directory that best matches the device configuration. Depending on the other
alternative resources available, a resource directory with the {@code hdpi} qualifier (such as
{@code drawable-hdpi/}) might be the best match, so the system uses the drawable resource from this
directory.</p>
</li>

<li>If no matching resource is available, the system uses the default resource and scales it up
or down as needed to match the current screen size and density
  <p>The "default" resources are those that are not tagged with a configuration qualifier. For
example, the resources in {@code drawable/} are the default drawable resources. The system
assumes that default resources are designed for the baseline screen size and density, which is a
normal screen size and a medium density. As such, the system scales default density
resources up for high-density screens and down for low-density screens, as appropriate.</p>
  <p>However, when the system is looking for a density-specific resource and does not find it in
the density-specific directory, it won't always use the default resources. The system may
instead use one of the other density-specific resources in order to provide better results
when scaling. For example, when looking for a low-density resource and it is not available, the
system prefers to scale-down the high-density version of the resource, because the
system can easily scale a high-density resource down to low-density by a factor of 0.5, with 
fewer artifacts, compared to scaling a medium-density resource by a factor of 0.75.</p>
</li>
</ol>

  <p>For more information about how Android selects alternative resources by matching configuration
qualifiers to the device configuration, read
<a href="{@docRoot}guide/topics/resources/providing-resources.html#BestMatch">How Android
Finds the Best-matching Resource</a>.</p>




<h3 id="qualifiers">Using configuration qualifiers</h3>

<p>Android supports several configuration qualifiers that allow you to control how the system
selects your alternative resources based on the characteristics of the current device screen. A
configuration qualifier is a string that you can append to a resource directory in your Android
project and specifies the configuration for which the resources inside are designed.</p>

<p>To use a configuration qualifier:</p>
<ol>
  <li>Create a new directory in your project's {@code res/} directory and name it using the
format: <nobr>{@code &lt;resources_name&gt;-&lt;qualifier&gt;}</nobr>
    <ul>
      <li>{@code &lt;resources_name&gt;} is the standard resource name (such as {@code drawable} or
{@code layout}).</li>
      <li>{@code &lt;qualifier&gt;} is a configuration qualifier from table 1, below, specifying the
screen configuration for which these resources are to be used (such as {@code hdpi} or {@code
xlarge}).</li>
    </ul>
    <p>You can use more than one {@code &lt;qualifier&gt;} at a time&mdash;simply separate each
qualifier with a dash.</p>
  </li>
  <li>Save the appropriate configuration-specific resources in this new directory. The resource
files must be named exactly the same as the default resource files.</li>
</ol>

<p>For example, {@code xlarge} is a configuration qualifier for extra large screens. When you append
this string to a resource directory name (such as {@code layout-xlarge}), it indicates to the
system that these resources are to be used on devices that have an extra large screen.</p>

<p class="table-caption"><strong>Table 1.</strong> Configuration qualifiers that allow you to
provide special resources for different screen configurations.</p>

<table>
<tr>
<th>Screen characteristic</th>
<th>Qualifier</th>
<th>Description</th>
</tr>

<tr>
  <td rowspan="4">Size</td>
  <td><code>small</code></td>
  <td>Resources for <em>small</em> size screens.</td>
</tr>
<tr>
  <td><code>normal</code></td>
  <td>Resources for <em>normal</em> size screens. (This is the baseline size.)</td>
</tr>
<tr>
<td><code>large</code></td>
<td>Resources for <em>large</em> size screens.</td>
</tr>
<tr>
<td><code>xlarge</code></td>
<td>Resources for <em>extra large</em> size screens.</td>
</tr>

<tr>
<td rowspan="5">Density</td>
<td><code>ldpi</code></td>
<td>Resources for low-density (<em>ldpi</em>) screens (~120dpi).</td>
</tr>
<tr>
<td><code>mdpi</code></td>
<td>Resources for medium-density (<em>mdpi</em>) screens (~160dpi). (This is the baseline
density.)</td>
</tr>
<tr>
<td><code>hdpi</code></td>
<td>Resources for high-density (<em>hdpi</em>) screens (~240dpi).</td>
</tr>
<tr>
<td><code>xhdpi</code></td>
<td>Resources for extra high-density (<em>xhdpi</em>) screens (~320dpi).</td>
</tr>
<tr>
<td><code>nodpi</code></td>
<td>Resources for all densities. These are density-independent resources. The system does not
scale resources tagged with this qualifier, regardless of the current screen's density.</td>
</tr>

<tr>
<td rowspan="2">Orientation</td>
<td><code>land</code></td>
<td>Resources for screens in the landscape orientation (wide aspect ratio).</td>
</tr>
<tr>
<td><code>port</code></td>
<td>Resources for screens in the portrait orientation (tall aspect ratio).</td>
</tr>

<tr>
<td rowspan="2">Aspect ratio</td>
<td><code>long</code></td>
<td>Resources for screens that have a significantly taller or wider aspect ratio (when in portrait
or landscape orientation, respectively) than the baseline screen configuration.</td>
</tr>
<tr>
<td><code>notlong</code></td>
<td>Resources for use screens that have an aspect ratio that is similar to the baseline screen
configuration.</td>
</tr>
</table>

<p>For more information about how these qualifiers roughly correspond to real screen
sizes and densities, see <a href="#range">Range of Screens Supported</a>, earlier in this
document.</p>

<p>For example, the following is a list of resource directories in an application that
provides different layout designs for different screen sizes and different bitmap drawables
for medium, high, and extra high density screens.</p>

<pre class="classic">
res/layout/my_layout.xml             // layout for normal screen size ("default")
res/layout-small/my_layout.xml       // layout for small screen size
res/layout-large/my_layout.xml       // layout for large screen size
res/layout-xlarge/my_layout.xml      // layout for extra large screen size
res/layout-xlarge-land/my_layout.xml // layout for extra large in landscape orientation

res/drawable-mdpi/my_icon.png        // bitmap for medium density
res/drawable-hdpi/my_icon.png        // bitmap for high density
res/drawable-xhdpi/my_icon.png       // bitmap for extra high density
</pre>

<p>For more information about how to use alternative resources and a complete list of
configuration qualifiers (not just for screen configurations), see
<a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">
Providing Alternative Resources</a>.</p>

  <p class="note"><strong>Tip:</strong> If you have some drawable resources that the system
should never scale (perhaps because you perform some adjustments to the image yourself at
runtime), you should place them in a directory with the {@code nodpi} configuration qualifier.
Resources with this qualifier are considered density-agnostic and the system will not scale
them.</p>


<h3 id="DesigningResources">Designing alternative layouts and drawables</h3>

<p>The types of alternative resources you should create depends on your application's needs.
Usually, you should use the size and orientation qualifiers to provide alternative layout resources
and use the density qualifiers to provide alternative bitmap drawable resources.</p>

<p>The following sections summarize how you might want to use the size and density qualifiers to
provide alternative layouts and drawables, respectively.</p>


<h4>Alternative layouts</h4>

<p>Generally, you'll know whether you need alternative layouts for different screen sizes once
you test your application on different screen configurations. For example:</p>

<ul>
  <li>When testing on a small screen, you might discover that your layout doesn't quite fit on the
screen. For example, a row of buttons might not fit within the width of the screen on a small screen
device. In this case you should provide an alternative layout for small screens that adjusts the
size or position of the buttons.</li>
  <li>When testing on an extra large screen, you might realize that your layout doesn't make
efficient use of the big screen and is obviously stretched to fill it.
In this case, you should provide an alternative layout for extra large screens that provides a
redesigned UI that is optimized for bigger screens such as tablets. 
    <p>Although your application should work fine without an alternative layout on big screens, it's
quite important to users that your application looks as though it's designed specifically for their
devices. If the UI is obviously stretched, users are more likely to be unsatisfied with the
application experience.</p></li>
  <li>And, when testing in the landscape orientation compared to the portrait orientation, you
might notice that UI elements placed at the bottom of the screen for the portrait orientation
should instead be on the right side of the screen in landscape orientation.</li>
</ul>

<p>To summarize, you should be sure that your application layout:</p>
<ul>
  <li>Fits on small screens (so users can actually use your application)</li>
  <li>Is optimized for bigger screens to take advantage of the additional screen space</li>
  <li>Is optimized for both landscape and portrait orientations</li>
</ul>

<p>If your UI uses bitmaps that need to fit the size of a view even after the system scales
the layout (such as the background image for a button), you should use <a
href="{@docRoot}guide/topics/graphics/2d-graphics.html#nine-patch">Nine-Patch</a> bitmap files. A
Nine-Patch file is basically a PNG file in which you specific two-dimensional regions that are
stretchable. When the system needs to scale the view in which the bitmap is used, the system
stretches the Nine-Patch bitmap, but stretches only the specified regions. As such, you don't
need to provide different drawables for different screen sizes, because the Nine-Patch bitmap can
adjust to any size. You should, however, provide alternate versions of your Nine-Patch files for
different screen densities.</p>


<h4>Alternative drawables</h4>

<div class="figure" style="width:223px;margin:0">
<img src="{@docRoot}images/screens_support/screens-densities.png" alt="" />
<p class="img-caption"><strong>Figure 4.</strong> Relative sizes for bitmap drawables
that support each density.</p>
</div>

<p>Almost every application should have alternative drawable resources for different screen
densities, because almost every application has a launcher icon and that icon should look good on
all screen densities. Likewise, if you include other bitmap drawables in your application (such
as for menu icons or other graphics in your application), you should provide alternative versions or
each one, for different densities.</p>

<p class="note"><strong>Note:</strong> You only need to provide density-specific drawables for
bitmap files ({@code .png}, {@code .jpg}, or {@code .gif}) and Nine-Path files ({@code
.9.png}). If you use XML files to define shapes, colors, or other <a
href="{@docRoot}guide/topics/resources/drawable-resource.html">drawable resources</a>, you should
put one copy in the default drawable directory ({@code drawable/}).</p>

<p>To create alternative bitmap drawables for different densities, you should follow the
<b>3:4:6:8 scaling ratio</b> between the four generalized densities. For example, if you have
a bitmap drawable that's 48x48 pixels for medium-density screen (the size for a launcher icon),
all the different sizes should be:</p>

<ul>
  <li>36x36 for low-density</li>
  <li>48x48 for medium-density</li>
  <li>72x72 for high-density</li>
  <li>96x96 for extra high-density</li>
</ul>

<p>For more information about designing icons, see the <a
href="{@docRoot}guide/practices/ui_guidelines/icon_design.html">Icon Design Guidelines</a>,
which includes size information for various bitmap drawables, such as launcher icons, menu
icons, status bar icons, tab icons, and more.</p>



<h2 id="screen-independence">Best Practices</h2>

<p>The objective of supporting multiple screens is to create an application that can function
properly and look good on any of the generalized screen configurations supported by Android. The
previous sections of this document provide information about how Android adapts your
application to screen configurations and how you can customize the look of your application on
different screen configurations. This section provides some additional tips and an overview of
techniques that help ensure that your application scales properly for different screen
configurations.</p>

<p>Here is a quick checklist about how you can ensure that your application displays properly
on different screens:</p>

<ol>
  <li>Use {@code wrap_content}, {@code fill_parent}, or {@code dp} units when specifying
dimensions in an XML layout file</li>
  <li>Do not use hard coded pixel values in your application code</li>
  <li>Do not use {@code AbsoluteLayout} (it's deprecated)</li>
  <li>Supply alternative bitmap drawables for different screen densities</li>
</ol>

<p>The following sections provide more details.</p>


<h3 id="use-relative">1. Use wrap_content, fill_parent, or the dp unit for layout dimensions</h3>

<p>When defining the <a
href="{@docRoot}reference/android/view/ViewGroup.LayoutParams.html#attr_android:layout_width"
>{@code android:layout_width}</a> and <a
href="{@docRoot}reference/android/view/ViewGroup.LayoutParams.html#attr_android:layout_height"
>{@code android:layout_height}</a> for
views in an XML layout file, using <code>"wrap_content"</code>,
<code>"fill_parent"</code> or <code>dp</code> units guarantees that the view is
given an appropriate size on the current device screen.</p>

<p>For instance, a view with a <code>layout_width="100dp"</code> measures 100 pixels wide on
medium-density screen and the system scales it up to 150 pixels wide on high-density screen, so
that the view occupies approximately the same physical space on the screen.</p>

<p>Similarly, you should prefer the <code>sp</code> (scale-independent pixel) to define text
sizes. The <code>sp</code> scale factor depends on a user setting and the system scales the
size the same as it does for {@code dp}.</p>


<h3>2. Do not use hard-coded pixel values in your application code</h3>

<p>For performance reasons and to keep the code simpler, the Android system uses pixels as the
standard unit for expressing dimension or coordinate values. That means that the dimensions of a
view are always expressed in the code using pixels, but always based on the current screen density.
For instance, if <code>myView.getWidth()</code> returns 10, the view is 10 pixels wide on the
current screen, but on a device with a higher density screen, the value returned might be 15. If you
use pixel values in your application code to work with bitmaps that are not pre-scaled for the
current screen density, you might need to scale the pixel values that you use in your code to match
the un-scaled bitmap source.</p>

<p>If your application manipulates bitmaps or deals with pixel values at runtime, see the section
below about <a href="#DensityConsiderations">Additional Density Considerations</a>.</p>


<h3 id="avoid-absolute">3. Do not use AbsoluteLayout </h3>

<p>Unlike the other layouts widgets, {@link android.widget.AbsoluteLayout} enforces
the use of fixed positions to lay out its child views, which can easily lead to user interfaces that
do not work well on different displays. Because of this, {@link android.widget.AbsoluteLayout} was
deprecated in Android 1.5 (API Level 3).</p>

<p>You should instead use {@link android.widget.RelativeLayout}, which uses relative positioning
to lay out its child views. For instance, you can specify that a button widget should appear "to
the right of" a text widget.</p>


<h3>4. Use size and density-specific resources</h3>

<p>Although the system scales your layout and drawable resources based on the current screen
configuration, you may want to make adjustments to the UI on different screen sizes and provide
bitmap drawables that are optimized for different densities. This essentially reiterates the
information from earlier in this document.</p>

<p>If you need to control exactly how your application will look on various
screen configurations, adjust your layouts and bitmap drawables in configuration-specific
resource directories. For example, consider an icon that you want to display on
medium and high density screens. Simply create your icon at two different sizes
(for instance 100x100 for medium density and 150x150 for high density) and put
the two variations in the appropriate directories, using the proper
qualifiers:</p>

<pre class="classic">
res/drawable-mdpi/icon.png&nbsp;&nbsp;&nbsp;//for medium-density screens
res/drawable-hdpi/icon.png&nbsp;&nbsp;&nbsp;//for high-density screens
</pre>

<p class="note"><strong>Note:</strong> If a density qualifier is not defined in a directory name,
the system assumes that the resources in that directory are designed for the baseline medium
density and will scale for other densities as appropriate.</p>

<p>For more information about valid configuration qualifiers, see <a href="#qualifiers">Using
configuration qualifiers</a>, earlier in this document.</p>





<h2 id="DensityConsiderations">Additional Density Considerations</h2>

<p>This section describes more about how Android performs scaling for bitmap drawables on different
screen densities and how you can further control how bitmaps are drawn on different densities. The
information in this section shouldn't be important to most applications, unless you have encountered
problems in your application when running on different screen densities or your application
manipulates graphics.</p>

<p>To better understand how you can support multiple densities when manipulating graphics at
runtime, you should understand that the system helps ensure the proper scale for bitmaps in the
following ways:</p>

<ol>
<li><em>Pre-scaling of resources (such as bitmap drawables)</em>

  <p>Based on the density of the current screen, the system uses any size- or density-specific
resources from your application and displays them without scaling. If resources are not available in
the correct density, the system loads the default resources and scales them up or down as needed to
match the current screen's density. The system assumes that default resources (those from a
directory without configuration qualifiers) are designed for the baseline screen density (mdpi),
unless they are loaded from a density-specific resource directory. Pre-scaling is, thus, what the
system does when resizing a bitmap to the appropriate size for the current screen
density.</p>

  <p>If you request the dimensions of a pre-scaled resource, the system returns values
representing the dimensions <em>after</em> scaling. For example, a bitmap designed at 50x50 pixels
for an mdpi screen is scaled to 75x75 pixels on an hdpi screen (if there is no alternative resource
for hdpi) and the system reports the size as such.</p>

<p>There are some situations in which you might not want Android to pre-scale
a resource. The easiest way to avoid pre-scaling is to put the resource in a resource directory
with the {@code nodpi} configuration qualifier. For example:</p>

<pre class="classic">res/drawable-nodpi/icon.png</pre>

<p>When the system uses the {@code icon.png} bitmap from this folder, it does not scale it
based on the current device density.</p>
</li>

<li><em>Auto-scaling of pixel dimensions and coordinates</em>

  <p>An application can disable pre-scaling by setting <a
href="{@docRoot}guide/topics/manifest/supports-screens-element.html#any">{@code
android:anyDensity}</a> to {@code "false"} in the manifest or programmatically for a {@link
android.graphics.Bitmap} by setting {@link android.graphics.BitmapFactory.Options#inScaled} to
{@code "false"}. In this case, the system auto-scales any absolute pixel coordinates and pixel
dimension values at draw time. It does this to ensure that pixel-defined screen elements are still
displayed at approximately the same physical size as they would be at the baseline screen density
(mdpi). The system handles this scaling transparently to the application and reports the scaled
pixel dimensions to the application, rather than physical pixel dimensions.</p>

  <p>For instance, suppose a device has a WVGA high-density screen, which is 480x800 and about the
same size as a traditional HVGA screen, but it's running an application that has disabled
pre-scaling. In this case, the system will "lie" to the application when it queries for screen
dimensions, and report 320x533 (the approximate mdpi translation for the screen density). Then, when
the application does drawing operations, such as invalidating the rectangle from (10,10) to (100,
100), the system transforms the coordinates by scaling them the appropriate amount, and actually
invalidate the region (15,15) to (150, 150). This discrepancy may cause unexpected behavior if
your application directly manipulates the scaled bitmap, but this is considered a reasonable
trade-off to keep the performance of applications as good as possible. If you encounter this
situation, read the following section about <a href="#dips-pels">Converting dp units to pixel
units</a>.</p>

  <p>Usually, <strong>you should not disable pre-scaling</strong>. The best way to support multiple
screens is to follow the basic techniques described above in <a href="#support">How to Support
Multiple Screens</a>.<p>
</li>

</ol>


<p>If your application manipulates bitmaps or directly interacts with pixels on the screen in some
other way, you might need to take additional steps to support different screen densities. For
example, if you respond to touch gestures by counting the number of pixels that a finger
crosses, you need to use the appropriate density-independent pixel values, instead of actual
pixels.</p>


<h3 id="scaling">Scaling Bitmap objects created at runtime</h3>

<div class="figure" style="width:300px">
<img src="{@docRoot}images/screens_support/scale-test.png" alt="" />
<p class="img-caption"><strong>Figure 5.</strong> Comparison of pre-scaled and auto-scaled
bitmaps, from <a
href="resources/samples/ApiDemos/src/com/example/android/apis/graphics/DensityActivity.html">
ApiDemos</a>.
</p>
</div>

<p>If your application creates an in-memory bitmap (a {@link android.graphics.Bitmap} object), the
system assumes that the bitmap is designed for the baseline medium-density screen, by default, and
auto-scales the bitmap at draw time. The system applies "auto-scaling" to a {@link
android.graphics.Bitmap} when the bitmap has unspecified density properties. If you don't properly
account for the current device's screen density and specify the bitmap's density properties, the
auto-scaling can result in scaling artifacts the same as when you don't provide alternative
resources.</p>

<p>To control whether a {@link android.graphics.Bitmap} created at runtime is scaled or not, you can
specify the density of the bitmap with {@link android.graphics.Bitmap#setDensity setDensity()},
passing a density constant from {@link android.util.DisplayMetrics}, such as {@link
android.util.DisplayMetrics#DENSITY_HIGH} or {@link android.util.DisplayMetrics#DENSITY_LOW}.</p>

<p>If you're creating a {@link android.graphics.Bitmap} using {@link
android.graphics.BitmapFactory}, such as from a file or a stream, you can use {@link
android.graphics.BitmapFactory.Options BitmapFactory.Options} to define properties of the bitmap as
it already exists, which determine if or how the system will scale it. For example, you can use the
{@link android.graphics.BitmapFactory.Options#inDensity} field to define the density for which the
bitmap is designed and the {@link
android.graphics.BitmapFactory.Options#inScaled} field to specify whether the bitmap should scale to
match the current device's screen density.</p>

<p>If you set the {@link
android.graphics.BitmapFactory.Options#inScaled} field to {@code false}, then you disable any
pre-scaling that the system may apply to the bitmap and the system will then auto-scale it at draw
time. Using auto-scaling instead of pre-scaling can be more CPU expensive, but uses
less memory.</p>

<p>Figure 5 demonstrates the results of the pre-scale and auto-scale mechanisms when loading low
(120), medium (160) and high (240) density bitmaps on a high-density screen. The differences are
subtle, because all of the bitmaps are being scaled to match the current screen density, however the
scaled bitmaps have slightly different appearances depending on whether they are pre-scaled or
auto-scaled at draw time. You can find the source code for this sample application, which
demonstrates using pre-scaled and auto-scaled bitmaps, in <a
href="resources/samples/ApiDemos/src/com/example/android/apis/graphics/DensityActivity.html">
ApiDemos</a>.</p>

<p class="note"><strong>Note:</strong> In Android 3.0 and above, there should be no perceivable
difference between pre-scaled and auto-scaled bitmaps, due to improvements in the graphics
framework.</p>





<h3 id="dips-pels">Converting dp units to pixel units</h3>

<p>In some cases, you will need to express dimensions in <code>dp</code> and then convert them to
pixels. Imagine an application in which a scroll or fling gesture is recognized after the user's
finger has moved by at least 16 pixels. On a baseline screen, a user's must move by {@code 16 pixels
/ 160 dpi}, which equals 1/10th of an inch (or 2.5 mm) before the gesture is recognized. On a device
with a high density display (240dpi), the user's must move by {@code 16 pixels / 240 dpi}, which
equals 1/15th of an inch (or 1.7 mm). The distance is much shorter and the application thus appears
more sensitive to the user.</p> 

<p>To fix this issue, the gesture threshold must be expressed in code in <code>dp</code> and then
converted to actual pixels. For example:</p>

<pre>// The gesture threshold expressed in dp
private static final float GESTURE_THRESHOLD_DP = 16.0f;

// Get the screen's density scale
final float scale = {@link android.content.ContextWrapper#getResources getResources()}.{@link
android.content.res.Resources#getDisplayMetrics getDisplayMetrics()}.density;
// Convert the dps to pixels, based on density scale
mGestureThreshold = (int) (GESTURE_THRESHOLD_DP * scale + 0.5f);</span>

// Use mGestureThreshold as a distance in pixels...
</pre>

<p>The {@link android.util.DisplayMetrics#density DisplayMetrics.density} field specifies the scale
factor you must use to convert {@code dp} units to pixels, according to the current screen density.
On a medium-density screen, {@link android.util.DisplayMetrics#density DisplayMetrics.density}
equals 1.0; on a high-density screen it equals 1.5; on an extra high-density screen, it equals 2.0;
and on a low-density screen, it equals 0.75. This figure is the factor by which you should multiply
the {@code dp} units on order to get the actual pixel count for the current screen. (Then add {@code
0.5f} to round the figure up to the nearest whole number, when converting to an integer.) For more
information, refer to the {@link android.util.DisplayMetrics DisplayMetrics} class.</p>

<p>However, instead of defining an arbitrary threshold for this kind of event, you should
use pre-scaled configuration values that are available from {@link
android.view.ViewConfiguration}.</p>


<h4 id="pre-scaled-values">Using pre-scaled configuration values</h4>

<p>You can use the {@link android.view.ViewConfiguration} class to access common distances,
speeds, and times used by the Android system. For instance, the
distance in pixels used by the framework as the scroll threshold can be obtained with {@link
android.view.ViewConfiguration#getScaledTouchSlop()}:</p>

<pre>
private static final int GESTURE_THRESHOLD_DP = ViewConfiguration.get(myContext).getScaledTouchSlop();
</pre>

<p>Methods in {@link android.view.ViewConfiguration} starting with the <code>getScaled</code> prefix
are guaranteed to return a value in pixels that will display properly regardless of the current
screen density.</p>






<h2 id="testing">How to Test Your Application on Multiple Screens</h2>

<div class="figure" style="width:500px;margin:0">
  <img src="{@docRoot}images/screens_support/avds-config.png" alt="" />
  <p class="img-caption"><strong>Figure 6.</strong>
  A set of AVDs for testing screens support.</p>
</div>

<p>Before publishing your application, you should thoroughly test it in all of the supported screen
sizes and densities. The Android SDK includes emulator skins you can use, which
replicate the sizes and densities of common screen configurations on which your application is
likely to run. You can also modify the default size, density, and resolution of the emulator skins
to replicate the characteristics of any specific screen. Using the emulator skins and additional
custom configurations allows you to test any possible screen configuration, so you don't
have to buy various devices just to test your application's screen support.</p>

<p>To set up an environment for testing your application's screen support, you should create a
series of AVDs (Android Virtual Devices), using emulator skins and screen configurations that
emulate the screen sizes and densities you want your application to support. To do so, you can use
the Android SDK and AVD Manager to create the AVDs and launch them with a graphical interface.</p>

<p>To launch the Android SDK and AVD Manager, execute the {@code
SDK Manager.exe} from your Android SDK directory (on Windows only) or execute {@code android} from
the {@code &lt;sdk&gt;/tools/} directory (on all platforms). Figure 6 shows the Android SDK and
AVD Manager with a selection of AVDs, for testing various screen configurations.</p>

<p>Table 2 shows the various emulator skins that are available in the Android SDK, which you can use
to emulate some of the most common screen configurations.</p>

<p>For more information about creating and using AVDs to test your application, see <a
href="{@docRoot}guide/developing/devices/managing-avds.html">Managing AVDs with AVD
Manager</a>.</p>


<p class="table-caption" id="screens-table"><strong>Table 2.</strong> Various screen
configurations available from emulator skins in the Android SDK (indicated in bold) and other
representative resolutions.</p>

  <table class="normal-headers">
    <tbody>
    <tr>
      <th></th>
      <th>
        <nobr>Low density (120), <em>ldpi</em></nobr>
      </th>
      <th>
        <nobr>Medium density (160), <em>mdpi</em></nobr>
      </th>
      <th>
        <nobr>High density (240), <em>hdpi</em><nobr>
      </th>
      <th>
        <nobr>Extra high density (320), <em>xhdpi</em><nobr>
      </th>
    </tr>
    <tr>
      <th>
        <em>Small</em> screen
      </th>
      <td><strong>QVGA (240x320)</strong></td>
      <td></td>
      <td>480x640</td>
      <td></td>
    </tr>
    <tr>
      <th>
        <em>Normal</em> screen
      </th>
      <td><strong>WQVGA400 (240x400)</strong>
        <br><strong>WQVGA432 (240x432)</strong></td>
      <td><strong>HVGA (320x480)</strong></td>
      <td><strong>WVGA800 (480x800)</strong>
        <br><strong>WVGA854 (480x854)</strong>
        <br>600x1024</td>
      <td>640x960</td>
    </tr>
    <tr>
      <th>
        <em>Large</em> screen
      </th>
      <td><strong>WVGA800** (480x800)</strong>
        <br><strong>WVGA854** (480x854)</strong></td>
      <td><strong>WVGA800* (480x800)</strong>
        <br><strong>WVGA854* (480x854)</strong>
        <br>600x1024</td>
      <td></td>
      <td></td>
    </tr>
    <tr>
      <th>
        <em>Extra Large</em> screen
      </th>
      <td>1024x600</td>
      <td><strong>WXGA (1280x800)</strong><sup>&dagger;</sup><br>
          1024x768<br>1280x768</td>
      <td>1536x1152<br>1920x1152
        <br>1920x1200</td>
      <td>2048x1536<br>2560x1536
        <br>2560x1600</td>
    </tr>
    <tr>
      <td colspan="5" style="border:none;font-size:85%;">* To emulate this configuration, specify a
custom density of 160 when creating an AVD that uses a WVGA800 or WVGA854 skin.<br/>
        ** To emulate this configuration, specify a custom density of 120 when creating an AVD that
uses a WVGA800 or WVGA854 skin.<br/>
        &dagger; This skin is available with the Android 3.0 platform
      </td>
    </tr>
</table>

<p>To see the relative numbers of active devices that support any given screen configuration, see
the <a href="{@docRoot}resources/dashboard/screens.html">Screen Sizes and Densities</a>
dashboard.</p>

<div class="figure" style="width:204px">
  <img src="{@docRoot}images/screens_support/avd-start.png" alt="" />
  <p class="img-caption"><strong>Figure 7.</strong>
  Size and density options you can set, when starting an AVD from the Android SDK and AVD
Manager.</p>
</div>

<p>We also recommend that you test your application in an emulator that is set
up to run at a physical size that closely matches an actual device. This makes
it a lot easier to compare the results at various sizes and densities. To
do so you need to know the approximate density, in dpi, of your computer
monitor (for instance, a 30" Dell monitor has a density of about 96 dpi). When you launch an AVD
from the Android SDK and AVD Manager, you can specify the screen size for the emulator and your
monitor dpi in the Launch Options, as shown in figure 7.</p>

<p>If you would like to test your application on a screen that uses a resolution
or density not supported by the built-in skins, you can create an AVD that uses a custom resolution
or density. When creating the AVD from the Android SDK and AVD Manager, specify the Resolution,
instead of selecting a Built-in Skin.</p>

<p>If you are launching your AVD from the command line, you can specify the scale for
the emulator with the <code>-scale</code> option. For example:</p>

<pre>emulator -avd &lt;avd_name&gt; -scale 96dpi</pre>

<p>To refine the size of the emulator, you can instead pass the {@code -scale} option a number
between 0.1 and 3 that represents the desired scaling factor.</p>

<p>For more information about creating AVDs from the command line, see <a
href="{@docRoot}guide/developing/devices/managing-avds-cmdline.html">Managing AVDs from the
Command Line</a></p>