Merge "docs: add docs for xhdpi and xlarge screen support update screen ranges figure bug: 3099462" into gingerbread

docs/html/guide/practices/screens_support.jd

@@ -35,7 +35,9 @@ page.title=Supporting Multiple Screens
   <ol>
     <li><code><a href="{@docRoot}guide/topics/manifest/supports-screens-element.html">&lt;supports-screens&gt;</a></code></li>
     <li><code><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">&lt;uses-sdk&gt;</a></code></li>
-    <li><a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">Alternative Resources</a></li>
+    <li><a
+href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">
+Providing Alternative Resources</a></li>
     <li><a href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a></li>
   </ol>
 
@@ -53,7 +55,7 @@ sizes and resolutions. </p>
 <p>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}.
 </p>
 
 <p>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 <a href="#testing">test your
 application</a> on all supported screens. </p>
 
+<p>Starting in Android 2.2, the platform includes support for extra high density screens
+(<em>xhdpi</em>), and starting in Android 2.3, the platform includes support for extra large screens
+(<em>xlarge</em>). If you've already followed the guidance in this document to support all other
+screen types, you should consider providing additional support for <em>xhdpi</em> and
+<em>xlarge</em> screens.</p>
+
 <p>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
+make available on small screens (such as QVGA) or for which you would like to provide better support
-see <a href="#strategies">Strategies for Legacy Applications</a> for more
+for extra large screens, please see <a href="#strategies">Strategies for Legacy Applications</a> for
-information about how to do that. </p>
+more information about how to do that. </p>
 
 
 <h2 id="overview">Overview of Screens Support</h2>
@@ -84,9 +92,9 @@ screen-compatibility features.</p>
 <dt><em>Screen size</em></dt>
   <dd>Actual physical size, measured as the screen's diagonal.
 
-  <p>For simplicity, Android collapses all actual screen sizes into three
+  <p>For simplicity, Android collapses all actual screen sizes into four
-generalized sizes: large, normal, and small. Applications can provide custom
+generalized sizes: small, normal, large, and extra large. Applications can provide custom
-layouts for each of these three sizes &mdash; the platform transparently handles
+layouts for each of these four sizes &mdash; the platform transparently handles
 the rendering of the layouts at the actual screen size.</p></dd>
 
 <dt><em>Aspect ratio</em></dt>
@@ -110,22 +118,22 @@ sometimes significantly more &mdash; 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. </p>
+screen.</p>
 
-  <p>For simplicity, Android collapses all actual screen densities into three
+  <p>For simplicity, Android collapses all actual screen densities into four
-generalized densities: high, medium, and low. Applications can provide custom
+generalized densities: low, medium, large, and extra large. Applications can provide custom
-resources for each of these three densities &mdash; the platform handles the
+resources for each of these densities &mdash; the platform handles any necessary
-scaling of the resources up or down to meet the actual screen density. </p></dd>
+scaling of the resources up or down to meet the specific screen density. </p></dd>
-<dt><em>Density-independent pixel (dip)</em></dt>
+<dt><em>Density-independent pixel (dp)</em></dt>
   <dd>A virtual pixel unit that applications can use in defining their UI, to
 express layout dimensions or position in a density-independent way.
   <p>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
+the dp units needed, based on the actual density of the screen in use. The
-conversion of dip units to screen pixels is simple: <code>pixels = dips *
+conversion of dp units to screen pixels is simple: <nobr><code>pixels = dps *
-(density / 160)</code>. For example, on 240 dpi screen, 1 dip would equal 1.5
+(density / 160)</code></nobr>. For example, on 240 dpi screen, 1 dp would equal 1.5
-physical pixels. Using dip units to define your application's UI is highly
+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. </p></dd>
 </dl>
@@ -146,13 +154,19 @@ applications, the platform divides the range of actual supported screen sizes
 and resolutions into:</p>
 
 <ul>
-<li>A set of three generalized sizes: <em>large</em>, <em>normal</em>, and <em>small</em>, and </li>
+<li>A set of four generalized sizes: <em>small</em>, <em>normal</em>, <em>large</em>,
-<li>A set of three generalized densities:  <em>hdpi</em> (high), <em>mdpi</em> (medium), and <em>ldpi</em> (low)
+and <em>xlarge</em></em>
+<li>A set of four generalized densities: <em>ldpi</em> (low), <em>mdpi</em> (medium),
+<em>hdpi</em> (high), and <em>xhdpi</em> (extra high)
 </ul>
 
+<p class="note"><strong>Note:</strong> The <code>xhdpi</code> density category was added in
+Android 2.2 (API Level 8). The <em>xlarge</em> size category was added in Android 2.3 (API Level
+9).</p>
+
 <p>Applications can provide custom resources (primarily layouts) for any of the
