diff options
| -rw-r--r-- | core/res/res/values/attrs_manifest.xml | 20 | ||||
| -rw-r--r-- | docs/html/guide/guide_toc.cs | 3 | ||||
| -rw-r--r-- | docs/html/guide/topics/manifest/supports-screens-element.jd | 138 | ||||
| -rw-r--r-- | docs/html/guide/topics/resources/providing-resources.jd | 139 |
4 files changed, 199 insertions, 101 deletions
diff --git a/core/res/res/values/attrs_manifest.xml b/core/res/res/values/attrs_manifest.xml index 38790ea..f1c76a1 100644 --- a/core/res/res/values/attrs_manifest.xml +++ b/core/res/res/values/attrs_manifest.xml @@ -1012,7 +1012,7 @@ {@link #AndroidManifest manifest} tag. --> <declare-styleable name="AndroidManifestSupportsScreens" parent="AndroidManifest"> <!-- Starting with {@link android.os.Build.VERSION_CODES#HONEYCOMB_MR2}, - this is the new way to specify the screens an application is + this is the new way to specify the minimum screen size an application is compatible with. This attribute provides the required minimum "smallest screen width" (as per the -swNNNdp resource configuration) that the application can run on. For example, a typical phone @@ -1023,17 +1023,15 @@ or xlargeScreens attributes will be used instead. --> <attr name="requiresSmallestWidthDp" format="integer" /> <!-- Starting with {@link android.os.Build.VERSION_CODES#HONEYCOMB_MR2}, - this is the new way to specify the screens an application is + this is the new way to specify the largest screens an application is compatible with. This attribute provides the maximum "smallest screen width" (as per the -swNNNdp resource configuration) that the application is designed for. If this value is smaller than the "smallest screen width" of the device it is running on, the user - will of offered to run it in a compatibility mode that emulates a - smaller screen. Currently the compatibility mode only emulates - phone screens, so it will not be used it the application provides - a requiresSmallestWidthDp that is larger than 320. Typical values - used with this attribute are 320 for a phone screen, 600 for a - 7" tablet, and 720 for a 10" tablet. --> + is offered to run it in a compatibility mode that emulates a + smaller screen and zooms it to fit the screen. Currently the compatibility mode only + emulates phone screens with a 320dp width, so compatibility mode is not applied if the + value for compatibleWidthLimitDp is larger than 320. --> <attr name="compatibleWidthLimitDp" format="integer" /> <!-- Starting with {@link android.os.Build.VERSION_CODES#HONEYCOMB_MR2}, this is the new way to specify the screens an application is @@ -1042,9 +1040,9 @@ that the application can work well on. If this value is smaller than the "smallest screen width" of the device it is running on, the application will be forced in to screen compatibility mode with - no way for the user to turn it off. Currently the compatibility mode - only emulates phone screens, so even if this value is larger than 320 - the width the app runs in will be a 320 phone dimension. --> + no way for the user to turn it off. Currently the compatibility mode only + emulates phone screens with a 320dp width, so compatibility mode is not applied if the + value for largestWidthLimitDp is larger than 320. --> <attr name="largestWidthLimitDp" format="integer" /> <!-- Indicates whether the application supports smaller screen form-factors. A small screen is defined as one with a smaller aspect ratio than diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs index abea85b..19cb6af 100644 --- a/docs/html/guide/guide_toc.cs +++ b/docs/html/guide/guide_toc.cs @@ -222,7 +222,8 @@ <li><a href="<?cs var:toroot ?>guide/topics/manifest/receiver-element.html"><receiver></a></li> <li><a href="<?cs var:toroot ?>guide/topics/manifest/service-element.html"><service></a></li> <li><a href="<?cs var:toroot ?>guide/topics/manifest/supports-gl-texture-element.html"><supports-gl-texture></a></li> - <li><a href="<?cs var:toroot ?>guide/topics/manifest/supports-screens-element.html"><supports-screens></a></li> <!-- ##api level 4## --> + <li><a href="<?cs var:toroot ?>guide/topics/manifest/supports-screens-element.html"><supports-screens></a> + <span class="new">updated</span></li> <!-- ##api level 4## --> <li><a href="<?cs var:toroot ?>guide/topics/manifest/uses-configuration-element.html"><uses-configuration></a></li> <li><a href="<?cs var:toroot ?>guide/topics/manifest/uses-feature-element.html"><uses-feature></a></li> <!-- ##api level 4## --> <li><a href="<?cs var:toroot ?>guide/topics/manifest/uses-library-element.html"><uses-library></a></li> diff --git a/docs/html/guide/topics/manifest/supports-screens-element.jd b/docs/html/guide/topics/manifest/supports-screens-element.jd index ee99a37..605a2bb 100644 --- a/docs/html/guide/topics/manifest/supports-screens-element.jd +++ b/docs/html/guide/topics/manifest/supports-screens-element.jd @@ -8,12 +8,15 @@ parent.link=manifest-intro.html <dt>syntax:</dt> <dd> <pre class="stx"> -<supports-screens android:<a href="#resizeable">resizeable</a>=["true" | "false"] - android:<a href="#small">smallScreens</a>=["true" | "false"] - android:<a href="#normal">normalScreens</a>=["true" | "false"] - android:<a href="#large">largeScreens</a>=["true" | "false"] +<supports-screens android:<a href="#requiresSmallest">requiresSmallestWidthDp</a>="<em>integer</em>" + android:<a href="#compatibleWidth">compatibleWidthLimitDp</a>="<em>integer</em>" + android:<a href="#largestWidth">largestWidthLimitDp</a>="<em>integer</em>" + android:<a href="#resizeable">resizeable</a>=["true"| "false"] + android:<a href="#small">smallScreens</a>=["true" | "false"] + android:<a href="#normal">normalScreens</a>=["true" | "false"] + android:<a href="#large">largeScreens</a>=["true" | "false"] android:<a href="#xlarge">xlargeScreens</a>=["true" | "false"] - android:<a href="#any">anyDensity</a>=["true" | "false"] /> + android:<a href="#any">anyDensity</a>=["true" | "false"] /> </pre> </dd> @@ -21,36 +24,37 @@ parent.link=manifest-intro.html <dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code></dd> <dt>description:</dt> -<dd>Lets you specify the screen dimensions the -application supports. By default, a modern application (using API Level 4 or higher) supports all -screen sizes; older applications are assumed to support only the "normal" screen size. Screen -size is determined as the available pixels to an application after density scaling has been -applied. (Note that screen size is a separate axis from screen density.) - -<p>An application "supports" a given screen size if it fills the entire screen and works as -expected. By default, the system will resize your application to fill the screen, if you have set +<dd>Lets you specify the screen sizes your application supports and enable screen +compatibility mode for screens larger than what your application supports. By default, a modern +application (using API Level 4 or higher) supports all screen sizes; older applications are assumed +to support only the "normal" screen size. Screen size is determined by the number of pixels on the +screen after the system accounts for screen density scaling. + +<p>An application "supports" a given screen size if it resizes properly to fill the entire screen. +By default, the system resizes your application UI to fill the screen if you have set either <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> or <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code -targetSdkVersion}</a> to {@code "4"} or higher. Resizing works well for most applications and -you don't have to do any extra work to make your application work on larger screens.</p> +targetSdkVersion}</a> to {@code "4"} or higher. Normal resizing works well for most applications and +you don't have to do any extra work to make your application work on screens larger than a +handset device.</p> -<p>In addition to allowing the system to resize your application, you can add additional support -for different screen sizes by providing <a +<p>In addition to allowing the system to resize your application to fit the current screen, you can +optimize your UI for different screen sizes by providing <a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">alternative layout resources</a> for different sizes. For instance, you might want to modify the layout of an activity when it is on a tablet or similar device that has an <em>xlarge</em> screen.</p> -<p>If your application does not support <em>large</em> or <em>xlarge</em> screens, then you should -declare that it is not resizeable by setting <a href="#resizeable">{@code android:resizeable}</a> to -{@code "false"}, so that the system will not resize your application on larger screens.</p> - -<p>If your application does not support <em>small</em> screens, then -there isn't much the system can do to make the application work well on a smaller screen, so -external services (such as Android Market) should not allow users to install the application on such -screens.</p> - - -<p>For more information, see +<p>However, if your application does not work well when resized to fit different screen sizes, +you can use the attributes of the {@code <supports-screens>} element to control whether +your application should be distributed to smaller screens or have its UI scaled up to fit larger +screens using the system's screen compatibility mode. When you have not designed for larger screen +sizes and the normal resizing does not achieve the appropriate results, <em>screen compatibility +mode</em> will scale your UI by emulating a <em>normal</em> size screen and then zooming in on it so +that it fills the entire screen—thus achieving the same layout as a normal handset device on +the large screen (but this usually causes pixelation and blurring of your UI).</p> + +<p>For more information about how to properly support different screen sizes so that you can avoid +using screen compatibility mode, read <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a>.</p> @@ -59,6 +63,74 @@ screens.</p> <dd> <dl class="attr"> + <dt id="requiresSmallest">{@code android:requiresSmallestWidthDp}</dt> + <dd>This attribute specifies the minimum "smallest screen width" with which your +application is compatible. In order for a device to be considered compatible with your +application, the shortest side of the available screen space must be equal to or greater than this +value. +<p>The width against which your value is compared takes into account screen decorations and system +UI. For example, if the device has some persistent UI elements on the left or right edge of the +display, the system declares the device's available width as one that is smaller than the actual +screen size, accounting for these UI elements because those are screen pixels not available for your +UI. Thus, the value you use should be the actual smallest width required by your layout.</p> +<p>If your application properly resizes for smaller screen sizes (down to the +<em>small</em> size or a minimum width of 320dp), you do +not need to use this attribute. Otherwise, you should use a value for this attribute that +matches the smallest value used by your application for the <a +href="{@docRoot}guide/topics/resources/providing-resources.html#SmallestScreenWidthQualifier"> +smallest screen width qualifier</a> ({@code sw<N>dp}).</p> + +<p>For example, a typical handset screen has a minimum width of 320dp, a 7" tablet has a minimum +width of 600dp, and a 10" tablet has a minimum width of 720dp. If the smallest available screen +width on a device is less than the value you supply here, then the application is considered +incompatible with that +device. External services such as Android Market use this to determine whether a device +is compatible with your application and prevent incompatible devices from installing it.</p> +<p>Beginning with Android 3.2 (API level 13), using this attribute is the preferred way to +specify the minimum screen size your application requires, instead of using the other attributes +for small, normal, large, and xlarge screens. The advantage of using this attribute is that you +have more control over exactly how much screen space your application needs at a minimum in order +to properly display its UI, rather than relying on the generalized size groups.</p> +<p>This attribute has no default value. If this attribute is not specified, then any of the old +<code><a href="#small">smallScreens</a></code>, <code><a href="#normal">normalScreens</a></code>, +<code><a href="#large">largeScreens</a></code>, or <code><a href="#xlarge">xlargeScreens</a></code> +attributes are used instead to determine the smallest screen required.</p> + <p>This attribute was introduced in API level 13.</p> + </dd> + + <dt id="compatibleWidth">{@code android:compatibleWidthLimitDp}</dt> + <dd>This attribute allows you to enable screen compatibility mode as a user-optional feature by +specifying the maximum "smallest screen width" for which your application is designed. If the value +you supply here is less than the shortest side of the available screen space, users can still +install your application, but are offered to run it in screen compatibility mode. By default, screen +compatibility mode is disabled and your layout is resized to fit the screen as usual, but a +button is available in the system bar that allows the user to toggle screen compatibility mode on +and off. + <p>If your application is compatible with all screen sizes and its layout properly resizes, you do +not need to use this attribute.</p> + <p class="note"><strong>Note:</strong> Currently, screen compatibility mode only emulates handset +screens with a 320dp width, so screen compatibility mode is not applied if your value for {@code +android:compatibleWidthLimitDp} is larger than 320.</p> + <p>This attribute was introduced in API level 13.</p> + </dd> + + <dt id="largestWidth">{@code android:largestWidthLimitDp}</dt> + <dd>This attribute allows you to force enable screen compatibility mode by specifying the maximum +"smallest screen width" for which your application is designed. If the value you supply here is less +than the shortest side of the available screen space, the application runs in screen +compatibility mode with no way for the user to disable it. + <p>If your application is compatible with all screen sizes and its layout properly resizes, you do +not need to use this attribute. Otherwise, you should first consider using the <a +href="#compatibleWidth">{@code android:compatibleWidthLimitDp}</a> attribute. You should use the +{@code android:largestWidthLimitDp} attribute only when your application is functionally broken when +resized for larger screens and screen compatibility mode is the only way that users should use +your application.</p> + <p class="note"><strong>Note:</strong> Currently, screen compatibility mode only emulates handset +screens with a 320dp width, so screen compatibility mode is not applied if your value for {@code +android:largestWidthLimitDp} is larger than 320.</p> + <p>This attribute was introduced in API level 13.</p> + </dd> + <dt><a name="resizeable"></a>{@code android:resizeable}</dt> <dd>Indicates whether the application is resizeable for different screen sizes. This attribute is true, by default, if you have set either <a @@ -75,6 +147,7 @@ when resized.</p> application does not work well on larger screens, follow the guide to <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a> to enable additional screen support.</p> + <p><strong>This attribute is deprecated</strong> as of API level 13.</p> </dd> @@ -91,6 +164,7 @@ href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targe {@code "4"} or higher, the default value for this is {@code "true"}, any value less than {@code "4"} results in this set to {@code "false"}. + <p><strong>This attribute is deprecated</strong> as of API level 13.</p> </dd> <dt><a name="normal"></a>{@code android:normalScreens}</dt> @@ -99,12 +173,13 @@ the default value for this is {@code "true"}, any value less than {@code "4"} re screen, but WQVGA low density and WVGA high density are also considered to be normal. This attribute is "true" by default, and applications currently should leave it that way. + <p><strong>This attribute is deprecated</strong> as of API level 13.</p> </dd> <dt><a name="large"></a>{@code android:largeScreens}</dt> <dd>Indicates whether the application supports larger screen form-factors. A large screen is defined as a screen that is significantly larger - than a "normal" phone screen, and thus might require some special care + than a "normal" handset screen, and thus might require some special care on the application's part to make good use of it, though it may rely on resizing by the system to fill the screen. If the application has set either <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> or <a @@ -112,6 +187,7 @@ href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targe {@code "4"} or higher, the default value for this is {@code "true"}, any value less than {@code "4"} results in this set to {@code "false"}. + <p><strong>This attribute is deprecated</strong> as of API level 13.</p> </dd> <dt><a name="xlarge"></a>{@code android:xlargeScreens}</dt> @@ -125,7 +201,8 @@ href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targe {@code "4"} or higher, the default value for this is {@code "true"}, any value less than {@code "4"} results in this set to {@code "false"}. - <p>This attribute was introduced in API Level 9.</p> + <p>This attribute was introduced in API level 9.</p> + <p><strong>This attribute is deprecated</strong> as of API level 13.</p> </dd> <dt><a name="any"></a>{@code android:anyDensity}</dt> @@ -142,6 +219,7 @@ the default value for this is {@code "true"}. Otherwise, it is {@code "false"}. down application assets by a factor of 0.75 (low dpi screens) or scale them up by a factor of 1.5 (high dpi screens), when you don't provide alternative resources for a specifc screen density. The screen density is expressed as dots-per-inch (dpi).</p> + <p><strong>This attribute is deprecated</strong> as of API level 13.</p> </dd> diff --git a/docs/html/guide/topics/resources/providing-resources.jd b/docs/html/guide/topics/resources/providing-resources.jd index a996ccc..ea778c1 100644 --- a/docs/html/guide/topics/resources/providing-resources.jd +++ b/docs/html/guide/topics/resources/providing-resources.jd @@ -335,80 +335,101 @@ indicates the current locale.</p> </tr> <tr id="SmallestScreenWidthQualifier"> <td>Smallest screen width</td> - <td>Examples:<br/> + <td><code>sw<N>dp</code><br/><br/> + Examples:<br/> <code>sw320dp</code><br/> <code>sw600dp</code><br/> <code>sw720dp</code><br/> etc. </td> <td> - <p>Specifies a minimum "smallest screen width," in "dp" units, at which the resource - should be used. This configuration value represents the base screen size - of the device, regardless of the orientation of the display. It is based - on the smallest width the application will have in which to perform its - UI layout (in dp units) regardless of the orientation of the screen. The - value here takes into account screen decorations so if the device has some - persistent UI elements on the left or right edge of the display it must - present a value here that is smaller than the real screen size, accounting - for these UI elements reducing the application's available space.</p> - <p>Some values you may use here for common screen sizes:</p> + <p>Specifies the "smallest width" in {@code dp} units that must be available to your + application in order for the resources to be used, regardless of the screen's current + orientation. For example, if your layout requires that its shortest side be at least 600 + dp in length at all times, then you can use this to create the layout resources, {@code + res/layout-sw600dp/}, and the system will use them only when the shortest side of + available screen space it at least 600dp.</p> + <p>The width against which the system compares your value takes into account screen + decorations and system UI. For example, if the device has some persistent UI elements on the + left or right edge of the display, the system declares its own available width as one that + is smaller than the actual screen size, accounting for these UI elements because those are + screen pixels not available for your UI. Thus, the value you use should be the actual + smallest width required by your layout.</p> + <p>Some values you might use here for common screen sizes:</p> <ul> - <li>240x320 ldpi (QVGA phone): 320 - <li>320x480 mdpi (phone): 320 - <li>480x800 hdpi (high density phone): 320 - <li>480x800 mdpi (tablet/phone): 480 - <li>600x1024 mdpi (7" tablet): 600 - <li>720x1280 mdpi (10" tablet): 720 + <li>320, for devices with screen configurations such as: + <ul> + <li>240x320 ldpi (QVGA handset)</li> + <li>320x480 mdpi (handset)</li> + <li>480x800 hdpi (high density handset)</li> + </ul> + </li> + <li>480, for screens such as 480x800 mdpi (tablet/handset).</li> + <li>600, for screens such as 600x1024 mdpi (7" tablet).</li> + <li>720, for screens such as 720x1280 mdpi (10" tablet).</li> </ul> - <p><em>Added in API Level 13.</em></p> - <p>Also see the {@link android.content.res.Configuration#smallestScreenWidthDp} - configuration field, which holds the current smallest screen width.</p> + <p>When your application provides multiple resource directories with different values for + this qualifier, the system uses the one closest to (without exceeding) the smallest width + for the available space. </p> + <p><em>Added in API level 13.</em></p> + <p>Also see the <a + href="{@docRoot}guide/topics/manifest/supports-screens-element.html#requiresSmallest">{@code + android:requiresSmallestWidthDp}</a> attribute, which declares the smallest available width + with which your application is compatible, and the {@link + android.content.res.Configuration#smallestScreenWidthDp} configuration field, which holds + the current smallest screen width for the device.</p> </td> </tr> <tr id="ScreenWidthQualifier"> <td>Screen width</td> - <td>Examples:<br/> + <td><code>w<N>dp</code><br/><br/> + Examples:<br/> <code>w720dp</code><br/> <code>w1024dp</code><br/> etc. </td> <td> - <p>Specifies a minimum screen width, in "dp" units, at which the resource - should be used. This configuration value will change when the orientation - changes between landscape and portrait to match the current actual width. - When multiple screen width configurations are available, the closest to - the current screen width will be used. The - value here takes into account screen decorations so if the device has some - persistent UI elements on the left or right edge of the display it must - present a value here that is smaller than the real screen size, accounting - for these UI elements reducing the application's available space.</p> - <p><em>Added in API Level 13.</em></p> + <p>Specifies a minimum screen width, in {@code dp} units at which the resource + should be used—defined by the <code><N></code> value. This + configuration value will change when the orientation + changes between landscape and portrait to match the current actual width.</p> + <p>When your application provides multiple resource directories with different values + for this configuration, the system uses the one closest to (without exceeding) + the device's current screen width. The + value here takes into account screen decorations, so if the device has some + persistent UI elements on the left or right edge of the display, it + uses a value for the width that is smaller than the real screen size, accounting + for these UI elements and reducing the application's available space.</p> + <p><em>Added in API level 13.</em></p> <p>Also see the {@link android.content.res.Configuration#screenWidthDp} configuration field, which holds the current screen width.</p> </td> </tr> <tr id="ScreenHeightQualifier"> <td>Screen height</td> - <td>Examples:<br/> + <td><code>h<N>dp</code><br/><br/> + Examples:<br/> <code>h720dp</code><br/> <code>h1024dp</code><br/> etc. </td> <td> - <p>Specifies a minimum screen height, in "dp" units, at which the resource - should be used. This configuration value will change when the orientation - changes between landscape and portrait to match the current actual height. - When multiple screen height configurations are available, the closest to - the current screen height will be used. The - value here takes into account screen decorations so if the device has some - persistent UI elements on the left or right edge of the display it must - present a value here that is smaller than the real screen size, accounting - for these UI elements reducing the application's available space. Screen + <p>Specifies a minimum screen height, in "dp" units at which the resource + should be used—defined by the <code><N></code> value. This + configuration value will change when the orientation + changes between landscape and portrait to match the current actual height.</p> + <p>When your application provides multiple resource directories with different values + for this configuration, the system uses the one closest to (without exceeding) + the device's current screen height. The + value here takes into account screen decorations, so if the device has some + persistent UI elements on the top or bottom edge of the display, it uses + a value for the height that is smaller than the real screen size, accounting + for these UI elements and reducing the application's available space. Screen decorations that are not fixed (such as a phone status bar that can be hidden when full screen) are <em>not</em> accounted for here, nor are - window decorations like title bar, so applications must be prepared to + window decorations like the title bar or action bar, so applications must be prepared to deal with a somewhat smaller space than they specify. - <p><em>Added in API Level 13.</em></p> + <p><em>Added in API level 13.</em></p> <p>Also see the {@link android.content.res.Configuration#screenHeightDp} configuration field, which holds the current screen width.</p> </td> @@ -444,9 +465,9 @@ indicates the current locale.</p> medium-density HVGA screen. The minimum layout size for this screen configuration is approximately 720x960 dp units. In most cases, devices with extra large screens would be too large to carry in a pocket and would most likely - be tablet-style devices. <em>Added in API Level 9.</em></li> + be tablet-style devices. <em>Added in API level 9.</em></li> </ul> - <p><em>Added in API Level 4.</em></p> + <p><em>Added in API level 4.</em></p> <p>See <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a> for more information.</p> <p>Also see the {@link android.content.res.Configuration#screenLayout} configuration field, @@ -465,7 +486,7 @@ or large.</p> <li>{@code long}: Long screens, such as WQVGA, WVGA, FWVGA</li> <li>{@code notlong}: Not long screens, such as QVGA, HVGA, and VGA</li> </ul> - <p><em>Added in API Level 4.</em></p> + <p><em>Added in API level 4.</em></p> <p>This is based purely on the aspect ratio of the screen (a "long" screen is wider). This is not related to the screen orientation.</p> <p>Also see the {@link android.content.res.Configuration#screenLayout} configuration field, @@ -503,7 +524,7 @@ which indicates the current device orientation.</p> <li>{@code car}: Device is in a car dock</li> <li>{@code desk}: Device is in a desk dock</li> </ul> - <p><em>Added in API Level 8.</em></p> + <p><em>Added in API level 8.</em></p> <p>This can change during the life of your application if the user places the device in a dock. You can enable or disable this mode using {@link android.app.UiModeManager}. See <a href="runtime-changes.html">Handling Runtime Changes</a> for @@ -521,7 +542,7 @@ information about how this affects your application during runtime.</p> <li>{@code night}: Night time</li> <li>{@code notnight}: Day time</li> </ul> - <p><em>Added in API Level 8.</em></p> + <p><em>Added in API level 8.</em></p> <p>This can change during the life of your application if night mode is left in auto mode (default), in which case the mode changes based on the time of day. You can enable or disable this mode using {@link android.app.UiModeManager}. See <a @@ -549,7 +570,7 @@ Level 8</em></li> <li>{@code nodpi}: This can be used for bitmap resources that you do not want to be scaled to match the device density.</li> </ul> - <p><em>Added in API Level 4.</em></p> + <p><em>Added in API level 4.</em></p> <p>There is thus a 3:4:6:8 scaling ratio between the four densities, so a 9x9 bitmap in ldpi is 12x12 in mdpi, 18x18 in hdpi and 24x24 in xhdpi.</p> <p>When Android selects which resource files to use, @@ -689,17 +710,17 @@ orientation" described above.</p> </tr> --> <tr id="VersionQualifier"> - <td>Platform Version (API Level)</td> + <td>Platform Version (API level)</td> <td>Examples:<br/> <code>v3</code><br/> <code>v4</code><br/> <code>v7</code><br/> etc.</td> <td> - <p>The API Level supported by the device. For example, <code>v1</code> for API Level -1 (devices with Android 1.0 or higher) and <code>v4</code> for API Level 4 (devices with Android + <p>The API level supported by the device. For example, <code>v1</code> for API level +1 (devices with Android 1.0 or higher) and <code>v4</code> for API level 4 (devices with Android 1.6 or higher). See the <a -href="{@docRoot}guide/appendix/api-levels.html">Android API Levels</a> document for more information +href="{@docRoot}guide/appendix/api-levels.html">Android API levels</a> document for more information about these values.</p> <p class="caution"><strong>Caution:</strong> Android 1.5 and 1.6 only match resources with this qualifier when it exactly matches the platform version. See the section below about <a @@ -863,7 +884,7 @@ cannot use the resources named with the new qualifier. For example, if your <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> is set to 4, and you qualify all of your drawable resources using <a href="#NightQualifier">night mode</a> ({@code night} or {@code notnight}, which were added in API -Level 8), then an API Level 4 device cannot access your drawable resources and will crash. In this +Level 8), then an API level 4 device cannot access your drawable resources and will crash. In this case, you probably want {@code notnight} to be your default resources, so you should exclude that qualifier so your drawable resources are in either {@code drawable/} or {@code drawable-night/}.</p> @@ -896,7 +917,7 @@ compatibility for these versions.</p> <dd>{@code long} and {@code notlong}</dd> </dl> -<p>These configuration qualifiers were introduced in Android 1.6, so Android 1.5 (API Level 3) and +<p>These configuration qualifiers were introduced in Android 1.6, so Android 1.5 (API level 3) and lower does not support them. If you use these configuration qualifiers and do not provide corresponding default resources, then an Android 1.5 device might use any one of the resource directories named with the above screen configuration qualifiers, because it ignores these @@ -926,9 +947,9 @@ is r6 or greater. <p>You need SDK Tools, Revision 6 (or greater), because it includes a new packaging tool that automatically applies an appropriate <a href="#VersionQualifier">version qualifier</a> to any resource directory named with a qualifier that does not exist in Android 1.0. For example, because -the density qualifier was introduced in Android 1.6 (API Level 4), when the packaging tool +the density qualifier was introduced in Android 1.6 (API level 4), when the packaging tool encounters a resource directory using the density qualifier, it adds {@code v4} to the directory -name to ensure that older versions do not use those resources (only API Level 4 and higher support +name to ensure that older versions do not use those resources (only API level 4 and higher support that qualifier). Thus, by putting your medium-density resources in a directory <em>without</em> the {@code mdpi} qualifier, they are still accessible by Android 1.5, and any device that supports the density qualifer and has a medium-density screen also uses the default resources (which are mdpi) @@ -937,7 +958,7 @@ resources).</p> </li> </ol> -<p class="note"><strong>Note:</strong> Later versions of Android, such as API Level 8, +<p class="note"><strong>Note:</strong> Later versions of Android, such as API level 8, introduce other configuration qualifiers that older version do not support. To provide the best compatibility, you should always include a set of default resources for each type of resource that your application uses, as discussed above to provide the best device compatibility.</p> @@ -1068,7 +1089,7 @@ href="accessing-resources.html">Accessing Resources</a>.</p> <p>The correct behavior is for the system to match resources marked with a <a href="#VersionQualifier">version qualifier</a> equal -to or less than the platform version on the device, but on Android 1.5 and 1.6, (API Level 3 and 4), +to or less than the platform version on the device, but on Android 1.5 and 1.6, (API level 3 and 4), there is a bug that causes the system to match resources marked with the version qualifier only when it exactly matches the version on the device.</p> |