1 page.title=Optimizing Apps for Android 3.0 2 @jd:body 3 4 5 <div id="deprecatedSticker"> 6 <a href="#" 7 onclick="$('#naMessage').show();$('#deprecatedSticker').hide();return false"> 8 <strong>This doc is deprecated</strong></a> 9 </div> 10 11 12 <div id="naMessage" style="display:block"> 13 <div><p><strong>This document has been deprecated.</strong></p> 14 <p>To learn about how you can optimize your app for both tablets and handsets, please 15 read the guide to <a href="tablets-and-handsets.html">Supporting Tablets and 16 Handsets</a>.</p> 17 18 <input style="margin-top:1em;padding:5px" type="button" 19 value="That's nice, but I still want to read this document" 20 onclick="$('#naMessage').hide();$('#deprecatedSticker').show()" /> 21 </div> 22 </div> 23 24 25 26 27 28 29 <div id="qv-wrapper"> 30 <div id="qv"> 31 <h2>In this document</h2> 32 <ol> 33 <li><a href="#Setup">Setting Up Your SDK with Android 3.0</a></li> 34 <li><a href="#Optimizing">Optimizing Your App for Tablets</a></li> 35 <li><a href="#Upgrading">Upgrading or Developing a New App for Tablets</a></li> 36 <li><a href="#ManagingAppDist">Managing App Distribution Based on Screen Configuration</a> 37 <ol> 38 <li><a href="#FilteringTabletApps">Filtering a tablet app from mobile devices</a></li> 39 <li><a href="#FilteringMobileApps">Filtering a mobile device app from tablets</a></li> 40 </ol> 41 </li> 42 <li><a href="#Issues">Other Issues</a> 43 <ol> 44 <li><a href="#Landscape">Adding support for landscape screens</a></li> 45 <li><a href="#Telephony">Using telephony or other variable features</a></li> 46 </ol> 47 </li> 48 </ol> 49 50 <h2>See also</h2> 51 52 <ol> 53 <li><a href="tablets-and-handsets.html">Supporting Tablets 54 and Handsets</a></li> 55 <li><a 56 href="{@docRoot}tools/extras/support-library.html">Compatibility Library</a></li> 57 <li><a href="http://code.google.com/p/iosched/">Google I/O App source code</a></li> 58 </ol> 59 60 </div> 61 </div> 62 63 <p>Android 3.0 introduces several features that allow 64 you to enhance your user's experience on tablets and similar devices. Any application you've already 65 published is compatible with devices running Android 3.0, by default, because Android applications 66 are forward-compatible. However, new tablet devices running Android 3.0 are now available to the 67 public and provide users a new Android experience on a larger screen, so you should make sure 68 your application looks and works great on the new platform and new device form-factors.</p> 69 70 <p>This document shows how you can optimize your existing application for Android 3.0 and 71 maintain compatibility with older versions or upgrade your application completely with new APIs.</p> 72 73 74 <p><b>To get started:</b></p> 75 76 <ol> 77 <li><a href="#Setup">Set up your SDK with Android 3.0</a>. 78 <p>Install the Android 3.0 platform, new tools, and set up a new AVD.</p></li> 79 <li>Choose to either optimize or upgrade: 80 <ol type="a"> 81 <li><a href="#Optimizing">Optimize your app for tablets and similar devices</a>. 82 <p>Read this section if you have an existing application and want to 83 maintain compatibility with older versions of Android. All you need to do is update your 84 manifest file to declare support for Android 3.0, test your application on the new platform, and 85 add extra resources to support extra large screens, as appropriate.</p> 86 </li> 87 <li><a href="#Upgrading">Upgrade or develop a new app for tablets and similar devices</a>. 88 <p>Read this section if you want to upgrade your application to use APIs introduced in 89 Android 3.0 or create a new application targeted to tablets and similar devices. Compared to 90 upgrading to previous versions of Android, there's nothing different about upgrading to Android 3.0. 91 This section introduces some of the key features and APIs you should use to make an 92 application that's fully enhanced for tablets.</p></li> 93 </ol> 94 </li> 95 <li>Consider whether you need to <a href="#ManagingAppDist">manage the distribution of your 96 application based on screen configuration</a>.</li> 97 <li>Then review some <a href="#Issue">other issues</a> you might encounter when developing 98 for tablets and similar devices.</li> 99 </ol> 100 101 102 <h2 id="Setup">Set Up Your SDK with Android 3.0</h2> 103 104 <p>To start testing and developing your application on Android 3.0, set up your existing Android 105 SDK with the new platform:</p> 106 107 <p>(If you don't have an existing Android SDK, <a href="{@docRoot}sdk/index.html">download the 108 SDK starter package now</a>.)</p> 109 110 <ol> 111 <li><a href="{@docRoot}sdk/exploring.html#launching">Launch the Android SDK 112 Manager</a> and install the following: 113 <ul> 114 <li>SDK Platform Android 3.0</li> 115 <li>Android SDK Tools, revision 10</li> 116 <li>Android SDK Platform-tools, revision 3</li> 117 <li>Documentation for Android SDK, API 11</li> 118 <li>Samples for SDK API 11</li> 119 </ul> 120 </li> 121 <li><a href="{@docRoot}tools/devices/managing-avds.html">Create an AVD</a> for a tablet-type 122 device: 123 <p>Set the target to "Android 3.0" and the skin to "WXGA" (the default skin).</p></li> 124 </ol> 125 126 <p>The best way to test your application on Android 3.0 is to use real hardware running Android 3.0, 127 such as the <a href="http://www.motorola.com/staticfiles/Consumers/XOOM/index.html">Motorola 128 Xoom</a>. Of course, you can also use the Android emulator on your development machine, but because 129 the Android emulator must simulate the ARM instruction set on your computer and the WXGA screen is 130 significantly larger than a typical virtual device, emulator performance is much slower than a real 131 device.</p> 132 133 <h3>About emulator performance</h3> 134 135 <p>Initializing the emulator can be slow and can take several minutes, depending on 136 your hardware. When the emulator is booting, there is limited user feedback, so please be patient 137 and wait until you see the home screen (or lock screen) appear. </p> 138 139 <p>However, you don't need to boot the emulator each time you rebuild your 140 application—typically you only need to boot at the start of a session and keep it running. 141 Also see the tip below for information about using a snapshot to drastically reduce startup time 142 after the first initialization. </p> 143 144 <p>General performance in the emulator is also slow. We're working hard to resolve the performance 145 issues and it will improve in future tools releases. If you don't yet have a real device running 146 Android 3.0, the emulator is still best way to evaluate your application's appearance and 147 functionality on Android 3.0.</p> 148 149 <p class="note"><strong>Tip:</strong> To improve the startup time for the emulator, enable snapshots 150 for the AVD when you create it with the AVD Manager (there's a checkbox in the AVD creator 151 to <strong>Enable</strong> snapshots). Then, start the AVD from the AVD manager and check <b>Launch 152 from snapshot</b> and <b>Save to snapshot</b>. This way, when you close the emulator, a snapshot of 153 the AVD state is saved and used to quickly relaunch the AVD next time. However, when you choose to 154 save a snapshot, the emulator will be slow to close, so you might want to disable <b>Save to 155 snapshot</b> after you've acquired an initial snapshot (after you close the AVD for the first 156 time).</p> 157 158 159 160 <h2 id="Optimizing">Optimizing Your App for Tablets</h2> 161 162 <p>If you've already developed an application for an earlier version of Android, there are a few 163 things you can do to optimize it for a tablet-style experience on Android 3.0 without changing the 164 minimum version required (you don't need to change your manifest's <a 165 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code 166 android:minSdkVersion}</a>).</p> 167 168 <p class="note"><strong>Note:</strong> All Android applications are forward-compatible, so 169 there's nothing you <em>have to</em> do—if your application is a good citizen of the Android 170 APIs, your app should work fine on devices running Android 3.0. However, in order to provide users 171 a better experience when using your app on an Android 3.0 tablet or similar-size device, you 172 should update your application to inherit the new system theme and provide some optimizations for 173 larger screens.</p> 174 175 <p>Here are a few things you can do to optimize your application for devices running Android 176 3.0:</p> 177 178 <ol> 179 <li><b>Test your current application on Android 3.0</b> 180 <ol> 181 <li>Build your application as-is and install it on your Android 3.0 AVD (created above during 182 <a href="#Setup">setup</a>).</li> 183 <li>Perform your usual tests to be sure everything works and looks as expected.</li> 184 </ol> 185 </li> 186 187 <li><b>Apply the new "holographic" theme to your application</b> 188 <ol> 189 <li>Open your manifest file and update the <a 190 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code <uses-sdk>}</a> element to 191 set <a 192 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code 193 android:targetSdkVersion}</a> to {@code "11"}. For example: 194 <pre> 195 <manifest ... > 196 <uses-sdk android:minSdkVersion="4" 197 android:targetSdkVersion="11" /> 198 <application ... > 199 ... 200 <application> 201 </manifest> 202 </pre> 203 <p>By targeting the Android 3.0 platform, the system automatically applies the holographic theme 204 to each activity when your application runs on an Android 3.0 device. The holographic theme 205 provides a new design for widgets, such as buttons and text boxes, and new styles for other 206 visual elements. This is the standard theme for applications built for Android 3.0, so your 207 application will look and feel consistent with the system and other applications when it is 208 enabled.</p> 209 <p>Additionally, when an activity uses the holographic theme, the system enables the <a 210 href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> for the activity and removes the 211 Options Menu button in the system bar. The Action Bar 212 replaces the traditional title bar at the top of the activity window and provides the user access to 213 the activity's Options Menu.</p> 214 </li> 215 <li>Build your application against the same version of the Android platform you have been 216 using previously (such as the version declared in your <a 217 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a>), 218 but install it on the Android 3.0 AVD. (You should not build against Android 3.0 unless you are 219 using new APIs.) Repeat your tests to be sure that your user interface works well with the 220 holographic theme. 221 <p class="note"><strong>Note:</strong> If you have applied other themes directly to your 222 activities, they will override the inherited holographic theme. To resolve this, you can use 223 the <a href="{@docRoot}guide/topics/resources/providing-resources.html#VersionQualifier">platform 224 version qualifier</a> to provide an alternative theme for Android 3.0 devices that's based on the 225 holographic theme. For more information, read how to <a 226 href="{@docRoot}guide/topics/ui/themes.html#SelectATheme">select a theme based on platform 227 version</a>.</p> 228 </ol> 229 </li> 230 231 <li><b>Supply alternative layout resources for xlarge screens</b> 232 <p>By providing <a 233 href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">alternative 234 resources</a> when running on extra large screens (using the <code>xlarge</code> resource 235 qualifier), you can improve the user experience of your application on tablet-type devices without 236 using new APIs.</p> 237 <p>For example, here are some things to consider when creating a new layout for extra large 238 screens:</p> 239 <ul> 240 <li>Landscape layout: The "normal" orientation for tablet-type devices is usually landscape 241 (wide), so you should be sure that your activities offer a layout that's optimized for a wide 242 viewing area. <p>You can specify landscape resources with the <code>land</code> resource 243 qualifier, but if you want alternative resources for an extra large landscape screen, you 244 should use both the <code>xlarge</code> and <code>land</code> qualifiers. For example, {@code 245 res/layout-xlarge-land/}. The order of the qualifier names is important; see <a 246 href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources"> 247 Providing Alternative Resources</a> for more information.</p></li> 248 <li>Button position and size: Consider whether the position and size of the most common 249 buttons in your UI make them easily accessible while holding a tablet with two hands. In some 250 cases, you might need to resize buttons, especially if they use {@code "wrap_content"} 251 as the width value. To enlarge the buttons, if necessary, you should either: add 252 extra padding to the button; specify dimension values with {@code dp} units; or use {@code 253 android:layout_weight} when the button is in a <a 254 href="{@docRoot}guide/topics/ui/layout-objects.html#linearlayout">linear layout</a>. Use your 255 best judgment of proportions for each screen size—you don't want the buttons to be too big, 256 either.</li> 257 <li>Font sizes: Be sure your application uses {@code sp} units when setting font 258 sizes. This alone should ensure a readable experience on tablet-style devices, because it is a 259 scale-independent pixel unit, which will resize as appropriate for the current screen configuration. 260 In some cases, however, you still might want to consider larger font sizes for <code>xlarge</code> 261 configurations.</li> 262 </ul> 263 <p>In general, always be sure that your application follows the <a 264 href="{@docRoot}guide/practices/screens_support.html#screen-independence">Best Practices 265 for Screen Independence</a>.</p> 266 </li> 267 </ol> 268 269 270 271 272 <h2 id="Upgrading">Upgrading or Developing a New App for Tablets</h2> 273 274 <div class="sidebox-wrapper"> 275 <div class="sidebox"> 276 <h3>Use the Compatibility Library to remain backward-compatible</h3> 277 <p>It is possible for you to upgrade your application with some new 278 APIs <em>and</em> remain compatible with older versions of Android. Usually, this requires that you 279 use techniques such as reflection to check for the availability of certain APIs at runtime. However, 280 to help you add features from Android 3.0 without requiring you to change your <a 281 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a> 282 or build target, we're providing a static library called the <a 283 href="{@docRoot}tools/extras/support-library.html">Compatibility Library</a> 284 (downloadable from the Android SDK Manager).</p> 285 <p>This library includes APIs for <a 286 href="{@docRoot}guide/components/fragments.html">fragments</a>, <a 287 href="{@docRoot}guide/components/loaders.html">loaders</a>, and some updated classes. By 288 simply adding this library to your Android project, you can use these APIs in your application and 289 remain compatible with Android 1.6. For information about how to get the library and start 290 using it in your application, see the <a 291 href="{@docRoot}tools/extras/support-library.html">Compatibility Library</a> document.</p> 292 </div> 293 </div> 294 295 296 <p>If you want to develop an application that's fully enhanced for tablet-type devices running 297 Android 3.0, then you need to use new APIs in Android 3.0. This section introduces some of 298 the new features you should use.</p> 299 300 301 <h3>Declare the minimum system version</h3> 302 303 <p>The first thing to do when you upgrade or create a project for Android 3.0 is set your manifest's 304 <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code 305 android:minSdkVersion}</a> to {@code "11"}. This declares that your application uses APIs available 306 in Android 3.0 and greater, so it should not be available to devices running an older version of 307 Android. For example:</p> 308 309 <pre> 310 <manifest ... > 311 <uses-sdk android:minSdkVersion="11" /> 312 <application ... > 313 ... 314 <application> 315 </manifest> 316 </pre> 317 318 <p>Not only is this necessary in order to declare the minimum API level your application requires, 319 but it enables the new holographic theme to each of your activities. The holographic theme is the 320 standard theme for the Android 3.0 system and all applications designed for it. It includes new 321 designs for the system widgets and overall appearance.</p> 322 323 <p>Additionally, the holographic theme enables the Action Bar for each activity.</p> 324 325 326 <h3>Use the Action Bar</h3> 327 328 <p>The Action Bar is a widget for activities that replaces the traditional title bar at the top of 329 the screen. By default, the Action Bar includes the application logo on the left side, followed by 330 the activity title, and access to items from the Options Menu in a drop-down list on the right 331 side.</p> 332 333 <p>You can enable items from the Options Menu to appear directly in the Action Bar as 334 "action items" by adding {@code showAsAction="ifRoom"} to specific menu items in your <a 335 href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a>. You can also add 336 navigation features to the Action Bar, such as tabs, and use the application icon to navigate to 337 your application's "home" activity or to navigate "up" the application's activity hierarchy.</p> 338 339 <p>For more information, read <a href="{@docRoot}guide/topics/ui/actionbar.html">Using the 340 Action Bar</a>.</p> 341 342 343 344 <h3>Divide your activities into fragments</h3> 345 346 <p>A fragment represents a behavior or a portion of user interface in an activity. You can think of 347 a fragment as a modular section of an activity, which has its own lifecycle, receives its own input 348 events, and which you can add or remove while the activity is running. Fragments are an optional 349 component for your activities that allow you to build a multi-pane UI and reuse them in multiple 350 activities. If you're building an application for tablets, we recommend that you use fragments to 351 create activities that offer a more dynamic and flexible user interface.</p> 352 353 <p>For example, a news application can use one fragment to show a list of articles on the left and 354 another fragment to display an article on the right—both fragments appear in one activity, 355 side by side, and each fragment has its own set of lifecycle callback methods and handles its own 356 input events. Thus, instead of using one activity to select an article and another activity to 357 read the article, the user can select an article and read it all within the same activity.</p> 358 359 <p>For more information, read the <a 360 href="{@docRoot}guide/components/fragments.html">Fragments</a> document.</p> 361 362 363 <h3>Use new animation APIs for transitions</h3> 364 365 <p>An all-new animation framework allows you to animate arbitrary properties of any object 366 (such as a View, Drawable, Fragment, or anything else). You can define several animation aspects 367 (such as duration, repeat, interpolation, and more) for an object's int, float, and hexadecimal 368 color values, by default. That is, when an object has a property field for one of these types, you 369 can change its value over time to affect an animation.</p> 370 371 <p>The {@link android.view.View} class also provides new APIs that leverage the new animation 372 framework, allowing you to easily apply 2D and 3D transformations to views in your activity layout. 373 New transformations are made possible with a set of object properties that define the view's layout 374 position, orientation, transparency and more.</p> 375 376 <p>For more information, read the <a 377 href="{@docRoot}guide/topics/graphics/prop-animation.html">Property Animation</a> document.</p> 378 379 380 <h3>Enable hardware acceleration</h3> 381 382 <p>Android 3.0 adds a hardware-accelerated OpenGL renderer that gives a performance boost to most 2D 383 graphics operations. You can enable hardware-accelerated rendering in your application by setting 384 {@code android:hardwareAccelerated="true"} in your manifest's <a 385 href="{@docRoot}guide/topics/manifest/application-element.html">{@code <application>}</a> 386 element or for individual <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code 387 <activity>}</a> elements. Hardware acceleration results in smoother animations, smoother 388 scrolling, and overall better performance and response to user interaction. When enabled, be sure 389 that you thoroughly test your application on a device that supports hardware acceleration.</p> 390 391 392 <h3>Enhance your app widgets</h3> 393 394 <p>App widgets allow users to access information from your application directly from the Home 395 screen and interact with ongoing services (such as preview their email and control music playback). 396 Android 3.0 enhances these capabilities by enabling collections, created with widgets such as 397 {@link android.widget.ListView}, {@link android.widget.GridView}, and the new {@link 398 android.widget.StackView}. These widgets allow you to create more interactive app 399 widgets, such as one with a scrolling list, and can automatically update their data through a {@link 400 android.widget.RemoteViewsService}.</p> 401 402 <p>Additionally, you should create a preview image of your app widget using the Widget Preview 403 application (pre-installed in an Android 3.0 AVD) and reference it with the {@link 404 android.appwidget.AppWidgetProviderInfo#previewImage android:previewImage} attribute, so that users 405 can see what the app widget looks like before adding it to their Home screen.</p> 406 407 408 <h3>Add other new features</h3> 409 410 <p>Android 3.0 introduces many more APIs that you might find valuable for your 411 application, such as drag and drop APIs, new Bluetooth APIs, a system-wide clipboard framework, a 412 new graphics engine called Renderscript, and more.</p> 413 414 <p>To learn more about the APIs mentioned above and more, see the <a 415 href="{@docRoot}about/versions/android-3.0.html">Android 3.0 Platform</a> document.</p> 416 417 418 <h3>Look at some samples</h3> 419 420 <p>Many of the new features and APIs that are described above and in the <a 421 href="{@docRoot}about/versions/android-3.0.html#api">Android 3.0 Platform</a> document also have accompanying 422 samples that allow you to preview the effects and can help you understand how to use them. To get 423 the samples, download them from the SDK repository <a href="{@docRoot}sdk/exploring.html" 424 >using the Android SDK Manager</a>. After downloading the samples ("Samples for SDK API 425 11"), you can find them in <code><sdk_root>/samples/android-11/</code>. The following list 426 provides links to the browsable source code for some of the samples:</p> 427 428 <ul> 429 <li><a href="{@docRoot}resources/samples/HoneycombGallery/index.html">Honeycomb Gallery</a>: 430 Demonstrates many new APIs in Android 3.0, including fragments, the action bar, drag and drop, and 431 animations.</li> 432 <li><a 433 href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/index.html#Fragment"> 434 Fragments</a>: Various samples that demonstrate fragment layouts, back stack, restoring state, and 435 more.</li> 436 <li><a 437 href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/ActionBarMechanics.html" 438 >Action Bar</a>: Samples that demonstrate various Action Bar features, such as tabs, logos, and 439 action items.</li> 440 <li><a 441 href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/content/ClipboardSample.html" 442 >Clipboard</a>: An example of how to use the clipboard for copy and paste operations.</li> 443 <li><a 444 href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/DragAndDropDemo.html"> 445 Drag and Drop</a>: An example of how to perform drag and drop with new View events.</li> 446 <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/List15.html"> 447 Multi-choice List</a>: An example of how to provide multiple-choice selection for ListView and 448 GridView.</li> 449 <li><a 450 href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LoaderThrottle.html"> 451 Content Loaders</a>: An example using new Loader APIs to asynchronously load data.</li> 452 <li><a 453 href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/animation/index.html"> 454 Property Animation</a>: Several samples using the new animation APIs to animate object 455 properties.</li> 456 <li><a 457 href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/SearchViewActionBar.html"> 458 Search View Widget</a>: Example using the new search widget in the Action Bar (as an 459 "action view").</li> 460 <li><a 461 href="{@docRoot}resources/samples/RenderScript/index.html">Renderscript</a>: Contains several 462 different applications that demonstrate using renderscript APIs for computations and 3D 463 graphics.</li> 464 </ul> 465 466 467 468 <h2 id="ManagingAppDist">Managing App Distribution Based on Screen Configuration</h2> 469 470 <p>If your manifest file has either <a 471 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a> 472 or <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code 473 android:targetSdkVersion}</a> set to {@code "4"} or higher, then the Android system will scale your 474 application's layout and assets to fit the current device screen, whether the device screen is 475 smaller or larger than the one for which you originally designed your application. As such, you 476 should always test your application on real or <a 477 href="{@docRoot}tools/devices/index.html">virtual devices</a> with various screen sizes 478 and densities.</p> 479 480 <p>Although we recommend that you design your application to function properly on multiple 481 configurations of screen size and density, you can instead choose to limit the distribution of your 482 application to certain types of screens, such as only tablets or only mobile devices. To do so, you 483 can add elements to your Android manifest file that enable filtering based on screen configuration 484 by external services such as Google Play.</p> 485 486 <p>However, before you decide to restrict your application to certain screen configurations, you 487 should understand the techniques for <a 488 href="{@docRoot}guide/practices/screens_support.html">supporting multiple screens</a> and employ 489 them to the best of your ability. By supporting multiple screens, your application can be made 490 available to the greatest number of users with different devices.</p> 491 492 493 <h3 id="FilteringTabletApps">Filtering a tablet application from mobile devices</h3> 494 495 <p>If the system scaling adversely affects your application UI when scaling your application down 496 for smaller screens, you should add <a 497 href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">alternative 498 layouts</a> for smaller screens to adjust your layout. However, sometimes your layout still might 499 not fit a smaller screen or you've explicitly designed your application only for tablets and other 500 large devices. In this case, you can manage the availability of your application to smaller screens 501 by using the <a href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code 502 <supports-screens>}</a> manifest element.</p> 503 504 <p>For example, if you want your application to be available only to extra large 505 screens, you can declare the element in your manifest like this:</p> 506 507 <pre> 508 <manifest ... > 509 ... 510 <supports-screens android:smallScreens="false" 511 android:normalScreens="false" 512 android:largeScreens="false" 513 android:xlargeScreens="true" /> 514 <application ... > 515 ... 516 <application> 517 </manifest> 518 </pre> 519 520 <p>External services such as Google Play read this manifest element and use it to ensure that 521 your application is available only to devices with an extra large screen.</p> 522 523 <p class="note"><strong>Note:</strong> If you use the <a 524 href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code 525 <supports-screens>}</a> element for the reverse scenario (when your application is not compatible 526 with <em>larger</em> screens) and set the larger screen size attributes to {@code "false"}, then 527 external services such as Google Play <strong>do not</strong> apply filtering. Your application 528 will still be available to larger screens, but when it runs, it will not fill the screen—the 529 system will draw it in a "postage stamp" window that's the same relative size as the screen size 530 that your application does support. If you want to prevent your application from being downloaded on 531 larger screens, see the following section.</p> 532 533 534 <h3 id="FilteringMobileApps">Filtering a mobile device application from tablets</h3> 535 536 <p>Because Android automatically scales applications to fit larger screens, you shouldn't 537 need to filter your application from larger screens. However, you might discover that your 538 application can't scale up or perhaps you've decided to publish two versions of your application 539 that each deliver different features for different screen configurations, so you don't want 540 larger devices to download the version designed for smaller screens. In such a case, you can 541 use the <a href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">{@code 542 <compatible-screens>}</a> element to manage the distribution of your application based on the 543 combination of screen size and density. External services such as 544 Google Play uses this information to apply filtering to your application, so that only devices 545 that have a screen configuration with which you declare compatibility can download your 546 application.</p> 547 548 <p>The <a href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">{@code 549 <compatible-screens>}</a> element must contain one or more {@code <screen>} elements, 550 which each specify a screen configuration with which your application is compatible, using both 551 the {@code android:screenSize} and {@code android:screenDensity} attributes. Each {@code 552 <screen>} element <strong>must include both attributes</strong> to specify an individual 553 screen configuration—if either attribute is missing, then the element is invalid 554 (external services such as Google Play will ignore it).</p> 555 556 <p>For example, if your application is compatible with only small and normal screens, regardless 557 of screen density, then you must specify eight different {@code <screen>} elements, 558 because each screen size has four density configurations. You must declare each one of 559 these; any combination of size and density that you do <em>not</em> specify is considered a screen 560 configuration with which your application is <em>not</em> compatible. Here's what the manifest 561 entry looks like if your application is compatible with only small and normal screens:</p> 562 563 <pre> 564 <manifest ... > 565 ... 566 <compatible-screens> 567 <!-- all small size screens --> 568 <screen android:screenSize="small" android:screenDensity="ldpi" /> 569 <screen android:screenSize="small" android:screenDensity="mdpi" /> 570 <screen android:screenSize="small" android:screenDensity="hdpi" /> 571 <screen android:screenSize="small" android:screenDensity="xhdpi" /> 572 <!-- all normal size screens --> 573 <screen android:screenSize="normal" android:screenDensity="ldpi" /> 574 <screen android:screenSize="normal" android:screenDensity="mdpi" /> 575 <screen android:screenSize="normal" android:screenDensity="hdpi" /> 576 <screen android:screenSize="normal" android:screenDensity="xhdpi" /> 577 </compatible-screens> 578 <application ... > 579 ... 580 <application> 581 </manifest> 582 </pre> 583 584 <p class="note"><strong>Note:</strong> Although you can also use the <a 585 href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">{@code 586 <compatible-screens>}</a> element for the reverse scenario (when your application is not 587 compatible with smaller screens), it's easier if you instead use the <a 588 href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code 589 <supports-screens>}</a> as discussed in the previous section, because it doesn't require you 590 to specify each screen density your application supports.</p> 591 592 <p>Remember, you should strive to make your application available to as many devices as possible by 593 applying all necessary techniques for <a 594 href="{@docRoot}guide/practices/screens_support.html">supporting multiple screens</a>. You should 595 then use the <a href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">{@code 596 <compatible-screens>}</a> element to filter your application from certain devices only when you 597 cannot offer compatibility on all screen configurations or you have decided to provide 598 multiple versions of your application, each for a different set of screen configurations.</p> 599 600 601 602 <h2 id="Issues">Other Issues</h2> 603 604 <p>Whether you decide to optimize or upgrade your application for tablet-type devices, you 605 should be aware that the functionality and availability of your application on new devices 606 might be affected by the following issues:</p> 607 608 <ul> 609 <li><a href="#Landscape">Tablets are often designed for use in the landscape orientation</a> 610 <p>Tablets and similar devices often have a screen that uses the landscape orientation 611 by default. If your application assumes a portrait orientation or locks into portrait 612 orientation, you should update your application to support landscape.</p></li> 613 <li><a href="#Telephony">Not all devices have telephony or other features</a> 614 <p>If your application declares the {@code "android.hardware.telephony"} feature in the manifest, 615 then it will not be available to devices that do not offer telephony (such as tablets), based on 616 Google Play filtering. If your application can function properly without telephony, you should 617 update your application to gracefully disable the telephony features when not available on a 618 device.</p></li> 619 </ul> 620 621 622 <h3 id="Landscape">Adding support for landscape screens</h3> 623 624 <p>Although tablets can rotate to operate in any orientation, they are often designed for 625 landscape orientation and that is how most users will use them. So, you should ensure that your 626 application can function in landscape. Even if you want to avoid rotating the screen while your 627 application is running, you should not assume that portrait is the device's default orientation. You 628 should either ensure that your layout is usable in both portrait and landscape orientations or 629 provide an <a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources" 630 >alternative layout resource</a> for landscape orientation.</p> 631 632 <p>If you believe your application or game provides its best experience when the screen is tall, 633 consider that tablets and similar devices have a screen that's as tall or taller in landscape 634 orientation than a phone in portrait orientation. With that in mind, you might be able to add a 635 landscape design that adds padding or extra landscape scenery on the left and right sides, so 636 the primary screen space still remains taller than it is wide.</p> 637 638 <p>Ideally, your application should handle all orientation changes instead of locking into one 639 orientation. When the user rotates the screen, the system restarts the current activity by calling 640 {@link android.app.Activity#onDestroy onDestroy()} and {@link android.app.Activity#onCreate 641 onCreate()}) in immediate succession. You should design your activity to account for these changes 642 in the lifecycle, so the activity can save and restore its state. You can learn about the 643 necessary lifecycle callback methods and how to save and restore the activity state in the <a 644 href="{@docRoot}guide/components/activities.html#Lifecycle">Activities</a> 645 document. If your activity state is more complex and cannot retain it using the normal 646 lifecycle callback methods, you can use alternative techniques described in <a 647 href="{@docRoot}guide/topics/resources/runtime-changes.html">Handling Runtime Changes</a>.</p> 648 649 <p>In the worst-case scenario, however, you can avoid orientation changes by using the <a 650 href="{@docRoot}guide/topics/manifest/activity-element.html#screen">{@code 651 android:screenOrientation}</a> attribute in the <a 652 href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> 653 element. Instead of locking the orientation in landscape or portrait, however, you should 654 specify a value of {@code "nosensor"}. This way, your activity uses whatever orientation the 655 device specifies as its natural orientation and the screen will not rotate. You should still 656 avoid using the <a 657 href="{@docRoot}guide/topics/manifest/activity-element.html#screen">{@code 658 android:screenOrientation}</a> attribute, but because it's sometimes necessary to lock the 659 screen into one orientation, it's best if you do so in a way that uses the device's natural 660 orientation instead of assuming one specific orientation.</p> 661 662 <p>If your application uses the orientation sensors, such as the accelerometer (with the {@link 663 android.hardware.SensorManager} APIs), also be aware that the landscape screen can also cause 664 problems, due to false assumptions about which orientation is the natural position. For more 665 information about how you should properly handle rotation changes when using the orientation 666 sensors, read the blog post, <a 667 href="http://android-developers.blogspot.com/2010/09/one-screen-turn-deserves-another.html">One 668 Screen Turn Deserves Another</a>.</p> 669 670 671 672 <h3 id="Telephony">Using telephony or other variable features</h3> 673 674 <p>Tablets and similar devices might not include support for telephony, so they can't make 675 traditional phone calls or handle SMS. Some devices might also omit 676 other hardware features, such as Bluetooth. If your application uses these features, then your 677 manifest file probably already includes (or should include) a declaration of the feature with the <a 678 href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a> 679 element. Doing so prevents devices that do not declare support for the feature from downloading 680 your applications. For example:</p> 681 682 <pre><uses-feature android:name="android.hardware.telephony" /></pre> 683 684 <p>By default, this declares that your application <em>requires</em> telephony features. So, 685 external services such as Google Play use this information to filter your application from 686 devices that do not offer telephony.</p> 687 688 <p>If, however, your application uses, but does not require the feature, you should 689 add to this element, {@code android:required="false"}. For example:</p> 690 691 <pre><uses-feature android:name="android.hardware.telephony" android:required="false" /></pre> 692 693 <p>This indicates that your application uses the feature, but is still functional if the feature is 694 not available. So, it should still be available to devices that don't provide telephony hardware 695 (or telephony features), such as tablets.</p> 696 697 <p>Then in your application code, you must gracefully disable the features that use telephony 698 when it's not available. You can check whether the feature is available using {@link 699 android.content.pm.PackageManager#hasSystemFeature PackageManager.hasSystemFeature()}. For 700 example:</p> 701 702 <pre> 703 PackageManager pm = getPackageManager(); 704 boolean hasTelephony = pm.hasSystemFeature(PackageManager.FEATURE_TELEPHONY); 705 </pre> 706 707 <p>For more information about these 708 issues and how to future-proof your application for different hardware, read the blog post <a 709 href="http://android-developers.blogspot.com/2010/10/five-steps-to-future-hardware-happiness.html"> 710 The Five Steps to Future Hardware Happiness</a>.</p>