am db76388e: am 9a05cfe5: docs: update docs for new screen support attributes and qualifiers

         {@link #AndroidManifest manifest} tag. -->

    <declare-styleable name="AndroidManifestSupportsScreens" parent="AndroidManifest">

        <!-- Starting with {@link android.os.Build.VERSION_CODES#HONEYCOMB_MR2},

             this is the new way to specify the screens an application is

             this is the new way to specify the minimum screen size an application is

             compatible with.  This attribute provides the required minimum

             "smallest screen width" (as per the -swNNNdp resource configuration)

             that the application can run on.  For example, a typical phone

             or xlargeScreens attributes will be used instead. -->

        <attr name="requiresSmallestWidthDp" format="integer" />

        <!-- Starting with {@link android.os.Build.VERSION_CODES#HONEYCOMB_MR2},

             this is the new way to specify the screens an application is

             this is the new way to specify the largest screens an application is

             compatible with.  This attribute provides the maximum

             "smallest screen width" (as per the -swNNNdp resource configuration)

             that the application is designed for.  If this value is smaller than

             the "smallest screen width" of the device it is running on, the user

             will of offered to run it in a compatibility mode that emulates a

             smaller screen.  Currently the compatibility mode only emulates

             phone screens, so it will not be used it the application provides

             a requiresSmallestWidthDp that is larger than 320.  Typical values

             used with this attribute are 320 for a phone screen, 600 for a

             7" tablet, and 720 for a 10" tablet. -->

             is offered to run it in a compatibility mode that emulates a

             smaller screen and zooms it to fit the screen. Currently the compatibility mode only

             emulates phone screens with a 320dp width, so compatibility mode is not applied if the

             value for compatibleWidthLimitDp is larger than 320. -->

        <attr name="compatibleWidthLimitDp" format="integer" />

        <!-- Starting with {@link android.os.Build.VERSION_CODES#HONEYCOMB_MR2},

             this is the new way to specify the screens an application is

             that the application can work well on.  If this value is smaller than

             the "smallest screen width" of the device it is running on, the

             application will be forced in to screen compatibility mode with

             no way for the user to turn it off.  Currently the compatibility mode

             only emulates phone screens, so even if this value is larger than 320

             the width the app runs in will be a 320 phone dimension. -->

             no way for the user to turn it off. Currently the compatibility mode only

             emulates phone screens with a 320dp width, so compatibility mode is not applied if the

             value for largestWidthLimitDp is larger than 320. -->

        <attr name="largestWidthLimitDp" format="integer" />

        <!-- Indicates whether the application supports smaller screen form-factors.

             A small screen is defined as one with a smaller aspect ratio than

          <li><a href="<?cs var:toroot ?>guide/topics/manifest/receiver-element.html">&lt;receiver&gt;</a></li>

          <li><a href="<?cs var:toroot ?>guide/topics/manifest/service-element.html">&lt;service&gt;</a></li>

          <li><a href="<?cs var:toroot ?>guide/topics/manifest/supports-gl-texture-element.html">&lt;supports-gl-texture&gt;</a></li> 

          <li><a href="<?cs var:toroot ?>guide/topics/manifest/supports-screens-element.html">&lt;supports-screens&gt;</a></li>  <!-- ##api level 4## -->

          <li><a href="<?cs var:toroot ?>guide/topics/manifest/supports-screens-element.html">&lt;supports-screens&gt;</a>

              <span class="new">updated</span></li>  <!-- ##api level 4## -->

          <li><a href="<?cs var:toroot ?>guide/topics/manifest/uses-configuration-element.html">&lt;uses-configuration&gt;</a></li>

          <li><a href="<?cs var:toroot ?>guide/topics/manifest/uses-feature-element.html">&lt;uses-feature&gt;</a></li> <!-- ##api level 4## -->

          <li><a href="<?cs var:toroot ?>guide/topics/manifest/uses-library-element.html">&lt;uses-library&gt;</a></li>

<dt>syntax:</dt>

<dd>

<pre class="stx">

&lt;supports-screens android:<a href="#resizeable">resizeable</a>=["true" | "false"]

&lt;supports-screens android:<a href="#requiresSmallest">requiresSmallestWidthDp</a>="<em>integer</em>"

                  android:<a href="#compatibleWidth">compatibleWidthLimitDp</a>="<em>integer</em>"

                  android:<a href="#largestWidth">largestWidthLimitDp</a>="<em>integer</em>"

                  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"]

<dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code></dd>

<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; 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

<dd>Lets you specify the screen sizes your application supports and enable screen

compatibility mode for screens larger than what your 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 by the number of pixels on the

screen after the system accounts for screen density scaling.

<p>An application "supports" a given screen size if it resizes properly to fill the entire screen.

By default, the system resizes your application UI 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>

targetSdkVersion}</a> to {@code "4"} or higher. Normal resizing works well for most applications and

you don't have to do any extra work to make your application work on screens larger than a

handset device.</p>

<p>In addition to allowing the system to resize your application, you can add additional support

for different screen sizes by providing <a

<p>In addition to allowing the system to resize your application to fit the current screen, you can

optimize your UI 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 

<p>However, if your application does not work well when resized to fit different screen sizes,

you can use the attributes of the {@code <supports-screens>} element to control whether

your application should be distributed to smaller screens or have its UI scaled up to fit larger

screens using the system's screen compatibility mode. When you have not designed for larger screen

sizes and the normal resizing does not achieve the appropriate results, <em>screen compatibility

mode</em> will scale your UI by emulating a <em>normal</em> size screen and then zooming in on it so

that it fills the entire screen—thus achieving the same layout as a normal handset device on

the large screen (but this usually causes pixelation and blurring of your UI).</p>

<p>For more information about how to properly support different screen sizes so that you can avoid

using screen compatibility mode, read

<a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a>.</p>

<dd>

<dl class="attr">

  <dt id="requiresSmallest">{@code android:requiresSmallestWidthDp}</dt>

  <dd>This attribute specifies the minimum "smallest screen width" with which your

application is compatible. In order for a device to be considered compatible with your

application, the shortest side of the available screen space must be equal to or greater than this

value.

<p>The width against which your value is compared takes into account screen decorations and system

UI. For example, if the device has some persistent UI elements on the left or right edge of the

display, the system declares the device's available width as one that is smaller than the actual

screen size, accounting for these UI elements because those are screen pixels not available for your

UI. Thus, the value you use should be the actual smallest width required by your layout.</p>

<p>If your application properly resizes for smaller screen sizes (down to the

<em>small</em> size or a minimum width of 320dp), you do

not need to use this attribute. Otherwise, you should use a value for this attribute that

matches the smallest value used by your application for the <a

href="{@docRoot}guide/topics/resources/providing-resources.html#SmallestScreenWidthQualifier">

smallest screen width qualifier</a> ({@code sw&lt;N&gt;dp}).</p>

<p>For example, a typical handset screen has a minimum width of 320dp, a 7" tablet has a minimum

width of 600dp, and a 10" tablet has a minimum width of 720dp. If the smallest available screen

width on a device is less than the value you supply here, then the application is considered

incompatible with that

device. External services such as Android Market use this to determine whether a device

is compatible with your application and prevent incompatible devices from installing it.</p>

<p>Beginning with Android 3.2 (API level 13), using this attribute is the preferred way to

specify the minimum screen size your application requires, instead of using the other attributes

for small, normal, large, and xlarge screens. The advantage of using this attribute is that you

have more control over exactly how much screen space your application needs at a minimum in order

to properly display its UI, rather than relying on the generalized size groups.</p>

<p>This attribute has no default value. If this attribute is not specified, then any of the old

<code><a href="#small">smallScreens</a></code>, <code><a href="#normal">normalScreens</a></code>,

<code><a href="#large">largeScreens</a></code>, or <code><a href="#xlarge">xlargeScreens</a></code>

attributes are used instead to determine the smallest screen required.</p>

     <p>This attribute was introduced in API level 13.</p>

  </dd>

  <dt id="compatibleWidth">{@code android:compatibleWidthLimitDp}</dt>

  <dd>This attribute allows you to enable screen compatibility mode as a user-optional feature by

specifying the maximum "smallest screen width" for which your application is designed. If the value

you supply here is less than the shortest side of the available screen space, users can still

install your application, but are offered to run it in screen compatibility mode. By default, screen

compatibility mode is disabled and your layout is resized to fit the screen as usual, but a

button is available in the system bar that allows the user to toggle screen compatibility mode on

and off.

  <p>If your application is compatible with all screen sizes and its layout properly resizes, you do

not need to use this attribute.</p>

  <p class="note"><strong>Note:</strong> Currently, screen compatibility mode only emulates handset

screens with a 320dp width, so screen compatibility mode is not applied if your value for {@code

android:compatibleWidthLimitDp} is larger than 320.</p>

     <p>This attribute was introduced in API level 13.</p>

  </dd>

  <dt id="largestWidth">{@code android:largestWidthLimitDp}</dt>

  <dd>This attribute allows you to force enable screen compatibility mode by specifying the maximum

"smallest screen width" for which your application is designed. If the value you supply here is less

than the shortest side of the available screen space, the application runs in screen

compatibility mode with no way for the user to disable it.

  <p>If your application is compatible with all screen sizes and its layout properly resizes, you do

not need to use this attribute. Otherwise, you should first consider using the <a

href="#compatibleWidth">{@code android:compatibleWidthLimitDp}</a> attribute. You should use the

{@code android:largestWidthLimitDp} attribute only when your application is functionally broken when

resized for larger screens and screen compatibility mode is the only way that users should use

your application.</p>

  <p class="note"><strong>Note:</strong> Currently, screen compatibility mode only emulates handset

screens with a 320dp width, so screen compatibility mode is not applied if your value for {@code

android:largestWidthLimitDp} is larger than 320.</p>

     <p>This attribute was introduced in API level 13.</p>

  </dd>

  <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

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>

  <p><strong>This attribute is deprecated</strong> as of API level 13.</p>

  </dd>

{@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><strong>This attribute is deprecated</strong> as of API level 13.</p>

  </dd>

  <dt><a name="normal"></a>{@code android:normalScreens}</dt>

     screen, but WQVGA low density and WVGA high density are also

     considered to be normal.  This attribute is "true" by default,

     and applications currently should leave it that way.

  <p><strong>This attribute is deprecated</strong> as of API level 13.</p>

  </dd>

  <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 might require some special care

     than a "normal" handset 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

{@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><strong>This attribute is deprecated</strong> as of API level 13.</p>

  </dd>

  <dt><a name="xlarge"></a>{@code android:xlargeScreens}</dt>

{@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>

     <p>This attribute was introduced in API level 9.</p>

  <p><strong>This attribute is deprecated</strong> as of API level 13.</p>

  </dd>

  <dt><a name="any"></a>{@code android:anyDensity}</dt>

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>

  <p><strong>This attribute is deprecated</strong> as of API level 13.</p>

  </dd>