From 44ec74db191f88dc22143b55cacc262bc8fc3cd2 Mon Sep 17 00:00:00 2001 From: Scott Main Date: Tue, 12 Jul 2011 18:10:00 -0700 Subject: cherrypick Change-Id: Ib2decf325271c50cac3202bad8c4bbbc40d233f2 docs: add tvdpi info also resolve issue 5018379 with more info about how size resources are selected Change-Id: Ib16d4ba81e4ff8ab798bcdfcfc4e086fedac5a1a --- docs/html/guide/practices/screens_support.jd | 26 +++++++- .../guide/topics/resources/providing-resources.jd | 75 ++++++++++++++-------- 2 files changed, 71 insertions(+), 30 deletions(-) (limited to 'docs') diff --git a/docs/html/guide/practices/screens_support.jd b/docs/html/guide/practices/screens_support.jd index c5b9a4b..42000c4 100644 --- a/docs/html/guide/practices/screens_support.jd +++ b/docs/html/guide/practices/screens_support.jd @@ -444,7 +444,7 @@ provide special resources for different screen configurations.

-Density +Density ldpi Resources for low-density (ldpi) screens (~120dpi). @@ -466,7 +466,15 @@ density.) 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. - + +tvdpi +Resources for screens somewhere between mdpi and hdpi; approximately 213dpi. This is not +considered a "primary" density group. It is mostly intended for televisions and most apps shouldn't +need it—providing mdpi and hdpi resources is sufficient for most apps and the system will +scale them as appropriate. If you find it necessary to provide tvdpi resources, you should size them +at a factor of 1.33*mdpi. For example, a 100px x 100px image for mdpi screens should be 133px x +133px for tvdpi. + Orientation land @@ -521,6 +529,20 @@ configuration qualifiers (not just for screen configurations), see Providing Alternative Resources.

+

Be aware that, when the Android system picks which resources to use at runtime, it uses +certain logic to determing the "best matching" resources. That is, the qualifiers you use don't +have to exactly match the current screen configuration in all cases in order for the system to +use them. Specifically, when selecting resources based on the size qualifiers, the system will +use resources designed for a screen smaller than the current screen if there are no resources +that better match (for example, a large-size screen will use normal-size screen resources if +necessary). However, if the only available resources are larger than the current screen, +the system will not use them and your application will crash if no other resources match the device +configuration (for example, if all layout resources are tagged with the {@code xlarge} qualifier, +but the device is a normal-size screen). For more information about how the system selects +resources, read How Android Finds the +Best-matching Resource.

+

Tip: 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. diff --git a/docs/html/guide/topics/resources/providing-resources.jd b/docs/html/guide/topics/resources/providing-resources.jd index ceff851..9dcda39 100644 --- a/docs/html/guide/topics/resources/providing-resources.jd +++ b/docs/html/guide/topics/resources/providing-resources.jd @@ -444,30 +444,35 @@ indicates the current locale.

+

Note: Using a size qualifier does not imply that the +resources are only for screens of that size. If you do not provide alternative +resources with qualifiers that better match the current device configuration, the system may use +whichever resources are the best match.

+

Caution: If all your resources use a size qualifier that +is larger than the current screen, the system will not use them and your +application will crash at runtime (for example, if all layout resources are tagged with the {@code +xlarge} qualifier, but the device is a normal-size screen).

Added in API level 4.

+

See Supporting Multiple Screens for more information.

Also see the {@link android.content.res.Configuration#screenLayout} configuration field, @@ -557,7 +562,8 @@ application during runtime.

mdpi
hdpi
xhdpi
- nodpi + nodpi
+ tvdpi -

Added in API level 4.

-

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.

-

When Android selects which resource files to use, - it handles screen density differently than the other qualifiers. - In step 1 of How Android finds the best - matching directory (below), screen density is always considered to - be a match. In step 4, if the qualifier being considered is screen - density, Android selects the best final match at that point, - without any need to move on to step 5. -

+

There is a 3:4:6:8 scaling ratio between the four primary densities (ignoring the +tvdpi density). So, a 9x9 bitmap in ldpi is 12x12 in mdpi, 18x18 in hdpi and 24x24 in xhdpi.

+

If you decide that your image resources don't look good enough on a television or +other certain devices and want to try tvdpi resources, the scaling factor is 1.33*mdpi. For +example, a 100px x 100px image for mdpi screens should be 133px x 133px for tvdpi.

+

Note: Using a density qualifier does not imply that the +resources are only for screens of that density. If you do not provide alternative +resources with qualifiers that better match the current device configuration, the system may use +whichever resources are the best match.

See Supporting Multiple -Screens for more information about how to handle screen sizes and how Android might scale -your bitmaps.

+Screens for more information about how to handle different screen densities and how Android +might scale your bitmaps to fit the current density.

@@ -993,7 +1001,10 @@ Primary text input method = 12key

By comparing the device configuration to the available alternative resources, Android selects -drawables from {@code drawable-en-port}. It arrives at this decision using the following logic:

+drawables from {@code drawable-en-port}.

+ +

The system arrives at its decision for which resources to use with the following +logic:

@@ -1069,6 +1080,14 @@ language is English ("en"), then any resource directory that has a language qual something other than English is never included in the pool of resources checked (though a resource directory without the language qualifier is still included).

+

When selecting resources based on the screen size qualifiers, the system will use resources +designed for a screen smaller than the current screen if there are no resources that better match +(for example, a large-size screen will use normal-size screen resources if necessary). However, if +the only available resources are larger than the current screen, the system will +not use them and your application will crash if no other resources match the device +configuration (for example, if all layout resources are tagged with the {@code xlarge} qualifier, +but the device is a normal-size screen).

+

Note: The precedence of the qualifier (in table 2) is more important than the number of qualifiers that exactly match the device. For example, in step 4 above, the last -- cgit v1.1