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

Merge "cherrypick Change-Id: Ib5e8ae7f420e9084e408089d9f5a6574ad95f299 docs: update Support Mult Screens for MR2 features"

Browse Source
This commit is contained in:
Scott Main
2011-07-27 11:36:44 -07:00
committed by Android (Google) Code Review
parent b5eba903b8 db909162b2
commit 6c71b63dc6
7 changed files with 729 additions and 195 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -667,11 +667,14 @@
<li class="toggle-list">
<div><a href="<?cs var:toroot ?>guide/practices/screens_support.html">
<span class="en">Supporting Multiple Screens</span>
</a></div>
</a> <span class="new">updated</span></div>
<ul>
<li><a href="<?cs var:toroot ?>guide/practices/screens-distribution.html">
<span class="en">Distributing to Specific Screens</span>
</a></li>
<li><a href="<?cs var:toroot ?>guide/practices/screen-compat-mode.html">
<span class="en">Screen Compatibility Mode</span>
</a> <span class="new">new!</span></li>
<li><a href="<?cs var:toroot ?>guide/practices/screens-support-1.5.html">
<span class="en">Strategies for Android 1.5</span>
</a></li>

257
docs/html/guide/practices/screen-compat-mode.jd Normal file
View File

@@ -0,0 +1,257 @@
page.title=Screen Compatibility Mode
parent.title=Supporting Multiple Screens
parent.link=screens_support.html
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#Disable">Disabling Screen Compatibility Mode</a></li>
<li><a href="#Enable">Enabling Screen Compatibility Mode</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a></li>
<li><a href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
&lt;supports-screens&gt;}</a></li>
</ol>
</div>
</div>
<div class="figure" style="width:500px;">
<a href="{@docRoot}images/screens_support/compat-zoom.png">
<img src="{@docRoot}images/screens_support/compat-zoom-thumb.png" alt="" />
</a>
<p class="img-caption"><strong>Figure 1.</strong> An application running in compatibility mode
on an Android 3.2 tablet.</p>
</div>
<div class="figure" style="width:500px;">
<a href="{@docRoot}images/screens_support/compat-stretch.png">
<img src="{@docRoot}images/screens_support/compat-stretch-thumb.png" alt="" />
</a>
<p class="img-caption"><strong>Figure 2.</strong> The same application from figure 1, with
compatibility mode disabled.</p>
</div>
<p class="caution"><strong>Notice:</strong> If you've developed an application for a version of
Android lower than Android 3.0, but it does resize properly for larger screens such as tablets, you
should disable screen compatibility mode in order to maintain the best user experience. To learn how
to quickly disable the user option, jump to <a href="#Disable">Disabling Screen Compatibility
Mode</a>.</p>
<p>Screen compatibility mode is an escape hatch for applications that are not properly designed
to resize for larger screens such as tablets. Since Android 1.6, Android has supported a
variety of screen sizes and does most of the work to resize application layouts so that they
properly fit each screen. However, if your application does not successfully follow the guide to
<a href="{@docRoot}guide/topics/practices/screens_support.html">Supporting Multiple Screens</a>,
then it might encounter some rendering issues on larger screens. For applications with this
problem, screen compatibility mode can make the application a little more usable on larger
screens.</p>
<p>There are two versions of screen compatibility mode with slightly different behaviors:</p>
<dl>
<dt>Version 1 (Android 1.6 - 3.1)</dt>
<dd>The system draws the application's UI in a "postage stamp"
window. That is, the system draws the application's layout the same as it would on a
normal size handset (emulating a 320dp x 480dp screen), with a black border that fills
the remaining area of the screen.
<p>This was introduced with Android 1.6 to handle apps that were designed only for the
original screen size of 320dp x 480dp. Because there are so few active devices remaining that run
Android 1.5, almost all applications should be developed against Android 1.6 or greater and
should not have version 1 of screen compatibility mode enabled for larger screens. This version
is considered obsolete.</p>
<p>To disable this version of screen compatibility mode, you simply need to set <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code
android:minSdkVersion}</a> or <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code
android:targetSdkVersion}</a> to {@code "4"} or higher, or set <a
href="guide/topics/manifest/supports-screens-element.html#resizeable">{@code
android:resizeable}</a> to {@code "true"}.</p>
</dd>
<dt>Version 2 (Android 3.2 and greater)</dt>
<dd>The system draws the application's layout the same as
it would on a normal size handset (approximately emulating a 320dp x 480dp screen), then scales it
up to fill the screen. This essentially "zooms" in on your layout to make it bigger,
which will usually cause artifacts such as blurring and pixelation in your UI.
<p>This was introduced with Android 3.2 to further
assist applications on the latest tablet devices when the applications have not yet
implemented techniques for <a
href="{@docRoot}guide/topics/practices/screens_support.html">Supporting Multiple
Screens</a>.</p>
<p>In general, large screen devices running Android 3.2 or higher allow users to enable
screen compatibility mode when the application does not <strong>explicitly declare that it supports
large screens</strong> in the manifest file. When this is the case, an icon (with
outward-pointing arrows) appears next to the clock in the system bar, which allows the user to
toggle screen compatibility mode on and off (figure 3). An application can also explicitly
declare that it <em>does not</em> support large screens such that screen compatibility mode
is always enabled and the user cannot disable it. (How to declare your application's
support for large screens is discussed in the following sections.)</p></dd>
</dl>
<img src="{@docRoot}images/screens_support/compat-toggle.png" alt="" />
<p class="img-caption"><strong>Figure 3.</strong> The pop up menu to toggle screen compatibility
mode (currently disabled, so normal resizing occurs).</p>
<p>As a developer, you have control over when your application uses screen compatibility mode. The
following sections describe how you can choose to disable or enable screen compatibility mode for
larger screens when running Android 3.2 or higher.</p>
<h2 id="Disable">Disabling Screen Compatibility Mode</h2>
<p>If you've developed your application primarily for versions of Android lower than 3.0, but
<strong>your application does resize properly</strong> for larger screens such as tablets,
<strong>you should disable screen compatibility mode</strong> in order to maintain the best user
experience. Otherwise, users may enable screen compatibility mode and experience your application in
a less-than-ideal format.</p>
<p>By default, screen compatibility mode for devices running Android 3.2 and higher is offered to
users as an optional feature when one of the following is true:</p>
<ul>
<li>Your application has set both <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a>
and <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code
android:targetSdkVersion}</a> to {@code "10"} or lower and <strong>does not explicitly
declare support</strong> for large screens using the <a
href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
&lt;supports-screens&gt;}</a> element.</li>
<li>Your application has set either <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a>
or <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code
android:targetSdkVersion}</a> to {@code "11"} or higher and <strong>explicitly declares that it does
not support</strong> large screens, using the <a
href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
&lt;supports-screens&gt;}</a> element.</li>
</ul>
<p>To completely disable the user option for screen compatibility mode and remove the icon in the
system bar, you can do one of the following:</p>
<ul>
<li><strong>Easiest:</strong>
<p>In your manifest file, add the <a
href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
&lt;supports-screens&gt;}</a> element and specify the <a
href="{@docRoot}guide/topics/manifest/supports-screens-element.html#xlarge">{@code
android:xlargeScreens}</a> attribute to {@code "true"}:</p>
<pre>
&lt;supports-screens android:xlargeScreens="true" /&gt;
</pre>
<p>That's it. This declares that your application supports all larger screen sizes, so the
system will always resize your layout to fit the screen. This works regardless of what values
you've set in the <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code &lt;uses-sdk&gt;}</a>
attributes.</p>
</li>
<li><strong>Easy but has other effects:</strong>
<p>In your manifest's <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code &lt;uses-sdk&gt;}</a>
element, set <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code
android:targetSdkVersion}</a> to {@code "11"} or higher:</p>
<pre>
&lt;uses-sdk android:minSdkVersion="4" android:targetSdkVersion="11" /&gt;
</pre>
<p>This declares that your application supports Android 3.0 and, thus, is designed to
work on larger screens such as tablets.</p>
<p class="caution"><strong>Caution:</strong> When running on Android 3.0 and greater, this also
has the effect of enabling the Holographic theme for you UI, adding the <a
href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> to your activities, and removing the
Options Menu button in the system bar.</p>
<p>If screen compatibility mode is still enabled after you change this, check your manifest's <a
href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
&lt;supports-screens&gt;}</a> and be sure that there are no attributes set {@code "false"}. The best
practice is to always explicitly declare your support for different screen sizes using the <a
href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
&lt;supports-screens&gt;}</a> element, so you should use this element anyway.</p>
<p>For more information about updating your application to target Android 3.0 devices, read <a
href="{@docRoot}guide/practices/optimizing-for-3.0.html">Optimizing Apps for Android
3.0</a>.</p>
</li>
<!--
<li><strong>Most control</strong> (but you must compile against Android 3.2 or higher):
<p>In your manifest file, add the <a
href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
&lt;supports-screens&gt;}</a> element and specify the {@code android:compatibleWidthLimitDp}
attribute to any value <em>higher than</em> {@code "320"}:</p>
<pre>
&lt;supports-screens android:compatibleWidthLimitDp="720" /&gt;
</pre>
<p>Using this technique allows you to specify exactly what your application's limit is for
layout resizing. Normally, only applications that are already built against Android 3.2 (or
higher) use this attribute, because the primary intention is to specify at what size should screen
compatibility mode actually be offered to users.</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 to any device if
your value for {@code android:compatibleWidthLimitDp} is larger than 320.</p>
</li>
-->
</ul>
<h2 id="Enable">Enabling Screen Compatibility Mode</h2>
<p>When your application is targeting Android 3.2 (API level 13) or higher, you can affect
whether compatibility mode is enabled for certain screens by using the <a
href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
&lt;supports-screens>}</a> element.</p>
<p class="note"><strong>Note:</strong> Screen compatibility mode is <strong>not</strong> a mode in
which you should want your application to run&mdash;it causes pixelation and blurring in your UI,
due to zooming. The proper way to make your application work well on large screens is to follow the
guide to <a
href="{@docRoot}guide/topics/practices/screens_support.html">Supporting Multiple Screens</a> and
provide alternative layouts for different screen sizes.</p>
<p>By default, when you've set either <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code
android:minSdkVersion}</a> or <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code
android:targetSdkVersion}</a> to {@code "11"} or higher, screen compatibility mode is
<strong>not</strong> available to users. If either of these are true and your application does not
resize properly for larger screens, you can choose to enable screen compatibility mode in one
of the following ways:</p>
<ul>
<li>In your manifest file, add the <a
href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
&lt;supports-screens&gt;}</a> element and specify the <a
href="{@docRoot}guide/topics/manifest/supports-screens-element.html#compatibleWidth">{@code
android:compatibleWidthLimitDp}</a> attribute to {@code "320"}:</p>
<pre>
&lt;supports-screens android:compatibleWidthLimitDp="320" /&gt;
</pre>
<p>This indicates that the maximum "smallest screen width" for which your application is designed
is 320dp. This way, any devices with their smallest side being larger than this value will offer
screen compatibility mode as a user-optional feature.</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 to any device if
your value for <a
href="{@docRoot}guide/topics/manifest/supports-screens-element.html#compatibleWidth">{@code
android:compatibleWidthLimitDp}</a> is larger than 320.</p>
</li>
<li>If your application is functionally broken when resized for large screens and you want to
force users into screen compatibility mode (rather than simply providing the option), you can use
the <a href="{@docRoot}guide/topics/manifest/supports-screens-element.html#largestWidth">{@code
android:largestWidthLimitDp}</a> attribute:
<pre>
&lt;supports-screens android:largestWidthLimitDp="320" /&gt;
</pre>
<p>This works the same as <a
href="{@docRoot}guide/topics/manifest/supports-screens-element.html#compatibleWidth">{@code
android:compatibleWidthLimitDp}</a> except it force-enables
screen compatibility mode and does not allow users to disable it.</p>
</li>
</ul>

6
docs/html/guide/practices/screens-distribution.jd
View File

@@ -144,9 +144,9 @@ href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
with <em>larger</em> screens) and set the larger screen size attributes to {@code "false"}, then
external services such as Android Market <strong>do not</strong> apply filtering. Your application
will still be available to larger screens, but when it runs, it will not resize to fit the screen.
Instead, the system will draw it in a "postage stamp" window that's the same relative size as the
screen size that your application does support (see <a
href="screens-support-1.5.html#CompatMode">compatibility mode</a> for more information). If you want
Instead, the system will emulate a handset screen size (about 320dp x 480dp; see <a
href="{@docRoot}guide/practices/screen-compat-mode.html">Screen Compatibility Mode</a> for more
information). If you want
to prevent your application from being downloaded on larger screens, use <a
href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">{@code
&lt;compatible-screens>}</a>, as discussed in the previous section about <a

47
docs/html/guide/practices/screens-support-1.5.jd
View File

@@ -18,7 +18,6 @@ an application designed for Android 1.5</li>
<h2>In this document</h2>
<ol>
<li><a href="#strategies">Adding Multiple Screens Support</a></li>
<li><a href="#CompatMode">Compatibility Mode</a></li>
</ol>
<h2>See also</h2>
@@ -47,11 +46,13 @@ android:targetSdkVersion}</a> set to {@code "4"} or higher, then this document i
default, an application written for Android 1.5 or below that does not set the <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code
android:targetSdkVersion}</a> set to {@code "4"} or higher runs in <a
href="#CompatMode">compatibility mode</a> when on a device with a screen larger than the
href="screen-compat-mode">screen compatibility mode</a> when on a device with a screen larger than
the
<em>normal</em> screen size (basically, the system displays the application in a small window
that is roughly the size of the normal screen size).</p>
<p>This document describes how to get your application out of <a href="#CompatMode">compatibility
<p>This document describes how to get your application out of <a
href="screen-compat-mode.html">screen compatibility
mode</a> and instead support multiple screens, but also maintain compatibility with Android 1.5 and
below.</p>
@@ -144,43 +145,3 @@ Android 3.0 and use the WXGA emulator skin.</p>
href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a> to add
complete support for different screen configurations.</p>
<h2 id="CompatMode">Compatibility Mode</h2>
<div class="figure" style="width:450px;margin:0">
<img src="{@docRoot}images/screens_support/compat-mode-on.png" alt="" />
<p class="img-caption"><strong>Figure 1.</strong> An application running in compatibility mode
on an extra large screen.</p>
</div>
<p>To allow applications to run on larger screens without stretching the UI, Android provides a
compatibility mode that draws an application's UI in a "postage stamp" window when on larger
screens. That is, the system displays the application at the baseline size (<em>normal</em>) and
density (<em>mdpi</em>), with a black border that fills the rest of the screen.</p>
<p>Compatibility mode exists primarily to support application's developed for Android 1.5 (or lower)
when running on larger screens, because multiple screen support was not added until Android 1.6,
older applications were not designed to support different screen configurations.</p>
<p>As such, if you've set your <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code
android:minSdkVersion}</a> to {@code "3"} or lower and have <em>not</em> set the <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code
android:targetSdkVersion}</a> to {@code "4"} or higher, then compatibility mode is enabled and
the system will not scale your application, because your application implicitly declares that it
only supports the baseline screen configuration (normal screen size and medium density).</p>
<p>To disable compatibility mode, set either <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code
android:minSdkVersion}</a> or <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code
android:targetSdkVersion}</a> to {@code "4"} or higher. For more information, see the previous
section about <a href="#strategies">Adding Multiple Screens Support</a>.</p>
<p>You can also affect whether compatibility mode is enabled by using the <a
href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
&lt;supports-screens>}</a> element (you can enable it by setting {@code android:resizeable} or
specific screen sizes to {@code "false"}). However, you should not explicitly enable compatibility
mode for your application, but should instead apply the necessary techniques to <a
href="{@docRoot}guide/practices/screens_support.html">supporting multiple screens</a> and allow your
application to properly fit the screen on all screen sizes.</p>

