add compatible-screens manifest element

and update supports-screens element with resizeable attribute

Change-Id: I0f9247464572d126b725270b40074a390b0887bf

2 files changed, 193 insertions, 38 deletions

diff --git a/docs/html/guide/topics/manifest/compatible-screens-element.jd b/docs/html/guide/topics/manifest/compatible-screens-element.jd
new file mode 100644
index 0000000..9fb0fd2
--- /dev/null
+++ b/docs/html/guide/topics/manifest/compatible-screens-element.jd
@@ -0,0 +1,108 @@
+page.title=<compatible-screens>
+@jd:body
+
+<dl class="xml">
+<dt>syntax:</dt>
+<dd>
+<pre>
+&lt;<a href="#compatible-screens">compatible-screens</a>&gt;
+    &lt;<a href="#screen">screen</a> android:<a href="#screenSize">screenSize</a>=["small" | "normal" | "large" | "xlarge"]
+            android:<a href="#screenDensity">screenDensity</a>=["ldpi" | "mdpi" | "hdpi" | "xhdpi"] /&gt;
+    ...
+&lt;/compatible-screens&gt;
+</pre>
+</dd>
+
+<dt>contained in:</dt>
+<dd><code><a
+href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code></dd>
+
+<dt>description:</dt>
+<dd>Specifies each screen configuration with which the application is compatible. Only one instance
+of the {@code &lt;compatible-screens&gt;} element is allowed in the manifest, but it can
+contain multiple <code>&lt;screen&gt;</code> elements. Each <code>&lt;screen&gt;</code> element
+specifies a specific screen size-density combination with which the application is compatible.
+
+  <p>The Android system <em>does not</em> read the {@code &lt;compatible-screens&gt;} manifest
+element (neither at install-time nor at runtime). This element is informational only and may be used
+by external services (such as Android Market) to better understand the application's compatibility
+with specific screen configurations and enable filtering for users. Any screen configuration that is
+<em>not</em> declared in this element is a screen with which the application is <em>not</em>
+compatible. Thus, external services (such as Android Market) should not provide the application to
+devices with such screens.</p>
+
+  <p class="caution"><strong>Caution:</strong> Normally, <strong>you should not use this manifest
+element</strong>. Using this element can dramatically reduce the potential user base for your
+application, by not allowing users to install your application if they have a device with a screen
+configuration that you have not listed. You should use it only as a last resort, when the
+application absolutely does not work with all screen configurations. Instead of using this element,
+you should follow the guide to <a href="{@docRoot}guide/practices/screens_support.html">Supporting
+Multiple Screens</a>, in order to provide complete support for multiple screens, by adding
+alternative resources for different screen sizes and densities.</p>
+
+  <p>If you want to set only a minimum screen <em>size</em> for your your application, then you
+should use the <a href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
+&lt;supports-screens&gt;}</a> element. For example, if you want your application to be available
+only for <em>large</em> and <em>xlarge</em> screen devices, the <a
+href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
+&lt;supports-screens&gt;}</a> element allows you to declare that your application does not
+support <em>small</em> and <em>normal</em> screen sizes. External services (such as Android
+Market) will filter your application accordingly. You can also use the <a
+href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
+&lt;supports-screens&gt;}</a> element to declare whether the system should resize your
+application for different screen sizes.</p>
+
+  <p>Also see the <a href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a>
+document for more information about how Android Market filters applications using this and
+other manifest elements.</p>
+
+</dd>
+
+<dt>child elements:</dt>
+<dd>
+  <dl class="tag-list">
+
+    <dt id="screen">{@code &lt;screen&gt;}</dt>
+    <dd>Specifies a single screen configuration with which the application is compatible.
+      <p>At least one instance of this element must be placed inside the {@code
+&lt;compatible-screens&gt;} element. This element <em>must include both</em> the {@code
+android:screenSize} and {@code android:screenDensity} attributes (if you do not declare both
+attributes, then the element is ignored).</p>
+
+      <p class="caps">attributes:</p>
+      <dl class="atn-list">
+        <dt id="screenSize"><code>android:screenSize</code></dt>
+        <dd><b>Required.</b> Specifies the screen size for this screen configuration.
+          <p>Accepted values:</p>
+          <ul>
+            <li>{@code small}</li>
+            <li>{@code normal}</li>
+            <li>{@code large}</li>
+            <li>{@code xlarge}</li>
+          </ul>
+          <p>For information about the different screen sizes, see <a
+href="{@docRoot}guide/practices/screens_support.html#range">Supporting Multiple Screens</a>.</p>
+        </dd>
+        <dt id="screenDensity"><code>android:screenDensity</code></dt>
+        <dd><b>Required.</b> Specifies the screen density for this screen configuration.
+          <p>Accepted values:</p>
+          <ul>
+            <li>{@code ldpi}</li>
+            <li>{@code mdpi}</li>
+            <li>{@code hdpi}</li>
+            <li>{@code xhdpi}</li>
+          </ul>
+          <p>For information about the different screen densities, see <a
+href="{@docRoot}guide/practices/screens_support.html#range">Supporting Multiple Screens</a>.</p>
+        </dd>
+      </dl>
+    </dd>
+  </dl>
+</dd>
+<dt>introduced in:</dt>
+<dd>API Level 9</dd>
+<dt>see also:</dt>
+<dd><a
+href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a></dd>
+<dd><a href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a></dd>
+</dl>
diff --git a/docs/html/guide/topics/manifest/supports-screens-element.jd b/docs/html/guide/topics/manifest/supports-screens-element.jd
index 64a7a58..92c769e 100644
--- a/docs/html/guide/topics/manifest/supports-screens-element.jd
+++ b/docs/html/guide/topics/manifest/supports-screens-element.jd
@@ -6,7 +6,8 @@ page.title=&lt;supports-screens&gt;
 <dt>syntax:</dt>
 <dd>
 <pre class="stx">
