From adaf5a70970c7f4bc972ef35b790d4eaf1534df8 Mon Sep 17 00:00:00 2001 From: Scott Main Date: Wed, 16 Feb 2011 15:52:38 -0800 Subject: [PATCH] docs: update getting started doc for 3.0; move out of preview docs Change-Id: Ibf6f001eca76ebff2f3be1f38691dbd33220a33e --- docs/html/sdk/android-3.0-optimize.jd | 397 ++++++++++++++++++++++++++ docs/html/sdk/android-3.0.jd | 6 +- docs/html/sdk/preview/start.jd | 294 ------------------- docs/html/sdk/sdk_toc.cs | 17 +- 4 files changed, 411 insertions(+), 303 deletions(-) create mode 100644 docs/html/sdk/android-3.0-optimize.jd delete mode 100644 docs/html/sdk/preview/start.jd 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 0000000000000..a22e69af2076a --- /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 + +
+ +
+ +

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.

+ +

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.

+ + +

To get started:

+ +
    +
  1. Set up your SDK with Android 3.0.
    2. +
  2. Then choose to either optimize or upgrade: +
      +
    1. Optimize Your App for Tablets and Similar Devices. +

      When you have an existing application and want to maintain compatibility with +older versions of Android.

      +
      2. +
    2. Upgrade or Develop a New App for Tablets and Similar Devices. +

      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.

      3. +
    +
    3. +
+ + +

Set Up Your SDK with Android 3.0

+ +

To start testing and developing your application on Android 3.0, set up your existing Android +SDK with the new platform:

+ +

(If you don't have an existing Android SDK, download the +SDK starter package now.)

+ +
    +
  1. Launch the Android SDK and AVD +Manager and install the following: +
      +
    • SDK Platform Android 3.0
      • +
    • Android SDK Tools, revision 10
      • +
    • Android SDK Platform-tools, revision 3
      • +
    • Documentation for Android SDK, API 11
      • +
    • Samples for SDK API 11
      • +
    +
    2. +
  2. Create an AVD for a tablet-type +device: +

    Set the target to "Android 3.0" and the skin to "WXGA" (the default skin).

    3. +
+ + +

About emulator performance

+ +

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.

+ +

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.

+ +

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.

+ +

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.

+ +

Tip: 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 Enable snapshots). Then, start the AVD from the AVD manager and check Launch +from snapshot and Save to snapshot. 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 Save to +snapshot after you've acquired an initial snapshot (after you close the AVD for the first +time).

+ + + +

Optimize Your Application for Tablets and Similar Devices

+ +

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 {@code +android:minSdkVersion}).

+ +

Note: All Android applications are forward-compatible, so +there's nothing you have to 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.

+ +

Here are a few things you can do to optimize your application for devices running Android +3.0:

+ +
    +
  1. Test your current application on Android 3.0 +
      +
    1. Build your application as-is and install it on your Android 3.0 AVD (created above during +setup).
      2. +
    2. Perform your usual tests to be sure everything works and looks as expected.
      3. +
    +
    2. + +
  2. Apply the new "holographic" theme to your application +
      +
    1. Open your manifest file and update the {@code <uses-sdk>} element to +set {@code +android:targetSdkVersion} to {@code "11"}. For example: +
      +<manifest ... >
+    <uses-sdk android:minSdkVersion="4" 
+              android:targetSdkVersion="11" />
+    <application ... >
+        ...
+    <application>
+</manifest>
+
      +

      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.

      +

      Additionally, the holographic theme enables the Action Bar 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.

      +
      2. +
    2. Continue to build your application against the minimum version specified by {@code android:minSdkVersion}, +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. +

      Note: If you have applied other themes directly to your +activities, they will override the inherited holographic theme. To resolve this, you can use +the system +version qualifier to provide an alternative theme for Android 3.0 devices that's based on the +holographic theme. For more information, read how to select a theme based on platform +version.

      +
    +
    3. + +
  3. Supply alternative layout resources for xlarge screens +

    By providing alternative +resources when running on extra large screens (using the xlarge resource +qualifier), you can improve the user experience of your application on tablet-type devices without +using new APIs.

    +

    For example, here are some things to consider when creating a new layout for extra large +screens:

    +
      +
    • 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.

      You can specify landscape resources with the land resource +qualifier, but if you want alternative resources for an extra large landscape screen, you +should use both xlarge and land qualifiers. For example, {@code +res/layout-xlarge-land/}. The order of the qualifier names is important; see +Providing Alternative Resources for more information.

      • +
    • Button position: Consider whether the position of the most common buttons in your UI are +easily accessible while holding a tablet with two hands.
      • +
    • 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 xlarge configurations.
      • +
    +

    In general, always be sure that your application follows the Best Practices +for Screen Independence.

    +
    4. +
+ + + + + +

