1 page.title=<supports-screens> 2 parent.title=The AndroidManifest.xml File 3 parent.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="#resizeable">resizeable</a>=["true"| "false"] 12 android:<a href="#small">smallScreens</a>=["true" | "false"] 13 android:<a href="#normal">normalScreens</a>=["true" | "false"] 14 android:<a href="#large">largeScreens</a>=["true" | "false"] 15 android:<a href="#xlarge">xlargeScreens</a>=["true" | "false"] 16 android:<a href="#any">anyDensity</a>=["true" | "false"] 17 android:<a href="#requiresSmallest">requiresSmallestWidthDp</a>="<em>integer</em>" 18 android:<a href="#compatibleWidth">compatibleWidthLimitDp</a>="<em>integer</em>" 19 android:<a href="#largestWidth">largestWidthLimitDp</a>="<em>integer</em>"/> 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 <a 28 href="{@docRoot}guide/practices/screen-compat-mode.html">screen compatibility mode</a> for screens 29 larger than what your application supports. It's important that you always use this element in your 30 application to specify the screen sizes your application supports. 31 32 <p>An application "supports" a given screen size if it resizes properly to fill the entire screen. 33 Normal resizing applied by the system works well for most applications and you don't have to do any 34 extra work to make your application work on screens larger than a handset device. However, it's 35 often important that you optimize your application's UI for different screen sizes by providing <a 36 href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">alternative 37 layout resources</a>. For instance, you might want to modify the layout of an activity 38 when it is on a tablet compared to when running on a handset device.</p> 39 40 <p>However, if your application does not work well when resized to fit different screen sizes, you 41 can use the attributes of the {@code <supports-screens>} element to control whether your 42 application should be distributed to smaller screens or have its UI scaled up ("zoomed") to fit 43 larger screens using the system's <a 44 href="{@docRoot}guide/practices/screen-compat-mode.html">screen compatibility mode</a>. When you 45 have not designed for larger screen sizes and the normal resizing does not achieve the appropriate 46 results, screen compatibility mode will scale your UI by emulating a <em>normal</em> size 47 screen and medium density, then zooming in so that it fills the entire screen. Beware that this 48 causes pixelation and blurring of your UI, so it's better if you optimize your UI for large 49 screens.</p> 50 51 <p class="note"><strong>Note:</strong> Android 3.2 introduces new attributes: {@code 52 android:requiresSmallestWidthDp}, {@code android:compatibleWidthLimitDp}, and {@code 53 android:largestWidthLimitDp}. If you're developing your application for Android 3.2 and higher, 54 you should use these attributes to declare your screen size support, instead of the attributes 55 based on generalized screen sizes.</p> 56 57 <p>For more information about how to properly support different screen sizes so that you can avoid 58 using screen compatibility mode with your application, read 59 <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a>.</p> 60 61 62 <dt>attributes:</dt> 63 64 <dd> 65 <dl class="attr"> 66 67 <dt><a name="resizeable"></a>{@code android:resizeable}</dt> 68 <dd>Indicates whether the application is resizeable for different screen sizes. This attribute is 69 true, by default. If set false, the system will run your application in <a 70 href="{@docRoot}guide/practices/screen-compat-mode.html">screen compatibility mode</a> on large 71 screens.</p> 72 73 <p><strong>This attribute is deprecated</strong>. It was introduced to help applications 74 transition from Android 1.5 to 1.6, when support for multiple screens was first introduced. You 75 should not use it.</p> 76 </dd> 77 78 <dt><a name="small"></a>{@code android:smallScreens}</dt> 79 <dd>Indicates whether the application supports smaller screen form-factors. 80 A small screen is defined as one with a smaller aspect ratio than 81 the "normal" (traditional HVGA) screen. An application that does 82 not support small screens <em>will not be available</em> for 83 small screen devices from external services (such as Google Play), because there is little 84 the platform can do to make such an application work on a smaller screen. This is {@code "true"} by 85 default. 86 </dd> 87 88 <dt><a name="normal"></a>{@code android:normalScreens}</dt> 89 <dd>Indicates whether an application supports the "normal" screen 90 form-factors. Traditionally this is an HVGA medium density 91 screen, but WQVGA low density and WVGA high density are also 92 considered to be normal. This attribute is "true" by default. 93 </dd> 94 95 <dt><a name="large"></a>{@code android:largeScreens}</dt> 96 <dd>Indicates whether the application supports larger screen form-factors. 97 A large screen is defined as a screen that is significantly larger 98 than a "normal" handset screen, and thus might require some special care 99 on the application's part to make good use of it, though it may rely on resizing by the 100 system to fill the screen. 101 <p>The default value for this actually varies between some versions, so it's better if 102 you explicitly declare this attribute at all times. Beware that setting it "false" will 103 generally enable <a href="{@docRoot}guide/practices/screen-compat-mode.html">screen 104 compatibility mode</a>.</p> 105 </dd> 106 107 <dt><a name="xlarge"></a>{@code android:xlargeScreens}</dt> 108 <dd>Indicates whether the application supports extra large screen form-factors. 109 An xlarge screen is defined as a screen that is significantly larger 110 than a "large" screen, such as a tablet (or something larger) and may require special care 111 on the application's part to make good use of it, though it may rely on resizing by the 112 system to fill the screen. 113 <p>The default value for this actually varies between some versions, so it's better if 114 you explicitly declare this attribute at all times. Beware that setting it "false" will 115 generally enable <a href="{@docRoot}guide/practices/screen-compat-mode.html">screen 116 compatibility mode</a>.</p> 117 <p>This attribute was introduced in API level 9.</p> 118 </dd> 119 120 <dt><a name="any"></a>{@code android:anyDensity}</dt> 121 <dd>Indicates whether the application includes resources to accommodate any screen 122 density. 123 <p>For applications that support Android 1.6 (API level 4) and higher, this is "true" 124 by default and <strong>you should not set it "false"</strong> unless you're absolutely certain that 125 it's necessary for your application to work. The only time it might be necessary to disable this 126 is if your app directly manipulates bitmaps (see the <a 127 href="{@docRoot}guide/practices/screens_support.html#DensityConsiderations">Supporting Multiple 128 Screens</a> document for more information).</p> 129 </dd> 130 131 <dt id="requiresSmallest">{@code android:requiresSmallestWidthDp}</dt> 132 <dd>Specifies the minimum smallestWidth required. The smallestWidth is the shortest dimension of 133 the screen space (in {@code dp} units) that must be available to your application UI—that is, 134 the shortest of the available screen's two dimensions. So, in order for a device to be considered 135 compatible with your application, the device's smallestWidth must be equal to or greater than this 136 value. (Usually, the value you supply for this is the "smallest width" that your layout supports, 137 regardless of the screen's current orientation.) 138 139 <p>For example, a typical handset screen has a smallestWidth of 320dp, a 7" tablet has a 140 smallestWidth of 600dp, and a 10" tablet has a smallestWidth of 720dp. These values are generally 141 the smallestWidth because they are the shortest dimension of the screen's available space.</p> 142 143 <p>The size against which your value is compared takes into account screen decorations and system 144 UI. For example, if the device has some persistent UI elements on the display, the system declares 145 the device's smallestWidth as one that is smaller than the actual screen size, accounting for these 146 UI elements because those are screen pixels not available for your UI. Thus, the value you use 147 should be the minimum width required by your layout, regardless of the screen's current 148 orientation.</p> 149 150 <p>If your application properly resizes for smaller screen sizes (down to the 151 <em>small</em> size or a minimum width of 320dp), you do 152 not need to use this attribute. Otherwise, you should use a value for this attribute that 153 matches the smallest value used by your application for the <a 154 href="{@docRoot}guide/topics/resources/providing-resources.html#SmallestScreenWidthQualifier"> 155 smallest screen width qualifier</a> ({@code sw<N>dp}).</p> 156 157 <p class="caution"><strong>Caution:</strong> The Android system does not pay attention to this 158 attribute, so it does not affect how your application behaves at runtime. Instead, it is used 159 to enable filtering for your application on services such as Google Play. However, 160 <strong>Google Play currently does not support this attribute for filtering</strong> (on Android 161 3.2), so you should continue using the other size attributes if your application does not support 162 small screens.</p> 163 164 <!-- 165 <p>Beginning with Android 3.2 (API level 13), using this attribute is the preferred way to 166 specify the minimum screen size your application requires, instead of using the other attributes 167 for small, normal, large, and xlarge screens. The advantage of using this attribute is that you 168 have more control over exactly how much screen space your application needs at a minimum in order 169 to properly display its UI, rather than relying on the generalized size groups.</p> 170 <p>This attribute has no default value. If this attribute is not specified, then any of the old 171 <code><a href="#small">smallScreens</a></code>, <code><a href="#normal">normalScreens</a></code>, 172 <code><a href="#large">largeScreens</a></code>, or <code><a href="#xlarge">xlargeScreens</a></code> 173 attributes are used instead to determine the smallest screen required.</p> 174 --> 175 <p>This attribute was introduced in API level 13.</p> 176 </dd> 177 178 <dt id="compatibleWidth">{@code android:compatibleWidthLimitDp}</dt> 179 <dd>This attribute allows you to enable <a 180 href="{@docRoot}guide/practices/screen-compat-mode.html">screen compatibility mode</a> as a 181 user-optional feature by specifying the maximum "smallest screen width" for which your application 182 is designed. If the smallest side of a device's available screen is greater than your value here, 183 users can still install your application, but are offered to run it in screen compatibility mode. By 184 default, screen compatibility mode is disabled and your layout is resized to fit the screen as 185 usual, but a button is available in the system bar that allows the user to toggle screen 186 compatibility mode on and off. 187 <p>If your application is compatible with all screen sizes and its layout properly resizes, you do 188 not need to use this attribute.</p> 189 <p class="note"><strong>Note:</strong> Currently, screen compatibility mode emulates only handset 190 screens with a 320dp width, so screen compatibility mode is not applied if your value for {@code 191 android:compatibleWidthLimitDp} is larger than 320.</p> 192 <p>This attribute was introduced in API level 13.</p> 193 </dd> 194 195 <dt id="largestWidth">{@code android:largestWidthLimitDp}</dt> 196 <dd>This attribute allows you to force-enable <a 197 href="{@docRoot}guide/practices/screen-compat-mode.html">screen compatibility mode</a> by specifying 198 the maximum "smallest screen width" for which your application is designed. If the smallest side of 199 a device's available screen is greater than your value here, the application runs in screen 200 compatibility mode with no way for the user to disable it. 201 <p>If your application is compatible with all screen sizes and its layout properly resizes, you do 202 not need to use this attribute. Otherwise, you should first consider using the <a 203 href="#compatibleWidth">{@code android:compatibleWidthLimitDp}</a> attribute. You should use the 204 {@code android:largestWidthLimitDp} attribute only when your application is functionally broken when 205 resized for larger screens and screen compatibility mode is the only way that users should use 206 your application.</p> 207 <p class="note"><strong>Note:</strong> Currently, screen compatibility mode emulates only handset 208 screens with a 320dp width, so screen compatibility mode is not applied if your value for {@code 209 android:largestWidthLimitDp} is larger than 320.</p> 210 <p>This attribute was introduced in API level 13.</p> 211 </dd> 212 213 214 </dl></dd> 215 216 <!-- ##api level indication## --> 217 <dt>introduced in:</dt> 218 <dd>API Level 4</dd> 219 220 <dt>see also:</dt> 221 <dd> 222 <ul> 223 <li><a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple 224 Screens</a></li> 225 <li>{@link android.util.DisplayMetrics}</li> 226 </ul> 227 </dd> 228 229 </dl> 230