345
docs/html/guide/practices/screens_support.jd
View File

@@ -25,6 +25,13 @@ page.title=Supporting Multiple Screens
<li><a href="#qualifiers">Using configuration qualifiers</a></li>
<li><a href="#DesigningResources">Designing alternative layouts and drawables</a></li>
</ol></li>
<li><a href="#DeclaringTabletLayouts">Declaring Tablet Layouts for Android 3.2</a> <span
class="new">new!</span>
<ol>
<li><a href="#NewQualifiers">Using new size qualifiers</a></li>
<li><a href="#ConfigurationExamples">Configuration examples</a></li>
<li><a href="#DeclaringScreenSizeSupport">Declaring screen size support</a></li>
</ol></li>
<li><a href="#screen-independence">Best Practices</a></li>
<li><a href="#DensityConsiderations">Additional Density Considerations</a>
<ol>
@@ -57,15 +64,15 @@ Guidelines</a></li>
applications, the Android system provides a consistent development environment across devices and
handles most of the work to adjust each application's user interface to the screen on which it is
displayed. At the same time, the system provides APIs that allow you to control your
application's UI on specific screen sizes and densities, in order to modify and optimize your UI
application's UI for specific screen sizes and densities, in order to optimize your UI
design for different screen configurations. For example, you might want a UI for tablets
that's different from the design for handsets.</p>
that's different from the UI for handsets.</p>
<p>Although the system performs sufficient scaling and resizing to make your application work on
<p>Although the system performs scaling and resizing to make your application work on
different screens, you should make the effort to optimize your application for different screen
sizes and densities. In doing so, you maximize the user experience for all devices and your users
believe that your application was actually designed for <em>their</em> devices&mdash;rather than
simply stretched to fit their devices.</p>
simply stretched to fit the screen on their devices.</p>
<p>By following the practices described in this document, you can create an application that
displays properly and provides an optimized user experience on all supported screen configurations,
@@ -74,7 +81,14 @@ using a single {@code .apk} file.</p>
<p class="note"><strong>Note:</strong> The information in this document assumes that your
application is designed for Android 1.6 (API Level 4) or higher. If your application supports
Android 1.5 or lower, please first read <a
href="{@docRoot}guide/practices/screens-support-1.5.html">Strategies for Android 1.5</a>.</p>
href="{@docRoot}guide/practices/screens-support-1.5.html">Strategies for Android 1.5</a>.
<br/><br/>
Also, be aware that <strong>Android 3.2 has introduced new APIs</strong> that allow you to more
precisely control the layout resources your application uses for different screen sizes. These new
features are especially important if you're developing an application that's optimized for tablets.
For details, see the section about <a href="#DeclaringTabletLayouts">Declaring Tablet Layouts for
Android 3.2</a>.
</p>
@@ -143,9 +157,16 @@ the range of actual screen sizes and densities into:</p>
<li>A set of four generalized <strong>sizes</strong>: <em>small</em>, <em>normal</em>,
<em>large</em>,
and <em>xlarge</em></em>
<p class="note"><strong>Note:</strong> Beginning with Android 3.2 (API level 13), these size groups
are deprecated in favor of a new technique for managing screen sizes based on the available screen
width. If you're developing for Android 3.2 and greater, see <a
href="#DeclaringTabletLayouts">Declaring Tablet Layouts for Android 3.2</a> for more
information.</p>
</li>
<li>A set of four generalized <strong>densities</strong>: <em>ldpi</em> (low), <em>mdpi</em>
(medium),
<em>hdpi</em> (high), and <em>xhdpi</em> (extra high)
</li>
</ul>
<p>The generalized sizes and densities are arranged around a
@@ -154,7 +175,7 @@ baseline is based upon the screen configuration for the first Android-powered de
G1, which has an HVGA screen (until Android 1.6, this was the only screen configuration that Android
supported).</p>
<p>Each generalized size or density spans a range of actual screen sizes or density. For example,
<p>Each generalized size and density spans a range of actual screen sizes and densities. For example,
two devices that both report a screen size of <em>normal</em> might have actual screen sizes and
aspect ratios that are slightly different when measured by hand. Similarly, two devices that report
a screen density of <em>hdpi</em> might have real pixel densities that are slightly different.
@@ -168,11 +189,30 @@ and density groups.</p>
Illustration of how Android roughly maps actual sizes and densities
to generalized sizes and densities (figures are not exact).</p>
<p>As you design your UI for different screen sizes, you'll discover that each design requires a
minimum amount of space. So, each generalized screen size above has an associated minimum
resolution that's defined by the system. These minimum sizes are in "dp" units&mdash;the same units
you should use when defining your layouts&mdash;which allows the system to avoid worrying about
changes in screen density.</p>
<ul>
<li><em>xlarge</em> screens are at least 960dp x 720dp</li>
<li><em>large</em> screens are at least 640dp x 480dp</li>
<li><em>normal</em> screens are at least 470dp x 320dp</li>
<li><em>small</em> screens are at least 426dp x 320dp</li>
</ul>
<p class="note"><strong>Note:</strong> These minimum screen sizes were not as well defined prior to
Android 3.0, so you may encounter some devices that are mis-classified between normal and large.
These are also based on the physical resolution of the screen, so may vary across devices&mdash;for
example a 1024x720 tablet with a system bar actually has a bit less space available to the
application due to it being used by the system bar.</p>
<p>To optimize your application's UI for the different screen sizes and densities, you can provide
<a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">alternative
resources</a> for any of the generalized sizes and densities. Typically, you should
provide alternative layouts for some of the different screen sizes and alternative bitmap images for
different screen densities. At runtime, the system uses the appropriate size or density resources
different screen densities. At runtime, the system uses the appropriate resources
for your application, based on the generalized size or density of the current device screen.</p>
<p>You do not need to provide alternative resources for every combination of screen size and
@@ -221,7 +261,7 @@ density, if necessary</li>
</ul>
<p>In figure 2, the text view and bitmap drawable have dimensions specified in pixels ({@code px}
units), so the elements are physically larger on a low density screen and smaller on a high density
units), so the views are physically larger on a low density screen and smaller on a high density
screen. This is because although the actual screen sizes may be the same, the high density screen
has more pixels per inch (the same amount of pixels fit in a smaller area). In figure 3, the layout
dimensions are specified in density-independent pixels ({@code dp} units). Because the baseline for
@@ -255,6 +295,18 @@ for the screen density, as appropriate. To more gracefully handle different scre
however, you should also:</p>
<ul>
<li><strong>Explicitly declare in the manifest which screen sizes your application
supports</strong>
<p>By declaring which screen sizes your application supports, you can ensure that only
devices with the screens you support can download your application. Declaring support for
different screen sizes can also affect how the system draws your application on larger
screens&mdash;specifically, whether your application runs in <a
href="{@docRoot}guide/practices/screen-compat-mode.html">screen compatibility mode</a>.</p>
<p>To declare the screen sizes your application supports, you should include the
<a href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
&lt;supports-screens&gt;}</a> element in your manifest file.</p>
</li>
<li><strong>Provide different layouts for different screen sizes</strong>
<p>By default, Android resizes your application layout to fit the current device screen. In most
cases, this works fine. In other cases, your UI might not look as good and might need adjustments
@@ -264,6 +316,12 @@ you might need to adjust sizes so that everything can fit on the screen.</p>
<p>The configuration qualifiers you can use to provide size-specific resources are
<code>small</code>, <code>normal</code>, <code>large</code>, and <code>xlarge</code>. For
example, layouts for an extra large screen should go in {@code layout-xlarge/}.</p>
<p>Beginning with Android 3.2 (API level 13), the above size groups are deprecated and you
should instead use the {@code sw&lt;N&gt;dp} configuration qualifier to define the smallest
available width required by your layout resources. For example, if your multi-pane tablet layout
requires at least 600dp of screen width, you should place it in {@code layout-sw600dp/}. Using the
new techniques for declaring layout resources is discussed further in the section about <a
href="#DeclaringTabletLayouts">Declaring Tablet Layouts for Android 3.2</a>.</p>
</li>
<li><strong>Provide different bitmap drawables for different screen densities</strong>
@@ -432,6 +490,12 @@ configuration.</td>
</tr>
</table>
<p class="note"><strong>Note:</strong> If you're developing your application for Android 3.2 and
higher, see the section about <a
href="#DeclaringTabletLayouts">Declaring Tablet Layouts for Android 3.2</a> for information about
new configuration qualifiers that you should use when declaring layout resources for specific
screen sizes (instead of using the size qualifiers in table 1).</p></p>
<p>For more information about how these qualifiers roughly correspond to real screen
sizes and densities, see <a href="#range">Range of Screens Supported</a>, earlier in this
document.</p>
@@ -554,6 +618,267 @@ icons, status bar icons, tab icons, and more.</p>
<h2 id="DeclaringTabletLayouts">Declaring Tablet Layouts for Android 3.2</h2>
<p>For the first generation of tablets running Android 3.0, the proper way to declare tablet
layouts was to put them in a directory with the {@code xlarge} configuration qualifier (for example,
{@code res/layout-xlarge/}). In order to accommodate other types of tablets and screen
sizes&mdash;in particular, 7" tablets&mdash;Android 3.2 introduces a new way to specify resources
for more discrete screen sizes. The new technique is based on the amount of space your layout needs
(such as 600dp of width), rather than trying to make your layout fit generalized size groups (such
as <em>large</em> or <em>xlarge</em>).</p>
<p>The reason designing for 7" tablets is tricky when using the generalized size groups is
that a 7" tablet is technically in the same group as a 5" handset (the <em>large</em> group). While
these two devices are seemingly close to each other in size, the amount of space for an
application's UI is significantly different, as is the style of user interaction. Thus, a 7" and 5"
screen should not always use the same layout. To make it possible for these two kinds of screens to
offer different layouts, Android now allows you to specify your layout resources based on the width
and/or height that's actually available for your application's layout, specified in dp units.</p>
<p>For example, after you've designed the layout you want to use for tablet-style devices, you might
determine that the layout stops working well when the screen is less than 600dp wide. This threshold
thus becomes the minimum size that you require for your tablet layout. As
such, you can now specify that these layout resources should be used only when there is at least
600dp of width available for your application's UI.</p>
<p>You should either pick a width and design to it as your minimum size, or test what is the
smallest width your layout supports once it's complete.</p>
<h3 id="NewQualifiers">Using new size qualifiers</h3>
<p>The numbers describing the width and height available for your layout are all in dp
units&mdash;remember that your layout dimensions should always be defined using dp units,
because what you care about is the amount of space available after the system accounts for screen
density (as opposed to using raw pixel numbers). The different resource configurations that you can
specify based on the space available for your layout are summarized in table 2. When building an
application for Android 3.2 and higher, you should use these new qualifiers instead of those for the
traditional screen size groups (small, normal, large, and xlarge).</p>
<p class="note"><strong>Note:</strong> The sizes that you specify using these qualifiers are
<strong>not the actual screen sizes</strong>. Rather, the sizes are for the width or height in dp
units that are <strong>available to your activity's window</strong>. The Android system
might use some of the screen for system UI (such as the system bar at the bottom of the screen or
the status bar at the top), so some of the screen might not be available for your layout. Thus, the
sizes you declare should be specifically about the sizes needed by your activity&mdash;the system
accounts for any space used by system UI when declaring how much space it provides for your layout.
Also beware that the <a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> is considered
a part of your application's window space, although your layout does not declare it, so it reduces
the space available for your layout and you must account for it in your design.</p>
<p class="table-caption"><strong>Table 2.</strong> New configuration qualifers for screen size
(introduced in Android 3.2).</p>
<table>
<tr><th>Screen configuration</th><th>Qualifier values</th><th>Description</th></tr>
<tr><td>Smallest available width</td>
<td><code>sw&lt;N&gt;dp</code><br/><br/>
Examples:<br/>
<code>sw600dp</code><br/>
<code>sw720dp</code><br/>
</td>
<td>
<p>Specifies the "smallest width" in dp units that must be available to your
application in order for the resources to be used&mdash;defined by the <code>&lt;N&gt;</code>
value&mdash;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 put your layout files in <code>res/layout-sw600dp/</code> and
the system will use them only when the shortest side of available screen space it at least
600dp.</p>
<p>This is the most important size configuration value, because it replaces the old screen size
buckets with a discrete number that specifies the effective size available for your UI. This number
is based on width because that is most often the driving factor in designing a layout. A UI will
often scroll vertically, but have fairly hard constraints on the minimum space it needs
horizontally. The available width is also the key factor in determining whether to use a one-pane
layout for handsets or multi-pane layout for tablets.</p>
</td>
</tr>
<tr>
<td>Available width</td>
<td><code>w&lt;N&gt;dp</code><br/><br/>
Examples:<br/>
<code>w720dp</code><br/>
<code>w1024dp</code><br/>
</td>
<td>
<p>Specifies a minimum available width in dp units at which the resources should be
used&mdash;defined by the <code>&lt;N&gt;</code> value. The system's corresponding value for the
width changes when the screen's orientation switches between landscape and portrait to
reflect the current actual width that's available for your UI.</p>
<p>This is often useful to determine whether to use a multi-pane layout, because even on a
tablet device, you often won't want the same multi-pane layout for portrait orientation as you do
for landscape. Thus, you can use this to specify the minimum width required for the layout, instead
of using both the screen size and orientation qualifiers together.</p>
</td>
</tr>
<tr>
<td>Available height</td>
<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 resources should be
used&mdash;defined by the <code>&lt;N&gt;</code> value. The system's corresponding value for
the height changes when the screen's orientation switches between landscape and portrait to
reflect the current actual height that's available for your UI.</p>
<p>Using this to define the
height required by your layout is useful in the same way as <code>w&lt;N&gt;dp</code> is for
defining the required width, instead of using both the screen size and orientation qualifiers.
However, most apps won't need this qualifier, considering that UIs often scroll vertically and are
thus more flexible with how much height is available, whereas the width is more rigid.</p>
</td>
</tr>
</table>
<p>While using these qualifiers might seem more complicated than using screen size groups, it should
actually be simpler once you determine the requirements for your UI. When you design your UI,
the main thing you probably care about is the actual size at which your application switches between
a handset-style UI and a tablet-style UI that uses multiple panes. The exact point of this switch
will depend on your particular design&mdash;maybe you need a 720dp width for your tablet layout,
maybe 600dp is enough, or 480dp, or some number between these. Using these qualifiers in table 2,
you are in control of the precise size at which your layout changes.</p>
<h3 id="ConfigurationExamples">Configuration examples</h3>
<p>To help you target some of your designs for different types of devices, here are some
numbers for typical screen widths:</p>
<ul>
<li>320dp: a typical phone screen (240x320 ldpi, 320x480 mdpi, 480x800 hdpi, etc).</li>
<li>480dp: a tweener tablet like the Streak (480x800 mdpi).</li>
<li>600dp: a 7” tablet (600x1024 mdpi).</li>
<li>720dp: a 10” tablet (720x1280 mdpi, 800x1280 mdpi, etc).</li>
</ul>
<p>Using the size qualifiers from table 2, your application can switch between your different layout
resources for handsets and tablets using any number you want for width and/or height. For example,
if 600dp is the smallest available width supported by your tablet layout, you can provide these two
sets of layouts:</p>
<pre class="classic">
res/layout/main_activity.xml # For handsets
res/layout-sw600dp/main_activity.xml # For tablets
</pre>
<p>In this case, the smallest width of the available screen space must be 600dp in order for the
tablet layout to be applied.</p>
<p>For other cases in which you want to further customize your UI to differentiate between sizes
such as 7” and 10” tablets, you can define additional smallest width layouts:</p>
<pre class="classic">
res/layout/main_activity.xml # For handsets (smaller than 600dp available width)
res/layout-sw600dp/main_activity.xml # For 7” tablets (600dp wide and bigger)
res/layout-sw720dp/main_activity.xml # For 10” tablets (720dp wide and bigger)
</pre>
<p>Notice that the previous two sets of example resources use the "smallest width" qualifer, {@code
sw&lt;N&gt;dp}, which specifies the smallest of the screen's two sides, regardless of the
device's current orientation. Thus, using {@code sw&lt;N&gt;dp} is a simple way to specify the
overall screen size available for your layout by ignoring the screen's orientation.</p>
<p>However, in some cases, what might be
important for your layout is exactly how much width or height is <em>currently</em> available. For
example, if you have a two-pane layout with two fragments side by side, you might want to use it
whenever the screen provides at least 600dp of width, whether the device is in landscape or
portrait orientation. In this case, your resources might look like this:</p>
<pre class="classic">
res/layout/main_activity.xml # For handsets (smaller than 600dp available width)
res/layout-w600dp/main_activity.xml # Multi-pane (any screen with 600dp available width or more)
</pre>
<p>Notice that the second set is using the "available width" qualifier, {@code w&lt;N&gt;dp}. This
way, one device may actually use both layouts, depending on the orientation of the screen (if
the available width is at least 600dp in one orientation and less than 600dp in the other
orientation).</p>
<p>If the available height is a concern for you, then you can do the same using the {@code
h&lt;N&gt;dp} qualifier. Or, even combine the {@code w&lt;N&gt;dp} and {@code h&lt;N&gt;dp}
qualifiers if you need to be really specific.</p>
<h3 id="DeclaringScreenSizeSupport">Declaring screen size support</h3>
<p>Once you've implemented your layouts for different screen sizes, it's equally important that you
declare in your manifest file which screens your application supports.</p>
<p>Along with the new configuration qualifiers for screen size, Android 3.2 introduces new
attributes for the <a
href="{@docRoot}guide/topics/manifest/supports-screens-element.html">&lt;supports-screens&gt;</a>
manifest element:</p>
<dl>
<!--
#### Sorry, Android Market does not yet support filtering based on this element. ####
<dt><a
href="{@docRoot}guide/topics/manifest/supports-screens-element.html#requiresSmallest">
{@code android:requiresSmallestWidthDp}</a></dt>
<dd>This attribute specifies the minimum "smallest 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>For example, if your application is only for tablet-style devices with a 600dp
smallest available width:</p>
<pre>
&lt;manifest ... &gt;
&lt;supports-screens android:requiresSmallestWidthDp="600" /&gt;
...
&lt;/manifest&gt;
</pre>
<p>However, if your application supports all screen sizes supported by Android (as small as
426dp x 320dp), then you don't need to declare this attribute, because the smallest width your
application requires is the smallest possible on any device.</p>
</dd>
-->
<dt><a
href="{@docRoot}guide/topics/manifest/supports-screens-element.html#compatibleWidth">
{@code android:compatibleWidthLimitDp}</a></dt>
<dd>This attribute allows you to enable <a
href="{@docRoot}guide/practices/screen-compat-mode.html">screen compatibility mode</a> as a
user-optional feature by specifying the maximum "smallest width" that your application
supports. If the smallest side of a device's available screen is greater than your value here,
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 users to toggle screen compatibility
mode on and off.
<p class="note"><strong>Note:</strong> If your application's layout properly resizes for large
screens, you do not need to use this attribute. We recommend that you avoid using this
attribute and instead ensure your layout resizes for larger screens by following the
recommendations in this document.</p></dd>
<dt><a
href="{@docRoot}guide/topics/manifest/supports-screens-element.html#largestWidth">
{@code android:largestWidthLimitDp}</a></dt>
<dd>This attribute allows you to force-enable <a
href="{@docRoot}guide/practices/screen-compat-mode.html">screen compatibility mode</a> by specifying
the maximum "smallest width" that your application supports. If the smallest
side of a device's available screen is greater than your value here, the application runs in screen
compatibility mode with no way for the user to disable it.
<p class="note"><strong>Note:</strong> If your application's layout properly resizes for large
screens, you do not need to use this attribute. We recommend that you avoid using this
attribute and instead ensure your layout resizes for larger screens by following the
recommendations in this document.</p></dd>
</dl>
<p class="caution"><strong>Caution:</strong> When developing for Android 3.2 and higher, you
should not use the older screen size attributes in combination with the attributes
listed above. Using both the new attributes and the older size attributes might cause
unexpected behavior.</p>
<p>For more information about each of these attributes, follow the respective links above.</p>
<h2 id="screen-independence">Best Practices</h2>
<p>The objective of supporting multiple screens is to create an application that can function
@@ -875,7 +1200,7 @@ SDK Manager.exe} from your Android SDK directory (on Windows only) or execute {@
the {@code &lt;sdk&gt;/tools/} directory (on all platforms). Figure 6 shows the Android SDK and
AVD Manager with a selection of AVDs, for testing various screen configurations.</p>
<p>Table 2 shows the various emulator skins that are available in the Android SDK, which you can use
<p>Table 3 shows the various emulator skins that are available in the Android SDK, which you can use
to emulate some of the most common screen configurations.</p>
<p>For more information about creating and using AVDs to test your application, see <a
@@ -883,7 +1208,7 @@ href="{@docRoot}guide/developing/devices/managing-avds.html">Managing AVDs with
Manager</a>.</p>
<p class="table-caption" id="screens-table"><strong>Table 2.</strong> Various screen
<p class="table-caption" id="screens-table"><strong>Table 3.</strong> Various screen
configurations available from emulator skins in the Android SDK (indicated in bold) and other
representative resolutions.</p>

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

@@ -8,15 +8,15 @@ parent.link=manifest-intro.html
<dt>syntax:</dt>
<dd>
<pre class="stx">
&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"]
&lt;supports-screens android:<a href="#resizeable">resizeable</a>=["true"| "false"]
android:<a href="#small">smallScreens</a>=["true" | "false"]
android:<a href="#normal">normalScreens</a>=["true" | "false"]
android:<a href="#large">largeScreens</a>=["true" | "false"]
android:<a href="#xlarge">xlargeScreens</a>=["true" | "false"]
android:<a href="#any">anyDensity</a>=["true" | "false"] /&gt;
android:<a href="#any">anyDensity</a>=["true" | "false"]
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>"/&gt;
</pre>
</dd>
@@ -24,37 +24,38 @@ 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 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.
<dd>Lets you specify the screen sizes your application supports and enable <a
href="{@docRoot}guide/practices/screen-compat-mode.html">screen compatibility mode</a> for screens
larger than what your application supports. It's important that you always use this element in your
application to specify the screen sizes your application supports.
<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. 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 to fit the current screen, you can
optimize your UI for different screen sizes by providing <a
Normal resizing applied by the system 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. However, it's
often important that you optimize your application's 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>
layout resources</a>. For instance, you might want to modify the layout of an activity
when it is on a tablet compared to when running on a handset device.</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>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 ("zoomed") to fit
larger screens using the system's <a
href="{@docRoot}guide/practices/screen-compat-mode.html">screen compatibility mode</a>. When you
have not designed for larger screen sizes and the normal resizing does not achieve the appropriate
results, screen compatibility mode will scale your UI by emulating a <em>normal</em> size
screen and medium density, then zooming in so that it fills the entire screen. Beware that this
causes pixelation and blurring of your UI, so it's better if you optimize your UI for large
screens.</p>
<p class="note"><strong>Note:</strong> Android 3.2 introduces new attributes: {@code
android:requiresSmallestWidthDp}, {@code android:compatibleWidthLimitDp}, and {@code
android:largestWidthLimitDp}. If you're developing your application for Android 3.2 and higher,
you should use these attributes to declare your screen size support, instead of the attributes
based on generalized screen sizes.</p>
<p>For more information about how to properly support different screen sizes so that you can avoid
using screen compatibility mode, read
using screen compatibility mode with your application, read
<a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a>.</p>
@@ -62,12 +63,87 @@ using screen compatibility mode, read
<dd>
<dl class="attr">
<dt><a name="resizeable"></a>{@code android:resizeable}</dt>
<dd>Indicates whether the application is resizeable for different screen sizes. This attribute is
true, by default. If set false, the system will run your application in <a
href="{@docRoot}guide/practices/screen-compat-mode.html">screen compatibility mode</a> on large
screens.</p>
<p><strong>This attribute is deprecated</strong>. It was introduced to help applications
transition from Android 1.5 to 1.6, when support for multiple screens was first introduced. You
should not use it.</p>
</dd>
<dt><a name="small"></a>{@code android:smallScreens}</dt>
<dd>Indicates whether the application supports smaller screen form-factors.
A small screen is defined as one with a smaller aspect ratio than
the "normal" (traditional HVGA) screen. An application that does
not support small screens <em>will not be available</em> for
small screen devices from external services (such as Android Market), because there is little
the platform can do to make such an application work on a smaller screen. This is {@code "true"} by
default.
</dd>
<dt><a name="normal"></a>{@code android:normalScreens}</dt>
<dd>Indicates whether an application supports the "normal" screen
form-factors. Traditionally this is an HVGA medium density
screen, but WQVGA low density and WVGA high density are also
considered to be normal. This attribute is "true" by default.
</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" 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.
<p>The default value for this actually varies between some versions, so it's better if
you explicitly declare this attribute at all times. Beware that setting it "false" will
generally enable <a href="{@docRoot}guide/practices/screen-compat-mode.html">screen
compatibility mode</a>.</p>
</dd>
<dt><a name="xlarge"></a>{@code android:xlargeScreens}</dt>
<dd>Indicates whether the application supports extra large screen form-factors.
An xlarge screen is defined as a screen that is significantly larger
than a "large" screen, such as a tablet (or something larger) and may require special care
on the application's part to make good use of it, though it may rely on resizing by the
system to fill the screen.
<p>The default value for this actually varies between some versions, so it's better if
you explicitly declare this attribute at all times. Beware that setting it "false" will
generally enable <a href="{@docRoot}guide/practices/screen-compat-mode.html">screen
compatibility mode</a>.</p>
<p>This attribute was introduced in API level 9.</p>
</dd>
<dt><a name="any"></a>{@code android:anyDensity}</dt>
<dd>Indicates whether the application includes resources to accommodate any screen
density.
<p>For applications that support Android 1.6 (API level 4) and higher, this is "true"
by default and <strong>you should not set it "false"</strong> unless you're absolutely certain that
it's necessary for your application to work. The only time it might be necessary to disable this
is if your app directly manipulates bitmaps (see the <a
href="{@docRoot}guide/practices/screens_support.html#DensityConsiderations">Supporting Multiple
Screens</a> document for more information).</p>
</dd>
<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 class="caution"><strong>Caution:</strong> The Android system does not pay attention to this
attribute, so it does not affect how your application behaves at runtime. Instead, it is used
to enable filtering for your application on services such as Android Market. However,
<strong>Android Market currently does not support this attribute</strong> (on Android 3.2), so you
should continue using the other size attributes if your application does not support
small screens.</p>
<!--
#### Android Market does not support this attribute yet. ####
<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
@@ -95,29 +171,32 @@ to properly display its UI, rather than relying on the generalized size groups.<
<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.
<dd>This attribute allows you to enable <a
href="{@docRoot}guide/practices/screen-compat-mode.html">screen compatibility mode</a> as a
user-optional feature by specifying the maximum "smallest screen width" for which your application
is designed. If the smallest side of a device's available screen is greater than your value here,
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
<p class="note"><strong>Note:</strong> Currently, screen compatibility mode emulates only 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
<dd>This attribute allows you to force-enable <a
href="{@docRoot}guide/practices/screen-compat-mode.html">screen compatibility mode</a> by specifying
the maximum "smallest screen width" for which your application is designed. If the smallest side of
a device's available screen is greater than your value here, 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
@@ -125,102 +204,11 @@ href="#compatibleWidth">{@code android:compatibleWidthLimitDp}</a> attribute. Yo
{@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
<p class="note"><strong>Note:</strong> Currently, screen compatibility mode emulates only 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
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> or <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> to
{@code "4"} or higher. Otherwise, it is false by default. If set false, the system will not resize
your application when run on <em>large</em> or <em>xlarge</em> screens. Instead, the
application appears in a "postage stamp" that equals the <em>normal</em> screen size that your
application does support. This is less than an ideal experience for users, because the
application appears smaller than the available screen, but it might help your application run
normally if it were designed only for the <em>normal</em> screen size and some behaviors do not work
when resized.</p>
<p>To provide the best experience on all screen sizes, you should allow resizing and, if your
application does not work well on larger screens, follow the guide to <a
href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a> to enable
additional screen support.</p>
<p><strong>This attribute is deprecated</strong> as of API level 13.</p>
</dd>
<dt><a name="small"></a>{@code android:smallScreens}</dt>
<dd>Indicates whether the application supports smaller screen form-factors.
A small screen is defined as one with a smaller aspect ratio than
the "normal" (traditional HVGA) screen. An application that does
not support small screens <em>will not be available</em> for
small screen devices from external services (such as Android Market), because there is little
the platform can do
to make such an application work on a smaller screen. If the application has set either <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> or <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> to
{@code "4"} or higher,
the default value for this is {@code "true"}, any value less than {@code "4"} results in this set to
{@code "false"}.
<p><strong>This attribute is deprecated</strong> as of API level 13.</p>
</dd>
<dt><a name="normal"></a>{@code android:normalScreens}</dt>
<dd>Indicates whether an application supports the "normal" screen
form-factors. Traditionally this is an HVGA medium density
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" 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
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> to
{@code "4"} or higher,
the default value for this is {@code "true"}, any value less than {@code "4"} results in this set to
{@code "false"}.
<p><strong>This attribute is deprecated</strong> as of API level 13.</p>
</dd>
<dt><a name="xlarge"></a>{@code android:xlargeScreens}</dt>
<dd>Indicates whether the application supports extra large screen form-factors.
An xlarge screen is defined as a screen that is significantly larger
than a "large" screen, such as a tablet (or something larger) and may require special care
on the application's part to make good use of it, though it may rely on resizing by the
system to fill the screen. If the application has set either <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> or <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> to
{@code "4"} or higher,
the default value for this is {@code "true"}, any value less than {@code "4"} results in this set to
{@code "false"}.
<p>This attribute was introduced in API level 9.</p>
<p><strong>This attribute is deprecated</strong> as of API level 13.</p>
</dd>
<dt><a name="any"></a>{@code android:anyDensity}</dt>
<dd>Indicates whether the application includes resources to accommodate any screen
density. Older applications (before API Level 4) are assumed unable to
accomodate all densities and this is {@code "false"} by default. If the application has set
either <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> or <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> to
{@code "4"} or higher,
the default value for this is {@code "true"}. Otherwise, it is {@code "false"}.
You can explicitly supply your abilities here.
<p>Based on the "standard" device screen density (medium dpi), the Android framework will scale
down application assets by a factor of 0.75 (low dpi screens) or scale them up by a factor of 1.5
(high dpi screens), when you don't provide alternative resources for a specifc screen density. The
screen density is expressed as dots-per-inch (dpi).</p>
<p><strong>This attribute is deprecated</strong> as of API level 13.</p>
</dd>
</dl></dd>

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

@@ -334,7 +334,7 @@ indicates the current locale.</p>
</td>
</tr>
<tr id="SmallestScreenWidthQualifier">
<td>Smallest screen width</td>
<td>Smallest available width</td>
<td><code>sw&lt;N&gt;dp</code><br/><br/>
Examples:<br/>
<code>sw320dp</code><br/>
@@ -381,7 +381,7 @@ indicates the current locale.</p>
</td>
</tr>
<tr id="ScreenWidthQualifier">
<td>Screen width</td>
<td>Available width</td>
<td><code>w&lt;N&gt;dp</code><br/><br/>
Examples:<br/>
<code>w720dp</code><br/>
@@ -389,7 +389,7 @@ indicates the current locale.</p>
etc.
</td>
<td>
<p>Specifies a minimum screen width, in {@code dp} units at which the resource
<p>Specifies a minimum available 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>
@@ -406,7 +406,7 @@ indicates the current locale.</p>
</td>
</tr>
<tr id="ScreenHeightQualifier">
<td>Screen height</td>
<td>Available height</td>
<td><code>h&lt;N&gt;dp</code><br/><br/>
Examples:<br/>
<code>h720dp</code><br/>
@@ -414,7 +414,7 @@ indicates the current locale.</p>
etc.
</td>
<td>
<p>Specifies a minimum screen height, in "dp" units at which the resource
<p>Specifies a minimum available 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>