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