Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

am 30f57295: am ba944ccd: Doc change: update screens support table and remove outdated density/size metrics.

Browse Source 
Merge commit '30f572956ef92e8636772be7bd5d0150cf7fd1fc' into gingerbread-plus-aosp

* commit '30f572956ef92e8636772be7bd5d0150cf7fd1fc':
  Doc change: update screens support table and remove outdated density/size metrics.
This commit is contained in:
Dirk Dougherty
2010-10-04 11:16:12 -07:00
committed by Android Git Automerger
parent 53fb09b42f 30f572956e
commit 44fad94aff
3 changed files with 230 additions and 232 deletions
Download Patch File Download Diff File Expand all files Collapse all files

58
docs/html/guide/practices/design/responsiveness.jd
View File

@@ -1,13 +1,31 @@
page.title=Designing for Responsiveness page.title=Designing for Responsiveness
@jd:body @jd:body
<p>It's possible to write code that wins every performance test in the world, but still sends users in a fiery rage when they try to use the application. These are the applications that aren't <em>responsive</em> enough &mdash; the ones that feel <div class="figure">
sluggish, hang or freeze for significant periods, or take too long to process <img src="{@docRoot}images/anr.png" alt="Screenshot of ANR dialog box" width="240" height="320"/>
input. </p> <p><strong>Figure 1.</strong> An ANR dialog displayed to the user.</p>
</div>
<p>In Android, the system guards against applications that are insufficiently responsive for a period of time by displaying a dialog to the user, called the Application Not Responding (ANR) dialog. The user can choose to let the application continue, but the user won't appreciate having to act on this dialog every time he or she uses your application. So it's important to design responsiveness into your application, so that the system never has cause to display an ANR to the user. </p> <p>It's possible to write code that wins every performance test in the world,
but still sends users in a fiery rage when they try to use the application.
These are the applications that aren't <em>responsive</em> enough &mdash; the
ones that feel sluggish, hang or freeze for significant periods, or take too
long to process input. </p>
<p>Generally, the system displays an ANR if an application cannot respond to user input. For example, if an application blocks on some I/O operation (frequently a network access), then the main application thread won't be able to process incoming user input events. After a time, the system concludes that the application has hung, and displays the ANR to give the user the option to kill it. <p>In Android, the system guards against applications that are insufficiently
responsive for a period of time by displaying a dialog to the user, called the
Application Not Responding (ANR) dialog, shown at right in Figure 1. The user
can choose to let the application continue, but the user won't appreciate having
to act on this dialog every time he or she uses your application. It's critical
to design responsiveness into your application, so that the system never has
cause to display an ANR dialog to the user. </p>
<p>Generally, the system displays an ANR if an application cannot respond to
user input. For example, if an application blocks on some I/O operation
(frequently a network access), then the main application thread won't be able to
process incoming user input events. After a time, the system concludes that the
application is frozen, and displays the ANR to give the user the option to kill
it. </p>
<p>Similarly, if your application spends too much time building an elaborate in-memory <p>Similarly, if your application spends too much time building an elaborate in-memory
structure, or perhaps computing the next move in a game, the system will structure, or perhaps computing the next move in a game, the system will
@@ -15,31 +33,17 @@ conclude that your application has hung. It's always important to make
sure these computations are efficient using the techniques above, but even the sure these computations are efficient using the techniques above, but even the
most efficient code still takes time to run.</p> most efficient code still takes time to run.</p>
<p>In both of these cases, the fix is usually to create a child thread, and do <p>In both of these cases, the recommended approach is to create a child thread and do
most of your work there. This keeps the main thread (which drives the user most of your work there. This keeps the main thread (which drives the user
interface event loop) running, and prevents the system from concluding your code interface event loop) running and prevents the system from concluding that your code
has frozen. Since such threading usually is accomplished at the class has frozen. Since such threading usually is accomplished at the class
level, you can think of responsiveness as a <em>class</em> problem. (Compare level, you can think of responsiveness as a <em>class</em> problem. (Compare
this with basic performance, which was described above as a <em>method</em>-level this with basic performance, which was described above as a <em>method</em>-level
concern.)</p> concern.)</p>
<div class="sidebox-wrapper"> <p>This document describes how the Android system determines whether an
<div class="sidebox"> application is not responding and provides guidelines for ensuring that your
<img src="{@docRoot}images/anr.png" width="240" height="320" alt="Screenshot of ANR dialog box"> application stays responsive. </p>
<p style="margin-top:.5em;padding:.5em;">An ANR dialog displayed to the user.</p>
</div>
</div>
<p>This document discusses how the Android system determines whether an application is
not responding and provides guidelines for
ensuring that your application is responsive. </p>
<p>This document covers these topics: </p>
<ul>
<li><a href="#anr">What Triggers ANR?</a></li>
<li><a href="#avoiding">How to Avoid ANR</a></li>
<li><a href="#reinforcing">Reinforcing Responsiveness</a></li>
</ul>
<h2 id="anr">What Triggers ANR?</h2> <h2 id="anr">What Triggers ANR?</h2>
@@ -48,8 +52,10 @@ and Window Manager system services. Android will display the ANR dialog
for a particular application when it detects one of the following for a particular application when it detects one of the following
conditions:</p> conditions:</p>
<ul> <ul>
<li>No response to an input event (e.g. key press, screen touch) within 5 seconds</li> <li>No response to an input event (e.g. key press, screen touch)
<li>A {@link android.content.BroadcastReceiver BroadcastReceiver} hasn't finished executing within 10 seconds</li> within 5 seconds</li>
<li>A {@link android.content.BroadcastReceiver BroadcastReceiver}
hasn't finished executing within 10 seconds</li>
</ul> </ul>
<h2 id="avoiding">How to Avoid ANR</h2> <h2 id="avoiding">How to Avoid ANR</h2>

