diff options
author | Scott Main <smain@google.com> | 2011-10-07 01:33:09 -0700 |
---|---|---|
committer | Scott Main <smain@google.com> | 2011-10-26 15:21:40 -0700 |
commit | 5e44f68a66041332fa28fc2359eaeab8fc452fac (patch) | |
tree | de1c2bed7e010dd6dcc1b8188fb928b8e0a5d138 /docs/html/guide/practices | |
parent | a6d2e6b952d535fec4483d67ea52947e6e3bc629 (diff) | |
download | frameworks_base-5e44f68a66041332fa28fc2359eaeab8fc452fac.zip frameworks_base-5e44f68a66041332fa28fc2359eaeab8fc452fac.tar.gz frameworks_base-5e44f68a66041332fa28fc2359eaeab8fc452fac.tar.bz2 |
docs: add guide for optimizing tablet apps for handsets
deprecate "optimizing for 3.0" doc
Change-Id: I290ff5cd22c714e639fb820251c9e1d763f750df
Diffstat (limited to 'docs/html/guide/practices')
-rw-r--r-- | docs/html/guide/practices/optimizing-for-3.0.jd | 27 | ||||
-rw-r--r-- | docs/html/guide/practices/screens-distribution.jd | 70 | ||||
-rw-r--r-- | docs/html/guide/practices/screens_support.jd | 3 | ||||
-rw-r--r-- | docs/html/guide/practices/tablets-and-handsets.jd | 491 |
4 files changed, 571 insertions, 20 deletions
diff --git a/docs/html/guide/practices/optimizing-for-3.0.jd b/docs/html/guide/practices/optimizing-for-3.0.jd index a24dba8..39662f1 100644 --- a/docs/html/guide/practices/optimizing-for-3.0.jd +++ b/docs/html/guide/practices/optimizing-for-3.0.jd @@ -1,6 +1,31 @@ page.title=Optimizing Apps for Android 3.0 @jd:body + +<div id="deprecatedSticker"> + <a href="#" + onclick="$('#naMessage').show();$('#deprecatedSticker').hide();return false"> + <strong>This doc is deprecated</strong></a> +</div> + + +<div id="naMessage" style="display:block"> +<div><p><strong>This document has been deprecated.</strong></p> + <p>To learn about how you can optimize your app for both tablets and handsets, please +read the guide to <a href="tablets-and-handsets.html">Supporting Tablets and +Handsets</a>.</p> + + <input style="margin-top:1em;padding:5px" type="button" + value="That's nice, but I still want to read this document" +onclick="$('#naMessage').hide();$('#deprecatedSticker').show()" /> +</div> +</div> + + + + + + <div id="qv-wrapper"> <div id="qv"> <h2>In this document</h2> @@ -25,6 +50,8 @@ page.title=Optimizing Apps for Android 3.0 <h2>See also</h2> <ol> + <li><a href="tablets-and-handsets.html">Supporting Tablets +and Handsets</a></li> <li><a href="{@docRoot}sdk/compatibility-library.html">Compatibility Library</a></li> <li><a href="http://code.google.com/p/iosched/">Google I/O App source code</a></li> diff --git a/docs/html/guide/practices/screens-distribution.jd b/docs/html/guide/practices/screens-distribution.jd index 951e364..60c9c95 100644 --- a/docs/html/guide/practices/screens-distribution.jd +++ b/docs/html/guide/practices/screens-distribution.jd @@ -15,8 +15,8 @@ screen configuration</li> <h2>In this document</h2> <ol> - <li><a href="#FilteringHansetApps">Filtering a Handset Application from Tablets</a></li> - <li><a href="#FilteringTabletApps">Filtering a Tablet Application from Handsets</a></li> + <li><a href="#FilteringHansetApps">Declaring an App is Only for Handsets</a></li> + <li><a href="#FilteringTabletApps">Declaring an App is Only for Tablets</a></li> <li><a href="#MultiApks">Publishing Multiple APKs for Different Screens</a></li> </ol> @@ -48,7 +48,7 @@ available to the greatest number of users with different devices, using a single -<h2 id="FilteringHandsetApps">Filtering a Handset Application from Tablets</h2> +<h2 id="FilteringHandsetApps">Declaring an App is Only for Handsets</h2> <p>Because the system generally scales applications to fit larger screens well, you shouldn't need to filter your application from larger screens. As long as you follow the <a @@ -79,7 +79,6 @@ entry looks like if your application is compatible with only small and normal sc <pre> <manifest ... > - ... <compatible-screens> <!-- all small size screens --> <screen android:screenSize="small" android:screenDensity="ldpi" /> @@ -92,6 +91,7 @@ entry looks like if your application is compatible with only small and normal sc <screen android:screenSize="normal" android:screenDensity="hdpi" /> <screen android:screenSize="normal" android:screenDensity="xhdpi" /> </compatible-screens> + ... <application ... > ... <application> @@ -108,36 +108,66 @@ to specify each screen density your application supports.</p> -<h2 id="FilteringTabletApps">Filtering a Tablet Application from Handsets</h2> -<p>If your application's UI is adversely affected when the system scales your application down to -smaller screens, you should add <a -href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">alternative -layouts</a> for smaller screens to adjust the layout for those screens. However, sometimes your -layout still might not fit a smaller screen or you've explicitly designed your application only for -tablets and other large devices. In this case, you can manage the availability of your application -to smaller screens by using the <a +<h2 id="FilteringTabletApps">Declaring an App is Only for Tablets</h2> + +<p>If you don't want your app to be used on handsets (perhaps your app truly makes sense only on a +large screen) or you need time to optimize it for smaller screens, you can prevent small-screen +devices from downloading your app by using the <a href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code <supports-screens>}</a> manifest element.</p> -<p>For example, if you want your application to be available only to large and extra large -screens, you can declare the element in your manifest like this:</p> +<p>For example, if you want your application to be available only to tablet devices, you can declare +the element in your manifest like this:</p> <pre> <manifest ... > - ... <supports-screens android:smallScreens="false" android:normalScreens="false" android:largeScreens="true" - android:xlargeScreens="true" /> + android:xlargeScreens="true" + android:requiresSmallestWidthDp="600" /> + ... <application ... > ... - <application> + </application> </manifest> </pre> -<p>External services such as Android Market read this manifest element and use it to ensure that -your application is available only to devices with either a large or an extra large screen.</p> +<p>This describes your app's screen-size support in two different ways:</p> + +<ul> + <li>It declares that the app does <em>not</em> support the screen sizes "small" and +"normal", which are traditionally not tablets.</li> + <li>It declares that the app requires a screen size with a minimum usable area that is at least +600dp wide.</li> +</ul> + +<p>The first technique is for devices that are running Android 3.1 or older, because those devices +declare their size based on generalized screen sizes. The <a +href="{@docRoot}guide/topics/manifest/supports-screens-element.html#requiresSmallest">{@code +requiresSmallestWidthDp}</a> attribute is for devices running Android 3.2 and newer, which includes +the capability for apps to specify size requirements based on a minimum number of +density-independent pixels available. In this example, the app declares a minimum width requirement +of 600dp, which generally implies a 7"-or-greater screen. </p> + +<p>Your size choice might be different, of course, based on how well your design works on different +screen sizes; for example, if your design works well only on screens that are 9" or larger, you +might require a minimum width of 720dp.</p> + +<p>The catch is that you must compile your application against Android 3.2 or higher in order to use +the <code>requiresSmallestWidthDp</code> attribute. Older versions don't understand this attribute +and will raise a compile-time error. The safest thing to do is develop your app against the platform +that matches the API level you've set for <a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">minSdkVersion</a +>. When you're making final preparations to build your release candidate, change the build target to +Android 3.2 and add the <code>requiresSmallestWidthDp</code> attribute. Android versions older than +3.2 simply ignore that XML attribute, so there's no risk of a runtime failure.</p> + +<p>For more information about why the "smallest width" screen size is +important for supporting different screen sizes, read <a +href="http://android-developers.blogspot.com/2011/07/new-tools-for-managing-screen-sizes.html">New +Tools for Managing Screen Sizes</a>.</p> <p class="caution"><strong>Caution:</strong> If you use the <a href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code @@ -151,7 +181,7 @@ information). If you want to prevent your application from being downloaded on larger screens, use <a href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">{@code <compatible-screens>}</a>, as discussed in the previous section about <a -href="#FilteringHandsetApps">Filtering a Handset Application from Tablets</a>.</p> +href="#FilteringHandsetApps">Declaring an App is Only for Handsets</a>.</p> <p>Remember, you should strive to make your application available to as many devices as possible by applying all necessary techniques for <a diff --git a/docs/html/guide/practices/screens_support.jd b/docs/html/guide/practices/screens_support.jd index 0c3c7d3..fb121bd 100644 --- a/docs/html/guide/practices/screens_support.jd +++ b/docs/html/guide/practices/screens_support.jd @@ -50,6 +50,9 @@ Resolutions</a></li> <h2>See also</h2> <ol> <li><a +href="http://android-developers.blogspot.com/2011/09/thinking-like-web-designer.html">Thinking +Like a Web Designer</a></li> + <li><a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources"> Providing Alternative Resources</a></li> <li><a href="{@docRoot}guide/practices/ui_guidelines/icon_design.html">Icon Design diff --git a/docs/html/guide/practices/tablets-and-handsets.jd b/docs/html/guide/practices/tablets-and-handsets.jd new file mode 100644 index 0000000..7bc1ad7 --- /dev/null +++ b/docs/html/guide/practices/tablets-and-handsets.jd @@ -0,0 +1,491 @@ +page.title=Supporting Tablets and Handsets + +@jd:body + +<div id="qv-wrapper"> +<ol id="qv"> + +<h2>In this document</h2> +<ol> + <li><a href="#Guidelines">Basic Guidelines</a></li> + <li><a href="#Fragments">Creating Single-pane and Multi-pane Layouts</a></li> + <li><a href="#ActionBar">Using the Action Bar</a> + <ol> + <li><a href="#SplitActionBar">Using split action bar</a></li> + <li><a href="#NavigatingUp">Using "up" navigation</a></li> + </ol> + </li> + <li><a href="#Tips">Other Design Tips</a></li> +</ol> + +<h2>Related samples</h2> +<ol> + <li><a href="{@docRoot}resources/samples/HoneycombGallery/index.html">Honeycomb +Gallery</a></li> +</ol> + +<h2>See also</h2> +<ol> + <li><a href="{@docRoot}guide/topics/fundamentals/fragments.html">Fragments</a></li> + <li><a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a></li> + <li><a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a></li> +</ol> + + + +</div> +</div> + + + +<p>The Android platform runs on a variety of screen sizes and the system gracefully resizes your +application's UI to fit each one. Typically, all you need to do is design your UI to be flexible and +optimize some elements for different sizes by providing <a +href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">alternative +resources</a> (such as alternative layouts that reposition some views or alternative +dimension values for views). However, sometimes you might want to go a step further to +optimize the overall user experience for different screen sizes. For example, tablets offer +more space in which your application can present multiple sets of information at once, while a +handset device usually requires that you split those sets apart and display them separately. So +even though a UI designed for handsets will properly resize to fit a tablet, it does not fully +leverage the potential of the tablet's screen to enhance the user experience.</p> + +<p>With Android 3.0 (API level 11), Android introduced a new set of framework APIs that allow you + to more effectively design activities that take advantage of large screens: the {@link +android.app.Fragment} APIs. Fragments allow you to separate distinct behavioral components of your +UI into separate parts, which you can then combine to create multi-pane layouts when running on a +tablet or place in separate activities when running on a handset. Android 3.0 also introduced +{@link android.app.ActionBar}, which provides a dedicated UI at the top of the screen to identify +the app and provide user actions and navigation.</p> + +<p>This document provides guidance that can help you create an application that offers a unique and +optimized user experience on both handsets and tablets, using fragments and the action bar.</p> + +<p>Before you continue with this guide, it's important that you first read the +guide to <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple +Screens</a>. That document describes the fundamental design principles for developing a UI that +supports different screen sizes and densities with flexible layouts and alternative bitmaps, +respectively.</p> + + + + +<h2 id="Guidelines">Basic Guidelines</h2> + +<p>Here are a few guidelines that will help you create an app that provides an optimized user +experience on both tablets and handsets:</p> + +<ul> + <li><strong>Build your activity designs based on fragments</strong> that you can reuse in +different combinations—in multi-pane layouts on tablets and single-pane layouts on handsets. + +<p>A {@link android.app.Fragment} represents a behavior or a portion of user interface in an +activity. You can think of a fragment as a modular section of an activity (a "fragment" of an +activity), which has its own lifecycle and which you can add or remove while the activity is +running.</p> + +<p>If you haven't used fragments yet, start by reading the <a +href="{@docRoot}guide/topics/fundamentals/fragments.html">Fragments</a> developer guide.</p> +</li> + + + <li><strong>Use the action bar</strong>, but follow best practices and ensure your design +is flexible enough for the system to adjust the action bar layout based on the screen size. + +<p>The {@link android.app.ActionBar} is a UI component for activities that replaces the traditional +title bar at the top of the screen. By default, the action bar includes the application logo on the +left side, followed by the activity title, and access to items from the options menu on the right +side.</p> + +<p>You can enable items from the options menu to appear directly in the action bar as "action +items". You can also add navigation features to the action bar, such as tabs or a drop-down list, +and use the application icon to supplement the system's BACK behavior with the option to navigate to +your application's "home" activity or "up" the application's structural hierarchy.</p> + +<p>This guide provides some tips for using the action bar in ways that support both tablets and +handsets. For a detailed discussion of the action bar APIs, read the <a +href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> developer guide.</p> +</li> + + + <li><strong>Implement flexible layouts</strong>, as discussed in the +<a href="{@docRoot}guide/practices/screens_support.html#screen-independence">Best Practices</a> for +supporting multiple screens and the blog post, <a +href="http://android-developers.blogspot.com/2011/09/thinking-like-web-designer.html">Thinking +Like a Web Designer</a>. + <p>A flexible layout design allows your application to adapt to variations in screen +sizes. Not all tablets are the same size, nor are all handsets the same size. While you might +provide different fragment combinations for "tablets" and "handsets", it's still necessary that +each design be flexible to resize to variations in size and aspect ratio.</p> +</li> +</ul> + +<p>The following sections discuss the first two recommendations in more detail. For more +information about creating flexible layouts, refer to the links provided above.</p> + + +<p class="note"><strong>Note:</strong> Aside from one feature in the action bar, all the +APIs needed to accomplish the recommendations in this document are available in Android +3.0. Additionally, you can even implement the fragment design patterns and remain +backward-compatible with Android 1.6, by using the support library—discussed in the side +bar below.</p> + + + +<h2 id="Fragments">Creating Single-pane and Multi-pane Layouts</h2> + + +<div class="sidebox-wrapper"> +<div class="sidebox"> + <h3>Remaining backward-compatible</h3> +<p>If you want to use fragments in your application <em>and</em> remain compatible with +versions of Android older than 3.0, you can do so by using the Android <a +href="{@docRoot}sdk/compatibility-library.html">Support Library</a> (downloadable from the +SDK Manager).</p> +<p>The support library includes APIs for <a +href="{@docRoot}guide/topics/fundamentals/fragments.html">fragments</a>, <a +href="{@docRoot}guide/topics/fundamentals/loaders.html">loaders</a>, and other APIs added in newer +versions of Android. By simply adding this library to your Android project, you can use +backward-compatible versions of these APIs in your application and remain compatible with Android +1.6 (your <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code +android:minSdkVersion}</a> value can be as low as {@code "4"}). For information about how to get the +library and start using it, see the <a href="{@docRoot}sdk/compatibility-library.html">Support +Library</a> document.</p> + +<p>The support library <em>does not</em> provide APIs for the action bar, but you can use +code from the sample app, <a +href="{@docRoot}resources/samples/ActionBarCompat/index.html">Action Bar Compatibility</a>, to +create an action bar that supports all devices.</p> +</div> +</div> + + + + +<p>The most effective way to create a distinct user experience for tablets and handsets is to create +layouts with different combinations of fragments, such that you can design "multi-pane" layouts for +tablets and "single-pane" layouts for handsets. For example, a news application on a tablet might +show a list of articles on the left side and a full article on the right side—selecting an +article on the left updates the article view on the right. On a handset, however, these two +components should appear on separate screens—selecting an article from a list changes the +entire screen to show that article. There are two techniques to accomplish this design with +fragments:</p> + + +<ul> + <li><em>Multiple fragments, one activity</em>: Use one activity regardless of the device size, +but decide at runtime whether to combine fragments in the layout (to create a multiple-pane design) +or swap fragments (to create a single-pane design). Or...</li> + + <li><em>Multiple fragments, multiple activities</em>: On a tablet, place multiple fragments in +one activity; on a handset, use separate activities to host each fragment. For example, +when the tablet design uses two fragments in an activity, use the same activity for handsets, but +supply an alternative layout that includes just the first fragment. When running on a handset and +you need to switch fragments (such as when the user selects an item), start another activity that +hosts the second fragment.</li> +</ul> + +<p>The approach you choose depends on your design and personal preferences. The first option +(one activity; swapping fragments) requires that you determine the screen size at runtime +and dynamically add each fragment as appropriate—rather than declare the fragments +in your activity's XML layout—because you <em>cannot</em> remove a fragment from an activity +if it's been declared in the XML layout. When using the first technique, you might also need to +update the action bar each time the fragments change, depending on what actions or navigation modes +are available for each fragment. In some cases, these factors might not affect your design, so +using one activity and swapping fragments might work well (especially if your tablet design requires +that you add fragments dynamically anyway). Other times, however, dynamically swapping +fragments for your handset design can make your code more complicated, because you must manage all +the fragment combinations in the activity's code (rather than use alternative layout resources to +define fragment combinations) and manage the back stack of fragments yourself (rather than +allow the normal activity stack to handle back-navigation).</p> + +<p>This guide focuses on the second option, in which you display each fragment in a separate +activity when on a smaller screen. Using this technique means that you can use alternative layout +files that define different fragment combinations for different screen sizes, keep fragment code +modular, simplify action bar management, and let the system handle all the back stack work on +handsets.</p> + +<p>Figure 1 illustrates how an application with two fragments might be arranged for +both handsets and tablets when using separate activities for the handset design:</p> + +<img src="{@docRoot}images/fundamentals/fragments.png" alt="" /> +<p class="img-caption"><strong>Figure 1.</strong> Different design patterns for tablets and +handsets when selecting an item to view its details.</p> + +<p>In the application shown in figure 1, Activity A is the "main activity" and uses different +layouts to display either one or two fragments at a time, depending on the size of the screen:</p> +<ul> + <li>On a tablet-sized screen, the Activity A layout contains both Fragment A and Fragment B.</li> + <li>On a handset-sized screen, the Activity A layout contains only Fragment A (the list +view). In order to show the details in Fragment B, Activity B must open.</li> +</ul> + +<p class="note"><strong>Note:</strong> Activity B is never used on a tablet. It is simply a +container to present Fragment B, so is only used on handset devices when the two fragments must +be displayed separately.</p> + +<p>Depending on the screen size, the system applies a different {@code main.xml} layout file:</p> + +<p><code>res/layout/main.xml</code> for handsets:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:layout_width="match_parent" + android:layout_height="match_parent"> + <!-- "Fragment A" --> + <fragment class="<b>com.example.android.TitlesFragment</b>" + android:id="@+id/list_frag" + android:layout_width="match_parent" + android:layout_height="match_parent"/> +</FrameLayout> +</pre> + +<p><code>res/layout-large/main.xml</code> for tablets:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:orientation="horizontal" + android:layout_width="match_parent" + android:layout_height="match_parent" + android:id="@+id/frags"> + <!-- "Fragment A" --> + <fragment class="<b>com.example.android.TitlesFragment</b>" + android:id="@+id/list_frag" + android:layout_width="@dimen/titles_size" + android:layout_height="match_parent"/> + <!-- "Fragment B" --> + <fragment class="<b>com.example.android.DetailsFragment</b>" + android:id="@+id/details_frag" + android:layout_width="match_parent" + android:layout_height="match_parent" /> +</LinearLayout> +</pre> + + +<div class="sidebox-wrapper"> +<div class="sidebox"> + <h3>Supporting sizes based on screen width</h3> + <p>Android 3.2 (API level 13) adds new APIs that provide more fine-grain control over what screen +sizes your app supports and what resources it uses, by declaring screen sizes based on the minimum +width your layouts require. For example, both a 5" and 7" device qualify as a "large" screen, so +your "large" layout resources are used on both devices. With API level 13, you can distinguish +between these two sizes based on the screen width, as measured in density-independent pixels.</p> + <p>For details, read the blog post about <a +href="http://android-developers.blogspot.com/2011/07/new-tools-for-managing-screen-sizes.html"> +New Tools for Managing Screen Sizes</a>.</p> +</div> +</div> + +<p class="note"><strong>Note:</strong> Although the above sample layout for tablets is based on +the "large" screen configuration qualifier, you should also use the new "minimum width" size +qualifiers in order to more precisely control the screen size at which the system applies your +handset or tablet layout. See the sidebar for more information.</p> + +<p>How the application responds when a user selects an item from the list depends on whether +Fragment B is available in the layout:</p> +<ul> + <li>If Fragment B is in the layout, Activity A notifies Fragment B to update itself.</li> + <li>If Fragment B is <em>not</em> in the layout, Activity A starts Activity B (which hosts +Fragment B).</li> +</ul> + + +<p>To implement this pattern for your application, it's important +that you develop your fragments to be highly compartmentalized. Specifically, you should follow two +guidelines:</p> + +<ul> + <li>Do not manipulate one fragment directly from another.</li> + <li>Keep all code that concerns content in a fragment inside that fragment, rather than putting it +in the host activity's code.</li> +</ul> + +<p>To avoid directly calling one fragment from another, <strong>define a callback interface in each +fragment</strong> class that it can use to deliver events to +its host activity, which implements the callback +interface. When the activity receives a callback due to an event (such as the user selecting a list +item), the activity responds appropriately based on the current fragment configuration.</p> + +<p>For example, Activity A from above can handle item selections depending on whether it's using +the tablet or handset layout like this:</p> + +<pre> +public class MainActivity extends Activity implements TitlesFragment.OnItemSelectedListener { + ... + + /** This is a callback that the list fragment (Fragment A) + calls when a list item is selected */ + public void onItemSelected(int position) { + DisplayFragment displayFrag = (DisplayFragment) getFragmentManager() + .findFragmentById(R.id.display_frag); + if (displayFrag == null) { + // DisplayFragment (Fragment B) is not in the layout (handset layout), + // so start DisplayActivity (Activity B) + // and pass it the info about the selected item + Intent intent = new Intent(this, DisplayActivity.class); + intent.putExtra("position", position); + startActivity(intent); + } else { + // DisplayFragment (Fragment B) is in the layout (tablet layout), + // so tell the fragment to update + displayFrag.updateContent(position); + } + } +} +</pre> + +<p>When <code>DisplayActivity</code> (Activity B) starts, it reads the data delivered by the +{@link android.content.Intent} and passes it to the <code>DisplayFragment</code> (Fragment B).</p> + +<p>If Fragment B needs to deliver a result back to Fragment A (because Activity B was started with +{@link android.app.Activity#startActivityForResult startActivityForResult()}), then the process +works similarly with a callback interface between Fragment B and Activity B. That is, Activity B +implements a different callback interface defined by Fragment B. When Activity B receives the +callback with a result from the fragment, it sets the result for the activity (with {@link +android.app.Activity#setResult setResult()}) and finishes itself. Activity A then receives the +result and delivers it to Fragment A.</p> + +<p>For a demonstration of this technique for creating different fragment combinations for +tablets and handsets, see the updated version of the <a +href="{@docRoot}resources/samples/HoneycombGallery/index.html">Honeycomb Gallery</a> +sample.</p> + + + + + + +<h2 id="ActionBar">Using the Action Bar</h2> + +<p>The <a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> is an important UI +component for Android apps on both tablets and handsets. To ensure that the action bar +behaves appropriately on all screen sizes, it's important that you use the {@link +android.app.ActionBar} APIs without adding complex customizations. By using the standard {@link +android.app.ActionBar} APIs to design your action bar, the Android system does all +the work to gracefully adapt the action bar for different screen sizes. Here are some important +tips to follow when creating your action bar:</p> + +<ul> + <li>When setting a menu item to be an action item, <strong>avoid using the {@code "always"} +value</strong>. In your <a +href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a>, use {@code "ifRoom"} +for the {@code android:showAsAction} attribute if you'd like the menu item to appear in the action +bar. However, you might need {@code "always"} when an action view does not provide an alternative +action for the overflow menu (that is, it must appear as an action view) or when a menu item added +by a fragment is low in the menu order and it must jump into the action bar at all times. However, +you should not use {@code "always"} more than once or twice. In almost all other cases, use {@code +"ifRoom"} as the value for {@code "android:showAsAction"} when you want the item to appear as an +action item. Forcing too many action items into the action bar can create a cluttered UI and +action items may overlap with other action bar elements such as the title or navigation items.</li> + + <li>When adding action items to the action bar with a text title, also <strong>provide an +icon</strong>, when appropriate, and declare <code>showAsAction="ifRoom|withText"</code>. +This way, if there's not enough room for the title, but there is enough room for the icon, then only +the icon may be used.</li> + + + <li>Always <strong>provide a title</strong> for your action items, even if you don't enable {@code +"withText"}, because users can view the title as a "tool-tip" by performing a +"long click" on the item—the title text appears momentarily in a toast message. Providing +a title is also critical for accessibility, because screen readers read aloud the item title +even when not visible.</li> + + + <li><strong>Avoid using custom navigation modes when possible</strong>. Use the built-in tab +and drop-down navigation modes when possible—they're designed so the system can adapt their +presentation to different screen sizes. For example, when the width is too narrow for both tabs and +other action items (such as a handset in portrait orientation), the tabs appear below the action bar +(this is known as the "stacked action bar"). If you must build a custom navigation mode or other +custom views in the action bar, thoroughly test them on smaller screens and make any +necessary adjustments to support a narrow action bar.</li> +</ul> + +<p>For example, the mock-ups below demonstrate how the system may adapt an action bar based +on the available screen space. On the handset, only two action items fit, so the remaining menu +items appear in the overflow menu (because {@code android:showAsAction} was set to {@code "ifRoom"}) +and the tabs appear in a separate row (the stacked action bar). On the tablet, more action items can +fit in the action bar and so do the tabs.</p> + +<img src="{@docRoot}images/practices/actionbar-phone-tablet.png" alt=""/> +<p class="img-caption"><strong>Figure 2.</strong> Mock-up showing how the system re-configures +action bar components based on the available screen space.</p> + + +<h3 id="SplitActionBar">Using split action bar</h3> + +<p>When your application is running on Android 4.0 (API level 14) and +higher, there's an extra mode available for the action bar called "split action bar." When +you enable split action bar, a separate bar appears at the bottom of the screen to +display all action items when the activity is running on a narrow screen (such as a portrait +handset). Splitting the action bar ensures that a reasonable amount of space is available to +display action items on a narrow screen and also leave room for navigation and title elements +at the top.</p> + +<p>To enable split action bar, simply add {@code uiOptions="splitActionBarWhenNarrow"} to your +<a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> or +<a href="{@docRoot}guide/topics/manifest/application-element.html">{@code <application>}</a> +manifest element.</p> + + +<img src="{@docRoot}images/practices/actionbar-phone-splitaction.png" alt=""/> +<p class="img-caption"><strong>Figure 3.</strong> Split action bar with navigation tabs on the left; +with the app icon and title disabled on the right.</p> + + +<p>If you'd like to hide the main action bar at the top, because you're using the built-in +navigation tabs along with the split action bar, call {@link +android.app.ActionBar#setDisplayShowHomeEnabled setDisplayShowHomeEnabled(false)} to disable the +application icon in the action bar. In this case, there's now nothing left in the main action bar, +so it disappears and all that’s left are the navigation tabs at the top and the action items at the +bottom, as shown by the second device in figure 3.</p> + +<p class="note"><strong>Note:</strong> Although the {@code uiOptions} attribute was added in Android +4.0 (API level 14), you can safely include it in your application even if your <a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> is set to +a value lower than {@code "14"} to remain compatible with older versions of Android. When running on +older versions, the system simply ignores the attribute because it doesn't understand it. The only +condition to adding it to your manifest is that you must compile your application against a platform +version that supports API level 14 or higher. Just be sure that you don't openly use other APIs in +your application code that aren't supported by the version declared by your <a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> +attribute.</p> + + +<h3 id="NavigatingUp">Using "up" navigation</h3> + +<p>As discussed in the <a href="{@docRoot}guide/topics/ui/actionbar.html#Home">Action Bar</a> +developer guide, you can use the application icon in the action bar to facilitate user navigation +when appropriate—either as a method to get back to the "home" activity (similar to clicking +the logo on a web site) or as a way to navigate up the application's structural hierarchy. Although +it might seem similar to the standard BACK navigation in some cases, the up navigation option +provides a more predictable navigation method for situations in which the user may have entered +from an external location, such as a notification, app widget, or a different application.</p> + +<p>When using fragments in different combinations for different devices, it's important to give +extra consideration to how your up navigation behaves in each configuration. For example, when on a +handset and your application shows just one fragment at a time, it might be appropriate to enable up +navigation to go up to the parent screen, whereas it's not necessary when showing the same +fragment in a multi-pane configuration.</p> + +<p>For more information about enabling up navigation, see the <a +href="{@docRoot}guide/topics/ui/actionbar.html#Home">Action Bar</a> developer guide.</p> + + + + +<h2 id="Tips">Other Design Tips</h2> + +<ul> + <li>When working with a {@link android.widget.ListView}, consider how you might provide more or less +information in each list item based on the available space. That is, you can create alternative +layouts to be used by the items in your list adapter such that a large screen might display more +detail for each item.</li> + <li>Create <a href="{@docRoot}guide/topics/resources/more-resources.html ">alternative resource +files</a> for values such as integers, dimensions, and even booleans. Using size qualifiers for +these resources, you can easily apply different layout sizes, font sizes, or enable/disable features +based on the current screen size.</li> +</ul> + + |