Upgrade or Develop a New App for Tablets and Similar Devices

+ +

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.

+ + +

Declare the minimum system version

+ +

The first thing to do when you create a project for Android 3.0 is set your manifest's {@code android:minSdkVersion} +to {@code "11"}. For example:

+ +
+<manifest ... >
+    <uses-sdk android:minSdkVersion="11" />
+    <application ... >
+        ...
+    <application>
+</manifest>
+
+ +

By targeting the Android 3.0 platform, the system automatically applies the new holographic theme +to each of your activities.

+ +

Additionally, the holographic theme enables the Action Bar for each activity.

+ + +

Use the Action Bar

+ +

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.

+ +

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 menu resource. 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.

+ +

For more information, read Using the +Action Bar.

+ + + +

Divide your activities into fragments

+ +

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.

+ +

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.

+ +

For more information, read the Fragments document.

+ + +

Use new animation APIs for transitions

+ +

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.

+ +

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.

+ +

For more information, read the Property Animation document.

+ + +

Enable hardware acceleration

+ +

You can now enable the OpenGL renderer for your application by setting {@code +android:hardwareAccelerated="true"} in your manifest's {@code <application>} +element or for individual {@code +<activity>} 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.

+ + +

Enhance your app widgets

+ +

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}.

+ +

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.

+ + +

Add other new features

+ +

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.

+ +

To learn more about the APIs mentioned above and more, see the Android 3.0 Platform document.

+ + +

Publish your app for extra large screens

+ +

You should also decide whether your application is only for +tablet-type devices (specifically, xlarge devices) or for all types of screen sizes.

+ +

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 {@code +android:minSdkVersion} set to {@code "4"} or higher will resize to fit any screen size.

+ +

If your application is only for xlarge screens, include the {@code +<supports-screens>} element in your manifest and declare that the application supports +only xlarge screens, by declaring all other sizes {@code "false"}. For example:

+ +
+<manifest ... >
+    ...
+    <supports-screens android:smallScreens="false"
+                      android:normalScreens="false"
+                      android:largeScreens="false"
+                      android:xlargeScreens="true" />
+    <application ... >
+        ...
+    <application>
+</manifest>
+
+ +

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.

+ + + +

Look at some samples

+ +

Many of the new features and APIs that are described in the Android 3.0 Platform Preview 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 <sdk_root>/samples/android-11/. The links below can help you +find samples for the features you are interested in:

+ + + diff --git a/docs/html/sdk/android-3.0.jd b/docs/html/sdk/android-3.0.jd index 8088e32e3227b..6c88146d7c846 100644 --- a/docs/html/sdk/android-3.0.jd +++ b/docs/html/sdk/android-3.0.jd @@ -25,7 +25,7 @@ Differences Report »

See Also

    -
  1. Getting Started
    2. +
  2. Optimizing Apps for Android 3.0
@@ -48,6 +48,10 @@ href="{@docRoot}sdk/index.html">download the SDK Starter Package first.

href="{@docRoot}sdk/android-{@sdkPlatformVersion}-highlights.html">Platform Highlights.

+

Also see the Optimizing Apps for Android +3.0 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.

+

Revisions

diff --git a/docs/html/sdk/preview/start.jd b/docs/html/sdk/preview/start.jd deleted file mode 100644 index d6e442e46bd95..0000000000000 --- a/docs/html/sdk/preview/start.jd +++ /dev/null @@ -1,294 +0,0 @@ -page.title=Getting Started with the Android 3.0 Preview -@jd:body - -

Welcome to Android 3.0!

- -

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.

- -

Be aware that:

- - - - -

How do I start?

- -
    -
  1. Set up the preview SDK
    2. -
  2. Then choose your app adventure: -
      -
    1. Optimize Your App for Tablets and Similar Devices -

      When you have an existing application and you want to maintain compatibility with -older versions of Android.

      -
      2. -
    2. Upgrade or Develop a New App for Tablets and Similar Devices -

      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.

      3. -
    -
    3. -
- -

Code samples

-

Many of the new features and APIs that are described in the -Android 3.0 Platform Preview 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 <sdk_root>/samples/android-Honeycomb. The list of links -below helps you find samples for the features you are interested in:

- - - -

Set Up the Preview SDK

- -

To start using the Android 3.0 preview SDK, set up your existing Android SDK with the new -platform:

-

