M7350/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 resolutions.</li>
    <li>The screen on which your application is displayed can affect its user interface.</li>
    <li>The platform handles most of the work of adapting your app to the current screen.</li>
    <li>You can create screen-specific resources for precise control of your UI, if needed. </li>
    <li>Older applications run in a compatibility mode that provides best-effort rendering on the current screen.</li>
    <li>It's important to follow the best practices described in this document and test your application in all supported screens. </li>
  </ul>

  <h2>In this document</h2>
  <ol>
    <li><a href="#overview">Overview of Screen Support</a></li>
    <ol>
       <li><a href="#range">Range of screens supported</a></li>
       <li><a href="#support">How Android supports multiple screens</a></li>
       <li><a href="#density-independence">Density independence</a></li>
       <li><a href="#attrs">Manifest attributes</a></li>
       <li><a href="#qualifiers">Resource qualifiers</a></li>
    </ol>
    <li style="padding-top:4px;"><a href="#screen-independence">Best Practices for Screen Independence</a></li>
    <li><a href="#strategies">Strategies for Legacy Apps</a></li>
    <li><a href="#testing">How to Test Your App</a></li>

  </ol>

  <h2>See Also</h2>
  <ol>
    <li><code><a href="{@docRoot}guide/topics/manifest/supports-screens-element.html">&lt;supports-screens&gt;</a></code></li>
    <li><code><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">&lt;uses-sdk&gt;</a></code></li>
    <li><a
href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">
Providing Alternative Resources</a></li>
    <li><a href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a></li>
  </ol>

</div>
</div>

<p>Android is designed to run on a variety of devices that offer a range of
screen sizes and resolutions. For applications, the platform provides a
consistent environment across devices and handles much of the complexity of
adapting an application's UI to the screen on which it is being displayed. At
the same time, the platform exposes APIs that give application developers
precise control over their application's UI when displayed on specific screen
sizes and resolutions. </p>

<p>This document explains the screens-support features provided by the platform
and how you use them in your application. By following the practices described
here, you can easily create an application that displays properly on all
supported device screens and that you can deploy to any device as a single {@code .apk}.
</p>

<p>If you have already developed and published an application for Android 1.5 or
earlier, you should read this document and consider how you may need to adapt
your application for proper display on new devices that offer different screens
and that are running Android 1.6 or later. In most cases, only minor adjustments
are needed, however you should make sure to <a href="#testing">test your
application</a> on all supported screens. </p>

<p>Starting in Android 2.2, the platform includes support for extra high density screens
(<em>xhdpi</em>), and starting in Android 2.3, the platform includes support for extra large screens
(<em>xlarge</em>). If you've already followed the guidance in this document to support all other
screen types, you should consider providing additional support for <em>xhdpi</em> and
<em>xlarge</em> screens.</p>

<p>In particular, if you have an existing application that you would like to
make available on small screens (such as QVGA) or for which you would like to provide better support
for extra large screens, please see <a href="#strategies">Strategies for Legacy Applications</a> for
more information about how to do that. </p>


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

<p>The sections below provide an overview of the Android platform's support for
multiple screens, including an introduction to terms and concepts used in this
document and in the API, a summary of the screen configurations that the
platform supports, and an overview of the API and underlying
screen-compatibility features.</p>


<h3>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 collapses all actual screen sizes into four
generalized sizes: small, normal, large, and extra large. Applications can provide custom
layouts for each of these four sizes &mdash; the platform transparently handles
the rendering of the layouts at the actual screen size.</p></dd>

<dt><em>Aspect ratio</em></dt>
  <dd>The porportional relationship of the screen's physical width to its
height. Applications can provide layout resources for specific aspect ratios by
using the resource qualifiers <code>long</code> and <code>notlong</code>. </dd>

<dt><em>Resolution</em></dt>
  <dd>The total number of physical pixels on a screen. Note that, although
resolution is often expressed as <em>width</em> x <em>height</em>, resolution
does not imply a specific aspect ratio. In Android, applications do not work
directly with resolution.</dd>

<dt><em>Density</em></dt>
  <dd>Based on the screen resolution, the spread of pixels across the physical
width and height of the screen.

  <p>A screen with lower density has fewer available pixels spread across the
screen width and height, where a screen with higher density has more &mdash;
sometimes significantly more &mdash; pixels spread across the same area. The
density of a screen is important because, other things being equal, a UI element
(such as a button) whose height and width are defined in terms of screen pixels
will appear larger on the lower density screen and smaller on the higher density
screen.</p>

  <p>For simplicity, Android collapses all actual screen densities into four
generalized densities: low, medium, large, and extra large. Applications can provide custom
resources for each of these densities &mdash; the platform handles any necessary
scaling of the resources up or down to meet the specific screen density. </p></dd>
<dt><em>Density-independent pixel (dp)</em></dt>
  <dd>A virtual pixel unit that applications can use in defining their UI, 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, the baseline density assumed by the platform (as described later in
this document). At run time, the platform transparently handles any scaling of
the dp units needed, based on the actual density of the screen in use. The
conversion of dp units to screen pixels is simple: <nobr><code>pixels = dps *
(density / 160)</code></nobr>. For example, on 240 dpi screen, 1 dp would equal 1.5
physical pixels. Using dp units to define your application's UI is highly
recommended, as a way of ensuring proper display of your UI on different
screens. </p></dd>
</dl>


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

<p>Starting from Android 1.6, the platform provides support for multiple screen
sizes and resolutions, reflecting the many new types and sizes of devices on
which the platform runs. If you are developing an application that will run
on Android 1.6 or later, you can use the compatibility features of the Android
platform to ensure that your application UI renders properly across the range of
supported screen sizes and resolutions.</p>

<p>To simplify the way that developers design their user interfaces for
multiple devices and to allow more devices to participate without affecting
applications, the platform divides the range of actual supported screen sizes
and resolutions into:</p>

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

<p class="note"><strong>Note:</strong> The <code>xhdpi</code> density category was added in
Android 2.2 (API Level 8). The <em>xlarge</em> size category was added in Android 2.3 (API Level
9).</p>

<p>Applications can provide custom resources (primarily layouts) for any of the
four generalized sizes and can provide resources (primarily drawables such as
images) for any of the four generalized densities. Applications do not need to
work with the actual physical size or density of the device screen. At run time,
the platform handles the loading of the correct size or density resources, based
on the generalized size or density of the current device screen, and adapts them
to the actual pixel map of the screen.</p>

<p>The generalized size/density configurations are arranged around a
baseline configuration that is assigned a size of <em>normal</em> and a density of
<em>mdpi</em> (medium). All applications written for Android 1.5 or earlier are (by
definition) designed for the baseline HVGA screen used on the T-Mobile G1 and
similar devices, which is size <em>normal</em> and density
<em>mdpi</em>.</p>

<p>Each generalized screen configuration spans a range of actual screen
densities and physical sizes. For example, that means that multiple devices that
report a screen size of <em>normal</em> might offer screens that differ slightly
in actual size or aspect ratio. Similarly, devices that report a screen density
of <em>hdpi</em> might offer screens with slightly different pixel densities.
The platform makes these differences abstract, however &mdash; applications can
offer UI designed for the generalized sizes and densities and let the system
handle the actual rendering of the UI on the current device screen according to
its characteristics. </p>


