docs: add getting started doc and version notes for HC preview

Change-Id: Ia969c54a9b57197fb0f8814cc1898e50c02608e0

1 files changed, 265 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..7e816c1
--- /dev/null
+++ b/docs/html/sdk/preview/start.jd
@@ -0,0 +1,265 @@
+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>