-three generalized sizes and can provide resources (primarily drawables such as
+four generalized sizes and can provide resources (primarily drawables such as
-images) for any of the three generalized densities. Applications do not need to
+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
@@ -213,6 +227,9 @@ sizes and densities of emulator skins included in the Android SDK.</p>
       <td  style="background-color:#f3f3f3">
         <nobr>High density (240), <em>hdpi</em><nobr>
       </td>
+      <td  style="background-color:#f3f3f3">
+        <nobr>Extra high density (320), <em>xhdpi</em><nobr>
+      </td>
     </tr>
     <tr>
       <td  style="background-color:#f3f3f3">
@@ -222,6 +239,7 @@ sizes and densities of emulator skins included in the Android SDK.</p>
       </td>
       <td></td>
       <td></td>
+      <td></td>
     </tr>
     <tr>
       <td style="background-color:#f3f3f3">
@@ -230,6 +248,7 @@ sizes and densities of emulator skins included in the Android SDK.</p>
       <td style="font-size:.9em;">WQVGA400 (240x400)<br>WQVGA432 (240x432)</td>
       <td style="font-size:.9em;">HVGA (320x480)</td>
       <td style="font-size:.9em;">WVGA800 (480x800)<br>WVGA854 (480x854)</td>
+      <td style="font-size:.9em;"></td>
     </tr>
     <tr>
       <td style="background-color:#f3f3f3">
@@ -238,12 +257,23 @@ sizes and densities of emulator skins included in the Android SDK.</p>
       <td></td>
       <td style="font-size:.9em;">WVGA800* (480x800)<br>WVGA854* (480x854)</td>
       <td></td>
+      <td></td>
+    </tr>
+    <tr>
+      <td style="background-color:#f3f3f3">
+        <em>Extra Large</em> screen
+      </td>
+      <td></td>
+      <td></td>
+      <td></td>
+      <td></td>
     </tr>
     <tr>
       <td colspan="4" style="border:none;font-size:90%;">* To emulate this
         configuration, specify a custom density of 160 when
         creating an AVD that uses a WVGA800 or WVGA854 skin.
       </td>
+    </tr>
 </table>
 
 <p>For an overview of the relative numbers of high (hdpi), medium (mdpi), and
@@ -264,7 +294,7 @@ resources at run time is based on the alternative resources framework.
 application and you are not familiar with resource qualifiers or how the
 platform uses them, please read
 <a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">
-Alternative Resources</a>.
+Providing Alternative Resources</a>.
 </div>
 </div>
 
@@ -278,18 +308,19 @@ to use them:</p>
 <ul>
   <li>The platform supports a set of resource qualifiers that let you provide
 size- and density-specific resources, if needed. The qualifiers for
-size-specific resources are <code>large</code>, <code>normal</code>, and
+size-specific resources are <code>small</code>, <code>normal</code>, <code>large</code>, and
-<code>small</code>, and those for density-specific resources are
+<code>xlarge</code>. Those for density-specific resources are <code>ldpi</code>
-<code>hdpi</code> (high), <code>mdpi</code> (medium), and <code>ldpi</code>
+(low), <code>mdpi</code> (medium), <code>hdpi</code> (high), and <code>xhdpi</code> (extra high).
-(low). The qualifiers correspond to the generalized densities described in 
+The qualifiers correspond to the generalized densities described in
 <a href="#range">Range of screens supported</a>, above.</li>
   <li>The platform also provides a
 <a href="{@docRoot}guide/topics/manifest/supports-screens-element.html">
 <code>&lt;supports-screens&gt;</code></a>
 manifest element, whose attributes
-<code>android:largeScreens</code>, <code>android:normalScreens</code>, and
+<code>android:smallScreens</code>, <code>android:normalScreens</code>,
-<code>android:smallScreens</code> let you specify what generalized screen sizes
+<code>android:largeScreens</code>, and <code>android:xlargeScreens</code> let you specify what
-your application supports. A fourth attribute, <code>android:anyDensity</code>,
+generalized screen sizes
+your application supports. Another attribute, <code>android:anyDensity</code>,
 lets you indicate whether or not your application includes built-in support for
 multiple densities.</li>
 </ul>
@@ -415,7 +446,7 @@ does this in three ways: </p>
 <ul>
 <li>Through pre-scaling of drawable resources (scaled at resource loading
 time)</li>
-<li>Through auto-scaling of density-independent pixel (dip) values used in
+<li>Through auto-scaling of density-independent pixel (dp) values used in
 layouts</li>
 <li>Through auto-scaling of absolute pixel values used in the application (only
 needed if the application has set <code>android:anyDensity="false"</code> in its
@@ -437,12 +468,12 @@ density (left), HVGA medium density (center), and QVGA low density (right). </p>
 
 <p>In most cases, you can take advantage of density independence in your
 application simply by making sure that your layouts specify all dimension values
-in density-independent pixels (<code>dip</code> or <code>dp</code>) or
+in density-independent pixels (<code>dp</code> or <code>dp</code>) or
 scale-independent pixels (<code>sip</code> or <code>sp</code>, for text only).
 If you are using absolute pixel values in the application and manifest includes
 <a href="#attrs"><code>android:anyDensity="true"</code></a>, you will also need
-to scale the pixel values. See <a href="#dips-pels">Converting from dips to
+to scale the pixel values. See <a href="#dips-pels">Converting dp units to
-pixels</a> for more information. </p> 
+pixel units</a> for more information. </p>
 
 
 <h3 id="attrs">Manifest attributes for screens support</h3>
@@ -451,11 +482,22 @@ pixels</a> for more information. </p>
 <a href="{@docRoot}guide/topics/manifest/supports-screens-element.html"><code>&lt;supports-screens&gt;</code></a>,
 whose attributes you can use to control the
 display of your application on different classes of device screens, as listed
-below. The <code>smallScreens</code>, <code>normalScreens</code>, and
+in table 2. The <code>smallScreens</code>, <code>normalScreens</code>, <code>largeScreens</code> and
-<code>largeScreens</code> attributes correspond to the generalized screen sizes
+<code>xlargeScreens</code> attributes correspond to the generalized screen sizes
 described in <a href="#range">Range of screens supported</a>, earlier in this
-document.</p>
+document. Notice that the default values for each attribute vary, depending
+on your minimum and targeted platform, as indicated in the <a
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code
+android:minSdkVersion}</a> and <a
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code
+android:targetSdkVersion}</a> attributes of your <a
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code &lt;uses-sdk&gt;}</a>
+manifest element.</p>
 
