android_frameworks_base/docs/html/sdk/preview/start.jd

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&mdash;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&mdash;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>&lt;sdk_root&gt;/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 &mdash; 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&mdash;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 &lt;uses-sdk&gt;}</a> element to
set {@code android:targetSdkVersion} to {@code "Honeycomb"}. For example:
<pre>
&lt;manifest ... >
    &lt;uses-sdk android:minSdkVersion="4" 
              android:targetSdkVersion="Honeycomb" /&gt;
    &lt;application ... >
        ...
    &lt;application>
&lt;/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 &lt;uses-sdk&gt;}</a> element to
use {@code "Honeycomb"} for the {@code android:minSdkVersion}. For example:</p>

<pre>
&lt;manifest ... >
    &lt;uses-sdk android:minSdkVersion="Honeycomb" /&gt;
    &lt;application ... >
        ...
    &lt;application>
&lt;/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
&lt;uses-sdk&gt;}</a> element appears <strong>before</strong> the <a
href="{@docRoot}guide/topics/manifest/application-element.html">{@code &lt;application&gt;}</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 &lt;application&gt;}</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
&lt;supports-screens&gt;}</a> element in your manifest with all sizes except for xlarge declared
false. For example:</p>

<pre>
&lt;manifest ... >
    &lt;uses-sdk android:minSdkVersion="Honeycomb" /&gt;
    &lt;supports-screens android:smallScreens="false"
                      android:normalScreens="false"
                      android:largeScreens="false"
                      android:xlargeScreens="true" /&gt;
    &lt;application ... >
        ...
    &lt;application>
&lt;/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
&lt;supports-screens&gt;}</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>