From b7c7f157377abf46a3897cbf7f106c5fa85c23ee Mon Sep 17 00:00:00 2001 From: Dirk Dougherty Date: Fri, 25 Mar 2011 11:54:46 -0700 Subject: Doc change: add Android 3.1 highlights and version notes. Change-Id: Ifbc7df004d8aca9073d6397fad282a57ad4f1b74 --- docs/html/guide/appendix/api-levels.jd | 4 +- docs/html/sdk/android-2.3.4.jd | 379 +++++++++++ docs/html/sdk/android-3.0-highlights.jd | 6 - docs/html/sdk/android-3.0.jd | 2 +- docs/html/sdk/android-3.1-highlights.jd | 380 +++++++++++ docs/html/sdk/android-3.1.jd | 1053 +++++++++++++++++++++++++++++++ docs/html/sdk/images/3.1/controls.png | Bin 0 -> 103866 bytes docs/html/sdk/images/3.1/home.png | Bin 0 -> 142023 bytes docs/html/sdk/images/3.1/home_full.png | Bin 0 -> 624953 bytes docs/html/sdk/images/3.1/resizeable.png | Bin 0 -> 64928 bytes docs/html/sdk/images/3.1/tasks.png | Bin 0 -> 136355 bytes docs/html/sdk/sdk_toc.cs | 44 +- docs/html/sdk/tools-notes.jd | 2 +- 13 files changed, 1850 insertions(+), 20 deletions(-) create mode 100644 docs/html/sdk/android-2.3.4.jd create mode 100644 docs/html/sdk/android-3.1-highlights.jd create mode 100644 docs/html/sdk/android-3.1.jd create mode 100644 docs/html/sdk/images/3.1/controls.png create mode 100644 docs/html/sdk/images/3.1/home.png create mode 100644 docs/html/sdk/images/3.1/home_full.png create mode 100644 docs/html/sdk/images/3.1/resizeable.png create mode 100644 docs/html/sdk/images/3.1/tasks.png (limited to 'docs') diff --git a/docs/html/guide/appendix/api-levels.jd b/docs/html/guide/appendix/api-levels.jd index 013cc94..5c18a83 100644 --- a/docs/html/guide/appendix/api-levels.jd +++ b/docs/html/guide/appendix/api-levels.jd @@ -83,8 +83,10 @@ Android platform.

+ - + + diff --git a/docs/html/sdk/android-2.3.4.jd b/docs/html/sdk/android-2.3.4.jd new file mode 100644 index 0000000..e5765d3 --- /dev/null +++ b/docs/html/sdk/android-2.3.4.jd @@ -0,0 +1,379 @@ +page.title=Android 2.3.4 Platform +sdk.platform.version=2.3.4 +sdk.platform.apiLevel=10 + + +@jd:body + +
+ +
+ +

+API Level: {@sdkPlatformApiLevel}

+ +

Android 2.3.4 is a maintenance release that adds several bug fixes and patches +to the Android 2.3 platform, without any API changes from Android 2.3.3. Additionally, +Android 2.3.4 brings support for the Open Accessory API to mobile devices, +through the optional Open Accessory Library.

+ +

For developers, the Android {@sdkPlatformVersion} platform and the Open +Accessory Library are available together in the latest version of the Google +APIs Add-On, a downloadable component for the Android SDK.

+ +

To get started developing or testing against Android {@sdkPlatformVersion}, +use the Android SDK Manager to download the latest version of the Google APIs +Add-On 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 2.3, see the Platform Highlights.

+ + +

Revisions

+ +

The sections below provide notes about successive releases of +the Android {@sdkPlatformVersion} platform component for the Android SDK, as denoted by +revision number. To determine what revision(s) of the Android +{@sdkPlatformVersion} platforms are installed in your SDK environment, refer to +the "Installed Packages" listing in the Android SDK and AVD Manager.

+ + + + +
+ + + Android {@sdkPlatformVersion}, Revision 1 (May 2011) +
+
+
Dependencies:
+
+

Requires SDK Tools r11 or higher.

+
+ +
+
+
+ + +

API Overview

+ +

Android 2.3.4 provides the same framework API to applications as Android 2.3.3 +(API level 10). For a summary of the API, see the +Android 2.3.3 version notes.

+ + +

Open Accessory Library

+ +

Open Accessory is a new capability for integrating +connected peripherals with applications running on the platform. The capability +is based on a USB (Universal Serial Bus) stack built into the platform and an +API exposed to applications. Peripherals that attach to Android-powered devices +as accessories connect as USB hosts.

