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

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

Browse Source 
* commit '9a05cfe5427a6cee988333e0d65f17b9854554a3':
  docs: update docs for new screen support attributes and qualifiers
This commit is contained in:
Scott Main
2011-06-23 12:26:33 -07:00
committed by Android Git Automerger
parent a602972c3f 9a05cfe542
commit db76388e9a
4 changed files with 197 additions and 99 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
core/res/res/values/attrs_manifest.xml
View File

@@ -1012,7 +1012,7 @@
{@link #AndroidManifest manifest} tag. --> {@link #AndroidManifest manifest} tag. -->
<declare-styleable name="AndroidManifestSupportsScreens" parent="AndroidManifest"> <declare-styleable name="AndroidManifestSupportsScreens" parent="AndroidManifest">
<!-- Starting with {@link android.os.Build.VERSION_CODES#HONEYCOMB_MR2}, <!-- 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 compatible with. This attribute provides the required minimum
"smallest screen width" (as per the -swNNNdp resource configuration) "smallest screen width" (as per the -swNNNdp resource configuration)
that the application can run on. For example, a typical phone that the application can run on. For example, a typical phone
@@ -1023,17 +1023,15 @@
or xlargeScreens attributes will be used instead. --> or xlargeScreens attributes will be used instead. -->
<attr name="requiresSmallestWidthDp" format="integer" /> <attr name="requiresSmallestWidthDp" format="integer" />
<!-- Starting with {@link android.os.Build.VERSION_CODES#HONEYCOMB_MR2}, <!-- 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 compatible with. This attribute provides the maximum
"smallest screen width" (as per the -swNNNdp resource configuration) "smallest screen width" (as per the -swNNNdp resource configuration)
that the application is designed for. If this value is smaller than 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 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 is offered to run it in a compatibility mode that emulates a
smaller screen. Currently the compatibility mode only emulates smaller screen and zooms it to fit the screen. Currently the compatibility mode only
phone screens, so it will not be used it the application provides emulates phone screens with a 320dp width, so compatibility mode is not applied if the
a requiresSmallestWidthDp that is larger than 320. Typical values value for compatibleWidthLimitDp is larger than 320. -->
used with this attribute are 320 for a phone screen, 600 for a
7" tablet, and 720 for a 10" tablet. -->
<attr name="compatibleWidthLimitDp" format="integer" /> <attr name="compatibleWidthLimitDp" format="integer" />
<!-- Starting with {@link android.os.Build.VERSION_CODES#HONEYCOMB_MR2}, <!-- 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 screens an application is
@@ -1042,9 +1040,9 @@
that the application can work well on. If this value is smaller than 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 the "smallest screen width" of the device it is running on, the
application will be forced in to screen compatibility mode with application will be forced in to screen compatibility mode with
no way for the user to turn it off. Currently the compatibility mode no way for the user to turn it off. Currently the compatibility mode only
only emulates phone screens, so even if this value is larger than 320 emulates phone screens with a 320dp width, so compatibility mode is not applied if the
the width the app runs in will be a 320 phone dimension. --> value for largestWidthLimitDp is larger than 320. -->
<attr name="largestWidthLimitDp" format="integer" /> <attr name="largestWidthLimitDp" format="integer" />
<!-- Indicates whether the application supports smaller screen form-factors. <!-- Indicates whether the application supports smaller screen form-factors.
A small screen is defined as one with a smaller aspect ratio than A small screen is defined as one with a smaller aspect ratio than

3
docs/html/guide/guide_toc.cs
View File

@@ -222,7 +222,8 @@
<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/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/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-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-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-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> <li><a href="<?cs var:toroot ?>guide/topics/manifest/uses-library-element.html">&lt;uses-library&gt;</a></li>

128
docs/html/guide/topics/manifest/supports-screens-element.jd
View File

@@ -8,12 +8,15 @@ parent.link=manifest-intro.html
<dt>syntax:</dt> <dt>syntax:</dt>
<dd> <dd>
<pre class="stx"> <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="#small">smallScreens</a>=["true" | "false"]
android:<a href="#normal">normalScreens</a>=["true" | "false"] android:<a href="#normal">normalScreens</a>=["true" | "false"]
android:<a href="#large">largeScreens</a>=["true" | "false"] android:<a href="#large">largeScreens</a>=["true" | "false"]
android:<a href="#xlarge">xlargeScreens</a>=["true" | "false"] android:<a href="#xlarge">xlargeScreens</a>=["true" | "false"]
android:<a href="#any">anyDensity</a>=["true" | "false"] /&gt; android:<a href="#any">anyDensity</a>=["true" | "false"] /&gt;
</pre> </pre>
</dd> </dd>
@@ -21,36 +24,37 @@ parent.link=manifest-intro.html
<dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code></dd> <dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code></dd>
<dt>description:</dt> <dt>description:</dt>
<dd>Lets you specify the screen dimensions the <dd>Lets you specify the screen sizes your application supports and enable screen
application supports. By default, a modern application (using API Level 4 or higher) supports all compatibility mode for screens larger than what your application supports. By default, a modern
screen sizes; older applications are assumed to support only the "normal" screen size. Screen application (using API Level 4 or higher) supports all screen sizes; older applications are assumed
size is determined as the available pixels to an application after density scaling has been to support only the "normal" screen size. Screen size is determined by the number of pixels on the
applied. (Note that screen size is a separate axis from screen density.) screen after the system accounts for screen density scaling.
<p>An application "supports" a given screen size if it fills the entire screen and works as <p>An application "supports" a given screen size if it resizes properly to fill the entire screen.
expected. By default, the system will resize your application to fill the screen, if you have set 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 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 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 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 larger screens.</p> 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 <p>In addition to allowing the system to resize your application to fit the current screen, you can
for different screen sizes by providing <a optimize your UI for different screen sizes by providing <a
href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">alternative 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 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> 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 <p>However, if your application does not work well when resized to fit different screen sizes,
declare that it is not resizeable by setting <a href="#resizeable">{@code android:resizeable}</a> to you can use the attributes of the {@code &lt;supports-screens&gt;} element to control whether
{@code "false"}, so that the system will not resize your application on larger screens.</p> 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&mdash;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>If your application does not support <em>small</em> screens, then <p>For more information about how to properly support different screen sizes so that you can avoid
there isn't much the system can do to make the application work well on a smaller screen, so using screen compatibility mode, read
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> <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a>.</p>
@@ -59,6 +63,74 @@ screens.</p>
<dd> <dd>
<dl class="attr"> <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> <dt><a name="resizeable"></a>{@code android:resizeable}</dt>
<dd>Indicates whether the application is resizeable for different screen sizes. This attribute is <dd>Indicates whether the application is resizeable for different screen sizes. This attribute is
true, by default, if you have set either <a true, by default, if you have set either <a
@@ -75,6 +147,7 @@ when resized.</p>
application does not work well on larger screens, follow the guide to <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 href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a> to enable
additional screen support.</p> additional screen support.</p>
<p><strong>This attribute is deprecated</strong> as of API level 13.</p>
</dd> </dd>
@@ -91,6 +164,7 @@ href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targe
{@code "4"} or higher, {@code "4"} or higher,
the default value for this is {@code "true"}, any value less than {@code "4"} results in this set to the default value for this is {@code "true"}, any value less than {@code "4"} results in this set to
{@code "false"}. {@code "false"}.
<p><strong>This attribute is deprecated</strong> as of API level 13.</p>
</dd> </dd>
<dt><a name="normal"></a>{@code android:normalScreens}</dt> <dt><a name="normal"></a>{@code android:normalScreens}</dt>
@@ -99,12 +173,13 @@ the default value for this is {@code "true"}, any value less than {@code "4"} re
screen, but WQVGA low density and WVGA high density are also screen, but WQVGA low density and WVGA high density are also
considered to be normal. This attribute is "true" by default, considered to be normal. This attribute is "true" by default,
and applications currently should leave it that way. and applications currently should leave it that way.
<p><strong>This attribute is deprecated</strong> as of API level 13.</p>
</dd> </dd>
<dt><a name="large"></a>{@code android:largeScreens}</dt> <dt><a name="large"></a>{@code android:largeScreens}</dt>
<dd>Indicates whether the application supports larger screen form-factors. <dd>Indicates whether the application supports larger screen form-factors.
A large screen is defined as a screen that is significantly larger 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 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 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#min">{@code minSdkVersion}</a> or <a
@@ -112,6 +187,7 @@ href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targe
{@code "4"} or higher, {@code "4"} or higher,
the default value for this is {@code "true"}, any value less than {@code "4"} results in this set to the default value for this is {@code "true"}, any value less than {@code "4"} results in this set to
{@code "false"}. {@code "false"}.
<p><strong>This attribute is deprecated</strong> as of API level 13.</p>
</dd> </dd>
<dt><a name="xlarge"></a>{@code android:xlargeScreens}</dt> <dt><a name="xlarge"></a>{@code android:xlargeScreens}</dt>
@@ -125,7 +201,8 @@ href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targe
{@code "4"} or higher, {@code "4"} or higher,
the default value for this is {@code "true"}, any value less than {@code "4"} results in this set to the default value for this is {@code "true"}, any value less than {@code "4"} results in this set to
{@code "false"}. {@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> </dd>
<dt><a name="any"></a>{@code android:anyDensity}</dt> <dt><a name="any"></a>{@code android:anyDensity}</dt>
@@ -142,6 +219,7 @@ the default value for this is {@code "true"}. Otherwise, it is {@code "false"}.
down application assets by a factor of 0.75 (low dpi screens) or scale them up by a factor of 1.5 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 (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> screen density is expressed as dots-per-inch (dpi).</p>
<p><strong>This attribute is deprecated</strong> as of API level 13.</p>
</dd> </dd>

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

@@ -335,80 +335,101 @@ indicates the current locale.</p>
</tr> </tr>
<tr id="SmallestScreenWidthQualifier"> <tr id="SmallestScreenWidthQualifier">
<td>Smallest screen width</td> <td>Smallest screen width</td>
<td>Examples:<br/> <td><code>sw&lt;N&gt;dp</code><br/><br/>
Examples:<br/>
<code>sw320dp</code><br/> <code>sw320dp</code><br/>
<code>sw600dp</code><br/> <code>sw600dp</code><br/>
<code>sw720dp</code><br/> <code>sw720dp</code><br/>
etc. etc.
</td> </td>
<td> <td>
<p>Specifies a minimum "smallest screen width," in "dp" units, at which the resource <p>Specifies the "smallest width" in {@code dp} units that must be available to your
should be used. This configuration value represents the base screen size application in order for the resources to be used, regardless of the screen's current
of the device, regardless of the orientation of the display. It is based orientation. For example, if your layout requires that its shortest side be at least 600
on the smallest width the application will have in which to perform its dp in length at all times, then you can use this to create the layout resources, {@code
UI layout (in dp units) regardless of the orientation of the screen. The res/layout-sw600dp/}, and the system will use them only when the shortest side of
value here takes into account screen decorations so if the device has some available screen space it at least 600dp.</p>
persistent UI elements on the left or right edge of the display it must <p>The width against which the system compares your value takes into account screen
present a value here that is smaller than the real screen size, accounting decorations and system UI. For example, if the device has some persistent UI elements on the
for these UI elements reducing the application's available space.</p> left or right edge of the display, the system declares its own available width as one that
<p>Some values you may use here for common screen sizes:</p> 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>Some values you might use here for common screen sizes:</p>
<ul> <ul>
<li>240x320 ldpi (QVGA phone): 320 <li>320, for devices with screen configurations such as:
<li>320x480 mdpi (phone): 320 <ul>
<li>480x800 hdpi (high density phone): 320 <li>240x320 ldpi (QVGA handset)</li>
<li>480x800 mdpi (tablet/phone): 480 <li>320x480 mdpi (handset)</li>
<li>600x1024 mdpi (7" tablet): 600 <li>480x800 hdpi (high density handset)</li>
<li>720x1280 mdpi (10" tablet): 720 </ul>
</li>
<li>480, for screens such as 480x800 mdpi (tablet/handset).</li>
<li>600, for screens such as 600x1024 mdpi (7" tablet).</li>
<li>720, for screens such as 720x1280 mdpi (10" tablet).</li>
</ul> </ul>
<p><em>Added in API Level 13.</em></p> <p>When your application provides multiple resource directories with different values for
<p>Also see the {@link android.content.res.Configuration#smallestScreenWidthDp} this qualifier, the system uses the one closest to (without exceeding) the smallest width
configuration field, which holds the current smallest screen width.</p> for the available space. </p>
<p><em>Added in API level 13.</em></p>
<p>Also see the <a
href="{@docRoot}guide/topics/manifest/supports-screens-element.html#requiresSmallest">{@code
android:requiresSmallestWidthDp}</a> attribute, which declares the smallest available width
with which your application is compatible, and the {@link
android.content.res.Configuration#smallestScreenWidthDp} configuration field, which holds
the current smallest screen width for the device.</p>
</td> </td>
</tr> </tr>
<tr id="ScreenWidthQualifier"> <tr id="ScreenWidthQualifier">
<td>Screen width</td> <td>Screen width</td>
<td>Examples:<br/> <td><code>w&lt;N&gt;dp</code><br/><br/>
Examples:<br/>
<code>w720dp</code><br/> <code>w720dp</code><br/>
<code>w1024dp</code><br/> <code>w1024dp</code><br/>
etc. etc.
</td> </td>
<td> <td>
<p>Specifies a minimum screen width, in "dp" units, at which the resource <p>Specifies a minimum screen width, in {@code dp} units at which the resource
should be used. This configuration value will change when the orientation should be used&mdash;defined by the <code>&lt;N&gt;</code> value. This
changes between landscape and portrait to match the current actual width. configuration value will change when the orientation
When multiple screen width configurations are available, the closest to changes between landscape and portrait to match the current actual width.</p>
the current screen width will be used. The <p>When your application provides multiple resource directories with different values
value here takes into account screen decorations so if the device has some for this configuration, the system uses the one closest to (without exceeding)
persistent UI elements on the left or right edge of the display it must the device's current screen width. The
present a value here that is smaller than the real screen size, accounting value here takes into account screen decorations, so if the device has some
for these UI elements reducing the application's available space.</p> persistent UI elements on the left or right edge of the display, it
<p><em>Added in API Level 13.</em></p> uses a value for the width that is smaller than the real screen size, accounting
for these UI elements and reducing the application's available space.</p>
<p><em>Added in API level 13.</em></p>
<p>Also see the {@link android.content.res.Configuration#screenWidthDp} <p>Also see the {@link android.content.res.Configuration#screenWidthDp}
configuration field, which holds the current screen width.</p> configuration field, which holds the current screen width.</p>
</td> </td>
</tr> </tr>
<tr id="ScreenHeightQualifier"> <tr id="ScreenHeightQualifier">
<td>Screen height</td> <td>Screen height</td>
<td>Examples:<br/> <td><code>h&lt;N&gt;dp</code><br/><br/>
Examples:<br/>
<code>h720dp</code><br/> <code>h720dp</code><br/>
<code>h1024dp</code><br/> <code>h1024dp</code><br/>
etc. etc.
</td> </td>
<td> <td>
<p>Specifies a minimum screen height, in "dp" units, at which the resource <p>Specifies a minimum screen height, in "dp" units at which the resource
should be used. This configuration value will change when the orientation should be used&mdash;defined by the <code>&lt;N&gt;</code> value. This
changes between landscape and portrait to match the current actual height. configuration value will change when the orientation
When multiple screen height configurations are available, the closest to changes between landscape and portrait to match the current actual height.</p>
the current screen height will be used. The <p>When your application provides multiple resource directories with different values
value here takes into account screen decorations so if the device has some for this configuration, the system uses the one closest to (without exceeding)
persistent UI elements on the left or right edge of the display it must the device's current screen height. The
present a value here that is smaller than the real screen size, accounting value here takes into account screen decorations, so if the device has some
for these UI elements reducing the application's available space. Screen persistent UI elements on the top or bottom edge of the display, it uses
a value for the height that is smaller than the real screen size, accounting
for these UI elements and reducing the application's available space. Screen
decorations that are not fixed (such as a phone status bar that can be decorations that are not fixed (such as a phone status bar that can be
hidden when full screen) are <em>not</em> accounted for here, nor are hidden when full screen) are <em>not</em> accounted for here, nor are
window decorations like title bar, so applications must be prepared to window decorations like the title bar or action bar, so applications must be prepared to
deal with a somewhat smaller space than they specify. deal with a somewhat smaller space than they specify.
<p><em>Added in API Level 13.</em></p> <p><em>Added in API level 13.</em></p>
<p>Also see the {@link android.content.res.Configuration#screenHeightDp} <p>Also see the {@link android.content.res.Configuration#screenHeightDp}
configuration field, which holds the current screen width.</p> configuration field, which holds the current screen width.</p>
</td> </td>
@@ -444,9 +465,9 @@ indicates the current locale.</p>
medium-density HVGA screen. The minimum layout size for this screen configuration medium-density HVGA screen. The minimum layout size for this screen configuration
is approximately 720x960 dp units. In most cases, devices with extra large 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 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> be tablet-style devices. <em>Added in API level 9.</em></li>
</ul> </ul>
<p><em>Added in API Level 4.</em></p> <p><em>Added in API level 4.</em></p>
<p>See <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple <p>See <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple
Screens</a> for more information.</p> Screens</a> for more information.</p>
<p>Also see the {@link android.content.res.Configuration#screenLayout} configuration field, <p>Also see the {@link android.content.res.Configuration#screenLayout} configuration field,
@@ -465,7 +486,7 @@ or large.</p>
<li>{@code long}: Long screens, such as WQVGA, WVGA, FWVGA</li> <li>{@code long}: Long screens, such as WQVGA, WVGA, FWVGA</li>
<li>{@code notlong}: Not long screens, such as QVGA, HVGA, and VGA</li> <li>{@code notlong}: Not long screens, such as QVGA, HVGA, and VGA</li>
</ul> </ul>
<p><em>Added in API Level 4.</em></p> <p><em>Added in API level 4.</em></p>
<p>This is based purely on the aspect ratio of the screen (a "long" screen is wider). This <p>This is based purely on the aspect ratio of the screen (a "long" screen is wider). This
is not related to the screen orientation.</p> is not related to the screen orientation.</p>
<p>Also see the {@link android.content.res.Configuration#screenLayout} configuration field, <p>Also see the {@link android.content.res.Configuration#screenLayout} configuration field,
@@ -503,7 +524,7 @@ which indicates the current device orientation.</p>
<li>{@code car}: Device is in a car dock</li> <li>{@code car}: Device is in a car dock</li>
<li>{@code desk}: Device is in a desk dock</li> <li>{@code desk}: Device is in a desk dock</li>
</ul> </ul>
<p><em>Added in API Level 8.</em></p> <p><em>Added in API level 8.</em></p>
<p>This can change during the life of your application if the user places the device in a <p>This can change during the life of your application if the user places the device in a
dock. You can enable or disable this mode using {@link dock. You can enable or disable this mode using {@link
android.app.UiModeManager}. See <a href="runtime-changes.html">Handling Runtime Changes</a> for android.app.UiModeManager}. See <a href="runtime-changes.html">Handling Runtime Changes</a> for
@@ -521,7 +542,7 @@ information about how this affects your application during runtime.</p>
<li>{@code night}: Night time</li> <li>{@code night}: Night time</li>
<li>{@code notnight}: Day time</li> <li>{@code notnight}: Day time</li>
</ul> </ul>
<p><em>Added in API Level 8.</em></p> <p><em>Added in API level 8.</em></p>
<p>This can change during the life of your application if night mode is left in <p>This can change during the life of your application if night mode is left in
auto mode (default), in which case the mode changes based on the time of day. You can enable auto mode (default), in which case the mode changes based on the time of day. You can enable
or disable this mode using {@link android.app.UiModeManager}. See <a or disable this mode using {@link android.app.UiModeManager}. See <a
@@ -549,7 +570,7 @@ Level 8</em></li>
<li>{@code nodpi}: This can be used for bitmap resources that you do not want to be scaled <li>{@code nodpi}: This can be used for bitmap resources that you do not want to be scaled
to match the device density.</li> to match the device density.</li>
</ul> </ul>
<p><em>Added in API Level 4.</em></p> <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 <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> in ldpi is 12x12 in mdpi, 18x18 in hdpi and 24x24 in xhdpi.</p>
<p>When Android selects which resource files to use, <p>When Android selects which resource files to use,
@@ -689,17 +710,17 @@ orientation" described above.</p>
</tr> </tr>
--> -->
<tr id="VersionQualifier"> <tr id="VersionQualifier">
<td>Platform Version (API Level)</td> <td>Platform Version (API level)</td>
<td>Examples:<br/> <td>Examples:<br/>
<code>v3</code><br/> <code>v3</code><br/>
<code>v4</code><br/> <code>v4</code><br/>
<code>v7</code><br/> <code>v7</code><br/>
etc.</td> etc.</td>
<td> <td>
<p>The API Level supported by the device. For example, <code>v1</code> for API Level <p>The API level supported by the device. For example, <code>v1</code> for API level
1 (devices with Android 1.0 or higher) and <code>v4</code> for API Level 4 (devices with Android 1 (devices with Android 1.0 or higher) and <code>v4</code> for API level 4 (devices with Android
1.6 or higher). See the <a 1.6 or higher). See the <a
href="{@docRoot}guide/appendix/api-levels.html">Android API Levels</a> document for more information href="{@docRoot}guide/appendix/api-levels.html">Android API levels</a> document for more information
about these values.</p> about these values.</p>
<p class="caution"><strong>Caution:</strong> Android 1.5 and 1.6 only match resources <p class="caution"><strong>Caution:</strong> Android 1.5 and 1.6 only match resources
with this qualifier when it exactly matches the platform version. See the section below about <a with this qualifier when it exactly matches the platform version. See the section below about <a
@@ -863,7 +884,7 @@ cannot use the resources named with the new qualifier. For example, if your <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code
minSdkVersion}</a> is set to 4, and you qualify all of your drawable resources using <a minSdkVersion}</a> is set to 4, and you qualify all of your drawable resources using <a
href="#NightQualifier">night mode</a> ({@code night} or {@code notnight}, which were added in API href="#NightQualifier">night mode</a> ({@code night} or {@code notnight}, which were added in API
Level 8), then an API Level 4 device cannot access your drawable resources and will crash. In this Level 8), then an API level 4 device cannot access your drawable resources and will crash. In this
case, you probably want {@code notnight} to be your default resources, so you should exclude that case, you probably want {@code notnight} to be your default resources, so you should exclude that
qualifier so your drawable resources are in either {@code drawable/} or {@code drawable-night/}.</p> qualifier so your drawable resources are in either {@code drawable/} or {@code drawable-night/}.</p>
@@ -896,7 +917,7 @@ compatibility for these versions.</p>
<dd>{@code long} and {@code notlong}</dd> <dd>{@code long} and {@code notlong}</dd>
</dl> </dl>
<p>These configuration qualifiers were introduced in Android 1.6, so Android 1.5 (API Level 3) and <p>These configuration qualifiers were introduced in Android 1.6, so Android 1.5 (API level 3) and
lower does not support them. If you use these configuration qualifiers and do not provide lower does not support them. If you use these configuration qualifiers and do not provide
corresponding default resources, then an Android 1.5 device might use any one of the resource corresponding default resources, then an Android 1.5 device might use any one of the resource
directories named with the above screen configuration qualifiers, because it ignores these directories named with the above screen configuration qualifiers, because it ignores these
@@ -926,9 +947,9 @@ is r6 or greater.
<p>You need SDK Tools, Revision 6 (or greater), because it includes a new packaging tool that <p>You need SDK Tools, Revision 6 (or greater), because it includes a new packaging tool that
automatically applies an appropriate <a href="#VersionQualifier">version qualifier</a> to any automatically applies an appropriate <a href="#VersionQualifier">version qualifier</a> to any
resource directory named with a qualifier that does not exist in Android 1.0. For example, because resource directory named with a qualifier that does not exist in Android 1.0. For example, because
the density qualifier was introduced in Android 1.6 (API Level 4), when the packaging tool the density qualifier was introduced in Android 1.6 (API level 4), when the packaging tool
encounters a resource directory using the density qualifier, it adds {@code v4} to the directory encounters a resource directory using the density qualifier, it adds {@code v4} to the directory
name to ensure that older versions do not use those resources (only API Level 4 and higher support name to ensure that older versions do not use those resources (only API level 4 and higher support
that qualifier). Thus, by putting your medium-density resources in a directory <em>without</em> the that qualifier). Thus, by putting your medium-density resources in a directory <em>without</em> the
{@code mdpi} qualifier, they are still accessible by Android 1.5, and any device that supports the {@code mdpi} qualifier, they are still accessible by Android 1.5, and any device that supports the
density qualifer and has a medium-density screen also uses the default resources (which are mdpi) density qualifer and has a medium-density screen also uses the default resources (which are mdpi)
@@ -937,7 +958,7 @@ resources).</p>
</li> </li>
</ol> </ol>
<p class="note"><strong>Note:</strong> Later versions of Android, such as API Level 8, <p class="note"><strong>Note:</strong> Later versions of Android, such as API level 8,
introduce other configuration qualifiers that older version do not support. To provide the best introduce other configuration qualifiers that older version do not support. To provide the best
compatibility, you should always include a set of default resources for each type of resource compatibility, you should always include a set of default resources for each type of resource
that your application uses, as discussed above to provide the best device compatibility.</p> that your application uses, as discussed above to provide the best device compatibility.</p>
@@ -1068,7 +1089,7 @@ href="accessing-resources.html">Accessing Resources</a>.</p>
<p>The correct behavior is for the system to match resources marked with a <a <p>The correct behavior is for the system to match resources marked with a <a
href="#VersionQualifier">version qualifier</a> equal href="#VersionQualifier">version qualifier</a> equal
to or less than the platform version on the device, but on Android 1.5 and 1.6, (API Level 3 and 4), to or less than the platform version on the device, but on Android 1.5 and 1.6, (API level 3 and 4),
there is a bug that causes the system to match resources marked with the version qualifier there is a bug that causes the system to match resources marked with the version qualifier
only when it exactly matches the version on the device.</p> only when it exactly matches the version on the device.</p>