page.title=Android 3.0 Platform sdk.platform.version=3.0 sdk.platform.apiLevel=11 @jd:body

In this document

  1. Revisions
  2. API Overview
  3. API Level
  4. Built-in Applications
  5. Locales
  6. Emulator Skins

Reference

  1. API Differences Report »

See Also

  1. Optimizing Apps for Android 3.0

API Level: {@sdkPlatformApiLevel}

For developers, the Android {@sdkPlatformVersion} platform is available as a downloadable component for the Android SDK. The downloadable platform includes an Android library and system image, as well as a set of emulator skins and more. The downloadable platform includes no external libraries.

To get started developing or testing against Android {@sdkPlatformVersion}, use the Android SDK Manager to download the platform into your SDK. For more information, see Adding SDK Components. If you are new to Android, download the SDK Starter Package first.

For a high-level introduction to Android {@sdkPlatformVersion}, see the Platform Highlights.

Note: If you've already published an Android application, please test and optimize your application on Android 3.0 as soon as possible. You should do so to be sure your application provides the best experience possible on the latest Android-powered devices. For information about what you can do, read Optimizing Apps for Android 3.0.

Revisions

To determine what revision of the Android {@sdkPlatformVersion} platform you have installed, refer to the "Installed Packages" listing in the Android SDK and AVD Manager.

Android {@sdkPlatformVersion}, Revision 1 (February 2011)

Dependencies:

Requires SDK Tools r10 or higher.

API Overview

The sections below provide a technical overview of what's new for developers in Android 3.0, including new features and changes in the framework API since the previous version.

Fragments

A fragment is a new framework component that allows you to separate distinct elements of an activity into self-contained modules that define their own UI and lifecycle. To create a fragment, you must extend the {@link android.app.Fragment} class and implement several lifecycle callback methods, similar to an {@link android.app.Activity}. You can then combine multiple fragments in a single activity to build a multi-pane UI in which each pane manages its own lifecycle and user inputs.

You can also use a fragment without providing a UI and instead use the fragment as a worker for the activity, such as to manage the progress of a download that occurs only while the activity is running.

Additionally:

To manage the fragments in your activity, you must use the {@link android.app.FragmentManager}, which provides several APIs for interacting with fragments, such as finding fragments in the activity and popping fragments off the back stack to restore their previous state.

