Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

cherrypick Change-Id: Ib2decf325271c50cac3202bad8c4bbbc40d233f2

Browse Source 
docs: add tvdpi info
also resolve issue 5018379 with more info about how size resources are selected

Change-Id: Ib16d4ba81e4ff8ab798bcdfcfc4e086fedac5a1a
This commit is contained in:
Scott Main
2011-07-12 18:10:00 -07:00
parent 31675e4295
commit 44ec74db19
2 changed files with 71 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
docs/html/guide/practices/screens_support.jd
View File

@@ -444,7 +444,7 @@ provide special resources for different screen configurations.</p>
</tr>
<tr>
<td rowspan="5">Density</td>
<td rowspan="6">Density</td>
<td><code>ldpi</code></td>
<td>Resources for low-density (<em>ldpi</em>) screens (~120dpi).</td>
</tr>
@@ -466,7 +466,15 @@ 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><code>tvdpi</code></td>
<td>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&mdash;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.</td>
</tr>
<tr>
<td rowspan="2">Orientation</td>
<td><code>land</code></td>
@@ -521,6 +529,20 @@ configuration qualifiers (not just for screen configurations), see
<a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">
Providing Alternative Resources</a>.</p>
<p>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 <em>larger</em> 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 <a
href="{@docRoot}guide/topics/resources/providing-resources.html#BestMatch">How Android Finds the
Best-matching Resource</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.

75
docs/html/guide/topics/resources/providing-resources.jd
View File

@@ -444,30 +444,35 @@ indicates the current locale.</p>
</td>
<td>
<ul class="nolist">
<li>{@code small}: Screens based on the space available on a
low-density QVGA screen. Considering a portrait HVGA display, this has
the same available width but less height&mdash;it is 3:4 vs. HVGA's
2:3 aspect ratio. The minimum layout size for this screen configuration
<li>{@code small}: Screens that are of similar size to a
low-density QVGA screen. The minimum layout size for a small screen
is approximately 320x426 dp units. Examples are QVGA low density and VGA high
density.</li>
<li>{@code normal}: Screens based on the traditional
medium-density HVGA screen. A screen is considered to be normal if it is
at least this size (independent of density) and not larger. The minimum
layout size for this screen configuration is approximately 320x470 dp units. Examples
<li>{@code normal}: Screens that are of similar size to a
medium-density HVGA screen. The minimum
layout size for a normal screen is approximately 320x470 dp units. Examples
of such screens a WQVGA low density, HVGA medium density, WVGA
high density.</li>
<li>{@code large}: Screens based on the space available on a
medium-density VGA screen. Such a screen has significantly more
available space in both width and height than an HVGA display.
The minimum layout size for this screen configuration is approximately 480x640 dp units.
<li>{@code large}: Screens that are of similar size to a
medium-density VGA screen.
The minimum layout size for a large screen is approximately 480x640 dp units.
Examples are VGA and WVGA medium density screens.</li>
<li>{@code xlarge}: Screens that are considerably larger than the traditional
medium-density HVGA screen. The minimum layout size for this screen configuration
medium-density HVGA screen. The minimum layout size for an xlarge screen
is approximately 720x960 dp units. In most cases, devices with extra large
screens would be too large to carry in a pocket and would most likely
be tablet-style devices. <em>Added in API level 9.</em></li>
</ul>
<p class="note"><strong>Note:</strong> Using a size qualifier does not imply that the
resources are <em>only</em> 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 <a href="#BestMatch">best match</a>.</p>
<p class="caution"><strong>Caution:</strong> If all your resources use a size qualifier that
is <em>larger</em> than the current screen, the system will <strong>not</strong> 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).</p>
<p><em>Added in API level 4.</em></p>
<p>See <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple
Screens</a> for more information.</p>
<p>Also see the {@link android.content.res.Configuration#screenLayout} configuration field,
@@ -557,7 +562,8 @@ application during runtime.</p>
<code>mdpi</code><br/>
<code>hdpi</code><br/>
<code>xhdpi</code><br/>
<code>nodpi</code>
<code>nodpi</code><br/>
<code>tvdpi</code>
</td>
<td>
<ul class="nolist">
@@ -569,21 +575,23 @@ application during runtime.</p>
Level 8</em></li>
<li>{@code nodpi}: This can be used for bitmap resources that you do not want to be scaled
to match the device density.</li>
<li>{@code tvdpi}: 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&mdash;providing mdpi and hdpi resources is sufficient for most apps and
the system will scale them as appropriate. This qualifier was introduced with API level 13.</li>
</ul>
<p><em>Added in API level 4.</em></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
matching directory</a> (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.
</p>
<p>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.</p>
<p>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.</p>
<p class="note"><strong>Note:</strong> Using a density qualifier does not imply that the
resources are <em>only</em> 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 <a href="#BestMatch">best match</a>.</p>
<p>See <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple
Screens</a> for more information about how to handle screen sizes and how Android might scale
your bitmaps.</p>
Screens</a> for more information about how to handle different screen densities and how Android
might scale your bitmaps to fit the current density.</p>
</td>
</tr>
<tr id="TouchscreenQualifier">
@@ -993,7 +1001,10 @@ Primary text input method = <code>12key</code>
</p>
<p>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:</p>
drawables from {@code drawable-en-port}.</p>
<p>The system arrives at its decision for which resources to use with the following
logic:</p>
<div class="figure" style="width:280px">
@@ -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 <em>without</em> the language qualifier is still included).</p>
<p>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 <em>larger</em> than the current screen, the system will
<strong>not</strong> 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).</p>
<p class="note"><strong>Note:</strong> The <em>precedence</em> of the qualifier (in <a
href="#table2">table 2</a>) is more important
than the number of qualifiers that exactly match the device. For example, in step 4 above, the last