diff options
Diffstat (limited to 'docs/html/sdk/preview/start.jd')
| -rw-r--r-- | docs/html/sdk/preview/start.jd | 294 |
1 files changed, 294 insertions, 0 deletions
diff --git a/docs/html/sdk/preview/start.jd b/docs/html/sdk/preview/start.jd new file mode 100644 index 0000000..3bf70b3 --- /dev/null +++ b/docs/html/sdk/preview/start.jd @@ -0,0 +1,294 @@ +page.title=Getting Started with the Android 3.0 Preview +@jd:body + +<p>Welcome to Android 3.0!</p> + +<p>Android 3.0 is the next major release of the Android platform and is optimized for larger screen +devices, particularly tablets. We're offering a preview SDK so you can get a head-start developing +applications for it or simply test and optimize your existing application for upcoming devices.</p> + +<p><strong>Be aware that:</strong></p> +<ul> + <li>The APIs in the preview SDK are <strong>not final</strong>. Some APIs may change in behavior +or availability when the final SDK is made available.</li> + <li>You <strong>cannot</strong> publish an application that's built against the preview +SDK—you can only run an application built against the preview SDK on the Android +emulator.</li> + <li>The documentation on <a href="http://developer.android.com">developer.android.com</a> +does <strong>not</strong> include the Android 3.0 documentation—to read the API reference and +developer guides for Android 3.0, you must install the Android 3.0 preview documentation from +the AVD and SDK Manager.</li> +</ul> + + + +<h3>How do I start?</h3> + +<ol> + <li><a href="#Setup">Set up the preview SDK</a></li> + <li>Then choose your app adventure: + <ol type="a"> + <li><a href="#Optimize">Optimize Your App for Tablets and Similar Devices</a> + <p>When you have an existing application and you want to maintain compatibility with +older versions of Android.</p> + </li> + <li><a href="#Upgrade">Upgrade or Develop a New App for Tablets and Similar Devices</a> + <p>When 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.</p></li> + </ol> + </li> +</ol> + +<h3>Code samples</h3> +<p>Many of the new features and APIs that are described in the <a href="{@docRoot}sdk/android-3.0.html#api"> +Android 3.0 Platform Preview</a> also have accompanying samples that help you understand how to use them. +To get the samples, download them from the SDK repository using the Android SDK Manager. After download +the samples are located in <code><sdk_root>/samples/android-Honeycomb</code>. The list of links +below helps you find samples for the features you are interested in:</p> +<ul> + <li><a href="{@docRoot}resources/samples/Honeycomb-Gallery/index.html">Honeycomb Gallery</a> - + A demo application highlighting how to use some of the new APIs in Honeycomb, including fragments, the action bar, + drag and drop, transition animations, and a stack widget.</li> + <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/index.html#Fragment">Fragments</a> + <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/ActionBarMechanics.html">Action Bar</a></li> + <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/content/ClipboardSample.html">Clipboard</a></li> + <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/DragAndDropDemo.html">Drag and Drop</a></li> + <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/List15.html"> + Multiple-choice selection for ListView and GridView</a></li> + <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LoaderThrottle.html">Content Loaders</a></li> + <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/animation/index.html">Property Animation</a></li> + <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/SearchViewActionBar.html">Search View Widget</a></li> + <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/PopupMenu1.html">Popup Menu Widget</a></li> +</ul> + + +<h2 id="Setup">Set Up the Preview SDK</h2> + +<p>To start using the Android 3.0 preview SDK, set up your existing Android SDK with the new +platform:</p> +<p>(If you don't have an existing SDK, <a href="{@docRoot}sdk/index.html">download it +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 Preview</li> + <li>Android SDK Tools, revision 9</li> + <li>Documentation for Android 'Honeycomb' Preview</li> + <li>Samples for SDK API Honeycomb Preview</li> + </ul> + </li> + <li><a href="{@docRoot}guide/developing/other-ide.html#AVD">Create an AVD</a> for tablets: set +the target to "Android 3.0 (Preview)" and the skin to "WXGA".</li> +</ol> + + +<h3>About emulator performance</h3> + +<p>Because the Android emulator must simulate the ARM instruction set architecture on your +computer and the WXGA screen is significantly larger than what the emulator +normally handles, emulator performance is much slower than usual.</p> + +<p>In particular, 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 continue waiting until you see +the home screen appear. </p> + +<p>Note that you do not need to do a full boot of your emulator each time you +rebuild your application — typically you only need to boot at the start of +a session. See the Tips section below for information about using Snapshots to +cut startup time after first initialization. </p> + +<p>We're working hard to resolve the performance issues and it will improve in future releases. +Unfortunately, the emulator will perform slowly during your trial with the preview SDK. For the time +being, 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 GUI). Then, start the AVD from the 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 enable <b>Save to +snapshot</b> only for the first time you launch the AVD.</p> + + +<h3>Known issues</h3> + +<p>The following known issues occur for Android 3.0 AVDs that are loaded in the emulator:</p> + <ul> + <li>You cannot take screenshots of an emulator screen. The Device Screen + Capture window displays <strong>Screen not available</strong>.</li> + <li>The emulator cannot receive incoming SMS messages.</li> + <li>GPS emulation is currently not supported.</li> + <li>When rotating the emulator screen by pressing Ctrl-F11, the screen turns green momentarily, +then displays the normal interface.</li> + <li>In some circumstances, the emulator displays a rotated portrait screen while in landscape +mode. To view the screen correctly, rotate the emulator to portrait mode by pressing Ctrl-F11 or +turn off the auto-rotate setting in <strong>Settings > Screen > Auto-rotate screen</strong>.</li> + <li>The Dev Tools application sometimes crashes when trying to use the Package Browser +feature.</li> + <li>On Ubuntu 10.04 64-bit machines, you cannot create an AVD that has an SD card.</li> + </ul> + + + +<h2 id="Optimize">Optimize Your Application for Tablets and Similar Devices</h2> + +<p>If you've already developed an application for Android, there are a few things you can do +to optimize it for a tablet-style experience, without changing the minimum platform version required +(you don't need to change the manifest {@code minSdkVersion}).</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 running your app on an Android 3.0 tablet or similar-size device, we +recommend that you update your application to adapt to the new system theme and optimize your +application for larger screens.</p> + +<p>Here's what you can do to optimize your application for tablets 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 WXGA AVD (created above).</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 {@code android:targetSdkVersion} to {@code "Honeycomb"}. For example: +<pre> +<manifest ... > + <uses-sdk android:minSdkVersion="4" + android:targetSdkVersion="Honeycomb" /> + <application ... > + ... + <application> +</manifest> +</pre> + <p class="note"><strong>Note:</strong> The API Level value "Honeycomb" is a provisional API +Level that is valid only while testing against the preview SDK. You +<strong>should not</strong> publish your application using this API Level. When the final version of +the Android 3.0 SDK is made available, you must change this value to the real API Level that will be +specified for Android 3.0. For more information, read about <a +href="{@docRoot}guide/appendix/api-levels.html">Android API Levels</a>.</p> + <p>By targeting the Android 3.0 platform, the system automatically applies the Holographic theme +to each of your activities, when running on an Android 3.0 device.</p> + </li> + <li>Continue to build against your application's {@code minSdkVersion}, but install it +on the Android 3.0 AVD. Perform more testing on your application to be sure that your user interface +works well with the Holographic theme. + <p class="note"><strong>Note:</strong> If you've applied themes to your activities already, +they will override the Holographic theme that the system applies when you set the {@code +android:targetSdkVersion} to {@code "Honeycomb"}. +Once the Android 3.0 APIs are finalized and an official API Level is assigned, you can use +the <a href="{@docRoot}guide/topics/resources/providing-resources.html#VersionQualifier">system +version qualifier</a> to provide an alternative theme that's based on the Holographic theme when +your application is running on Android 3.0.</p> + </ol> + </li> + + <li><b>Supply alternative layout resources for xlarge screens</b> + <p>As discussed in the guide to <a +href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a>, Android +2.3 and above support the <code>xlarge</code> resource qualifier, which you should use to supply +alternative layouts for extra large screens.</p> + <p>By providing alternative layouts for some of your activities when running on extra large +screens, you can improve the user experience of your application on a tablet without using any +new APIs.</p> + <p>For example, here are some things to consider when creating a new layout for tables:</p> + <ul> + <li>Landscape layout: The "normal" orientation for tablets is usually landscape (wide), so +you should be sure that your activities offer an appropriate layout for such a wide viewing +area.</li> + <li>Button position: Consider whether the position of the most common buttons in your UI are +easily accessible while holding a tablet with two hands.</li> + </ul> + </li> +</ol> + + <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> + + +<h2 id="Upgrade">Upgrade or Develop a New App for Tablets and Similar Devices</h2> + +<p>If you want to develop something truly for tablet-type devices running Android 3.0, then you need +to use new APIs available in Android 3.0. This section introduces some of the new features that you +should use.</p> + +<p>The first thing to do when you create a project with the Android 3.0 preview is set the <a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code <uses-sdk>}</a> element to +use {@code "Honeycomb"} for the {@code android:minSdkVersion}. For example:</p> + +<pre> +<manifest ... > + <uses-sdk android:minSdkVersion="Honeycomb" /> + <application ... > + ... + <application> +</manifest> +</pre> + +<p class="note"><strong>Note:</strong> The API Level value "Honeycomb" is a provisional API +Level that is valid only while building and testing against the preview SDK. You +<strong>cannot</strong> publish your application using this API Level. When the final version of the +Android 3.0 SDK is made available, you must change this value to the real API Level that is +specified for Android 3.0. For more information, read about <a +href="{@docRoot}guide/appendix/api-levels.html">Android API Levels</a>.</p> + +<p>Be sure that the <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code +<uses-sdk>}</a> element appears <strong>before</strong> the <a +href="{@docRoot}guide/topics/manifest/application-element.html">{@code <application>}</a> +element.</p> + +<p>By targeting the Android 3.0 platform (and declaring it before <a +href="{@docRoot}guide/topics/manifest/application-element.html">{@code <application>}</a>), +the system automatically applies the new Holographic theme to each of your +activities.</p> + + + +<h3>Publishing your app for tablet-type devices only</h3> + +<p>Additionally, you should decide whether your application is for <em>only</em> tablet devices +(specifically, <em>xlarge</em> devices) or for devices of all sizes that may run Android 3.0.</p> + +<p>If your application is <em>only</em> for tablets (<em>xlarge</em> screens; not for mobile +devices/phones), then you should include the <a +href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code +<supports-screens>}</a> element in your manifest with all sizes except for xlarge declared +false. For example:</p> + +<pre> +<manifest ... > + <uses-sdk android:minSdkVersion="Honeycomb" /> + <supports-screens android:smallScreens="false" + android:normalScreens="false" + android:largeScreens="false" + android:xlargeScreens="true" /> + <application ... > + ... + <application> +</manifest> +</pre> + +<p>With this declaration, you indicate that your application does not support any screen size except +extra large. External services such as Android Market may use this to filter your application +from devices that do not have an extra large screen.</p> + +<p>Otherwise, if you want your application to be available to both small devices (phones) and large +devices (tablets), do <em>not</em> include the <a +href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code +<supports-screens>}</a> element.</p> + +<div class="special"> +<p>To learn more about some of the new APIs, +see the <a href="{@docRoot}sdk/android-3.0.html">Android 3.0 Platform Preview</a> document.</p> +</div> |