+<p class="table-caption" id="table2"><strong>Table 2.</strong> Summary of attributes for the <a
+href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
+&lt;supports-screens&gt;}</a> manifest element, including default values based on platform
+version.</p>
     <table id="vrr8">
       <tr>
         <th>
@@ -465,10 +507,12 @@ document.</p>
           Description
         </th>
         <th>
-          Default value,<br><nobr>Android 1.5 and Lower</nobr>
+          Default value, when<br><nobr><code>minSdkVersion</code> or</nobr>
+<code>targetSdkVersion</code> is 4 or lower
         </th>
         <th>
-          Default value,<br><nobr>Android 1.6 and Higher</nobr>
+          Default value, when<br><nobr><code>minSdkVersion</code> or</nobr>
+<code>targetSdkVersion</code> is 5 or higher
         </th>
       </tr>
       <tr>
@@ -538,13 +582,48 @@ It does not affect size-compatibility features such as display on a virtual
 baseline screen.</p>
         </td>
 <td>"<code>false</code>"</td>
+<td>"<code>true</code>"</td>
+      </tr>
+      <tr>
+        <td colspan="4"><strong>Note:</strong> Android 2.3 (API Level 9) introduced a new
+attribute for the <code>&lt;supports-screens&gt;</code> element: <code>xlargeScreens</code>, shown
+below. It works the same as the other screen attributes above, but, if neither your
+<code>minSdkVersion</code> or <code>targetSdkVersion</code> are set to "9", the default value is
+"false" when your application is installed on a device running Android 2.3.</td>
+      </tr>
+      <tr>
+        <th>
+          Attribute
+        </th>
+        <th >
+          Description
+        </th>
+        <th>
+          Default value, when<br><nobr><code>minSdkVersion</code> or</nobr>
+<code>targetSdkVersion</code> is 8 or lower
+        </th>
+        <th>
+          Default value, when<br><nobr><code>minSdkVersion</code> or</nobr>
+<code>targetSdkVersion</code> is 9 or higher
+        </th>
+      </tr>
+      <tr>
+        <td>
+          <code>android:xlargeScreens</code>
+        </td>
+        <td>
+           Whether or not the application UI is designed for use on
+<em>xlarge</em> screens &mdash; "<code>true</code>" if it is, and
+"<code>false</code>" if not.
+        </td>
+<td>"<code>false</code>"</td>
 <td>"<code>true</code>"</td>
       </tr>
     </table>
 
 <p>In general, when you declare a screen-size attribute
-(<code>smallScreens</code>, <code>normalScreens</code>, or
+(<code>smallScreens</code>, <code>normalScreens</code>, <code>largeScreens</code>, or
-<code>largeScreens</code>) as "<code>true</code>", you are signaling to the
+<code>xlargeScreens</code>) as "<code>true</code>", 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
@@ -577,16 +656,20 @@ features for applications.</p>
 
 <ul>
     <li>Assume that you declare <code>smallScreens="false" normalScreens="true"
