From ae5335b673be71fe96b8871ea376337d29e01e6e Mon Sep 17 00:00:00 2001 From: Scott Main Date: Wed, 3 Nov 2010 14:46:36 -0700 Subject: [PATCH] docs: add docs for xhdpi and xlarge screen support update screen ranges figure bug: 3099462 Change-Id: I4667f105df2ddc04a8e2b6c3ad06ec0ded2dccd2 --- docs/html/guide/practices/screens_support.jd | 474 +++++++++++------- .../topics/resources/providing-resources.jd | 10 +- .../images/screens_support/screens-ranges.png | Bin 8514 -> 21221 bytes 3 files changed, 297 insertions(+), 187 deletions(-) diff --git a/docs/html/guide/practices/screens_support.jd b/docs/html/guide/practices/screens_support.jd index 13b5e3aba50e2..7811d903b95f5 100644 --- a/docs/html/guide/practices/screens_support.jd +++ b/docs/html/guide/practices/screens_support.jd @@ -35,7 +35,9 @@ page.title=Supporting Multiple Screens
  1. <supports-screens>
  2. <uses-sdk>
    3. -
  3. Alternative Resources
    4. +
  4. +Providing Alternative Resources
  5. Android Virtual Devices
@@ -53,7 +55,7 @@ sizes and resolutions.

This document explains the screens-support features provided by the platform and how you use them in your application. By following the practices described here, you can easily create an application that displays properly on all -supported device screens and that you can deploy to any device as a single .apk. +supported device screens and that you can deploy to any device as a single {@code .apk}.

If you have already developed and published an application for Android 1.5 or @@ -63,10 +65,16 @@ and that are running Android 1.6 or later. In most cases, only minor adjustments are needed, however you should make sure to test your application on all supported screens.

+

Starting in Android 2.2, the platform includes support for extra high density screens +(xhdpi), and starting in Android 2.3, the platform includes support for extra large screens +(xlarge). If you've already followed the guidance in this document to support all other +screen types, you should consider providing additional support for xhdpi and +xlarge screens.

+

In particular, if you have an existing application that you would like to -make available for users of devices with small screens (such as QVGA), please -see Strategies for Legacy Applications for more -information about how to do that.

+make available on small screens (such as QVGA) or for which you would like to provide better support +for extra large screens, please see Strategies for Legacy Applications for +more information about how to do that.

Overview of Screens Support

@@ -82,11 +90,11 @@ screen-compatibility features.

Screen size
-
Actual physical size, measured as the screen's diagonal. +
Actual physical size, measured as the screen's diagonal. -

For simplicity, Android collapses all actual screen sizes into three -generalized sizes: large, normal, and small. Applications can provide custom -layouts for each of these three sizes — the platform transparently handles +

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.

Aspect ratio
@@ -110,22 +118,22 @@ 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.

+screen.

-

For simplicity, Android collapses all actual screen densities into three -generalized densities: high, medium, and low. Applications can provide custom -resources for each of these three densities — the platform handles the -scaling of the resources up or down to meet the actual screen density.

-
Density-independent pixel (dip)
+

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.

+
Density-independent pixel (dp)
A virtual pixel unit that applications can use in defining their UI, to -express layout dimensions or position in a density-independent way. +express layout dimensions or position in a density-independent way.

The density-independent pixel is equivalent to one physical pixel on a 160 dpi screen, the baseline density assumed by the platform (as described later in this document). At run time, the platform transparently handles any scaling of -the dip units needed, based on the actual density of the screen in use. The -conversion of dip units to screen pixels is simple: pixels = dips * -(density / 160). For example, on 240 dpi screen, 1 dip would equal 1.5 -physical pixels. Using dip units to define your application's UI is highly +the dp units needed, based on the actual density of the screen in use. The +conversion of dp units to screen pixels is simple: pixels = dps * +(density / 160). 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.

@@ -146,13 +154,19 @@ applications, the platform divides the range of actual supported screen sizes and resolutions into:

+

Note: The xhdpi density category was added in +Android 2.2 (API Level 8). The xlarge size category was added in Android 2.3 (API Level +9).

+

Applications can provide custom resources (primarily layouts) for any of the -three generalized sizes and can provide resources (primarily drawables such as -images) for any of the three generalized densities. Applications do not need to +four generalized sizes and can provide resources (primarily drawables such as +images) for any of the four generalized densities. Applications do not need to work with the actual physical size or density of the device screen. At run time, the platform handles the loading of the correct size or density resources, based on the generalized size or density of the current device screen, and adapts them @@ -177,8 +191,8 @@ its characteristics.

-

Figure 1. -Illustration of how the Android platform maps actual screen densities and sizes +

Figure 1. +Illustration of how the Android platform maps actual screen densities and sizes to generalized density and size configurations.

Although the platform lets your application provide layouts and resources for @@ -213,6 +227,9 @@ sizes and densities of emulator skins included in the Android SDK.

High density (240), hdpi + + Extra high density (320), xhdpi + @@ -222,6 +239,7 @@ sizes and densities of emulator skins included in the Android SDK.

+ @@ -230,6 +248,7 @@ sizes and densities of emulator skins included in the Android SDK.

WQVGA400 (240x400)
WQVGA432 (240x432) HVGA (320x480) WVGA800 (480x800)
WVGA854 (480x854) + @@ -238,16 +257,27 @@ sizes and densities of emulator skins included in the Android SDK.

WVGA800* (480x800)
WVGA854* (480x854) + - * To emulate this - configuration, specify a custom density of 160 when + + Extra Large screen + + + + + + + + * To emulate this + configuration, specify a custom density of 160 when creating an AVD that uses a WVGA800 or WVGA854 skin. + -

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 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 Screen Sizes and Densities dashboard.

@@ -262,9 +292,9 @@ resources at run time is based on the alternative resources framework.

If you want to use size- or density-specific layouts or drawables in your application and you are not familiar with resource qualifiers or how the -platform uses them, please read +platform uses them, please read -Alternative Resources. +Providing Alternative Resources. @@ -277,19 +307,20 @@ to use them:

@@ -299,7 +330,7 @@ application, to ensure the best possible display on the current device screen:

    -
  1. Pre-scaling of resources (such as image assets) +
  2. Pre-scaling of resources (such as image assets)

    Based on the density of the current screen, the platform automatically loads any size- or density-specific resources from your application and displays @@ -344,18 +375,18 @@ lower-density screen, coordinates are scaled down.

    For more information, see the android:anyDensity attribute in Manifest attributes for screens support.

    3. -
    - -
    - -

    Publishing to Small Screen Devices

    +
    + +
    + +

    Publishing to Small Screen Devices

    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 test your application -on small screens and then upload an updated version that explicitly +on small screens and then upload an updated version that explicitly indicates support for small screens.

    -
    +
  3. Compatibility-mode display on larger screen-sizes @@ -374,7 +405,7 @@ of scaling the application, however, the application's 320x480 interface will be placed as a "postage stamp" in the larger 480x800 screen.

    For more information, see the android:anyDensity attribute in -Manifest elements for screens support and the +Manifest elements for screens support and the Screen-Compatibility Examples section.

@@ -415,7 +446,7 @@ does this in three ways: