From ba944ccda3d61ccbe6061277fcc50c96fe2643f1 Mon Sep 17 00:00:00 2001 From: Dirk Dougherty Date: Thu, 23 Sep 2010 08:56:13 -0700 Subject: Doc change: update screens support table and remove outdated density/size metrics. Change-Id: I05895b09e2198379a078c12489a2098f84865f58 --- docs/html/guide/practices/design/responsiveness.jd | 60 +-- docs/html/guide/practices/screens_support.jd | 412 ++++++++++----------- .../html/images/screens_support/screens-ranges.png | Bin 0 -> 8514 bytes docs/html/resources/community-groups.jd | 2 +- 4 files changed, 236 insertions(+), 238 deletions(-) create mode 100644 docs/html/images/screens_support/screens-ranges.png diff --git a/docs/html/guide/practices/design/responsiveness.jd b/docs/html/guide/practices/design/responsiveness.jd index 8a4e7cf..9858e36 100644 --- a/docs/html/guide/practices/design/responsiveness.jd +++ b/docs/html/guide/practices/design/responsiveness.jd @@ -1,13 +1,31 @@ page.title=Designing for Responsiveness @jd:body -

It's possible to write code that wins every performance test in the world, but still sends users in a fiery rage when they try to use the application. These are the applications that aren't responsive enough — the ones that feel -sluggish, hang or freeze for significant periods, or take too long to process -input.

- -

In Android, the system guards against applications that are insufficiently responsive for a period of time by displaying a dialog to the user, called the Application Not Responding (ANR) dialog. The user can choose to let the application continue, but the user won't appreciate having to act on this dialog every time he or she uses your application. So it's important to design responsiveness into your application, so that the system never has cause to display an ANR to the user.

+
+Screenshot of ANR dialog box +

Figure 1. An ANR dialog displayed to the user.

+
-

Generally, the system displays an ANR if an application cannot respond to user input. For example, if an application blocks on some I/O operation (frequently a network access), then the main application thread won't be able to process incoming user input events. After a time, the system concludes that the application has hung, and displays the ANR to give the user the option to kill it. +

It's possible to write code that wins every performance test in the world, +but still sends users in a fiery rage when they try to use the application. +These are the applications that aren't responsive enough — the +ones that feel sluggish, hang or freeze for significant periods, or take too +long to process input.

+ +

In Android, the system guards against applications that are insufficiently +responsive for a period of time by displaying a dialog to the user, called the +Application Not Responding (ANR) dialog, shown at right in Figure 1. The user +can choose to let the application continue, but the user won't appreciate having +to act on this dialog every time he or she uses your application. It's critical +to design responsiveness into your application, so that the system never has +cause to display an ANR dialog to the user.

+ +

Generally, the system displays an ANR if an application cannot respond to +user input. For example, if an application blocks on some I/O operation +(frequently a network access), then the main application thread won't be able to +process incoming user input events. After a time, the system concludes that the +application is frozen, and displays the ANR to give the user the option to kill +it.

Similarly, if your application spends too much time building an elaborate in-memory structure, or perhaps computing the next move in a game, the system will @@ -15,31 +33,17 @@ conclude that your application has hung. It's always important to make sure these computations are efficient using the techniques above, but even the most efficient code still takes time to run.

-

In both of these cases, the fix is usually to create a child thread, and do +

In both of these cases, the recommended approach is to create a child thread and do most of your work there. This keeps the main thread (which drives the user -interface event loop) running, and prevents the system from concluding your code +interface event loop) running and prevents the system from concluding that your code has frozen. Since such threading usually is accomplished at the class level, you can think of responsiveness as a class problem. (Compare this with basic performance, which was described above as a method-level concern.)

-
-
-Screenshot of ANR dialog box -

An ANR dialog displayed to the user.

-
-
- -

This document discusses how the Android system determines whether an application is -not responding and provides guidelines for -ensuring that your application is responsive.

- -

This document covers these topics:

- +

This document describes how the Android system determines whether an +application is not responding and provides guidelines for ensuring that your +application stays responsive.

What Triggers ANR?

@@ -48,8 +52,10 @@ and Window Manager system services. Android will display the ANR dialog for a particular application when it detects one of the following conditions:

How to Avoid ANR

diff --git a/docs/html/guide/practices/screens_support.jd b/docs/html/guide/practices/screens_support.jd index 2863fb2..11ad1b8 100644 --- a/docs/html/guide/practices/screens_support.jd +++ b/docs/html/guide/practices/screens_support.jd @@ -131,57 +131,79 @@ screens.

-

Range of Screens Supported

+

Range of screens supported

-

Android 1.5 and earlier versions of the platform were designed to support a -single screen configuration — HVGA (320x480) resolution on a 3.2" screen. -Because the platform targeted just one screen, application developers could -write their applications specifically for that screen, without needing to worry -about how their applications would be displayed on other screens.

- -

Starting from Android 1.6, the platform adds support for multiple screen +

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 will run. This means that developers must design their -applications for proper display on a range of devices and screens.

+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.

-

To simplify the way application developers design their user interfaces for -multiple devices, and to allow more devices to participate without impacting +

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:

- -

Applications can provide custom resources (primarily layouts) for any of the -three generalized sizes, if needed, and they can also provide resources -(primarily drawables such as images) for any of the three 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.

- -

The table below lists some of the more common screens supported -by Android and illustrates how the platform maps them to generalized screen -configurations. Some devices use screens that are not specifically listed -in the table — the platform maps those to the same set generalized -screen configurations.

- -

Table 1. Examples of -device screens supported by Android.

- - +three generalized sizes and can provide resources (primarily drawables such as +images) for any of the three 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.

+ +

The generalized size/density configurations are arranged around a +baseline configuration that is assigned a size of normal and a density of +mdpi (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 normal and density +mdpi.

+ +

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 normal might offer screens that differ slightly +in actual size or aspect ratio. Similarly, devices that report a screen density +of hdpi 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.

+ + + +

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 +generalized size-density configurations, you do not necessarily need to do write +custom code or provide custom resources for each of the nine supported +configurations. The platform provides robust compatibility features, described +in the sections below, that can handle most of the work of rendering your +application on any device screen, provided that you've implemented your +application UI properly. For more information about how to implement a UI that +renders properly across device screens and platform versions, see +Best Practices for Screen Independence.

+ +

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.

+ +

Table 1. Screen +sizes and densities of emulator skins included in the Android SDK.

+ +
- + @@ -196,10 +218,7 @@ device screens supported by Android.

- @@ -208,74 +227,29 @@ device screens supported by Android.

- - - + + + - + - -
Low density (120), ldpi Small screen -
    -
  • QVGA (240x320), 2.6"-3.0" diagonal
    • -
+ 		QVGA (240x320) Normal screen -
    -
  • WQVGA (240x400), 3.2"-3.5" diagonal
    • -
  • FWQVGA (240x432), 3.5"-3.8" diagonal
    • -
- 		-
    -
  • HVGA (320x480), 3.0"-3.5" diagonal
    • -
- 		-
    -
  • WVGA (480x800), 3.3"-4.0" diagonal
    • -
  • FWVGA (480x854), 3.5"-4.0" diagonal
    • -
- 		WQVGA400 (240x400)
WQVGA432 (240x432)		HVGA (320x480)WVGA800 (480x800)
WVGA854 (480x854)
Large screen -
    -
  • WVGA (480x800), 4.8"-5.5" diagonal
    • -
  • FWVGA (480x854), 5.0"-5.8" diagonal
    • -
- 		WVGA800* (480x800)
WVGA854* (480x854)
- -

- -

As shown above, the various screen configurations are arranged around a -baseline screen that is assigned a size of "normal" and a density of -"medium". The HVGA screen is used as the baseline because all applications -written against Android 1.5 or earlier are (by definition) written for the HVGA -screen used on the T-Mobile G1 and similar devices.

- - - -

Although the platform currently supports the nine possible size-density -configurations listed in the table, you do not necessarily need to create custom -resources for each one of them. The platform provides robust compatibility -features, described in the sections below, that can handle most of the work of -rendering your application on the current device screen, provided that the UI is -properly implemented. For more information, see Best Practices for Screen Independence.

- - +low (ldpi) density screens in Android-powered devices available now, see the Screen Sizes and Densities dashboard.

+

How Android supports multiple screens

@@ -307,8 +281,8 @@ size- and density-specific resources, if needed. The qualifiers for size-specific resources are large, normal, and small, and those for density-specific resources are hdpi (high), mdpi (medium), and ldpi -(low). The qualifiers correspond to the generalized densities given in -Table 1, above. +(low). The qualifiers correspond to the generalized densities described in +Range of screens supported, above.
  • The platform also provides a <supports-screens> @@ -457,7 +431,7 @@ different.

    Figure 1. Examples of density independence on WVGA high +1em;">Figure 2. Examples of density independence on WVGA high density (left), HVGA medium density (center), and QVGA low density (right).

    @@ -479,7 +453,8 @@ whose attributes you can use to control the display of your application on different classes of device screens, as listed below. The smallScreens, normalScreens, and largeScreens attributes correspond to the generalized screen sizes -shown in Table 1, earlier in this document.

    +described in Range of screens supported, earlier in this +document.

    @@ -489,6 +464,12 @@ shown in Table 1, earlier in this document.

    + + + + + + + + + +
    Description + Default value,
    Android 1.5 and Lower +     		+ Default value,
    Android 1.6 and Higher +
    @@ -497,10 +478,10 @@ shown in Table 1, earlier in this document.

    		 Whether or not the application UI is designed for use on small screens — "true" if it is, and -"false" if not. See Default values for -attributes for information about the assumed value of this attribute, if not -declared. +"false" if not.

    		"false""true"
    @@ -509,8 +490,10 @@ declared. Whether or not the application UI is designed for use on normal screens — "true" if it is, and -"false" if not. The default value is "true". +"false" if not. The default value is always "true". "true""true"
    @@ -519,10 +502,10 @@ declared. Whether or not the application UI is designed for use on large screens — "true" if it is, and -"false" if not. See Default values for -attributes for information about the assumed value of this attribute, if not -declared. +"false" if not. "false""true"
    @@ -535,9 +518,13 @@ in different density environments — "true" if so, and
    • If set to "true", the platform disables its density-compatibility features for all screen densities — specifically, -the auto-scaling of absolute pixel units and math — and relies on the -application to use density-independent pixel units and/or to manage the -adaptation of pixel values according to density of the current screen.
      • +the auto-scaling of absolute pixel units (px) and math — and +relies on the application to use density-independent pixel units +(dp) 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 +"true".
    • If set to "false", the platform enables its density-compatibility features for all screen densities. In this case, the @@ -546,45 +533,73 @@ which it can layout and draw its UI as though against a medium-density screen (160). The platform then transparently auto-scales the application's pixel units and math as needed to match the actual device screen density.
    -

    See Default values for attributes for -information about the assumed value of this attribute, if not declared.

    +

    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.

    		"false""true"

    In general, when you declare a screen-size attribute (smallScreens, normalScreens, or -largeScreens) as "true", you are signaling to the platform that -your application wants to manage its UI by itself, for all screen sizes, without -the platform applying any size-compatibility behaviors (such as a virtual HVGA -display area). If you declare a screen-size attribute as "false", you are -signaling that your application is not designed for that screen size. The -effects are conditioned by the screen size that your application does not -support:

    - +largeScreens) as "true", 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 +"false", you are signaling that your application is not +designed for that screen size. In this case, the platform does apply +size-compatibility features, rendering the application in an HVGA baseline +display area. If the current screen is larger than normal size, the +platform renders the application in a virtual HVGA screen on the larger screen. +See Screen-Compatibility Examples for an +illustration of what an application looks like when displayed in a virtual HVGA +screen.

    + +

    In other words, setting a <supports-screens> attribute to +"false" tells the platform to enable it's compatibility features +when displaying the application on a screen of that size or any larger +size, if also disallowed. Otherwise, the platform gives the application a +normal display area that can use the full device screen area, if +appropriate.

    + +

    Android Market also makes use of the <supports-screens> +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.

    + +

    Here are some examples:

    + -

    If you declare the android:anyDensity attribute as "true", you -are signaling to the platform that your application wants to manage its UI by -itself, for all screen densities, using the actual screen dimensions and pixels. -In this case, the application must ensure that it declares its UI dimensions -using density-independent pixels and scales any actual pixel values or math by -the scaling factor available from -{@link android.util.DisplayMetrics#density android.util.DisplayMetrics.density}.

    +

    If you declare the android:anyDensity attribute as +"true", 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 (dp) and scales any absolute pixel +values (px) or math by the scaling factor available from {@link +android.util.DisplayMetrics#density android.util.DisplayMetrics.density}. See Converting from dips to pixels for an example.

    Note that the setting of the android:anyDensity attribute does not affect the platform's pre-scaling of drawable resources, such as bitmaps and @@ -594,22 +609,22 @@ nine-patch images, which always takes place by default.

    normal, and small screens in any densities.

    <manifest xmlns:android="http://schemas.android.com/apk/res/android">
-
+  ...
   <supports-screens
           android:largeScreens="true"
           android:normalScreens="true"
           android:smallScreens="true"
-          android:resizable="true"
           android:anyDensity="true" />
-  </manifest>
+  ...
+</manifest>
    - +

    Default values for attributes

    The default values for the <supports-screens> attributes -differs, depending on the the value of the +differ, depending on the the value of the android:minSdkVersion attribute in the application's manifest, as well as on the value of android:targetSdkVersion, if declared:

    @@ -618,19 +633,20 @@ the value of android:targetSdkVersion, if declared: