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

docs: update docs for new screen support attributes and qualifiers

Browse Source 
Change-Id: I8fdfd90e5d7970bdbb72e0b3271f047f5ed300ee
This commit is contained in:
Scott Main
2011-06-22 11:00:29 -07:00
parent 1acd2a7f2b
commit 9a05cfe542
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. -->
<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
@@ -1023,17 +1023,15 @@
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
@@ -1042,9 +1040,9 @@
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

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

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

@@ -8,12 +8,15 @@ parent.link=manifest-intro.html
<dt>syntax:</dt>
<dd>
<pre class="stx">
&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"]
&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"]
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>
</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>
<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.)
<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 fills the entire screen and works as
expected. By default, the system will resize your application to fill the screen, if you have set
<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>However, if your application does not work well when resized to fit different screen sizes,
you can use the attributes of the {@code &lt;supports-screens&gt;} 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&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
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>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>
@@ -59,6 +63,74 @@ screens.</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
@@ -75,6 +147,7 @@ when resized.</p>
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>
@@ -91,6 +164,7 @@ href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targe
{@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>
@@ -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
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
@@ -112,6 +187,7 @@ href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targe
{@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>
@@ -125,7 +201,8 @@ href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targe
{@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>
@@ -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
(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>

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

@@ -335,80 +335,101 @@ indicates the current locale.</p>
</tr>
<tr id="SmallestScreenWidthQualifier">
<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>sw600dp</code><br/>
<code>sw720dp</code><br/>
etc.
</td>
<td>
<p>Specifies a minimum "smallest screen width," in "dp" units, at which the resource
should be used. This configuration value represents the base screen size
of the device, regardless of the orientation of the display. It is based
on the smallest width the application will have in which to perform its
UI layout (in dp units) regardless of the orientation of the screen. The
value here takes into account screen decorations so if the device has some
persistent UI elements on the left or right edge of the display it must
present a value here that is smaller than the real screen size, accounting
for these UI elements reducing the application's available space.</p>
<p>Some values you may use here for common screen sizes:</p>
<p>Specifies the "smallest width" in {@code dp} units that must be available to your
application in order for the resources to be used, regardless of the screen's current
orientation. For example, if your layout requires that its shortest side be at least 600
dp in length at all times, then you can use this to create the layout resources, {@code
res/layout-sw600dp/}, and the system will use them only when the shortest side of
available screen space it at least 600dp.</p>
<p>The width against which the system compares your value 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 its own 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>Some values you might use here for common screen sizes:</p>
<ul>
<li>240x320 ldpi (QVGA phone): 320
<li>320x480 mdpi (phone): 320
<li>480x800 hdpi (high density phone): 320
<li>480x800 mdpi (tablet/phone): 480
<li>600x1024 mdpi (7" tablet): 600
<li>720x1280 mdpi (10" tablet): 720
<li>320, for devices with screen configurations such as:
<ul>
<li>240x320 ldpi (QVGA handset)</li>
<li>320x480 mdpi (handset)</li>
<li>480x800 hdpi (high density handset)</li>
</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>
<p><em>Added in API Level 13.</em></p>
<p>Also see the {@link android.content.res.Configuration#smallestScreenWidthDp}
configuration field, which holds the current smallest screen width.</p>
<p>When your application provides multiple resource directories with different values for
this qualifier, the system uses the one closest to (without exceeding) the smallest width
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>
</tr>
<tr id="ScreenWidthQualifier">
<td>Screen width</td>
<td>Examples:<br/>
<td><code>w&lt;N&gt;dp</code><br/><br/>
Examples:<br/>
<code>w720dp</code><br/>
<code>w1024dp</code><br/>
etc.
</td>
<td>
<p>Specifies a minimum screen width, in "dp" units, at which the resource
should be used. This configuration value will change when the orientation
changes between landscape and portrait to match the current actual width.
When multiple screen width configurations are available, the closest to
the current screen width will be used. The
value here takes into account screen decorations so if the device has some
persistent UI elements on the left or right edge of the display it must
present a value here that is smaller than the real screen size, accounting
for these UI elements reducing the application's available space.</p>
<p><em>Added in API Level 13.</em></p>
<p>Specifies a minimum screen width, in {@code dp} units at which the resource
should be used&mdash;defined by the <code>&lt;N&gt;</code> value. This
configuration value will change when the orientation
changes between landscape and portrait to match the current actual width.</p>
<p>When your application provides multiple resource directories with different values
for this configuration, the system uses the one closest to (without exceeding)
the device's current screen width. The
value here takes into account screen decorations, so if the device has some
persistent UI elements on the left or right edge of the display, it
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}
configuration field, which holds the current screen width.</p>
</td>
</tr>
<tr id="ScreenHeightQualifier">
<td>Screen height</td>
<td>Examples:<br/>
<td><code>h&lt;N&gt;dp</code><br/><br/>
Examples:<br/>
<code>h720dp</code><br/>
<code>h1024dp</code><br/>
etc.
</td>
<td>
<p>Specifies a minimum screen height, in "dp" units, at which the resource
should be used. This configuration value will change when the orientation
changes between landscape and portrait to match the current actual height.
When multiple screen height configurations are available, the closest to
the current screen height will be used. The
value here takes into account screen decorations so if the device has some
persistent UI elements on the left or right edge of the display it must
present a value here that is smaller than the real screen size, accounting
for these UI elements reducing the application's available space. Screen
<p>Specifies a minimum screen height, in "dp" units at which the resource
should be used&mdash;defined by the <code>&lt;N&gt;</code> value. This
configuration value will change when the orientation
changes between landscape and portrait to match the current actual height.</p>
<p>When your application provides multiple resource directories with different values
for this configuration, the system uses the one closest to (without exceeding)
the device's current screen height. The
value here takes into account screen decorations, so if the device has some
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
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.
<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}
configuration field, which holds the current screen width.</p>
</td>
@@ -444,9 +465,9 @@ indicates the current locale.</p>
medium-density HVGA screen. The minimum layout size for this screen configuration
is approximately 720x960 dp units. In most cases, devices with extra large
screens would be too large to carry in a pocket and would most likely
be tablet-style devices. <em>Added in API Level 9.</em></li>
be tablet-style devices. <em>Added in API level 9.</em></li>
</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
Screens</a> for more information.</p>
<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 notlong}: Not long screens, such as QVGA, HVGA, and VGA</li>
</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
is not related to the screen orientation.</p>
<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 desk}: Device is in a desk dock</li>
</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
dock. You can enable or disable this mode using {@link
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 notnight}: Day time</li>
</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
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
@@ -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
to match the device density.</li>
</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
in ldpi is 12x12 in mdpi, 18x18 in hdpi and 24x24 in xhdpi.</p>
<p>When Android selects which resource files to use,
@@ -689,17 +710,17 @@ orientation" described above.</p>
</tr>
-->
<tr id="VersionQualifier">
<td>Platform Version (API Level)</td>
<td>Platform Version (API level)</td>
<td>Examples:<br/>
<code>v3</code><br/>
<code>v4</code><br/>
<code>v7</code><br/>
etc.</td>
<td>
<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
<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.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>
<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
@@ -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
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
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
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>
</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
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
@@ -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
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
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
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
{@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)
@@ -937,7 +958,7 @@ resources).</p>
</li>
</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
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>
@@ -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
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
only when it exactly matches the version on the device.</p>