+ +

Open Accessory is introduced in Android 3.1 (API level 12), but is +made available to devices running Android 2.3.4 by means of an optional external +library, the Open Accessory Library. The library exposes a framework API that +lets applications discover, communicate with, and manage a variety of device +types connected over USB. It also provides the implementation of the API against +parts of the Android platform that are not directly exposed to applications in +Android 2.3.4.

+ +

The Open Accessory Library is optional on any given device. Device +manufacturers may choose whether to include the Open Accessory Library in their +products or exclude it. The library is forward-compatible with Android 3.1, so +applications developed against Android 2.3.4 will run properly on devices +running Android 3.1, if those devices support USB accessories.

+ +

The API provided by the Open Accessory Library is based on the Open Accessory +API provided in Android 3.1. In most areas, you can use the same techniques and +APIs. However, developing for the Open Accessory Library on Android 2.3.4 differs +from the standard USB API in these ways: + +

+ +

To develop apps using the Open Accessory Library, you need:

+ + + +

For a full discussion of how to develop applications that interact with USB +accessories, please see the related developer documentation.

+ +

Additionally, developers can request filtering on Android Market, such that +their applications are not available to users whose devices do not provide the +appropriate accessory support. To request filtering, add the element below +to the application manifest:

+ +
<uses-feature
+  android:name="android.hardware.usb.accessory"
+  android:required="true">
+ + +

API Level

+ +

The Android 2.3.4 platform does not increment the API level — +it uses the same API level as Android 2.3.3, API level 10. + +

To use APIs introduced in API level 10 in your application, +you need compile the application against the Android library that is provided in +the latest version of the Google APIs Add-On, which also includes the Open +Accessory Library.

+ +

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

+ +
Platform VersionAPI Level
Android 3.112
Android 3.011
Android 2.3.310
Android 2.3.410
Android 2.3.3
Android 2.39
Android 2.28
Android 2.17
+ + + + +
+
    +
  • Browser
    • +
  • Calculator
    • +
  • Camera
    • +
  • Clock
    • +
  • Contacts
    • +
  • Cusom Locale
    • +
  • Dev Tools
    • +
  • Downloads
    • +
  • Email
    • +
+		 +
    +
  • Gallery
    • +
  • IMEs for Japanese, Chinese, and Latin text input
    • +
  • Messaging
    • +
  • Music
    • +
  • Phone
    • +
  • Search
    • +
  • Settings
    • +
  • Spare Parts (developer app)
    • +
  • Speech Recorder
    • +