<img src="{@docRoot}images/screens_support/screens-ranges.png" />
<p class="img-caption"><strong>Figure 1.</strong>
Illustration of how the Android platform maps actual screen densities and sizes
to generalized density and size configurations. </p>

<p>Although the platform lets your application provide customized resources for
the various size and density configurations, you do not need to do write
custom code or provide custom resources for every combination of screen size and density.
The platform provides robust compatibility features, described
in the sections below, that can handle most of the work of rendering your
application on any device screen, provided that you've implemented your
application UI properly. For more information about how to implement a UI that
renders properly across device screens and platform versions, see
<a href="#screen-independence">Best Practices for Screen Independence</a>.</p>

<p>To help you test your applications, the Android SDK includes emulator skins
that replicate the sizes and densities of actual device screens on which your
application is likely to run. You can also modify the default size and density
of the emulator skins to replicate the characteristics of any specific
screen.</p>

<p class="table-caption" id="screens-table"><strong>Table 1.</strong> Screen
sizes and densities of emulator skins included in the Android SDK.</p>

  <table>
    <tbody>
    <tr>
      <td style="border:none"></td>
      <td style="background-color:#f3f3f3">
        <nobr>Low density (120), <em>ldpi</em></nobr>
      </td>
      <td style="background-color:#f3f3f3">
        <nobr>Medium density (160), <em>mdpi</em></nobr>
      </td>
      <td  style="background-color:#f3f3f3">
        <nobr>High density (240), <em>hdpi</em><nobr>
      </td>
      <td  style="background-color:#f3f3f3">
        <nobr>Extra high density (320), <em>xhdpi</em><nobr>
      </td>
    </tr>
    <tr>
      <td  style="background-color:#f3f3f3">
        <em>Small</em> screen
      </td>
      <td style="font-size:.9em;">QVGA (240x320)</td>
      </td>
      <td></td>
      <td></td>
      <td></td>
    </tr>
    <tr>
      <td style="background-color:#f3f3f3">
        <em>Normal</em> screen
      </td>
      <td style="font-size:.9em;">WQVGA400 (240x400)<br>WQVGA432 (240x432)</td>
      <td style="font-size:.9em;">HVGA (320x480)</td>
      <td style="font-size:.9em;">WVGA800 (480x800)<br>WVGA854 (480x854)</td>
      <td style="font-size:.9em;"></td>
    </tr>
    <tr>
      <td style="background-color:#f3f3f3">
        <em>Large</em> screen
      </td>
      <td></td>
      <td style="font-size:.9em;">WVGA800* (480x800)<br>WVGA854* (480x854)</td>
      <td></td>
      <td></td>
    </tr>
    <tr>
      <td style="background-color:#f3f3f3">
        <em>Extra Large</em> screen
      </td>
      <td></td>
      <td></td>
      <td></td>
      <td></td>
    </tr>
    <tr>
      <td colspan="4" style="border:none;font-size:90%;">* To emulate this
        configuration, specify a custom density of 160 when
        creating an AVD that uses a WVGA800 or WVGA854 skin.
      </td>
    </tr>
</table>

<p>For an overview of the relative numbers of high (hdpi), medium (mdpi), and
low (ldpi) density screens in Android-powered devices available now, see the <a
href="{@docRoot}resources/dashboard/screens.html">Screen Sizes and Densities</a> dashboard.</p>


<h3 id="support">How Android supports multiple screens</h3>

<div class="sidebox-wrapper">
<div class="sidebox">
<h2>Using the alternative resources framework</h2>

<p>The platform's support for loading screen size- and density-specific
resources at run time is based on the alternative resources framework.

<p> If you want to use size- or density-specific layouts or drawables in your
application and you are not familiar with resource qualifiers or how the
platform uses them, please read
<a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">
Providing Alternative Resources</a>.
</div>
</div>

<p>The foundation of Android's support for multiple screens is a set of built-in
compatibility features that together manage the rendering of application
resources in an appropriate way for the current device screen. The platform
handles most of the work of rendering your application, but also gives you two
key ways to control how your application is displayed, if you need or want
to use them:</p>

<ul>
  <li>The platform supports a set of resource qualifiers that let you provide
size- and density-specific resources, if needed. The qualifiers for
size-specific resources are <code>small</code>, <code>normal</code>, <code>large</code>, and
<code>xlarge</code>. Those for density-specific resources are <code>ldpi</code>
(low), <code>mdpi</code> (medium), <code>hdpi</code> (high), and <code>xhdpi</code> (extra high).
The qualifiers correspond to the generalized densities described in
<a href="#range">Range of screens supported</a>, above.</li>
  <li>The platform also provides a
<a href="{@docRoot}guide/topics/manifest/supports-screens-element.html">
<code>&lt;supports-screens&gt;</code></a>
manifest element, whose attributes
<code>android:smallScreens</code>, <code>android:normalScreens</code>,
<code>android:largeScreens</code>, and <code>android:xlargeScreens</code> let you specify what
generalized screen sizes
your application supports. Another attribute, <code>android:anyDensity</code>,
lets you indicate whether or not your application includes built-in support for
multiple densities.</li>
</ul>

<p>At run time, the platform provides three types of support to your
application, to ensure the best possible display on the current device
screen:</p>

<ol>
<li><em>Pre-scaling of resources (such as image assets)</em>

  <p>Based on the density of the current screen, the platform automatically
loads any size- or density-specific resources from your application and displays
them without scaling. If no matching resources are available, the platform loads
the default resources and scales them up or down as needed to match the current
screen's generalized density. The platform assumes that default resources are
designed for proper display at the baseline screen density of "medium" (160),
unless they are loaded from a density-specific resource directory.</p>

  <p>For example, if the current screen's density is "high", the platform loads
resources that are tagged with the qualifier <code>hdpi</code> and uses them
without scaling. If no such resources are available, the platform uses the
default resources instead, scaling them from the baseline density ("medium") to
"high".  </p>

  <p>For more information about how to create size- and density-specific
resources, see <a href="#qualifiers">Resource qualifiers</a>.</p></li>

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

  <p>If the application states that it does not support different screen
densities, the platform auto-scales any absolute pixel coordinates, pixel
dimension values, and pixel math used in the application (such as might be used
for specifying the width or padding for a view). It does this to ensure that
pixel-defined screen elements are displayed at approximately the same physical
size as they would be at the baseline density of "medium" (160). The platform
handles this scaling transparently to the application and also reports scaled
overall pixel dimensions to the application, rather than physical pixel
dimensions. </p>

  <p>For instance, suppose a given device is using a WVGA high-denisty screen,
which is 480x800 and about the same size as a traditional HVGA screen, but it's
running an app that states that it does not support multiple densities. In this
case, the system will "lie" to the application when it queries for screen
dimensions, and report 320x533. Then, when the app does drawing operations, such
as invalidating the rectangle from (10,10) to (100, 100), the system will
likewise automatically transform the coordinates by scaling them the appropriate
amount, and actually invalidate the region (15,15) to (150, 150).  The same
thing happens in the other direction, if the application is running on a
lower-density screen, coordinates are scaled down.<p>

  <p>For more information, see the <code>android:anyDensity</code> attribute in
<a href="#attrs">Manifest attributes for screens support</a>.</p></li>

<div class="sidebox-wrapper" xstyle="margin-bottom:2em;margin-top:.5em;width:90%;">
  <img id="rule" src="{@docRoot}assets/images/grad-rule-qv.png">
  <div id="qv-sub-rule">
    <img src="{@docRoot}assets/images/icon_market.jpg" style="float:left;margin:0;padding:0;">
    <p style="color:#669999;">Publishing to Small Screen Devices</p>
    <p>To ensure the best experience for users on small-screen devices, Android
Market only shows applications that explicitly declare support for small
screens. If you developed an application on Android 1.5 or earlier and published
it on Android Market, you need to <a href="#testing">test your application</a>
on small screens and then upload an updated version that explicitly
<a href="#attrs">indicates support for small screens</a>. </p>
  </div>
</div>

<li><em>Compatibility-mode display on larger screen-sizes</em>

  <p>If the current screen's size is larger than your application supports, as
specified in the <code>supports-screens</code> element, the platform displays
the application at the baseline size ("normal") and density ("medium). For
screens larger than baseline, the platform displays the application in a
baseline-sized portion of the overall screen, against a black background. </p>

  <p>For instance, suppose a given device is using a WVGA medium density screen,
classified as a "large" screen, but the application states that it does not
support large screens; in this case, the system will again "lie" to the
application when it queries for screen dimensions, and report 320x480.  Instead
of scaling the application, however, the application's 320x480 interface will be
placed as a "postage stamp" in the larger 480x800 screen.</p>

  <p>For more information, see the <code>android:anyDensity</code> attribute in
<a href="#attrs">Manifest elements for screens support</a> and the
<a href="#compatibility-examples">Screen-Compatibility Examples</a>
section.</p></li>
</ol>

<p>In general, these compatibility features ensure that all applications,
including those written against Android 1.5 and earlier platform versions, can
display properly on most devices, especially when the device's screen is at the
baseline "normal" size or larger. </p>

<p>However, note that applications written for the baseline screen may need
minor adjustments before they display properly on smaller screens such as QVGA.
With the reduced screen area of small screens, there may be tradeoffs in design,
content, and function that you, as the application developer, need to consider.
For more information about how to prepare an existing application for display on
small screens, see <a href="#strategies">Strategies for Legacy
Applications</a>.</p>

<p>The sections below provide more information how to take advantage of the
platform's multiple-screens support. </p>


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

<p>The goal of density independence is to preserve the physical size, from the
user's point of view, of user interface elements declared in an application,
when the application is displayed on screens with different densities. Density
independence applies to both layouts and drawables such as icons. Maintaining
density-independence is important because, other things being equal, a UI
element (such as a button) whose height and width are defined in terms of screen
pixels will appear physically larger on the lower density screen and smaller on
the higher density screen. Such density-related size changes can cause problems
in application layout, usability, and consistency with other applications
installed on the device.</p>

<p>The platform provides density independence to applications by default. It
does this in three ways: </p>

<ul>
<li>Through pre-scaling of drawable resources (scaled at resource loading
time)</li>
<li>Through auto-scaling of density-independent pixel (dp) values used in
layouts</li>
<li>Through auto-scaling of absolute pixel values used in the application (only
needed if the application has set <code>android:anyDensity="false"</code> in its
manifest)</li>
</ul>

<p>The example screens below illustrate the density independence provided by the
platform. Note that both the layouts and launcher icons are displayed at the
same physical sizes, although screen sizes, aspect ratios, and densities are
different.</p>


<div id=vi09 style=TEXT-ALIGN:left>
<img src="{@docRoot}images/screens_support/dip.png" style="padding-bottom:0;margin-bottom:0;" />
<p class="caption" style="margin:0 0 1.5em 1em;padding:0 0 0
1em;"><strong>Figure 2.</strong> Examples of density independence on WVGA high
density (left), HVGA medium density (center), and QVGA low density (right). </p>
</div>

<p>In most cases, you can take advantage of density independence in your
application simply by making sure that your layouts specify all dimension values
in density-independent pixels (<code>dp</code> or <code>dp</code>) or
scale-independent pixels (<code>sip</code> or <code>sp</code>, for text only).
If you are using absolute pixel values in the application and manifest includes
<a href="#attrs"><code>android:anyDensity="true"</code></a>, you will also need
to scale the pixel values. See <a href="#dips-pels">Converting dp units to
pixel units</a> for more information. </p>


<h3 id="attrs">Manifest attributes for screens support</h3>

<p> Android 1.6 introduced a new manifest element,
<a href="{@docRoot}guide/topics/manifest/supports-screens-element.html"><code>&lt;supports-screens&gt;</code></a>,
whose attributes you can use to control the
display of your application on different classes of device screens, as listed
in table 2. The <code>smallScreens</code>, <code>normalScreens</code>, <code>largeScreens</code> and
<code>xlargeScreens</code> attributes correspond to the generalized screen sizes
described in <a href="#range">Range of screens supported</a>, earlier in this
document. Notice that the default values for each attribute vary, depending
on your minimum and targeted platform, as indicated in the <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code
android:minSdkVersion}</a> and <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code
android:targetSdkVersion}</a> attributes of your <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code &lt;uses-sdk&gt;}</a>
manifest element.</p>

<p class="table-caption" id="table2"><strong>Table 2.</strong> Summary of attributes for the <a
href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
&lt;supports-screens&gt;}</a> manifest element, including default values based on platform
version.</p>
    <table id="vrr8">
      <tr>
        <th>
          Attribute
        </th>
        <th >
          Description
        </th>
        <th>
          Default value, when<br><nobr><code>minSdkVersion</code> or</nobr>
<code>targetSdkVersion</code> is 4 or lower
        </th>
        <th>
          Default value, when<br><nobr><code>minSdkVersion</code> or</nobr>
<code>targetSdkVersion</code> is 5 or higher
        </th>
      </tr>
      <tr>
        <td>
          <code>android:smallScreens</code>
        </td>
        <td>
          Whether or not the application UI is designed for use on
<em>small</em> screens &mdash; "<code>true</code>" if it is, and
"<code>false</code>" if not. </p>
        </td>
<td>"<code>false</code>"</td>
<td>"<code>true</code>"</td>
      </tr>
      <tr>
        <td>
          <code>android:normalScreens</code>
        </td>
        <td>
           Whether or not the application UI is designed for use on
<em>normal</em> screens &mdash; "<code>true</code>" if it is, and
"<code>false</code>" if not. The default value is always "<code>true</code>".
        </td>
<td>"<code>true</code>"</td>
<td>"<code>true</code>"</td>
      </tr>
      <tr>
        <td>
          <code>android:largeScreens</code>
        </td>
        <td>
           Whether or not the application UI is designed for use on
<em>large</em> screens &mdash; "<code>true</code>" if it is, and
"<code>false</code>" if not.
        </td>
<td>"<code>false</code>"</td>
<td>"<code>true</code>"</td>
      </tr>
      <tr>
        <td>
          <code>android:anyDensity</code>
        </td>
        <td>
         <p>Whether or not the application is designed to manage its UI properly