To perform a transaction, such as add or remove a fragment, you must create a {@link android.app.FragmentTransaction}. You can then call methods such as {@link android.app.FragmentTransaction#add add()} {@link android.app.FragmentTransaction#remove remove()}, or {@link android.app.FragmentTransaction#replace replace()}. Once you've applied all the changes you want to perform for the transaction, you must call {@link android.app.FragmentTransaction#commit commit()} and the system applies the fragment transaction to the activity.

For more information about using fragments, read the Fragments documentation. Several samples are also available in the API Demos application.

Action Bar

The Action Bar is a replacement for the traditional title bar at the top of the activity window. It includes the application logo in the left corner and provides a new interface for items in the Options Menu. Additionally, the Action Bar allows you to:

The Action Bar is standard for all applications that use the new holographic theme, which is also standard when you set either the {@code android:minSdkVersion} or {@code android:targetSdkVersion} to {@code "11"}.

For more information about the Action Bar, read the Action Bar documentation. Several samples are also available in the API Demos application.

System clipboard

Applications can now copy and paste data (beyond mere text) to and from the system-wide clipboard. Clipped data can be plain text, a URI, or an intent.

By providing the system access to the data you want the user to copy, through a content provider, the user can copy complex content (such as an image or data structure) from your application and paste it into another application that supports that type of content.

To start using the clipboard, get the global {@link android.content.ClipboardManager} object by calling {@link android.content.Context#getSystemService getSystemService(CLIPBOARD_SERVICE)}.

To copy an item to the clipboard, you need to create a new {@link android.content.ClipData} object, which holds one or more {@link android.content.ClipData.Item} objects, each describing a single entity. To create a {@link android.content.ClipData} object containing just one {@link android.content.ClipData.Item}, you can use one of the helper methods, such as {@link android.content.ClipData#newPlainText newPlainText()}, {@link android.content.ClipData#newUri newUri()}, and {@link android.content.ClipData#newIntent newIntent()}, which each return a {@link android.content.ClipData} object pre-loaded with the {@link android.content.ClipData.Item} you provide.

To add the {@link android.content.ClipData} to the clipboard, pass it to {@link android.content.ClipboardManager#setPrimaryClip setPrimaryClip()} for your instance of {@link android.content.ClipboardManager}.

You can then read a file from the clipboard (in order to paste it) by calling {@link android.content.ClipboardManager#getPrimaryClip()} on the {@link android.content.ClipboardManager}. Handling the {@link android.content.ClipData} you receive can be complicated and you need to be sure you can actually handle the data type in the clipboard before attempting to paste it.

The clipboard holds only one piece of clipped data (a {@link android.content.ClipData} object) at a time, but one {@link android.content.ClipData} can contain multiple {@link android.content.ClipData.Item}s.

For more information, read the Copy and Paste documentation. You can also see a simple implementation of copy and paste in the API Demos and a more complete implementation in the Note Pad application.

Drag and drop

New APIs simplify drag and drop operations in your application's user interface. A drag operation is the transfer of some kind of data—carried in a {@link android.content.ClipData} object—from one place to another. The start and end point for the drag operation is a {@link android.view.View}, so the APIs that directly handle the drag and drop operations are in the {@link android.view.View} class.

A drag and drop operation has a lifecycle that's defined by several drag actions—each defined by a {@link android.view.DragEvent} object—such as {@link android.view.DragEvent#ACTION_DRAG_STARTED}, {@link android.view.DragEvent#ACTION_DRAG_ENTERED}, and {@link android.view.DragEvent#ACTION_DROP}. Each view that wants to participate in a drag operation can listen for these actions.

To begin dragging content in your activity, call {@link android.view.View#startDrag startDrag()} on a {@link android.view.View}, providing a {@link android.content.ClipData} object that represents the data to drag, a {@link android.view.View.DragShadowBuilder} to facilitate the "shadow" that users see under their fingers while dragging, and an {@link java.lang.Object} that can share information about the drag object with views that may receive the object.

To accept a drag object in a {@link android.view.View} (receive the "drop"), register the view with an {@link android.view.View.OnDragListener OnDragListener} by calling {@link android.view.View#setOnDragListener setOnDragListener()}. When a drag event occurs on the view, the system calls {@link android.view.View.OnDragListener#onDrag onDrag()} for the {@link android.view.View.OnDragListener OnDragListener}, which receives a {@link android.view.DragEvent} describing the type of drag action has occurred (such as {@link android.view.DragEvent#ACTION_DRAG_STARTED}, {@link android.view.DragEvent#ACTION_DRAG_ENTERED}, and {@link android.view.DragEvent#ACTION_DROP}). During a drag, the system repeatedly calls {@link android.view.View.OnDragListener#onDrag onDrag()} for the view underneath the drag, to deliver a stream of drag events. The receiving view can inquire the event type delivered to {@link android.view.View#onDragEvent onDragEvent()} by calling {@link android.view.DragEvent#getAction getAction()} on the {@link android.view.DragEvent}.

Note: Although a drag event may carry a {@link android.content.ClipData} object, this is not related to the system clipboard. A drag and drop operation should never put the dragged data in the system clipboard.

For more information, read the Dragging and Dropping documentation. You can also see an implementation of drag and drop in the API Demos application and the Honeycomb Gallery application.

App widgets

Android 3.0 supports several new widget classes for more interactive app widgets on the users Home screen, including: {@link android.widget.GridView}, {@link android.widget.ListView}, {@link android.widget.StackView}, {@link android.widget.ViewFlipper}, and {@link android.widget.AdapterViewFlipper}.

More importantly, you can use the new {@link android.widget.RemoteViewsService} to create app widgets with collections, using widgets such as {@link android.widget.GridView}, {@link android.widget.ListView}, and {@link android.widget.StackView} that are backed by remote data, such as from a content provider.

The {@link android.appwidget.AppWidgetProviderInfo} class (defined in XML with an {@code <appwidget-provider>} element) also supports two new fields: {@link android.appwidget.AppWidgetProviderInfo#autoAdvanceViewId} and {@link android.appwidget.AppWidgetProviderInfo#previewImage}. The {@link android.appwidget.AppWidgetProviderInfo#autoAdvanceViewId} field lets you specify the view ID of the app widget subview that should be auto-advanced by the app widget’s host. The {@link android.appwidget.AppWidgetProviderInfo#previewImage} field specifies a preview of what the app widget looks like and is shown to the user from the widget picker. If this field is not supplied, the app widget's icon is used for the preview.

To help create a preview image for your app widget (to specify in the {@link android.appwidget.AppWidgetProviderInfo#previewImage} field), the Android emulator includes an application called "Widget Preview." To create a preview image, launch this application, select the app widget for your application and set it up how you'd like your preview image to appear, then save it and place it in your application's drawable resources.

You can see an implementation of the new app widget features in the StackView App Widget and Weather List Widget applications.

Status bar notifications

The {@link android.app.Notification} APIs have been extended to support more content-rich status bar notifications, plus a new {@link android.app.Notification.Builder} class allows you to easily create {@link android.app.Notification} objects.

New features include:

Content loaders

New framework APIs facilitate asynchronous loading of data using the {@link android.content.Loader} class. You can use it in combination with UI components such as views and fragments to dynamically load data from worker threads. The {@link android.content.CursorLoader} subclass is specially designed to help you do so for data backed by a {@link android.content.ContentProvider}.

All you need to do is implement the {@link android.app.LoaderManager.LoaderCallbacks LoaderCallbacks} interface to receive callbacks when a new loader is requested or the data has changed, then call {@link android.app.LoaderManager#initLoader initLoader()} to initialize the loader for your activity or fragment.

For more information, read the Loaders documentation. You can also see example code using loaders in the FragmentListCursorLoader and LoaderThrottle samples.

Bluetooth A2DP and headset APIs

Android now includes APIs for applications to verify the state of connected Bluetooth A2DP and headset profile devices. For example, applications can identify when a Bluetooth headset is connected for listening to music and notify the user as appropriate. Applications can also receive broadcasts for vendor specific AT commands and notify the user about the state of the connected device, such as when the connected device's battery is low.

You can initialize the respective {@link android.bluetooth.BluetoothProfile} by calling {@link android.bluetooth.BluetoothAdapter#getProfileProxy getProfileProxy()} with either the {@link android.bluetooth.BluetoothProfile#A2DP} or {@link android.bluetooth.BluetoothProfile#HEADSET} profile constant and a {@link android.bluetooth.BluetoothProfile.ServiceListener} to receive callbacks when the Bluetooth client is connected or disconnected.

Animation framework

An all new flexible animation framework allows you to animate arbitrary properties of any object (View, Drawable, Fragment, Object, or anything else). It allows you to define several aspects of an animation, such as:

You can define these animation aspects, and others, 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. To animate any other type of value, you tell the system how to calculate the values for that given type, by implementing the {@link android.animation.TypeEvaluator} interface.

There are two animators you can use to animate the values of a property: {@link android.animation.ValueAnimator} and {@link android.animation.ObjectAnimator}. The {@link android.animation.ValueAnimator} computes the animation values, but is not aware of the specific object or property that is animated as a result. It simply performs the calculations, and you must listen for the updates and process the data with your own logic. The {@link android.animation.ObjectAnimator} is a subclass of {@link android.animation.ValueAnimator} and allows you to set the object and property to animate, and it handles all animation work. That is, you give the {@link android.animation.ObjectAnimator} the object to animate, the property of the object to change over time, and a set of values to apply to the property over time, then start the animation.

Additionally, the {@link android.animation.LayoutTransition} class enables automatic transition animations for changes you make to your activity layout. To enable transitions for part of the layout, create a {@link android.animation.LayoutTransition} object and set it on any {@link android.view.ViewGroup} by calling {@link android.view.ViewGroup#setLayoutTransition setLayoutTransition()}. This causes default animations to run whenever items are added to or removed from the group. To specify custom animations, call {@link android.animation.LayoutTransition#setAnimator setAnimator()} on the {@link android.animation.LayoutTransition} and provide a custom {@link android.animation.Animator}, such as a {@link android.animation.ValueAnimator} or {@link android.animation.ObjectAnimator} discussed above.

For more information, see the Property Animation documentation. You can also see several samples using the animation APIs in the API Demos application.

Extended UI framework

Graphics

Media

Keyboard support

Split touch events

Previously, only a single view could accept touch events at one time. Android 3.0 adds support for splitting touch events across views and even windows, so different views can accept simultaneous touch events.

Split touch events is enabled by default when an application targets Android 3.0. That is, when the application has set either the {@code android:minSdkVersion} or {@code android:targetSdkVersion} attribute's value to {@code "11"}.

However, the following properties allow you to disable split touch events across views inside specific view groups and across windows.

WebKit

Browser

The Browser application adds the following features to support web applications:

JSON utilities

New classes, {@link android.util.JsonReader} and {@link android.util.JsonWriter}, help you read and write JSON streams. The new APIs complement the {@link org.json} classes, which manipulate a document in memory.

You can create an instance of {@link android.util.JsonReader} by calling its constructor method and passing the {@link java.io.InputStreamReader} that feeds the JSON string. Then begin reading an object by calling {@link android.util.JsonReader#beginObject()}, read a key name with {@link android.util.JsonReader#nextName()}, read the value using methods respective to the type, such as {@link android.util.JsonReader#nextString()} and {@link android.util.JsonReader#nextInt()}, and continue doing so while {@link android.util.JsonReader#hasNext()} is true.

You can create an instance of {@link android.util.JsonWriter} by calling its constructor and passing the appropriate {@link java.io.OutputStreamWriter}. Then write the JSON data in a manner similar to the reader, using {@link android.util.JsonWriter#name name()} to add a property name and an appropriate {@link android.util.JsonWriter#value value()} method to add the respective value.

These classes are strict by default. The {@link android.util.JsonReader#setLenient setLenient()} method in each class configures them to be more liberal in what they accept. This lenient parse mode is also compatible with the {@link org.json}'s default parser.

New feature constants

The {@code <uses-feature>} manfest element should be used to inform external entities (such as Android Market) of the set of hardware and software features on which your application depends. In this release, Android adds the following new constants that applications can declare with this element:

New permissions

New platform technologies

API differences report

For a detailed view of all API changes in Android {@sdkPlatformVersion} (API Level {@sdkPlatformApiLevel}), see the API Differences Report.

API Level

The Android {@sdkPlatformVersion} platform delivers an updated version of the framework API. The Android {@sdkPlatformVersion} API is assigned an integer identifier — {@sdkPlatformApiLevel} — that is stored in the system itself. This identifier, called the "API Level", allows the system to correctly determine whether an application is compatible with the system, prior to installing the application.

To use APIs introduced in Android {@sdkPlatformVersion} in your application, you need compile the application against the Android library that is provided in the Android {@sdkPlatformVersion} SDK platform. Depending on your needs, you might also need to add an android:minSdkVersion="{@sdkPlatformApiLevel}" attribute to the <uses-sdk> element in the application's manifest. If your application is designed to run only on Android 2.3 and higher, declaring the attribute prevents the application from being installed on earlier versions of the platform.

For more information about how to use API Level, see the API Levels document.

Built-in Applications

The system image included in the downloadable platform provides these built-in applications:

  • API Demos
  • Browser
  • Calculator
  • Camera
  • Clock
  • Contacts
  • Custom Locale
  • Dev Tools
  • Downloads
  • Email
  • Gallery
  • Gestures Builder
  • Messaging
  • Music
  • Search
  • Settings
  • Spare Parts
  • Speech Recorder
  • Widget Preview

Locales

The system image included in the downloadable SDK platform provides a variety of built-in locales. In some cases, region-specific strings are available for the locales. In other cases, a default version of the language is used. The languages that are available in the Android 3.0 system image are listed below (with language_country/region locale descriptor).

  • Arabic, Egypt (ar_EG)
  • Arabic, Israel (ar_IL)
  • Bulgarian, Bulgaria (bg_BG)
  • Catalan, Spain (ca_ES)
  • Czech, Czech Republic (cs_CZ)
  • Danish, Denmark(da_DK)
  • German, Austria (de_AT)
  • German, Switzerland (de_CH)
  • German, Germany (de_DE)
  • German, Liechtenstein (de_LI)
  • Greek, Greece (el_GR)
  • English, Australia (en_AU)
  • English, Canada (en_CA)
  • English, Britain (en_GB)
  • English, Ireland (en_IE)
  • English, India (en_IN)
  • English, New Zealand (en_NZ)
  • English, Singapore(en_SG)
  • English, US (en_US)
  • English, Zimbabwe (en_ZA)
  • Spanish (es_ES)
  • Spanish, US (es_US)
  • Finnish, Finland (fi_FI)
  • French, Belgium (fr_BE)
  • French, Canada (fr_CA)
  • French, Switzerland (fr_CH)
  • French, France (fr_FR)
  • Hebrew, Israel (he_IL)
  • Hindi, India (hi_IN)
  • Croatian, Croatia (hr_HR)
  • Hungarian, Hungary (hu_HU)
  • Indonesian, Indonesia (id_ID)
  • Italian, Switzerland (it_CH)
  • Italian, Italy (it_IT)
  • Japanese (ja_JP)
  • Korean (ko_KR)
  • Lithuanian, Lithuania (lt_LT)
  • Latvian, Latvia (lv_LV)
  • Norwegian bokmål, Norway (nb_NO)
  • Dutch, Belgium (nl_BE)
  • Dutch, Netherlands (nl_NL)
  • Polish (pl_PL)
  • Portuguese, Brazil (pt_BR)
  • Portuguese, Portugal (pt_PT)
  • Romanian, Romania (ro_RO)
  • Russian (ru_RU)
  • Slovak, Slovakia (sk_SK)
  • Slovenian, Slovenia (sl_SI)
  • Serbian (sr_RS)
  • Swedish, Sweden (sv_SE)
  • Thai, Thailand (th_TH)
  • Tagalog, Philippines (tl_PH)
  • Turkish, Turkey (tr_TR)
  • Ukrainian, Ukraine (uk_UA)
  • Vietnamese, Vietnam (vi_VN)
  • Chinese, PRC (zh_CN)
  • Chinese, Taiwan (zh_TW)
  • Note: The Android platform may support more locales than are included in the SDK system image. All of the supported locales are available in the Android Open Source Project.

    Emulator Skins

    The downloadable platform includes the following emulator skin:

    For more information about how to develop an application that displays and functions properly on all Android-powered devices, see Supporting Multiple Screens.