(If you don't have an existing SDK, download it -now.)

-
    -
  1. Launch the Android SDK and AVD -Manager and install the following: -
      -
    • SDK Platform Android 3.0 Preview
      • -
    • Android SDK Tools, revision 9
      • -
    • Documentation for Android 'Honeycomb' Preview
      • -
    • Samples for SDK API Honeycomb Preview
      • -
    -
    2. -
  2. Create an AVD for tablets: set -the target to "Android 3.0 (Preview)" and the skin to "WXGA".
    3. -
- - -

About emulator performance

- -

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.

- -

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.

- -

Note that you do not need to do a full boot of your emulator each time you -rebuild your application — 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.

- -

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.

- -

Tip: 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 Launch from snapshot and Save to -snapshot. 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 Save to -snapshot only for the first time you launch the AVD.

- - -

Known issues

- -

The following known issues occur for Android 3.0 AVDs that are loaded in the emulator:

- - - - -

Optimize Your Application for Tablets and Similar Devices

- -

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}).

- -

Note: All Android applications are forward-compatible, so -there's nothing you have to 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 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.

- -

Here's what you can do to optimize your application for tablets running Android -3.0:

- -
    -
  1. Test your current application on Android 3.0 -
      -
    1. Build your application as-is and install it on your WXGA AVD (created above).
      2. -
    2. Perform your usual tests to be sure everything works and looks as expected.
      3. -
    -
    2. - -
  2. Apply the new "holographic" theme to your application -
      -
    1. Open your manifest file and update the {@code <uses-sdk>} element to -set {@code android:targetSdkVersion} to {@code "Honeycomb"}. For example: -
      -<manifest ... >
-    <uses-sdk android:minSdkVersion="4" 
-              android:targetSdkVersion="Honeycomb" />
-    <application ... >
-        ...
-    <application>
-</manifest>
-
      -

      Note: The API Level value "Honeycomb" is a provisional API -Level that is valid only while testing against the preview SDK. You -should not 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 Android API Levels.

      -

      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.

      -
      2. -
    2. 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. -

      Note: 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 system -version qualifier to provide an alternative theme that's based on the Holographic theme when -your application is running on Android 3.0.

      -
    -
    3. - -
  3. Supply alternative layout resources for xlarge screens -

    As discussed in the guide to Supporting Multiple Screens, Android -2.3 and above support the xlarge resource qualifier, which you should use to supply -alternative layouts for extra large screens.

    -

    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.

    -

    For example, here are some things to consider when creating a new layout for tables:

    -
      -
    • 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.
      • -
    • Button position: Consider whether the position of the most common buttons in your UI are -easily accessible while holding a tablet with two hands.
      • -
    -
    4. -
- -

In general, always be sure that your application follows the Best Practices -for Screen Independence.

- - -

Upgrade or Develop a New App for Tablets and Similar Devices

- -

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.

- -

The first thing to do when you create a project with the Android 3.0 preview is set the {@code <uses-sdk>} element to -use {@code "Honeycomb"} for the {@code android:minSdkVersion}. For example:

- -
-<manifest ... >
-    <uses-sdk android:minSdkVersion="Honeycomb" />
-    <application ... >
-        ...
-    <application>
-</manifest>
-
- -

Note: The API Level value "Honeycomb" is a provisional API -Level that is valid only while building and testing against the preview SDK. You -cannot 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 Android API Levels.

- -

Be sure that the {@code -<uses-sdk>} element appears before the {@code <application>} -element.

- -

By targeting the Android 3.0 platform (and declaring it before {@code <application>}), -the system automatically applies the new Holographic theme to each of your -activities.

- - - -

Publishing your app for tablet-type devices only

- -

Additionally, you should decide whether your application is for only tablet devices -(specifically, xlarge devices) or for devices of all sizes that may run Android 3.0.

- -

If your application is only for tablets (xlarge screens; not for mobile -devices/phones), then you should include the {@code -<supports-screens>} element in your manifest with all sizes except for xlarge declared -false. For example:

- -
-<manifest ... >
-    <uses-sdk android:minSdkVersion="Honeycomb" />
-    <supports-screens android:smallScreens="false"
-                      android:normalScreens="false"
-                      android:largeScreens="false"
-                      android:xlargeScreens="true" />
-    <application ... >
-        ...
-    <application>
-</manifest>
-
- -

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.

- -

Otherwise, if you want your application to be available to both small devices (phones) and large -devices (tablets), do not include the {@code -<supports-screens>} element.

- -
-

To learn more about some of the new APIs, -see the Android 3.0 Platform Preview document.

-
diff --git a/docs/html/sdk/sdk_toc.cs b/docs/html/sdk/sdk_toc.cs index 1b94b2cc4d598..c1894d89c393f 100644 --- a/docs/html/sdk/sdk_toc.cs +++ b/docs/html/sdk/sdk_toc.cs @@ -80,6 +80,7 @@ class="new">new!
Android 3.0 Platform new!
@@ -88,10 +89,17 @@ class="new">new!
Android 2.3.3 Platform new!
+
  • +
    + Android 2.3 Platform
    + +
  • Android 2.2 Platform
  • Android 2.1 Platform
  • Android 1.6 Platform
    • @@ -99,13 +107,6 @@ class="new">new!
  • Older Platforms