in different density environments &mdash; "<code>true</code>" if so, and
"<code>false</code>" if not. </p>
        <ul>
          <li>If set to "<code>true</code>", the platform disables its
density-compatibility features for all screen densities &mdash; specifically,
the auto-scaling of absolute pixel units (<code>px</code>) and math &mdash; and
relies on the application to use density-independent pixel units
(<code>dp</code>) and/or math to manage the adaptation of pixel values according
to density of the current screen. That is, as long as your application uses
density-independent units (dp) for screen layout sizes, then it will perform
properly on different densities when this attribute is set to
"<code>true</code>".</li>

          <li>If set to "<code>false</code>", the platform enables its
density-compatibility features for all screen densities. In this case, the
platform provides a scaled, virtual screen pixel map to the application, against
which it can layout and draw its UI as though against a medium-density screen
(160). The platform then transparently auto-scales the application's pixel units
and math as needed to match the actual device screen density. </li>
        </ul>
<p>Note that the setting of this attribute affects density-compatibility only.
It does not affect size-compatibility features such as display on a virtual
baseline screen.</p>
        </td>
<td>"<code>false</code>"</td>
<td>"<code>true</code>"</td>
      </tr>
      <tr>
        <td colspan="4"><strong>Note:</strong> Android 2.3 (API Level 9) introduced a new
attribute for the <code>&lt;supports-screens&gt;</code> element: <code>xlargeScreens</code>, shown
below. It works the same as the other screen attributes above, but, if neither your
<code>minSdkVersion</code> or <code>targetSdkVersion</code> are set to "9", the default value is
"false" when your application is installed on a device running Android 2.3.</td>
      </tr>
      <tr>
        <th>
          Attribute
        </th>
        <th >
          Description
        </th>
        <th>
          Default value, when<br><nobr><code>minSdkVersion</code> or</nobr>
<code>targetSdkVersion</code> is 8 or lower
        </th>
        <th>
          Default value, when<br><nobr><code>minSdkVersion</code> or</nobr>
<code>targetSdkVersion</code> is 9 or higher
        </th>
      </tr>
      <tr>
        <td>
          <code>android:xlargeScreens</code>
        </td>
        <td>
           Whether or not the application UI is designed for use on
<em>xlarge</em> screens &mdash; "<code>true</code>" if it is, and
"<code>false</code>" if not.
        </td>
<td>"<code>false</code>"</td>
<td>"<code>true</code>"</td>
      </tr>
    </table>

<p>In general, when you declare a screen-size attribute
(<code>smallScreens</code>, <code>normalScreens</code>, <code>largeScreens</code>, or
<code>xlargeScreens</code>) as "<code>true</code>", you are signaling to the
platform that your application is designed to render properly on that screen
size. As a result, the platform does not apply any size-compatibility features
(such as a virtual HVGA display area). If you declare a screen-size attribute as
"<code>false</code>", you are signaling that your application is <em>not</em>
designed for that screen size. In this case, the platform <em>does</em> apply
size-compatibility features, rendering the application in an HVGA baseline
display area. If the current screen is larger than <em>normal</em> size, the
platform renders the application in a virtual HVGA screen on the larger screen.
See <a href="#compatibility-examples">Screen-Compatibility Examples</a> for an
illustration of what an application looks like when displayed in a virtual HVGA
screen.</p>

<p>In other words, setting a <code>&lt;supports-screens&gt;</code> attribute to
"<code>false</code>" tells the platform to enable it's compatibility features
when displaying the application on a screen of that size <em>or any larger
size</em>, if also disallowed. Otherwise, the platform gives the application a
normal display area that can use the full device screen area, if
appropriate.</p>

<p>Android Market also makes use of the <code>&lt;supports-screens&gt;</code>
attributes. It uses them to filter the application from devices whose screens
are not supported by the application. Specifically, Android Market considers an
application compatible with a device if the application supports a screen that
is the same or smaller than the current device screen. Android Market filters
the application if it disallows the device's screen size and does not support a
smaller size. In general, Android does not provide downward size-compatibility
features for applications.</p>

<p>Here are some examples:</p>

<ul>
    <li>Assume that you declare <code>smallScreens="false" normalScreens="true"
largeScreens="false" xlargeScreens="false"</code> in your application's manifest. <p>Although the
application is not designed for display on large or extra large screens, the platform can still
run it successfully in <a href="#compatibility-examples">screen-compatibility
mode</a>. Android Market shows the application to devices with
<em>normal</em>, <em>large</em>, and <em>xlarge</em> size screens, but does filter it from
<em>small</em> size screens, because the application provides no screen support at
<em>small</em> size. Android's <a href="#compatibility-examples">screen-compatibility
mode</a> mode does not provide support for screens that are smaller than those the
application supports&mdash;it only provides support for screens that are larger. Thus,
although the application declares "false" for <em>large</em> and <em>xlarge</em> screens,
the application still functions, but runs in compatibility mode.</p></li>

    <li>Assume that you declare <code>smallScreens="false" normalScreens="false"
largeScreens="true" xlargeScreens="true"</code> in your application's manifest. <p>Android Market
filters the application from users of devices with <em>small</em> and
<em>normal</em> size screens. In effect, this prevents such users from
installing the application.</p></li>
</ul>

<p>If you declare the <code>android:anyDensity</code> attribute as
"<code>true</code>", you are signaling to the platform that your application is
designed to display properly on any screen density. In this case, the
application must ensure that it declares its UI dimensions using
density-independent pixels (<code>dp</code>) and scales any absolute pixel
values (<code>px</code>) or math by the scaling factor available from {@link
android.util.DisplayMetrics#density android.util.DisplayMetrics.density}. See <a
href="#dips-pels">Converting dp units to pixel units</a> for an example.</p>

<p>Note that the setting of the <code>android:anyDensity</code> attribute does
not affect the platform's pre-scaling of drawable resources, such as bitmaps and
nine-patch images, which always takes place by default. </p>

<p>The following example shows a manifest that declares support for small, normal, large, and
 xlarge screens in any density.</p>

<pre>
&lt;manifest xmlns:android="http://schemas.android.com/apk/res/android"&gt;
    &lt;supports-screens
        android:smallScreens="true"
        android:normalScreens="true"
        android:largeScreens="true"
        android:xlargeScreens="true"
        android:anyDensity="true" /&gt;
    ...
&lt;/manifest&gt;
</pre>
<!--  &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; android:resizeable="true" -->
<h4 id="defaults">
  Default values for attributes
</h4>

<p>The default values for the <code>&lt;supports-screens&gt;</code> attributes
differ, depending on the the value of the
<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code>android:minSdkVersion</code></a>
 attribute in the application's manifest, as well as on
the value of <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code
android:targetSdkVersion}</a>, if declared.</p>

<p>Above, <a href="#table2">table 2</a> indicates the default values for each attribute, based on
the values you provide for the <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code
android:minSdkVersion}</a> and <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code
android:targetSdkVersion}</a>, in the <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code &lt;uses-sdk&gt;}</a>
element.</p>

<p class="note"><strong>Note:</strong> If your application uses APIs introduced in Android 1.6 or
higher, but does not support specific screen densities and/or screen sizes, you need to explicitly
set the appropriate attributes to "<code>false</code>" (because most are "true", by default).</p>


