| page.title=Supporting Multiple Screens |
| |
| @jd:body |
| |
| <div id="qv-wrapper"> |
| <div id="qv"> |
| |
| <h2>Quickview</h2> |
| <ul> |
| <li>Android runs on devices that have different screen sizes and resolutions.</li> |
| <li>The screen on which your application is displayed can affect its user interface.</li> |
| <li>The platform handles most of the work of adapting your app to the current screen.</li> |
| <li>You can create screen-specific resources for precise control of your UI, if needed. </li> |
| <li>Older applications run in a compatibility mode that provides best-effort rendering on the current screen.</li> |
| <li>It's important to follow the best practices described in this document and test your application in all supported screens. </li> |
| </ul> |
| |
| <h2>In this document</h2> |
| <ol> |
| <li><a href="#overview">Overview of Screen Support</a></li> |
| <ol> |
| <li><a href="#range">Range of screens supported</a></li> |
| <li><a href="#support">How Android supports multiple screens</a></li> |
| <li><a href="#density-independence">Density independence</a></li> |
| <li><a href="#attrs">Manifest attributes</a></li> |
| <li><a href="#qualifiers">Resource qualifiers</a></li> |
| </ol> |
| <li style="padding-top:4px;"><a href="#screen-independence">Best Practices for Screen Independence</a></li> |
| <li><a href="#strategies">Strategies for Legacy Apps</a></li> |
| <li><a href="#testing">How to Test Your App</a></li> |
| |
| </ol> |
| |
| <h2>See Also</h2> |
| <ol> |
| <li><code><a href="{@docRoot}guide/topics/manifest/supports-screens-element.html"><supports-screens></a></code></li> |
| <li><code><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></a></code></li> |
| <li><a |
| href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources"> |
| Providing Alternative Resources</a></li> |
| <li><a href="{@docRoot}guide/developing/devices/index.html">Creating and Managing Virtual Devices</a></li> |
| </ol> |
| |
| </div> |
| </div> |
| |
| <p>Android is designed to run on a variety of devices that offer a range of |
| screen sizes and resolutions. For applications, the platform provides a |
| consistent environment across devices and handles much of the complexity of |
| adapting an application's UI to the screen on which it is being displayed. At |
| the same time, the platform exposes APIs that give application developers |
| precise control over their application's UI when displayed on specific screen |
| sizes and resolutions. </p> |
| |
| <p>This document explains the screens-support features provided by the platform |
| and how you use them in your application. By following the practices described |
| here, you can easily create an application that displays properly on all |
| supported device screens and that you can deploy to any device as a single {@code .apk}. |
| </p> |
| |
| <p>If you have already developed and published an application for Android 1.5 or |
| earlier, you should read this document and consider how you may need to adapt |
| your application for proper display on new devices that offer different screens |
| and that are running Android 1.6 or later. In most cases, only minor adjustments |
| are needed, however you should make sure to <a href="#testing">test your |
| application</a> on all supported screens. </p> |
| |
| <p>Starting in Android 2.2, the platform includes support for extra high density screens |
| (<em>xhdpi</em>), and starting in Android 2.3, the platform includes support for extra large screens |
| (<em>xlarge</em>). If you've already followed the guidance in this document to support all other |
| screen types, you should consider providing additional support for <em>xhdpi</em> and |
| <em>xlarge</em> screens.</p> |
| |
| <p>In particular, if you have an existing application that you would like to |
| make available on small screens (such as QVGA) or for which you would like to provide better support |
| for extra large screens, please see <a href="#strategies">Strategies for Legacy Applications</a> for |
| more information about how to do that. </p> |
| |
| |
| <h2 id="overview">Overview of Screens Support</h2> |
| |
| <p>The sections below provide an overview of the Android platform's support for |
| multiple screens, including an introduction to terms and concepts used in this |
| document and in the API, a summary of the screen configurations that the |
| platform supports, and an overview of the API and underlying |
| screen-compatibility features.</p> |
| |
| |
| <h3>Terms and Concepts</h3> |
| |
| <dl> |
| <dt><em>Screen size</em></dt> |
| <dd>Actual physical size, measured as the screen's diagonal. |
| |
| <p>For simplicity, Android collapses all actual screen sizes into four |
| generalized sizes: small, normal, large, and extra large. Applications can provide custom |
| layouts for each of these four sizes — the platform transparently handles |
| the rendering of the layouts at the actual screen size.</p></dd> |
| |
| <dt><em>Aspect ratio</em></dt> |
| <dd>The porportional relationship of the screen's physical width to its |
| height. Applications can provide layout resources for specific aspect ratios by |
| using the resource qualifiers <code>long</code> and <code>notlong</code>. </dd> |
| |
| <dt><em>Resolution</em></dt> |
| <dd>The total number of physical pixels on a screen. Note that, although |
| resolution is often expressed as <em>width</em> x <em>height</em>, resolution |
| does not imply a specific aspect ratio. In Android, applications do not work |
| directly with resolution.</dd> |
| |
| <dt><em>Density</em></dt> |
| <dd>Based on the screen resolution, the spread of pixels across the physical |
| width and height of the screen. |
| |
| <p>A screen with lower density has fewer available pixels spread across the |
| screen width and height, where a screen with higher density has more — |
| sometimes significantly more — pixels spread across the same area. The |
| density of a screen is important because, other things being equal, a UI element |
| (such as a button) whose height and width are defined in terms of screen pixels |
| will appear larger on the lower density screen and smaller on the higher density |
| screen.</p> |
| |
| <p>For simplicity, Android collapses all actual screen densities into four |
| generalized densities: low, medium, large, and extra large. Applications can provide custom |
| resources for each of these densities — the platform handles any necessary |
| scaling of the resources up or down to meet the specific screen density. </p></dd> |
| <dt><em>Density-independent pixel (dp)</em></dt> |
| <dd>A virtual pixel unit that applications can use in defining their UI, to |
| express layout dimensions or position in a density-independent way. |
| <p>The density-independent pixel is equivalent to one physical pixel on a 160 |
| dpi screen, the baseline density assumed by the platform (as described later in |
| this document). At run time, the platform transparently handles any scaling of |
| the dp units needed, based on the actual density of the screen in use. The |
| conversion of dp units to screen pixels is simple: <nobr><code>pixels = dps * |
| (density / 160)</code></nobr>. For example, on 240 dpi screen, 1 dp would equal 1.5 |
| physical pixels. Using dp units to define your application's UI is highly |
| recommended, as a way of ensuring proper display of your UI on different |
| screens. </p></dd> |
| </dl> |
| |
| |
| <h3 id="range">Range of screens supported</h3> |
| |
| <p>Starting from Android 1.6, the platform provides support for multiple screen |
| sizes and resolutions, reflecting the many new types and sizes of devices on |
| which the platform runs. If you are developing an application that will run |
| on Android 1.6 or later, you can use the compatibility features of the Android |
| platform to ensure that your application UI renders properly across the range of |
| supported screen sizes and resolutions.</p> |
| |
| <p>To simplify the way that developers design their user interfaces for |
| multiple devices and to allow more devices to participate without affecting |
| applications, the platform divides the range of actual supported screen sizes |
| and resolutions into:</p> |
| |
| <ul> |
| <li>A set of four generalized sizes: <em>small</em>, <em>normal</em>, <em>large</em>, |
| and <em>xlarge</em></em> |
| <li>A set of four generalized densities: <em>ldpi</em> (low), <em>mdpi</em> (medium), |
| <em>hdpi</em> (high), and <em>xhdpi</em> (extra high) |
| </ul> |
| |
| <p class="note"><strong>Note:</strong> The <code>xhdpi</code> density category was added in |
| Android 2.2 (API Level 8). The <em>xlarge</em> size category was added in Android 2.3 (API Level |
| 9).</p> |
| |
| <p>Applications can provide custom resources (primarily layouts) for any of the |
| four generalized sizes and can provide resources (primarily drawables such as |
| images) for any of the four generalized densities. Applications do not need to |
| work with the actual physical size or density of the device screen. At run time, |
| the platform handles the loading of the correct size or density resources, based |
| on the generalized size or density of the current device screen, and adapts them |
| to the actual pixel map of the screen.</p> |
| |
| <p>The generalized size/density configurations are arranged around a |
| baseline configuration that is assigned a size of <em>normal</em> and a density of |
| <em>mdpi</em> (medium). All applications written for Android 1.5 or earlier are (by |
| definition) designed for the baseline HVGA screen used on the T-Mobile G1 and |
| similar devices, which is size <em>normal</em> and density |
| <em>mdpi</em>.</p> |
| |
| <p>Each generalized screen configuration spans a range of actual screen |
| densities and physical sizes. For example, that means that multiple devices that |
| report a screen size of <em>normal</em> might offer screens that differ slightly |
| in actual size or aspect ratio. Similarly, devices that report a screen density |
| of <em>hdpi</em> might offer screens with slightly different pixel densities. |
| The platform makes these differences abstract, however — applications can |
| offer UI designed for the generalized sizes and densities and let the system |
| handle the actual rendering of the UI on the current device screen according to |
| its characteristics. </p> |
| |
| |
| <img src="{@docRoot}images/screens_support/screens-ranges.png" /> |
| <p class="img-caption"><strong>Figure 1.</strong> |
| Illustration of how the Android platform maps actual screen densities and sizes |
| to generalized density and size configurations. </p> |
| |
| <p>Although the platform lets your application provide customized resources for |
| the various size and density configurations, you do not need to do write |
| custom code or provide custom resources for every combination of screen size and density. |
| The platform provides robust compatibility features, described |
| in the sections below, that can handle most of the work of rendering your |
| application on any device screen, provided that you've implemented your |
| application UI properly. For more information about how to implement a UI that |
| renders properly across device screens and platform versions, see |
| <a href="#screen-independence">Best Practices for Screen Independence</a>.</p> |
| |
| <p>To help you test your applications, the Android SDK includes emulator skins |
| that replicate the sizes and densities of actual device screens on which your |
| application is likely to run. You can also modify the default size and density |
| of the emulator skins to replicate the characteristics of any specific |
| screen.</p> |
| |
| <p class="table-caption" id="screens-table"><strong>Table 1.</strong> Screen |
| sizes and densities of emulator skins included in the Android SDK.</p> |
| |
| <table> |
| <tbody> |
| <tr> |
| <td style="border:none"></td> |
| <td style="background-color:#f3f3f3"> |
| <nobr>Low density (120), <em>ldpi</em></nobr> |
| </td> |
| <td style="background-color:#f3f3f3"> |
| <nobr>Medium density (160), <em>mdpi</em></nobr> |
| </td> |
| <td style="background-color:#f3f3f3"> |
| <nobr>High density (240), <em>hdpi</em><nobr> |
| </td> |
| <td style="background-color:#f3f3f3"> |
| <nobr>Extra high density (320), <em>xhdpi</em><nobr> |
| </td> |
| </tr> |
| <tr> |
| <td style="background-color:#f3f3f3"> |
| <em>Small</em> screen |
| </td> |
| <td style="font-size:.9em;">QVGA (240x320)</td> |
| </td> |
| <td></td> |
| <td></td> |
| <td></td> |
| </tr> |
| <tr> |
| <td style="background-color:#f3f3f3"> |
| <em>Normal</em> screen |
| </td> |
| <td style="font-size:.9em;">WQVGA400 (240x400)<br>WQVGA432 (240x432)</td> |
| <td style="font-size:.9em;">HVGA (320x480)</td> |
| <td style="font-size:.9em;">WVGA800 (480x800)<br>WVGA854 (480x854)</td> |
| <td style="font-size:.9em;"></td> |
| </tr> |
| <tr> |
| <td style="background-color:#f3f3f3"> |
| <em>Large</em> screen |
| </td> |
| <td></td> |
| <td style="font-size:.9em;">WVGA800* (480x800)<br>WVGA854* (480x854)</td> |
| <td></td> |
| <td></td> |
| </tr> |
| <tr> |
| <td style="background-color:#f3f3f3"> |
| <em>Extra Large</em> screen |
| </td> |
| <td></td> |
| <td></td> |
| <td></td> |
| <td></td> |
| </tr> |
| <tr> |
| <td colspan="4" style="border:none;font-size:90%;">* To emulate this |
| configuration, specify a custom density of 160 when |
| creating an AVD that uses a WVGA800 or WVGA854 skin. |
| </td> |
| </tr> |
| </table> |
| |
| <p>For an overview of the relative numbers of high (hdpi), medium (mdpi), and |
| low (ldpi) density screens in Android-powered devices available now, see the <a |
| href="{@docRoot}resources/dashboard/screens.html">Screen Sizes and Densities</a> dashboard.</p> |
| |
| |
| <h3 id="support">How Android supports multiple screens</h3> |
| |
| <div class="sidebox-wrapper"> |
| <div class="sidebox"> |
| <h2>Using the alternative resources framework</h2> |
| |
| <p>The platform's support for loading screen size- and density-specific |
| resources at run time is based on the alternative resources framework. |
| |
| <p> If you want to use size- or density-specific layouts or drawables in your |
| application and you are not familiar with resource qualifiers or how the |
| platform uses them, please read |
| <a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources"> |
| Providing Alternative Resources</a>. |
| </div> |
| </div> |
| |
| <p>The foundation of Android's support for multiple screens is a set of built-in |
| compatibility features that together manage the rendering of application |
| resources in an appropriate way for the current device screen. The platform |
| handles most of the work of rendering your application, but also gives you two |
| key ways to control how your application is displayed, if you need or want |
| to use them:</p> |
| |
| <ul> |
| <li>The platform supports a set of resource qualifiers that let you provide |
| size- and density-specific resources, if needed. The qualifiers for |
| size-specific resources are <code>small</code>, <code>normal</code>, <code>large</code>, and |
| <code>xlarge</code>. Those for density-specific resources are <code>ldpi</code> |
| (low), <code>mdpi</code> (medium), <code>hdpi</code> (high), and <code>xhdpi</code> (extra high). |
| The qualifiers correspond to the generalized densities described in |
| <a href="#range">Range of screens supported</a>, above.</li> |
| <li>The platform also provides a |
| <a href="{@docRoot}guide/topics/manifest/supports-screens-element.html"> |
| <code><supports-screens></code></a> |
| manifest element, whose attributes |
| <code>android:smallScreens</code>, <code>android:normalScreens</code>, |
| <code>android:largeScreens</code>, and <code>android:xlargeScreens</code> let you specify what |
| generalized screen sizes |
| your application supports. Another attribute, <code>android:anyDensity</code>, |
| lets you indicate whether or not your application includes built-in support for |
| multiple densities.</li> |
| </ul> |
| |
| <p>At run time, the platform provides three types of support to your |
| application, to ensure the best possible display on the current device |
| screen:</p> |
| |
| <ol> |
| <li><em>Pre-scaling of resources (such as image assets)</em> |
| |
| <p>Based on the density of the current screen, the platform automatically |
| loads any size- or density-specific resources from your application and displays |
| them without scaling. If no matching resources are available, the platform loads |
| the default resources and scales them up or down as needed to match the current |
| screen's generalized density. The platform assumes that default resources are |
| designed for proper display at the baseline screen density of "medium" (160), |
| unless they are loaded from a density-specific resource directory.</p> |
| |
| <p>For example, if the current screen's density is "high", the platform loads |
| resources that are tagged with the qualifier <code>hdpi</code> and uses them |
| without scaling. If no such resources are available, the platform uses the |
| default resources instead, scaling them from the baseline density ("medium") to |
| "high". </p> |
| |
| <p>For more information about how to create size- and density-specific |
| resources, see <a href="#qualifiers">Resource qualifiers</a>.</p></li> |
| |
| <li><em>Auto-scaling of pixel dimensions and coordinates</em> |
| |
| <p>If the application states that it does not support different screen |
| densities, the platform auto-scales any absolute pixel coordinates, pixel |
| dimension values, and pixel math used in the application (such as might be used |
| for specifying the width or padding for a view). It does this to ensure that |
| pixel-defined screen elements are displayed at approximately the same physical |
| size as they would be at the baseline density of "medium" (160). The platform |
| handles this scaling transparently to the application and also reports scaled |
| overall pixel dimensions to the application, rather than physical pixel |
| dimensions. </p> |
| |
| <p>For instance, suppose a given device is using a WVGA high-denisty screen, |
| which is 480x800 and about the same size as a traditional HVGA screen, but it's |
| running an app that states that it does not support multiple densities. In this |
| case, the system will "lie" to the application when it queries for screen |
| dimensions, and report 320x533. Then, when the app does drawing operations, such |
| as invalidating the rectangle from (10,10) to (100, 100), the system will |
| likewise automatically transform the coordinates by scaling them the appropriate |
| amount, and actually invalidate the region (15,15) to (150, 150). The same |
| thing happens in the other direction, if the application is running on a |
| lower-density screen, coordinates are scaled down.<p> |
| |
| <p>For more information, see the <code>android:anyDensity</code> attribute in |
| <a href="#attrs">Manifest attributes for screens support</a>.</p></li> |
| |
| <div class="sidebox-wrapper" xstyle="margin-bottom:2em;margin-top:.5em;width:90%;"> |
| <img id="rule" src="{@docRoot}assets/images/grad-rule-qv.png"> |
| <div id="qv-sub-rule"> |
| <img src="{@docRoot}assets/images/icon_market.jpg" style="float:left;margin:0;padding:0;"> |
| <p style="color:#669999;">Publishing to Small Screen Devices</p> |
| <p>To ensure the best experience for users on small-screen devices, Android |
| Market only shows applications that explicitly declare support for small |
| screens. If you developed an application on Android 1.5 or earlier and published |
| it on Android Market, you need to <a href="#testing">test your application</a> |
| on small screens and then upload an updated version that explicitly |
| <a href="#attrs">indicates support for small screens</a>. </p> |
| </div> |
| </div> |
| |
| <li><em>Compatibility-mode display on larger screen-sizes</em> |
| |
| <p>If the current screen's size is larger than your application supports, as |
| specified in the <code>supports-screens</code> element, the platform displays |
| the application at the baseline size ("normal") and density ("medium). For |
| screens larger than baseline, the platform displays the application in a |
| baseline-sized portion of the overall screen, against a black background. </p> |
| |
| <p>For instance, suppose a given device is using a WVGA medium density screen, |
| classified as a "large" screen, but the application states that it does not |
| support large screens; in this case, the system will again "lie" to the |
| application when it queries for screen dimensions, and report 320x480. Instead |
| of scaling the application, however, the application's 320x480 interface will be |
| placed as a "postage stamp" in the larger 480x800 screen.</p> |
| |
| <p>For more information, see the <code>android:anyDensity</code> attribute in |
| <a href="#attrs">Manifest elements for screens support</a> and the |
| <a href="#compatibility-examples">Screen-Compatibility Examples</a> |
| section.</p></li> |
| </ol> |
| |
| <p>In general, these compatibility features ensure that all applications, |
| including those written against Android 1.5 and earlier platform versions, can |
| display properly on most devices, especially when the device's screen is at the |
| baseline "normal" size or larger. </p> |
| |
| <p>However, note that applications written for the baseline screen may need |
| minor adjustments before they display properly on smaller screens such as QVGA. |
| With the reduced screen area of small screens, there may be tradeoffs in design, |
| content, and function that you, as the application developer, need to consider. |
| For more information about how to prepare an existing application for display on |
| small screens, see <a href="#strategies">Strategies for Legacy |
| Applications</a>.</p> |
| |
| <p>The sections below provide more information how to take advantage of the |
| platform's multiple-screens support. </p> |
| |
| |
| <h3 id="density-independence">Density independence</h3> |
| |
| <p>The goal of density independence is to preserve the physical size, from the |
| user's point of view, of user interface elements declared in an application, |
| when the application is displayed on screens with different densities. Density |
| independence applies to both layouts and drawables such as icons. Maintaining |
| density-independence is important because, other things being equal, a UI |
| element (such as a button) whose height and width are defined in terms of screen |
| pixels will appear physically larger on the lower density screen and smaller on |
| the higher density screen. Such density-related size changes can cause problems |
| in application layout, usability, and consistency with other applications |
| installed on the device.</p> |
| |
| <p>The platform provides density independence to applications by default. It |
| does this in three ways: </p> |
| |
| <ul> |
| <li>Through pre-scaling of drawable resources (scaled at resource loading |
| time)</li> |
| <li>Through auto-scaling of density-independent pixel (dp) values used in |
| layouts</li> |
| <li>Through auto-scaling of absolute pixel values used in the application (only |
| needed if the application has set <code>android:anyDensity="false"</code> in its |
| manifest)</li> |
| </ul> |
| |
| <p>The example screens below illustrate the density independence provided by the |
| platform. Note that both the layouts and launcher icons are displayed at the |
| same physical sizes, although screen sizes, aspect ratios, and densities are |
| different.</p> |
| |
| |
| <div id=vi09 style=TEXT-ALIGN:left> |
| <img src="{@docRoot}images/screens_support/dip.png" style="padding-bottom:0;margin-bottom:0;" /> |
| <p class="caption" style="margin:0 0 1.5em 1em;padding:0 0 0 |
| 1em;"><strong>Figure 2.</strong> Examples of density independence on WVGA high |
| density (left), HVGA medium density (center), and QVGA low density (right). </p> |
| </div> |
| |
| <p>In most cases, you can take advantage of density independence in your |
| application simply by making sure that your layouts specify all dimension values |
| in density-independent pixels (<code>dp</code> or <code>dp</code>) or |
| scale-independent pixels (<code>sip</code> or <code>sp</code>, for text only). |
| If you are using absolute pixel values in the application and manifest includes |
| <a href="#attrs"><code>android:anyDensity="true"</code></a>, you will also need |
| to scale the pixel values. See <a href="#dips-pels">Converting dp units to |
| pixel units</a> for more information. </p> |
| |
| |
| <h3 id="attrs">Manifest attributes for screens support</h3> |
| |
| <p> Android 1.6 introduced a new manifest element, |
| <a href="{@docRoot}guide/topics/manifest/supports-screens-element.html"><code><supports-screens></code></a>, |
| whose attributes you can use to control the |
| display of your application on different classes of device screens, as listed |
| in table 2. The <code>smallScreens</code>, <code>normalScreens</code>, <code>largeScreens</code> and |
| <code>xlargeScreens</code> attributes correspond to the generalized screen sizes |
| described in <a href="#range">Range of screens supported</a>, earlier in this |
| document. Notice that the default values for each attribute vary, depending |
| on your minimum and targeted platform, as indicated in the <a |
| href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code |
| android:minSdkVersion}</a> and <a |
| href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code |
| android:targetSdkVersion}</a> attributes of your <a |
| href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code <uses-sdk>}</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 |
| <supports-screens>}</a> manifest element, including default values based on platform |
| version.</p> |
| <table id="vrr8"> |
| <tr> |
| <th> |
| Attribute |
| </th> |
| <th > |
| Description |
| </th> |
| <th> |
| Default value, when<br><nobr><code>minSdkVersion</code> or</nobr> |
| <code>targetSdkVersion</code> is 4 or lower |
| </th> |
| <th> |
| Default value, when<br><nobr><code>minSdkVersion</code> or</nobr> |
| <code>targetSdkVersion</code> is 5 or higher |
| </th> |
| </tr> |
| <tr> |
| <td> |
| <code>android:smallScreens</code> |
| </td> |
| <td> |
| Whether or not the application UI is designed for use on |
| <em>small</em> screens — "<code>true</code>" if it is, and |
| "<code>false</code>" if not. </p> |
| </td> |
| <td>"<code>false</code>"</td> |
| <td>"<code>true</code>"</td> |
| </tr> |
| <tr> |
| <td> |
| <code>android:normalScreens</code> |
| </td> |
| <td> |
| Whether or not the application UI is designed for use on |
| <em>normal</em> screens — "<code>true</code>" if it is, and |
| "<code>false</code>" if not. The default value is always "<code>true</code>". |
| </td> |
| <td>"<code>true</code>"</td> |
| <td>"<code>true</code>"</td> |
| </tr> |
| <tr> |
| <td> |
| <code>android:largeScreens</code> |
| </td> |
| <td> |
| Whether or not the application UI is designed for use on |
| <em>large</em> screens — "<code>true</code>" if it is, and |
| "<code>false</code>" if not. |
| </td> |
| <td>"<code>false</code>"</td> |
| <td>"<code>true</code>"</td> |
| </tr> |
| <tr> |
| <td> |
| <code>android:anyDensity</code> |
| </td> |
| <td> |
| <p>Whether or not the application is designed to manage its UI properly |
| in different density environments — "<code>true</code>" if so, and |
| "<code>false</code>" if not. </p> |
| <ul> |
| <li>If set to "<code>true</code>", the platform disables its |
| density-compatibility features for all screen densities — specifically, |
| the auto-scaling of absolute pixel units (<code>px</code>) and math — and |
| relies on the application to use density-independent pixel units |
| (<code>dp</code>) and/or math to manage the adaptation of pixel values according |
| to density of the current screen. That is, as long as your application uses |
| density-independent units (dp) for screen layout sizes, then it will perform |
| properly on different densities when this attribute is set to |
| "<code>true</code>".</li> |
| |
| <li>If set to "<code>false</code>", the platform enables its |
| density-compatibility features for all screen densities. In this case, the |
| platform provides a scaled, virtual screen pixel map to the application, against |
| which it can layout and draw its UI as though against a medium-density screen |
| (160). The platform then transparently auto-scales the application's pixel units |
| and math as needed to match the actual device screen density. </li> |
| </ul> |
| <p>Note that the setting of this attribute affects density-compatibility only. |
| It does not affect size-compatibility features such as display on a virtual |
| baseline screen.</p> |
| </td> |
| <td>"<code>false</code>"</td> |
| <td>"<code>true</code>"</td> |
| </tr> |
| <tr> |
| <td colspan="4"><strong>Note:</strong> Android 2.3 (API Level 9) introduced a new |
| attribute for the <code><supports-screens></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 — "<code>true</code>" if it is, and |
| "<code>false</code>" if not. |
| </td> |
| <td>"<code>false</code>"</td> |
| <td>"<code>true</code>"</td> |
| </tr> |
| </table> |
| |
| <p>In general, when you declare a screen-size attribute |
| (<code>smallScreens</code>, <code>normalScreens</code>, <code>largeScreens</code>, or |
| <code>xlargeScreens</code>) as "<code>true</code>", you are signaling to the |
| platform that your application is designed to render properly on that screen |
| size. As a result, the platform does not apply any size-compatibility features |
| (such as a virtual HVGA display area). If you declare a screen-size attribute as |
| "<code>false</code>", you are signaling that your application is <em>not</em> |
| designed for that screen size. In this case, the platform <em>does</em> apply |
| size-compatibility features, rendering the application in an HVGA baseline |
| display area. If the current screen is larger than <em>normal</em> size, the |
| platform renders the application in a virtual HVGA screen on the larger screen. |
| See <a href="#compatibility-examples">Screen-Compatibility Examples</a> for an |
| illustration of what an application looks like when displayed in a virtual HVGA |
| screen.</p> |
| |
| <p>In other words, setting a <code><supports-screens></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><supports-screens></code> |
| attributes. It uses them to filter the application from devices whose screens |
| are not supported by the application. Specifically, Android Market considers an |
| application compatible with a device if the application supports a screen that |
| is the same or smaller than the current device screen. Android Market filters |
| the application if it disallows the device's screen size and does not support a |
| smaller size. In general, Android does not provide downward size-compatibility |
| features for applications.</p> |
| |
| <p>Here are some examples:</p> |
| |
| <ul> |
| <li>Assume that you declare <code>smallScreens="false" normalScreens="true" |
| largeScreens="false" xlargeScreens="false"</code> in your application's manifest. <p>Although the |
| application is not designed for display on large or extra large screens, the platform can still |
| run it successfully in <a href="#compatibility-examples">screen-compatibility |
| mode</a>. Android Market shows the application to devices with |
| <em>normal</em>, <em>large</em>, and <em>xlarge</em> size screens, but does filter it from |
| <em>small</em> size screens, because the application provides no screen support at |
| <em>small</em> size. Android's <a href="#compatibility-examples">screen-compatibility |
| mode</a> mode does not provide support for screens that are smaller than those the |
| application supports—it only provides support for screens that are larger. Thus, |
| although the application declares "false" for <em>large</em> and <em>xlarge</em> screens, |
| the application still functions, but runs in compatibility mode.</p></li> |
| |
| <li>Assume that you declare <code>smallScreens="false" normalScreens="false" |
| largeScreens="true" xlargeScreens="true"</code> in your application's manifest. <p>Android Market |
| filters the application from users of devices with <em>small</em> and |
| <em>normal</em> size screens. In effect, this prevents such users from |
| installing the application.</p></li> |
| </ul> |
| |
| <p>If you declare the <code>android:anyDensity</code> attribute as |
| "<code>true</code>", you are signaling to the platform that your application is |
| designed to display properly on any screen density. In this case, the |
| application must ensure that it declares its UI dimensions using |
| density-independent pixels (<code>dp</code>) and scales any absolute pixel |
| values (<code>px</code>) or math by the scaling factor available from {@link |
| android.util.DisplayMetrics#density android.util.DisplayMetrics.density}. See <a |
| href="#dips-pels">Converting dp units to pixel units</a> for an example.</p> |
| |
| <p>Note that the setting of the <code>android:anyDensity</code> attribute does |
| not affect the platform's pre-scaling of drawable resources, such as bitmaps and |
| nine-patch images, which always takes place by default. </p> |
| |
| <p>The following example shows a manifest that declares support for small, normal, large, and |
| xlarge screens in any density.</p> |
| |
| <pre> |
| <manifest xmlns:android="http://schemas.android.com/apk/res/android"> |
| <supports-screens |
| android:smallScreens="true" |
| android:normalScreens="true" |
| android:largeScreens="true" |
| android:xlargeScreens="true" |
| android:anyDensity="true" /> |
| ... |
| </manifest> |
| </pre> |
| <!-- android:resizeable="true" --> |
| <h4 id="defaults"> |
| Default values for attributes |
| </h4> |
| |
| <p>The default values for the <code><supports-screens></code> attributes |
| differ, depending on the the value of the |
| <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code>android:minSdkVersion</code></a> |
| attribute in the application's manifest, as well as on |
| the value of <a |
| href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code |
| android:targetSdkVersion}</a>, if declared.</p> |
| |
| <p>Above, <a href="#table2">table 2</a> indicates the default values for each attribute, based on |
| the values you provide for the <a |
| href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code |
| android:minSdkVersion}</a> and <a |
| href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code |
| android:targetSdkVersion}</a>, in the <a |
| href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code <uses-sdk>}</a> |
| element.</p> |
| |
| <p class="note"><strong>Note:</strong> If your application uses APIs introduced in Android 1.6 or |
| higher, but does not support specific screen densities and/or screen sizes, you need to explicitly |
| set the appropriate attributes to "<code>false</code>" (because most are "true", by default).</p> |
| |
| |
| <h3 id="qualifiers">Resource directory qualifiers for screen size and density</h3> |
| |
| <p>Android supports resource directory qualifiers for controlling the selection |
| of resources based on the characteristics of the screen on which your application |
| is running. You can use these qualifiers to provide size- and density-specific |
| resources in your application. For more information about the generalized sizes |
| and densities that correspond to the qualifiers, see <a href="#range">Range |
| of Screens Supported</a>, earlier in this document.</p> |
| |
| <table> |
| <tr> |
| <th>Screen characteristic</th> |
| <th>Qualifier</th> |
| <th>Description</th> |
| </tr> |
| |
| <tr> |
| <td rowspan="4">Size</td> |
| <td><code>small</code></td> |
| <td>Resources designed for <em>small</em> size screens.</td> |
| </tr> |
| <tr> |
| <td><code>normal</code></td> |
| <td>Resources designed for <em>normal</em> size screens.</td> |
| </tr> |
| <tr> |
| <td><code>large</code></td> |
| <td>Resources designed for <em>large</em> size screens.</td> |
| </tr> |
| <tr> |
| <td><code>xlarge</code></td> |
| <td>Resources designed for <em>extra large</em> size screens.</td> |
| </tr> |
| |
| <tr> |
| <td rowspan="5">Density</td> |
| <td><code>ldpi</code></td> |
| <td>Resources designed for low-density (<em>ldpi</em>) screens.</td> |
| </tr> |
| <tr> |
| <td><code>mdpi</code></td> |
| <td>Resources designed for medium-density (<em>mdpi</em>) screens.</td> |
| </tr> |
| <tr> |
| <td><code>hdpi</code></td> |
| <td>Resources designed for high-density (<em>hdpi</em>) screens.</td> |
| </tr> |
| <tr> |
| <td><code>xhdpi</code></td> |
| <td>Resources designed for extra high-density (<em>xhdpi</em>) screens.</td> |
| </tr> |
| <tr> |
| <td><code>nodpi</code></td> |
| <td>Density-independent resources. The platform does not auto-scale resources |
| tagged with this qualifier, regardless of the current screen's density.</td> |
| </tr> |
| |
| <tr> |
| <td rowspan="2">Aspect ratio</td> |
| <td><code>long</code></td> |
| <td>Resources for screens of any size or density that have a significantly |
| taller (in portrait mode) and wider (in landscape mode) aspect ratio than the |
| baseline screen configuration.</td> |
| </tr> |
| <tr> |
| <td><code>notlong</code></td> |
| <td>Resources for use only on screens that have an aspect ratio that is similar |
| to the baseline screen configuration.</td> |
| </tr> |
| <tr> |
| <td>Platform version</td> |
| <td><nobr><code>v<api-level></code></nobr></td> |
| <td>Resources that are for use only on a specific API Level or higher. For |
| example, if your application is designed to run on both Android 1.5 (API Level |
| 3) and Android 1.6 (API Level 4 and higher), you can use the <code>-v4</code> |
| qualifier to tag any resources that should be excluded when your application is |
| running on Android 1.5 (API Level 3). </td> |
| </tr> |
| </table> |
| |
| <p> |
| Note that the density and the screen size are independent parameters and are |
| interpreted by the system individually. For example, WVGA high density is |
| considered a normal screen because its physical size is about the same as one of |
| T-Mobile G1. On the other hand, a WVGA medium density screen is considered a |
| <i>large</i> screen — it offers the same resolution but at lower pixel |
| density, meaning that it is both physically larger than the baseline screen and |
| can display significantly more information than a normal screen size. |
| </p> |
| |
| <p>Here is an example of the resource directory structure of an application that |
| employs different layout schemes for different screen sizes and supports low and high density |
| screens.</p> |
| |
| <pre> |
| res/layout/my_layout.xml // layout for normal screen size |
| res/layout-small/my_layout.xml // layout for small screen size |
| res/layout-large/my_layout.xml // layout for large screen size |
| res/layout-large-land/my_layout.xml // layout for large screen size in landscape mode |
| res/layout-xlarge/my_layout.xml // layout for extra large screen size |
| |
| res/drawable-lhdpi/my_icon.png // image for low density |
| res/drawable-mdpi/dpi/my_icon.png // image for medium density |
| res/drawable-hdpi/my_icon.png // image for high density |
| |
| res/drawable-nodpi/composite.xml // density independent resource |
| </pre> |
| |
| <p>For more information about how to use resource qualifiers or how the platform |
| selects them, please read |
| <a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources"> |
| Providing Alternative Resources</a>.</p> |
| |
| |
| <h2 id="screen-independence">Best practices for Screen Independence</h2> |
| |
| <p>The objective of supporting multiple screens is to create an application that |
| can run properly on any display and function properly on any of the generalized |
| screen configurations supported by the platform. |
| </p> |
| |
| <p>You can easily ensure that your application will display properly on |
| different screens. Here is a quick checklist:</p> |
| |
| <ol> |
| <li> |
| Use {@code wrap_content}, {@code fill_parent}, or the {@code dp} unit (instead of {@code px}), |
| when specifying dimensions in an XML layout file |
| </li> |
| <li> |
| Do not use {@code AbsoluteLayout} |
| </li> |
| <li> |
| Do not use hard coded pixel values in your code |
| </li> |
| <li> |
| Use density and/or resolution specific resources |
| </li> |
| </ol> |
| |
| <h3 id="use-relative">1. Use wrap_content, fill_parent, or the dp unit, instead of |
| absolute pixels<br> </h3> |
| |
| <p>When defining the <code>layout_width</code> and <code>layout_height</code> of |
| views in an XML layout file, using <code>wrap_content</code>, |
| <code>fill_parent</code> or the <code>dp</code> will guarantee that the view is |
| given an appropriate size on the current device screen. For instance, a view |
| with a <code>layout_width="100dp"</code> will measure 100 pixels wide on an |
| HVGA@160 density display and 150 pixels on a WVGA@240 density display, but the |
| view will occupy approximately the same physical space. </p> |
| |
| <p>Similarly, you should prefer the <code>sp</code> (scale-independent pixel, |
| the scale factor depends on a user setting) or <code>dp</code> (if you don't |
| want to allow the user to scale the text) to define font sizes.</p> |
| |
| <h3 id="avoid-absolute">2. Avoid AbsoluteLayout </h3> |
| |
| <p>{@link android.widget.AbsoluteLayout AbsoluteLayout} |
| is one of the layout containers offered by the Android UI toolkit. Unlike the |
| other layouts however, <code>AbsoluteLayout</code> enforces the use of fixed |
| positions which might easily lead to user interfaces that do not work well on |
| different displays. Because of this, <code>AbsoluteLayout</code> was deprecated |
| in Android 1.5 (API Level 3). </p> |
| |
| <p>You can achieve much the same layout by using a |
| {@link android.widget.FrameLayout FrameLayout} instead, and setting |
| <code>layout_margin</code> attributes of the children. This approach is more |
| flexible and will yield better results on different screens.</p> |
| |
| <h3>3. Do not use hard-coded pixel values in your code</h3> |
| |
| <p>For performance reasons and to keep the code simpler, the Android framework |
| API uses pixels as the standard unit for expressing dimension or coordinate |
| values. That means that the dimensions of a View are always expressed in the |
| code in pixels. For instance, if <code>myView.getWidth()</code> returns 10, the |
| view is 10 pixels wide. In some cases, you may need to scale the pixel values |
| that you use in your code. The sections below provide more information. </p> |
| |
| <h4 id="dips-pels">Converting dp units to pixel units</h4> |
| |
| <p>In some cases, you will need to express dimensions in <code>dp</code> and |
| then convert them to pixels. Imagine an application in which a scroll gesture is |
| recognized after the user's finger has moved by at least 16 pixels. On a |
| baseline screen, the user will have to move his finger by 16 pixels / 160 |
| dpi = 1/10th of an inch (or 2.5 mm) before the gesture is recognized. On a |
| device with a high (240) density display, the user will move his finger by only |
| 16 pixels / 240 dpi = 1/15th of an inch (or 1.7 mm.) The distance is much |
| shorter and the application thus appears more sensitive to the user. To fix this |
| issue, the gesture threshold must be expressed in the code in <code>dp</code> |
| and then converted to actual pixels.</p> |
| |
| <pre>// The gesture threshold expressed in dp |
| private static final float GESTURE_THRESHOLD_DP = 16.0f; |
| |
| // Convert the dps to pixels |
| final float scale = getContext().getResources().getDisplayMetrics().density; |
| mGestureThreshold = (int) (GESTURE_THRESHOLD_DP * scale + 0.5f);</span> |
| |
| // Use mGestureThreshold as a distance in pixels |
| </pre> |
| |
| <p>The {@link android.util.DisplayMetrics#density android.util.DisplayMetrics.density} |
| field specifies the the scale factor you must use to |
| convert dps to pixels according to the current screen density. You can access |
| the current screen's metrics through a <code>Context</code> or |
| <code>Activity</code>. On a medium (160) density screen, |
| <code>DisplayMetrics.density</code> equals "1.0", whereas on a high (240) |
| density screen it equals "1.5". You can refer to the documentation of the |
| {@link android.util.DisplayMetrics DisplayMetrics} |
| class for details.</p> |
| |
| <h4>Use pre-scaled configuration values</h4> |
| |
| <p>The {@link android.view.ViewConfiguration ViewConfiguration} class can be |
| used to access the most common distances, speeds, and times used in the Android |
| framework. For instance, the distance in pixels used by the framework as the |
| scroll threshold can be obtained as follows:</p> |
| |
| <pre>ViewConfiguration.get(aContext).getScaledTouchSlop()</pre> |
| |
| <p>Methods starting with the <code>getScaled</code> prefix are guaranteed to return a value in pixels that will display properly regardless of the current screen density.</p> |
| |
| <h3>4. Use density and/or size-specific resources</h3> |
| |
| <div style="float: right;background-color:#fff;margin: 0;padding: 20px 0 20px 20px;"> |
| <img src="{@docRoot}images/screens_support/scale-test.png" style="padding:0;margin:0;"> |
| <p class="caption" style="margin:0;padding:0;"><strong>Figure 3.</strong> Comparison of pre-scaled and auto-scaled bitmaps.</p> |
| </div> |
| |
| <p>Even with the size- and density-compatibility features that the platform |
| provides, you may still want to make adjustments to the UI of your application |
| when it displayed on certain screen sizes or densities. You can do this by |
| providing size- or density-specific resources — assets, layouts, strings, |
| and so on. If you want, you can also take control over the scaling of images |
| assets. The sections below provide more information.</p> |
| |
| <h4 id="resource-dirs">Custom resources and directories</h4> |
| |
| <p>If you need to control exactly how your application will look on various |
| displays, simply adjust your assets and layouts in configuration-specific |
| resources directories. For example, consider an icon that you want to display on |
| medium and high density screens. Simply create your icon at two different sizes |
| (for instance 100x100 for medium density and 150x150 for high density) and put |
| the two variations in the appropriate directories, using the proper |
| qualifiers:</p> |
| |
| <p style="margin-left:2em;"><code>res/drawable-mdpi/icon.png // |
| for medium-density screens</code></p> |
| |
| <p style="margin-left:2em;"><code>res/drawable-hdpi/icon.png // |
| for high-density screens</code></p> |
| |
| <p>If a density qualifier is not defined in a resource directory name, the |
| platform assumes that the resources in that directory are designed for the |
| baseline medium density. It is not recommended that you put density-specific |
| resources such as images in the default directory.</p> |
| |
| <p>For more information about valid resource qualifiers, see |
| <a href="#qualifiers">Resource directory qualifiers</a>, earlier in this |
| document.</p> |
| |
| <h4 id="scaling">Pre-scaling and auto-scaling of bitmaps and nine-patches</h4> |
| |
| <p>When a bitmap or nine-patch image is loaded from the application's resources, |
| the platform attempts to pre-scale it to match the display's density. For |
| instance, if you placed a 100x100 icon in the <code>res/drawable/</code> |
| directory and loaded that icon as a bitmap on a high-density screen, Android |
| would automatically scale up the icon and produce a 150x150 bitmap.</p> |
| |
| <p>This pre-scaling mechanism works independently of the source. For instance, |
| an application targeted for a high-density screen may have bitmaps only in the |
| <code>res/drawable-hdpi/</code> directory. If one of the bitmaps is a 240x240 |
| icon and is loaded on a medium-density screen, the resulting bitmap will measure |
| 160x160.</p> |
| |
| <p>The platform pre-scales resources as needed, whether the application is |
| running with density-compatibility features enabled or not (as specified by the |
| value of <code>android:anyDensity</code>). However, when running with |
| density-compatibility enabled, the platform continues to report the size of |
| pre-scaled bitmaps and other resources as if they were loaded in a |
| medium-density environment. For example, when density-compatibility is enabled, |
| if you load a 76x76 image from the default resources for display on a |
| high-density screen, the platform will pre-scale the image to 114x114 |
| internally. However, the API still reports the size of the image as 76x76. This |
| discrepancy may cause unexpected behavior if your application somehow directly |
| manipulates the scaled bitmap, but this was considered a reasonable trade-off to |
| keep the performance of existing applications as good as possible.</p> |
| |
| <p>This does not apply for the case that an application creates an in-memory |
| bitmap internally and draws something on it, for later display on the screen. |
| The platform auto-scales such bitmaps on the fly, at draw time. Other side |
| effects of such a case might be that fonts drawn in such a bitmap will be scaled |
| at the bitmap level, when the off-screen bitmap is finally rendered to the |
| display, resulting in scaling artifacts.</p> |
| |
| <p>There are situations in which you may not want Android to automatically scale |
| a resource. The easiest way to accomplish this is to put it in a "nodpi" |
| resource directory:</p> |
| |
| <p style="margin-left:2em;"><code>res/drawable-nodpi/icon.png</code></p> |
| |
| <p>You can also take complete control of the scaling mechanism by using the |
| {@link android.graphics.BitmapFactory.Options BitmapFactory.Options} class, |
| which lets you define whether you want the bitmap to be pre-scaled and what the |
| density of the bitmap should be. For instance, if you are loading a bitmap from |
| a web server, you may want to force the bitmap's density to be high density. |
| When pre-scaling is disabled, the resulting bitmap is in auto-scaling mode. The |
| bitmap is associated with a density (that you may or may not have specified |
| through the <code>BitmapFactory.Options</code>) which will be used to scale the |
| bitmap on screen <em>at drawing time</em>. |
| |
| <p>Using auto-scaling instead of pre-scaling is more CPU expensive than |
| pre-scaling but uses less memory. You can refer to the documentation of |
| {@link android.graphics.BitmapFactory BitmapFactory}, |
| {@link android.graphics.Bitmap Bitmap}, and |
| {@link android.graphics.Canvas Canvas} for more |
| information on auto-scaling.</p> |
| |
| <p>Figure 3, at right, demonstrates the results of the pre-scale and auto-scale |
| mechanisms when loading low (120), medium (160) and high (240) density bitmaps |
| on a baseline screen. The differences are subtle, because all of the bitmaps are |
| being scaled to match the current screen density, however the scaled bitmaps |
| have slightly different appearances depending on whether they are pre-scaled or |
| auto-scaled at draw time.</p> |
| |
| <h2 id="strategies">Strategies for Legacy Applications</h2> |
| |
| <p>If you have already developed and published an Android application based on |
| Android 1.5 or earlier platform version, you need to consider how you will adapt |
| your application so that it is deployable to:</p> |
| |
| <ul> |
| <li>Existing devices, which may be running Android 1.5 (or lower) platform |
| version, as well as to </li> |
| <li>Newer devices that are running Android 1.6 (or higher) and offering various |
| screen sizes and resolutions</li> |
| </ul> |
| |
| <p class="note"><strong>Note:</strong> Even if your application targets Android 1.6 already, you |
| should follow the same strategies below in order to support <em>xhdpi</em> and <em>xlarge</em> |
| screens on Android 2.3 (API Level 9), while maintaining compatibility with older versions of |
| the platform.</p> |
| |
| <p>To support the newer devices and the different screens they use, you might |
| need to make some changes in your app, but at the same time your app may be very |
| stable and so you want to minimize the changes. There are a variety of ways that |
| you can extend your existing application to support new devices with multiple |
| screens <em>and</em> existing devices running older platform versions. You |
| should be able to make these changes to your application such that you can |
| distribute a single {@code .apk} to all devices.</p> |
| |
| <p>The recommended strategy is to develop against the most recent version of the |
| platform you are targeting, and test on the minimum platform version you want to run on. |
| Here's how to do that:</p> |
| |
| <ol> |
| <li>Maintain compatibility with existing devices by leaving your application's |
| <code>android:minSdkVersion</code> attribute as it is. You <em>do not</em> need |
| to increment the value of the attribute to support new devices and multiple |
| screens. </li> |
| <li>Extend compatibility for Android 1.6 (and higher) devices by adding |
| a new attribute — <code>android:targetSdkVersion</code> — to the |
| <code>uses-sdk</code> element. Set the value of the attribute to |
| <code>"4"</code>. [To support <em>xhdpi</em> and <em>xlarge</em> screens, set the value to |
| <code>"9"</code>.] This allows your application to "inherit" the platform's |
| multiple screens support, even though it is technically using an earlier version |
| of the API. </li> |
| <li>Add an empty <code><supports-screens></code> element as a child of |
| <code><manifest></code>. If you need to enable size or density attributes |
| later, this is where you will add them.</li> |
| <li>Change your application's build properties, such that it compiles against |
| the Android 1.6 (API Level 4) library [or against Android 2.3 (API Level 9) to support |
| <em>xhdpi</em> and <em>xlarge</em> screens], rather than against the Android 1.5 (or |
| earlier) library. You will not be able to compile your application against the |
| older platform because of the new manifest attribute. </li> |
| <li>Set up AVDs for testing your application on Android 1.6 [or Android 2.3] and higher |
| releases. Create AVDs that use the screen sizes and densities that you want to |
| support. When you create the AVDs, make sure to select the Android 1.6 [or Android 2.3] or higher |
| platform as the system image to run. For more information, see <a |
| href="#testing">How to Test Your Application on Multiple Screens</a>, |
| below.</li> |
| <li>Set up AVDs for testing your application on older versions of the platform, as low as the |
| version declared by your <code>android:minSdkVersion</code>. You need AVDs running the older |
| platforms you are targeting, so that |
| you can test for compatibility and ensure that there are no functional |
| regressions. </li> |
| <li>Compile your application against the Android 1.6 [or Android 2.3] library and run it on the |
| AVDs you created. Observe the way your application looks and runs, and test all |
| of the user interactions. </li> |
| <li>Debug any display or functional issues. For issues that you resolve in |
| your application code, <span style="color:red">make certain not to use any APIs |
| introduced later than the version declared by your <code>android:minSdkVersion</code></span>. If you |
| are in doubt, refer to SDK reference documentation and look for the API Level specifier for the API |
| you want to use. Using newer APIs not supported by your minimum version will mean that your |
| application will no longer be compatible with devices running on that version.</li> |
| <li>For resource-related issues, you can try resolving them by: |
| <ul> |
| <li>Adding a <code>anyDensity="false"</code> attribute to |
| <code><supports-screens></code>, to enable density-compatibility |
| scaling.</li> |
| <li>Creating any size- or density-specific resources you need and placing |
| them in directories tagged with the <a href="#qualifiers">correct |
| qualifiers</a>. Qualifiers must be arranged in a proscribed order. See |
| <a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources"> |
| Providing Alternative Resources</a> for more information. </li> |
| <li>Note that if you add size- or density-specific resource directories |
| tagged with any of the resource qualifiers listed in this document, you should |
| make sure to also tag those directories with the <code>v<api-level></code> |
| qualifier (for example, <code>-v4</code> to target API Level 4). This ensures that those resources |
| will be ignored when the application is run on Android 1.5 or lower platform |
| versions.</p></li> |
| </ul> |
| </li> |
| <li>If your application does not offer support (such as custom layouts) for |
| large screens and you want the platform to display your application in |
| screen-compatibility mode on larger screens, add the |
| <code>largeScreens="false"</code> and <code>xlargeScreens="false"</code> attributes to the |
| <code><supports-screens></code> element in the manifest. See |
| <a href="#compatibility-examples">Screen-Compatibility Examples</a> for |
| illustrations of how the platform displays your application in this case.</li> |
| <li>If your application does not offer support (such as custom layouts) for |
| small screens (such as on a QVGA low-density screen) and you do not want Android |
| Market to offer the application to users of small-screen devices, you |
| <em>must</em> add a <code>smallScreens="false"</code> attribute to the |
| <code><supports-screens></code> element. </li> |
| <li>Continue testing and debugging until your application performs as expected |
| on all of the platforms and screen sizes your application will support.</li> |
| <li>Export, zipalign, and sign your application using the same private key you |
| used when publishing the previous version, then publish the application to users |
| as an update. </li> |
| </ol> |
| |
| <p>In particular, remember to test your application on an AVD that emulates a |
| small-screen device. Devices that offer screens with QVGA resolution at low |
| density are available now. Users of those devices may want to download your |
| application, so you should understand how your application will look and |
| function on a small-screen device. In many cases, the reduced screen area and |
| density mean that you may need to make tradeoffs in design, content, and |
| function on those devices. </p> |
| |
| <p>Also give extra attention to testing your application on an AVD that emulates an <em>xlarge</em> |
| screen. Devices with extra large screens |
| are tablet-sized or larger, so you should pay close attention to how usable your application is on |
| such screens. You might want to design new layouts specifically for extra large screens, to address |
| usability aspects such as the location and size of buttons in your UI. To test your application on |
| an extra large screen, create an AVD targeted to Android 2.3 with a high resolution, such as 1280 x |
| 800, and the default density of 160dpi. This AVD will use any resources you've provided with the |
| <code>xlarge</code> <a href="#qualifiers">resouce qualifier</a>.</p> |
| |
| |
| <h2 id="testing">How to Test Your Application on Multiple Screens</h2> |
| |
| <p>Before publishing an application that supports multiple screens, you should |
| thoroughly test it in all of the targeted screen sizes and densities. You can |
| test how it displays with the platform's compatibility features enabled or with |
| screen-specific UI resources included in your application. The Android SDK |
| includes all the tools you need to test your application on any supported |
| screen.</p> |
| |
| <!-- You can test in any minsdk, and you can test with compatabiltiy code or |
| not. Once you've tested your application and found that it displays properly on |
| various screen sizes, you should make sure to add the corresponding size |
| attribute(s) to your application's manifest. --> |
| |
| <div id="f9.5" class="figure" style="width:530px"> |
| <img src="{@docRoot}images/screens_support/avds-config.png" /> |
| <p class="img-caption"><strong>Figure 4.</strong> |
| A typical set of AVDs for testing screens support.</p> |
| </div> |
| |
| <p>As a test environment for your applications, set up a series of AVDs that |
| emulate the screen sizes and densities you want to support. The Android SDK |
| includes several emulator skins to get you started. You can use the Android AVD |
| Manager or the <code>android</code> tool to create AVDs that use the various |
| emulator skins and you can also set up custom AVDs to test densities other than |
| the defaults. For general information about working with AVDs, see |
| <a href="{@docRoot}guide/developing/devices/index.html">Creating and Managing Virtual |
| Devices</a>.</p> |
| |
| <p>The Android SDK provides a set of default emulator skins that you can use for |
| testing. The skins are included as part of each Android platform that you can |
| install in your SDK. The Android 1.6 platform offers these default skins:</p> |
| |
| <ul> |
| <li> |
| QVGA (240x320, low density, small screen) |
| </li> |
| <li> |
| HVGA (320x480, medium density, normal screen) |
| </li> |
| <li> |
| WVGA800 (480x800, high density, normal screen) |
| </li> |
| <li> |
| WVGA854 (480x854 high density, normal screen) |
| </li> |
| </ul> |
| |
| <p>The Android 2.0 platform offers all of the Android 1.6 default skins, |
| above, plus:</p> |
| |
| <ul> |
| <li> |
| WQVGA400 (240x400, low density, normal screen) |
| </li> |
| <li> |
| WQVGA432 (240x432, low density, normal screen) |
| </li> |
| </ul> |
| |
| <p>If you are using the <code>android</code> tool command line to create your |
| AVDs, here's an example of how to specify the skin you want to use:</p> |
| |
| <pre>android create avd ... --skin WVGA800</pre> |
| |
| <p>We also recommend that you test your application in an emulator that is set |
| up to run at a physical size that closely matches an actual device. This makes |
| it a lot easier to compare the results at various resolutions and densities. To |
| do so you will need to know the approximate density, in dpi, of your computer |
| monitor (a 30" Dell monitor has for instance a density of about 96 dpi.). Use |
| your monitor's dpi as the value of the <code>-scale</code> option, when |
| launching the emulator, for example:</p> |
| |
| <pre>emulator -avd <name> -scale 96dpi</pre> |
| |
| <p>If you are working in Eclipse with ADT, you can specify the <code>-scale |
| 96dpi</code> option in the Target tab of run and debug configurations, under |
| "Additional Emulator Command Line Options" field. </p> |
| |
| <p>Note that starting the emulator with the <code>-scale</code> option will |
| scale the entire emulator display, based on both the dpi of the skin and of your |
| monitor. The default emulator skins included in the Android SDK are listed |
| in <a href="#screens-table">Table 1</a>, earlier in this document.</p> |
| |
| <div class="figure" style="width:324px"> |
| <img src="{@docRoot}images/screens_support/avd-density.png" > |
| <p class="img-caption"><strong>Figure 5.</strong> |
| Resolution and density options that you can use, when creating an AVD using the AVD Manager.</p> |
| </div> |
| |
| <p>You should also make sure to test your application on different physical |
| screen sizes within a single size-density configuration. For example, to |
| display this screen configuration on a 30" monitor you will need to adjust |
| the value passed to <code>-scale</code> to 96*2.8/3.3 = 81dpi. You can also |
| pass a float value to <code>-scale</code> to specify your own scaling factor:</p> |
| |
| <pre>emulator -avd <name> -scale 0.6</pre> |
| |
| <p>If you would like to test your application on a screen that uses a resolution |
| or density not supported by the built-in skins, you can either adjust an |
| existing skin, or create an AVD that uses a custom resolution or density.</p> |
| |
| <p>In the AVD Manager, you can specify a custom skin resolution or density in |
| the Create New AVD dialog, as shown in Figure 5, at right.</p> |
| |
| <p>In the <code>android</code> tool, follow these steps to create an AVD with a |
| custom resolution or density:</p> |
| |
| <ol> |
| <li>Use the <code>create avd</code> command to create a new AVD, specifying |
| the <code>--skin</code> option with a value that references either a default |
| skin name (such as "WVGA800") or a custom skin resolution (such as 240x432). |
| Here's an example: |
| <pre>android create avd -n <name> -t <targetID> --skin WVGA800</pre> |
| </li> |
| <li>To specify a custom density for the skin, answer "yes" when asked whether |
| you want to create a custom hardware profile for the new AVD.</li> |
| <li>Continue through the various profile settings until the tool asks you to |
| specify "Abstracted LCD density" (<em>hw.lcd.density</em>). Enter an appropriate |
| value, such as "120" for a low-density screen, "160" for a medium density screen, |
| or "240" for a high-density screen.</li> |
| <li>Set any other hardware options and complete the AVD creation.</li> |
| </ol> |
| |
| <p>In the example above (WVGA medium density), the new AVD will emulate a 5.8" |
| WVGA screen.</p> |
| |
| <p>As an alternative to adjusting the emulator skin configuration, you can use |
| the emulator skin's default density and add the <code>-dpi-device</code> option |
| to the emulator command line when starting the AVD. For example, </p> |
| |
| <pre>emulator -avd WVGA800 -scale 96dpi -dpi-device 160</pre> |
| |
| |
| <h2 id="compatibility-examples">Screen-Compatibility Examples</h2> |
| |
| <p>This section provides examples of how the Android platform displays an |
| application written for the baseline screen configuration — HVGA (320x480) |
| resolution on a 3.2" screen — with all of the platform's size- and |
| density-compatibility features enabled. That is, the examples show how |
| the platform displays an application that doesn't provide built-in support |
| for the screen on which it is being rendered, but which instead relies completely |
| on the platform.</p> |
| |
| <p>The platform's screen-compatibility features are designed to provide such |
| an application with a virtual baseline screen environment against which to run, |
| while at the same time ensuring for the user a physical display that is |
| approximately the same as the baseline screen size and density. </p> |
| |
| <p>Legacy applications that have not been modified to support multiple |
| screens would be typical examples of such applications. In most cases, |
| you would want to add multiple-screens support to a legacy application and |
| publish an updated version, as described in <a href="#strategies">Strategies |
| for Legacy Applications</a>. However, if you did not do so, the |
| platform still performs best-effort rendering of your application, as |
| illustrated below.</p> |
| |
| <p> Internally, these are the compatibility features that the platform |
| provides, based on the current device screen:</p> |
| |
| <ul> |
| <li> |
| If the device's screen density is <em>not medium</em>, the application's |
| layout and drawing of its content is as if the screen <em>is</em> medium density, but the |
| framework scales the layout and images (if the image for the target density is |
| not available) to fit the target density. It scales 1.5 times if the target |
| density is high density (160->240 virtual dpi), or 0.75 times if the target |
| density is low density (160 -> 120 virtual dpi). |
| </li> |
| <li> |
| If the device's screen size is <em>small</em>, there are few options |
| options for making Android 1.5 applications work well on such a screen, so |
| Android Market will filter applications that are not known to support these |
| screens from the device. |
| </li> |
| <li> |
| If the device's screen size is <em>large</em>, it limits the application's |
| screen to the normal size and draws a black background around the application. |
| For example, if an application supports high density, but does not support large |
| screens, it only uses a 480x720 area of the screen and the rest will be filled |
| with a black background (see example below). |
| </li> |
| </ul> |
| |
| <table style="width:10%;margin-left:.5em;"> |
| <tr> |
| <td> |
| HVGA, normal size, normal density<br> |
| [ emulator -skin HVGA ]<br> |
| <img height=149 src="{@docRoot}images/screens_support/afdvfckr9j_15dcsvrscg_b.png" width=225> |
| </td> |
| <td> |
| WVGA, normal size, high density<br> |
| [emulator -skin WVGA854 -dpi-device 240]<br> |
| <img height=143 src="{@docRoot}images/screens_support/afdvfckr9j_18c6mhm3cm_b.png" width=254><br> |
| <p>The application occupies full screen as its considered to be normal size. (close to 480x720)</p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| VGA, large size, medium density<br> |
| [ emulator -skin 640x480 ]<br> |
| <img height=243 src="{@docRoot}images/screens_support/afdvfckr9j_14fj6dhsc3_b.png" width=324> |
| <p>The application occupies 320x480 of VGA.</p> |
| </td> |
| <td> |
| SVGA, large size, high density<br> |
| [ emulator -skin 800x600 -dpi-device 240]<br> |
| <img height=223 src="{@docRoot}images/screens_support/afdvfckr9j_19c743p6cr_b.png" width=294> |
| <p>The application occupies 480x720 (=1.5 x [320x480]) of 800x600.</p> |
| </td> |
| </tr> |
| </table> |
| |
| |
| <h3>Screen-compatibility limitations on small, low-density screens</h3> |
| |
| <p>Because these device has smaller state/resolution, there are known |
| limitations when application runs in compatibility mode.</p> |
| |
| <h4>QVGA</h4> |
| |
| <p>Because QVGA (240x320) screens have less screen area available and lower |
| density than normal, which is 240x360 in low density, some applications cannot |
| render all their content properly on those screens. As a result, on a QVGA |
| device, Android Market will filter out all applications that do not declare they |
| support small screens.</p> |
| |
| <p>Examples:</p> |
| |
| <table style="width:10%;margin-left:.5em;"> |
| <tr> |
| <td>The part of z value graph is chopped.</td> |
| <td>The lap time area is chopped.<br></td> |
| </tr> |
| <tr> |
| <td><img height=207 src="{@docRoot}images/screens_support/afdvfckr9j_16g95wjqg3_b.png" width="155"></td> |
| <td><img height=186 src="{@docRoot}images/screens_support/afdvfckr9j_17p2w4txgc_b.png" width="139"></td> |
| </tr> |
| </table> |
| |
| |
| <h4>Images with 1 pixel height/width.</h4> |
| |
| <p>If an image has 1 pixel height or width, it may not be shown on the screen |
| due to rounding issue. This is inevitable as it just does not have enough |
| pixels.</p> |
| |
| <p>For example, in the screen below, the divider in the menu is invisible |
| because the width of the image is trancated to 0. (This particular problem is |
| solvable because menu is handled inside framework, but there is no generic |
| solution as it just does not have enough pixels.)</p> |
| |
| <img height=222 src="{@docRoot}images/screens_support/afdvfckr9j_20fvptbbdd_b.png" width=166> |
| |
| |
| |