Home | History | Annotate | Download | only in practices
      1 page.title=Screen Compatibility Mode
      2 excludeFromSuggestions=true
      3 parent.title=Supporting Multiple Screens
      4 parent.link=screens_support.html
      5 
      6 @jd:body
      7 
      8 
      9 <div id="qv-wrapper">
     10 <div id="qv">
     11 
     12 <h2>In this document</h2>
     13 <ol>
     14   <li><a href="#Disable">Disabling Screen Compatibility Mode</a></li>
     15   <li><a href="#Enable">Enabling Screen Compatibility Mode</a></li>
     16 </ol>
     17 <h2>See also</h2>
     18 <ol>
     19   <li><a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a></li>
     20   <li><a href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
     21 <supports-screens>}</a></li>
     22 </ol>
     23 </div>
     24 </div>
     25 
     26 <div class="figure" style="width:500px;">
     27 <a href="{@docRoot}images/screens_support/compat-zoom.png">
     28 <img src="{@docRoot}images/screens_support/compat-zoom-thumb.png" alt="" />
     29 </a>
     30 <p class="img-caption"><strong>Figure 1.</strong> An application running in compatibility mode
     31 on an Android 3.2 tablet.</p>
     32 </div>
     33 
     34 <div class="figure" style="width:500px;">
     35 <a href="{@docRoot}images/screens_support/compat-stretch.png">
     36 <img src="{@docRoot}images/screens_support/compat-stretch-thumb.png" alt="" />
     37 </a>
     38 <p class="img-caption"><strong>Figure 2.</strong> The same application from figure 1, with
     39 compatibility mode disabled.</p>
     40 </div>
     41 
     42 <p class="caution"><strong>Notice:</strong> If you've developed an application for a version of
     43 Android lower than Android 3.0, but it does resize properly for larger screens such as tablets, you
     44 should disable screen compatibility mode in order to maintain the best user experience. To learn how
     45 to quickly disable the user option, jump to <a href="#Disable">Disabling Screen Compatibility
     46 Mode</a>.</p>
     47 
     48 <p>Screen compatibility mode is an escape hatch for applications that are not properly designed
     49 to resize for larger screens such as tablets. Since Android 1.6, Android has supported a
     50 variety of screen sizes and does most of the work to resize application layouts so that they
     51 properly fit each screen. However, if your application does not successfully follow the guide to
     52 <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a>,
     53 then it might encounter some rendering issues on larger screens. For applications with this
     54 problem, screen compatibility mode can make the application a little more usable on larger
     55 screens.</p>
     56 
     57 <p>There are two versions of screen compatibility mode with slightly different behaviors:</p>
     58 <dl>
     59   <dt>Version 1 (Android 1.6 - 3.1)</dt>
     60   <dd>The system draws the application's UI in a "postage stamp"
     61 window. That is, the system draws the application's layout the same as it would on a
     62 normal size handset (emulating a 320dp x 480dp screen), with a black border that fills
     63 the remaining area of the screen.
     64 
     65 <p>This was introduced with Android 1.6 to handle apps that were designed only for the
     66 original screen size of 320dp x 480dp. Because there are so few active devices remaining that run
     67 Android 1.5, almost all applications should be developed against Android 1.6 or greater and
     68 should not have version 1 of screen compatibility mode enabled for larger screens. This version
     69 is considered obsolete.</p>
     70   <p>To disable this version of screen compatibility mode, you simply need to set <a
     71 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code
     72 android:minSdkVersion}</a> or <a
     73 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code
     74 android:targetSdkVersion}</a> to {@code "4"} or higher, or set <a
     75 href="{@docRoot}guide/topics/manifest/supports-screens-element.html#resizeable">{@code
     76 android:resizeable}</a> to {@code "true"}.</p>
     77   </dd>
     78 
     79   <dt>Version 2 (Android 3.2 and greater)</dt>
     80   <dd>The system draws the application's layout the same as
     81 it would on a normal size handset (approximately emulating a 320dp x 480dp screen), then scales it
     82 up to fill the screen. This essentially "zooms" in on your layout to make it bigger,
     83 which will usually cause artifacts such as blurring and pixelation in your UI.
     84   <p>This was introduced with Android 3.2 to further
     85 assist applications on the latest tablet devices when the applications have not yet
     86 implemented techniques for <a
     87 href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple
     88 Screens</a>.</p>
     89   <p>In general, large screen devices running Android 3.2 or higher allow users to enable
     90 screen compatibility mode when the application does not <strong>explicitly declare that it supports
     91 large screens</strong> in the manifest file. When this is the case, an icon (with
     92 outward-pointing arrows) appears next to the clock in the system bar, which allows the user to
     93 toggle screen compatibility mode on and off (figure 3). An application can also explicitly
     94 declare that it <em>does not</em> support large screens such that screen compatibility mode
     95 is always enabled and the user cannot disable it. (How to declare your application's
     96 support for large screens is discussed in the following sections.)</p></dd>
     97 </dl>
     98 
     99 <img src="{@docRoot}images/screens_support/compat-toggle.png" alt="" />
    100 <p class="img-caption"><strong>Figure 3.</strong> The pop up menu to toggle screen compatibility
    101 mode (currently disabled, so normal resizing occurs).</p>
    102 
    103 <p>As a developer, you have control over when your application uses screen compatibility mode. The
    104 following sections describe how you can choose to disable or enable screen compatibility mode for
    105 larger screens when running Android 3.2 or higher.</p>
    106 
    107 
    108 <h2 id="Disable">Disabling Screen Compatibility Mode</h2>
    109 
    110 <p>If you've developed your application primarily for versions of Android lower than 3.0, but
    111 <strong>your application does resize properly</strong> for larger screens such as tablets,
    112 <strong>you should disable screen compatibility mode</strong> in order to maintain the best user
    113 experience. Otherwise, users may enable screen compatibility mode and experience your application in
    114 a less-than-ideal format.</p>
    115 
    116 <p>By default, screen compatibility mode for devices running Android 3.2 and higher is offered to
    117 users as an optional feature when one of the following is true:</p>
    118 
    119 <ul>
    120   <li>Your application has set both <a
    121 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a>
    122 and <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code
    123 android:targetSdkVersion}</a> to {@code "10"} or lower and <strong>does not explicitly
    124 declare support</strong> for large screens using the <a
    125 href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
    126 <supports-screens>}</a> element.</li>
    127 
    128   <li>Your application has set either <a
    129 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a>
    130 or <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code
    131 android:targetSdkVersion}</a> to {@code "11"} or higher and <strong>explicitly declares that it does
    132 not support</strong> large screens, using the <a
    133 href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
    134 <supports-screens>}</a> element.</li>
    135 </ul>
    136 
    137 <p>To completely disable the user option for screen compatibility mode and remove the icon in the
    138 system bar, you can do one of the following:</p>
    139 
    140 <ul>
    141   <li><strong>Easiest:</strong>
    142     <p>In your manifest file, add the <a
    143 href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
    144 <supports-screens>}</a> element and specify the <a
    145 href="{@docRoot}guide/topics/manifest/supports-screens-element.html#xlarge">{@code
    146 android:xlargeScreens}</a> attribute to {@code "true"}:</p>
    147 <pre>
    148 &lt;supports-screens android:xlargeScreens="true" /&gt;
    149 </pre>
    150   <p>That's it. This declares that your application supports all larger screen sizes, so the
    151 system will always resize your layout to fit the screen. This works regardless of what values
    152 you've set in the <a
    153 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code <uses-sdk>}</a>
    154 attributes.</p>
    155   </li>
    156 
    157   <li><strong>Easy but has other effects:</strong>
    158     <p>In your manifest's <a
    159 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code <uses-sdk>}</a>
    160 element, set <a
    161 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code
    162 android:targetSdkVersion}</a> to {@code "11"} or higher:</p>
    163 <pre>
    164 &lt;uses-sdk android:minSdkVersion="4" android:targetSdkVersion="11" /&gt;
    165 </pre>
    166   <p>This declares that your application supports Android 3.0 and, thus, is designed to
    167 work on larger screens such as tablets.</p>
    168   <p class="caution"><strong>Caution:</strong> When running on Android 3.0 and greater, this also
    169 has the effect of enabling the Holographic theme for you UI, adding the <a
    170 href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> to your activities, and removing the
    171 Options Menu button in the system bar.</p>
    172   <p>If screen compatibility mode is still enabled after you change this, check your manifest's <a
    173 href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
    174 <supports-screens>}</a> and be sure that there are no attributes set {@code "false"}. The best
    175 practice is to always explicitly declare your support for different screen sizes using the <a
    176 href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
    177 <supports-screens>}</a> element, so you should use this element anyway.</p>
    178   <p>For more information about updating your application to target Android 3.0 devices, read <a
    179 href="{@docRoot}guide/practices/optimizing-for-3.0.html">Optimizing Apps for Android
    180 3.0</a>.</p>
    181   </li>
    182 <!--
    183   <li><strong>Most control</strong> (but you must compile against Android 3.2 or higher):
    184     <p>In your manifest file, add the <a
    185 href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
    186 <supports-screens>}</a> element and specify the {@code android:compatibleWidthLimitDp}
    187 attribute to any value <em>higher than</em> {@code "320"}:</p>
    188 <pre>
    189 &lt;supports-screens android:compatibleWidthLimitDp="720" /&gt;
    190 </pre>
    191   <p>Using this technique allows you to specify exactly what your application's limit is for
    192 layout resizing. Normally, only applications that are already built against Android 3.2 (or
    193 higher) use this attribute, because the primary intention is to specify at what size should screen
    194 compatibility mode actually be offered to users.</p>
    195   <p class="note"><strong>Note:</strong> Currently, screen compatibility mode only emulates
    196 handset screens with a 320dp width, so screen compatibility mode is not applied to any device if
    197 your value for {@code android:compatibleWidthLimitDp} is larger than 320.</p>
    198   </li>
    199   -->
    200 </ul>
    201 
    202 
    203 
    204 <h2 id="Enable">Enabling Screen Compatibility Mode</h2>
    205 
    206 <p>When your application is targeting Android 3.2 (API level 13) or higher, you can affect
    207 whether compatibility mode is enabled for certain screens by using the <a
    208 href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
    209 <supports-screens>}</a> element.</p>
    210 
    211 <p class="note"><strong>Note:</strong> Screen compatibility mode is <strong>not</strong> a mode in
    212 which you should want your application to run&mdash;it causes pixelation and blurring in your UI,
    213 due to zooming. The proper way to make your application work well on large screens is to follow the
    214 guide to <a
    215 href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a> and
    216 provide alternative layouts for different screen sizes.</p>
    217 
    218 <p>By default, when you've set either <a
    219 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code
    220 android:minSdkVersion}</a> or <a
    221 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code
    222 android:targetSdkVersion}</a> to {@code "11"} or higher, screen compatibility mode is
    223 <strong>not</strong> available to users. If either of these are true and your application does not
    224 resize properly for larger screens, you can choose to enable screen compatibility mode in one
    225 of the following ways:</p>
    226 
    227 <ul>
    228   <li>In your manifest file, add the <a
    229 href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
    230 <supports-screens>}</a> element and specify the <a
    231 href="{@docRoot}guide/topics/manifest/supports-screens-element.html#compatibleWidth">{@code
    232 android:compatibleWidthLimitDp}</a> attribute to {@code "320"}:</p>
    233 <pre>
    234 &lt;supports-screens android:compatibleWidthLimitDp="320" /&gt;
    235 </pre>
    236   <p>This indicates that the maximum "smallest screen width" for which your application is designed
    237 is 320dp. This way, any devices with their smallest side being larger than this value will offer
    238 screen compatibility mode as a user-optional feature.</p>
    239   <p class="note"><strong>Note:</strong> Currently, screen compatibility mode only emulates
    240 handset screens with a 320dp width, so screen compatibility mode is not applied to any device if
    241 your value for <a
    242 href="{@docRoot}guide/topics/manifest/supports-screens-element.html#compatibleWidth">{@code
    243 android:compatibleWidthLimitDp}</a> is larger than 320.</p>
    244   </li>
    245 
    246   <li>If your application is functionally broken when resized for large screens and you want to
    247 force users into screen compatibility mode (rather than simply providing the option), you can use
    248 the <a href="{@docRoot}guide/topics/manifest/supports-screens-element.html#largestWidth">{@code
    249 android:largestWidthLimitDp}</a> attribute:
    250 <pre>
    251 &lt;supports-screens android:largestWidthLimitDp="320" /&gt;
    252 </pre>
    253   <p>This works the same as <a
    254 href="{@docRoot}guide/topics/manifest/supports-screens-element.html#compatibleWidth">{@code
    255 android:compatibleWidthLimitDp}</a> except it force-enables
    256 screen compatibility mode and does not allow users to disable it.</p>
    257   </li>
    258 </ul>