diff options
Diffstat (limited to 'docs/html')
| -rw-r--r-- | docs/html/guide/practices/screens_support.jd | 98 | ||||
| -rw-r--r-- | docs/html/guide/topics/manifest/supports-screens-element.jd | 50 | ||||
| -rw-r--r-- | docs/html/guide/topics/resources/providing-resources.jd | 54 |
3 files changed, 120 insertions, 82 deletions
diff --git a/docs/html/guide/practices/screens_support.jd b/docs/html/guide/practices/screens_support.jd index 42000c4..6dec4b3 100644 --- a/docs/html/guide/practices/screens_support.jd +++ b/docs/html/guide/practices/screens_support.jd @@ -648,16 +648,17 @@ layouts was to put them in a directory with the {@code xlarge} configuration qua {@code res/layout-xlarge/}). In order to accommodate other types of tablets and screen sizes—in particular, 7" tablets—Android 3.2 introduces a new way to specify resources for more discrete screen sizes. The new technique is based on the amount of space your layout needs -(such as 600dp of width), rather than trying to make your layout fit generalized size groups (such -as <em>large</em> or <em>xlarge</em>).</p> +(such as 600dp of width), rather than trying to make your layout fit the generalized size groups +(such as <em>large</em> or <em>xlarge</em>).</p> <p>The reason designing for 7" tablets is tricky when using the generalized size groups is that a 7" tablet is technically in the same group as a 5" handset (the <em>large</em> group). While these two devices are seemingly close to each other in size, the amount of space for an application's UI is significantly different, as is the style of user interaction. Thus, a 7" and 5" -screen should not always use the same layout. To make it possible for these two kinds of screens to -offer different layouts, Android now allows you to specify your layout resources based on the width -and/or height that's actually available for your application's layout, specified in dp units.</p> +screen should not always use the same layout. To make it possible for you to provide different +layouts for these two kinds of screens, Android now allows you to specify your layout resources +based on the width and/or height that's actually available for your application's layout, specified +in dp units.</p> <p>For example, after you've designed the layout you want to use for tablet-style devices, you might determine that the layout stops working well when the screen is less than 600dp wide. This threshold @@ -668,16 +669,20 @@ such, you can now specify that these layout resources should be used only when t <p>You should either pick a width and design to it as your minimum size, or test what is the smallest width your layout supports once it's complete.</p> +<p class="note"><strong>Note:</strong> Remember that all the figures used with these new size APIs +are density-indpendent pixel (dp) values and your layout dimensions should also always be defined +using dp units, because what you care about is the amount of screen space available after the system +accounts for screen density (as opposed to using raw pixel resolution). For more information about +density-indpendent pixels, read <a href="#terms">Terms and concepts</a>, earlier in this +document.</p> + <h3 id="NewQualifiers">Using new size qualifiers</h3> -<p>The numbers describing the width and height available for your layout are all in dp -units—remember that your layout dimensions should always be defined using dp units, -because what you care about is the amount of space available after the system accounts for screen -density (as opposed to using raw pixel numbers). The different resource configurations that you can -specify based on the space available for your layout are summarized in table 2. When building an -application for Android 3.2 and higher, you should use these new qualifiers instead of those for the -traditional screen size groups (small, normal, large, and xlarge).</p> +<p>The different resource configurations that you can specify based on the space available for your +layout are summarized in table 2. These new qualifiers offer you more control over the specific +screen sizes your application supports, compared to the traditional screen size groups (small, +normal, large, and xlarge).</p> <p class="note"><strong>Note:</strong> The sizes that you specify using these qualifiers are <strong>not the actual screen sizes</strong>. Rather, the sizes are for the width or height in dp @@ -694,30 +699,40 @@ the space available for your layout and you must account for it in your design.< (introduced in Android 3.2).</p> <table> <tr><th>Screen configuration</th><th>Qualifier values</th><th>Description</th></tr> - <tr><td>Smallest available width</td> + <tr><td>smallestWidth</td> <td><code>sw<N>dp</code><br/><br/> Examples:<br/> <code>sw600dp</code><br/> <code>sw720dp</code><br/> </td> <td> - <p>Specifies the "smallest width" in dp units that must be available to your -application in order for the resources to be used—defined by the <code><N></code> -value—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 put your layout files in <code>res/layout-sw600dp/</code> and -the system will use them only when the shortest side of available screen space it at least -600dp.</p> - <p>This is the most important size configuration value, because it replaces the old screen size -buckets with a discrete number that specifies the effective size available for your UI. This number -is based on width because that is most often the driving factor in designing a layout. A UI will -often scroll vertically, but have fairly hard constraints on the minimum space it needs -horizontally. The available width is also the key factor in determining whether to use a one-pane -layout for handsets or multi-pane layout for tablets.</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.</p> + <p>This is an alternative to the generalized screen size qualifiers (small, normal, large, xlarge) +that allows you to define a discrete number for the effective size available for your UI. +Using smallestWidth to determine the general screen size is useful because width is +often the driving factor in designing a layout. A UI will often scroll vertically, but have fairly +hard constraints on the minimum space it needs horizontally. The available width is also the key +factor in determining whether to use a one-pane layout for handsets or multi-pane layout for +tablets. Thus, you likely care most about what the smallest possible width will be on each +device.</p> </td> </tr> <tr> - <td>Available width</td> + <td>Available screen width</td> <td><code>w<N>dp</code><br/><br/> Examples:<br/> <code>w720dp</code><br/> @@ -735,7 +750,7 @@ of using both the screen size and orientation qualifiers together.</p> </td> </tr> <tr> - <td>Available height</td> + <td>Available screen height</td> <td><code>h<N>dp</code><br/><br/> Examples:<br/> <code>h720dp</code><br/> @@ -764,6 +779,10 @@ will depend on your particular design—maybe you need a 720dp width for you maybe 600dp is enough, or 480dp, or some number between these. Using these qualifiers in table 2, you are in control of the precise size at which your layout changes.</p> +<p>For more discussion about these size configuration qualifiers, see the <a +href="{@docRoot}guide/topics/resources/providing-resources.html#SmallestScreenWidthQualifier"> +Providing Resources</a> document.</p> + <h3 id="ConfigurationExamples">Configuration examples</h3> @@ -836,17 +855,16 @@ href="{@docRoot}guide/topics/manifest/supports-screens-element.html"><support manifest element:</p> <dl> - <!-- - - #### Sorry, Android Market does not yet support filtering based on this element. #### - + <dt><a href="{@docRoot}guide/topics/manifest/supports-screens-element.html#requiresSmallest"> {@code android:requiresSmallestWidthDp}</a></dt> - <dd>This attribute specifies the minimum "smallest 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. + <dd>Specifies the minimum smallestWidth required. The smallestWidth is the shortest dimension of +the screen space (in {@code dp} units) that must be available to your application UI—that is, +the shortest of the available screen's two dimensions. So, in order for a device to be considered +compatible with your application, the device's smallestWidth must be equal to or greater than this +value. (Usually, the value you supply for this is the "smallest width" that your layout supports, +regardless of the screen's current orientation.) <p>For example, if your application is only for tablet-style devices with a 600dp smallest available width:</p> <pre> @@ -858,8 +876,14 @@ smallest available width:</p> <p>However, if your application supports all screen sizes supported by Android (as small as 426dp x 320dp), then you don't need to declare this attribute, because the smallest width your application requires is the smallest possible on any device.</p> + + <p class="caution"><strong>Caution:</strong> The Android system does not pay attention to this +attribute, so it does not affect how your application behaves at runtime. Instead, it is used +to enable filtering for your application on services such as Android Market. However, +<strong>Android Market currently does not support this attribute for filtering</strong> (on Android +3.2), so you should continue using the other size attributes if your application does not support +small screens.</p> </dd> - --> <dt><a href="{@docRoot}guide/topics/manifest/supports-screens-element.html#compatibleWidth"> diff --git a/docs/html/guide/topics/manifest/supports-screens-element.jd b/docs/html/guide/topics/manifest/supports-screens-element.jd index a659678..81d6e27 100644 --- a/docs/html/guide/topics/manifest/supports-screens-element.jd +++ b/docs/html/guide/topics/manifest/supports-screens-element.jd @@ -129,26 +129,24 @@ Screens</a> document for more information).</p> </dd> <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. + <dd>Specifies the minimum smallestWidth required. The smallestWidth is the shortest dimension of +the screen space (in {@code dp} units) that must be available to your application UI—that is, +the shortest of the available screen's two dimensions. So, in order for a device to be considered +compatible with your application, the device's smallestWidth must be equal to or greater than this +value. (Usually, the value you supply for this is the "smallest width" that your layout supports, +regardless of the screen's current orientation.) + + <p>For example, a typical handset screen has a smallestWidth of 320dp, a 7" tablet has a +smallestWidth of 600dp, and a 10" tablet has a smallestWidth of 720dp. These values are generally +the smallestWidth because they are the shortest dimension of the screen's available space.</p> + +<p>The size 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 display, the system declares +the device's smallestWidth 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 minimum width required by your layout, regardless of the screen's current +orientation.</p> - <p class="caution"><strong>Caution:</strong> The Android system does not pay attention to this -attribute, so it does not affect how your application behaves at runtime. Instead, it is used -to enable filtering for your application on services such as Android Market. However, -<strong>Android Market currently does not support this attribute</strong> (on Android 3.2), so you -should continue using the other size attributes if your application does not support -small screens.</p> - -<!-- - #### Android Market does not support this attribute yet. #### - -<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 @@ -156,12 +154,14 @@ 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 class="caution"><strong>Caution:</strong> The Android system does not pay attention to this +attribute, so it does not affect how your application behaves at runtime. Instead, it is used +to enable filtering for your application on services such as Android Market. However, +<strong>Android Market currently does not support this attribute for filtering</strong> (on Android +3.2), so you should continue using the other size attributes if your application does not support +small screens.</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 diff --git a/docs/html/guide/topics/resources/providing-resources.jd b/docs/html/guide/topics/resources/providing-resources.jd index 9dcda39..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 available 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,15 +374,18 @@ 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"> @@ -403,6 +411,9 @@ 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"> @@ -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"> |