-&lt;supports-screens android:<a href="#small">smallScreens</a>=["true" | "false"] 
+&lt;supports-screens android:<a href="#resizeable">resizeable</a>=["true" | "false"]
+                  android:<a href="#small">smallScreens</a>=["true" | "false"] 
                   android:<a href="#normal">normalScreens</a>=["true" | "false"] 
                   android:<a href="#large">largeScreens</a>=["true" | "false"] 
                   android:<a href="#xlarge">xlargeScreens</a>=["true" | "false"]
@@ -19,17 +20,33 @@ page.title=&lt;supports-screens&gt;
 
 <dt>description:</dt>
 <dd>Lets you specify the screen dimensions the
-application supports.  By default a modern application (using API Level 4 or higher) supports all
-screen sizes and must explicitly disable certain screen sizes here;
-older applications are assumed to support only the "normal"
-screen size.  Note that screen size is a separate axis from
-density. Screen size is determined as the available pixels to an application
-after density scaling has been applied. 
-
-<p>Based on the target device screen density, the Android 
-framework will scale down assets by a factor of 0.75 (low dpi screens) 
-or scale them up by a factor of 1.5 (high dpi screens).
-The screen density is expressed as dots-per-inch (dpi).</p>
+application supports.  By default, a modern application (using API Level 4 or higher) supports all
+screen sizes; older applications are assumed to support only the "normal" screen size. Screen
+size is determined as the available pixels to an application after density scaling has been
+applied. (Note that screen size is a separate axis from screen density.)
+
+<p>An application "supports" a given screen size if it fills the entire screen and works as
+expected. By default, the system will resize your application to fill the screen, if you have set
+either <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code
+minSdkVersion}</a> or <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code
+targetSdkVersion}</a> to {@code "4"} or higher. Resizing works well for most applications and
+you don't have to do any extra work to make your application work on larger screens.</p>
+
+<p>In addition to allowing the system to resize your application, you can add additional support
+for different screen sizes by providing <a
+href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">alternative
+layout resources</a> for different sizes. For instance, you might want to modify the layout
+of an activity when it is on a tablet or similar device that has an <em>xlarge</em> screen.</p>
+
+<p>If your application does not support <em>large</em> or <em>xlarge</em> screens, then you should
+declare that it is not resizeable by setting <a href="#resizeable">{@code android:resizeable}</a> to
+{@code "false"}, so that the system will not resize your application on larger screens.</p>
+
+<p>If your application does not support <em>small</em> screens, then
+there isn't much the system can do to make the application work well on a smaller screen, so
+external services (such as Android Market) should not allow users to install the application on such
+screens.</p>
+
 
 <p>For more information, see 
 <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a>.</p>
@@ -38,16 +55,40 @@ The screen density is expressed as dots-per-inch (dpi).</p>
 <dt>attributes:</dt>
 
 <dd>
