cherrypick Change-Id: Ib2decf325271c50cac3202bad8c4bbbc40d233f2

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

Change-Id: Ib16d4ba81e4ff8ab798bcdfcfc4e086fedac5a1a

2 files changed, 71 insertions, 30 deletions

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