Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge "docs: update getting started doc for 3.0; move out of preview docs" into honeycomb

Browse Source
This commit is contained in:
Scott Main
2011-02-18 10:26:41 -08:00
committed by Android (Google) Code Review
parent a58f58daf9 adaf5a7097
commit 163413f436
4 changed files with 411 additions and 303 deletions
Download Patch File Download Diff File Expand all files Collapse all files

397
docs/html/sdk/android-3.0-optimize.jd Normal file
View File

@@ -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&mdash;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&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 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 &lt;uses-sdk&gt;}</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>
&lt;manifest ... >
&lt;uses-sdk android:minSdkVersion="4"
android:targetSdkVersion="11" /&gt;
&lt;application ... >
...
&lt;application>
&lt;/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>
&lt;manifest ... >
&lt;uses-sdk android:minSdkVersion="11" /&gt;
&lt;application ... >
...
&lt;application>
&lt;/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&mdash;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 &lt;application&gt;}</a>
element or for individual <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code
&lt;activity&gt;}</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
&lt;supports-screens&gt;}</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>
&lt;manifest ... >
...
&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 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>&lt;sdk_root&gt;/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>

6
docs/html/sdk/android-3.0.jd
View File

@@ -25,7 +25,7 @@ Differences Report &raquo;</a> </li>
<h2>See Also</h2>
<ol>
<li><a href="{@docRoot}sdk/preview/start.html">Getting Started</a></li>
<li><a href="{@docRoot}sdk/android-3.0-optimize.html">Optimizing Apps for Android 3.0</a></li>
</ol>
</div>
@@ -48,6 +48,10 @@ href="{@docRoot}sdk/index.html">download the SDK Starter Package</a> first.</p>
href="{@docRoot}sdk/android-{@sdkPlatformVersion}-highlights.html">Platform
Highlights</a>.</p>
<p>Also see the <a href="{@docRoot}sdk/android-3.0-optimize.html">Optimizing Apps for Android
3.0</a> document for information about how to optimize your existing applications for Android 3.0
devices, even if you want to remain compatible with previous versions.</p>
<h2 id="relnotes">Revisions</h2>

294
docs/html/sdk/preview/start.jd
View File

@@ -1,294 +0,0 @@
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/HoneycombGallery/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>

17
docs/html/sdk/sdk_toc.cs
View File

@@ -80,6 +80,7 @@ class="new">new!</span></li>
<div><a href="<?cs var:toroot ?>sdk/android-3.0.html">
<span class="en">Android 3.0 Platform</span></a> <span class="new">new!</span></div>
<ul>
<li><a href="<?cs var:toroot ?>sdk/android-3.0-optimize.html">Optimizing Apps for 3.0</a></li>
<li><a href="<?cs var:toroot ?>sdk/android-3.0-highlights.html">Platform Highlights</a></li>
<li><a href="<?cs var:toroot ?>sdk/api_diff/11/changes.html">API Differences Report &raquo;</a></li>
</ul>
@@ -88,10 +89,17 @@ class="new">new!</span></li>
<div><a href="<?cs var:toroot ?>sdk/android-2.3.3.html">
<span class="en">Android 2.3.3 Platform</span></a> <span class="new">new!</span></div>
<ul>
<li><a href="<?cs var:toroot ?>sdk/android-2.3-highlights.html">Platform Highlights</a></li>
<li><a href="<?cs var:toroot ?>sdk/api_diff/10/changes.html">API Differences Report &raquo;</a></li>
</ul>
</li>
<li class="toggle-list">
<div><a href="<?cs var:toroot ?>sdk/android-2.3.html">
<span class="en">Android 2.3 Platform</span></a></div>
<ul>
<li><a href="<?cs var:toroot ?>sdk/android-2.3-highlights.html">Platform Highlights</a></li>
<li><a href="<?cs var:toroot ?>sdk/api_diff/9/changes.html">API Differences Report &raquo;</a></li>
</ul>
</li>
<li><a href="<?cs var:toroot ?>sdk/android-2.2.html">Android 2.2 Platform</a></li>
<li><a href="<?cs var:toroot ?>sdk/android-2.1.html">Android 2.1 Platform</a></li>
<li><a href="<?cs var:toroot ?>sdk/android-1.6.html">Android 1.6 Platform</a></li>
@@ -99,13 +107,6 @@ class="new">new!</span></li>
<li class="toggle-list">
<div><a href="#" onclick="toggle(this.parentNode.parentNode,true); return false;">Older Platforms</a></div>
<ul>
<li class="toggle-list">
<div><a href="<?cs var:toroot ?>sdk/android-2.3.html">
<span class="en">Android 2.3 Platform</span></a></div>
<ul>
<li><a href="<?cs var:toroot ?>sdk/api_diff/9/changes.html">API Differences Report &raquo;</a></li>
</ul>
</li>
<li><a href="<?cs var:toroot ?>sdk/android-2.0.1.html">Android 2.0.1 Platform</a></li>
<li><a href="<?cs var:toroot ?>sdk/android-2.0.html">Android 2.0 Platform</a></li>
<li><a href="<?cs var:toroot ?>sdk/android-1.1.html">Android 1.1 Platform</a></li>