-<dl class="attr"><dt><a name="small"></a>{@code android:smallScreens}</dt>
+<dl class="attr">
+  
+  <dt><a name="resizeable"></a>{@code android:resizeable}</dt>
+  <dd>Indicates whether the application is resizeable for different screen sizes. This attribute is
+true, by default, if you have set either <a
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> or <a
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> to
+{@code "4"} or higher. Otherwise, it is false by default. If set false, the system will not resize
+your application when run on <em>large</em> or <em>xlarge</em> screens. Instead, the
+application appears in a "postage stamp" that equals the <em>normal</em> screen size that your
+application does support. This is less than an ideal experience for users, because the
+application appears smaller than the available screen, but it might help your application run
+normally if it were designed only for the <em>normal</em> screen size and some behaviors do not work
+when resized.</p>
+  <p>To provide the best experience on all screen sizes, you should allow resizing and, if your
+application does not work well on larger screens, follow the guide to <a
+href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a> to enable
+additional screen support.</p>
+  </dd>
+  
+  
+  <dt><a name="small"></a>{@code android:smallScreens}</dt>
   <dd>Indicates whether the application supports smaller screen form-factors.
      A small screen is defined as one with a smaller aspect ratio than
      the "normal" (traditional HVGA) screen.  An application that does
      not support small screens <em>will not be available</em> for
-     small screen devices, because there is little the platform can do
-     to make such an application work on a smaller screen. If the application has set the <a
-href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code &lt;uses-sdk&gt;}</a> element's
-{@code android:minSdkVersion} or {@code android:targetSdkVersion} attribute to "4" or higher,
-the default value for this is "true", any value less than "4" results in this set to "false".
+     small screen devices from external services (such as Android Market), because there is little
+the platform can do
+     to make such an application work on a smaller screen. If the application has set either <a
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> or <a
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> to
+{@code "4"} or higher,
+the default value for this is {@code "true"}, any value less than {@code "4"} results in this set to
+{@code "false"}.
   </dd>
   
   <dt><a name="normal"></a>{@code android:normalScreens}</dt>
@@ -61,38 +102,44 @@ the default value for this is "true", any value less than "4" results in this se
   <dt><a name="large"></a>{@code android:largeScreens}</dt>
   <dd>Indicates whether the application supports larger screen form-factors.
      A large screen is defined as a screen that is significantly larger
-     than a "normal" phone screen, and thus may require some special care
-     on the application's part to make good use of it. An application that 
-     does not support large screens (declares this "false")&mdash;but does support "normal" or
-"small" screens&mdash;will be placed as a "postage stamp" on 
-     a large screen, so that it retains the dimensions it was originally
-     designed for. If the application has set the <a
-href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code &lt;uses-sdk&gt;}</a> element's
-{@code android:minSdkVersion} or {@code android:targetSdkVersion} attribute to "4" or higher,
-the default value for this is "true", any value less than "4" results in this set to "false".
+     than a "normal" phone screen, and thus might require some special care
+     on the application's part to make good use of it, though it may rely on resizing by the
+system to fill the screen. If the application has set either <a
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> or <a
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> to
+{@code "4"} or higher,
+the default value for this is {@code "true"}, any value less than {@code "4"} results in this set to
+{@code "false"}.
   </dd>
-  
+
   <dt><a name="xlarge"></a>{@code android:xlargeScreens}</dt>
   <dd>Indicates whether the application supports extra large screen form-factors.
      An xlarge screen is defined as a screen that is significantly larger
      than a "large" screen, such as a tablet (or something larger) and may require special care
-     on the application's part to make good use of it. An application that 
-     does not support xlarge screens (declares this "false")&mdash;but does support "large",
-"normal", or "small" screens&mdash;will be placed as a "postage stamp" on 
-     an xlarge screen, so that it retains the dimensions it was originally
-     designed for. If the application has set the <a
-href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code &lt;uses-sdk&gt;}</a> element's
-{@code android:minSdkVersion} or {@code android:targetSdkVersion} attribute to "4" or higher,
-the default value for this is "true", any value less than "4" results in this set to "false".
+     on the application's part to make good use of it, though it may rely on resizing by the
+system to fill the screen. If the application has set either <a
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> or <a
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> to
+{@code "4"} or higher,
+the default value for this is {@code "true"}, any value less than {@code "4"} results in this set to
+{@code "false"}.
      <p>This attribute was introduced in API Level 9.</p>
   </dd>
   
   <dt><a name="any"></a>{@code android:anyDensity}</dt>
   <dd>Indicates whether the application includes resources to accommodate any screen
      density.  Older applications (before API Level 4) are assumed unable to
-     accomodate all densities and this is "false" by default. Applications using 
-     API Level 4 or higher are assumed able to and this is "true" by default. 
+     accomodate all densities and this is {@code "false"} by default. If the application has set
+either <a
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> or <a
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> to
+{@code "4"} or higher,
+the default value for this is {@code "true"}. Otherwise, it is {@code "false"}.
      You can explicitly supply your abilities here.
+     <p>Based on the "standard" device screen density (medium dpi), the Android framework will scale
+down application assets by a factor of 0.75 (low dpi screens) or scale them up by a factor of 1.5
+(high dpi screens), when you don't provide alternative resources for a specifc screen density. The
+screen density is expressed as dots-per-inch (dpi).</p>
   </dd>