<h3 id="qualifiers">Resource directory qualifiers for screen size and density</h3>

<p>Android supports resource directory qualifiers for controlling the selection
of resources based on the characteristics of the screen on which your application
is running. You can use these qualifiers to provide size- and density-specific
resources in your application. For more information about the generalized sizes
and densities that correspond to the qualifiers, see <a href="#range">Range
of Screens Supported</a>, earlier in this document.</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 designed for <em>small</em> size screens.</td>
</tr>
<tr>
  <td><code>normal</code></td>
  <td>Resources designed for <em>normal</em> size screens.</td>
</tr>
<tr>
<td><code>large</code></td>
<td>Resources designed for <em>large</em> size screens.</td>
</tr>
<tr>
<td><code>xlarge</code></td>
<td>Resources designed for <em>extra large</em> size screens.</td>
</tr>

<tr>
<td rowspan="5">Density</td>
<td><code>ldpi</code></td>
<td>Resources designed for low-density (<em>ldpi</em>) screens.</td>
</tr>
<tr>
<td><code>mdpi</code></td>
<td>Resources designed for medium-density (<em>mdpi</em>) screens.</td>
</tr>
<tr>
<td><code>hdpi</code></td>
<td>Resources designed for high-density (<em>hdpi</em>) screens.</td>
</tr>
<tr>
<td><code>xhdpi</code></td>
<td>Resources designed for extra high-density (<em>xhdpi</em>) screens.</td>
</tr>
<tr>
<td><code>nodpi</code></td>
<td>Density-independent resources. The platform does not auto-scale resources
tagged with this qualifier, regardless of the current screen's density.</td>
</tr>

<tr>
<td rowspan="2">Aspect ratio</td>
<td><code>long</code></td>
<td>Resources for screens of any size or density that have a significantly
taller (in portrait mode) and wider (in landscape mode) aspect ratio than the
baseline screen configuration.</td>
</tr>
<tr>
<td><code>notlong</code></td>
<td>Resources for use only on screens that have an aspect ratio that is similar
to the baseline screen configuration.</td>
</tr>
<tr>
<td>Platform version</td>
<td><nobr><code>v&lt;api-level&gt;</code></nobr></td>
<td>Resources that are for use only on a specific API Level or higher. For
example, if your application is designed to run on both Android 1.5 (API Level
3) and Android 1.6 (API Level 4 and higher), you can use the <code>-v4</code>
qualifier to tag any resources that should be excluded when your application is
running on Android 1.5 (API Level 3).  </td>
</tr>
</table>

<p>
Note that the density and the screen size are independent parameters and are
interpreted by the system individually. For example, WVGA high density is
considered a normal screen because its physical size is about the same as one of
T-Mobile G1. On the other hand, a WVGA medium density screen is considered a
<i>large</i> screen &mdash; it offers the same resolution but at lower pixel
density, meaning that it is both physically larger than the baseline screen and
can display significantly more information than a normal screen size.
</p>

<p>Here is an example of the resource directory structure of an application that
employs different layout schemes for different screen sizes and supports low and high density
screens.</p>

<pre>
res/layout/my_layout.xml            // layout for normal screen size
res/layout-small/my_layout.xml      // layout for small screen size
res/layout-large/my_layout.xml      // layout for large screen size
res/layout-large-land/my_layout.xml // layout for large screen size in landscape mode
res/layout-xlarge/my_layout.xml     // layout for extra large screen size

res/drawable-lhdpi/my_icon.png      // image for low density
res/drawable-mdpi/dpi/my_icon.png   // image for medium density
res/drawable-hdpi/my_icon.png       // image for high density

res/drawable-nodpi/composite.xml    // density independent resource
</pre>

<p>For more information about how to use resource qualifiers or how the platform
selects them, please read
<a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">
Providing Alternative Resources</a>.</p>


<h2 id="screen-independence">Best practices for Screen Independence</h2>

<p>The objective of supporting multiple screens is to create an application that
can run properly on any display and function properly on any of the generalized
screen configurations supported by the platform.
</p>

<p>You can easily ensure that your application will display properly on
different screens. Here is a quick checklist:</p>

<ol>
  <li>
   Use {@code wrap_content}, {@code fill_parent}, or the {@code dp} unit (instead of {@code px}),
when specifying dimensions in an XML layout file
  </li>
  <li>
    Do not use {@code AbsoluteLayout}
  </li>
  <li>
    Do not use hard coded pixel values in your code
  </li>
  <li>
    Use density and/or resolution specific resources
  </li>
</ol>

<h3 id="use-relative">1. Use wrap_content, fill_parent, or the dp unit, instead of
absolute pixels<br> </h3>

<p>When defining the <code>layout_width</code> and <code>layout_height</code> of
views in an XML layout file, using <code>wrap_content</code>,
<code>fill_parent</code> or the <code>dp</code> will guarantee that the view is
given an appropriate size on the current device screen. For instance, a view
with a <code>layout_width="100dp"</code> will measure 100 pixels wide on an
HVGA@160 density display and 150 pixels on a WVGA@240 density display, but the
view will occupy approximately the same physical space. </p>

<p>Similarly, you should prefer the <code>sp</code> (scale-independent pixel,
the scale factor depends on a user setting) or <code>dp</code> (if you don't
want to allow the user to scale the text) to define font sizes.</p>

<h3 id="avoid-absolute">2. Avoid AbsoluteLayout </h3>

<p>{@link android.widget.AbsoluteLayout AbsoluteLayout}
is one of the layout containers offered by the Android UI toolkit. Unlike the
other layouts however, <code>AbsoluteLayout</code> enforces the use of fixed
positions which might easily lead to user interfaces that do not work well on
different displays. Because of this, <code>AbsoluteLayout</code> was deprecated
in Android 1.5 (API Level 3). </p>

<p>You can achieve much the same layout by using a
{@link android.widget.FrameLayout FrameLayout} instead, and setting
<code>layout_margin</code> attributes of the children. This approach is more
flexible and will yield better results on different screens.</p>

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

<p>For performance reasons and to keep the code simpler, the Android framework
API 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 in pixels. For instance, if <code>myView.getWidth()</code> returns 10, the
view is 10 pixels wide. In some cases, you may need to scale the pixel values
that you use in your code. The sections below provide more information. </p>

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

<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 gesture is
recognized after the user's finger has moved by at least 16 pixels. On a
baseline screen, the user will have to move his finger by 16 pixels / 160
dpi = 1/10th of an inch (or 2.5 mm) before the gesture is recognized. On a
device with a high (240) density display, the user will move his finger by only
16 pixels / 240 dpi = 1/15th of an inch (or 1.7 mm.) The distance is much
shorter and the application thus appears more sensitive to the user. To fix this
issue, the gesture threshold must be expressed in the code in <code>dp</code>
and then converted to actual pixels.</p>

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

// Convert the dps to pixels
final float scale = getContext().getResources().getDisplayMetrics().density;
mGestureThreshold = (int) (GESTURE_THRESHOLD_DP * scale + 0.5f);</span>

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

