page.title=Android 3.2 Platform sdk.platform.version=3.2 sdk.platform.apiLevel=13 @jd:body
API Level: {@sdkPlatformApiLevel}
Welcome to Android 3.2!
Android 3.2 is an incremental platform release that adds new capabilities for users and developers. The sections below provide an overview of the new features and developer APIs.
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.
Reminder: If you've already published an Android application, please test and optimize your application on Android 3.2 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.x.
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 (July 2011)
Android 3.2 includes a variety of optimizations across the system to ensure a great user experience on a wider range of tablet devices.
Android 3.2 introduces a new compatibility zoom mode that gives users a new way to view fixed-sized apps on larger devices. The new mode provides a pixel-scaled alternative to the standard UI stretching for apps that are not designed to run on larger screen sizes, such as on tablets. The new mode is accessible to users from a menu icon in the system bar, for apps that need compatibility support.
On devices that support an SD card, users can now load media files directly from the SD card to apps that use them. A system facility makes the files accessible to apps from the system media store.
Android 3.2 introduces extensions to the platform's screen support API to give developers additional ways to manage application UI across the range of Android-powered devices. The API includes new resource qualifiers and new manifest attributes that give you more precise control over how your apps are displayed on different sizes, rather than relying on generalized size categories.
To ensure the best possible display for fixed-sized apps and apps with limited support for various screen sizes, the platform also provides a new zoom compatibility mode that renders the UI on a smaller screen area, then scales it up to fill the space available on the display. For more information about the screen support API and the controls it provides, see the sections below.
Android 3.2 introduces new screens support APIs that give you more control over how their applications are displayed across different screen sizes. The API builds on the existing screens-support API, including the platform's generalized screen density model, but extends it with the ability to precisely target specific screen ranges by their dimensions, measured in density-independent pixel units (such as 600dp or 720dp wide), rather than by their generalized screen sizes (such as large or xlarge)
When designing an application's UI, you can still rely on the platform to provide density abstraction, which means that applications do not need to compensate for the differences in actual pixel density across devices. You can design the application UI according to the amount of horizontal or vertical space available. The platform expresses the amount of space available using three new characteristics: smallestWidth, width, and height.
The new screens support API is designed to let you manage application UI according to the smallestWidth of the current screen. You can also manage the UI according to current width or height, as needed. For those purposes, the API provides these tools:
Additionally, applications can still query the system and manage UI and resource loading at runtime, as in the previous versions of the platform.
Since the new API lets you target screens more directly through smallestWidth, width, and height, it's helpful to understand the typical characteristics of the different screen types. The table below provides some examples, measured in "dp" units.
Type | Density (generalized) | Dimensions (dp) | smallestWidth (dp) |
---|---|---|---|
Baseline phone | mdpi | 320x480 | 320 |
Small tablet/large phone | mdpi | 480x800 | 480 |
7-inch tablet | mdpi | 600x1024 | 600 |
10-inch tablet | mdpi | 800x1280 | 800 |
The sections below provide more information about the new screen qualifiers and manifest attributes. For complete information about how to use the screen support API, see Supporting Multiple Screens.
The new resource qualifiers in Android 3.2 let you better target your layouts for ranges of screen sizes. Using the qualifiers, you can create resource configurations designed for a specific minimum smallestWidth, current width, or current height, measured in density-independent pixels.
The new qualifiers are:
swNNNdp
— Specifies the minimum smallestWidth on which
the resource should be used, measured in "dp" units. As mentioned above, a
screen's smallestWidth is constant, regardless of orientation. Examples:
sw320dp
, sw720dp
, sw720dp
.wNNNdp
and hNNNdp
— Specifies the minimum
width or height on which the resource should be used, measured in "dp" units. As
mentioned above, a screen's width and height are relative to the orientation of
the screen and change whenever the orientation changes. Examples:
w320dp
, w720dp
, h1024dp
.You can also create multiple overlapping resource configurations if needed. For example, you could tag some resources for use on any screen wider than 480 dp, others for wider than 600 dp, and others for wider than 720 dp. When multiple resource configurations are qualified for a given screen, the system selects the configuration that is the closest match. For precise control over which resources are loaded on a given screen, you can tag resources with one qualifier or combine several new or existing qualifiers.
Based on the typical dimensions listed earlier, here are some examples of how you could use the new qualifiers:
res/layout/main_activity.xml # For phones res/layout-sw600dp/main_activity.xml # For 7” tablets res/layout-sw720dp/main_activity.xml # For 10” tablets res/layout-w600dp/main_activity.xml # Multi-pane when enough width res/layout-sw600dp-w720dp/main_activity.xml # For large width
Older versions of the platform will ignore the new qualifiers, so you can mix them as needed to ensure that your app looks great on any device. Here are some examples:
res/layout/main_activity.xml # For phones res/layout-xlarge/main_activity.xml # For pre-3.2 tablets res/layout-sw600dp/main_activity.xml # For 3.2 and up tablets
For complete information about how to use the new qualifiers, see Using new size qualifiers.
The framework offers a new set of <supports-screens>
manifest attributes that let
you manage your app's support for different screen sizess.
Specifically, you can specify the largest and smallest screens on which your app
is designed to run, as well as the largest screen on which it is designed run
without needing the system's new screen
compatibility mode. Like the resource qualifiers described above, the new
manifest attributes specify the range of screens that the application supports,
as specified by the smallestWidth.
The new manifest attributes for screen support are:
android:compatibleWidthLimitDp="numDp"
— This
attribute lets you specify the maximum smallestWidth on which the application
can run without needing compatibility mode. If the current screen is larger than
the value specified, the system displays the application in normal mode but
allows the user to optionally switch to compatibility mode through a setting in
the system bar.android:largestWidthLimitDp="numDp"
— This
attribute lets you specify the maximum smallestWidth on which the application
is designed to run. If the current screen is larger than the value specified,
the system forces the application into screen compatibility mode, to ensure best
display on the current screen.android:requiresSmallestWidthDp="numDp"
— This
attribute lets you specify the minimum smallestWidth on which the application
can run. If the current screen is smaller than the value specified, the system
considers the application incompatible with the device, but does not prevent it
from being installed and run.Note: Android Market does not currently filter
apps based on any of the attributes above. Support for filtering will be
added in a later platform release. Applications that require
filtering based on screen size can use the existing <supports-screens>
attributes.
For complete information about how to use the new attributes, see Declaring screen size support.
Android 3.2 provides a new screen compatibility mode for applications explicitly declaring that they do not support screens as large as the one on which they are running. This new "zoom" mode is a pixel-scaled — it renders the application in a smaller screen area and then scales the pixels to fill the current screen.
By default, the system offers screen compatibility mode as an user option, for apps that require it. Users can turn the zoom mode on and off using a control available in the system bar.
Because the new screen compatibility mode may not be appropriate for all applications, the platform allows the application to disable it using manifest attributes. When disabled by the app, the system does not offer "zoom" compatibility mode as an option for users when the app is running.
Note: For important information about how to control compatibility mode in your applications, please review the New Mode for Apps on Large Screens article on the Android Developers Blog.
To meet the needs of applications running on 720p televisions or similar with
moderate density screens, Android 3.2 introduces a new generalized density,
tvdpi
, with an approximate dpi of 213. Applications can query for
the new density in {@link android.util.DisplayMetrics#densityDpi} and can use
the new tvdpi
qualifier to tag resources for televisions and
similar devices. For example:
res/drawable-tvdpi/my_icon.png # Bitmap for tv density
In general, applications should not need to work with this density. For situations where output is needed for a 720p screen, the UI elements can be scaled automatically by the platform.
<supports-screens>
attributes
in the application manifest file.The platform adds new hardware feature constants that you can declare in their application manifests, to inform external entities such as Android Market of required hardware and software capabilities. You declare these and other feature constants in {@code <uses-feature>} manifest elements.
Android Market filters applications based on their <uses-feature>
attributes, to ensure that they are available only to devices on which their requirements are met.
Android 3.2 introduces new feature constants that let applications specify whether they require display in landscape orientation, portrait orientation, or both. Declaring these constants indicates that the application must not be installed on a device that doesn't offer the associated orientation. Conversely, if one or both of the constants are not declared, it indicates that the application does not have a preference for the undeclared orientations and may be installed on a device that doesn't offer them.
A typical application that functions properly in both landscape and portrait orientations would not normally need to declare an orientation requirement. Rather, an application designed primarily for one orientation, such as an app designed for a television, could declare one of the constants to ensure that it isn't available to devices that don't provide that orientation.
If any of activities declared in the manifest request that they run in a specific orientation, using the {@code android:screenOrientation} attribute, then this also declares that the application requires that orientation.
For a detailed view of all API changes in Android {@sdkPlatformVersion} (API Level {@sdkPlatformApiLevel}), see the API Differences Report.
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.
The system image included in the downloadable platform provides these built-in applications:
|
|
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).
|
|
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.
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.