-largeScreens="false" </code> in your application's manifest. <p>Although the
+largeScreens="false" xlargeScreens="false"</code> in your application's manifest. <p>Although the
-application is not designed for display on large screens, the platform can still
+application is not designed for display on large or extra large screens, the platform can still
-run it successfully in <a href="#compatibility-examples">size-compatibility
+run it successfully in <a href="#compatibility-examples">screen-compatibility
-mode</a>. Android Market does not filter the application from devices
+mode</a>. Android Market shows the application to devices with
-<em>normal</em> and <em>large</em> size screens, but does filter it from
+<em>normal</em>, <em>large</em>, and <em>xlarge</em> size screens, but does filter it from
-<em>small</em> size screens, since the application provides no screen support at
+<em>small</em> size screens, because the application provides no screen support at
-<em>small</em> size (and there is no smaller size).</p></li>
+<em>small</em> size. Android's <a href="#compatibility-examples">screen-compatibility
+mode</a> mode does not provide support for screens that are smaller than those the
+application supports&mdash;it only provides support for screens that are larger. Thus,
+although the application declares "false" for <em>large</em> and <em>xlarge</em> screens,
+the application still functions, but runs in compatibility mode.</p></li>
 
     <li>Assume that you declare <code>smallScreens="false" normalScreens="false"
-largeScreens="true"</code> in your application's manifest. <p>Android Market
+largeScreens="true" xlargeScreens="true"</code> in your application's manifest. <p>Android Market
 filters the application from users of devices with <em>small</em> and
 <em>normal</em> size screens. In effect, this prevents such users from
 installing the application.</p></li>
@@ -599,23 +682,24 @@ application must ensure that it declares its UI dimensions using
 density-independent pixels (<code>dp</code>) and scales any absolute pixel
 values (<code>px</code>) or math by the scaling factor available from {@link
 android.util.DisplayMetrics#density android.util.DisplayMetrics.density}. See <a
-href="#dips-pels">Converting from dips to pixels</a> for an example.</p>
+href="#dips-pels">Converting dp units to pixel units</a> for an example.</p>
 
 <p>Note that the setting of the <code>android:anyDensity</code> attribute does
 not affect the platform's pre-scaling of drawable resources, such as bitmaps and
 nine-patch images, which always takes place by default. </p>
 
-<p>The following example shows a manifest that declares support for large,
+<p>The following example shows a manifest that declares support for small, normal, large, and
-normal, and small screens in any densities.</p>
+ xlarge screens in any density.</p>
 
-<pre>&lt;manifest xmlns:android="http://schemas.android.com/apk/res/android"&gt;
+<pre>
+&lt;manifest xmlns:android="http://schemas.android.com/apk/res/android"&gt;
     ...
     &lt;supports-screens
-  &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; android:largeScreens="true"
+        android:smallScreens="true"
-  &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; android:normalScreens="true"
+        android:normalScreens="true"
-  &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; android:smallScreens="true"
+        android:largeScreens="true"
-  &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; android:anyDensity="true" /&gt;
+        android:xlargeScreens="true"
-  ...
+        android:anyDensity="true" /&gt;
 &lt;/manifest&gt;
 </pre>
 <!--  &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; android:resizeable="true" -->
@@ -627,33 +711,22 @@ normal, and small screens in any densities.</p>
 differ, depending on the the value of the
 <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code>android:minSdkVersion</code></a>
  attribute in the application's manifest, as well as on
-the value of <code>android:targetSdkVersion</code>, if declared:</p>
+the value of <a
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code
+android:targetSdkVersion}</a>, if declared.</p>
 
-<div>
+<p>Above, <a href="#table2">table 2</a> indicates the default values for each attribute, based on
-  <ul>
+the values you provide for the <a
-    <li>
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code
-      If <code>android:minSdkVersion</code> or
+android:minSdkVersion}</a> and <a
-<code>android:targetSdkVersion</code> is "4" (Android 1.6) or higher, the
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code
-default value for everything is "<code>true</code>". If your application uses
+android:targetSdkVersion}</a>, in the <a
-APIs introduced in Android 1.6 or higher, but does not support specific screen
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code &lt;uses-sdk&gt;}</a>
-densities and/or screen sizes, you need to explicitly set the appropriate
+element.</p>
-attributes to "<code>false</code>".
+
-    </li>
+<p class="note"><strong>Note:</strong> If your application uses APIs introduced in Android 1.6 or
-    <li>
+higher, but does not support specific screen densities and/or screen sizes, you need to explicitly
-      If <code>android:minSdkVersion</code> is declared with a value of "3"
+set the appropriate attributes to "<code>false</code>" (because most are "true", by default).</p>
-(Android 1.5) or lower <em>and</em> a <code>android:targetSdkVersion</code>
-attribute is <em>not</em> declared with a value of "4" or higher, the default
-value for all attributes except <code>android:normalScreens</code> is
-"<code>false</code>". If you are primarily targeting pre-Android 1.6 platforms
-but also want to support other densities/screen sizes, you need to explicitly
-set the appropriate attributes to "<code>true</code>".
-    </li>
-    <li>
-      Note that <code>android:normalScreens</code> always defaults to
-<code>true</code>.
-    </li>
-  </ul>
-</div>
 
 
 <h3 id="qualifiers">Resource directory qualifiers for screen size and density</h3>