<p>The {@link android.util.DisplayMetrics#density android.util.DisplayMetrics.density}
field specifies the the scale factor you must use to
convert dps to pixels according to the current screen density. You can access
the current screen's metrics through a <code>Context</code> or
<code>Activity</code>. On a medium (160) density screen,
<code>DisplayMetrics.density</code> equals "1.0", whereas on a high (240)
density screen it equals "1.5". You can refer to the documentation of the
{@link android.util.DisplayMetrics DisplayMetrics}
class for details.</p>

<h4>Use pre-scaled configuration values</h4>

<p>The {@link android.view.ViewConfiguration ViewConfiguration} class can be
used to access the most common distances, speeds, and times used in the Android
framework. For instance, the distance in pixels used by the framework as the
scroll threshold can be obtained as follows:</p>

<pre>ViewConfiguration.get(aContext).getScaledTouchSlop()</pre>

<p>Methods 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>

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

<div style="float: right;background-color:#fff;margin: 0;padding: 20px 0 20px 20px;">
<img src="{@docRoot}images/screens_support/scale-test.png" style="padding:0;margin:0;">
<p class="caption" style="margin:0;padding:0;"><strong>Figure 3.</strong> Comparison of pre-scaled and auto-scaled bitmaps.</p>
</div>

<p>Even with the size- and density-compatibility features that the platform
provides, you may still want to make adjustments to the UI of your application
when it displayed on certain screen sizes or densities. You can do this by
providing size- or density-specific resources &mdash; assets, layouts, strings,
and so on. If you want, you can also take control over the scaling of images
assets. The sections below provide more information.</p>

<h4 id="resource-dirs">Custom resources and directories</h4>

<p>If you need to control exactly how your application will look on various
displays, simply adjust your assets and layouts in configuration-specific
resources 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>

<p style="margin-left:2em;"><code>res/drawable-mdpi/icon.png&nbsp;&nbsp;&nbsp;//
for medium-density screens</code></p>

<p style="margin-left:2em;"><code>res/drawable-hdpi/icon.png&nbsp;&nbsp;&nbsp;//
for high-density screens</code></p>

<p>If a density qualifier is not defined in a resource directory name, the
platform assumes that the resources in that directory are designed for the
baseline medium density. It is not recommended that you put density-specific
resources such as images in the default directory.</p>

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

<h4 id="scaling">Pre-scaling and auto-scaling of bitmaps and nine-patches</h4>

<p>When a bitmap or nine-patch image is loaded from the application's resources,
the platform attempts to pre-scale it to match the display's density. For
instance, if you placed a 100x100 icon in the <code>res/drawable/</code>
directory and loaded that icon as a bitmap on a high-density screen, Android
would automatically scale up the icon and produce a 150x150 bitmap.</p>

<p>This pre-scaling mechanism works independently of the source. For instance,
an application targeted for a high-density screen may have bitmaps only in the
<code>res/drawable-hdpi/</code> directory. If one of the bitmaps is a 240x240
icon and is loaded on a medium-density screen, the resulting bitmap will measure
160x160.</p>

<p>The platform pre-scales resources as needed, whether the application is
running with density-compatibility features enabled or not (as specified by the
value of <code>android:anyDensity</code>). However, when running with
density-compatibility enabled, the platform continues to report the size of
pre-scaled bitmaps and other resources as if they were loaded in a
medium-density environment. For example, when density-compatibility is enabled,
if you load a 76x76 image from the default resources for display on a
high-density screen, the platform will pre-scale the image to 114x114
internally. However, the API still reports the size of the image as 76x76. This
discrepancy may cause unexpected behavior if your application somehow directly
manipulates the scaled bitmap, but this was considered a reasonable trade-off to
keep the performance of existing applications as good as possible.</p>

<p>This does not apply for the case that an application creates an in-memory
bitmap internally and draws something on it, for later display on the screen.
The platform auto-scales such bitmaps on the fly, at draw time. Other side
effects of such a case might be that fonts drawn in such a bitmap will be scaled
at the bitmap level, when the off-screen bitmap is finally rendered to the
display, resulting in scaling artifacts.</p>

<p>There are situations in which you may not want Android to automatically scale
a resource. The easiest way to accomplish this is to put it in a "nodpi"
resource directory:</p>

<p style="margin-left:2em;"><code>res/drawable-nodpi/icon.png</code></p>

<p>You can also take complete control of the scaling mechanism by using the
{@link android.graphics.BitmapFactory.Options BitmapFactory.Options} class,
which lets you define whether you want the bitmap to be pre-scaled and what the
density of the bitmap should be. For instance, if you are loading a bitmap from
a web server, you may want to force the bitmap's density to be high density.
When pre-scaling is disabled, the resulting bitmap is in auto-scaling mode. The
bitmap is associated with a density (that you may or may not have specified
through the <code>BitmapFactory.Options</code>) which will be used to scale the
bitmap on screen <em>at drawing time</em>.

<p>Using auto-scaling instead of pre-scaling is more CPU expensive than
pre-scaling but uses less memory. You can refer to the documentation of
{@link android.graphics.BitmapFactory BitmapFactory},
{@link android.graphics.Bitmap Bitmap}, and
{@link android.graphics.Canvas Canvas} for more
information on auto-scaling.</p>

<p>Figure 3, at right, demonstrates the results of the pre-scale and auto-scale
mechanisms when loading low (120), medium (160) and high (240) density bitmaps
on a baseline 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.</p>

<h2 id="strategies">Strategies for Legacy Applications</h2>

<p>If you have already developed and published an Android application based on
Android 1.5 or earlier platform version, you need to consider how you will adapt
your application so that it is deployable to:</p>

<ul>
<li>Existing devices, which may be running Android 1.5 (or lower) platform
version, as well as to </li>
<li>Newer devices that are running Android 1.6 (or higher) and offering various
screen sizes and resolutions</li>
</ul>

<p class="note"><strong>Note:</strong> Even if your application targets Android 1.6 already, you
should follow the same strategies below in order to support <em>xhdpi</em> and <em>xlarge</em>
screens on Android 2.3 (API Level 9), while maintaining compatibility with older versions of
the platform.</p>

<p>To support the newer devices and the different screens they use, you might
need to make some changes in your app, but at the same time your app may be very
stable and so you want to minimize the changes. There are a variety of ways that
you can extend your existing application to support new devices with multiple
screens <em>and</em> existing devices running older platform versions. You
should be able to make these changes to your application such that you can
distribute a single {@code .apk} to all devices.</p>

<p>The recommended strategy is to develop against the most recent version of the
platform you are targeting, and test on the minimum platform version you want to run on.
Here's how to do that:</p>

<ol>
  <li>Maintain compatibility with existing devices by leaving your application's
<code>android:minSdkVersion</code> attribute as it is. You <em>do not</em> need
to increment the value of the attribute to support new devices and multiple
screens. </li>
  <li>Extend compatibility for Android 1.6 (and higher) devices by adding
a new attribute &mdash; <code>android:targetSdkVersion</code> &mdash; to the
<code>uses-sdk</code> element. Set the value of the attribute to
<code>"4"</code>. [To support <em>xhdpi</em> and <em>xlarge</em> screens, set the value to
<code>"9"</code>.] This allows your application to "inherit" the platform's
multiple screens support, even though it is technically using an earlier version
of the API. </li>
  <li>Add an empty <code>&lt;supports-screens&gt;</code> element as a child of
<code>&lt;manifest&gt;</code>. If you need to enable size or density attributes
later, this is where you will add them.</li>
  <li>Change your application's build properties, such that it compiles against
the Android 1.6 (API Level 4) library [or against Android 2.3 (API Level 9) to support
<em>xhdpi</em> and <em>xlarge</em> screens], rather than against the Android 1.5 (or
earlier) library. You will not be able to compile your application against the
older platform because of the new manifest attribute. </li>
  <li>Set up AVDs for testing your application on Android 1.6 [or Android 2.3] and higher
releases. Create AVDs that use the screen sizes and densities that you want to
support. When you create the AVDs, make sure to select the Android 1.6 [or Android 2.3] or higher
platform as the system image to run. For more information, see <a
href="#testing">How to Test Your Application on Multiple Screens</a>,
below.</li>
  <li>Set up AVDs for testing your application on older versions of the platform, as low as the
version declared by your <code>android:minSdkVersion</code>. You need AVDs running the older
platforms you are targeting, so that
you can test for compatibility and ensure that there are no functional
regressions. </li>
  <li>Compile your application against the Android 1.6 [or Android 2.3] library and run it on the
AVDs you created. Observe the way your application looks and runs, and test all
of the user interactions. </li>
  <li>Debug any display or functional issues. For issues that you resolve in
your application code, <span style="color:red">make certain not to use any APIs
introduced later than the version declared by your <code>android:minSdkVersion</code></span>. If you
are in doubt, refer to SDK reference documentation and look for the API Level specifier for the API
you want to use. Using newer APIs not supported by your minimum version will mean that your
application will no longer be compatible with devices running on that version.</li>
  <li>For resource-related issues, you can try resolving them by:
    <ul>
    <li>Adding a <code>anyDensity="false"</code> attribute to
<code>&lt;supports-screens&gt;</code>, to enable density-compatibility
scaling.</li>
    <li>Creating any size- or density-specific resources you need and placing
them in directories tagged with the <a href="#qualifiers">correct
qualifiers</a>. Qualifiers must be arranged in a proscribed order. See
<a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">
Providing Alternative Resources</a> for more information. </li>
    <li>Note that if you add size- or density-specific resource directories
tagged with any of the resource qualifiers listed in this document, you should
make sure to also tag those directories with the <code>v&lt;api-level&gt;</code>
qualifier (for example, <code>-v4</code> to target API Level 4). This ensures that those resources
will be ignored when the application is run on Android 1.5 or lower platform
versions.</p></li>
    </ul>
  </li>
  <li>If your application does not offer support (such as custom layouts) for
large screens and you want the platform to display your application in
screen-compatibility mode on larger screens, add the
<code>largeScreens="false"</code> and <code>xlargeScreens="false"</code> attributes to the
<code>&lt;supports-screens&gt;</code> element in the manifest. See
<a href="#compatibility-examples">Screen-Compatibility Examples</a> for
illustrations of how the platform displays your application in this case.</li>
  <li>If your application does not offer support (such as custom layouts) for
small screens (such as on a QVGA low-density screen) and you do not want Android
Market to offer the application to users of small-screen devices, you
<em>must</em> add a <code>smallScreens="false"</code> attribute to the
<code>&lt;supports-screens&gt;</code> element. </li>
  <li>Continue testing and debugging until your application performs as expected
on all of the platforms and screen sizes your application will support.</li>
  <li>Export, zipalign, and sign your application using the same private key you
used when publishing the previous version, then publish the application to users
as an update. </li>
</ol>

<p>In particular, remember to test your application on an AVD that emulates a
small-screen device. Devices that offer screens with QVGA resolution at low
density are available now. Users of those devices may want to download your
application, so you should understand how your application will look and
function on a small-screen device. In many cases, the reduced screen area and
density mean that you may need to make tradeoffs in design, content, and
function on those devices. </p>

<p>Also give extra attention to testing your application on an AVD that emulates an <em>xlarge</em>
screen. Devices with extra large screens
are tablet-sized or larger, so you should pay close attention to how usable your application is on
such screens. You might want to design new layouts specifically for extra large screens, to address
usability aspects such as the location and size of buttons in your UI. To test your application on
an extra large screen, create an AVD targeted to Android 2.3 with a high resolution, such as 1280 x
800, and the default density of 160dpi. This AVD will use any resources you've provided with the
<code>xlarge</code> <a href="#qualifiers">resouce qualifier</a>.</p>


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

<p>Before publishing an application that supports multiple screens, you should
thoroughly test it in all of the targeted screen sizes and densities. You can
test how it displays with the platform's compatibility features enabled or with
screen-specific UI resources included in your application. The Android SDK
includes all the tools you need to test your application on any supported
screen.</p>

<!-- You can test in any minsdk, and you can test with compatabiltiy code or
not. Once you've tested your application and found that it displays properly on
various screen sizes, you should make sure to add the corresponding size
attribute(s) to your application's manifest. -->

<div id="f9.5" class="figure" style="width:530px">
  <img src="{@docRoot}images/screens_support/avds-config.png" />
  <p class="img-caption"><strong>Figure 4.</strong>
  A typical set of AVDs for testing screens support.</p>
</div>

<p>As a test environment for your applications, set up a series of AVDs that
emulate the screen sizes and densities you want to support. The Android SDK
includes several emulator skins to get you started. You can use the Android AVD
Manager or the <code>android</code> tool to create AVDs that use the various
emulator skins and you can also set up custom AVDs to test densities other than
the defaults. For general information about working with AVDs, see
<a href="{@docRoot}guide/developing/tools/avd.html">Android Virtual
Devices</a>.</p>

<p>The Android SDK provides a set of default emulator skins that you can use for
testing. The skins are included as part of each Android platform that you can
install in your SDK. The Android 1.6 platform offers these default skins:</p>

<ul>
  <li>
    QVGA (240x320, low density, small screen)
  </li>
  <li>
    HVGA (320x480, medium density, normal screen)
  </li>
  <li>
    WVGA800 (480x800, high density, normal screen)
  </li>
  <li>
    WVGA854 (480x854 high density, normal screen)
  </li>
</ul>

<p>The Android 2.0 platform offers all of the Android 1.6 default skins,
above, plus:</p>

<ul>
  <li>
    WQVGA400 (240x400, low density, normal screen)
  </li>
  <li>
    WQVGA432 (240x432, low density, normal screen)
  </li>
</ul>

<p>If you are using the <code>android</code> tool command line to create your
AVDs, here's an example of how to specify the skin you want to use:</p>

<pre>android create avd ... --skin WVGA800</pre>

<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 resolutions and densities. To
do so you will need to know the approximate density, in dpi, of your computer
monitor (a 30" Dell monitor has for instance a density of about 96 dpi.). Use
your monitor's dpi as the value of the <code>-scale</code> option, when
launching the emulator, for example:</p>

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

<p>If you are working in Eclipse with ADT, you can specify the <code>-scale
96dpi</code> option in the Target tab of run and debug configurations, under
"Additional Emulator Command Line Options" field. </p>

<p>Note that starting the emulator with the <code>-scale</code> option will
scale the entire emulator display, based on both the dpi of the skin and of your
monitor. The default emulator skins included in the Android SDK are listed
in <a href="#screens-table">Table 1</a>, earlier in this document.</p>

<div class="figure" style="width:324px">
  <img src="{@docRoot}images/screens_support/avd-density.png" >
  <p class="img-caption"><strong>Figure 5.</strong>
  Resolution and density options that you can use, when creating an AVD using the AVD Manager.</p>
</div>

<p>You should also make sure to test your application on different physical
screen sizes within a single size-density configuration. For example, to
display this screen configuration on a 30" monitor you will need to adjust
the value passed to <code>-scale</code> to 96*2.8/3.3 = 81dpi. You can also
pass a float value to <code>-scale</code> to specify your own scaling factor:</p>

<pre>emulator -avd &lt;name&gt; -scale 0.6</pre>

<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 either adjust an
existing skin, or create an AVD that uses a custom resolution or density.</p>

<p>In the AVD Manager, you can specify a custom skin resolution or density in
the Create New AVD dialog, as shown in Figure 5, at right.</p>

<p>In the <code>android</code> tool, follow these steps to create an AVD with a
custom resolution or density:</p>

<ol>
  <li>Use the <code>create avd</code> command to create a new AVD, specifying
the <code>--skin</code> option with a value that references either a default
skin name (such as "WVGA800") or a custom skin resolution (such as 240x432).
Here's an example:
     <pre>android create avd -n &lt;name&gt; -t &lt;targetID&gt; --skin WVGA800</pre>
  </li>
  <li>To specify a custom density for the skin, answer "yes" when asked whether
you want to create a custom hardware profile for the new AVD.</li>
  <li>Continue through the various profile settings until the tool asks you to
specify "Abstracted LCD density" (<em>hw.lcd.density</em>). Enter an appropriate
value, such as "120" for a low-density screen, "160" for a medium density screen,
or "240" for a high-density screen.</li>
  <li>Set any other hardware options and complete the AVD creation.</li>
</ol>

<p>In the example above (WVGA medium density), the new AVD will emulate a 5.8"
WVGA screen.</p>

<p>As an alternative to adjusting the emulator skin configuration, you can use
the emulator skin's default density and add the <code>-dpi-device</code> option
to the emulator command line when starting the AVD. For example, </p>

<pre>emulator -avd WVGA800 -scale 96dpi -dpi-device 160</pre>


<h2 id="compatibility-examples">Screen-Compatibility Examples</h2>

<p>This section provides examples of how the Android platform displays an
application written for the baseline screen configuration &mdash; HVGA (320x480)
resolution on a 3.2" screen &mdash; with all of the platform's size- and
density-compatibility features enabled. That is, the examples show how
the platform displays an application that doesn't provide built-in support
for the screen on which it is being rendered, but which instead relies completely
on the platform.</p>

<p>The platform's screen-compatibility features are designed to provide such
an application with a virtual baseline screen environment against which to run,
while at the same time ensuring for the user a physical display that is
approximately the same as the baseline screen size and density. </p>

<p>Legacy applications that have not been modified to support multiple
screens would be typical examples of such applications. In most cases,
you would want to add multiple-screens support to a legacy application and
publish an updated version, as described in <a href="#strategies">Strategies
for Legacy Applications</a>. However, if you did not do so, the
platform still performs best-effort rendering of your application, as
illustrated below.</p>

<p> Internally, these are the compatibility features that the platform
provides, based on the current device screen:</p>

  <ul>
    <li>
      If the device's screen density is <em>not medium</em>, the application's
layout and drawing of its content is as if the screen <em>is</em> medium density, but the
framework scales the layout and images (if the image for the target density is
not available) to fit the target density. It scales 1.5 times if the target
density is high density (160-&gt;240 virtual dpi), or 0.75 times if the target
density is low density (160 -&gt; 120 virtual dpi).
    </li>
    <li>
      If the device's screen size is <em>small</em>, there are few options
options for making Android 1.5 applications work well on such a screen, so
Android Market will filter applications that are not known to support these
screens from the device.
    </li>
    <li>
      If the device's screen size is <em>large</em>, it limits the application's
screen to the normal size and draws a black background around the application.
For example, if an application supports high density, but does not support large
screens, it only uses a 480x720 area of the screen and the rest will be filled
with a black background (see example below).
    </li>
  </ul>

<table style="width:10%;margin-left:.5em;">
  <tr>
    <td>
      HVGA, normal size, normal density<br>
      [ emulator -skin HVGA ]<br>
      <img height=149 src="{@docRoot}images/screens_support/afdvfckr9j_15dcsvrscg_b.png" width=225>
    </td>
    <td>
       WVGA, normal size, high density<br>
      [emulator -skin WVGA854 -dpi-device 240]<br>
      <img height=143 src="{@docRoot}images/screens_support/afdvfckr9j_18c6mhm3cm_b.png" width=254><br>
      <p>The application occupies full screen as its considered to be normal size. (close to 480x720)</p>
    </td>
  </tr>
  <tr>
    <td>
      VGA, large size, medium density<br>
      [ emulator -skin 640x480 ]<br>
      <img height=243 src="{@docRoot}images/screens_support/afdvfckr9j_14fj6dhsc3_b.png" width=324>
      <p>The application occupies 320x480 of VGA.</p>
    </td>
    <td>
      SVGA, large size, high density<br>
      [ emulator -skin 800x600 -dpi-device 240]<br>
      <img height=223 src="{@docRoot}images/screens_support/afdvfckr9j_19c743p6cr_b.png" width=294>
      <p>The application occupies 480x720 (=1.5 x [320x480]) of 800x600.</p>
    </td>
  </tr>
</table>


<h3>Screen-compatibility limitations on small, low-density screens</h3>

<p>Because these device has smaller state/resolution, there are known
limitations when application runs in compatibility mode.</p>

<h4>QVGA</h4>

<p>Because QVGA (240x320) screens have less screen area available and lower
density than normal, which is 240x360 in low density, some applications cannot
render all their content properly on those screens.&nbsp; As a result, on a QVGA
device, Android Market will filter out all applications that do not declare they
support small screens.</p>

<p>Examples:</p>

<table style="width:10%;margin-left:.5em;">
  <tr>
    <td>The part of z value graph is chopped.</td>
    <td>The lap time area is chopped.<br></td>
  </tr>
  <tr>
    <td><img height=207 src="{@docRoot}images/screens_support/afdvfckr9j_16g95wjqg3_b.png" width="155"></td>
    <td><img height=186 src="{@docRoot}images/screens_support/afdvfckr9j_17p2w4txgc_b.png" width="139"></td>
  </tr>
</table>


<h4>Images with 1 pixel height/width.</h4>

<p>If an image has 1 pixel height or width, it may not be shown on the screen
due to rounding issue. This is inevitable as it just does not have enough
pixels.</p>

<p>For example, in the screen below, the divider in the menu is invisible
because the width of the image is trancated to 0. (This particular problem is
solvable because menu is handled inside framework, but there is no generic
solution as it just does not have enough pixels.)</p>

<img height=222 src="{@docRoot}images/screens_support/afdvfckr9j_20fvptbbdd_b.png" width=166>