Scott Main | db90916 | 2011-06-22 14:28:44 -0700 | [diff] [blame] | 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 |
Scott Main | 8da1191 | 2011-08-12 12:22:18 -0700 | [diff] [blame] | 51 | <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a>, |
Scott Main | db90916 | 2011-06-22 14:28:44 -0700 | [diff] [blame] | 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 |
Scott Main | 19aad29 | 2011-10-18 16:57:32 -0700 | [diff] [blame^] | 74 | href="{@docRoot}guide/topics/manifest/supports-screens-element.html#resizeable">{@code |
Scott Main | db90916 | 2011-06-22 14:28:44 -0700 | [diff] [blame] | 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 |
Scott Main | 8da1191 | 2011-08-12 12:22:18 -0700 | [diff] [blame] | 86 | href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple |
Scott Main | db90916 | 2011-06-22 14:28:44 -0700 | [diff] [blame] | 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 |
Scott Main | 8da1191 | 2011-08-12 12:22:18 -0700 | [diff] [blame] | 214 | href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a> and |
Scott Main | db90916 | 2011-06-22 14:28:44 -0700 | [diff] [blame] | 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> |