398
docs/html/guide/practices/screens_support.jd
View File

@@ -131,57 +131,79 @@ screens. </p></dd>
</dl> </dl>
<h3 id="range">Range of Screens Supported</h3> <h3 id="range">Range of screens supported</h3>
<p>Android 1.5 and earlier versions of the platform were designed to support a <p>Starting from Android 1.6, the platform provides support for multiple screen
single screen configuration &mdash; 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 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 which the platform runs. If you are developing an application that will run
applications for proper display on a range of devices and screens.</p> 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 application developers design their user interfaces for <p>To simplify the way that developers design their user interfaces for
multiple devices, and to allow more devices to participate without impacting multiple devices and to allow more devices to participate without affecting
applications, the platform divides the range of actual supported screen sizes applications, the platform divides the range of actual supported screen sizes
and resolutions into:</p> and resolutions into:</p>
<ul> <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 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>) <li>A set of three generalized densities: <em>hdpi</em> (high), <em>mdpi</em> (medium), and <em>ldpi</em> (low)
</ul> </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 <p>Applications can provide custom resources (primarily layouts) for any of the
three generalized sizes, if needed, and they can also provide resources three generalized sizes and can provide resources (primarily drawables such as
(primarily drawables such as images) for any of the three generalized densities. images) for any of the three generalized densities. Applications do not need to
Applications do not need to work with the actual physical size or density of the work with the actual physical size or density of the device screen. At run time,
device screen. At run time, the platform handles the loading of the correct size the platform handles the loading of the correct size or density resources, based
or density resources, based on the generalized size or density of the current on the generalized size or density of the current device screen, and adapts them
device screen, and adapts them to the actual pixel map of the screen.</p> to the actual pixel map of the screen.</p>
<p>The table below lists some of the more common screens supported <p>The generalized size/density configurations are arranged around a
by Android and illustrates how the platform maps them to generalized screen baseline configuration that is assigned a size of <em>normal</em> and a density of
configurations. Some devices use screens that are not specifically listed <em>mdpi</em> (medium). All applications written for Android 1.5 or earlier are (by
in the table &mdash; the platform maps those to the same set generalized definition) designed for the baseline HVGA screen used on the T-Mobile G1 and
screen configurations. </p> similar devices, which is size <em>normal</em> and density
<em>mdpi</em>.</p>
<p class="table-caption" id="screens-table"><strong>Table 1.</strong> Examples of <p>Each generalized screen configuration spans a range of actual screen
device screens supported by Android.</p> 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>
<table id="screens-table" width="80%" style="margin-top:2em;">
<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 layouts and resources for
generalized size-density configurations, you do not necessarily need to do write
custom code or provide custom resources for each of the nine supported
configurations. 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 id="screens-table">
<tbody> <tbody>
<tr> <tr>
<td></td> <td style="border:none"></td>
<td style="background-color:#f3f3f3"> <td style="background-color:#f3f3f3">
<nobr>Low density (120), <em>ldpi</em></nobr> <nobr>Low density (120), <em>ldpi</em></nobr>
</td> </td>
@@ -196,10 +218,7 @@ device screens supported by Android.</p>
<td style="background-color:#f3f3f3"> <td style="background-color:#f3f3f3">
<em>Small</em> screen <em>Small</em> screen
</td> </td>
<td style="font-size:.9em;"> <td style="font-size:.9em;">QVGA (240x320)</td>
<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></td>
<td></td> <td></td>
@@ -208,74 +227,29 @@ device screens supported by Android.</p>
<td style="background-color:#f3f3f3"> <td style="background-color:#f3f3f3">
<em>Normal</em> screen <em>Normal</em> screen
</td> </td>
<td style="font-size:.9em;"> <td style="font-size:.9em;">WQVGA400 (240x400)<br>WQVGA432 (240x432)</td>
<ul style="padding:0"> <td style="font-size:.9em;">HVGA (320x480)</td>
<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> <td style="font-size:.9em;">WVGA800 (480x800)<br>WVGA854 (480x854)</td>
<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>
<tr> <tr>
<td style="background-color:#f3f3f3"> <td style="background-color:#f3f3f3">
<em>Large</em> screen <em>Large</em> screen
</td> </td>
<td></td> <td></td>
<td style="font-size:.9em;"> <td style="font-size:.9em;">WVGA800* (480x800)<br>WVGA854* (480x854)</td>
<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> <td></td>
</tr> </tr>
</tbody> <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>
</table> </table>
<p class="caption" style="margin-top:1em;margin-bottom:1.5em;"> </p>
<p>As shown above, the various screen configurations are arranged around a
<em>baseline screen</em> that 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 &mdash; from 3.0" to 3.5" diagonal &mdash; 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 create 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>
<!--
<p>For an overview of the relative numbers of high (hdpi), medium (mdpi), and <p>For an overview of the relative numbers of high (hdpi), medium (mdpi), and
low (ldpi) density screens, see the <a low (ldpi) density screens in Android-powered devices available now, see the <a
href="{@docRoot}guide/resources/dashboard/screen-densities.html">Screen Densities dashboard</a>.</p> href="{@docRoot}resources/dashboard/screens.html">Screen Sizes and Densities</a> dashboard.</p>
-->
<h3 id="support">How Android supports multiple screens</h3> <h3 id="support">How Android supports multiple screens</h3>
@@ -307,8 +281,8 @@ size- and density-specific resources, if needed. The qualifiers for
size-specific resources are <code>large</code>, <code>normal</code>, and size-specific resources are <code>large</code>, <code>normal</code>, and
<code>small</code>, and those for density-specific resources are <code>small</code>, and those for density-specific resources are
<code>hdpi</code> (high), <code>mdpi</code> (medium), and <code>ldpi</code> <code>hdpi</code> (high), <code>mdpi</code> (medium), and <code>ldpi</code>
(low). The qualifiers correspond to the generalized densities given in (low). The qualifiers correspond to the generalized densities described in
<a href="#range">Table 1</a>, above.</li> <a href="#range">Range of screens supported</a>, above.</li>
<li>The platform also provides a <li>The platform also provides a
<a href="{@docRoot}guide/topics/manifest/supports-screens-element.html"> <a href="{@docRoot}guide/topics/manifest/supports-screens-element.html">
<code>&lt;supports-screens&gt;</code></a> <code>&lt;supports-screens&gt;</code></a>
@@ -457,7 +431,7 @@ different.</p>
<div id=vi09 style=TEXT-ALIGN:left> <div id=vi09 style=TEXT-ALIGN:left>
<img src="{@docRoot}images/screens_support/dip.png" style="padding-bottom:0;margin-bottom:0;" /> <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 <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 1em;"><strong>Figure 2.</strong> Examples of density independence on WVGA high
density (left), HVGA medium density (center), and QVGA low density (right). </p> density (left), HVGA medium density (center), and QVGA low density (right). </p>
</div> </div>
@@ -479,7 +453,8 @@ whose attributes you can use to control the
display of your application on different classes of device screens, as listed display of your application on different classes of device screens, as listed
below. The <code>smallScreens</code>, <code>normalScreens</code>, and below. The <code>smallScreens</code>, <code>normalScreens</code>, and
<code>largeScreens</code> attributes correspond to the generalized screen sizes <code>largeScreens</code> attributes correspond to the generalized screen sizes
shown in <a href="#range">Table 1</a>, earlier in this document.</p> described in <a href="#range">Range of screens supported</a>, earlier in this
document.</p>
<table id="vrr8"> <table id="vrr8">
<tr> <tr>
@@ -489,6 +464,12 @@ shown in <a href="#range">Table 1</a>, earlier in this document.</p>
<th > <th >
Description Description
</th> </th>
<th>
Default value,<br><nobr>Android 1.5 and Lower</nobr>
</th>
<th>
Default value,<br><nobr>Android 1.6 and Higher</nobr>
</th>
</tr> </tr>
<tr> <tr>
<td> <td>
@@ -497,10 +478,10 @@ shown in <a href="#range">Table 1</a>, earlier in this document.</p>
<td> <td>
Whether or not the application UI is designed for use on Whether or not the application UI is designed for use on
<em>small</em> screens &mdash; "<code>true</code>" if it is, and <em>small</em> screens &mdash; "<code>true</code>" if it is, and
"<code>false</code>" if not. See <a href="#defaults">Default values for "<code>false</code>" if not. </p>
attributes</a> for information about the assumed value of this attribute, if not
declared.
</td> </td>
<td>"<code>false</code>"</td>
<td>"<code>true</code>"</td>
</tr> </tr>
<tr> <tr>
<td> <td>
@@ -509,8 +490,10 @@ declared.
<td> <td>
Whether or not the application UI is designed for use on Whether or not the application UI is designed for use on
<em>normal</em> screens &mdash; "<code>true</code>" if it is, and <em>normal</em> screens &mdash; "<code>true</code>" if it is, and
"<code>false</code>" if not. The default value is "<code>true</code>". "<code>false</code>" if not. The default value is always "<code>true</code>".
</td> </td>
<td>"<code>true</code>"</td>
<td>"<code>true</code>"</td>
</tr> </tr>
<tr> <tr>
<td> <td>
@@ -519,10 +502,10 @@ declared.
<td> <td>
Whether or not the application UI is designed for use on Whether or not the application UI is designed for use on
<em>large</em> screens &mdash; "<code>true</code>" if it is, and <em>large</em> screens &mdash; "<code>true</code>" if it is, and
"<code>false</code>" if not. See <a href="#defaults">Default values for "<code>false</code>" if not.
attributes</a> for information about the assumed value of this attribute, if not
declared.
</td> </td>
<td>"<code>false</code>"</td>
<td>"<code>true</code>"</td>
</tr> </tr>
<tr> <tr>
<td> <td>
@@ -535,9 +518,13 @@ in different density environments &mdash; "<code>true</code>" if so, and
<ul> <ul>
<li>If set to "<code>true</code>", the platform disables its <li>If set to "<code>true</code>", the platform disables its
density-compatibility features for all screen densities &mdash; specifically, density-compatibility features for all screen densities &mdash; specifically,
the auto-scaling of absolute pixel units and math &mdash; and relies on the the auto-scaling of absolute pixel units (<code>px</code>) and math &mdash; and
application to use density-independent pixel units and/or to manage the relies on the application to use density-independent pixel units
adaptation of pixel values according to density of the current screen. </li> (<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 <li>If set to "<code>false</code>", the platform enables its
density-compatibility features for all screen densities. In this case, the density-compatibility features for all screen densities. In this case, the
@@ -546,45 +533,73 @@ 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 (160). The platform then transparently auto-scales the application's pixel units
and math as needed to match the actual device screen density. </li> and math as needed to match the actual device screen density. </li>
</ul> </ul>
<p>See <a href="#defaults">Default values for attributes</a> for <p>Note that the setting of this attribute affects density-compatibility only.
information about the assumed value of this attribute, if not declared.</p> It does not affect size-compatibility features such as display on a virtual
baseline screen.</p>
</td> </td>
<td>"<code>false</code>"</td>
<td>"<code>true</code>"</td>
</tr> </tr>
</table> </table>
<p>In general, when you declare a screen-size attribute <p>In general, when you declare a screen-size attribute
(<code>smallScreens</code>, <code>normalScreens</code>, or (<code>smallScreens</code>, <code>normalScreens</code>, or
<code>largeScreens</code>) as "true", you are signaling to the platform that <code>largeScreens</code>) as "<code>true</code>", you are signaling to the
your application wants to manage its UI by itself, for all screen sizes, without platform that your application is designed to render properly on that screen
the platform applying any size-compatibility behaviors (such as a virtual HVGA size. As a result, the platform does not apply any size-compatibility features
display area). If you declare a screen-size attribute as "false", you are (such as a virtual HVGA display area). If you declare a screen-size attribute as
signaling that your application is not designed for that screen size. The "<code>false</code>", you are signaling that your application is <em>not</em>
effects are conditioned by the screen size that your application does not designed for that screen size. In this case, the platform <em>does</em> apply
support:</p> 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> <ul>
<li>If you declare <code>largeScreens="false"</code>, your application can <li>Assume that you declare <code>smallScreens="false" normalScreens="true"
still be installed by users of devices with large screens. When run on a device largeScreens="false" </code> in your application's manifest. <p>Although the
with a large screen, this attribute value causes the platform to run the application is not designed for display on large screens, the platform can still
application in compatibility mode, rendering it in a baseline screen area run it successfully in <a href="#compatibility-examples">size-compatibility
(normal size, medium density) reserved on the larger screen. See mode</a>. Android Market does not filter the application from devices
<a href="#compatibility-examples">Screen-Compatibility Examples</a> for an <em>normal</em> and <em>large</em> size screens, but does filter it from
illustration of what an application looks like when displayed in compatibility <em>small</em> size screens, since the application provides no screen support at
mode.</li> <em>small</em> size (and there is no smaller size).</p></li>
<li>If you declare <code>smallScreens="false"</code>, your application can
still be installed by users of devices with small screens. However, this <li>Assume that you declare <code>smallScreens="false" normalScreens="false"
attribute value causes Android Market to filter your application from the list largeScreens="true"</code> in your application's manifest. <p>Android Market
of applications available to such users. In effect, this prevents users from filters the application from users of devices with <em>small</em> and
installing the application on small-screen devices. </li> <em>normal</em> size screens. In effect, this prevents such users from
installing the application.</p></li>
</ul> </ul>
<p>If you declare the <code>android:anyDensity</code> attribute as "true", you <p>If you declare the <code>android:anyDensity</code> attribute as
are signaling to the platform that your application wants to manage its UI by "<code>true</code>", you are signaling to the platform that your application is
itself, for all screen densities, using the actual screen dimensions and pixels. designed to display properly on any screen density. In this case, the
In this case, the application must ensure that it declares its UI dimensions application must ensure that it declares its UI dimensions using
using density-independent pixels and scales any actual pixel values or math by density-independent pixels (<code>dp</code>) and scales any absolute pixel
the scaling factor available from values (<code>px</code>) or math by the scaling factor available from {@link
{@link android.util.DisplayMetrics#density android.util.DisplayMetrics.density}.</p> android.util.DisplayMetrics#density android.util.DisplayMetrics.density}. See <a
href="#dips-pels">Converting from dips to pixels</a> for an example.</p>
<p>Note that the setting of the <code>android:anyDensity</code> attribute does <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 not affect the platform's pre-scaling of drawable resources, such as bitmaps and
@@ -594,22 +609,22 @@ nine-patch images, which always takes place by default. </p>
normal, and small screens in any densities.</p> normal, and small screens in any densities.</p>
<pre>&lt;manifest xmlns:android="http://schemas.android.com/apk/res/android"&gt; <pre>&lt;manifest xmlns:android="http://schemas.android.com/apk/res/android"&gt;
...
&lt;supports-screens &lt;supports-screens
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; android:largeScreens="true" &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; android:largeScreens="true"
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; android:normalScreens="true" &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; android:normalScreens="true"
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; android:smallScreens="true" &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; android:smallScreens="true"
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; android:resizable="true"
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; android:anyDensity="true" /&gt; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; android:anyDensity="true" /&gt;
...
&lt;/manifest&gt; &lt;/manifest&gt;
</pre> </pre>
<!-- &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; android:resizeable="true" -->
<h4 id="defaults"> <h4 id="defaults">
Default values for attributes Default values for attributes
</h4> </h4>
<p>The default values for the <code>&lt;supports-screens&gt;</code> attributes <p>The default values for the <code>&lt;supports-screens&gt;</code> attributes
differs, depending on the the value of the differ, depending on the the value of the
<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code>android:minSdkVersion</code></a> <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 attribute in the application's manifest, as well as on
the value of <code>android:targetSdkVersion</code>, if declared:</p> the value of <code>android:targetSdkVersion</code>, if declared:</p>
@@ -618,19 +633,20 @@ the value of <code>android:targetSdkVersion</code>, if declared:</p>
<ul> <ul>
<li> <li>
If <code>android:minSdkVersion</code> or If <code>android:minSdkVersion</code> or
<code>android:targetSdkVersion</code> is "3" (Android 1.5) or lower, the default <code>android:targetSdkVersion</code> is "4" (Android 1.6) or higher, the
value for everything except android:normalScreens is <code>false</code>. If you default value for everything is "<code>true</code>". If your application uses
are primarily targeting pre-Android 1.6 platforms but also want to support other APIs introduced in Android 1.6 or higher, but does not support specific screen
densities/screen sizes, you need to set the appropriate attributes to densities and/or screen sizes, you need to explicitly set the appropriate
<code>true</code>. attributes to "<code>false</code>".
</li> </li>
<li> <li>
If <code>android:minSdkVersion</code> or If <code>android:minSdkVersion</code> is declared with a value of "3"
<code>android:targetSdkVersion</code> is "4" (Android 1.6) or higher, the (Android 1.5) or lower <em>and</em> a <code>android:targetSdkVersion</code>
default value for everything is <code>true</code>. If your application attribute is <em>not</em> declared with a value of "4" or higher, the default
requires&nbsp;<span style=BACKGROUND-COLOR:#ffffff>Android 1.6 </span>features, value for all attributes except <code>android:normalScreens</code> is
but does not support these densities and/or screen sizes, you need to set the "<code>false</code>". If you are primarily targeting pre-Android 1.6 platforms
appropriate attributes to <code>false</code>. but also want to support other densities/screen sizes, you need to explicitly
set the appropriate attributes to "<code>true</code>".
</li> </li>
<li> <li>
Note that <code>android:normalScreens</code> always defaults to Note that <code>android:normalScreens</code> always defaults to
@@ -646,8 +662,8 @@ appropriate attributes to <code>false</code>.
of resources based on the characteristics of the screen on which your application 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 is running. You can use these qualifiers to provide size- and density-specific
resources in your application. For more information about the generalized sizes resources in your application. For more information about the generalized sizes
and densities that correspond to the qualifiers, see <a href="#range">Table and densities that correspond to the qualifiers, see <a href="#range">Range
1</a>, earlier in this document.</p> of Screens Supported</a>, earlier in this document.</p>
<table> <table>
<tr> <tr>
@@ -659,30 +675,29 @@ and densities that correspond to the qualifiers, see <a href="#range">Table
<tr> <tr>
<td rowspan="3">Size</td> <td rowspan="3">Size</td>
<td><code>small</code></td> <td><code>small</code></td>
<td>Resources for small screens, such as QVGA low density.</td> <td>Resources designed for <em>small</em> size screens.</td>
</tr> </tr>
<tr> <tr>
<td><code>normal</code></td> <td><code>normal</code></td>
<td>Resources for normal (baseline configuration) screens, such as T-Mobile <td>Resources designed for <em>normal</em> size screens.</td>
G1/HTC Magic screen size, or equivalent.</td>
</tr> </tr>
<tr> <tr>
<td><code>large</code></td> <td><code>large</code></td>
<td>Resources for large screens. Typical example is a tablet like device.</td> <td>Resources for <em>large</em> size screens.</td>
</tr> </tr>
<tr> <tr>
<td rowspan="4">Density</td> <td rowspan="4">Density</td>
<td><code>ldpi</code></td> <td><code>ldpi</code></td>
<td>Low-density resources, for 100 to 140 dpi screens.</td> <td>Resources designed for low-density (<em>ldpi</em>) screens.</td>
</tr> </tr>
<tr> <tr>
<td><code>mdpi</code></td> <td><code>mdpi</code></td>
<td>Medium-density resources for 140 to 180 dpi screens.</td> <td>Resources designed for medium-density (<em>mdpi</em>) screens.</td>
</tr> </tr>
<tr> <tr>
<td><code>hdpi</code></td> <td><code>hdpi</code></td>
<td>High-density resources for 190 to 250 dpi screens.</td> <td>Resources designed for high-density (<em>hdpi</em>) screens.</td>
</tr> </tr>
<tr> <tr>
<td><code>nodpi</code></td> <td><code>nodpi</code></td>
@@ -747,8 +762,8 @@ Alternative Resources</a>.</p>
<h2 id="screen-independence">Best practices for Screen Independence</h2> <h2 id="screen-independence">Best practices for Screen Independence</h2>
<p>The objective of supporting multiple screens is to create an application that <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 can run properly on any display and function properly on any of the generalized
configurations listed in <a href="#range">Table 1</a> earlier in this document. screen configurations supported by the platform.
</p> </p>
<p>You can easily ensure that your application will display properly on <p>You can easily ensure that your application will display properly on
@@ -855,7 +870,7 @@ scroll threshold can be obtained as follows:</p>
<div style="float: right;background-color:#fff;margin: 0;padding: 20px 0 20px 20px;"> <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;"> <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> <p class="caption" style="margin:0;padding:0;"><strong>Figure 3.</strong> Comparison of pre-scaled and auto-scaled bitmaps.</p>
</div> </div>
<p>Even with the size- and density-compatibility features that the platform <p>Even with the size- and density-compatibility features that the platform
@@ -947,7 +962,7 @@ pre-scaling but uses less memory. You can refer to the documentation of
{@link android.graphics.Canvas Canvas} for more {@link android.graphics.Canvas Canvas} for more
information on auto-scaling.</p> information on auto-scaling.</p>
<p>Figure 2, at right, demonstrates the results of the pre-scale and auto-scale <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 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 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 being scaled to match the current screen density, however the scaled bitmaps
@@ -1078,7 +1093,7 @@ attribute(s) to your application's manifest. -->
<div id="f9.5" style="float:right;margin:0;padding:0;"> <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;"> <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> <p class="caption" style="margin:0 0 1.5em 1em;padding:0 0 0 1em;"><strong>Figure 4.</strong>
A typical set of AVDs for testing screens support.</p> A typical set of AVDs for testing screens support.</p>
</div> </div>
@@ -1143,52 +1158,29 @@ launching the emulator, for example:</p>
<p>Note that starting the emulator with the <code>-scale</code> option will <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 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 monitor. The default emulator skins included in the Android SDK are listed
1.6 SDK will emulate the following screen sizes:</p> in <a href="#screens-table">Table 1</a>, earlier in this document.</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;"> <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;"> <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> <p class="caption" style="margin:0 0 1.5em 1em;padding:0 0 0 1em; width:280px;"><strong>Figure 5.</strong>
Resolution and density options that you can use, when creating an AVD using the AVD Manager.</p> Resolution and density options that you can use, when creating an AVD using the AVD Manager.</p>
</div> </div>
<p>You should also make sure to test your application on different physical <p>You should also make sure to test your application on different physical
screen sizes within a single size-density configuration. For example, according screen sizes within a single size-density configuration. For example, to
to <a href="#range">Table 1</a>, the minimum supported diagonal of QVGA is 2.8". display this screen configuration on a 30" monitor you will need to adjust
To display this is on a 30" monitor you will need to adjust the value passed to the value passed to <code>-scale</code> to 96*2.8/3.3 = 81dpi. You can also
<code>-scale</code> to 96*2.8/3.3 = 81dpi. You can also pass a float value to pass a float value to <code>-scale</code> to specify your own scaling factor:</p>
<code>-scale</code> to specify your own scaling factor:</p>
<pre>emulator -avd &lt;name&gt; -scale 0.6</pre> <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 <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 or density not supported by the built-in skins, you can either adjust an
existing skin, or create an AVD existing skin, or create an AVD that uses a custom resolution or density.</p>
that uses a custom resolution or density.</p>
<p>In the AVD Manager, you can specify a custom skin resolution or density in <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> 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 <p>In the <code>android</code> tool, follow these steps to create an AVD with a
custom resolution or density:</p> custom resolution or density:</p>
@@ -1203,9 +1195,9 @@ Here's an example:
<li>To specify a custom density for the skin, answer "yes" when asked whether <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> 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 <li>Continue through the various profile settings until the tool asks you to
specify "Abstracted LCD density" (<em>hw.lcd.density</em>). Consult <a specify "Abstracted LCD density" (<em>hw.lcd.density</em>). Enter an appropriate
href="#range">Table 1</a>, earlier in this document, and enter the appropriate value, such as "120" for a low-density screen, "160" for a medium density screen,
value. For example, enter "160" to use medium density for the WVGA800 screen.</li> or "240" for a high-density screen.</li>
<li>Set any other hardware options and complete the AVD creation.</li> <li>Set any other hardware options and complete the AVD creation.</li>
</ol> </ol>

BIN
docs/html/images/screens_support/screens-ranges.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 8.3 KiB