@@ -673,7 +746,7 @@ of Screens Supported</a>, earlier in this document.</p>
 </tr>
 
 <tr>
-  <td rowspan="3">Size</td>
+  <td rowspan="4">Size</td>
   <td><code>small</code></td>
   <td>Resources designed for <em>small</em> size screens.</td>
 </tr>
@@ -683,11 +756,15 @@ of Screens Supported</a>, earlier in this document.</p>
 </tr>
 <tr>
 <td><code>large</code></td>
-<td>Resources for <em>large</em> size screens.</td>
+<td>Resources designed for <em>large</em> size screens.</td>
+</tr>
+<tr>
+<td><code>xlarge</code></td>
+<td>Resources designed for <em>extra large</em> size screens.</td>
 </tr>
 
 <tr>
-<td rowspan="4">Density</td>
+<td rowspan="5">Density</td>
 <td><code>ldpi</code></td>
 <td>Resources designed for low-density (<em>ldpi</em>) screens.</td>
 </tr>
@@ -700,6 +777,10 @@ of Screens Supported</a>, earlier in this document.</p>
 <td>Resources designed for high-density (<em>hdpi</em>) screens.</td>
 </tr>
 <tr>
+<td><code>xhdpi</code></td>
+<td>Resources designed for extra high-density (<em>xhdpi</em>) screens.</td>
+</tr>
+<tr>
 <td><code>nodpi</code></td>
 <td>Density-independent resources. The platform does not auto-scale resources
 tagged with this qualifier, regardless of the current screen's density.</td>
@@ -739,16 +820,19 @@ can display significantly more information than a normal screen size.
 </p>
 
 <p>Here is an example of the resource directory structure of an application that
-supports low and high density, and employs different layout schemes.</p>
+employs different layout schemes for different screen sizes and supports low and high density
+screens.</p>
 
-<pre>res/layout/my_layout.xml            // layout for normal screen size
+<pre>
+res/layout/my_layout.xml            // layout for normal screen size
 res/layout-small/my_layout.xml      // layout for small screen size
 res/layout-large/my_layout.xml      // layout for large screen size
 res/layout-large-land/my_layout.xml // layout for large screen size in landscape mode
+res/layout-xlarge/my_layout.xml     // layout for extra large screen size
 
-res/drawable-ldpi/my_icon.png       // icon image for low density
+res/drawable-lhdpi/my_icon.png      // image for low density
-res/drawable-mdpi/dpi/my_icon.png   // icon for medium density
+res/drawable-mdpi/dpi/my_icon.png   // image for medium density
-res/drawable-hdpi/my_icon.png       // icon image for high density
+res/drawable-hdpi/my_icon.png       // image for high density
 
 res/drawable-nodpi/composite.xml    // density independent resource
 </pre>
@@ -756,7 +840,7 @@ res/drawable-nodpi/composite.xml    // density independent resource
 <p>For more information about how to use resource qualifiers or how the platform
 selects them, please read
 <a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">
-Alternative Resources</a>.</p>
+Providing Alternative Resources</a>.</p>
 
 
 <h2 id="screen-independence">Best practices for Screen Independence</h2>
@@ -771,10 +855,11 @@ different screens. Here is a quick checklist:</p>
 
 <ol>
   <li>
-    Prefer wrap_content, fill_parent and the dip unit to px in XML layout files
+   Use {@code wrap_content}, {@code fill_parent}, or the {@code dp} unit (instead of {@code px}),
+when specifying dimensions in an XML layout file
   </li>
   <li>
-    Avoid AbsoluteLayout
+    Do not use {@code AbsoluteLayout}
   </li>
   <li>
     Do not use hard coded pixel values in your code
@@ -784,19 +869,19 @@ different screens. Here is a quick checklist:</p>
   </li>
 </ol>
 
