1page.title=Screen Compatibility Mode 2excludeFromSuggestions=true 3parent.title=Supporting Multiple Screens 4parent.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 31on 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 39compatibility mode disabled.</p> 40</div> 41 42<p class="caution"><strong>Notice:</strong> If you've developed an application for a version of 43Android lower than Android 3.0, but it does resize properly for larger screens such as tablets, you 44should disable screen compatibility mode in order to maintain the best user experience. To learn how 45to quickly disable the user option, jump to <a href="#Disable">Disabling Screen Compatibility 46Mode</a>.</p> 47 48<p>Screen compatibility mode is an escape hatch for applications that are not properly designed 49to resize for larger screens such as tablets. Since Android 1.6, Android has supported a 50variety of screen sizes and does most of the work to resize application layouts so that they 51properly 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>, 53then it might encounter some rendering issues on larger screens. For applications with this 54problem, screen compatibility mode can make the application a little more usable on larger 55screens.</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" 61window. That is, the system draws the application's layout the same as it would on a 62normal size handset (emulating a 320dp x 480dp screen), with a black border that fills 63the remaining area of the screen. 64 65<p>This was introduced with Android 1.6 to handle apps that were designed only for the 66original screen size of 320dp x 480dp. Because there are so few active devices remaining that run 67Android 1.5, almost all applications should be developed against Android 1.6 or greater and 68should not have version 1 of screen compatibility mode enabled for larger screens. This version 69is considered obsolete.</p> 70 <p>To disable this version of screen compatibility mode, you simply need to set <a 71href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code 72android:minSdkVersion}</a> or <a 73href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code 74android:targetSdkVersion}</a> to {@code "4"} or higher, or set <a 75href="{@docRoot}guide/topics/manifest/supports-screens-element.html#resizeable">{@code 76android: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 81it would on a normal size handset (approximately emulating a 320dp x 480dp screen), then scales it 82up to fill the screen. This essentially "zooms" in on your layout to make it bigger, 83which will usually cause artifacts such as blurring and pixelation in your UI. 84 <p>This was introduced with Android 3.2 to further 85assist applications on the latest tablet devices when the applications have not yet 86implemented techniques for <a 87href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple 88Screens</a>.</p> 89 <p>In general, large screen devices running Android 3.2 or higher allow users to enable 90screen compatibility mode when the application does not <strong>explicitly declare that it supports 91large screens</strong> in the manifest file. When this is the case, an icon (with 92outward-pointing arrows) appears next to the clock in the system bar, which allows the user to 93toggle screen compatibility mode on and off (figure 3). An application can also explicitly 94declare that it <em>does not</em> support large screens such that screen compatibility mode 95is always enabled and the user cannot disable it. (How to declare your application's 96support 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 101mode (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 104following sections describe how you can choose to disable or enable screen compatibility mode for 105larger 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 113experience. Otherwise, users may enable screen compatibility mode and experience your application in 114a less-than-ideal format.</p> 115 116<p>By default, screen compatibility mode for devices running Android 3.2 and higher is offered to 117users as an optional feature when one of the following is true:</p> 118 119<ul> 120 <li>Your application has set both <a 121href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a> 122and <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code 123android:targetSdkVersion}</a> to {@code "10"} or lower and <strong>does not explicitly 124declare support</strong> for large screens using the <a 125href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code 126<supports-screens>}</a> element.</li> 127 128 <li>Your application has set either <a 129href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a> 130or <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code 131android:targetSdkVersion}</a> to {@code "11"} or higher and <strong>explicitly declares that it does 132not support</strong> large screens, using the <a 133href="{@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 138system 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 143href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code 144<supports-screens>}</a> element and specify the <a 145href="{@docRoot}guide/topics/manifest/supports-screens-element.html#xlarge">{@code 146android:xlargeScreens}</a> attribute to {@code "true"}:</p> 147<pre> 148<supports-screens android:xlargeScreens="true" /> 149</pre> 150 <p>That's it. This declares that your application supports all larger screen sizes, so the 151system will always resize your layout to fit the screen. This works regardless of what values 152you've set in the <a 153href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code <uses-sdk>}</a> 154attributes.</p> 155 </li> 156 157 <li><strong>Easy but has other effects:</strong> 158 <p>In your manifest's <a 159href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code <uses-sdk>}</a> 160element, set <a 161href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code 162android:targetSdkVersion}</a> to {@code "11"} or higher:</p> 163<pre> 164<uses-sdk android:minSdkVersion="4" android:targetSdkVersion="11" /> 165</pre> 166 <p>This declares that your application supports Android 3.0 and, thus, is designed to 167work on larger screens such as tablets.</p> 168 <p class="caution"><strong>Caution:</strong> When running on Android 3.0 and greater, this also 169has the effect of enabling the Holographic theme for you UI, adding the <a 170href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> to your activities, and removing the 171Options 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 173href="{@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 175practice is to always explicitly declare your support for different screen sizes using the <a 176href="{@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 179href="{@docRoot}guide/practices/optimizing-for-3.0.html">Optimizing Apps for Android 1803.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 185href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code 186<supports-screens>}</a> element and specify the {@code android:compatibleWidthLimitDp} 187attribute to any value <em>higher than</em> {@code "320"}:</p> 188<pre> 189<supports-screens android:compatibleWidthLimitDp="720" /> 190</pre> 191 <p>Using this technique allows you to specify exactly what your application's limit is for 192layout resizing. Normally, only applications that are already built against Android 3.2 (or 193higher) use this attribute, because the primary intention is to specify at what size should screen 194compatibility mode actually be offered to users.</p> 195 <p class="note"><strong>Note:</strong> Currently, screen compatibility mode only emulates 196handset screens with a 320dp width, so screen compatibility mode is not applied to any device if 197your 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 207whether compatibility mode is enabled for certain screens by using the <a 208href="{@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 212which you should want your application to run—it causes pixelation and blurring in your UI, 213due to zooming. The proper way to make your application work well on large screens is to follow the 214guide to <a 215href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a> and 216provide alternative layouts for different screen sizes.</p> 217 218<p>By default, when you've set either <a 219href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code 220android:minSdkVersion}</a> or <a 221href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code 222android: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 224resize properly for larger screens, you can choose to enable screen compatibility mode in one 225of the following ways:</p> 226 227<ul> 228 <li>In your manifest file, add the <a 229href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code 230<supports-screens>}</a> element and specify the <a 231href="{@docRoot}guide/topics/manifest/supports-screens-element.html#compatibleWidth">{@code 232android:compatibleWidthLimitDp}</a> attribute to {@code "320"}:</p> 233<pre> 234<supports-screens android:compatibleWidthLimitDp="320" /> 235</pre> 236 <p>This indicates that the maximum "smallest screen width" for which your application is designed 237is 320dp. This way, any devices with their smallest side being larger than this value will offer 238screen compatibility mode as a user-optional feature.</p> 239 <p class="note"><strong>Note:</strong> Currently, screen compatibility mode only emulates 240handset screens with a 320dp width, so screen compatibility mode is not applied to any device if 241your value for <a 242href="{@docRoot}guide/topics/manifest/supports-screens-element.html#compatibleWidth">{@code 243android: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 247force users into screen compatibility mode (rather than simply providing the option), you can use 248the <a href="{@docRoot}guide/topics/manifest/supports-screens-element.html#largestWidth">{@code 249android:largestWidthLimitDp}</a> attribute: 250<pre> 251<supports-screens android:largestWidthLimitDp="320" /> 252</pre> 253 <p>This works the same as <a 254href="{@docRoot}guide/topics/manifest/supports-screens-element.html#compatibleWidth">{@code 255android:compatibleWidthLimitDp}</a> except it force-enables 256screen compatibility mode and does not allow users to disable it.</p> 257 </li> 258</ul>
