supports-screens-element.jd revision 9a05cfe5427a6cee988333e0d65f17b9854554a3
1page.title=<supports-screens> 2parent.title=The AndroidManifest.xml File 3parent.link=manifest-intro.html 4@jd:body 5 6<dl class="xml"> 7 8<dt>syntax:</dt> 9<dd> 10<pre class="stx"> 11<supports-screens android:<a href="#requiresSmallest">requiresSmallestWidthDp</a>="<em>integer</em>" 12 android:<a href="#compatibleWidth">compatibleWidthLimitDp</a>="<em>integer</em>" 13 android:<a href="#largestWidth">largestWidthLimitDp</a>="<em>integer</em>" 14 android:<a href="#resizeable">resizeable</a>=["true"| "false"] 15 android:<a href="#small">smallScreens</a>=["true" | "false"] 16 android:<a href="#normal">normalScreens</a>=["true" | "false"] 17 android:<a href="#large">largeScreens</a>=["true" | "false"] 18 android:<a href="#xlarge">xlargeScreens</a>=["true" | "false"] 19 android:<a href="#any">anyDensity</a>=["true" | "false"] /> 20</pre> 21</dd> 22 23<dt>contained in:</dt> 24<dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code></dd> 25 26<dt>description:</dt> 27<dd>Lets you specify the screen sizes your application supports and enable screen 28compatibility mode for screens larger than what your application supports. By default, a modern 29application (using API Level 4 or higher) supports all screen sizes; older applications are assumed 30to support only the "normal" screen size. Screen size is determined by the number of pixels on the 31screen after the system accounts for screen density scaling. 32 33<p>An application "supports" a given screen size if it resizes properly to fill the entire screen. 34By default, the system resizes your application UI to fill the screen if you have set 35either <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code 36minSdkVersion}</a> or <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code 37targetSdkVersion}</a> to {@code "4"} or higher. Normal resizing works well for most applications and 38you don't have to do any extra work to make your application work on screens larger than a 39handset device.</p> 40 41<p>In addition to allowing the system to resize your application to fit the current screen, you can 42optimize your UI for different screen sizes by providing <a 43href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">alternative 44layout resources</a> for different sizes. For instance, you might want to modify the layout 45of an activity when it is on a tablet or similar device that has an <em>xlarge</em> screen.</p> 46 47<p>However, if your application does not work well when resized to fit different screen sizes, 48you can use the attributes of the {@code <supports-screens>} element to control whether 49your application should be distributed to smaller screens or have its UI scaled up to fit larger 50screens using the system's screen compatibility mode. When you have not designed for larger screen 51sizes and the normal resizing does not achieve the appropriate results, <em>screen compatibility 52mode</em> will scale your UI by emulating a <em>normal</em> size screen and then zooming in on it so 53that it fills the entire screen—thus achieving the same layout as a normal handset device on 54the large screen (but this usually causes pixelation and blurring of your UI).</p> 55 56<p>For more information about how to properly support different screen sizes so that you can avoid 57using screen compatibility mode, read 58<a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a>.</p> 59 60 61<dt>attributes:</dt> 62 63<dd> 64<dl class="attr"> 65 66 <dt id="requiresSmallest">{@code android:requiresSmallestWidthDp}</dt> 67 <dd>This attribute specifies the minimum "smallest screen width" with which your 68application is compatible. In order for a device to be considered compatible with your 69application, the shortest side of the available screen space must be equal to or greater than this 70value. 71<p>The width against which your value is compared takes into account screen decorations and system 72UI. For example, if the device has some persistent UI elements on the left or right edge of the 73display, the system declares the device's available width as one that is smaller than the actual 74screen size, accounting for these UI elements because those are screen pixels not available for your 75UI. Thus, the value you use should be the actual smallest width required by your layout.</p> 76<p>If your application properly resizes for smaller screen sizes (down to the 77<em>small</em> size or a minimum width of 320dp), you do 78not need to use this attribute. Otherwise, you should use a value for this attribute that 79matches the smallest value used by your application for the <a 80href="{@docRoot}guide/topics/resources/providing-resources.html#SmallestScreenWidthQualifier"> 81smallest screen width qualifier</a> ({@code sw<N>dp}).</p> 82 83<p>For example, a typical handset screen has a minimum width of 320dp, a 7" tablet has a minimum 84width of 600dp, and a 10" tablet has a minimum width of 720dp. If the smallest available screen 85width on a device is less than the value you supply here, then the application is considered 86incompatible with that 87device. External services such as Android Market use this to determine whether a device 88is compatible with your application and prevent incompatible devices from installing it.</p> 89<p>Beginning with Android 3.2 (API level 13), using this attribute is the preferred way to 90specify the minimum screen size your application requires, instead of using the other attributes 91for small, normal, large, and xlarge screens. The advantage of using this attribute is that you 92have more control over exactly how much screen space your application needs at a minimum in order 93to properly display its UI, rather than relying on the generalized size groups.</p> 94<p>This attribute has no default value. If this attribute is not specified, then any of the old 95<code><a href="#small">smallScreens</a></code>, <code><a href="#normal">normalScreens</a></code>, 96<code><a href="#large">largeScreens</a></code>, or <code><a href="#xlarge">xlargeScreens</a></code> 97attributes are used instead to determine the smallest screen required.</p> 98 <p>This attribute was introduced in API level 13.</p> 99 </dd> 100 101 <dt id="compatibleWidth">{@code android:compatibleWidthLimitDp}</dt> 102 <dd>This attribute allows you to enable screen compatibility mode as a user-optional feature by 103specifying the maximum "smallest screen width" for which your application is designed. If the value 104you supply here is less than the shortest side of the available screen space, users can still 105install your application, but are offered to run it in screen compatibility mode. By default, screen 106compatibility mode is disabled and your layout is resized to fit the screen as usual, but a 107button is available in the system bar that allows the user to toggle screen compatibility mode on 108and off. 109 <p>If your application is compatible with all screen sizes and its layout properly resizes, you do 110not need to use this attribute.</p> 111 <p class="note"><strong>Note:</strong> Currently, screen compatibility mode only emulates handset 112screens with a 320dp width, so screen compatibility mode is not applied if your value for {@code 113android:compatibleWidthLimitDp} is larger than 320.</p> 114 <p>This attribute was introduced in API level 13.</p> 115 </dd> 116 117 <dt id="largestWidth">{@code android:largestWidthLimitDp}</dt> 118 <dd>This attribute allows you to force enable screen compatibility mode by specifying the maximum 119"smallest screen width" for which your application is designed. If the value you supply here is less 120than the shortest side of the available screen space, the application runs in screen 121compatibility mode with no way for the user to disable it. 122 <p>If your application is compatible with all screen sizes and its layout properly resizes, you do 123not need to use this attribute. Otherwise, you should first consider using the <a 124href="#compatibleWidth">{@code android:compatibleWidthLimitDp}</a> attribute. You should use the 125{@code android:largestWidthLimitDp} attribute only when your application is functionally broken when 126resized for larger screens and screen compatibility mode is the only way that users should use 127your application.</p> 128 <p class="note"><strong>Note:</strong> Currently, screen compatibility mode only emulates handset 129screens with a 320dp width, so screen compatibility mode is not applied if your value for {@code 130android:largestWidthLimitDp} is larger than 320.</p> 131 <p>This attribute was introduced in API level 13.</p> 132 </dd> 133 134 <dt><a name="resizeable"></a>{@code android:resizeable}</dt> 135 <dd>Indicates whether the application is resizeable for different screen sizes. This attribute is 136true, by default, if you have set either <a 137href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> or <a 138href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> to 139{@code "4"} or higher. Otherwise, it is false by default. If set false, the system will not resize 140your application when run on <em>large</em> or <em>xlarge</em> screens. Instead, the 141application appears in a "postage stamp" that equals the <em>normal</em> screen size that your 142application does support. This is less than an ideal experience for users, because the 143application appears smaller than the available screen, but it might help your application run 144normally if it were designed only for the <em>normal</em> screen size and some behaviors do not work 145when resized.</p> 146 <p>To provide the best experience on all screen sizes, you should allow resizing and, if your 147application does not work well on larger screens, follow the guide to <a 148href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a> to enable 149additional screen support.</p> 150 <p><strong>This attribute is deprecated</strong> as of API level 13.</p> 151 </dd> 152 153 154 <dt><a name="small"></a>{@code android:smallScreens}</dt> 155 <dd>Indicates whether the application supports smaller screen form-factors. 156 A small screen is defined as one with a smaller aspect ratio than 157 the "normal" (traditional HVGA) screen. An application that does 158 not support small screens <em>will not be available</em> for 159 small screen devices from external services (such as Android Market), because there is little 160the platform can do 161 to make such an application work on a smaller screen. If the application has set either <a 162href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> or <a 163href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> to 164{@code "4"} or higher, 165the default value for this is {@code "true"}, any value less than {@code "4"} results in this set to 166{@code "false"}. 167 <p><strong>This attribute is deprecated</strong> as of API level 13.</p> 168 </dd> 169 170 <dt><a name="normal"></a>{@code android:normalScreens}</dt> 171 <dd>Indicates whether an application supports the "normal" screen 172 form-factors. Traditionally this is an HVGA medium density 173 screen, but WQVGA low density and WVGA high density are also 174 considered to be normal. This attribute is "true" by default, 175 and applications currently should leave it that way. 176 <p><strong>This attribute is deprecated</strong> as of API level 13.</p> 177 </dd> 178 179 <dt><a name="large"></a>{@code android:largeScreens}</dt> 180 <dd>Indicates whether the application supports larger screen form-factors. 181 A large screen is defined as a screen that is significantly larger 182 than a "normal" handset screen, and thus might require some special care 183 on the application's part to make good use of it, though it may rely on resizing by the 184system to fill the screen. If the application has set either <a 185href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> or <a 186href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> to 187{@code "4"} or higher, 188the default value for this is {@code "true"}, any value less than {@code "4"} results in this set to 189{@code "false"}. 190 <p><strong>This attribute is deprecated</strong> as of API level 13.</p> 191 </dd> 192 193 <dt><a name="xlarge"></a>{@code android:xlargeScreens}</dt> 194 <dd>Indicates whether the application supports extra large screen form-factors. 195 An xlarge screen is defined as a screen that is significantly larger 196 than a "large" screen, such as a tablet (or something larger) and may require special care 197 on the application's part to make good use of it, though it may rely on resizing by the 198system to fill the screen. If the application has set either <a 199href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> or <a 200href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> to 201{@code "4"} or higher, 202the default value for this is {@code "true"}, any value less than {@code "4"} results in this set to 203{@code "false"}. 204 <p>This attribute was introduced in API level 9.</p> 205 <p><strong>This attribute is deprecated</strong> as of API level 13.</p> 206 </dd> 207 208 <dt><a name="any"></a>{@code android:anyDensity}</dt> 209 <dd>Indicates whether the application includes resources to accommodate any screen 210 density. Older applications (before API Level 4) are assumed unable to 211 accomodate all densities and this is {@code "false"} by default. If the application has set 212either <a 213href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> or <a 214href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> to 215{@code "4"} or higher, 216the default value for this is {@code "true"}. Otherwise, it is {@code "false"}. 217 You can explicitly supply your abilities here. 218 <p>Based on the "standard" device screen density (medium dpi), the Android framework will scale 219down application assets by a factor of 0.75 (low dpi screens) or scale them up by a factor of 1.5 220(high dpi screens), when you don't provide alternative resources for a specifc screen density. The 221screen density is expressed as dots-per-inch (dpi).</p> 222 <p><strong>This attribute is deprecated</strong> as of API level 13.</p> 223 </dd> 224 225 226</dl></dd> 227 228<!-- ##api level indication## --> 229<dt>introduced in:</dt> 230<dd>API Level 4</dd> 231 232<dt>see also:</dt> 233<dd> 234 <ul> 235 <li><a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple 236Screens</a></li> 237 <li>{@link android.util.DisplayMetrics}</li> 238 </ul> 239</dd> 240 241</dl> 242