+
+ + +

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 {@sdkPlatformVersion} 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-Bokmol, 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 a set of emulator skins that you can use +for modeling your application in different screen sizes and resolutions. The +emulator skins are:

    + + + +

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

    diff --git a/docs/html/sdk/android-3.0-highlights.jd b/docs/html/sdk/android-3.0-highlights.jd index d4fd002..33897de 100644 --- a/docs/html/sdk/android-3.0-highlights.jd +++ b/docs/html/sdk/android-3.0-highlights.jd @@ -39,10 +39,6 @@ page.title=Android 3.0 Platform Highlights - - - -

    Welcome to Android 3.0!

    The Android 3.0 platform introduces many new and exciting features for users and developers. @@ -265,5 +261,3 @@ allowscriptaccess="always" allowfullscreen="true" width="278" height="180">Android 3.0 Platform document.

    For a video overview of platform features, see the Android 3.0 Sneak Peek.

    - - diff --git a/docs/html/sdk/android-3.0.jd b/docs/html/sdk/android-3.0.jd index a81be20..d73bd63 100644 --- a/docs/html/sdk/android-3.0.jd +++ b/docs/html/sdk/android-3.0.jd @@ -559,7 +559,7 @@ menu.

    Provides a search box that you can configure to deliver search queries to a specified activity and display search suggestions (in the same manner as the traditional search dialog). This widget is particularly useful for offering a search widget in the Action Bar. For more information, -see Creating a Search Interface

    . +see Creating a Search Interface.

  • {@link android.widget.StackView}

    A view that displays its children in a 3D stack and allows users to swipe through diff --git a/docs/html/sdk/android-3.1-highlights.jd b/docs/html/sdk/android-3.1-highlights.jd new file mode 100644 index 0000000..3d132a3 --- /dev/null +++ b/docs/html/sdk/android-3.1-highlights.jd @@ -0,0 +1,380 @@ +page.title=Android 3.1 Platform Highlights + +@jd:body + + + + +

    Welcome to Android 3.1!

    + +

    Android 3.1 is an incremental platform release that refines many of the +features introduced in Android 3.0. It builds on the same tablet-optimized UI +and features offered in Android 3.0 and adds several new capabilities for +users and developers. This document provides an overview of the new features and +technologies introduced in Android 3.1. For a more detailed look at new +developer APIs, see the API +Overview document.

    + +

    For a high-level introduction to Android 3.0, please see the Android 3.0 Platform +Highlights.

    + + + +

    New User Features

    + +
    +
    +
    Figure 1. An Android 3.1 Home screen.
    +
    + +

    UI refinements

    + +

    The Android 3.1 platform adds a variety of refinements to make the user +interface more intuitive and more efficient to use.

    + +

    UI transitions are improved throughout the system and across the standard +apps. The Launcher animation is optimized for faster, smoother transition to and +from the Apps list. Adjustments in color, positioning, and text make UI elements +easier to see, understand, and use. Accessibility is improved with consistent +audible feedback throughout the UI and a new setting to let users customize the +touch-hold interval to meet their needs.

    + +

    Navigation to and from the five home screens is now easier — touching +the Home button in the system bar now takes you to the home screen most recently +used. Settings offers an improved view of internal storage, +showing the storage used by a larger set of file types.

    + +

    Connectivity for USB accessories

    + +

    Android 3.1 adds broad platform support for a variety of USB-connected +peripherals and accessories. Users can attach many types of input devices +(keyboards, mice, game controllers) and digital cameras. Applications can build +on the platform’s USB support to extend connectivity to almost any type of USB +device.

    + +

    The platform also adds new support for USB accessories — external +hardware devices designed to attach to Android-powered devices as USB hosts. When an +accessory is attached, the framework will look for a corresponding application +and offer to launch it for the user. The accessory can also present a URL +to the user, for downloading an appropriate application if one is not already +installed. Users can interact with the application to control powered accessories such +as robotics controllers; docking stations; diagnostic and musical equipment; +kiosks; card readers; and much more.

    + +

    The platform’s USB capabilities rely on components in device hardware, so +support for USB on specific devices may vary and is determined by device +manufacturers.

    + +
    +
    +
    Figure 2. The Recent Apps menu is now expandable and scrollable.
    +
    + +

    Expanded Recent Apps list

    + +

    For improved multitasking and instant visual access to a much larger number +of apps, the Recent Apps list is now expandable. Users can now scroll the list +of recent apps vertically to see thumbnail images all of the tasks in progress +and recently used apps, then touch a thumbnail to jump back into that task.

    + +

    Resizeable Home screen widgets

    + +

    For more flexible Home screen customization, users can now resize their Home +screen widgets using drag bars provided by the system. Users can expand widgets +both horizontally and/or vertically to include more content, where supported by +each widget.

    + + +

    Support for external keyboards +and pointing devices

    + +

    Users can now attach almost any type of external keyboard or mouse to their +Android-powered devices, to create a familiar environment and work more +efficiently. One or more input devices can be attached to the system simultaneously +over USB and/or Bluetooth HID, in any combination. No special configuration or +driver is needed, in most cases. When multiple devices are connected, users can +conveniently manage the active keyboard and IME using the keyboard settings that +are available from the System bar.

    + +

    For pointing devices, the platform supports most types of mouse with a single +button and optionally a scroll wheel, as well as similar devices such as +trackballs. When these are connected, users can interact with the UI using +point, select, drag, scroll, hover, and other standard actions.

    + +

    Support for joysticks and gamepads

    + +

    To make the platform even better for gaming, Android 3.1 adds support for +most PC joysticks and gamepads that are connected over USB or Bluetooth HID.

    + +

    For example, users can connect Sony Playstation™ 3 and XBox 360™ game +controllers over USB (but not Bluetooth), Logitech Dual Action™ gamepads and +flight sticks, or a car racing controller. Game controllers that use proprietary +networking or pairing are not supported by default, but in general, the platform +supports most PC-connectible joysticks and gamepads.

    + +

    Robust Wi-Fi networking

    + +

    Android 3.1 adds robust Wi-Fi features, to make sure that users and their +apps can take full advantage of higher-speed Wi-Fi access at home, at work, and +while away.

    + +

    A new high-performance Wi-Fi lock lets applications maintain +high-performance Wi-Fi connections even when the device screen is off. Users can +take advantage of this to play continuous streamed music, video, and voice +services for long periods, even when the device is otherwise idle and the screen +is off.

    + +

    Users can now configure an HTTP proxy for each individual Wi-Fi access +point, by touch-hold of the access point in Settings. The browser uses the HTTP +proxy when communicating with the network over the access point and other apps +may also choose to do so. The platform also provides backup and restore of the +user-defined IP and proxy settings.

    +

    The platform adds support for Preferred Network Offload (PNO), a background +scanning capability that conserves battery power savings in cases where Wi-Fi +needs to be available continuously for long periods of time.

    + +

    Updated set of standard apps

    + +

    The Android 3.1 platform includes an updated set of standard applications +that are optimized for use on larger screen devices. The sections below +highlight some of the new features.

    + +
    +
    +
    Figure 3. Quick Controls menu in the Browser.
    +
    +
    + +

    Browser

    + +

    The Browser app includes a variety of new features and UI improvements that +make viewing web content simpler, faster, and more convenient.

    + +

    The Quick Controls UI, accessible from Browser Settings, is extended and +redesigned. Users can now use the controls to view thumbnails of open tabs and +close the active tab, as well as access the overflow menu for instant access to +Settings and other controls.

    + +

    To ensure a consistent viewing experience, the Browser extends it's support +for popular web standards such as CSS 3D, animations, and CSS fixed +positioning to all sites, mobile or desktop. It also adds support for embedded +playback of HTML5 video content. To make it easier to manage favorite +content, users can now save a web page locally for offline viewing, including +all styling and images. For convenience when visiting Google sites, an improved +auto-login UI lets users sign in quickly and manage access when multiple users +are sharing a device.

    + +

    For best performance, the Browser adds support for plugins that use hardware +accelerated rendering. Page zoom performance is also dramatically improved, +making it faster to navigate and view web pages.

    + +

    Gallery

    + +

    The Gallery app now supports Picture Transfer Protocol (PTP), so that users +can connect their cameras over USB and import their pictures to Gallery with a +single touch. The app also copies the pictures to local storage and provides an +indicator to let users see how much space is available.

    + +
    +
    +
    Figure +4. Home screen widgets can now be resized.
    + +

    Calendar

    + +

    Calendar grids are larger, for better readability and more accurate +touch-targeting. Additionally, users can create a larger viewing area for grids +by hiding the calendar list controls. Controls in the date picker are +redesigned, making them easier to see and use.

    • + + +

    Contacts

    + +

    The Contacts app now lets you locate contacts more easily using full text +search. Search returns matching results from all fields that are stored for a +contact. +

    + +

    Email

    + +

    When replying or forwarding an HTML message, The Email app now sends both +plain text and HTML bodies as a multi-part mime message. This ensures that the +message will be formatted properly for all recipients. Folder prefixes for IMAP +accounts are now easier to define and manage. To conserve battery power and +minimize cell data usage, the application now prefetches email from the server +only when the device is connected to a Wi-Fi access point.

    + +

    An updated Home screen widget give users quick access to more email. Users +can touch Email icon at the top of the widget to cycle through labels such as +Inbox, Unread, and Starred. The widget itself is now resizable, both +horizontally and vertically.

    + +

    Enterprise support

    + +

    Users can now configure an HTTP proxy for each connected Wi-Fi access point. +This lets administrators work with users to set a proxy hostname, port, and any +bypass subdomains. This proxy configuration is automatically used by the Browser +when the Wi-Fi access point is connected, and may optionally be used by other +apps. The proxy and IP configuration is now backed up and restored across system +updates and resets.

    + +

    To meet the needs of tablet users, the platform now allows a "encrypted +storage card" device policy to be accepted on devices with emulated storage +cards and encrypted primary storage.

    + + +

    New Developer Features

    + +

    The Android 3.1 platform adds refinements and new capabilities that +developers can build on, to create powerful and engaging application experiences +on tablets and other large-screen devices.

    + +

    Open Accessory API for rich interaction with +peripherals

    + +

    Android 3.1 introduces a new API for integrating hardware accessories with +applications running on the platform. The API provides a way to interact across +a wide range of peripherals, from robotics controllers to musical equipment, +exercise bicycles, and more.

    + +

    The API is based on a new USB (Universal Serial Bus) stack and services +that are built into the platform. The platform provides services for discovering +and identifying connected hardware, as well as for notifying interested +applications that the hardware is available.

    + +

    When a user plugs in a USB accessory, the platform receives +identifying information such as product name, accessory type, manufacturer, and +version. The platform sets up communication with the accessory and uses its +information to notify and launch a targeted app, if one is available. Optionally, +an accessory can provide a URL that lets users find and download an +app that works with the accessory. These discovery features make +first-time setup easier for the user and ensure that an appropriate application +is available for interacting with the connected hardware.

    + +

    For application developers and accessory manufacturers, accessory mode offers +many new ways to engage users and build powerful interaction experiences with +connected hardware.

    + +

    To learn more about how to develop applications that interact with +accessories, see the USB +Accessory documentation.

    + +

    USB host API

    + +

    Android 3.1 provides built-in platform support for USB host mode and exposes +an API that lets applications manage connected peripherals. On devices that +support host mode, applications can use the API to identify and communicate with +connected devices such as audio devices. input devices, communications devices, +hubs, cameras, and more.

    + +

    To learn more about how to develop applications that interact with +USB devices, see the USB +Host documentation.

    + +

    Input from mice, joysticks, and gamepads

    + +

    Android 3.1 extends the input event system to support a variety of new input +sources and motion events, across all views and windows. Developers can build on +these capabilities to let users interact with their applications using mice, +trackballs, joysticks, gamepads, and other devices, in addition to keyboards and +touchscreens.

    + +

    For mouse and trackball input, the platform supports two new motion event +actions: scroll (horizontal or vertical) such as from a scrollwheel; and hover, +which reports the location of the mouse when no buttons are pressed. +Applications can handle these events in any way needed.

    + +

    For joysticks and gamepads, the platform provides a large number of motion +axes that applications can use from a given input source, such as X, Y, Hat X, +Hat Y, rotation, throttle, pressure, size, touch, tool, orientation, and others. +Developers can also define custom axes if needed, to capture motion in +additional ways. The platform provides motion events to applications as a batch, +and applications can query the details of the movements included in the batch, +for more efficient and precise handling of events.

    + +

    Applications can query for the list of connected input devices and the motion +ranges (axes) supported by each device. Applications can also handle multiple +input and motion events from a single input device. For example, an application +can use mouse and joystick and mouse event sources from a single input +device.

    + +

    Resizable Home screen widgets

    + +

    Developers can now create Home screen widgets that users can resize +horizontally, vertically, or both. By simply adding an attribute to the +declaration of a widget, the widget becomes resizable horizontally, vertically, +or both. This lets users customize the display of the widget content and display +more of it on their Home screens.

    + +

    MTP API for integrating with external cameras

    + +

    In Android 3.1, a new MTP (Media Transfer Protocol) API lets developers write +apps that interact directly with connected cameras and other PTP devices. The +new API makes it easy for applications to receive notifications when devices are +attached and removed, manage files and storage on those devices, and transfer +files and metadata to and from them. The MTP API implements the PTP (Picture +Transfer Protocol) subset of the MTP specification.

    + +

    RTP API, for control over audio streaming sessions

    + +

    Android 3.1 exposes an API to its built-in RTP (Real-time Transport Protocol) +stack, which applications can use to directly manage on-demand or interactive +data streaming. In particular, apps that provide VOIP, push-to-talk, +conferencing, and audio streaming can use the API to initiate sessions and +transmit or receive data streams over any available network.

    + +

    Performance optimizations

    + +

    Android 3.1 includes a variety of performance optimizations that help make +applications faster and more responsive. Some of the optimizations include:

    + + + diff --git a/docs/html/sdk/android-3.1.jd b/docs/html/sdk/android-3.1.jd new file mode 100644 index 0000000..57fe1eb --- /dev/null +++ b/docs/html/sdk/android-3.1.jd @@ -0,0 +1,1053 @@ +page.title=Android 3.1 Platform +sdk.platform.version=3.1 +sdk.platform.apiLevel=12 +@jd:body + +
    + +
    + + +

    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.

    + +

    Reminder: If you've already published an +Android application, please test and optimize your application on Android 3.0 +and Android 3.1 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 (May 2011) +

    + +
    + +
    + +
    Dependencies:
    +
    +

    Requires SDK Tools r11 or +higher.

    +
    + +
    + +
    +
    + + +

    API Overview

    + +

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

    + +

    USB APIs

    + +

    Android 3.1 introduces powerful new APIs for +integrating connected peripherals with applications running on the platform. +The APIs are based on a USB (Universal Serial Bus) stack and services that are +built into the platform, including support for both USB host and device +interactions. Using the APIs, developers can create applications that are able to +discover, communicate with, and manage a variety of device types connected over +USB.

    + +

    The stack and APIs distinguish two basic types of USB hardware, based on +whether the platform iself is acting as host or the external hardware is acting +as host:

    + + + +

    For both types — USB devices and USB accessories — the +platform's USB APIs support discovery by intent broadcast when attached or +detached, as well as standard interfaces, endpoints, and transfer modes +(control, bulk, and interrupt).

    + +

    The USB APIs are available in the package {@link android.hardware.usb}. The +central class is {@link android.hardware.usb.UsbManager}, which provides +helper methods for identifying and communicating with +both USB devices and USB accessories. Applications can acquire an instance of +{@link android.hardware.usb.UsbManager} and then query for the list of attached +devices or accessories and then communicate with or manage them. +{@link android.hardware.usb.UsbManager} also declares intent actions that the +system broadcasts, to announce when a USB device or accessory is attached or +detached.

    + +

    Other classes include:

    + + + +

    Note that although the USB stack is built into the platform, actual support +for USB host and open accessory modes on specific devices is determined by +their manufacturers. In particular, host mode relies on appropriate USB +controller hardware in the Android-powered device.

    + +

    Additionally, developers can request filtering on Android Market, such that +their applications are not availabe to users whose devices do not provide the +appropriate USB support. To request filtering, add one or both of the elements +below to the application manifest, as appropriate:

    + + + +

    For complete information about how to develop applications that interact with +USB accessories, please see the +developer documentation.

    + +

    To look at sample applications that use the USB host API, see ADB Test and Missile +Launcher

    + +

    MTP/PTP API

    + +

    Android 3.1 exposes a new MTP API that lets applications interact directly +with connected cameras and other PTP devices. The new API makes it easy for an +application to receive notifications when devices are attached and removed, +manage files and storage on those devices, and transfer files and metadata to +and from them. The MTP API implements the PTP (Picture Transfer Protocol) subset +of the MTP (Media Transfer Protocol) specification.

    + +

    The MTP API is available in the {@link android.mtp} package and provides +these classes:

    + + + +

    Support for new input devices and motion events

    + +

    Android 3.1 extends the input subsystem to support new input devices and new +types of motion events, across all views and windows. Developers can build on +these capabilities to let users interact with their applications using mice, +trackballs, joysticks, gamepads, and other devices, in addition to keyboards and +touchscreens.

    + +

    For handling mouse, scrollwheel, and trackball input, the platform supports +two new motion event actions:

    + + +

    To support joysticks and gamepads, the {@link android.view.InputDevice} class +includes these new input device sources:

    + + +

    To describe motion events from these new sources, as well as those from mice +and trackballs, the platform now defines axis codes on {@link +android.view.MotionEvent}, similar to how it defines key codes on {@link +android.view.KeyEvent}. New axis codes for joysticks +and game controllers include +{@link android.view.MotionEvent#AXIS_HAT_X}, {@link +android.view.MotionEvent#AXIS_HAT_Y}, {@link +android.view.MotionEvent#AXIS_RTRIGGER}, {@link +android.view.MotionEvent#AXIS_ORIENTATION}, {@link +android.view.MotionEvent#AXIS_THROTTLE}, and many others. +Existing {@link android.view.MotionEvent} axes are represented by {@link +android.view.MotionEvent#AXIS_X}, {@link android.view.MotionEvent#AXIS_Y}, +{@link android.view.MotionEvent#AXIS_PRESSURE}, {@link +android.view.MotionEvent#AXIS_SIZE}, {@link +android.view.MotionEvent#AXIS_TOUCH_MAJOR}, {@link +android.view.MotionEvent#AXIS_TOUCH_MINOR}, {@link +android.view.MotionEvent#AXIS_TOOL_MAJOR}, {@link +android.view.MotionEvent#AXIS_TOOL_MINOR}, and {@link +android.view.MotionEvent#AXIS_ORIENTATION}.

    + +

    Additionally, {@link android.view.MotionEvent} defines a number of generic +axis codes that are used when the framework does not know how to map a +particular axis. Specific devices can use the generic axis codes to pass custom +motion data to applications. For a full list of axes and their intended +interpretations, see the {@link android.view.MotionEvent} class documentation. +

    + +

    The platform provides motion events to applications in batches, so a single +event may contain a current position and multiple so-called historical movements. +Applications should use {@link android.view.MotionEvent#getHistorySize()} to get +the number of historical samples, then retrieve and process all historical +samples in order using {@link +android.view.MotionEvent#getHistoricalAxisValue(int, int, int) +getHistoricalAxisValue()}. After that, applications should process the current +sample using {@link android.view.MotionEvent#getAxisValue(int) getAxisValue()}. +

    + +

    Some axes can be retrieved using special accessor methods. For example, +instead of calling {@link android.view.MotionEvent#getAxisValue(int) +getAxisValue()}, applications can call {@link android.view.MotionEvent#getX(int) +getX()}. Axes that have built-in accessors include {@link +android.view.MotionEvent#AXIS_X}, {@link android.view.MotionEvent#AXIS_Y}, +{@link android.view.MotionEvent#AXIS_PRESSURE}, {@link +android.view.MotionEvent#AXIS_SIZE}, {@link +android.view.MotionEvent#AXIS_TOUCH_MAJOR}, {@link +android.view.MotionEvent#AXIS_TOUCH_MINOR}, {@link +android.view.MotionEvent#AXIS_TOOL_MAJOR}, {@link +android.view.MotionEvent#AXIS_TOOL_MINOR}, and {@link +android.view.MotionEvent#AXIS_ORIENTATION}.

    + +

    Each input device has a unique, system-assigned ID and may also provide +multiple sources. When a device provides multiple sources, more than one source +can provide axis data using the same axis. For example, a touch event coming +from the touch source uses the X axis for screen position data, while a joystick +event coming from the joystick source will use the X axis for the stick position +instead. For this reason, it's important for applications to interpret axis +values according to the source from which they originate. When handling a motion +event, applications should use methods on the {@link android.view.InputDevice} +class to determine the axes supported by a device or source. Specifically, +applications can use {@link android.view.InputDevice#getMotionRanges() +getMotionRanges()} to query for all axes of a device or all axes of a given +source of the device. In both cases, the range information for axes returned in +the {@link android.view.InputDevice.MotionRange} object specifies the source for +each axis value.

    + +

    Finally, since the motion events from joysticks, gamepads, mice, and +trackballs are not touch events, the platform adds a new callback method for +passing them to a {@link android.view.View} as "generic" motion events. +Specifically, it reports the non-touch motion events to +{@link android.view.View}s through a call to {@link +android.view.View#onGenericMotionEvent(android.view.MotionEvent) +onGenericMotionEvent()}, rather than to {@link +android.view.View#onTouchEvent(android.view.MotionEvent) +onTouchEvent()}.

    + +

    The platform dispatches generic motion events differently, depending on the +event source class. {@link android.view.InputDevice#SOURCE_CLASS_POINTER} events +go to the {@link android.view.View} under the pointer, similar to how touch +events work. All others go to the currently focused {@link android.view.View}. +For example, this means a {@link android.view.View} must take focus in order to +receive joystick events. If needed, applications can handle these events at the +level of Activity or Dialog by implementing {@link +android.view.View#onGenericMotionEvent(android.view.MotionEvent) +onGenericMotionEvent()} there instead.

    + +

    To look at a sample application that uses joystick motion +events, see GameControllerInput and GameView.

    + +

    RTP API

    + +

    Android 3.1 exposes an API to its built-in RTP (Real-time Transport Protocol) +stack, which applications can use to manage on-demand or interactive data +streaming. In particular, apps that provide VOIP, push-to-talk, conferencing, +and audio streaming can use the API to initiate sessions and transmit or receive +data streams over any available network.

    + +

    The RTP API is available in the {@link android.net.rtp} package. Classes +include:

    + + +

    To support audio conferencing and similar usages, an application instantiates +two classes as endpoints for the stream:

    + + + +

    The simplest usage involves a single remote endpoint and local endpoint. +For more complex usages, please refer to the limitations described for +{@link android.net.rtp.AudioGroup}.

    + +

    To use the RTP API, applications must request permission from the user by +declaring <uses-permission +android:name="android.permission.INTERNET"> +in their manifest files. To acquire the device microphone, the <uses-permission +android:name="android.permission.RECORD_AUDIO"> permission is also required.

    + +

    Resizable app widgets

    + +

    Starting in Android 3.1, developers can make their homescreen widgets +resizeable — horizontally, vertically, or on both axes. Users touch-hold a +widget to show its resize handles, then drag the horizontal and/or vertical +handles to change the size on the layout grid.

    + +

    Developers can make any Home screen widget resizeable by defining a +resizeMode attribute in the widget's {@link +android.appwidget.AppWidgetProviderInfo} metadata. Values for the +resizeMode attribute include "horizontal", "vertical", and "none". +To declare a widget as resizeable horizontally and vertically, supply the value +"horizontal|vertical". + +

    Here's an example:

    + +
    <appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
+    android:minWidth="294dp"
+    android:minHeight="72dp"
+    android:updatePeriodMillis="86400000"
+    android:previewImage="@drawable/preview"
+    android:initialLayout="@layout/example_appwidget"
+    android:configure="com.example.android.ExampleAppWidgetConfigure"
+    android:resizeMode="horizontal|vertical" >
+</appwidget-provider>
    + +

    For more information about Home screen widgets, see the App Widgets +documentation.

    + +

    Animation framework

    + + + +

    UI framework

    + + +

    Graphics

    + + + +

    Network

    + + + + +

    Download Manager

    + + +

    IME framework

    + + + +

    Media

    + + + +

    Launch controls on stopped +applications

    + +

    Starting from Android 3.1, the system's package manager keeps track of +applications that are in a stopped state and provides a means of controlling +their launch from background processes and other applications.

    + +

    Note that an application's stopped state is not the same as an Activity's +stopped state. The system manages those two stopped states separately.

    + +

    The platform defines two new intent flags that let a sender specify +whether the Intent should be allowed to activate components in stopped +application.

    + + + +

    When neither or both of these flags is defined in an intent, the default +behavior is to include filters of stopped applications in the list of +potential targets.

    + +

    Note that the system adds {@link +android.content.Intent#FLAG_EXCLUDE_STOPPED_PACKAGES} to all broadcast +intents. It does this to prevent broadcasts from background services from +inadvertently or unnecessarily launching components of stoppped applications. +A background service or application can override this behavior by adding the +{@link android.content.Intent#FLAG_INCLUDE_STOPPED_PACKAGES} flag to broadcast +intents that should be allowed to activate stopped applications.

    + +

    Applications are in a stopped state when they are first installed but are not +yet launched and when they are manually stopped by the user (in Manage +Applications).

    + +

    Notification of application first launch and upgrade

    + +

    The platform adds improved notification of application first launch and +upgrades through two new intent actions:

    + + + +

    Core utilities

    + + + + + + + + +

    WebKit

    + + + + + +

    Browser

    + +

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

    + + + + + + + +

    New feature constants

    + +

    The platform adds new hardware feature constants that developers can declare +in their application manifests, to inform external entities such as Android +Market of the application's requirement for new hardware capabilities supported +in this version of the platform. Developers declare these and other feature +constants in {@code +<uses-feature>} manifest elements. + +

    + +

    Android Market filters applications based on features declared in {@code +<uses-feature>} manifest elements. For more information about +declaring features in an application manifest, read Android Market +Filters.

    + + + +

    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.

    + +

    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.

    \ No newline at end of file diff --git a/docs/html/sdk/images/3.1/controls.png b/docs/html/sdk/images/3.1/controls.png new file mode 100644 index 0000000..e0ca1f8 Binary files /dev/null and b/docs/html/sdk/images/3.1/controls.png differ diff --git a/docs/html/sdk/images/3.1/home.png b/docs/html/sdk/images/3.1/home.png new file mode 100644 index 0000000..ea0a75a Binary files /dev/null and b/docs/html/sdk/images/3.1/home.png differ diff --git a/docs/html/sdk/images/3.1/home_full.png b/docs/html/sdk/images/3.1/home_full.png new file mode 100644 index 0000000..2b8e85e Binary files /dev/null and b/docs/html/sdk/images/3.1/home_full.png differ diff --git a/docs/html/sdk/images/3.1/resizeable.png b/docs/html/sdk/images/3.1/resizeable.png new file mode 100644 index 0000000..c9f5e8e Binary files /dev/null and b/docs/html/sdk/images/3.1/resizeable.png differ diff --git a/docs/html/sdk/images/3.1/tasks.png b/docs/html/sdk/images/3.1/tasks.png new file mode 100644 index 0000000..89d69e5 Binary files /dev/null and b/docs/html/sdk/images/3.1/tasks.png differ diff --git a/docs/html/sdk/sdk_toc.cs b/docs/html/sdk/sdk_toc.cs index 3240b57..11f29b1 100644 --- a/docs/html/sdk/sdk_toc.cs +++ b/docs/html/sdk/sdk_toc.cs @@ -77,37 +77,59 @@ class="new">new!