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

am 828b6816: Merge "docs: add docs for xhdpi and xlarge screen support update screen ranges figure bug: 3099462" into gingerbread

Browse Source 
* commit '828b68166679ebfc0002e2ea516ca91e6fb13597':
  docs: add docs for xhdpi and xlarge screen support update screen ranges figure bug: 3099462
This commit is contained in:
Scott Main
2010-11-19 16:51:57 -08:00
committed by Android Git Automerger
parent 716f60ce60 828b681666
commit 55ff5708bb
3 changed files with 297 additions and 187 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -35,7 +35,9 @@ page.title=Supporting Multiple Screens
<ol>
<li><code><a href="{@docRoot}guide/topics/manifest/supports-screens-element.html">&lt;supports-screens&gt;</a></code></li>
<li><code><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">&lt;uses-sdk&gt;</a></code></li>
<li><a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">Alternative Resources</a></li>
<li><a
href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">
Providing Alternative Resources</a></li>
<li><a href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a></li>
</ol>
@@ -53,7 +55,7 @@ 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.
supported device screens and that you can deploy to any device as a single {@code .apk}.
</p>
<p>If you have already developed and published an application for Android 1.5 or
@@ -63,10 +65,16 @@ and that are running Android 1.6 or later. In most cases, only minor adjustments
are needed, however you should make sure to <a href="#testing">test your
application</a> on all supported screens. </p>
<p>Starting in Android 2.2, the platform includes support for extra high density screens
(<em>xhdpi</em>), and starting in Android 2.3, the platform includes support for extra large screens
(<em>xlarge</em>). If you've already followed the guidance in this document to support all other
screen types, you should consider providing additional support for <em>xhdpi</em> and
<em>xlarge</em> screens.</p>
<p>In particular, if you have an existing application that you would like to
make available 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>
make available on small screens (such as QVGA) or for which you would like to provide better support
for extra large screens, please see <a href="#strategies">Strategies for Legacy Applications</a> for
more information about how to do that. </p>
<h2 id="overview">Overview of Screens Support</h2>
@@ -82,11 +90,11 @@ screen-compatibility features.</p>
<dl>
<dt><em>Screen size</em></dt>
<dd>Actual physical size, measured as the screen's diagonal.
<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 &mdash; the platform transparently handles
<p>For simplicity, Android collapses all actual screen sizes into four
generalized sizes: small, normal, large, and extra large. Applications can provide custom
layouts for each of these four sizes &mdash; the platform transparently handles
the rendering of the layouts at the actual screen size.</p></dd>
<dt><em>Aspect ratio</em></dt>
@@ -110,22 +118,22 @@ sometimes significantly more &mdash; pixels spread across the same area. The
density of a screen is important because, other things being equal, a UI element
(such as a button) whose height and width are defined in terms of screen pixels
will appear larger on the lower density screen and smaller on the higher density
screen. </p>
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 &mdash; 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>
<p>For simplicity, Android collapses all actual screen densities into four
generalized densities: low, medium, large, and extra large. Applications can provide custom
resources for each of these densities &mdash; the platform handles any necessary
scaling of the resources up or down to meet the specific screen density. </p></dd>
<dt><em>Density-independent pixel (dp)</em></dt>
<dd>A virtual pixel unit that applications can use in defining their UI, to
express layout dimensions or position in a density-independent way.
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
the dp units needed, based on the actual density of the screen in use. The
conversion of dp units to screen pixels is simple: <nobr><code>pixels = dps *
(density / 160)</code></nobr>. For example, on 240 dpi screen, 1 dp would equal 1.5
physical pixels. Using dp units to define your application's UI is highly
recommended, as a way of ensuring proper display of your UI on different
screens. </p></dd>
</dl>
@@ -146,13 +154,19 @@ 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: <em>hdpi</em> (high), <em>mdpi</em> (medium), and <em>ldpi</em> (low)
<li>A set of four generalized sizes: <em>small</em>, <em>normal</em>, <em>large</em>,
and <em>xlarge</em></em>
<li>A set of four generalized densities: <em>ldpi</em> (low), <em>mdpi</em> (medium),
<em>hdpi</em> (high), and <em>xhdpi</em> (extra high)
</ul>
<p class="note"><strong>Note:</strong> The <code>xhdpi</code> density category was added in
Android 2.2 (API Level 8). The <em>xlarge</em> size category was added in Android 2.3 (API Level
9).</p>
<p>Applications can provide custom resources (primarily layouts) for any of the
three generalized sizes and can provide resources (primarily drawables such as
images) for any of the three generalized densities. Applications do not need to
four generalized sizes and can provide resources (primarily drawables such as
images) for any of the four generalized densities. Applications do not need to
work with the actual physical size or density of the device screen. At run time,
the platform handles the loading of the correct size or density resources, based
on the generalized size or density of the current device screen, and adapts them
@@ -177,8 +191,8 @@ its characteristics. </p>
<img src="{@docRoot}images/screens_support/screens-ranges.png" />
<p class="img-caption"><strong>Figure 1.</strong>
Illustration of how the Android platform maps actual screen densities and sizes
<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
@@ -213,6 +227,9 @@ sizes and densities of emulator skins included in the Android SDK.</p>
<td style="background-color:#f3f3f3">
<nobr>High density (240), <em>hdpi</em><nobr>
</td>
<td style="background-color:#f3f3f3">
<nobr>Extra high density (320), <em>xhdpi</em><nobr>
</td>
</tr>
<tr>
<td style="background-color:#f3f3f3">
@@ -222,6 +239,7 @@ sizes and densities of emulator skins included in the Android SDK.</p>
</td>
<td></td>
<td></td>
<td></td>
</tr>
<tr>
<td style="background-color:#f3f3f3">
@@ -230,6 +248,7 @@ sizes and densities of emulator skins included in the Android SDK.</p>
<td style="font-size:.9em;">WQVGA400 (240x400)<br>WQVGA432 (240x432)</td>
<td style="font-size:.9em;">HVGA (320x480)</td>
<td style="font-size:.9em;">WVGA800 (480x800)<br>WVGA854 (480x854)</td>
<td style="font-size:.9em;"></td>
</tr>
<tr>
<td style="background-color:#f3f3f3">
@@ -238,16 +257,27 @@ sizes and densities of emulator skins included in the Android SDK.</p>
<td></td>
<td style="font-size:.9em;">WVGA800* (480x800)<br>WVGA854* (480x854)</td>
<td></td>
<td></td>
</tr>
<tr>
<td colspan="4" style="border:none;font-size:90%;">* To emulate this
configuration, specify a custom density of 160 when
<td style="background-color:#f3f3f3">
<em>Extra Large</em> screen
</td>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr>
<td colspan="4" style="border:none;font-size:90%;">* To emulate this
configuration, specify a custom density of 160 when
creating an AVD that uses a WVGA800 or WVGA854 skin.
</td>
</tr>
</table>
<p>For an overview of the relative numbers of high (hdpi), medium (mdpi), and
low (ldpi) density screens in Android-powered devices available now, see the <a
<p>For an overview of the relative numbers of high (hdpi), medium (mdpi), and
low (ldpi) density screens in Android-powered devices available now, see the <a
href="{@docRoot}resources/dashboard/screens.html">Screen Sizes and Densities</a> dashboard.</p>
@@ -262,9 +292,9 @@ resources at run time is based on the alternative resources framework.
<p> If you want to use size- or density-specific layouts or drawables in your
application and you are not familiar with resource qualifiers or how the
platform uses them, please read
platform uses them, please read
<a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">
Alternative Resources</a>.
Providing Alternative Resources</a>.
</div>
</div>
@@ -277,19 +307,20 @@ to use them:</p>
<ul>
<li>The platform supports a set of resource qualifiers that let you provide
size- and density-specific resources, if needed. The qualifiers for
size-specific resources are <code>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 described in
size- and density-specific resources, if needed. The qualifiers for
size-specific resources are <code>small</code>, <code>normal</code>, <code>large</code>, and
<code>xlarge</code>. Those for density-specific resources are <code>ldpi</code>
(low), <code>mdpi</code> (medium), <code>hdpi</code> (high), and <code>xhdpi</code> (extra high).
The qualifiers correspond to the generalized densities described in
<a href="#range">Range of screens supported</a>, above.</li>
<li>The platform also provides a
<li>The platform also provides a
<a href="{@docRoot}guide/topics/manifest/supports-screens-element.html">
<code>&lt;supports-screens&gt;</code></a>
manifest element, whose attributes
<code>android: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>,
<code>android:smallScreens</code>, <code>android:normalScreens</code>,
<code>android:largeScreens</code>, and <code>android:xlargeScreens</code> let you specify what
generalized screen sizes
your application supports. Another attribute, <code>android:anyDensity</code>,
lets you indicate whether or not your application includes built-in support for
multiple densities.</li>
</ul>
@@ -299,7 +330,7 @@ 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>
<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
@@ -344,18 +375,18 @@ 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>
<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
on small screens and then upload an updated version that explicitly
<a href="#attrs">indicates support for small screens</a>. </p>
</div>
</div>
</div>
<li><em>Compatibility-mode display on larger screen-sizes</em>
@@ -374,7 +405,7 @@ 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="#attrs">Manifest elements for screens support</a> and the
<a href="#compatibility-examples">Screen-Compatibility Examples</a>
section.</p></li>
</ol>
@@ -415,7 +446,7 @@ does this in three ways: </p>
<ul>
<li>Through pre-scaling of drawable resources (scaled at resource loading
time)</li>
<li>Through auto-scaling of density-independent pixel (dip) values used in
<li>Through auto-scaling of density-independent pixel (dp) values used in
layouts</li>
<li>Through auto-scaling of absolute pixel values used in the application (only
needed if the application has set <code>android:anyDensity="false"</code> in its
@@ -437,25 +468,36 @@ density (left), HVGA medium density (center), and QVGA low density (right). </p>
<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
in density-independent pixels (<code>dp</code> or <code>dp</code>) or
scale-independent pixels (<code>sip</code> or <code>sp</code>, for text only).
If you are using absolute pixel values in the application and manifest includes
<a href="#attrs"><code>android:anyDensity="true"</code></a>, you will also need
to scale the pixel values. See <a href="#dips-pels">Converting from dips to
pixels</a> for more information. </p>
to scale the pixel values. See <a href="#dips-pels">Converting dp units to
pixel units</a> for more information. </p>
<h3 id="attrs">Manifest attributes for screens support</h3>
<p> Android 1.6 introduced a new manifest element,
<p> Android 1.6 introduced a new manifest element,
<a href="{@docRoot}guide/topics/manifest/supports-screens-element.html"><code>&lt;supports-screens&gt;</code></a>,
whose attributes you can use to control the
display of your application on different classes of device screens, as listed
below. The <code>smallScreens</code>, <code>normalScreens</code>, and
<code>largeScreens</code> attributes correspond to the generalized screen sizes
in table 2. The <code>smallScreens</code>, <code>normalScreens</code>, <code>largeScreens</code> and
<code>xlargeScreens</code> attributes correspond to the generalized screen sizes
described in <a href="#range">Range of screens supported</a>, earlier in this
document.</p>
document. Notice that the default values for each attribute vary, depending
on your minimum and targeted platform, as indicated in the <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code
android:minSdkVersion}</a> and <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code
android:targetSdkVersion}</a> attributes of your <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code &lt;uses-sdk&gt;}</a>
manifest element.</p>
<p class="table-caption" id="table2"><strong>Table 2.</strong> Summary of attributes for the <a
href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
&lt;supports-screens&gt;}</a> manifest element, including default values based on platform
version.</p>
<table id="vrr8">
<tr>
<th>
@@ -465,10 +507,12 @@ document.</p>
Description
</th>
<th>
Default value,<br><nobr>Android 1.5 and Lower</nobr>
Default value, when<br><nobr><code>minSdkVersion</code> or</nobr>
<code>targetSdkVersion</code> is 4 or lower
</th>
<th>
Default value,<br><nobr>Android 1.6 and Higher</nobr>
Default value, when<br><nobr><code>minSdkVersion</code> or</nobr>
<code>targetSdkVersion</code> is 5 or higher
</th>
</tr>
<tr>
@@ -538,13 +582,48 @@ It does not affect size-compatibility features such as display on a virtual
baseline screen.</p>
</td>
<td>"<code>false</code>"</td>
<td>"<code>true</code>"</td>
</tr>
<tr>
<td colspan="4"><strong>Note:</strong> Android 2.3 (API Level 9) introduced a new
attribute for the <code>&lt;supports-screens&gt;</code> element: <code>xlargeScreens</code>, shown
below. It works the same as the other screen attributes above, but, if neither your
<code>minSdkVersion</code> or <code>targetSdkVersion</code> are set to "9", the default value is
"false" when your application is installed on a device running Android 2.3.</td>
</tr>
<tr>
<th>
Attribute
</th>
<th >
Description
</th>
<th>
Default value, when<br><nobr><code>minSdkVersion</code> or</nobr>
<code>targetSdkVersion</code> is 8 or lower
</th>
<th>
Default value, when<br><nobr><code>minSdkVersion</code> or</nobr>
<code>targetSdkVersion</code> is 9 or higher
</th>
</tr>
<tr>
<td>
<code>android:xlargeScreens</code>
</td>
<td>
Whether or not the application UI is designed for use on
<em>xlarge</em> screens &mdash; "<code>true</code>" if it is, and
"<code>false</code>" if not.
</td>
<td>"<code>false</code>"</td>
<td>"<code>true</code>"</td>
</tr>
</table>
<p>In general, when you declare a screen-size attribute
(<code>smallScreens</code>, <code>normalScreens</code>, or
<code>largeScreens</code>) as "<code>true</code>", you are signaling to the
(<code>smallScreens</code>, <code>normalScreens</code>, <code>largeScreens</code>, or
<code>xlargeScreens</code>) as "<code>true</code>", you are signaling to the
platform that your application is designed to render properly on that screen
size. As a result, the platform does not apply any size-compatibility features
(such as a virtual HVGA display area). If you declare a screen-size attribute as
@@ -577,16 +656,20 @@ features for applications.</p>
<ul>
<li>Assume that you declare <code>smallScreens="false" normalScreens="true"
largeScreens="false" </code> in your application's manifest. <p>Although the
application is not designed for display on large screens, the platform can still
run it successfully in <a href="#compatibility-examples">size-compatibility
mode</a>. Android Market does not filter the application from devices
<em>normal</em> and <em>large</em> size screens, but does filter it from
<em>small</em> size screens, since the application provides no screen support at
<em>small</em> size (and there is no smaller size).</p></li>
largeScreens="false" xlargeScreens="false"</code> in your application's manifest. <p>Although the
application is not designed for display on large or extra large screens, the platform can still
run it successfully in <a href="#compatibility-examples">screen-compatibility
mode</a>. Android Market shows the application to devices with
<em>normal</em>, <em>large</em>, and <em>xlarge</em> size screens, but does filter it from
<em>small</em> size screens, because the application provides no screen support at
<em>small</em> size. Android's <a href="#compatibility-examples">screen-compatibility
mode</a> mode does not provide support for screens that are smaller than those the
application supports&mdash;it only provides support for screens that are larger. Thus,
although the application declares "false" for <em>large</em> and <em>xlarge</em> screens,
the application still functions, but runs in compatibility mode.</p></li>
<li>Assume that you declare <code>smallScreens="false" normalScreens="false"
largeScreens="true"</code> in your application's manifest. <p>Android Market
largeScreens="true" xlargeScreens="true"</code> in your application's manifest. <p>Android Market
filters the application from users of devices with <em>small</em> and
<em>normal</em> size screens. In effect, this prevents such users from
installing the application.</p></li>
@@ -599,23 +682,24 @@ application must ensure that it declares its UI dimensions using
density-independent pixels (<code>dp</code>) and scales any absolute pixel
values (<code>px</code>) or math by the scaling factor available from {@link
android.util.DisplayMetrics#density android.util.DisplayMetrics.density}. See <a
href="#dips-pels">Converting from dips to pixels</a> for an example.</p>
href="#dips-pels">Converting dp units to pixel units</a> for an example.</p>
<p>Note that the setting of the <code>android:anyDensity</code> attribute does
not affect the platform's pre-scaling of drawable resources, such as bitmaps and
nine-patch images, which always takes place by default. </p>
<p>The following example shows a manifest that declares support for large,
normal, and small screens in any densities.</p>
<p>The following example shows a manifest that declares support for small, normal, large, and
xlarge screens in any density.</p>
<pre>&lt;manifest xmlns:android="http://schemas.android.com/apk/res/android"&gt;
...
&lt;supports-screens
&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:smallScreens="true"
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; android:anyDensity="true" /&gt;
...
<pre>
&lt;manifest xmlns:android="http://schemas.android.com/apk/res/android"&gt;
...
&lt;supports-screens
android:smallScreens="true"
android:normalScreens="true"
android:largeScreens="true"
android:xlargeScreens="true"
android:anyDensity="true" /&gt;
&lt;/manifest&gt;
</pre>
<!-- &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; android:resizeable="true" -->
@@ -624,36 +708,25 @@ normal, and small screens in any densities.</p>
</h4>
<p>The default values for the <code>&lt;supports-screens&gt;</code> attributes
differ, 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>
attribute in the application's manifest, as well as on
the value of <code>android:targetSdkVersion</code>, if declared:</p>
the value of <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code
android:targetSdkVersion}</a>, if declared.</p>
<div>
<ul>
<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 uses
APIs introduced in Android 1.6 or higher, but does not support specific screen
densities and/or screen sizes, you need to explicitly set the appropriate
attributes to "<code>false</code>".
</li>
<li>
If <code>android:minSdkVersion</code> is declared with a value of "3"
(Android 1.5) or lower <em>and</em> a <code>android:targetSdkVersion</code>
attribute is <em>not</em> declared with a value of "4" or higher, the default
value for all attributes except <code>android:normalScreens</code> 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 explicitly
set the appropriate attributes to "<code>true</code>".
</li>
<li>
Note that <code>android:normalScreens</code> always defaults to
<code>true</code>.
</li>
</ul>
</div>
<p>Above, <a href="#table2">table 2</a> indicates the default values for each attribute, based on
the values you provide for the <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code
android:minSdkVersion}</a> and <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code
android:targetSdkVersion}</a>, in the <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code &lt;uses-sdk&gt;}</a>
element.</p>
<p class="note"><strong>Note:</strong> If your application uses APIs introduced in Android 1.6 or
higher, but does not support specific screen densities and/or screen sizes, you need to explicitly
set the appropriate attributes to "<code>false</code>" (because most are "true", by default).</p>
<h3 id="qualifiers">Resource directory qualifiers for screen size and density</h3>
@@ -673,7 +746,7 @@ of Screens Supported</a>, earlier in this document.</p>
</tr>
<tr>
<td rowspan="3">Size</td>
<td rowspan="4">Size</td>
<td><code>small</code></td>
<td>Resources designed for <em>small</em> size screens.</td>
</tr>
@@ -683,11 +756,15 @@ of Screens Supported</a>, earlier in this document.</p>
</tr>
<tr>
<td><code>large</code></td>
<td>Resources for <em>large</em> size screens.</td>
<td>Resources designed for <em>large</em> size screens.</td>
</tr>
<tr>
<td><code>xlarge</code></td>
<td>Resources designed for <em>extra large</em> size screens.</td>
</tr>
<tr>
<td rowspan="4">Density</td>
<td rowspan="5">Density</td>
<td><code>ldpi</code></td>
<td>Resources designed for low-density (<em>ldpi</em>) screens.</td>
</tr>
@@ -700,6 +777,10 @@ of Screens Supported</a>, earlier in this document.</p>
<td>Resources designed for high-density (<em>hdpi</em>) screens.</td>
</tr>
<tr>
<td><code>xhdpi</code></td>
<td>Resources designed for extra high-density (<em>xhdpi</em>) screens.</td>
</tr>
<tr>
<td><code>nodpi</code></td>
<td>Density-independent resources. The platform does not auto-scale resources
tagged with this qualifier, regardless of the current screen's density.</td>
@@ -732,31 +813,34 @@ running on Android 1.5 (API Level 3). </td>
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
T-Mobile G1. On the other hand, a WVGA medium density screen is considered a
<i>large</i> screen &mdash; it offers the same resolution but at lower pixel
density, meaning that it is both physically larger than the baseline screen and
can display significantly more information than a normal screen size.
</p>
<p>Here is an example of the resource directory structure of an application that
supports low and high density, and employs different layout schemes.</p>
employs different layout schemes for different screen sizes and supports low and high density
screens.</p>
<pre>res/layout/my_layout.xml // layout for normal screen size
<pre>
res/layout/my_layout.xml // layout for normal screen size
res/layout-small/my_layout.xml // layout for small screen size
res/layout-large/my_layout.xml // layout for large screen size
res/layout-large-land/my_layout.xml // layout for large screen size in landscape mode
res/layout-xlarge/my_layout.xml // layout for extra large screen size
res/drawable-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-lhdpi/my_icon.png // image for low density
res/drawable-mdpi/dpi/my_icon.png // image for medium density
res/drawable-hdpi/my_icon.png // image for high density
res/drawable-nodpi/composite.xml // density independent resource
</pre>
<p>For more information about how to use resource qualifiers or how the platform
selects them, please read
selects them, please read
<a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">
Alternative Resources</a>.</p>
Providing Alternative Resources</a>.</p>
<h2 id="screen-independence">Best practices for Screen Independence</h2>
@@ -771,10 +855,11 @@ 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
Use {@code wrap_content}, {@code fill_parent}, or the {@code dp} unit (instead of {@code px}),
when specifying dimensions in an XML layout file
</li>
<li>
Avoid AbsoluteLayout
Do not use {@code AbsoluteLayout}
</li>
<li>
Do not use hard coded pixel values in your code
@@ -784,19 +869,19 @@ different screens. Here is a quick checklist:</p>
</li>
</ol>
<h3 id="use-relative">1. Prefer wrap_content, fill_parent and the dip unit to
<h3 id="use-relative">1. Use wrap_content, fill_parent, or the dp unit, instead of
absolute pixels<br> </h3>
<p>When defining the <code>layout_width</code> and <code>layout_height</code> of
views in an XML layout file, using <code>wrap_content</code>,
<code>fill_parent</code> or the <code>dip</code> will guarantee that the view is
<code>fill_parent</code> or the <code>dp</code> will guarantee that the view is
given an appropriate size on the current device screen. For instance, a view
with a <code>layout_width="100dip"</code> will measure 100 pixels wide on an
with a <code>layout_width="100dp"</code> will measure 100 pixels wide on an
HVGA@160 density display and 150 pixels on a WVGA@240 density display, but the
view will occupy approximately the same physical space. </p>
<p>Similarly, you should prefer the <code>sp</code> (scale-independent pixel,
the scale factor depends on a user setting) or <code>dip</code> (if you don't
the scale factor depends on a user setting) or <code>dp</code> (if you don't
want to allow the user to scale the text) to define font sizes.</p>
<h3 id="avoid-absolute">2. Avoid AbsoluteLayout </h3>
@@ -808,7 +893,7 @@ 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
<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>
@@ -822,9 +907,9 @@ 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>
<h4 id="dips-pels">Converting dp units to pixel units</h4>
<p>In some cases, you will need to express dimensions in <code>dip</code> and
<p>In some cases, you will need to express dimensions in <code>dp</code> and
then convert them to pixels. Imagine an application in which a scroll gesture is
recognized after the user's finger has moved by at least 16 pixels. On a
baseline screen, the user will have to move his finger by 16 pixels / 160
@@ -832,26 +917,26 @@ 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>
issue, the gesture threshold must be expressed in the code in <code>dp</code>
and then converted to actual pixels.</p>
<pre>// The gesture threshold expressed in dip
private static final float GESTURE_THRESHOLD_DIP = 16.0f;
<pre>// The gesture threshold expressed in dp
private static final float GESTURE_THRESHOLD_DP = 16.0f;
// Convert the dips to pixels
// Convert the dps to pixels
final float scale = getContext().getResources().getDisplayMetrics().density;
mGestureThreshold = (int) (GESTURE_THRESHOLD_DIP * scale + 0.5f);</span>
mGestureThreshold = (int) (GESTURE_THRESHOLD_DP * scale + 0.5f);</span>
// Use mGestureThreshold as a distance in pixels
</pre>
<p>The {@link android.util.DisplayMetrics#density android.util.DisplayMetrics.density}
<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
convert dps to pixels according to the current screen density. You can access
the current screen's metrics through a <code>Context</code> or
<code>Activity</code>. On a medium (160) density screen,
<code>DisplayMetrics.density</code> equals "1.0", whereas on a high (240)
density screen it equals "1.5". You can refer to the documentation of the
density screen it equals "1.5". You can refer to the documentation of the
{@link android.util.DisplayMetrics DisplayMetrics}
class for details.</p>
@@ -901,7 +986,7 @@ 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
<p>For more information about valid resource qualifiers, see
<a href="#qualifiers">Resource directory qualifiers</a>, earlier in this
document.</p>
@@ -945,7 +1030,7 @@ 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
<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
@@ -953,12 +1038,12 @@ 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>.
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
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>
@@ -973,7 +1058,7 @@ auto-scaled at draw time.</p>
<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>
your application so that it is deployable to:</p>
<ul>
<li>Existing devices, which may be running Android 1.5 (or lower) platform
@@ -982,16 +1067,21 @@ version, as well as to </li>
screen sizes and resolutions</li>
</ul>
<p class="note"><strong>Note:</strong> Even if your application targets Android 1.6 already, you
should follow the same strategies below in order to support <em>xhdpi</em> and <em>xlarge</em>
screens on Android 2.3 (API Level 9), while maintaining compatibility with older versions of
the platform.</p>
<p>To support the newer devices and the different screens they use, you might
need to make some changes in your app, but at the same time your app may be very
stable and so you want to minimize the changes. There are a variety of ways that
you can extend your existing application to support new devices with multiple
screens <em>and</em> existing devices running older platform versions. You
should be able to make these changes to your application such that you can
distribute a single .apk to any and all devices.</p>
distribute a single {@code .apk} to all devices.</p>
<p>The recommended strategy is to develop against the most recent version of the
platform you are targeting, and test on the minimum one you want to run on.
platform you are targeting, and test on the minimum platform version you want to run on.
Here's how to do that:</p>
<ol>
@@ -999,39 +1089,41 @@ Here's how to do that:</p>
<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
<li>Extend compatibility for Android 1.6 (and higher) devices by adding
a new attribute &mdash; <code>android:targetSdkVersion</code> &mdash; to the
<code>uses-sdk</code> element. Set the value of the attribute to
"<code>4</code>". This allows your application to "inherit" the platform's
<code>"4"</code>. [To support <em>xhdpi</em> and <em>xlarge</em> screens, set the value to
<code>"9"</code>.] This allows your application to "inherit" the platform's
multiple screens support, even though it is technically using an earlier version
of the API. </li>
<li>Add an empty <code>&lt;supports-screens&gt;</code> element as a child of
<code>&lt;manifest&gt;</code>. If you need to enable size or density attributes
later, this is where you will add them.</li>
<li>Change your application's build properties, such that it compiles against
the Android 1.6 (API Level 4) library, rather than against the Android 1.5 (or
the Android 1.6 (API Level 4) library [or against Android 2.3 (API Level 9) to support
<em>xhdpi</em> and <em>xlarge</em> screens], rather than against the Android 1.5 (or
earlier) library. You will not be able to compile your application against the
older platform because of the new manifest attribute. </li>
<li>Set up AVDs for testing your application on Android 1.6 and higher
<li>Set up AVDs for testing your application on Android 1.6 [or Android 2.3] and higher
releases. Create AVDs that use the screen sizes and densities that you want to
support. When you create the AVDs, make sure to select the Android 1.6 or higher
support. When you create the AVDs, make sure to select the Android 1.6 [or Android 2.3] or higher
platform as the system image to run. For more information, see <a
href="#testing">How to Test Your Application on Multiple Screens</a>,
below.</li>
<li>Set up AVDs for testing your application on Android 1.5 (or earlier
platform). You need AVDs running the older platforms you are targeting, so that
<li>Set up AVDs for testing your application on older versions of the platform, as low as the
version declared by your <code>android:minSdkVersion</code>. You need AVDs running the older
platforms you are targeting, so that
you can test for compatibility and ensure that there are no functional
regressions. </li>
<li>Compile your application against the Android 1.6 library and run it on the
<li>Compile your application against the Android 1.6 [or Android 2.3] library and run it on the
AVDs you created. Observe the way your application looks and runs, and test all
of the user interactions. </li>
<li>Debug any display or functional issues. For issues that you resolve in
your application code, <span style="color:red">make certain not to use any APIs
introduced 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>
introduced later than the version declared by your <code>android:minSdkVersion</code></span>. If you
are in doubt, refer to SDK reference documentation and look for the API Level specifier for the API
you want to use. Using newer APIs not supported by your minimum version will mean that your
application will no longer be compatible with devices running on that version.</li>
<li>For resource-related issues, you can try resolving them by:
<ul>
<li>Adding a <code>anyDensity="false"</code> attribute to
@@ -1039,22 +1131,22 @@ earlier.</li>
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
qualifiers</a>. Qualifiers must be arranged in a proscribed order. See
<a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">
Alternative Resources</a> for more information. </li>
Providing Alternative Resources</a> for more information. </li>
<li>Note that if you add size- or density-specific resource directories
tagged with any of the resource qualifiers listed in this document, you should
make sure to also tag those directories with the <code>v&lt;api-level&gt;</code>
qualifier (for example, <code>-v4</code>). This ensures that those resources
qualifier (for example, <code>-v4</code> to target API Level 4). This ensures that those resources
will be ignored when the application is run on Android 1.5 or lower platform
versions.</p></li>
</ul>
</li>
<li>If your application does not offer support (such as custom layouts) for
large screens and you want the platform to display your application in
screen-compatibility mode on larger screens, add a
<code>largeScreens="false"</code> attribute to the
<code>&lt;supports-screens&gt;</code> element in the manifest. See
screen-compatibility mode on larger screens, add the
<code>largeScreens="false"</code> and <code>xlargeScreens="false"</code> attributes to the
<code>&lt;supports-screens&gt;</code> element in the manifest. See
<a href="#compatibility-examples">Screen-Compatibility Examples</a> for
illustrations of how the platform displays your application in this case.</li>
<li>If your application does not offer support (such as custom layouts) for
@@ -1077,6 +1169,16 @@ function on a small-screen device. In many cases, the reduced screen area and
density mean that you may need to make tradeoffs in design, content, and
function on those devices. </p>
<p>Also give extra attention to testing your application on an AVD that emulates an <em>xlarge</em>
screen. Devices with extra large screens
are tablet-sized or larger, so you should pay close attention to how usable your application is on
such screens. You might want to design new layouts specifically for extra large screens, to address
usability aspects such as the location and size of buttons in your UI. To test your application on
an extra large screen, create an AVD targeted to Android 2.3 with a high resolution, such as 1280 x
800, and the default density of 160dpi. This AVD will use any resources you've provided with the
<code>xlarge</code> <a href="#qualifiers">resouce qualifier</a>.</p>
<h2 id="testing">How to Test Your Application on Multiple Screens</h2>
<p>Before publishing an application that supports multiple screens, you should
@@ -1091,22 +1193,22 @@ 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 4.</strong>
<div id="f9.5" class="figure" style="width:530px">
<img src="{@docRoot}images/screens_support/avds-config.png" />
<p class="img-caption"><strong>Figure 4.</strong>
A typical set of AVDs for testing screens support.</p>
</div>
<p>As a test environment for your applications, set up a series of AVDs that
emulate the screen sizes and densities you want to support. The Android SDK
includes six emulator skins to get you started. You can use the Android AVD
includes several emulator skins to get you started. You can use the Android AVD
Manager or the <code>android</code> tool to create AVDs that use the various
emulator skins and you can also set up custom AVDs to test densities other than
the defaults. For general information about working with AVDs, see
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
<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>
@@ -1125,7 +1227,7 @@ install in your SDK. The Android 1.6 platform offers these default skins:</p>
</li>
</ul>
<p>The Android 2.0 platform offers all of the Android 1.6 default skins,
<p>The Android 2.0 platform offers all of the Android 1.6 default skins,
above, plus:</p>
<ul>
@@ -1161,15 +1263,15 @@ scale the entire emulator display, based on both the dpi of the skin and of your
monitor. The default emulator skins included in the Android SDK are listed
in <a href="#screens-table">Table 1</a>, earlier in this document.</p>
<div 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 5.</strong>
<div class="figure" style="width:324px">
<img src="{@docRoot}images/screens_support/avd-density.png" >
<p class="img-caption"><strong>Figure 5.</strong>
Resolution and density options that you can use, when creating an AVD using the AVD Manager.</p>
</div>
<p>You should also make sure to test your application on different physical
screen sizes within a single size-density configuration. For example, to
display this screen configuration on a 30" monitor you will need to adjust
screen sizes within a single size-density configuration. For example, to
display this screen configuration on a 30" monitor you will need to adjust
the value passed to <code>-scale</code> to 96*2.8/3.3 = 81dpi. You can also
pass a float value to <code>-scale</code> to specify your own scaling factor:</p>
@@ -1201,7 +1303,7 @@ or "240" for a high-density screen.</li>
<li>Set any other hardware options and complete the AVD creation.</li>
</ol>
<p>In the example above (WVGA medium density), the new AVD will emulate a 5.8"
<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
@@ -1216,21 +1318,21 @@ to the emulator command line when starting the AVD. For example, </p>
<p>This section provides examples of how the Android platform displays an
application written for the baseline screen configuration &mdash; HVGA (320x480)
resolution on a 3.2" screen &mdash; with all of the platform's size- and
density-compatibility features enabled. That is, the examples show how
the platform displays an application that doesn't provide built-in support
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
<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,
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
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>
@@ -1248,9 +1350,9 @@ density is low density (160 -&gt; 120 virtual dpi).
</li>
<li>
If the device's screen size is <em>small</em>, there are few options
options for making Android 1.5 applications work well on such a screen, so
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.
screens from the device.
</li>
<li>
If the device's screen size is <em>large</em>, it limits the application's

10
docs/html/guide/topics/resources/providing-resources.jd
View File

@@ -329,7 +329,8 @@ indicates the current locale.</p>
<td>
<code>small</code><br/>
<code>normal</code><br/>
<code>large</code>
<code>large</code><br/>
<code>xlarge</code>
</td>
<td>
<ul class="nolist">
@@ -347,6 +348,10 @@ indicates the current locale.</p>
medium-density VGA screen. Such a screen has significantly more
available space in both width and height than an HVGA display.
Examples are VGA and WVGA medium density screens.</li>
<li>{@code xlarge}: Screens that are considerably larger than the traditional
medium-density HVGA screen. In most cases, devices with extra large screens would be too
large to carry in a pocket and would most likely be tablet-style devices. <em>Added in API Level
9.</em></li>
</ul>
<p><em>Added in API Level 4.</em></p>
<p>See <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple
@@ -437,6 +442,7 @@ application during runtime.</p>
<code>ldpi</code><br/>
<code>mdpi</code><br/>
<code>hdpi</code><br/>
<code>xhdpi</code><br/>
<code>nodpi</code>
</td>
<td>
@@ -445,6 +451,8 @@ application during runtime.</p>
<li>{@code mdpi}: Medium-density (on traditional HVGA) screens; approximately
160dpi.</li>
<li>{@code hdpi}: High-density screens; approximately 240dpi.</li>
<li>{@code xhdpi}: Extra high-density screens; approximately 320dpi. <em>Added in API
Level 8</em></li>
<li>{@code nodpi}: This can be used for bitmap resources that you do not want to be scaled
to match the device density.</li>
</ul>

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

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 8.3 KiB

After

Width:  |  Height:  |  Size: 21 KiB