path: root/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 tablet
devices. We're offering a preview SDK so you can get a head-start developing
applications for it or simply optimize your existing application for upcoming
tablets.</p>


<h3>What is the preview SDK?</h3>

<p>The Android 3.0 preview SDK is an early look at the upcoming version of Android 3.0, for
developers only.</p>

<p>The preview SDK includes:</p>
<ul>
  <li>An early Android 3.0 system image for use in the Android emulator</li>
  <li>An Android 3.0 library with non-final APIs</li>
  <li>A new WXGA emulator skin for an extra large Android Virtual Device</li>
  <li>New documentation for Android 3.0, including a complete API reference, new developer guides,
and an API differences report between Android 3.0 and 2.3.</li>
</ul>

<div class="note">
<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>
</div>



<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</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</a>
        <p>When you want to upgrade your application to use APIs introduced in Android 3.0 or
    create an all new application targeted to tablet devices.</p></li>
    </ol>
  </li>
</ol>




<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>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. Please
continue to use the emulator 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>



<h2 id="Optimize">Optimize Your Application for Tablets</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 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, we recommend that you update
your application to adapt to the new system theme and add 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</h2>

<p>If you want to develop something truly for tablets 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 tablets 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</a> document.</p>
</div>