| 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> |
| <ol> |
| <li><a href="#Setup">Setting Up Your SDK with Android 3.0</a></li> |
| <li><a href="#Optimizing">Optimizing Your App for Tablets</a></li> |
| <li><a href="#Upgrading">Upgrading or Developing a New App for Tablets</a></li> |
| <li><a href="#ManagingAppDist">Managing App Distribution Based on Screen Configuration</a> |
| <ol> |
| <li><a href="#FilteringTabletApps">Filtering a tablet app from mobile devices</a></li> |
| <li><a href="#FilteringMobileApps">Filtering a mobile device app from tablets</a></li> |
| </ol> |
| </li> |
| <li><a href="#Issues">Other Issues</a> |
| <ol> |
| <li><a href="#Landscape">Adding support for landscape screens</a></li> |
| <li><a href="#Telephony">Using telephony or other variable features</a></li> |
| </ol> |
| </li> |
| </ol> |
| |
| <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> |
| </ol> |
| |
| </div> |
| </div> |
| |
| <p>Android 3.0 introduces several features that allow |
| you to enhance your user's experience on tablets and similar devices. Any application you've already |
| published is compatible with devices running Android 3.0, by default, because Android applications |
| are forward-compatible. However, new tablet devices running Android 3.0 are now available to the |
| public and provide users a new Android experience on a larger screen, so you should make sure |
| your application looks and works great on the new platform and new device form-factors.</p> |
| |
| <p>This document shows how you can optimize your existing application for Android 3.0 and |
| maintain compatibility with older versions or upgrade your application completely with new APIs.</p> |
| |
| |
| <p><b>To get started:</b></p> |
| |
| <ol> |
| <li><a href="#Setup">Set up your SDK with Android 3.0</a>. |
| <p>Install the Android 3.0 platform, new tools, and set up a new AVD.</p></li> |
| <li>Choose to either optimize or upgrade: |
| <ol type="a"> |
| <li><a href="#Optimizing">Optimize your app for tablets and similar devices</a>. |
| <p>Read this section if you have an existing application and want to |
| maintain compatibility with older versions of Android. All you need to do is update your |
| manifest file to declare support for Android 3.0, test your application on the new platform, and |
| add extra resources to support extra large screens, as appropriate.</p> |
| </li> |
| <li><a href="#Upgrading">Upgrade or develop a new app for tablets and similar devices</a>. |
| <p>Read this section if you want to upgrade your application to use APIs introduced in |
| Android 3.0 or create a new application targeted to tablets and similar devices. Compared to |
| upgrading to previous versions of Android, there's nothing different about upgrading to Android 3.0. |
| This section introduces some of the key features and APIs you should use to make an |
| application that's fully enhanced for tablets.</p></li> |
| </ol> |
| </li> |
| <li>Consider whether you need to <a href="#ManagingAppDist">manage the distribution of your |
| application based on screen configuration</a>.</li> |
| <li>Then review some <a href="#Issue">other issues</a> you might encounter when developing |
| for tablets and similar devices.</li> |
| </ol> |
| |
| |
| <h2 id="Setup">Set Up Your SDK with Android 3.0</h2> |
| |
| <p>To start testing and developing your application on Android 3.0, set up your existing Android |
| SDK with the new platform:</p> |
| |
| <p>(If you don't have an existing Android SDK, <a href="{@docRoot}sdk/index.html">download the |
| SDK starter package now</a>.)</p> |
| |
| <ol> |
| <li><a href="{@docRoot}sdk/adding-components.html#launching">Launch the Android SDK and AVD |
| Manager</a> and install the following: |
| <ul> |
| <li>SDK Platform Android 3.0</li> |
| <li>Android SDK Tools, revision 10</li> |
| <li>Android SDK Platform-tools, revision 3</li> |
| <li>Documentation for Android SDK, API 11</li> |
| <li>Samples for SDK API 11</li> |
| </ul> |
| </li> |
| <li><a href="{@docRoot}guide/developing/other-ide.html#AVD">Create an AVD</a> for a tablet-type |
| device: |
| <p>Set the target to "Android 3.0" and the skin to "WXGA" (the default skin).</p></li> |
| </ol> |
| |
| <p>The best way to test your application on Android 3.0 is to use real hardware running Android 3.0, |
| such as the <a href="http://www.motorola.com/staticfiles/Consumers/XOOM/index.html">Motorola |
| Xoom</a>. Of course, you can also use the Android emulator on your development machine, but because |
| the Android emulator must simulate the ARM instruction set on your computer and the WXGA screen is |
| significantly larger than a typical virtual device, emulator performance is much slower than a real |
| device.</p> |
| |
| <h3>About emulator performance</h3> |
| |
| <p>Initializing the emulator can be slow and can take several minutes, depending on |
| your hardware. When the emulator is booting, there is limited user feedback, so please be patient |
| and wait until you see the home screen (or lock screen) appear. </p> |
| |
| <p>However, you don't need to boot the emulator each time you rebuild your |
| application—typically you only need to boot at the start of a session and keep it running. |
| Also see the tip below for information about using a snapshot to drastically reduce startup time |
| after the first initialization. </p> |
| |
| <p>General performance in the emulator is also slow. We're working hard to resolve the performance |
| issues and it will improve in future tools releases. If you don't yet have a real device running |
| Android 3.0, the emulator is still best way to evaluate your application's appearance and |
| functionality on Android 3.0.</p> |
| |
| <p class="note"><strong>Tip:</strong> To improve the startup time for the emulator, enable snapshots |
| for the AVD when you create it with the SDK and AVD Manager (there's a checkbox in the AVD creator |
| to <strong>Enable</strong> snapshots). Then, start the AVD from the AVD manager and check <b>Launch |
| from snapshot</b> and <b>Save to snapshot</b>. This way, when you close the emulator, a snapshot of |
| the AVD state is saved and used to quickly relaunch the AVD next time. However, when you choose to |
| save a snapshot, the emulator will be slow to close, so you might want to disable <b>Save to |
| snapshot</b> after you've acquired an initial snapshot (after you close the AVD for the first |
| time).</p> |
| |
| |
| |
| <h2 id="Optimizing">Optimizing Your App for Tablets</h2> |
| |
| <p>If you've already developed an application for an earlier version of Android, there are a few |
| things you can do to optimize it for a tablet-style experience on Android 3.0 without changing the |
| minimum version required (you don't need to change your manifest's <a |
| href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code |
| android:minSdkVersion}</a>).</p> |
| |
| <p class="note"><strong>Note:</strong> All Android applications are forward-compatible, so |
| there's nothing you <em>have to</em> do—if your application is a good citizen of the Android |
| APIs, your app should work fine on devices running Android 3.0. However, in order to provide users |
| a better experience when using your app on an Android 3.0 tablet or similar-size device, you |
| should update your application to inherit the new system theme and provide some optimizations for |
| larger screens.</p> |
| |
| <p>Here are a few things you can do to optimize your application for devices running Android |
| 3.0:</p> |
| |
| <ol> |
| <li><b>Test your current application on Android 3.0</b> |
| <ol> |
| <li>Build your application as-is and install it on your Android 3.0 AVD (created above during |
| <a href="#Setup">setup</a>).</li> |
| <li>Perform your usual tests to be sure everything works and looks as expected.</li> |
| </ol> |
| </li> |
| |
| <li><b>Apply the new "holographic" theme to your application</b> |
| <ol> |
| <li>Open your manifest file and update the <a |
| href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code <uses-sdk>}</a> element to |
| set <a |
| href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code |
| android:targetSdkVersion}</a> to {@code "11"}. For example: |
| <pre> |
| <manifest ... > |
| <uses-sdk android:minSdkVersion="4" |
| android:targetSdkVersion="11" /> |
| <application ... > |
| ... |
| <application> |
| </manifest> |
| </pre> |
| <p>By targeting the Android 3.0 platform, the system automatically applies the holographic theme |
| to each activity when your application runs on an Android 3.0 device. The holographic theme |
| provides a new design for widgets, such as buttons and text boxes, and new styles for other |
| visual elements. This is the standard theme for applications built for Android 3.0, so your |
| application will look and feel consistent with the system and other applications when it is |
| enabled.</p> |
| <p>Additionally, when an activity uses the holographic theme, the system enables the <a |
| href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> for the activity and removes the |
| Options Menu button in the system bar. The Action Bar |
| replaces the traditional title bar at the top of the activity window and provides the user access to |
| the activity's Options Menu.</p> |
| </li> |
| <li>Build your application against the same version of the Android platform you have been |
| using previously (such as the version declared in your <a |
| href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a>), |
| but install it on the Android 3.0 AVD. (You should not build against Android 3.0 unless you are |
| using new APIs.) Repeat your tests to be sure that your user interface works well with the |
| holographic theme. |
| <p class="note"><strong>Note:</strong> If you have applied other themes directly to your |
| activities, they will override the inherited holographic theme. To resolve this, you can use |
| the <a href="{@docRoot}guide/topics/resources/providing-resources.html#VersionQualifier">platform |
| version qualifier</a> to provide an alternative theme for Android 3.0 devices that's based on the |
| holographic theme. For more information, read how to <a |
| href="{@docRoot}guide/topics/ui/themes.html#SelectATheme">select a theme based on platform |
| version</a>.</p> |
| </ol> |
| </li> |
| |
| <li><b>Supply alternative layout resources for xlarge screens</b> |
| <p>By providing <a |
| href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">alternative |
| resources</a> when running on extra large screens (using the <code>xlarge</code> resource |
| qualifier), you can improve the user experience of your application on tablet-type devices without |
| using new APIs.</p> |
| <p>For example, here are some things to consider when creating a new layout for extra large |
| screens:</p> |
| <ul> |
| <li>Landscape layout: The "normal" orientation for tablet-type devices is usually landscape |
| (wide), so you should be sure that your activities offer a layout that's optimized for a wide |
| viewing area. <p>You can specify landscape resources with the <code>land</code> resource |
| qualifier, but if you want alternative resources for an extra large landscape screen, you |
| should use both the <code>xlarge</code> and <code>land</code> qualifiers. For example, {@code |
| res/layout-xlarge-land/}. The order of the qualifier names is important; see <a |
| href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources"> |
| Providing Alternative Resources</a> for more information.</p></li> |
| <li>Button position and size: Consider whether the position and size of the most common |
| buttons in your UI make them easily accessible while holding a tablet with two hands. In some |
| cases, you might need to resize buttons, especially if they use {@code "wrap_content"} |
| as the width value. To enlarge the buttons, if necessary, you should either: add |
| extra padding to the button; specify dimension values with {@code dp} units; or use {@code |
| android:layout_weight} when the button is in a <a |
| href="{@docRoot}guide/topics/ui/layout-objects.html#linearlayout">linear layout</a>. Use your |
| best judgment of proportions for each screen size—you don't want the buttons to be too big, |
| either.</li> |
| <li>Font sizes: Be sure your application uses {@code sp} units when setting font |
| sizes. This alone should ensure a readable experience on tablet-style devices, because it is a |
| scale-independent pixel unit, which will resize as appropriate for the current screen configuration. |
| In some cases, however, you still might want to consider larger font sizes for <code>xlarge</code> |
| configurations.</li> |
| </ul> |
| <p>In general, always be sure that your application follows the <a |
| href="{@docRoot}guide/practices/screens_support.html#screen-independence">Best Practices |
| for Screen Independence</a>.</p> |
| </li> |
| </ol> |
| |
| |
| |
| |
| <h2 id="Upgrading">Upgrading or Developing a New App for Tablets</h2> |
| |
| <div class="sidebox-wrapper"> |
| <div class="sidebox"> |
| <h3>Use the Compatibility Library to remain backward-compatible</h3> |
| <p>It is possible for you to upgrade your application with some new |
| APIs <em>and</em> remain compatible with older versions of Android. Usually, this requires that you |
| use techniques such as reflection to check for the availability of certain APIs at runtime. However, |
| to help you add features from Android 3.0 without requiring you to change your <a |
| href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a> |
| or build target, we're providing a static library called the <a |
| href="{@docRoot}sdk/compatibility-library.html">Compatibility Library</a> |
| (downloadable from the AVD and SDK Manager).</p> |
| <p>This 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 some updated classes. By |
| simply adding this library to your Android project, you can use these APIs in your application and |
| remain compatible with Android 1.6. For information about how to get the library and start |
| using it in your application, see the <a |
| href="{@docRoot}sdk/compatibility-library.html">Compatibility Library</a> document.</p> |
| </div> |
| </div> |
| |
| |
| <p>If you want to develop an application that's fully enhanced for tablet-type devices running |
| Android 3.0, then you need to use new APIs in Android 3.0. This section introduces some of |
| the new features you should use.</p> |
| |
| |
| <h3>Declare the minimum system version</h3> |
| |
| <p>The first thing to do when you upgrade or create a project for Android 3.0 is set your manifest's |
| <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code |
| android:minSdkVersion}</a> to {@code "11"}. This declares that your application uses APIs available |
| in Android 3.0 and greater, so it should not be available to devices running an older version of |
| Android. For example:</p> |
| |
| <pre> |
| <manifest ... > |
| <uses-sdk android:minSdkVersion="11" /> |
| <application ... > |
| ... |
| <application> |
| </manifest> |
| </pre> |
| |
| <p>Not only is this necessary in order to declare the minimum API level your application requires, |
| but it enables the new holographic theme to each of your activities. The holographic theme is the |
| standard theme for the Android 3.0 system and all applications designed for it. It includes new |
| designs for the system widgets and overall appearance.</p> |
| |
| <p>Additionally, the holographic theme enables the Action Bar for each activity.</p> |
| |
| |
| <h3>Use the Action Bar</h3> |
| |
| <p>The Action Bar is a widget 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 in a drop-down list on the right |
| side.</p> |
| |
| <p>You can enable items from the Options Menu to appear directly in the Action Bar as |
| "action items" by adding {@code showAsAction="ifRoom"} to specific menu items in your <a |
| href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a>. You can also add |
| navigation features to the Action Bar, such as tabs, and use the application icon to navigate to |
| your application's "home" activity or to navigate "up" the application's activity hierarchy.</p> |
| |
| <p>For more information, read <a href="{@docRoot}guide/topics/ui/actionbar.html">Using the |
| Action Bar</a>.</p> |
| |
| |
| |
| <h3>Divide your activities into fragments</h3> |
| |
| <p>A 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, which has its own lifecycle, receives its own input |
| events, and which you can add or remove while the activity is running. Fragments are an optional |
| component for your activities that allow you to build a multi-pane UI and reuse them in multiple |
| activities. If you're building an application for tablets, we recommend that you use fragments to |
| create activities that offer a more dynamic and flexible user interface.</p> |
| |
| <p>For example, a news application can use one fragment to show a list of articles on the left and |
| another fragment to display an article on the right—both fragments appear in one activity, |
| side by side, and each fragment has its own set of lifecycle callback methods and handles its own |
| input events. Thus, instead of using one activity to select an article and another activity to |
| read the article, the user can select an article and read it all within the same activity.</p> |
| |
| <p>For more information, read the <a |
| href="{@docRoot}guide/topics/fundamentals/fragments.html">Fragments</a> document.</p> |
| |
| |
| <h3>Use new animation APIs for transitions</h3> |
| |
| <p>An all-new animation framework allows you to animate arbitrary properties of any object |
| (such as a View, Drawable, Fragment, or anything else). You can define several animation aspects |
| (such as duration, repeat, interpolation, and more) for an object's int, float, and hexadecimal |
| color values, by default. That is, when an object has a property field for one of these types, you |
| can change its value over time to affect an animation.</p> |
| |
| <p>The {@link android.view.View} class also provides new APIs that leverage the new animation |
| framework, allowing you to easily apply 2D and 3D transformations to views in your activity layout. |
| New transformations are made possible with a set of object properties that define the view's layout |
| position, orientation, transparency and more.</p> |
| |
| <p>For more information, read the <a |
| href="{@docRoot}guide/topics/graphics/animation.html">Property Animation</a> document.</p> |
| |
| |
| <h3>Enable hardware acceleration</h3> |
| |
| <p>Android 3.0 adds a hardware-accelerated OpenGL renderer that gives a performance boost to most 2D |
| graphics operations. You can enable hardware-accelerated rendering in your application by setting |
| {@code android:hardwareAccelerated="true"} in your manifest's <a |
| href="{@docRoot}guide/topics/manifest/application-element.html">{@code <application>}</a> |
| element or for individual <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code |
| <activity>}</a> elements. Hardware acceleration results in smoother animations, smoother |
| scrolling, and overall better performance and response to user interaction. When enabled, be sure |
| that you thoroughly test your application on a device that supports hardware acceleration.</p> |
| |
| |
| <h3>Enhance your app widgets</h3> |
| |
| <p>App widgets allow users to access information from your application directly from the Home |
| screen and interact with ongoing services (such as preview their email and control music playback). |
| Android 3.0 enhances these capabilities by enabling collections, created with widgets such as |
| {@link android.widget.ListView}, {@link android.widget.GridView}, and the new {@link |
| android.widget.StackView}. These widgets allow you to create more interactive app |
| widgets, such as one with a scrolling list, and can automatically update their data through a {@link |
| android.widget.RemoteViewsService}.</p> |
| |
| <p>Additionally, you should create a preview image of your app widget using the Widget Preview |
| application (pre-installed in an Android 3.0 AVD) and reference it with the {@link |
| android.appwidget.AppWidgetProviderInfo#previewImage android:previewImage} attribute, so that users |
| can see what the app widget looks like before adding it to their Home screen.</p> |
| |
| |
| <h3>Add other new features</h3> |
| |
| <p>Android 3.0 introduces many more APIs that you might find valuable for your |
| application, such as drag and drop APIs, new Bluetooth APIs, a system-wide clipboard framework, a |
| new graphics engine called Renderscript, and more.</p> |
| |
| <p>To learn more about the APIs mentioned above and more, see the <a |
| href="{@docRoot}sdk/android-3.0.html">Android 3.0 Platform</a> document.</p> |
| |
| |
| <h3>Look at some samples</h3> |
| |
| <p>Many of the new features and APIs that are described above and in the <a |
| href="{@docRoot}sdk/android-3.0.html#api">Android 3.0 Platform</a> document also have accompanying |
| samples that allow you to preview the effects and can help you understand how to use them. To get |
| the samples, download them from the SDK repository <a href="{@docRoot}sdk/adding-components.html" |
| >using the Android SDK and AVD Manager</a>. After downloading the samples ("Samples for SDK API |
| 11"), you can find them in <code><sdk_root>/samples/android-11/</code>. The following list |
| provides links to the browsable source code for some of the samples:</p> |
| |
| <ul> |
| <li><a href="{@docRoot}resources/samples/HoneycombGallery/index.html">Honeycomb Gallery</a>: |
| Demonstrates many new APIs in Android 3.0, including fragments, the action bar, drag and drop, and |
| animations.</li> |
| <li><a |
| href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/index.html#Fragment"> |
| Fragments</a>: Various samples that demonstrate fragment layouts, back stack, restoring state, and |
| more.</li> |
| <li><a |
| href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/ActionBarMechanics.html" |
| >Action Bar</a>: Samples that demonstrate various Action Bar features, such as tabs, logos, and |
| action items.</li> |
| <li><a |
| href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/content/ClipboardSample.html" |
| >Clipboard</a>: An example of how to use the clipboard for copy and paste operations.</li> |
| <li><a |
| href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/DragAndDropDemo.html"> |
| Drag and Drop</a>: An example of how to perform drag and drop with new View events.</li> |
| <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/List15.html"> |
| Multi-choice List</a>: An example of how to provide multiple-choice selection for ListView and |
| GridView.</li> |
| <li><a |
| href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LoaderThrottle.html"> |
| Content Loaders</a>: An example using new Loader APIs to asynchronously load data.</li> |
| <li><a |
| href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/animation/index.html"> |
| Property Animation</a>: Several samples using the new animation APIs to animate object |
| properties.</li> |
| <li><a |
| href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/SearchViewActionBar.html"> |
| Search View Widget</a>: Example using the new search widget in the Action Bar (as an |
| "action view").</li> |
| <li><a |
| href="{@docRoot}resources/samples/RenderScript/index.html">Renderscript</a>: Contains several |
| different applications that demonstrate using renderscript APIs for computations and 3D |
| graphics.</li> |
| </ul> |
| |
| |
| |
| <h2 id="ManagingAppDist">Managing App Distribution Based on Screen Configuration</h2> |
| |
| <p>If your manifest file has either <a |
| href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a> |
| or <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code |
| android:targetSdkVersion}</a> set to {@code "4"} or higher, then the Android system will scale your |
| application's layout and assets to fit the current device screen, whether the device screen is |
| smaller or larger than the one for which you originally designed your application. As such, you |
| should always test your application on real or <a |
| href="{@docRoot}guide/developing/devices/index.html">virtual devices</a> with various screen sizes |
| and densities.</p> |
| |
| <p>Although we recommend that you design your application to function properly on multiple |
| configurations of screen size and density, you can instead choose to limit the distribution of your |
| application to certain types of screens, such as only tablets or only mobile devices. To do so, you |
| can add elements to your Android manifest file that enable filtering based on screen configuration |
| by external services such as Google Play.</p> |
| |
| <p>However, before you decide to restrict your application to certain screen configurations, you |
| should understand the techniques for <a |
| href="{@docRoot}guide/practices/screens_support.html">supporting multiple screens</a> and employ |
| them to the best of your ability. By supporting multiple screens, your application can be made |
| available to the greatest number of users with different devices.</p> |
| |
| |
| <h3 id="FilteringTabletApps">Filtering a tablet application from mobile devices</h3> |
| |
| <p>If the system scaling adversely affects your application UI when scaling your application down |
| for smaller screens, you should add <a |
| href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">alternative |
| layouts</a> for smaller screens to adjust your layout. 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 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 extra large |
| screens, you can declare the element in your manifest like this:</p> |
| |
| <pre> |
| <manifest ... > |
| ... |
| <supports-screens android:smallScreens="false" |
| android:normalScreens="false" |
| android:largeScreens="false" |
| android:xlargeScreens="true" /> |
| <application ... > |
| ... |
| <application> |
| </manifest> |
| </pre> |
| |
| <p>External services such as Google Play read this manifest element and use it to ensure that |
| your application is available only to devices with an extra large screen.</p> |
| |
| <p class="note"><strong>Note:</strong> If you use the <a |
| href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code |
| <supports-screens>}</a> element for the reverse scenario (when your application is not compatible |
| with <em>larger</em> screens) and set the larger screen size attributes to {@code "false"}, then |
| external services such as Google Play <strong>do not</strong> apply filtering. Your application |
| will still be available to larger screens, but when it runs, it will not fill the screen—the |
| system will draw it in a "postage stamp" window that's the same relative size as the screen size |
| that your application does support. If you want to prevent your application from being downloaded on |
| larger screens, see the following section.</p> |
| |
| |
| <h3 id="FilteringMobileApps">Filtering a mobile device application from tablets</h3> |
| |
| <p>Because Android automatically scales applications to fit larger screens, you shouldn't |
| need to filter your application from larger screens. However, you might discover that your |
| application can't scale up or perhaps you've decided to publish two versions of your application |
| that each deliver different features for different screen configurations, so you don't want |
| larger devices to download the version designed for smaller screens. In such a case, you can |
| use the <a href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">{@code |
| <compatible-screens>}</a> element to manage the distribution of your application based on the |
| combination of screen size and density. External services such as |
| Google Play uses this information to apply filtering to your application, so that only devices |
| that have a screen configuration with which you declare compatibility can download your |
| application.</p> |
| |
| <p>The <a href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">{@code |
| <compatible-screens>}</a> element must contain one or more {@code <screen>} elements, |
| which each specify a screen configuration with which your application is compatible, using both |
| the {@code android:screenSize} and {@code android:screenDensity} attributes. Each {@code |
| <screen>} element <strong>must include both attributes</strong> to specify an individual |
| screen configuration—if either attribute is missing, then the element is invalid |
| (external services such as Google Play will ignore it).</p> |
| |
| <p>For example, if your application is compatible with only small and normal screens, regardless |
| of screen density, then you must specify eight different {@code <screen>} elements, |
| because each screen size has four density configurations. You must declare each one of |
| these; any combination of size and density that you do <em>not</em> specify is considered a screen |
| configuration with which your application is <em>not</em> compatible. Here's what the manifest |
| entry looks like if your application is compatible with only small and normal screens:</p> |
| |
| <pre> |
| <manifest ... > |
| ... |
| <compatible-screens> |
| <!-- all small size screens --> |
| <screen android:screenSize="small" android:screenDensity="ldpi" /> |
| <screen android:screenSize="small" android:screenDensity="mdpi" /> |
| <screen android:screenSize="small" android:screenDensity="hdpi" /> |
| <screen android:screenSize="small" android:screenDensity="xhdpi" /> |
| <!-- all normal size screens --> |
| <screen android:screenSize="normal" android:screenDensity="ldpi" /> |
| <screen android:screenSize="normal" android:screenDensity="mdpi" /> |
| <screen android:screenSize="normal" android:screenDensity="hdpi" /> |
| <screen android:screenSize="normal" android:screenDensity="xhdpi" /> |
| </compatible-screens> |
| <application ... > |
| ... |
| <application> |
| </manifest> |
| </pre> |
| |
| <p class="note"><strong>Note:</strong> Although you can also use the <a |
| href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">{@code |
| <compatible-screens>}</a> element for the reverse scenario (when your application is not |
| compatible with smaller screens), it's easier if you instead use the <a |
| href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code |
| <supports-screens>}</a> as discussed in the previous section, because it doesn't require you |
| to specify each screen density your application supports.</p> |
| |
| <p>Remember, you should strive to make your application available to as many devices as possible by |
| applying all necessary techniques for <a |
| href="{@docRoot}guide/practices/screens_support.html">supporting multiple screens</a>. You should |
| then use the <a href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">{@code |
| <compatible-screens>}</a> element to filter your application from certain devices only when you |
| cannot offer compatibility on all screen configurations or you have decided to provide |
| multiple versions of your application, each for a different set of screen configurations.</p> |
| |
| |
| |
| <h2 id="Issues">Other Issues</h2> |
| |
| <p>Whether you decide to optimize or upgrade your application for tablet-type devices, you |
| should be aware that the functionality and availability of your application on new devices |
| might be affected by the following issues:</p> |
| |
| <ul> |
| <li><a href="#Landscape">Tablets are often designed for use in the landscape orientation</a> |
| <p>Tablets and similar devices often have a screen that uses the landscape orientation |
| by default. If your application assumes a portrait orientation or locks into portrait |
| orientation, you should update your application to support landscape.</p></li> |
| <li><a href="#Telephony">Not all devices have telephony or other features</a> |
| <p>If your application declares the {@code "android.hardware.telephony"} feature in the manifest, |
| then it will not be available to devices that do not offer telephony (such as tablets), based on |
| Google Play filtering. If your application can function properly without telephony, you should |
| update your application to gracefully disable the telephony features when not available on a |
| device.</p></li> |
| </ul> |
| |
| |
| <h3 id="Landscape">Adding support for landscape screens</h3> |
| |
| <p>Although tablets can rotate to operate in any orientation, they are often designed for |
| landscape orientation and that is how most users will use them. So, you should ensure that your |
| application can function in landscape. Even if you want to avoid rotating the screen while your |
| application is running, you should not assume that portrait is the device's default orientation. You |
| should either ensure that your layout is usable in both portrait and landscape orientations or |
| provide an <a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources" |
| >alternative layout resource</a> for landscape orientation.</p> |
| |
| <p>If you believe your application or game provides its best experience when the screen is tall, |
| consider that tablets and similar devices have a screen that's as tall or taller in landscape |
| orientation than a phone in portrait orientation. With that in mind, you might be able to add a |
| landscape design that adds padding or extra landscape scenery on the left and right sides, so |
| the primary screen space still remains taller than it is wide.</p> |
| |
| <p>Ideally, your application should handle all orientation changes instead of locking into one |
| orientation. When the user rotates the screen, the system restarts the current activity by calling |
| {@link android.app.Activity#onDestroy onDestroy()} and {@link android.app.Activity#onCreate |
| onCreate()}) in immediate succession. You should design your activity to account for these changes |
| in the lifecycle, so the activity can save and restore its state. You can learn about the |
| necessary lifecycle callback methods and how to save and restore the activity state in the <a |
| href="{@docRoot}guide/topics/fundamentals/activities.html#Lifecycle">Activities</a> |
| document. If your activity state is more complex and cannot retain it using the normal |
| lifecycle callback methods, you can use alternative techniques described in <a |
| href="{@docRoot}guide/topics/resources/runtime-changes.html">Handling Runtime Changes</a>.</p> |
| |
| <p>In the worst-case scenario, however, you can avoid orientation changes by using the <a |
| href="{@docRoot}guide/topics/manifest/activity-element.html#screen">{@code |
| android:screenOrientation}</a> attribute in the <a |
| href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> |
| element. Instead of locking the orientation in landscape or portrait, however, you should |
| specify a value of {@code "nosensor"}. This way, your activity uses whatever orientation the |
| device specifies as its natural orientation and the screen will not rotate. You should still |
| avoid using the <a |
| href="{@docRoot}guide/topics/manifest/activity-element.html#screen">{@code |
| android:screenOrientation}</a> attribute, but because it's sometimes necessary to lock the |
| screen into one orientation, it's best if you do so in a way that uses the device's natural |
| orientation instead of assuming one specific orientation.</p> |
| |
| <p>If your application uses the orientation sensors, such as the accelerometer (with the {@link |
| android.hardware.SensorManager} APIs), also be aware that the landscape screen can also cause |
| problems, due to false assumptions about which orientation is the natural position. For more |
| information about how you should properly handle rotation changes when using the orientation |
| sensors, read the blog post, <a |
| href="http://android-developers.blogspot.com/2010/09/one-screen-turn-deserves-another.html">One |
| Screen Turn Deserves Another</a>.</p> |
| |
| |
| |
| <h3 id="Telephony">Using telephony or other variable features</h3> |
| |
| <p>Tablets and similar devices might not include support for telephony, so they can't make |
| traditional phone calls or handle SMS. Some devices might also omit |
| other hardware features, such as Bluetooth. If your application uses these features, then your |
| manifest file probably already includes (or should include) a declaration of the feature with the <a |
| href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a> |
| element. Doing so prevents devices that do not declare support for the feature from downloading |
| your applications. For example:</p> |
| |
| <pre><uses-feature android:name="android.hardware.telephony" /></pre> |
| |
| <p>By default, this declares that your application <em>requires</em> telephony features. So, |
| external services such as Google Play use this information to filter your application from |
| devices that do not offer telephony.</p> |
| |
| <p>If, however, your application uses, but does not require the feature, you should |
| add to this element, {@code android:required="false"}. For example:</p> |
| |
| <pre><uses-feature android:name="android.hardware.telephony" android:required="false" /></pre> |
| |
| <p>This indicates that your application uses the feature, but is still functional if the feature is |
| not available. So, it should still be available to devices that don't provide telephony hardware |
| (or telephony features), such as tablets.</p> |
| |
| <p>Then in your application code, you must gracefully disable the features that use telephony |
| when it's not available. You can check whether the feature is available using {@link |
| android.content.pm.PackageManager#hasSystemFeature PackageManager.hasSystemFeature()}. For |
| example:</p> |
| |
| <pre> |
| PackageManager pm = getPackageManager(); |
| boolean hasTelephony = pm.hasSystemFeature(PackageManager.FEATURE_TELEPHONY); |
| </pre> |
| |
| <p>For more information about these |
| issues and how to future-proof your application for different hardware, read the blog post <a |
| href="http://android-developers.blogspot.com/2010/10/five-steps-to-future-hardware-happiness.html"> |
| The Five Steps to Future Hardware Happiness</a>.</p> |