-<h3 id="use-relative">1. Prefer wrap_content, fill_parent and the dip unit to
+<h3 id="use-relative">1. Use wrap_content, fill_parent, or the dp unit, instead of
 absolute pixels<br> </h3>
 
 <p>When defining the <code>layout_width</code> and <code>layout_height</code> of
 views in an XML layout file, using <code>wrap_content</code>,
-<code>fill_parent</code> or the <code>dip</code> will guarantee that the view is
+<code>fill_parent</code> or the <code>dp</code> will guarantee that the view is
 given an appropriate size on the current device screen. For instance, a view
-with a <code>layout_width="100dip"</code> will measure 100 pixels wide on an
+with a <code>layout_width="100dp"</code> will measure 100 pixels wide on an
 HVGA@160 density display and 150 pixels on a WVGA@240 density display, but the
 view will occupy approximately the same physical space. </p>
 
 <p>Similarly, you should prefer the <code>sp</code> (scale-independent pixel,
-the scale factor depends on a user setting) or <code>dip</code> (if you don't
+the scale factor depends on a user setting) or <code>dp</code> (if you don't
 want to allow the user to scale the text) to define font sizes.</p>
 
 <h3 id="avoid-absolute">2. Avoid AbsoluteLayout </h3>
@@ -822,9 +907,9 @@ code in pixels. For instance, if <code>myView.getWidth()</code> returns 10, the
 view is 10 pixels wide. In some cases, you may need to scale the pixel values
 that you use in your code. The sections below provide more information. </p>
 
-<h4 id="dips-pels">Converting from dips to pixels</h4>
+<h4 id="dips-pels">Converting dp units to pixel units</h4>
 
-<p>In some cases, you will need to express dimensions in <code>dip</code> and
+<p>In some cases, you will need to express dimensions in <code>dp</code> and
 then convert them to pixels. Imagine an application in which a scroll gesture is
 recognized after the user's finger has moved by at least 16 pixels. On a
 baseline screen, the user will have to move his finger by 16 pixels / 160
@@ -832,22 +917,22 @@ dpi = 1/10th of an inch (or 2.5 mm) before the gesture is recognized. On a
 device with a high (240) density display, the user will move his finger by only
 16 pixels / 240 dpi = 1/15th of an inch (or 1.7 mm.) The distance is much
 shorter and the application thus appears more sensitive to the user. To fix this
-issue, the gesture threshold must be expressed in the code in <code>dip</code>
+issue, the gesture threshold must be expressed in the code in <code>dp</code>
 and then converted to actual pixels.</p>
 
-<pre>// The gesture threshold expressed in dip
+<pre>// The gesture threshold expressed in dp
-private static final float GESTURE_THRESHOLD_DIP = 16.0f;
+private static final float GESTURE_THRESHOLD_DP = 16.0f;
 
-// Convert the dips to pixels
+// Convert the dps to pixels
 final float scale = getContext().getResources().getDisplayMetrics().density;
