1336 lines
62 KiB
Plaintext
1336 lines
62 KiB
Plaintext
page.title=Supporting Multiple Screens
|
|
|
|
@jd:body
|
|
|
|
<div id="qv-wrapper">
|
|
<div id="qv">
|
|
|
|
<h2>Multiple screens 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"><supports-screens></a></code></li>
|
|
<li><code><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></a></code></li>
|
|
<li><a href="{@docRoot}guide/topics/resources/resources-i18n.html#AlternateResources">Alternate 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 .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>In particular, if you have an existing application that you would like to
|
|
make available for users of devices with small screens (such as QVGA), 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 three
|
|
generalized sizes: large, normal, and small. Applications can provide custom
|
|
layouts for each of these three sizes — 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 —
|
|
sometimes significantly more — 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 three
|
|
generalized densities: high, medium, and low. Applications can provide custom
|
|
resources for each of these three densities — the platform handles the
|
|
scaling of the resources up or down to meet the actual screen density. </p></dd>
|
|
<dt><em>Density independent pixel (dip)</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 dip units needed, based on the actual density of the screen in use. The
|
|
conversion of dip units to screen pixels is simple: <code>pixels = dips *
|
|
(density / 160)</code>. For example, on 240 dpi screen, 1 dip would equal 1.5
|
|
physical pixels. Using dip 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>Android 1.5 and earlier versions of the platform were designed to support a
|
|
single screen configuration — HVGA (320x480) resolution on a 3.2" screen.
|
|
Because the platform targeted just one screen, application developers could
|
|
write their applications specifically for that screen, without needing to worry
|
|
about how their applications would be displayed on other screens. </p>
|
|
|
|
<p>Starting from Android 1.6, the platform adds support for multiple screen
|
|
sizes and resolutions, reflecting the many new types and sizes of devices on
|
|
which the platform will run. This means that developers must design their
|
|
applications for proper display on a range of devices and screens.</p>
|
|
|
|
<p>To simplify the way application developers design their user interfaces for
|
|
multiple devices, and to allow more devices to participate without impacting
|
|
applications, the platform divides the range of actual supported screen sizes
|
|
and resolutions into:</p>
|
|
|
|
<ul>
|
|
<li>A set of three generalized sizes: <em>large</em>, <em>normal</em>, and <em>small</em>, and </li>
|
|
<li>A set of three generalized densities: high (<em>hdpi</em>), medium (<em>mdpi</em>), and low (<em>ldpi</em>)
|
|
</ul>
|
|
|
|
<!--<p>Applications use to these generalized sizesThe to let you apply custom UI
|
|
and enable/disable functionality according to the generalized class of screen,
|
|
rather than by the specific screen. When you are developing your application,
|
|
you use these generalized sizes and densities and Applications can use these
|
|
generalized sizes and densities to tell the platform I will do it or you do it.
|
|
Or a combination of both. -->
|
|
|
|
<p>Applications can provide custom resources (primarily layouts) for any of the
|
|
three generalized sizes, if needed, and they can also provide resources
|
|
(primarily drawables such as images) for any of the three 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 range of screens supported by Android and the generalized screen
|
|
configurations that the platform maps them to are shown in the table below. </p>
|
|
|
|
<table id="screens-table" width="80%" style="margin-top:2em;">
|
|
<tbody>
|
|
<tr>
|
|
<td></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>
|
|
</tr>
|
|
<tr>
|
|
<td style="background-color:#f3f3f3">
|
|
<em>Small</em> screen
|
|
</td>
|
|
<td style="font-size:.9em;">
|
|
<ul style="padding:0">
|
|
<li style="margin: 0 0 0 1em;padding:.25em 0 0 0; font-size:.9em;">QVGA (240x320), <nobr>2.6"-3.0" diagonal</nobr></li>
|
|
</ul>
|
|
</td>
|
|
<td></td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td style="background-color:#f3f3f3">
|
|
<em>Normal</em> screen
|
|
</td>
|
|
<td style="font-size:.9em;">
|
|
<ul style="padding:0">
|
|
<li style="margin: 0 0 0 1em;padding:.25em 0 0 0; font-size:.9em;">WQVGA (240x400), <nobr>3.2"-3.5" diagonal</nobr></li>
|
|
<li style="margin: 0 0 0 1em;padding:.25em 0 0 0; font-size:.9em;">FWQVGA (240x432), <nobr>3.5"-3.8" diagonal</nobr></li>
|
|
</ul>
|
|
</td>
|
|
<td style="font-size:.9em;background-color:#FFE;">
|
|
<ul style="padding:0">
|
|
<li style="margin: 0 0 0 1em;padding:.25em 0 0 0; font-size:.9em;">HVGA (320x480), <nobr>3.0"-3.5" diagonal</nobr></li>
|
|
</ul>
|
|
</td>
|
|
<td style="font-size:.9em;">
|
|
<ul style="padding:0">
|
|
<li style="margin: 0 0 0 1em;padding:.25em 0 0 0; font-size:.9em;">WVGA (480x800), <nobr>3.3"-4.0" diagonal</nobr></li>
|
|
<li style="margin: 0 0 0 1em;padding:.25em 0 0 0; font-size:.9em;">FWVGA (480x854), <nobr>3.5"-4.0" diagonal</nobr></li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="background-color:#f3f3f3">
|
|
<em>Large</em> screen
|
|
</td>
|
|
<td></td>
|
|
<td style="font-size:.9em;">
|
|
<ul style="padding:0">
|
|
<li style="margin: 0 0 0 1em;padding:.25em 0 0 0; font-size:.9em;">WVGA (480x800), <nobr>4.8"-5.5" diagonal</nobr></li>
|
|
<li style="margin: 0 0 0 1em;padding:.25em 0 0 0; font-size:.9em;">FWVGA (480x854), <nobr>5.0"-5.8" diagonal</nobr></li>
|
|
</ul>
|
|
</td>
|
|
<td></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<p class="caption" style="margin-top:1em;margin-bottom:1.5em;"><strong>Table
|
|
1.</strong> Summary of device screens supported by Android. </p>
|
|
|
|
<p>As shown above, the various screen configurations are arranged around a
|
|
baseline screen — HVGA (320x480) resolution on a 3.2" screen — which
|
|
is assigned a size of "normal" and a density of "medium". The HVGA screen is
|
|
used as the baseline because all applications written against Android 1.5 or
|
|
earlier are (by definition) written for the HVGA screen used on the T-Mobile G1
|
|
and similar devices.</p>
|
|
|
|
<!-- <p>Note that each screen configuration spans a range of actual resolutions
|
|
and physical screen sizes. For example, the The baseline configuration spans a
|
|
range of actual screen sizes — from 3.0" to 3.5" diagonal — all with
|
|
the same HVGA resolution. That means that the actual pixel density of devices in
|
|
a single screen configuration can vary. </p>
|
|
|
|
Because differences in density can affect the displayed size of UI elements
|
|
declared in pixels, the framework provides a density-independent pixel (dip)
|
|
unit that applications can use to declare UI dimensions, letting the platform
|
|
automatically handle the scaling to the actual pixel density of the screen. When
|
|
UI dimensions are declared in dip, the result is that they are displayed at the
|
|
same physical size on all screens in a given configuration. </p> -->
|
|
|
|
<p>Although the platform currently supports the nine possible size-density
|
|
configurations listed in the table, you do not necessarily need to custom
|
|
resources for each one of them. The platform provides robust compatibility
|
|
features, described in the sections below, that can handle most of the work of
|
|
rendering your application on the current device screen, provided that the UI is
|
|
properly implemented. For more information, see <a
|
|
href="#screen-independence">Best Practices for Screen Independence</a>.</p>
|
|
|
|
|
|
<h3 id="support">How Android supports multiple screens</h3>
|
|
|
|
<div class="sidebox-wrapper">
|
|
<div class="sidebox">
|
|
<h2>Using the alternate resources framework</h2>
|
|
|
|
<p>The platform's support for loading screen size- and density-specific
|
|
resources at run time is based on the alternate 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/resources-i18n.html#AlternateResources">
|
|
Alternate 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 the way your application is displayed, if you need or want
|
|
to use them:</p>
|
|
|
|
<ul>
|
|
<li>The platform provides a set of resource qualifiers that let you provide
|
|
size- and density-specific resources, if needed. The qualifiers for
|
|
size-specific resources are <code>large</code>, <code>normal</code>, and
|
|
<code>small</code>, and those for density-specific resources are
|
|
<code>hdpi</code> (high), <code>mdpi</code> (medium), and <code>ldpi</code>
|
|
(low). The qualifiers correspond to the generalized densities given in
|
|
<a href="#range">Table 1</a>, above.</li>
|
|
<li>The platform also provides a
|
|
<a href="{@docRoot}guide/topics/manifest/supports-screens-element.html">
|
|
<code><supports-screens></code></a>
|
|
element, whose attributes
|
|
<code>android:largeScreens</code>, <code>android:normalScreens</code>, and
|
|
<code>android:smallScreens</code> let you specify what generalized screen sizes
|
|
your application supports. A fourth 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 HVGA 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 device-independent pixel (dip) 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 1.</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>dip</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 from dips to
|
|
pixels</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><supports-screens></code></a>,
|
|
whose attributes you can use to control the
|
|
display of your application on different classes of device screens, as listed
|
|
below. The <code>smallScreens</code>, <code>normalScreens</code>, and
|
|
<code>largeScreens</code> attributes correspond to the generalized screen sizes
|
|
shown in <a href="#range">Table 1</a>, earlier in this document.</p>
|
|
|
|
<table id="vrr8">
|
|
<tr>
|
|
<th>
|
|
Attribute
|
|
</th>
|
|
<th >
|
|
Description
|
|
</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 — "<code>true</code>" if it is, and
|
|
"<code>false</code>" if not. See <a href="#defaults">Default values for
|
|
attributes</a> for information about the assumed value of this attribute, if not
|
|
declared.
|
|
</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 — "<code>true</code>" if it is, and
|
|
"<code>false</code>" if not. The default value is "<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 — "<code>true</code>" if it is, and
|
|
"<code>false</code>" if not. See <a href="#defaults">Default values for
|
|
attributes</a> for information about the assumed value of this attribute, if not
|
|
declared.
|
|
</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 — "<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 — specifically,
|
|
the auto-scaling of absolute pixel units and math — and relies on the
|
|
application to use density-independent pixel units and/or to manage the
|
|
adaptation of pixel values according to density of the current screen. </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>See <a href="#defaults">Default values for attributes</a> for
|
|
information about the assumed value of this attribute, if not declared.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>In general, when you declare a screen-size attribute
|
|
(<code>smallScreens</code>, <code>normalScreens</code>, or
|
|
<code>largeScreens</code>) as "true", you are signaling to the platform that
|
|
your application wants to manage its UI by itself, for all screen sizes, without
|
|
the platform applying any size-compatibility behaviors (such as a virtual HVGA
|
|
display area). If you declare a screen-size attribute as "false", you are
|
|
signaling that your application is not designed for that screen size. The
|
|
effects are conditioned by the screen size that your application does not
|
|
support:</p>
|
|
|
|
<ul>
|
|
<li>If you declare <code>largeScreens="false"</code>, your application can
|
|
still be installed by users of devices with large screens. When run on a device
|
|
with a large screen, this attribute value causes the platform to run the
|
|
application in compatibility mode, rendering it in a baseline HVGA screen area
|
|
(normal size, medium density) reserved 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 compatibility
|
|
mode.</li>
|
|
<li>If you declare <code>smallScreens="false"</code>, your application can
|
|
still be installed by users of devices with small screens. However, this
|
|
attribute value causes Android Market to filter your application from the list
|
|
of applications available to such users. In effect, this prevents users from
|
|
installing the application on small-screen devices. </li>
|
|
</ul>
|
|
|
|
<p>If you declare the <code>android:anyDensity</code> attribute as "true", you
|
|
are signaling to the platform that your application wants to manage its UI by
|
|
itself, for all screen densities, using the actual screen dimensions and pixels.
|
|
In this case, the application must ensure that it declares its UI dimensions
|
|
using device-independent pixels and scales any actual pixel values or math by
|
|
the scaling factor available from
|
|
{@link android.util.DisplayMetrics#density android.util.DisplayMetrics.density}.</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 large,
|
|
normal, and small screens in any densities.</p>
|
|
|
|
<pre><manifest xmlns:android="http://schemas.android.com/apk/res/android">
|
|
|
|
<supports-screens
|
|
android:largeScreens="true"
|
|
android:normalScreens="true"
|
|
android:smallScreens="true"
|
|
android:resizable="true"
|
|
android:anyDensity="true" />
|
|
</manifest>
|
|
</pre>
|
|
|
|
<h4 id="defaults">
|
|
Default values for attributes
|
|
</h4>
|
|
|
|
<p>The default values for the <code><supports-screens></code> attributes
|
|
differs, 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 <code>android:targetSdkVersion</code>, if declared:</p>
|
|
|
|
<div>
|
|
<ul>
|
|
<li>
|
|
If <code>android:minSdkVersion</code> or
|
|
<code>android:targetSdkVersion</code> is "3" (Android 1.5) or lower, the default
|
|
value for everything except android:normalScreens is <code>false</code>. If you
|
|
are primarily targeting pre-Android 1.6 platforms but also want to support other
|
|
densities/screen sizes, you need to set the appropriate attributes to
|
|
<code>true</code>.
|
|
</li>
|
|
<li>
|
|
If <code>android:minSdkVersion</code> or
|
|
<code>android:targetSdkVersion</code> is "4" (Android 1.6) or higher, the
|
|
default value for everything is <code>true</code>. If your application
|
|
requires <span style=BACKGROUND-COLOR:#ffffff>Android 1.6 </span>features,
|
|
but does not support these densities and/or screen sizes, you need to set the
|
|
appropriate attributes to <code>false</code>.
|
|
</li>
|
|
<li>
|
|
Note that <code>android:normalScreens</code> always defaults to
|
|
<code>true</code>.
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
|
|
|
|
<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">Table
|
|
1</a>, earlier in this document.</p>
|
|
|
|
<table>
|
|
<tr>
|
|
<th>Screen characteristic</th>
|
|
<th>Qualifier</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td rowspan="3">Size</td>
|
|
<td><code>small</code></td>
|
|
<td>Resources for small screens, such as QVGA low density.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>normal</code></td>
|
|
<td>Resources for normal (baseline configuration) screens, such as T-Mobile
|
|
G1/HTC Magic screen size, or equivalent.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>large</code></td>
|
|
<td>Resources for large screens. Typical example is a tablet like device.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td rowspan="4">Density</td>
|
|
<td><code>ldpi</code></td>
|
|
<td>Low-density resources, for 100 to 140 dpi screens.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>mdpi</code></td>
|
|
<td>Medium-density resources for 140 to 180 dpi screens.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>hdpi</code></td>
|
|
<td>High-density resources for 190 to 250 dpi 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<api-level></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 — 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
|
|
supports low and high density, and employs different layout schemes.</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/drawable-ldpi/my_icon.png // icon image for low density
|
|
res/drawable-mdpi/dpi/my_icon.png // icon for medium density
|
|
res/drawable-hdpi/my_icon.png // icon 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/resources-i18n.html#AlternateResources">
|
|
Alternate 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 screen
|
|
configurations listed in <a href="#range">Table 1</a> earlier in this document.
|
|
</p>
|
|
|
|
<p>You can easily ensure that your application will display properly on
|
|
different screens. Here is a quick checklist:</p>
|
|
|
|
<ol>
|
|
<li>
|
|
Prefer wrap_content, fill_parent and the dip unit to px in XML layout files
|
|
</li>
|
|
<li>
|
|
Avoid 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. Prefer wrap_content, fill_parent and the dip unit to
|
|
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>dip</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="100dip"</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>dip</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 from dips to pixels</h4>
|
|
|
|
<p>In some cases, you will need to express dimensions in <code>dip</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 HVGA 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>dip</code>
|
|
and then converted to actual pixels.</p>
|
|
|
|
<pre>// The gesture threshold expressed in dip
|
|
private static final float GESTURE_THRESHOLD_DIP = 16.0f;
|
|
|
|
// Convert the dips to pixels
|
|
final float scale = getContext().getResources().getDisplayMetrics().density;
|
|
mGestureThreshold = (int) (GESTURE_THRESHOLD_DIP * 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 dips 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 2.</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 — 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 //
|
|
for medium-density screens</code></p>
|
|
|
|
<p style="margin-left:2em;"><code>res/drawable-hdpi/icon.png //
|
|
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 2, 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>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 .apk to any and 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 one 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 — <code>android:targetSdkVersion</code> — to the
|
|
<code>uses-sdk</code> element. Set the value of the attribute to
|
|
"<code>4</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><supports-screens></code> element as a child of
|
|
<code><manifest></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, 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 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 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 Android 1.5 (or earlier
|
|
platform). 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 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 in API Level 4 or later</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 an API introduced in API Level 4 or later will mean that your
|
|
application will no longer be compatible with devices running Android 1.5 or
|
|
earlier.</li>
|
|
<li>For resource-related issues, you can try resolving them by:
|
|
<ul>
|
|
<li>Adding a <code>anyDensity="false"</code> attribute to
|
|
<code><supports-screens></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/resources-i18n.html#AlternateResources">
|
|
Alternate 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<api-level></code>
|
|
qualifier (for example, <code>-v4</code>). 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 a
|
|
<code>largeScreens="false"</code> attribute to the
|
|
<code><supports-screens></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><supports-screens></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>
|
|
|
|
<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" style="float:right;margin:0;padding:0;">
|
|
<img src="{@docRoot}images/screens_support/avds-config.png" style="padding:0;margin:0;">
|
|
<p class="caption" style="margin:0 0 1.5em 1em;padding:0 0 0 1em;"><strong>Figure 3.</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 six 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 <name> -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. Using the default densities, the emulator skins included in the Android
|
|
1.6 SDK will emulate the following screen sizes:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
QVGA, low density: 3.3"
|
|
</li>
|
|
<li>
|
|
WQVGA, low density: 3.9"
|
|
</li>
|
|
<li>
|
|
WQVGA432, low density: 4.1"
|
|
</li>
|
|
<li>
|
|
HVGA, medium density: 3.6"
|
|
</li>
|
|
<li>
|
|
WVGA800, high density: 3.9"
|
|
</li>
|
|
<li>
|
|
WVGA854, high density: 4.1"
|
|
</li>
|
|
</ul>
|
|
|
|
<div style="float: right;background-color:#fff;margin: 0;padding: 20px 0 20px 20px;width:520px;">
|
|
<img src="{@docRoot}images/screens_support/avd-density.png" style="padding:0;margin:0;">
|
|
<p class="caption" style="margin:0 0 1.5em 1em;padding:0 0 0 1em; width:280px;"><strong>Figure 4.</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, according
|
|
to <a href="#range">Table 1</a>, the minimum supported diagonal of QVGA is 2.8".
|
|
To display this is 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 <name> -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 4, 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 <name> -t <targetID> --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>). Consult <a
|
|
href="#range">Table 1</a>, earlier in this document, and enter the appropriate
|
|
value. For example, enter "160" to use medium density for the WVGA800 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 — HVGA (320x480)
|
|
resolution on a 3.2" screen — 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->240 virtual dpi), or 0.75 times if the target
|
|
density is low density (160 -> 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. 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>
|
|
|
|
|
|
|