docs: update getting started doc for 3.0; move out of preview docs
Change-Id: Ibf6f001eca76ebff2f3be1f38691dbd33220a33e
diff --git a/docs/html/sdk/android-3.0-optimize.jd b/docs/html/sdk/android-3.0-optimize.jd
new file mode 100644
index 0000000..a22e69a
--- /dev/null
+++ b/docs/html/sdk/android-3.0-optimize.jd
@@ -0,0 +1,397 @@
+page.title=Optimizing Apps for Android 3.0
+@jd:body
+
+<div id="qv-wrapper">
+<div id="qv">
+<h2>In this document</h2>
+<ol>
+<li><a href="#Setup">Set Up Your SDK with Android 3.0</a></li>
+<li><a href="#SearchableConfiguration">Optimize Your App for Tablets and Similar Devices</a></li>
+<li><a href="#SearchableActivity">Upgrade or Develop a New App for Tablets and Similar
+Devices</a></li>
+</ol>
+
+</div>
+</div>
+
+<p>If you're developing an Android application, Android 3.0 introduces several features that allow
+you to enhance your user's experience on tablets and similar devices. Any application you've already
+published is compatible with devices running Android 3.0, by default, because Android applications
+are forward-compatible. However, there are some simple changes you should make to optimize your
+application for tablet-type devices.</p>
+
+<p>This document shows how you can optimize your existing application for Android 3.0 and
+maintain compatibility with older versions or upgrade your application completely with new APIs.</p>
+
+
+<p><b>To get started:</b></p>
+
+<ol>
+ <li><a href="#Setup">Set up your SDK with Android 3.0</a>.</li>
+ <li>Then choose to either optimize or upgrade:
+ <ol type="a">
+ <li><a href="#Optimize">Optimize Your App for Tablets and Similar Devices</a>.
+ <p>When you have an existing application and 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>
+
+
+<h2 id="Setup">Set Up Your SDK with Android 3.0</h2>
+
+<p>To start testing and developing your application on Android 3.0, set up your existing Android
+SDK with the new platform:</p>
+
+<p>(If you don't have an existing Android SDK, <a href="{@docRoot}sdk/index.html">download the
+SDK starter package 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</li>
+ <li>Android SDK Tools, revision 10</li>
+ <li>Android SDK Platform-tools, revision 3</li>
+ <li>Documentation for Android SDK, API 11</li>
+ <li>Samples for SDK API 11</li>
+ </ul>
+ </li>
+ <li><a href="{@docRoot}guide/developing/other-ide.html#AVD">Create an AVD</a> for a tablet-type
+device:
+ <p>Set the target to "Android 3.0" and the skin to "WXGA" (the default skin).</p></li>
+</ol>
+
+
+<h3>About emulator performance</h3>
+
+<p>Because the Android emulator must simulate the ARM instruction set on your computer
+and the WXGA screen is significantly larger than a typical virtual device, emulator performance is
+much slower than a real device.</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 wait until you see the home screen (or lock screen) appear. </p>
+
+<p>However, you don't need to boot the emulator each time you rebuild your
+application—typically you only need to boot at the start of a session and keep it running.
+Also see the tip below for information about using a snapshot to drastically reduce startup time
+after the first initialization. </p>
+
+<p>We're working hard to resolve the performance issues and it will improve in future tools
+releases. For the time being, the emulator is still best way to evaluate your application's
+appearance and functionality on Android 3.0 without a real device.</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 AVD creator
+to <strong>Enable</strong> snapshots). Then, start the AVD from the AVD 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 disable <b>Save to
+snapshot</b> after you've acquired an initial snapshot (after you close the AVD for the first
+time).</p>
+
+
+
+<h2 id="Optimize">Optimize Your Application for Tablets and Similar Devices</h2>
+
+<p>If you've already developed an application for an earlier version of Android, there are a few
+things you can do to optimize it for a tablet-style experience on Android 3.0 without changing the
+minimum version required (you don't need to change your manifest's <a
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code
+android:minSdkVersion}</a>).</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 using your app on an Android 3.0 tablet or similar-size device, you
+should update your application to inherit the new system theme and provide some optimizations for
+larger screens.</p>
+
+<p>Here are a few things you can do to optimize your application for devices 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 Android 3.0 AVD (created above during
+<a href="#Setup">setup</a>).</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 <a
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code
+android:targetSdkVersion}</a> to {@code "11"}. For example:
+<pre>
+<manifest ... >
+ <uses-sdk android:minSdkVersion="4"
+ android:targetSdkVersion="11" />
+ <application ... >
+ ...
+ <application>
+</manifest>
+</pre>
+ <p>By targeting the Android 3.0 platform, the system automatically applies the holographic theme
+to each activity when your application runs on an Android 3.0 device. The holographic theme
+provides a new design for widgets, such as buttons and text boxes, and restyles other
+visual elements. This is the standard theme in applications built for Android 3.0, so your
+application will look more at home by enabling the theme.</p>
+ <p>Additionally, the holographic theme enables the <a
+href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> in your activities when running on an
+Android 3.0 device. The Action Bar replaces the traditional title bar at the top of the activity
+window and provides the user access to the activity's Options Menu.</p>
+ </li>
+ <li>Continue to build your application against the minimum version specified by <a
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a>,
+but install it on the Android 3.0 AVD. Repeat your tests to be sure that your user interface works
+well with the holographic theme.
+ <p class="note"><strong>Note:</strong> If you have applied other themes directly to your
+activities, they will override the inherited holographic theme. To resolve this, you can use
+the <a href="{@docRoot}guide/topics/resources/providing-resources.html#VersionQualifier">system
+version qualifier</a> to provide an alternative theme for Android 3.0 devices that's based on the
+holographic theme. For more information, read how to <a
+href="{@docRoot}guide/topics/ui/themes.html#SelectATheme">select a theme based on platform
+version</a>.</p>
+ </ol>
+ </li>
+
+ <li><b>Supply alternative layout resources for xlarge screens</b>
+ <p>By providing <a
+href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">alternative
+resources</a> when running on extra large screens (using the <code>xlarge</code> resource
+qualifier), you can improve the user experience of your application on tablet-type devices without
+using new APIs.</p>
+ <p>For example, here are some things to consider when creating a new layout for extra large
+screens:</p>
+ <ul>
+ <li>Landscape layout: The "normal" orientation for tablet-type devices is usually landscape
+(wide), so you should be sure that your activities offer a layout that's optimized for a wide
+viewing area. <p>You can specify landscape resources with the <code>land</code> resource
+qualifier, but if you want alternative resources for an extra large landscape screen, you
+should use both <code>xlarge</code> and <code>land</code> qualifiers. For example, {@code
+res/layout-xlarge-land/}. The order of the qualifier names is important; see <a
+href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">
+Providing Alternative Resources</a> for more information.</p></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>
+ <li>Font sizes: Be sure your application uses {@code sp} units when setting font
+sizes. This alone should ensure a readable experience on tablet-style devices. In some cases,
+however, you might want to consider larger font sizes for <code>xlarge</code> configurations.</li>
+ </ul>
+ <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>
+ </li>
+</ol>
+
+
+
+
+
+<h2 id="Upgrade">Upgrade or Develop a New App for Tablets and Similar Devices</h2>
+
+<p>If you want to develop an application that's fully enhanced for tablet-type devices running
+Android 3.0, then you need to use new APIs in Android 3.0. This section introduces some of
+the new features you should use.</p>
+
+
+<h3>Declare the minimum system version</h3>
+
+<p>The first thing to do when you create a project for Android 3.0 is set your manifest's <a
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a>
+to {@code "11"}. For example:</p>
+
+<pre>
+<manifest ... >
+ <uses-sdk android:minSdkVersion="11" />
+ <application ... >
+ ...
+ <application>
+</manifest>
+</pre>
+
+<p>By targeting the Android 3.0 platform, the system automatically applies the new holographic theme
+to each of your activities.</p>
+
+<p>Additionally, the holographic theme enables the Action Bar for each activity.</p>
+
+
+<h3>Use the Action Bar</h3>
+
+<p>The Action Bar is a widget for activities that replaces the traditional title bar at the top of
+the screen. By default, the Action Bar includes the application logo on the left side, followed by
+the activity title, and any available items from the Options Menu on the right side.</p>
+
+<p>You can enable items from your activity's Options Menu to appear directly in the Action Bar as
+"action items" by adding {@code showAsAction="ifRoom"} to specific items in your <a
+href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a>. You can also add
+navigation features to the Action Bar, such as tabs, and use the application icon to navigate to
+your application's "home" activity or "up" the activity hierarchy.</p>
+
+<p>For more information, read <a href="{@docRoot}guide/topics/ui/actionbar.html">Using the
+Action Bar</a>.</p>
+
+
+
+<h3>Divide your activities into fragments</h3>
+
+<p>A fragment represents a behavior or a portion of user interface in an activity. You can combine
+multiple fragments in a single activity to build a multi-pane UI and reuse a fragment in multiple
+activities. You can think of a fragment as a modular section of an activity, which has its own
+lifecycle, receives its own input events, and which you can add or remove while the activity is
+running.</p>
+
+<p>For example, a news application can use one fragment to show a list of articles on the left and
+another fragment to display an article on the right—both fragments appear in one activity,
+side by side, and each fragment has its own set of lifecycle callback methods and handles its own
+input events. Thus, instead of using one activity to select an article and another activity to
+read the article, the user can select an article and read it all within the same activity.</p>
+
+<p>For more information, read the <a
+href="{@docRoot}guide/topics/fundamentals/fragments.html">Fragments</a> document.</p>
+
+
+<h3>Use new animation APIs for transitions</h3>
+
+<p>An all new flexible animation framework allows you to animate arbitrary properties of any object
+(View, Drawable, Fragment, Object, or anything else). You can define several animation aspects
+(such as duration, repeat, interpolation, and more) for an object's int, float, and hexadecimal
+color values, by default. That is, when an object has a property field for one of these types, you
+can change its value over time to affect an animation.</p>
+
+<p>The {@link android.view.View} class also provides new APIs that leverage the new animation
+framework, allowing you to easily apply 2D and 3D transformations to views in your activity layout.
+New transformations are made possible with a set of object properties that define the view's layout
+position, orientation, transparency and more.</p>
+
+<p>For more information, read the <a
+href="{@docRoot}guide/topics/graphics/animation.html">Property Animation</a> document.</p>
+
+
+<h3>Enable hardware acceleration</h3>
+
+<p>You can now enable the OpenGL renderer for your application by setting {@code
+android:hardwareAccelerated="true"} in your manifest's <a
+href="{@docRoot}guide/topics/manifest/application-element.html">{@code <application>}</a>
+element or for individual <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code
+<activity>}</a> elements. Hardware acceleration results in smoother animations, smoother
+scrolling, and overall better performance and response to user interaction. When enabled, be sure
+that you thoroughly test your application on a device that supports hardware acceleration.</p>
+
+
+<h3>Enhance your app widgets</h3>
+
+<p>App widgets allow users to access information from your application directly from the Home
+screen and interact with ongoing services (such as preview their email and control music playback).
+Android 3.0 enhances these capabilities by enabling collections, created with widgets such as
+{@link android.widget.ListView}, {@link android.widget.GridView}, and the new {@link
+android.widget.StackView}. These widgets allow you to create more interactive app
+widgets, such as one with a scrolling list, and can automatically update their data through a {@link
+android.widget.RemoteViewsService}.</p>
+
+<p>Additionally, you should create a preview image of your app widget using the Widget Preview
+application (pre-installed in an Android 3.0 AVD) and reference it with the {@link
+android.appwidget.AppWidgetProviderInfo#previewImage android:previewImage} attribute, so that users
+can see what the app widget looks like before adding it to their Home screen.</p>
+
+
+<h3>Add other new features</h3>
+
+<p>Android 3.0 introduces many more APIs that you might find valuable for your
+application, such as drag and drop APIs, new Bluetooth APIs, a system-wide clipboard framework, a
+new graphics engine called Renderscript, and more.</p>
+
+<p>To learn more about the APIs mentioned above and more, see the <a
+href="{@docRoot}sdk/android-3.0.html">Android 3.0 Platform</a> document.</p>
+
+
+<h3>Publish your app for extra large screens</h3>
+
+<p>You should also decide whether your application is <em>only</em> for
+tablet-type devices (specifically, <em>xlarge</em> devices) or for all types of screen sizes.</p>
+
+<p>If you want your application to be available to all screen sizes (for example, for all
+phones and tablets), there's nothing you need to do. By default, an application with <a
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code
+android:minSdkVersion}</a> set to {@code "4"} or higher will resize to fit any screen size.</p>
+
+<p>If your application is <em>only</em> for <em>xlarge</em> screens, include the <a
+href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
+<supports-screens>}</a> element in your manifest and declare that the application supports
+only <em>xlarge</em> screens, by declaring all other sizes {@code "false"}. For example:</p>
+
+<pre>
+<manifest ... >
+ ...
+ <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 then use this information to filter your
+application from devices that do not have an extra large screen.</p>
+
+
+
+<h3>Look at some 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 can help you understand how to use them. To get the samples, download them from the SDK
+repository using the Android SDK Manager. After downloading the samples ("Samples for SDK API 11"),
+you can find them in <code><sdk_root>/samples/android-11/</code>. The links below can help you
+find samples for the features you are interested in:</p>
+
+<ul>
+ <li><a href="{@docRoot}resources/samples/HoneycombGallery/index.html">Honeycomb Gallery</a>:
+Demonstrates many new APIs in Android 3.0, including fragments, the action bar, drag and drop, and
+animations.</li>
+ <li><a
+href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/index.html#Fragment">
+Fragments</a>: Various samples that demonstrate fragment layouts, back stack, restoring state, and
+more.</li>
+ <li><a
+href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/ActionBarMechanics.html"
+>Action Bar</a>: Samples that demonstrate various Action Bar features, such as tabs, logos, and
+action items.</li>
+ <li><a
+href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/content/ClipboardSample.
+html">Clipboard</a>: An example of how to use the clipboard for copy and paste operations.</li>
+ <li><a
+href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/DragAndDropDemo.html">
+Drag and Drop</a>: An example of how to perform drag and drop with new View events.</li>
+ <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/List15.html">
+Multi-choice List</a>: An example of how to provide multiple-choice selection for ListView and
+GridView.</li>
+ <li><a
+href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LoaderThrottle.html">
+Content Loaders</a>: An example using new Loader APIs to asynchronously load data.</li>
+ <li><a
+href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/animation/index.html">
+Property Animation</a>: Several samples using the new animation APIs to animate object
+properties.</li>
+ <li><a
+href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/SearchViewActionBar.
+html">Search View Widget</a>: Example using the new search widget in the Action Bar (as an
+"action view").</li>
+ <li><a
+href="{@docRoot}resources/samples/Renderscript/index.html">Renderscript</a>: Contains several
+different applications that demonstrate using renderscript APIs for computations and 3D
+graphics.</li>
+</ul>
+