diff options
Diffstat (limited to 'docs/html/guide/practices/screen-compat-mode.jd')
| -rw-r--r-- | docs/html/guide/practices/screen-compat-mode.jd | 257 |
1 files changed, 257 insertions, 0 deletions
diff --git a/docs/html/guide/practices/screen-compat-mode.jd b/docs/html/guide/practices/screen-compat-mode.jd new file mode 100644 index 0000000..a792386 --- /dev/null +++ b/docs/html/guide/practices/screen-compat-mode.jd @@ -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 +<supports-screens>}</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 +<supports-screens>}</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 +<supports-screens>}</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 +<supports-screens>}</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> +<supports-screens android:xlargeScreens="true" /> +</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 <uses-sdk>}</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 <uses-sdk>}</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> +<uses-sdk android:minSdkVersion="4" android:targetSdkVersion="11" /> +</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 +<supports-screens>}</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 +<supports-screens>}</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 +<supports-screens>}</a> element and specify the {@code android:compatibleWidthLimitDp} +attribute to any value <em>higher than</em> {@code "320"}:</p> +<pre> +<supports-screens android:compatibleWidthLimitDp="720" /> +</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 +<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—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 +<supports-screens>}</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> +<supports-screens android:compatibleWidthLimitDp="320" /> +</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> +<supports-screens android:largestWidthLimitDp="320" /> +</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>
\ No newline at end of file |