Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit db909162 authored by Scott Main's avatar Scott Main
Browse files

cherrypick Change-Id: Ib5e8ae7f420e9084e408089d9f5a6574ad95f299 

docs: update Support Mult Screens for MR2 features

Change-Id: Ibab5e60c05c71d58f11daa6f48894011b3e31509
parent 63625002

docs/html/guide/guide_toc.cs

+4 −1
Original line number Diff line number Diff line
@@ -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>

docs/html/guide/practices/screen-compat-mode.jd

0 → 100644
+257 −0
Original line number Diff line number Diff line 
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>
 
 No newline at end of file

docs/html/guide/practices/screens-distribution.jd

+3 −3
Original line number Diff line number Diff line
@@ -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

docs/html/guide/practices/screens-support-1.5.jd

+4 −43
Original line number Diff line number Diff line
@@ -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>