diff options
| author | Scott Main <smain@google.com> | 2011-05-09 18:32:10 -0700 |
|---|---|---|
| committer | Android (Google) Code Review <android-gerrit@google.com> | 2011-05-09 18:32:10 -0700 |
| commit | 7f3cf449fe1b90b902a37ddc3c05ec7aa236e584 (patch) | |
| tree | a10da04e87911d28edabee0dbf7d35ca1043618f /docs | |
| parent | c3038308a765de2826997b65c175bf752b45bc70 (diff) | |
| parent | 6aa2b625cf7c39271a09222e5adaf62c1bf9c1ea (diff) | |
| download | frameworks_base-7f3cf449fe1b90b902a37ddc3c05ec7aa236e584.zip frameworks_base-7f3cf449fe1b90b902a37ddc3c05ec7aa236e584.tar.gz frameworks_base-7f3cf449fe1b90b902a37ddc3c05ec7aa236e584.tar.bz2 | |
Merge "docs: update screen support doc to de-emphasize support for 1.5 this includes a variety of other revisions to reorganize some of the content in the main document and also add separate documents for how to enable screen filtering and add screen support on 1.5" into honeycomb-mr1
Diffstat (limited to 'docs')
14 files changed, 1129 insertions, 1247 deletions
diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs index 2f7c60c..916da09 100644 --- a/docs/html/guide/guide_toc.cs +++ b/docs/html/guide/guide_toc.cs @@ -653,9 +653,19 @@ <li><a href="<?cs var:toroot ?>guide/practices/compatibility.html"> <span class="en">Compatibility</span> </a></li> - <li><a href="<?cs var:toroot ?>guide/practices/screens_support.html"> - <span class="en">Supporting Multiple Screens</span> + <li class="toggle-list"> + <div><a href="<?cs var:toroot ?>guide/practices/screens_support.html"> + <span class="en">Supporting Multiple Screens</span> + </a></div> + <ul> + <li><a href="<?cs var:toroot ?>guide/practices/screens-distribution.html"> + <span class="en">Distributing to Specific Screens</span> </a></li> + <li><a href="<?cs var:toroot ?>guide/practices/screens-support-1.5.html"> + <span class="en">Strategies for Android 1.5</span> + </a></li> + </ul> + </li> <li><a href="<?cs var:toroot ?>guide/practices/optimizing-for-3.0.html"> <span class="en">Optimizing Apps for Android 3.0</span> </a></li> diff --git a/docs/html/guide/practices/screens-distribution.jd b/docs/html/guide/practices/screens-distribution.jd new file mode 100644 index 0000000..0c5193b --- /dev/null +++ b/docs/html/guide/practices/screens-distribution.jd @@ -0,0 +1,164 @@ +page.title=Distributing to Specific Screens +parent.title=Supporting Multiple Screens +parent.link=screens_support.html + +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + + <h2>Quickview</h2> + <ul> + <li>If necessary, you can control distribution of your application based on the device +screen configuration</li> + </ul> + + <h2>In this document</h2> + <ol> + <li><a href="#FilteringHansetApps">Filtering a Handset Application from Tablets</a></li> + <li><a href="#FilteringTabletApps">Filtering a Tablet Application from Handsets</a></li> + </ol> + + <h2>See also</h2> + <ol> + <li><a +href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a></li> + <li><a +href="{@docRoot}guide/practices/optimizing-for-3.0.html">Optimizing Apps for Android 3.0</a></li> + </ol> + +</div> +</div> + + + +<p>Although we recommend that you design your application to function properly on multiple +configurations of screen size and density, you can instead choose to limit the distribution of your +application to certain types of screens, such as only tablets and other large devices or only +handsets and similar-sized devices. To do so, you can enable filtering by external services such as +Android Market by adding elements to your manifest file that specify the screen configurations your +application supports.</p> + +<p>However, before you decide to restrict your application to certain screen configurations, you +should understand the techniques for <a +href="{@docRoot}guide/practices/screens_support.html">supporting multiple screens</a> and implement +them to the best of your ability. By supporting multiple screens, your application can be made +available to the greatest number of users with different devices, using a single {@code .apk}.</p> + + + +<h2 id="FilteringHandsetApps">Filtering a Handset Application from Tablets</h2> + +<p>Because the system generally scales applications to fit larger screens well, you shouldn't +need to filter your application from larger screens. As long as you follow the <a +href="{@docRoot}guide/practices/screens_support.html#screen-independence">Best Practices for Screen +Independence</a>, your application should work well on larger screens such as tablets. However, you +might discover that your application can't scale up well or perhaps you've decided to publish two +versions of your application for different screen configurations. In such a case, you can use the <a +href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">{@code +<compatible-screens>}</a> element to manage the distribution of your application based on +combinations of screen size and density. External services such as Android Market use this +information to apply filtering to your application, so that only devices that have a screen +configuration with which you declare compatibility can download your application.</p> + +<p>The <a href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">{@code +<compatible-screens>}</a> element must contain one or more {@code <screen>} elements. Each +{@code <screen>} element specifies a screen configuration with which your application is +compatible, using both the {@code android:screenSize} and {@code android:screenDensity} attributes. +Each {@code <screen>} element <strong>must include both attributes</strong> to specify an +individual screen configuration—if either attribute is missing, then the element is invalid +(external services such as Android Market will ignore it).</p> + +<p>For example, if your application is compatible with only small and normal size screens, +regardless of screen density, you must specify eight different {@code <screen>} elements, +because each screen size has four density configurations. You must declare each one of +these; any combination of size and density that you do <em>not</em> specify is considered a screen +configuration with which your application is <em>not</em> compatible. Here's what the manifest +entry looks like if your application is compatible with only small and normal screen sizes:</p> + +<pre> +<manifest ... > + ... + <compatible-screens> + <!-- all small size screens --> + <screen android:screenSize="small" android:screenDensity="ldpi" /> + <screen android:screenSize="small" android:screenDensity="mdpi" /> + <screen android:screenSize="small" android:screenDensity="hdpi" /> + <screen android:screenSize="small" android:screenDensity="xhdpi" /> + <!-- all normal size screens --> + <screen android:screenSize="normal" android:screenDensity="ldpi" /> + <screen android:screenSize="normal" android:screenDensity="mdpi" /> + <screen android:screenSize="normal" android:screenDensity="hdpi" /> + <screen android:screenSize="normal" android:screenDensity="xhdpi" /> + </compatible-screens> + <application ... > + ... + <application> +</manifest> +</pre> + +<p class="note"><strong>Note:</strong> Although you can also use the <a +href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">{@code +<compatible-screens>}</a> element for the reverse scenario (when your application is not +compatible with smaller screens), it's easier if you instead use the <a +href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code +<supports-screens>}</a> as discussed in the next section, because it doesn't require you +to specify each screen density your application supports.</p> + + + +<h2 id="FilteringTabletApps">Filtering a Tablet Application from Handsets</h2> + +<p>If your application's UI is adversely affected when the system scales your application down to +smaller screens, you should add <a +href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">alternative +layouts</a> for smaller screens to adjust the layout for those screens. However, sometimes your +layout still might not fit a smaller screen or you've explicitly designed your application only for +tablets and other large devices. In this case, you can manage the availability of your application +to smaller screens by using the <a +href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code +<supports-screens>}</a> manifest element.</p> + +<p>For example, if you want your application to be available only to large and extra large +screens, you can declare the element in your manifest like this:</p> + +<pre> +<manifest ... > + ... + <supports-screens android:smallScreens="false" + android:normalScreens="false" + android:largeScreens="true" + android:xlargeScreens="true" /> + <application ... > + ... + <application> +</manifest> +</pre> + +<p>External services such as Android Market read this manifest element and use it to ensure that +your application is available only to devices with either a large or an extra large screen.</p> + +<p class="caution"><strong>Caution:</strong> If you use the <a +href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code +<supports-screens>}</a> element for the reverse scenario (when your application is not compatible +with <em>larger</em> screens) and set the larger screen size attributes to {@code "false"}, then +external services such as Android Market <strong>do not</strong> apply filtering. Your application +will still be available to larger screens, but when it runs, it will not resize to fit the screen. +Instead, the system will draw it in a "postage stamp" window that's the same relative size as the +screen size that your application does support (see <a +href="screens-support-1.5.html#CompatMode">compatibility mode</a> for more information). If you want +to prevent your application from being downloaded on larger screens, use <a +href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">{@code +<compatible-screens>}</a>, as discussed in the previous section about <a +href="#FilteringHandsetApps">Filtering a Handset Application from Tablets</a>.</p> + +<p>Remember, you should strive to make your application available to as many devices as possible by +applying all necessary techniques for <a +href="{@docRoot}guide/practices/screens_support.html">supporting multiple screens</a>. You should +use <a href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">{@code +<compatible-screens>}</a> or <a +href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code +<supports-screens>}</a> only when you cannot provide compatibility on all screen configurations +or you have decided to provide different versions of your application for different sets of screen +configurations.</p> + diff --git a/docs/html/guide/practices/screens-support-1.5.jd b/docs/html/guide/practices/screens-support-1.5.jd new file mode 100644 index 0000000..6fd36bb --- /dev/null +++ b/docs/html/guide/practices/screens-support-1.5.jd @@ -0,0 +1,186 @@ +page.title=Strategies for Android 1.5 +parent.title=Supporting Multiple Screens +parent.link=screens_support.html + +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + + <h2>Quickview</h2> + <ul> + <li>Apps developed for Android 1.5 and below support only the baseline screen +configuration, by default</li> + <li>There are some simple steps you should take to enable support for multiple screens in +an application designed for Android 1.5</li> + </ul> + + <h2>In this document</h2> + <ol> + <li><a href="#strategies">Adding Multiple Screens Support</a></li> + <li><a href="#CompatMode">Compatibility Mode</a></li> + </ol> + + <h2>See also</h2> + <ol> + <li><a +href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a></li> + </ol> + +</div> +</div> + + +<p>All applications written for Android 1.5 or earlier, by default, support only the +baseline HVGA screen used on the T-Mobile G1 and similar devices, which is <em>normal</em> screen +size and medium density (<em>mdpi</em>). Android 1.6 introduced support for different screen +configurations and added APIs that allow applications to control how they operate on different +screens, using alternative resources for different screen configurations.</p> + +<p>If your manifest file includes the <a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code <uses-sdk>}</a> element, +with the <a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a> +attribute set to {@code "3"} or lower, and does <em>not</em> include the <a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code +android:targetSdkVersion}</a> set to {@code "4"} or higher, then this document is for you. By +default, an application written for Android 1.5 or below that does not set the <a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code +android:targetSdkVersion}</a> set to {@code "4"} or higher runs in <a +href="#CompatMode">compatibility mode</a> when on a device with a screen larger than the +<em>normal</em> screen size (basically, the system displays the application in a small window +that is roughly the size of the normal screen size).</p> + +<p>This document describes how to get your application out of <a href="#CompatMode">compatibility +mode</a> and instead support multiple screens, but also maintain compatibility with Android 1.5 and +below.</p> + +<p class="note"><strong>Note:</strong> Before you begin, you should first decide whether it's even +necessary to support Android 1.5. To see the relative number of devices that are still running +Android 1.5, see the <a +href="http://developer.android.com/resources/dashboard/platform-versions.html">Platform Versions +Dashboard</a>.</p> + + + + +<h2 id="strategies">Adding Multiple Screens Support</h2> + +<p>If you have already developed and published an Android application based on +Android 1.5 or earlier platform version, and want to maintain compatibility with Android 1.5, you +need to make some changes to your application in order for it to properly run on newer devices with +different screen configurations. 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 your application against Android 1.6 (because it's the +lowest version that includes support for multiple screens) and test your application on each +platform version your application supports (especially the minimum platform, such as Android 1.5). +Here's how to do that:</p> + +<ol> + <li>Maintain compatibility with existing devices by leaving your application's <a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a> +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 +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code +android:targetSdkVersion}</a> to the <a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code <uses-sdk>}</a> element. +Set the value of <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code +android:targetSdkVersion}</a> to <code>"4"</code>. This allows your application to "inherit" the +platform's multiple screens support, even though it is technically using an earlier version of the +API. + <p>Adding this attribute will cause an error in the compiler, because the attribute is unknown to +Android 1.5. You'll fix this next.</p></li> + <li>Change your application's build properties, such that it compiles against the Android 1.6 (API +Level 4) library, rather than against the Android 1.5 (or earlier) library. You must do this in +order for your application to successfully compile when using the new manifest attributes. Older +versions of the platform simply ignore the attributes they don't know, so your application still +runs fine on them, as long as you don't use APIs in your application code from Android 1.6. </li> +</ol> + +<p>Your application is now prepared to run on multiple screens, while maintaining support for +Android 1.5 or lower.</p> + +<p>Here's how you should begin testing your application:</p> + +<ol> + <li>Set up AVDs for testing your application on Android 1.6 and some new versions. Create AVDs +that use the screen sizes and densities that you want to support. When you create the AVDs, make +sure to select the Android 1.6 or higher platform as the system image to use. For more information, +see <a href="{@docRoot}guide/practices/screens_support.html#testing">How to Test Your Application on +Multiple Screens</a>.</li> + <li>Set up AVDs for testing your application on older versions of the platform, as low as the +version declared by your <a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a>. +You need AVDs running the older platforms you are targeting, so that you can ensure there are +no functional regressions.</li> + <li>Compile your application against the Android 1.6 library and run it on the AVDs you created. +Observe the way your application looks and runs, and test all of the user interactions.</li> + <li>Debug any display or functional issues. For issues that you resolve in +your application code, <span style="color:red">make certain not to use any APIs +introduced later than the version declared by your <a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code +android:minSdkVersion}</a></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> +</ol> + +<p>In particular, remember to test your application on an AVD that emulates a small-screen device. +Users of devices with QVGA resolution at low density may want to download your application, so you +should understand how your application will look and function on a small-screen device. In some +cases, the reduced screen area and density mean that you need to make tradeoffs in design 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 3.0 and use the WXGA emulator skin.</p> + +<p>Once you've completed the procedures above, you should follow the recommendations in <a +href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a> to add +complete support for different screen configurations.</p> + + +<h2 id="CompatMode">Compatibility Mode</h2> + +<div class="figure" style="width:450px;margin:0"> +<img src="{@docRoot}images/screens_support/compat-mode-on.png" alt="" /> +<p class="img-caption"><strong>Figure 1.</strong> An application running in compatibility mode +on an extra large screen.</p> +</div> + +<p>To allow applications to run on larger screens without stretching the UI, Android provides a +compatibility mode that draws an application's UI in a "postage stamp" window when on larger +screens. That is, the system displays the application at the baseline size (<em>normal</em>) and +density (<em>mdpi</em>), with a black border that fills the rest of the screen.</p> + +<p>Compatibility mode exists primarily to support application's developed for Android 1.5 (or lower) +when running on larger screens, because multiple screen support was not added until Android 1.6, +older applications were not designed to support different screen configurations.</p> + +<p>As such, if you've set your <a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code +android:minSdkVersion}</a> to {@code "3"} or lower and have <em>not</em> set the <a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code +android:targetSdkVersion}</a> to {@code "4"} or higher, then compatibility mode is enabled and +the system will not scale your application, because your application implicitly declares that it +only supports the baseline screen configuration (normal screen size and medium density).</p> + +<p>To disable compatibility mode, set either <a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code +android:minSdkVersion}</a> or <a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code +android:targetSdkVersion}</a> to {@code "4"} or higher. For more information, see the previous +section about <a href="#strategies">Adding Multiple Screens Support</a>.</p> + +<p>You can also affect whether compatibility mode is enabled by using the <a +href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code +<supports-screens>}</a> element (you can enable it by setting {@code android:resizeable} or +specific screen sizes to {@code "false"}). However, you should not explicitly enable compatibility +mode for your application, but should instead apply the necessary techniques to <a +href="{@docRoot}guide/practices/screens_support.html">supporting multiple screens</a> and allow your +application to properly fit the screen on all screen sizes.</p> diff --git a/docs/html/guide/practices/screens_support.jd b/docs/html/guide/practices/screens_support.jd index 9875a6e..14de152 100644 --- a/docs/html/guide/practices/screens_support.jd +++ b/docs/html/guide/practices/screens_support.jd @@ -1,5 +1,4 @@ page.title=Supporting Multiple Screens - @jd:body <div id="qv-wrapper"> @@ -7,772 +6,359 @@ page.title=Supporting Multiple Screens <h2>Quickview</h2> <ul> - <li>Android runs on devices that have different screen sizes and resolutions.</li> + <li>Android runs on devices that have different screen sizes and densities.</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> + <li>The system handles most of the work of adapting your app to the current screen.</li> + <li>You should create screen-specific resources for precise control of your UI. </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> + <li><a href="#overview">Overview of Screen Support</a> + <ol> + <li><a href="#terms">Terms and concepts</a></li> + <li><a href="#range">Range of screens supported</a></li> + <li><a href="#density-independence">Density independence</a></li> + </ol></li> + <li><a href="#support">How to Support Multiple Screens</a> + <ol> + <li><a href="#qualifiers">Using configuration qualifiers</a></li> + <li><a href="#DesigningResources">Designing alternative layouts and drawables</a></li> + </ol></li> + <li><a href="#screen-independence">Best Practices</a></li> + <li><a href="#DensityConsiderations">Additional Density Considerations</a> + <ol> + <li><a href="#scaling">Scaling Bitmap objects created at runtime</a></li> + <li><a href="#dips-pels">Converting dp units to pixel units</a></li> + </ol></li> + <li><a href="#testing">How to Test Your Application on Multiple Screens</a></li> + </ol> + <h2>Related samples</h2> + <ol> + <li><a href="{@docRoot}resources/samples/MultiResolution/index.html">Multiple +Resolutions</a></li> </ol> - <h2>See Also</h2> + <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> + <li><a href="{@docRoot}guide/practices/ui_guidelines/icon_design.html">Icon Design +Guidelines</a></li> + <li><a href="{@docRoot}guide/developing/devices/index.html">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>Android runs on a variety of devices that offer different screen sizes and densities. For +applications, the Android system provides a consistent development environment across devices and +handles most of the work to adjust each application's user interface to the screen on which it is +displayed. At the same time, the system provides APIs that allow you to control your +application's UI on specific screen sizes and densities, in order to modify and optimize your UI +design for different screen configurations. For example, you might want a UI for tablets +that's different from the design for handsets.</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>Although the system performs sufficient scaling and resizing to make your application work on +different screens, you should make the effort to optimize your application for different screen +sizes and densities. In doing so, you maximize the user experience for all devices and your users +believe that your application was actually designed for <em>their</em> devices—rather than +simply stretched to fit their devices.</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>By following the practices described in this document, you can create an application that +displays properly and provides an optimized user experience on all supported screen configurations, +using a single {@code .apk} file.</p> + +<p class="note"><strong>Note:</strong> The information in this document assumes that your +application is designed for Android 1.6 (API Level 4) or higher. If your application supports +Android 1.5 or lower, please first read <a +href="{@docRoot}guide/practices/screens-support-1.5.html">Strategies for Android 1.5</a>.</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 +<p>This section provides an overview of Android's support for multiple screens, including: an +introduction to the terms and concepts used in this document and in the API, a summary of the screen +configurations that the system supports, and an overview of the API and underlying screen-compatibility features.</p> - -<h3>Terms and Concepts</h3> +<h3 id="terms">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> + <p>For simplicity, Android groups all actual screen sizes into four generalized sizes: small, +normal, large, and extra large.</p></dd> + +<dt><em>Screen density</em></dt> + <dd>The quantity of pixels within a physical area of the screen; usually referred to as dpi (dots +per inch). For example, a "low" density screen has fewer pixels within a given physical area, +compared to a "normal" or "high" density screen.</p> + + <p>For simplicity, Android groups all actual screen densities into four generalized densities: +low, medium, high, and extra high.</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>Orientation</em></dt> + <dd>The orientation of the screen from the user's point of view. This is either landscape or +portrait, meaning that the screen's aspect ratio is either wide or tall, respectively. Be aware +that not only do different devices operate in different orientations by default, but the +orientation can change at runtime when the user rotates the device. +</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> + <dd>The total number of physical pixels on a screen. When adding support for multiple screens, +applications do not work directly with resolution; applications should be concerned only with screen +size and density, as specified by the generalized size and density groups.</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> + <dd>A virtual pixel unit that you should use when defining UI layout, 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, which is +the baseline density assumed by the system for a "medium" density screen. At runtime, the system +transparently handles any scaling of the dp units, as necessary, based on the actual density of the +screen in use. The conversion of dp units to screen pixels is simple: +<nobr><code>px = dp * (dpi / 160)</code></nobr>. +For example, on a 240 dpi screen, 1 dp equals 1.5 physical pixels. You should always use dp units +when defining your application's UI, to ensure proper display of your UI on screens with different +densities. </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>Starting with Android 1.6 (API Level 4), Android provides support for multiple screen sizes and +densities, reflecting the many different screen configurations that a device may have. You can use +features of the Android system to optimize your application's user interface for each screen +configuration and ensure that your application not only renders properly, but provides the best +user experience possible on each screen.</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> +<p>To simplify the way that you design your user interfaces for multiple screens, Android divides +the range of actual screen sizes and densities into:</p> <ul> -<li>A set of four generalized sizes: <em>small</em>, <em>normal</em>, <em>large</em>, +<li>A set of four generalized <strong>sizes</strong>: <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), +<li>A set of four generalized <strong>densities</strong>: <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>The generalized sizes and densities are arranged around a +baseline configuration that is a <em>normal</em> size and <em>mdpi</em> (medium) density. This +baseline is based upon the screen configuration for the first Android-powered device, the T-Mobile +G1, which has an HVGA screen (until Android 1.6, this was the only screen configuration that Android +supported).</p> + +<p>Each generalized size or density spans a range of actual screen sizes or density. For example, +two devices that both report a screen size of <em>normal</em> might have actual screen sizes and +aspect ratios that are slightly different when measured by hand. Similarly, two devices that report +a screen density of <em>hdpi</em> might have real pixel densities that are slightly different. +Android makes these differences abstract to applications, so you can provide UI designed for the +generalized sizes and densities and let the system handle any final adjustments as necessary. Figure +1 illustrates how different sizes and densities are roughly categorized into the different size +and density groups.</p> + +<img src="{@docRoot}images/screens_support/screens-ranges.png" style="padding:1em 0 0" alt="" /> <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> +Illustration of how Android roughly maps actual sizes and densities +to generalized sizes and densities (figures are not exact).</p> -<p>Layout designs often need to be done against a minimum amount of -available space, so each screen size bucket has an associated minimum size. -These sizes are in "dp" units -- the same units you should use in defining -your layouts, which allow us to avoid worrying about changes in screen density.</p> +<p>To optimize your application's UI for the different screen sizes and densities, you can provide +<a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">alternative +resources</a> for any of the generalized sizes and densities. Typically, you should +provide alternative layouts for some of the different screen sizes and alternative bitmap images for +different screen densities. At runtime, the system uses the appropriate size or density resources +for your application, based on the generalized size or density of the current device screen.</p> -<ul> -<li> <em>xlarge</em> screens are at least 960dp x 720dp. -<li> <em>large</em> screens are at least 640dp x 480dp. -<li> <em>normal</em> screens are at least 470dp x 320dp. -<li> <em>small</em> screens are at least 426dp x 320dp. -</ul> +<p>You do not need to provide alternative resources for every combination of screen size and +density. The system provides robust compatibility features that can handle most of the work of +rendering your application on any device screen, provided that you've implemented your UI using +techniques that allow it to gracefully resize (as described in the <a +href="#screen-independence">Best Practices</a>, below).</p> -<p>Note that these minimum screen sizes were not -as well defined prior to Android 3.0, so you may encounter some devices -that are mis-classified between normal and large. These are also based -on the physical resolution of the screen, so may vary across devices -- -for example a 1024x720 tablet with a system bar would actually have a bit -less space available to the application due to it being used by the system -bar. Android does not currently support screens smaller than the "small" -426dp x 320dp size.</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 and other -representative resolutions.</p> +<p class="note"><strong>Note:</strong> The characteristics that define a device's generalized screen +size and density are independent from each other. For example, a WVGA high-density screen is +considered a normal size screen because its physical size is about the same as the T-Mobile G1 +(Android's first device and baseline screen configuration). On the other hand, a WVGA medium-density +screen is considered a large size screen. Although it offers the same resolution (the same number of +pixels), the WVGA medium-density screen has a lower screen density, meaning that each pixel is +physically larger and, thus, the entire screen is larger than the baseline (normal size) screen.</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;"><strong>QVGA (240x320)</strong></td> - </td> - <td></td> - <td style="font-size:.9em;">480x640</td> - <td></td> - </tr> - <tr> - <td style="background-color:#f3f3f3"> - <em>Normal</em> screen - </td> - <td style="font-size:.9em;"><strong>WQVGA400 (240x400)</strong> - <br><strong>WQVGA432 (240x432)</strong></td> - <td style="font-size:.9em;"><strong>HVGA (320x480)</strong></td> - <td style="font-size:.9em;"><strong>WVGA800 (480x800)</strong> - <br><strong>WVGA854 (480x854)</strong> - <br>600x1024</td> - <td style="font-size:.9em;">640x960</td> - </tr> - <tr> - <td style="background-color:#f3f3f3"> - <em>Large</em> screen - </td> - <td style="font-size:.9em;"><strong>WVGA800** (480x800)</strong> - <br><strong>WVGA854** (480x854)</strong></td> - <td style="font-size:.9em;"><strong>WVGA800* (480x800)</strong> - <br><strong>WVGA854* (480x854)</strong> - <br>600x1024</td> - <td></td> - <td></td> - </tr> - <tr> - <td style="background-color:#f3f3f3"> - <em>Extra Large</em> screen - </td> - <td style="font-size:.9em;">600x1024</td> - <td style="font-size:.9em;">768x1024<br><strong>WXGA (768x1280)</strong> - <br>800x1280</td> - <td style="font-size:.9em;">1152x1536<br>1152x1920 - <br>1200x1920</td> - <td style="font-size:.9em;">1536x2048<br>1536x2560 - <br>1600x2560</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> - <tr> - <td colspan="4" style="border:none;font-size:90%;">** To emulate this - configuration, specify a custom density of 120 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="density-independence">Density independence</h3> -<h3 id="support">How Android supports multiple screens</h3> +<p>Your application achieves "density independence" when it preserves the physical size (from +the user's point of view) of user interface elements when displayed on screens with different +densities.</p> -<div class="sidebox-wrapper"> -<div class="sidebox"> -<h2>Using the alternative resources framework</h2> +<p>Maintaining density independence is important because, without it, a UI element (such as a +button) appears physically larger on a low density screen and smaller on a high density screen. Such +density-related size changes can cause problems in your application layout and usability. Figures 2 +and 3 show the difference between an application when it does not provide density independence and +when it does, respectively.</p> -<p>The platform's support for loading screen size- and density-specific -resources at run time is based on the alternative resources framework. +<img src="{@docRoot}images/screens_support/density-test-bad.png" alt="" /> +<p class="img-caption"><strong>Figure 2.</strong> Example application without support for +different densities, as shown on low, medium, and high density screens.</p> -<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> +<img src="{@docRoot}images/screens_support/density-test-good.png" alt="" /> +<p class="img-caption"><strong>Figure 3.</strong> Example application with good support for +different densities (it's density independent), as shown on low, medium, and high +density screens.</p> -<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> +<p>The Android system helps your application achieve density independence in two ways: </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> +<li>The system scales dp units as appropriate for the current screen density</li> +<li>The system scales drawable resources to the appropriate size, based on the current screen +density, if necessary</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>In figure 2, the text view and bitmap drawable have dimensions specified in pixels ({@code px} +units), so the elements are physically larger on a low density screen and smaller on a high density +screen. This is because although the actual screen sizes may be the same, the high density screen +has more pixels per inch (the same amount of pixels fit in a smaller area). In figure 3, the layout +dimensions are specified in density-independent pixels ({@code dp} units). Because the baseline for +density-independent pixels is a medium-density screen, the device with a medium-density screen looks +the same as it does in figure 2. For the low-density and high-density screens, however, the system +scales the density-independent pixel values down and up, respectively, to fit the screen as +appropriate.</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>In most cases, you can ensure density independence in your application simply by specifying all +layout dimension values in density-independent pixels (<code>dp</code> units) or with {@code +"wrap_content"}, as appropriate. The system then scales bitmap drawables as appropriate in order to +display at the appropriate size, based on the appropriate scaling factor for the current screen's +density.</p> -<p>The sections below provide more information how to take advantage of the -platform's multiple-screens support. </p> +<p>However, bitmap scaling can result in blurry or pixelated bitmaps, which you might notice in the +above screenshots. To avoid these artifacts, you should provide alternative bitmap resources for +different densities. For example, you should provide higher-resolution bitmaps for high-density +screens and the system will use those instead of resizing the bitmap designed for medium-density +screens. The following section describes more about how to supply alternative resources for +different screen configurations.</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> +<h2 id="support">How to Support Multiple Screens</h2> -<p>The platform provides density independence to applications by default. It -does this in three ways: </p> +<p>The foundation of Android's support for multiple screens is its ability to manage the rendering +of an application's layout and bitmap drawables in an appropriate way for the current screen +configuration. The system handles most of the work to render your application properly on each +screen configuration by scaling layouts to fit the screen size/density and scaling bitmap drawables +for the screen density, as appropriate. To more gracefully handle different screen configurations, +however, you should also:</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> + <li><strong>Provide different layouts for different screen sizes</strong> + <p>By default, Android resizes your application layout to fit the current device screen. In most +cases, this works fine. In other cases, your UI might not look as good and might need adjustments +for different screen sizes. For example, on a larger screen, you might want to adjust the position +and size of some elements to take advantage of the additional screen space, or on a smaller screen, +you might need to adjust sizes so that everything can fit on the screen.</p> + <p>The configuration qualifiers you can use to provide size-specific resources are +<code>small</code>, <code>normal</code>, <code>large</code>, and <code>xlarge</code>. For +example, layouts for an extra large screen should go in {@code layout-xlarge/}.</p> + </li> + + <li><strong>Provide different bitmap drawables for different screen densities</strong> + <p>By default, Android scales your bitmap drawables ({@code .png}, {@code .jpg}, and {@code +.gif} files) and Nine-Patch drawables ({@code .9.png} files) so that they render at the appropriate +physical size on each device. For example, if your application provides bitmap drawables only for +the baseline, medium screen density (mdpi), then the system scales them up when on a high-density +screen, and scales them down when on a low-density screen. This scaling can cause artifacts in the +bitmaps. To ensure your bitmaps look their best, you should include alternative versions at +different resolutions for different screen densities.</p> + <p>The configuration qualifiers you can use for density-specific resources are +<code>ldpi</code> (low), <code>mdpi</code> (medium), <code>hdpi</code> (high), and +<code>xhdpi</code> (extra high). For example, bitmaps for high-density screens should go in +{@code drawable-hdpi/}.</p> + </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> +<p>The size and density configuration qualifiers correspond to the generalized sizes and densities +described in <a href="#range">Range of screens supported</a>, above.</p> +<p class="note"><strong>Note:</strong> If you're not familiar with configuration qualifiers and how +the system uses them to apply alternative resources, read <a +href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">Providing +Alternative Resources</a> for more information.</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>At runtime, the system ensures the best possible display on the current screen with +the following procedure for any given resource:</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>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> +<ol> +<li>The system uses the appropriate alternative resource + <p>Based on the size and density of the current screen, the system uses any size- and +density-specific resource provided in your application. For example, if the device has a +high-density screen and the application requests a drawable resource, the system looks for a +drawable resource directory that best matches the device configuration. Depending on the other +alternative resources available, a resource directory with the {@code hdpi} qualifier (such as +{@code drawable-hdpi/}) might be the best match, so the system uses the drawable resource from this +directory.</p> +</li> + +<li>If no matching resource is available, the system uses the default resource and scales it up +or down as needed to match the current screen size and density + <p>The "default" resources are those that are not tagged with a configuration qualifier. For +example, the resources in {@code drawable/} are the default drawable resources. The system +assumes that default resources are designed for the baseline screen size and density, which is a +normal screen size and a medium density. As such, the system scales default density +resources up for high-density screens and down for low-density screens, as appropriate.</p> + <p>However, when the system is looking for a density-specific resource and does not find it in +the density-specific directory, it won't always use the default resources. The system may +instead use one of the other density-specific resources in order to provide better results +when scaling. For example, when looking for a low-density resource and it is not available, the +system prefers to scale-down the high-density version of the resource, because the +system can easily scale a high-density resource down to low-density by a factor of 0.5, with +fewer artifacts, compared to scaling a medium-density resource by a factor of 0.75.</p> +</li> +</ol> -<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>For more information about how Android selects alternative resources by matching configuration +qualifiers to the device configuration, read +<a href="{@docRoot}guide/topics/resources/providing-resources.html#BestMatch">How Android +Finds the Best-matching Resource</a>.</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> +<h3 id="qualifiers">Using configuration qualifiers</h3> -<p>The following example shows a manifest that declares support for small, normal, large, and - xlarge screens in any density.</p> +<p>Android supports several configuration qualifiers that allow you to control how the system +selects your alternative resources based on the characteristics of the current device screen. A +configuration qualifier is a string that you can append to a resource directory in your Android +project and specifies the configuration for which the resources inside are designed.</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> +<p>To use a configuration qualifier:</p> +<ol> + <li>Create a new directory in your project's {@code res/} directory and name it using the +format: <nobr>{@code <resources_name>-<qualifier>}</nobr> + <ul> + <li>{@code <resources_name>} is the standard resource name (such as {@code drawable} or +{@code layout}).</li> + <li>{@code <qualifier>} is a configuration qualifier from table 1, below, specifying the +screen configuration for which these resources are to be used (such as {@code hdpi} or {@code +xlarge}).</li> + </ul> + <p>You can use more than one {@code <qualifier>} at a time—simply separate each +qualifier with a dash.</p> + </li> + <li>Save the appropriate configuration-specific resources in this new directory. The resource +files must be named exactly the same as the default resource files.</li> +</ol> + +<p>For example, {@code xlarge} is a configuration qualifier for extra large screens. When you append +this string to a resource directory name (such as {@code layout-xlarge}), it indicates to the +system that these resources are to be used on devices that have an extra large screen.</p> + +<p class="table-caption"><strong>Table 1.</strong> Configuration qualifiers that allow you to +provide special resources for different screen configurations.</p> <table> <tr> @@ -784,691 +370,627 @@ of Screens Supported</a>, earlier in this document.</p> <tr> <td rowspan="4">Size</td> <td><code>small</code></td> - <td>Resources designed for <em>small</em> size screens.</td> + <td>Resources for <em>small</em> size screens.</td> </tr> <tr> <td><code>normal</code></td> - <td>Resources designed for <em>normal</em> size screens.</td> + <td>Resources for <em>normal</em> size screens. (This is the baseline size.)</td> </tr> <tr> <td><code>large</code></td> -<td>Resources designed for <em>large</em> size screens.</td> +<td>Resources 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> +<td>Resources 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> +<td>Resources for low-density (<em>ldpi</em>) screens (~120dpi).</td> </tr> <tr> <td><code>mdpi</code></td> -<td>Resources designed for medium-density (<em>mdpi</em>) screens.</td> +<td>Resources for medium-density (<em>mdpi</em>) screens (~160dpi). (This is the baseline +density.)</td> </tr> <tr> <td><code>hdpi</code></td> -<td>Resources designed for high-density (<em>hdpi</em>) screens.</td> +<td>Resources for high-density (<em>hdpi</em>) screens (~240dpi).</td> </tr> <tr> <td><code>xhdpi</code></td> -<td>Resources designed for extra high-density (<em>xhdpi</em>) screens.</td> +<td>Resources for extra high-density (<em>xhdpi</em>) screens (~320dpi).</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> +<td>Resources for all densities. These are density-independent resources. The system does not +scale resources tagged with this qualifier, regardless of the current screen's density.</td> +</tr> + +<tr> +<td rowspan="2">Orientation</td> +<td><code>land</code></td> +<td>Resources for screens in the landscape orientation (wide aspect ratio).</td> +</tr> +<tr> +<td><code>port</code></td> +<td>Resources for screens in the portrait orientation (tall aspect ratio).</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> +<td>Resources for screens that have a significantly taller or wider aspect ratio (when in portrait +or landscape orientation, respectively) 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> +<td>Resources for use screens that have an aspect ratio that is similar to the baseline screen +configuration.</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>For more information about how these qualifiers roughly correspond to real screen +sizes and densities, see <a href="#range">Range of Screens Supported</a>, earlier in this +document.</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> +<p>For example, the following is a list of resource directories in an application that +provides different layout designs for different screen sizes and different bitmap drawables +for medium, high, and extra 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 +<pre class="classic"> +res/layout/my_layout.xml // layout for normal screen size ("default") +res/layout-small/my_layout.xml // layout for small screen size +res/layout-large/my_layout.xml // layout for large screen size +res/layout-xlarge/my_layout.xml // layout for extra large screen size +res/layout-xlarge-land/my_layout.xml // layout for extra large in landscape orientation -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 +res/drawable-mdpi/my_icon.png // bitmap for medium density +res/drawable-hdpi/my_icon.png // bitmap for high density +res/drawable-xhdpi/my_icon.png // bitmap for extra high density </pre> -<p>For more information about how to use resource qualifiers or how the platform -selects them, please read +<p>For more information about how to use alternative resources and a complete list of +configuration qualifiers (not just for screen configurations), see <a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources"> Providing Alternative Resources</a>.</p> + <p class="note"><strong>Tip:</strong> If you have some drawable resources that the system +should never scale (perhaps because you perform some adjustments to the image yourself at +runtime), you should place them in a directory with the {@code nodpi} configuration qualifier. +Resources with this qualifier are considered density-agnostic and the system will not scale +them.</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> +<h3 id="DesigningResources">Designing alternative layouts and drawables</h3> + +<p>The types of alternative resources you should create depends on your application's needs. +Usually, you should use the size and orientation qualifiers to provide alternative layout resources +and use the density qualifiers to provide alternative bitmap drawable resources.</p> -<p>You can easily ensure that your application will display properly on -different screens. Here is a quick checklist:</p> +<p>The following sections summarize how you might want to use the size and density qualifiers to +provide alternative layouts and drawables, respectively.</p> + + +<h4>Alternative layouts</h4> + +<p>Generally, you'll know whether you need alternative layouts for different screen sizes once +you test your application on different screen configurations. For example:</p> + +<ul> + <li>When testing on a small screen, you might discover that your layout doesn't quite fit on the +screen. For example, a row of buttons might not fit within the width of the screen on a small screen +device. In this case you should provide an alternative layout for small screens that adjusts the +size or position of the buttons.</li> + <li>When testing on an extra large screen, you might realize that your layout doesn't make +efficient use of the big screen and is obviously stretched to fill it. +In this case, you should provide an alternative layout for extra large screens that provides a +redesigned UI that is optimized for bigger screens such as tablets. + <p>Although your application should work fine without an alternative layout on big screens, it's +quite important to users that your application looks as though it's designed specifically for their +devices. If the UI is obviously stretched, users are more likely to be unsatisfied with the +application experience.</p></li> + <li>And, when testing in the landscape orientation compared to the portrait orientation, you +might notice that UI elements placed at the bottom of the screen for the portrait orientation +should instead be on the right side of the screen in landscape orientation.</li> +</ul> + +<p>To summarize, you should be sure that your application layout:</p> +<ul> + <li>Fits on small screens (so users can actually use your application)</li> + <li>Is optimized for bigger screens to take advantage of the additional screen space</li> + <li>Is optimized for both landscape and portrait orientations</li> +</ul> + +<p>If your UI uses bitmaps that need to fit the size of a view even after the system scales +the layout (such as the background image for a button), you should use <a +href="{@docRoot}guide/topics/graphics/2d-graphics.html#nine-patch">Nine-Patch</a> bitmap files. A +Nine-Patch file is basically a PNG file in which you specific two-dimensional regions that are +stretchable. When the system needs to scale the view in which the bitmap is used, the system +stretches the Nine-Patch bitmap, but stretches only the specified regions. As such, you don't +need to provide different drawables for different screen sizes, because the Nine-Patch bitmap can +adjust to any size. You should, however, provide alternate versions of your Nine-Patch files for +different screen densities.</p> + + +<h4>Alternative drawables</h4> + +<div class="figure" style="width:223px;margin:0"> +<img src="{@docRoot}images/screens_support/screens-densities.png" alt="" /> +<p class="img-caption"><strong>Figure 4.</strong> Relative sizes for bitmap drawables +that support each density.</p> +</div> + +<p>Almost every application should have alternative drawable resources for different screen +densities, because almost every application has a launcher icon and that icon should look good on +all screen densities. Likewise, if you include other bitmap drawables in your application (such +as for menu icons or other graphics in your application), you should provide alternative versions or +each one, for different densities.</p> + +<p class="note"><strong>Note:</strong> You only need to provide density-specific drawables for +bitmap files ({@code .png}, {@code .jpg}, or {@code .gif}) and Nine-Path files ({@code +.9.png}). If you use XML files to define shapes, colors, or other <a +href="{@docRoot}guide/topics/resources/drawable-resource.html">drawable resources</a>, you should +put one copy in the default drawable directory ({@code drawable/}).</p> + +<p>To create alternative bitmap drawables for different densities, you should follow the +<b>3:4:6:8 scaling ratio</b> between the four generalized densities. For example, if you have +a bitmap drawable that's 48x48 pixels for medium-density screen (the size for a launcher icon), +all the different sizes should be:</p> + +<ul> + <li>36x36 for low-density</li> + <li>48x48 for medium-density</li> + <li>72x72 for high-density</li> + <li>96x96 for extra high-density</li> +</ul> + +<p>For more information about designing icons, see the <a +href="{@docRoot}guide/practices/ui_guidelines/icon_design.html">Icon Design Guidelines</a>, +which includes size information for various bitmap drawables, such as launcher icons, menu +icons, status bar icons, tab icons, and more.</p> + + + +<h2 id="screen-independence">Best Practices</h2> + +<p>The objective of supporting multiple screens is to create an application that can function +properly and look good on any of the generalized screen configurations supported by Android. The +previous sections of this document provide information about how Android adapts your +application to screen configurations and how you can customize the look of your application on +different screen configurations. This section provides some additional tips and an overview of +techniques that help ensure that your application scales properly for different screen +configurations.</p> + +<p>Here is a quick checklist about how you can ensure that your application displays properly +on different screens:</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> + <li>Use {@code wrap_content}, {@code fill_parent}, or {@code dp} units when specifying +dimensions in an XML layout file</li> + <li>Do not use hard coded pixel values in your application code</li> + <li>Do not use {@code AbsoluteLayout} (it's deprecated)</li> + <li>Supply alternative bitmap drawables for different screen densities</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> +<p>The following sections provide more details.</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> +<h3 id="use-relative">1. Use wrap_content, fill_parent, or the dp unit for layout dimensions</h3> -// Use mGestureThreshold as a distance in pixels -</pre> +<p>When defining the <a +href="{@docRoot}reference/android/view/ViewGroup.LayoutParams.html#attr_android:layout_width" +>{@code android:layout_width}</a> and <a +href="{@docRoot}reference/android/view/ViewGroup.LayoutParams.html#attr_android:layout_height" +>{@code android:layout_height}</a> for +views in an XML layout file, using <code>"wrap_content"</code>, +<code>"fill_parent"</code> or <code>dp</code> units guarantees that the view is +given an appropriate size on the current device screen.</p> -<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> +<p>For instance, a view with a <code>layout_width="100dp"</code> measures 100 pixels wide on +medium-density screen and the system scales it up to 150 pixels wide on high-density screen, so +that the view occupies approximately the same physical space on the screen.</p> -<h4>Use pre-scaled configuration values</h4> +<p>Similarly, you should prefer the <code>sp</code> (scale-independent pixel) to define text +sizes. The <code>sp</code> scale factor depends on a user setting and the system scales the +size the same as it does for {@code dp}.</p> -<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> +<h3>2. Do not use hard-coded pixel values in your application code</h3> -<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> +<p>For performance reasons and to keep the code simpler, the Android system 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 using pixels, but always based on the current screen density. +For instance, if <code>myView.getWidth()</code> returns 10, the view is 10 pixels wide on the +current screen, but on a device with a higher density screen, the value returned might be 15. If you +use pixel values in your application code to work with bitmaps that are not pre-scaled for the +current screen density, you might need to scale the pixel values that you use in your code to match +the un-scaled bitmap source.</p> -<h3>4. Use density and/or size-specific resources</h3> +<p>If your application manipulates bitmaps or deals with pixel values at runtime, see the section +below about <a href="#DensityConsiderations">Additional Density Considerations</a>.</p> -<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> +<h3 id="avoid-absolute">3. Do not use AbsoluteLayout </h3> + +<p>Unlike the other layouts widgets, {@link android.widget.AbsoluteLayout} enforces +the use of fixed positions to lay out its child views, which can easily lead to user interfaces that +do not work well on different displays. Because of this, {@link android.widget.AbsoluteLayout} was +deprecated in Android 1.5 (API Level 3).</p> + +<p>You should instead use {@link android.widget.RelativeLayout}, which uses relative positioning +to lay out its child views. For instance, you can specify that a button widget should appear "to +the right of" a text widget.</p> -<h4 id="resource-dirs">Custom resources and directories</h4> + +<h3>4. Use size and density-specific resources</h3> + +<p>Although the system scales your layout and drawable resources based on the current screen +configuration, you may want to make adjustments to the UI on different screen sizes and provide +bitmap drawables that are optimized for different densities. This essentially reiterates the +information from earlier in this document.</p> <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 +screen configurations, adjust your layouts and bitmap drawables in configuration-specific +resource 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> +<pre class="classic"> +res/drawable-mdpi/icon.png //for medium-density screens +res/drawable-hdpi/icon.png //for high-density screens +</pre> -<p style="margin-left:2em;"><code>res/drawable-hdpi/icon.png // -for high-density screens</code></p> +<p class="note"><strong>Note:</strong> If a density qualifier is not defined in a directory name, +the system assumes that the resources in that directory are designed for the baseline medium +density and will scale for other densities as appropriate.</p> + +<p>For more information about valid configuration qualifiers, see <a href="#qualifiers">Using +configuration qualifiers</a>, earlier in this document.</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> +<h2 id="DensityConsiderations">Additional Density Considerations</h2> -<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>This section describes more about how Android performs scaling for bitmap drawables on different +screen densities and how you can further control how bitmaps are drawn on different densities. The +information in this section shouldn't be important to most applications, unless you have encountered +problems in your application when running on different screen densities or your application +manipulates graphics.</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> +<p>To better understand how you can support multiple densities when manipulating graphics at +runtime, you should understand that the system helps ensure the proper scale for bitmaps in the +following ways:</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> +<li><em>Pre-scaling of resources (such as bitmap drawables)</em> + + <p>Based on the density of the current screen, the system uses any size- or density-specific +resources from your application and displays them without scaling. If resources are not available in +the correct density, the system loads the default resources and scales them up or down as needed to +match the current screen's density. The system assumes that default resources (those from a +directory without configuration qualifiers) are designed for the baseline screen density (mdpi), +unless they are loaded from a density-specific resource directory. Pre-scaling is, thus, what the +system does when resizing a bitmap to the appropriate size for the current screen +density.</p> + + <p>If you request the dimensions of a pre-scaled resource, the system returns values +representing the dimensions <em>after</em> scaling. For example, a bitmap designed at 50x50 pixels +for an mdpi screen is scaled to 75x75 pixels on an hdpi screen (if there is no alternative resource +for hdpi) and the system reports the size as such.</p> + +<p>There are some situations in which you might not want Android to pre-scale +a resource. The easiest way to avoid pre-scaling is to put the resource in a resource directory +with the {@code nodpi} configuration qualifier. For example:</p> + +<pre class="classic">res/drawable-nodpi/icon.png</pre> + +<p>When the system uses the {@code icon.png} bitmap from this folder, it does not scale it +based on the current device density.</p> +</li> + +<li><em>Auto-scaling of pixel dimensions and coordinates</em> + + <p>An application can disable pre-scaling by setting <a +href="{@docRoot}guide/topics/manifest/supports-screens-element.html#any">{@code +android:anyDensity}</a> to {@code "false"} in the manifest or programmatically for a {@link +android.graphics.Bitmap} by setting {@link android.graphics.BitmapFactory.Options#inScaled} to +{@code "false"}. In this case, the system auto-scales any absolute pixel coordinates and pixel +dimension values at draw time. It does this to ensure that pixel-defined screen elements are still +displayed at approximately the same physical size as they would be at the baseline screen density +(mdpi). The system handles this scaling transparently to the application and reports the scaled +pixel dimensions to the application, rather than physical pixel dimensions.</p> + + <p>For instance, suppose a device has a WVGA high-density screen, which is 480x800 and about the +same size as a traditional HVGA screen, but it's running an application that has disabled +pre-scaling. In this case, the system will "lie" to the application when it queries for screen +dimensions, and report 320x533 (the approximate mdpi translation for the screen density). Then, when +the application does drawing operations, such as invalidating the rectangle from (10,10) to (100, +100), the system transforms the coordinates by scaling them the appropriate amount, and actually +invalidate the region (15,15) to (150, 150). This discrepancy may cause unexpected behavior if +your application directly manipulates the scaled bitmap, but this is considered a reasonable +trade-off to keep the performance of applications as good as possible. If you encounter this +situation, read the following section about <a href="#dips-pels">Converting dp units to pixel +units</a>.</p> + + <p>Usually, <strong>you should not disable pre-scaling</strong>. The best way to support multiple +screens is to follow the basic techniques described above in <a href="#support">How to Support +Multiple Screens</a>.<p> +</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> +<p>If your application manipulates bitmaps or directly interacts with pixels on the screen in some +other way, you might need to take additional steps to support different screen densities. For +example, if you respond to touch gestures by counting the number of pixels that a finger +crosses, you need to use the appropriate density-independent pixel values, instead of actual +pixels.</p> -<h2 id="testing">How to Test Your Application on Multiple Screens</h2> +<h3 id="scaling">Scaling Bitmap objects created at runtime</h3> -<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 class="figure" style="width:300px"> +<img src="{@docRoot}images/screens_support/scale-test.png" alt="" /> +<p class="img-caption"><strong>Figure 5.</strong> Comparison of pre-scaled and auto-scaled +bitmaps, from <a +href="resources/samples/ApiDemos/src/com/example/android/apis/graphics/DensityActivity.html"> +ApiDemos</a>. +</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>If your application creates an in-memory bitmap (a {@link android.graphics.Bitmap} object), the +system assumes that the bitmap is designed for the baseline medium-density screen, by default, and +auto-scales the bitmap at draw time. The system applies "auto-scaling" to a {@link +android.graphics.Bitmap} when the bitmap has unspecified density properties. If you don't properly +account for the current device's screen density and specify the bitmap's density properties, the +auto-scaling can result in scaling artifacts the same as when you don't provide alternative +resources.</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> +<p>To control whether a {@link android.graphics.Bitmap} created at runtime is scaled or not, you can +specify the density of the bitmap with {@link android.graphics.Bitmap#setDensity setDensity()}, +passing a density constant from {@link android.util.DisplayMetrics}, such as {@link +android.util.DisplayMetrics#DENSITY_HIGH} or {@link android.util.DisplayMetrics#DENSITY_LOW}.</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>If you're creating a {@link android.graphics.Bitmap} using {@link +android.graphics.BitmapFactory}, such as from a file or a stream, you can use {@link +android.graphics.BitmapFactory.Options BitmapFactory.Options} to define properties of the bitmap as +it already exists, which determine if or how the system will scale it. For example, you can use the +{@link android.graphics.BitmapFactory.Options#inDensity} field to define the density for which the +bitmap is designed and the {@link +android.graphics.BitmapFactory.Options#inScaled} field to specify whether the bitmap should scale to +match the current device's screen density.</p> -<p>The Android 2.0 platform offers all of the Android 1.6 default skins, -above, plus:</p> +<p>If you set the {@link +android.graphics.BitmapFactory.Options#inScaled} field to {@code false}, then you disable any +pre-scaling that the system may apply to the bitmap and the system will then auto-scale it at draw +time. Using auto-scaling instead of pre-scaling can be more CPU expensive, but uses +less memory.</p> -<ul> - <li> - WQVGA400 (240x400, low density, normal screen) - </li> - <li> - WQVGA432 (240x432, low density, normal screen) - </li> -</ul> +<p>Figure 5 demonstrates the results of the pre-scale and auto-scale mechanisms when loading low +(120), medium (160) and high (240) density bitmaps on a high-density 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. You can find the source code for this sample application, which +demonstrates using pre-scaled and auto-scaled bitmaps, in <a +href="resources/samples/ApiDemos/src/com/example/android/apis/graphics/DensityActivity.html"> +ApiDemos</a>.</p> -<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> +<p class="note"><strong>Note:</strong> In Android 3.0 and above, there should be no perceivable +difference between pre-scaled and auto-scaled bitmaps, due to improvements in the graphics +framework.</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> +<h3 id="dips-pels">Converting dp units to pixel units</h3> -<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 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 or fling gesture is recognized after the user's +finger has moved by at least 16 pixels. On a baseline screen, a user's must move by {@code 16 pixels +/ 160 dpi}, which equals 1/10th of an inch (or 2.5 mm) before the gesture is recognized. On a device +with a high density display (240dpi), the user's must move by {@code 16 pixels / 240 dpi}, which +equals 1/15th of an inch (or 1.7 mm). The distance is much shorter and the application thus appears +more sensitive to the user.</p> -<p>In the <code>android</code> tool, follow these steps to create an AVD with a -custom resolution or density:</p> +<p>To fix this issue, the gesture threshold must be expressed in code in <code>dp</code> and then +converted to actual pixels. For example:</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> +<pre>// The gesture threshold expressed in dp +private static final float GESTURE_THRESHOLD_DP = 16.0f; -<p>In the example above (WVGA medium density), the new AVD will emulate a 5.8" -WVGA screen.</p> +// Get the screen's density scale +final float scale = {@link android.content.ContextWrapper#getResources getResources()}.{@link +android.content.res.Resources#getDisplayMetrics getDisplayMetrics()}.density; +// Convert the dps to pixels, based on density scale +mGestureThreshold = (int) (GESTURE_THRESHOLD_DP * scale + 0.5f);</span> -<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> +// Use mGestureThreshold as a distance in pixels... +</pre> -<pre>emulator -avd WVGA800 -scale 96dpi -dpi-device 160</pre> +<p>The {@link android.util.DisplayMetrics#density DisplayMetrics.density} field specifies the scale +factor you must use to convert {@code dp} units to pixels, according to the current screen density. +On a medium-density screen, {@link android.util.DisplayMetrics#density DisplayMetrics.density} +equals 1.0; on a high-density screen it equals 1.5; on an extra high-density screen, it equals 2.0; +and on a low-density screen, it equals 0.75. This figure is the factor by which you should multiply +the {@code dp} units on order to get the actual pixel count for the current screen. (Then add {@code +0.5f} to round the figure up to the nearest whole number, when converting to an integer.) For more +information, refer to the {@link android.util.DisplayMetrics DisplayMetrics} class.</p> +<p>However, instead of defining an arbitrary threshold for this kind of event, you should +use pre-scaled configuration values that are available from {@link +android.view.ViewConfiguration}.</p> -<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> +<h4 id="pre-scaled-values">Using pre-scaled configuration values</h4> -<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>You can use the {@link android.view.ViewConfiguration} class to access common distances, +speeds, and times used by the Android system. For instance, the +distance in pixels used by the framework as the scroll threshold can be obtained with {@link +android.view.ViewConfiguration#getScaledTouchSlop()}:</p> + +<pre> +private static final int GESTURE_THRESHOLD_DP = ViewConfiguration.get(myContext).getScaledTouchSlop(); +</pre> + +<p>Methods in {@link android.view.ViewConfiguration} 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> -<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> +<h2 id="testing">How to Test Your Application on Multiple Screens</h2> + +<div class="figure" style="width:500px;margin:0"> + <img src="{@docRoot}images/screens_support/avds-config.png" alt="" /> + <p class="img-caption"><strong>Figure 6.</strong> + A set of AVDs for testing screens support.</p> +</div> + +<p>Before publishing your application, you should thoroughly test it in all of the supported screen +sizes and densities. The Android SDK includes emulator skins you can use, which +replicate the sizes and densities of common screen configurations on which your application is +likely to run. You can also modify the default size, density, and resolution of the emulator skins +to replicate the characteristics of any specific screen. Using the emulator skins and additional +custom configurations allows you to test any possible screen configuration, so you don't +have to buy various devices just to test your application's screen support.</p> -<p>Because these device has smaller state/resolution, there are known -limitations when application runs in compatibility mode.</p> +<p>To set up an environment for testing your application's screen support, you should create a +series of AVDs (Android Virtual Devices), using emulator skins and screen configurations that +emulate the screen sizes and densities you want your application to support. To do so, you can use +the Android SDK and AVD Manager to create the AVDs and launch them with a graphical interface.</p> -<h4>QVGA</h4> +<p>To launch the Android SDK and AVD Manager, execute the {@code +SDK Manager.exe} from your Android SDK directory (on Windows only) or execute {@code android} from +the {@code <sdk>/tools/} directory (on all platforms). Figure 6 shows the Android SDK and +AVD Manager with a selection of AVDs, for testing various screen configurations.</p> -<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>Table 2 shows the various emulator skins that are available in the Android SDK, which you can use +to emulate some of the most common screen configurations.</p> -<p>Examples:</p> +<p>For more information about creating and using AVDs to test your application, see <a +href="{@docRoot}guide/developing/devices/managing-avds.html">Managing AVDs with AVD +Manager</a>.</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> + +<p class="table-caption" id="screens-table"><strong>Table 2.</strong> Various screen +configurations available from emulator skins in the Android SDK (indicated in bold) and other +representative resolutions.</p> + + <table class="normal-headers"> + <tbody> + <tr> + <th></th> + <th> + <nobr>Low density (120), <em>ldpi</em></nobr> + </th> + <th> + <nobr>Medium density (160), <em>mdpi</em></nobr> + </th> + <th> + <nobr>High density (240), <em>hdpi</em><nobr> + </th> + <th> + <nobr>Extra high density (320), <em>xhdpi</em><nobr> + </th> + </tr> + <tr> + <th> + <em>Small</em> screen + </th> + <td><strong>QVGA (240x320)</strong></td> + <td></td> + <td>480x640</td> + <td></td> + </tr> + <tr> + <th> + <em>Normal</em> screen + </th> + <td><strong>WQVGA400 (240x400)</strong> + <br><strong>WQVGA432 (240x432)</strong></td> + <td><strong>HVGA (320x480)</strong></td> + <td><strong>WVGA800 (480x800)</strong> + <br><strong>WVGA854 (480x854)</strong> + <br>600x1024</td> + <td>640x960</td> + </tr> + <tr> + <th> + <em>Large</em> screen + </th> + <td><strong>WVGA800** (480x800)</strong> + <br><strong>WVGA854** (480x854)</strong></td> + <td><strong>WVGA800* (480x800)</strong> + <br><strong>WVGA854* (480x854)</strong> + <br>600x1024</td> + <td></td> + <td></td> + </tr> + <tr> + <th> + <em>Extra Large</em> screen + </th> + <td>1024x600</td> + <td><strong>WXGA (1280x800)</strong><sup>†</sup><br> + 1024x768<br>1280x768</td> + <td>1536x1152<br>1920x1152 + <br>1920x1200</td> + <td>2048x1536<br>2560x1536 + <br>2560x1600</td> + </tr> + <tr> + <td colspan="5" style="border:none;font-size:85%;">* To emulate this configuration, specify a +custom density of 160 when creating an AVD that uses a WVGA800 or WVGA854 skin.<br/> + ** To emulate this configuration, specify a custom density of 120 when creating an AVD that +uses a WVGA800 or WVGA854 skin.<br/> + † This skin is available with the Android 3.0 platform + </td> + </tr> </table> +<p>To see the relative numbers of active devices that support any given screen configuration, see +the <a href="{@docRoot}resources/dashboard/screens.html">Screen Sizes and Densities</a> +dashboard.</p> -<h4>Images with 1 pixel height/width.</h4> +<div class="figure" style="width:204px"> + <img src="{@docRoot}images/screens_support/avd-start.png" alt="" /> + <p class="img-caption"><strong>Figure 7.</strong> + Size and density options you can set, when starting an AVD from the Android SDK and AVD +Manager.</p> +</div> -<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>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 sizes and densities. To +do so you need to know the approximate density, in dpi, of your computer +monitor (for instance, a 30" Dell monitor has a density of about 96 dpi). When you launch an AVD +from the Android SDK and AVD Manager, you can specify the screen size for the emulator and your +monitor dpi in the Launch Options, as shown in figure 7.</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> +<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 create an AVD that uses a custom resolution +or density. When creating the AVD from the Android SDK and AVD Manager, specify the Resolution, +instead of selecting a Built-in Skin.</p> -<img height=222 src="{@docRoot}images/screens_support/afdvfckr9j_20fvptbbdd_b.png" width=166> +<p>If you are launching your AVD from the command line, you can specify the scale for +the emulator with the <code>-scale</code> option. For example:</p> +<pre>emulator -avd <avd_name> -scale 96dpi</pre> +<p>To refine the size of the emulator, you can instead pass the {@code -scale} option a number +between 0.1 and 3 that represents the desired scaling factor.</p> +<p>For more information about creating AVDs from the command line, see <a +href="{@docRoot}guide/developing/devices/managing-avds-cmdline.html">Managing AVDs from the +Command Line</a></p> diff --git a/docs/html/guide/topics/resources/providing-resources.jd b/docs/html/guide/topics/resources/providing-resources.jd index 7c84bd2..caebe55 100644 --- a/docs/html/guide/topics/resources/providing-resources.jd +++ b/docs/html/guide/topics/resources/providing-resources.jd @@ -461,8 +461,8 @@ Level 8</em></li> to match the device density.</li> </ul> <p><em>Added in API Level 4.</em></p> - <p>There is thus a 3:4:6 scaling ratio between the three densities, so a 9x9 bitmap - in ldpi is 12x12 in mdpi and 18x18 in hdpi.</p> + <p>There is thus a 3:4:6:8 scaling ratio between the four densities, so a 9x9 bitmap + in ldpi is 12x12 in mdpi, 18x18 in hdpi and 24x24 in xhdpi.</p> <p>When Android selects which resource files to use, it handles screen density differently than the other qualifiers. In step 1 of <a href="#BestMatch">How Android finds the best diff --git a/docs/html/images/screens_support/avd-start.png b/docs/html/images/screens_support/avd-start.png Binary files differnew file mode 100644 index 0000000..affb4bd --- /dev/null +++ b/docs/html/images/screens_support/avd-start.png diff --git a/docs/html/images/screens_support/avds-config.png b/docs/html/images/screens_support/avds-config.png Binary files differindex 7db8c73..3af1c39 100644 --- a/docs/html/images/screens_support/avds-config.png +++ b/docs/html/images/screens_support/avds-config.png diff --git a/docs/html/images/screens_support/compat-mode-on.png b/docs/html/images/screens_support/compat-mode-on.png Binary files differnew file mode 100644 index 0000000..ebdbf41 --- /dev/null +++ b/docs/html/images/screens_support/compat-mode-on.png diff --git a/docs/html/images/screens_support/density-test-bad.png b/docs/html/images/screens_support/density-test-bad.png Binary files differnew file mode 100644 index 0000000..d3fe1c3 --- /dev/null +++ b/docs/html/images/screens_support/density-test-bad.png diff --git a/docs/html/images/screens_support/density-test-good.png b/docs/html/images/screens_support/density-test-good.png Binary files differnew file mode 100644 index 0000000..f2eb47c --- /dev/null +++ b/docs/html/images/screens_support/density-test-good.png diff --git a/docs/html/images/screens_support/icon-density-example.png b/docs/html/images/screens_support/icon-density-example.png Binary files differnew file mode 100644 index 0000000..3cac5ee --- /dev/null +++ b/docs/html/images/screens_support/icon-density-example.png diff --git a/docs/html/images/screens_support/scale-test.png b/docs/html/images/screens_support/scale-test.png Binary files differindex f4fc662..19cf34f 100644 --- a/docs/html/images/screens_support/scale-test.png +++ b/docs/html/images/screens_support/scale-test.png diff --git a/docs/html/images/screens_support/screens-densities.png b/docs/html/images/screens_support/screens-densities.png Binary files differnew file mode 100644 index 0000000..edbd1e3 --- /dev/null +++ b/docs/html/images/screens_support/screens-densities.png diff --git a/docs/html/images/screens_support/screens-ranges.png b/docs/html/images/screens_support/screens-ranges.png Binary files differindex dce6264..d8a0ffa 100644 --- a/docs/html/images/screens_support/screens-ranges.png +++ b/docs/html/images/screens_support/screens-ranges.png |
