diff options
Diffstat (limited to 'docs/html/guide/topics/resources/providing-resources.jd')
| -rw-r--r-- | docs/html/guide/topics/resources/providing-resources.jd | 137 |
1 files changed, 85 insertions, 52 deletions
diff --git a/docs/html/guide/topics/resources/providing-resources.jd b/docs/html/guide/topics/resources/providing-resources.jd index ea778c1..252c153 100644 --- a/docs/html/guide/topics/resources/providing-resources.jd +++ b/docs/html/guide/topics/resources/providing-resources.jd @@ -334,7 +334,7 @@ indicates the current locale.</p> </td> </tr> <tr id="SmallestScreenWidthQualifier"> - <td>Smallest screen width</td> + <td>smallestWidth</td> <td><code>sw<N>dp</code><br/><br/> Examples:<br/> <code>sw320dp</code><br/> @@ -343,18 +343,23 @@ indicates the current locale.</p> etc. </td> <td> - <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>The fundamental size of a screen, as indicated by the shortest dimension of the available +screen area. Specifically, the device's smallestWidth is the shortest of the screen's available +height and width (you may also think of it as the "smallest possible width" for the screen). You can +use this qualifier to ensure that, regardless of the screen's current orientation, your +application's has at least {@code <N>} dps of width available for it UI.</p> + <p>For example, if your layout requires that its smallest dimension of screen area be at +least 600 dp at all times, then you can use this qualifer to create the layout resources, {@code +res/layout-sw600dp/}. The system will use these resources only when the smallest dimension of +available screen is at least 600dp, regardless of whether the 600dp side is the user-perceived +height or width. The smallestWidth is a fixed screen size characteristic of the device; <strong>the +device's smallestWidth does not change when the screen's orientation changes</strong>.</p> + <p>The smallestWidth of a device takes into account screen decorations and system UI. For +example, if the device has some persistent UI elements on the screen that account for space along +the axis of the smallestWidth, the system declares the smallestWidth to be smaller than the actual +screen size, because those are screen pixels not available for your UI. Thus, the value you use +should be the actual smallest dimension <em>required by your layout</em> (usually, this value is the +"smallest width" that your layout supports, regardless of the screen's current orientation).</p> <p>Some values you might use here for common screen sizes:</p> <ul> <li>320, for devices with screen configurations such as: @@ -369,19 +374,22 @@ indicates the current locale.</p> <li>720, for screens such as 720x1280 mdpi (10" tablet).</li> </ul> <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> + the smallestWidth qualifier, the system uses the one closest to (without exceeding) the +device's smallestWidth. </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> +href="{@docRoot}guide/topics/manifest/supports-screens-element.html#requiresSmallest">{@code +android:requiresSmallestWidthDp}</a> attribute, which declares the minimum smallestWidth with which +your application is compatible, and the {@link +android.content.res.Configuration#smallestScreenWidthDp} configuration field, which holds the +device's smallestWidth value.</p> + <p>For more information about designing for different screens and using this +qualifier, see the <a href="{@docRoot}guide/practices/screens_support.html">Supporting +Multiple Screens</a> developer guide.</p> </td> </tr> <tr id="ScreenWidthQualifier"> - <td>Screen width</td> + <td>Available width</td> <td><code>w<N>dp</code><br/><br/> Examples:<br/> <code>w720dp</code><br/> @@ -389,7 +397,7 @@ indicates the current locale.</p> etc. </td> <td> - <p>Specifies a minimum screen width, in {@code dp} units at which the resource + <p>Specifies a minimum available 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> @@ -403,10 +411,13 @@ indicates the current locale.</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> + <p>For more information about designing for different screens and using this +qualifier, see the <a href="{@docRoot}guide/practices/screens_support.html">Supporting +Multiple Screens</a> developer guide.</p> </td> </tr> <tr id="ScreenHeightQualifier"> - <td>Screen height</td> + <td>Available height</td> <td><code>h<N>dp</code><br/><br/> Examples:<br/> <code>h720dp</code><br/> @@ -414,7 +425,7 @@ indicates the current locale.</p> etc. </td> <td> - <p>Specifies a minimum screen height, in "dp" units at which the resource + <p>Specifies a minimum available 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> @@ -432,6 +443,9 @@ indicates the current locale.</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> + <p>For more information about designing for different screens and using this +qualifier, see the <a href="{@docRoot}guide/practices/screens_support.html">Supporting +Multiple Screens</a> developer guide.</p> </td> </tr> <tr id="ScreenSizeQualifier"> @@ -444,30 +458,35 @@ indicates the current locale.</p> </td> <td> <ul class="nolist"> - <li>{@code small}: Screens based on the space available on a - low-density QVGA screen. Considering a portrait HVGA display, this has - the same available width but less height—it is 3:4 vs. HVGA's - 2:3 aspect ratio. The minimum layout size for this screen configuration + <li>{@code small}: Screens that are of similar size to a + low-density QVGA screen. The minimum layout size for a small screen is approximately 320x426 dp units. Examples are QVGA low density and VGA high density.</li> - <li>{@code normal}: Screens based on the traditional - medium-density HVGA screen. A screen is considered to be normal if it is - at least this size (independent of density) and not larger. The minimum - layout size for this screen configuration is approximately 320x470 dp units. Examples + <li>{@code normal}: Screens that are of similar size to a + medium-density HVGA screen. The minimum + layout size for a normal screen is approximately 320x470 dp units. Examples of such screens a WQVGA low density, HVGA medium density, WVGA high density.</li> - <li>{@code large}: Screens based on the space available on a - medium-density VGA screen. Such a screen has significantly more - available space in both width and height than an HVGA display. - The minimum layout size for this screen configuration is approximately 480x640 dp units. + <li>{@code large}: Screens that are of similar size to a + medium-density VGA screen. + The minimum layout size for a large screen is approximately 480x640 dp units. Examples are VGA and WVGA medium density screens.</li> <li>{@code xlarge}: Screens that are considerably larger than the traditional - medium-density HVGA screen. The minimum layout size for this screen configuration + medium-density HVGA screen. The minimum layout size for an xlarge screen 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> </ul> + <p class="note"><strong>Note:</strong> Using a size qualifier does not imply that the +resources are <em>only</em> for screens of that size. If you do not provide alternative +resources with qualifiers that better match the current device configuration, the system may use +whichever resources are the <a href="#BestMatch">best match</a>.</p> + <p class="caution"><strong>Caution:</strong> If all your resources use a size qualifier that +is <em>larger</em> than the current screen, the system will <strong>not</strong> use them and your +application will crash at runtime (for example, if all layout resources are tagged with the {@code +xlarge} qualifier, but the device is a normal-size screen).</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, @@ -557,7 +576,8 @@ application during runtime.</p> <code>mdpi</code><br/> <code>hdpi</code><br/> <code>xhdpi</code><br/> - <code>nodpi</code> + <code>nodpi</code><br/> + <code>tvdpi</code> </td> <td> <ul class="nolist"> @@ -569,21 +589,23 @@ application during runtime.</p> 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> + <li>{@code tvdpi}: Screens somewhere between mdpi and hdpi; approximately 213dpi. This is +not considered a "primary" density group. It is mostly intended for televisions and most +apps shouldn't need it—providing mdpi and hdpi resources is sufficient for most apps and +the system will scale them as appropriate. This qualifier was introduced with API level 13.</li> </ul> - <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, - it handles screen density differently than the other qualifiers. - In step 1 of <a href="#BestMatch">How Android finds the best - matching directory</a> (below), screen density is always considered to - be a match. In step 4, if the qualifier being considered is screen - density, Android selects the best final match at that point, - without any need to move on to step 5. - </p> + <p>There is a 3:4:6:8 scaling ratio between the four primary densities (ignoring the +tvdpi density). So, a 9x9 bitmap in ldpi is 12x12 in mdpi, 18x18 in hdpi and 24x24 in xhdpi.</p> + <p>If you decide that your image resources don't look good enough on a television or +other certain devices and want to try tvdpi resources, the scaling factor is 1.33*mdpi. For +example, a 100px x 100px image for mdpi screens should be 133px x 133px for tvdpi.</p> + <p class="note"><strong>Note:</strong> Using a density qualifier does not imply that the +resources are <em>only</em> for screens of that density. If you do not provide alternative +resources with qualifiers that better match the current device configuration, the system may use +whichever resources are the <a href="#BestMatch">best match</a>.</p> <p>See <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple -Screens</a> for more information about how to handle screen sizes and how Android might scale -your bitmaps.</p> +Screens</a> for more information about how to handle different screen densities and how Android +might scale your bitmaps to fit the current density.</p> </td> </tr> <tr id="TouchscreenQualifier"> @@ -993,7 +1015,10 @@ Primary text input method = <code>12key</code> </p> <p>By comparing the device configuration to the available alternative resources, Android selects -drawables from {@code drawable-en-port}. It arrives at this decision using the following logic:</p> +drawables from {@code drawable-en-port}.</p> + +<p>The system arrives at its decision for which resources to use with the following +logic:</p> <div class="figure" style="width:280px"> @@ -1069,6 +1094,14 @@ language is English ("en"), then any resource directory that has a language qual something other than English is never included in the pool of resources checked (though a resource directory <em>without</em> the language qualifier is still included).</p> +<p>When selecting resources based on the screen size qualifiers, the system will use resources +designed for a screen smaller than the current screen if there are no resources that better match +(for example, a large-size screen will use normal-size screen resources if necessary). However, if +the only available resources are <em>larger</em> than the current screen, the system will +<strong>not</strong> use them and your application will crash if no other resources match the device +configuration (for example, if all layout resources are tagged with the {@code xlarge} qualifier, +but the device is a normal-size screen).</p> + <p class="note"><strong>Note:</strong> The <em>precedence</em> of the qualifier (in <a href="#table2">table 2</a>) is more important than the number of qualifiers that exactly match the device. For example, in step 4 above, the last |