-mGestureThreshold = (int) (GESTURE_THRESHOLD_DIP * scale + 0.5f);</span>
+mGestureThreshold = (int) (GESTURE_THRESHOLD_DP * scale + 0.5f);</span>
 
 // Use mGestureThreshold as a distance in pixels
 </pre>
 
 <p>The {@link android.util.DisplayMetrics#density android.util.DisplayMetrics.density}
 field specifies the the scale factor you must use to
-convert dips to pixels according to the current screen density. You can access
+convert dps to pixels according to the current screen density. You can access
 the current screen's metrics through a <code>Context</code> or
 <code>Activity</code>. On a medium (160) density screen,
 <code>DisplayMetrics.density</code> equals "1.0", whereas on a high (240)
@@ -973,7 +1058,7 @@ auto-scaled at draw time.</p>
 
 <p>If you have already developed and published an Android application based on
 Android 1.5 or earlier platform version, you need to consider how you will adapt
-your application so that it is deployable to </p>
+your application so that it is deployable to:</p>
 
 <ul>
 <li>Existing devices, which may be running Android 1.5 (or lower) platform
@@ -982,16 +1067,21 @@ version, as well as to </li>
 screen sizes and resolutions</li>
 </ul>
 
+<p class="note"><strong>Note:</strong> Even if your application targets Android 1.6 already, you
+should follow the same strategies below in order to support <em>xhdpi</em> and <em>xlarge</em>
+screens on Android 2.3 (API Level 9), while maintaining compatibility with older versions of
+the platform.</p>
+
 <p>To support the newer devices and the different screens they use, you might
 need to make some changes in your app, but at the same time your app may be very
 stable and so you want to minimize the changes. There are a variety of ways that
 you can extend your existing application to support new devices with multiple
 screens <em>and</em> existing devices running older platform versions. You
 should be able to make these changes to your application such that you can
-distribute a single .apk to any and all devices.</p>
+distribute a single {@code .apk} to all devices.</p>
 
 <p>The recommended strategy is to develop against the most recent version of the
-platform you are targeting, and test on the minimum one you want to run on.
+platform you are targeting, and test on the minimum platform version you want to run on.
 Here's how to do that:</p>
 
 <ol>
@@ -1002,36 +1092,38 @@ screens. </li>
   <li>Extend compatibility for Android 1.6 (and higher) devices by adding
 a new attribute &mdash; <code>android:targetSdkVersion</code> &mdash; to the
 <code>uses-sdk</code> element. Set the value of the attribute to
-"<code>4</code>". This allows your application to "inherit" the platform's
+<code>"4"</code>. [To support <em>xhdpi</em> and <em>xlarge</em> screens, set the value to
+<code>"9"</code>.] This allows your application to "inherit" the platform's
 multiple screens support, even though it is technically using an earlier version
 of the API. </li>
   <li>Add an empty <code>&lt;supports-screens&gt;</code> element as a child of
 <code>&lt;manifest&gt;</code>. If you need to enable size or density attributes
 later, this is where you will add them.</li>
   <li>Change your application's build properties, such that it compiles against
-the Android 1.6 (API Level 4) library, rather than against the Android 1.5 (or
+the Android 1.6 (API Level 4) library [or against Android 2.3 (API Level 9) to support
+<em>xhdpi</em> and <em>xlarge</em> screens], rather than against the Android 1.5 (or
 earlier) library. You will not be able to compile your application against the
 older platform because of the new manifest attribute. </li>
-  <li>Set up AVDs for testing your application on Android 1.6 and higher
+  <li>Set up AVDs for testing your application on Android 1.6 [or Android 2.3] and higher
 releases. Create AVDs that use the screen sizes and densities that you want to
-support. When you create the AVDs, make sure to select the Android 1.6 or higher
+support. When you create the AVDs, make sure to select the Android 1.6 [or Android 2.3] or higher
 platform as the system image to run. For more information, see <a
 href="#testing">How to Test Your Application on Multiple Screens</a>,
 below.</li>
-  <li>Set up AVDs for testing your application on Android 1.5 (or earlier
+  <li>Set up AVDs for testing your application on older versions of the platform, as low as the
-platform). You need AVDs running the older platforms you are targeting, so that
+version declared by your <code>android:minSdkVersion</code>. You need AVDs running the older
+platforms you are targeting, so that
 you can test for compatibility and ensure that there are no functional
 regressions. </li>
-  <li>Compile your application against the Android 1.6 library and run it on the
+  <li>Compile your application against the Android 1.6 [or Android 2.3] library and run it on the
 AVDs you created. Observe the way your application looks and runs, and test all
 of the user interactions. </li>
   <li>Debug any display or functional issues. For issues that you resolve in
 your application code, <span style="color:red">make certain not to use any APIs
-introduced in API Level 4 or later</span>. If you are in doubt, refer to SDK
+introduced later than the version declared by your <code>android:minSdkVersion</code></span>. If you
-reference documentation and look for the API Level specifier for the API you
+are in doubt, refer to SDK reference documentation and look for the API Level specifier for the API
-want to use. Using an API introduced in API Level 4 or later will mean that your
+you want to use. Using newer APIs not supported by your minimum version will mean that your
-application will no longer be compatible with devices running Android 1.5 or
+application will no longer be compatible with devices running on that version.</li>
-earlier.</li>
   <li>For resource-related issues, you can try resolving them by:
     <ul>
     <li>Adding a <code>anyDensity="false"</code> attribute to
@@ -1041,19 +1133,19 @@ scaling.</li>
 them in directories tagged with the <a href="#qualifiers">correct
 qualifiers</a>. Qualifiers must be arranged in a proscribed order. See
 <a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">
-Alternative Resources</a> for more information. </li>
+Providing Alternative Resources</a> for more information. </li>
     <li>Note that if you add size- or density-specific resource directories
 tagged with any of the resource qualifiers listed in this document, you should
 make sure to also tag those directories with the <code>v&lt;api-level&gt;</code>
-qualifier (for example, <code>-v4</code>). This ensures that those resources
+qualifier (for example, <code>-v4</code> to target API Level 4). This ensures that those resources
 will be ignored when the application is run on Android 1.5 or lower platform
 versions.</p></li>
     </ul>
   </li>
   <li>If your application does not offer support (such as custom layouts) for
 large screens and you want the platform to display your application in
-screen-compatibility mode on larger screens, add a
+screen-compatibility mode on larger screens, add the
-<code>largeScreens="false"</code> attribute to the
+<code>largeScreens="false"</code> and <code>xlargeScreens="false"</code> attributes to the
 <code>&lt;supports-screens&gt;</code> element in the manifest. See
 <a href="#compatibility-examples">Screen-Compatibility Examples</a> for
 illustrations of how the platform displays your application in this case.</li>
@@ -1077,6 +1169,16 @@ function on a small-screen device. In many cases, the reduced screen area and
 density mean that you may need to make tradeoffs in design, content, and
 function on those devices. </p>
 
+<p>Also give extra attention to testing your application on an AVD that emulates an <em>xlarge</em>
+screen. Devices with extra large screens
+are tablet-sized or larger, so you should pay close attention to how usable your application is on
+such screens. You might want to design new layouts specifically for extra large screens, to address
+usability aspects such as the location and size of buttons in your UI. To test your application on
+an extra large screen, create an AVD targeted to Android 2.3 with a high resolution, such as 1280 x
+800, and the default density of 160dpi. This AVD will use any resources you've provided with the
+<code>xlarge</code> <a href="#qualifiers">resouce qualifier</a>.</p>
+
+
 <h2 id="testing">How to Test Your Application on Multiple Screens</h2>
 
 <p>Before publishing an application that supports multiple screens, you should
@@ -1091,15 +1193,15 @@ not. Once you've tested your application and found that it displays properly on
 various screen sizes, you should make sure to add the corresponding size
 attribute(s) to your application's manifest. -->
 
-<div id="f9.5" style="float:right;margin:0;padding:0;">
+<div id="f9.5" class="figure" style="width:530px">
-  <img src="{@docRoot}images/screens_support/avds-config.png" style="padding:0;margin:0;">
+  <img src="{@docRoot}images/screens_support/avds-config.png" />
-  <p class="caption" style="margin:0 0 1.5em 1em;padding:0 0 0 1em;"><strong>Figure 4.</strong>
+  <p class="img-caption"><strong>Figure 4.</strong>
   A typical set of AVDs for testing screens support.</p>
 </div>
 
 <p>As a test environment for your applications, set up a series of AVDs that
 emulate the screen sizes and densities you want to support. The Android SDK
-includes six emulator skins to get you started. You can use the Android AVD
+includes several emulator skins to get you started. You can use the Android AVD
 Manager or the <code>android</code> tool to create AVDs that use the various
 emulator skins and you can also set up custom AVDs to test densities other than
 the defaults. For general information about working with AVDs, see
@@ -1161,9 +1263,9 @@ scale the entire emulator display, based on both the dpi of the skin and of your
 monitor. The default emulator skins included in the Android SDK are listed
 in <a href="#screens-table">Table 1</a>, earlier in this document.</p>
 
-<div style="float: right;background-color:#fff;margin: 0;padding: 20px 0 20px 20px;width:520px;">
+<div class="figure" style="width:324px">
-  <img src="{@docRoot}images/screens_support/avd-density.png" style="padding:0;margin:0;">
+  <img src="{@docRoot}images/screens_support/avd-density.png" >
-  <p class="caption" style="margin:0 0 1.5em 1em;padding:0 0 0 1em; width:280px;"><strong>Figure 5.</strong>
+  <p class="img-caption"><strong>Figure 5.</strong>
   Resolution and density options that you can use, when creating an AVD using the AVD Manager.</p>
 </div>
 

docs/html/guide/topics/resources/providing-resources.jd

@@ -329,7 +329,8 @@ indicates the current locale.</p>
       <td>
         <code>small</code><br/>
         <code>normal</code><br/>
-        <code>large</code>
+        <code>large</code><br/>
+        <code>xlarge</code>
       </td>
       <td>
         <ul class="nolist">
@@ -347,6 +348,10 @@ indicates the current locale.</p>
         medium-density VGA screen.  Such a screen has significantly more
         available space in both width and height than an HVGA display.
         Examples are VGA and WVGA medium density screens.</li>
+        <li>{@code xlarge}: Screens that are considerably larger than the traditional
+        medium-density HVGA screen. 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><em>Added in API Level 4.</em></p>
         <p>See <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple
@@ -437,6 +442,7 @@ application during runtime.</p>
         <code>ldpi</code><br/>
         <code>mdpi</code><br/>
         <code>hdpi</code><br/>
+        <code>xhdpi</code><br/>
         <code>nodpi</code>
       </td>
       <td>
@@ -445,6 +451,8 @@ application during runtime.</p>
           <li>{@code mdpi}: Medium-density (on traditional HVGA) screens; approximately
 160dpi.</li>
           <li>{@code hdpi}: High-density screens; approximately 240dpi.</li>
+          <li>{@code xhdpi}: Extra high-density screens; approximately 320dpi. <em>Added in API
+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>
         </ul>