Welcome to the Android developers community! We're glad you're here and invite you to participate in these discussions. Before posting, please read the Groups Charter that covers the community guidelines.
+
Community
+
Welcome to the Android developers community! We're glad you're here and invite you to participate in these discussions. Before posting, please read the Groups Charter that covers the community guidelines.
Note: If you are seeking discussion about Android source code (not application development),
then please refer to the Open Source Project Mailing lists.
@@ -53,48 +53,42 @@ phrasing your questions, read android-beginners
-
Android developers - You're now an experienced Android application developer. You've grasped the basics of Android app development, you're comfortable using the SDK, now you want to move to advanced topics. Get help here with troubleshooting applications, advice on implementation, and strategies for improving your application's performance and user experience. This is the not the right place to discuss user issues (use android-discuss for that) or beginner questions with the Android SDK (use android-beginners for that).
Android discuss - The "water cooler" of Android discussion. You can discuss just about anything Android-related here, ideas for the Android platform, announcements about your applications, discussions about Android devices, community resources... As long as your discussion is related to Android, it's on-topic here. However, if you have a discussion here that could belong on another list, you are probably not reaching all of your target audience here and may want to consider shifting to a more targeted list.
Android security discuss - A place for open discussion on secure development, emerging security concerns, and best practices for and by android developers. Please don't disclose vulnerabilities directly on this list, you'd be putting all Android users at risk.
diff --git a/docs/html/guide/appendix/api-levels.jd b/docs/html/guide/appendix/api-levels.jd
index 8fc899bb4cc2..cebd2d43891a 100644
--- a/docs/html/guide/appendix/api-levels.jd
+++ b/docs/html/guide/appendix/api-levels.jd
@@ -1,81 +1,348 @@
page.title=Android API Levels
@jd:body
+
+
-
The Android API Level is an integer that indicates a set of APIs available in an Android SDK
-and on a version of the Android platform. Each version of the Android platform supports a specific set
-of APIs, which are always backward-compatible. For example, Android 1.5 supports all APIs available in
-Android 1.0, but the reverse is not true. If an application uses APIs
-available in Android 1.5 that are not available in 1.0, then the application should never be installed
-on an Android 1.0 device, because it will fail due to missing APIs. The API Level ensures this does not happen
-by comparing the minimum API Level required by the applicaiton to the API Level available on the device.
-
-
When a new version of Android adds APIs, a new API Level is added to the platform. The new APIs
-are available only to applications that declare a minimum API Level that is equal-to or greater-than
-the API Level in which the APIs were introduced. The API Level required by an application is declared with the
-<uses-sdk> element inside the Android manifest, like this:
-
-
<uses-sdk android:minSdkVersion="3" />
-
-
The value for minSdkVersion is the minimum API Level required by the application.
-If this is not declared, then it is assumed that the application is compatible with all versions and defaults to
-API Level 1. In which case, if the application actually uses APIs introduced with an API Level greater than 1, then
-the application will fail in unpredictable ways when installed on a device that only supports API Level 1
-(such as an Android 1.0 device).
-See the <uses-sdk>
-documentation for more about declaring the API Level in your manifest.
-
-
For example, the {@link android.appwidget} package was introduced with API Level 3. If your application
-has set minSdkVersion to 1 or 2, then your application cannot use this package,
-even if the device running your application uses a version of Android that supports it.
-In order to use the {@link android.appwidget} package, your application must set minSdkVersion
-to 3 or higher. When the minSdkVersion is set to 3, the application will no longer be able to install
-on a device running a platform version with an API Level less than 3.
-
-
Despite the name of the manifest attribute (minSdkVersion), the API Level is not directly
-associated with a specific SDK. For example, the SDK for Android 1.0 uses
-API Level 1 and the SDK for Android 1.1 uses API Level 2. So it may seem that the API Level increases consistently.
-However, it's possible that a subsequent platform
-releases will not introduce new APIs, and thus, the API Level will remain the same. In addition, there are often
-multiple SDK releases for a single platform version (there were three SDK releases for Android 1.5), and
-there's no guarantee that the API Level will remain the same between these. It's possible (but unlikely) that
-a second or third SDK for a given version of the platform will provide new APIs and add a new API Level.
-When you install a new SDK, be sure to read the SDK Contents on the install page, which specifies the API
-Level for each platform available in the SDK. Also see the comparison of
-Platform Versions vs. API Levels, below.
-
-
Note: During an "Early Look" SDK release, the APIs may not be final, so the
-API Level number cannot be specified. In this case, a string value matching the
-platform codename must be used as the value for minSdkVersion. This codename value
-will only be valid while using the Early Look SDK with the emulator. An application using this API Level
-can never be installed on an Android device. When the final SDK is released, you must update your manifest to use
-the official API Level integer.
-
-
Platform Versions vs. API Levels
-
-
The following table specifies the maximum API Level supported by each version of the Android platform.
-(Every platform is backward-compatible to API Level 1.)
As you develop your application on Android, it's useful to understand the
+platform's general approach to API change management. It's also important to
+understand the API Level identifier and the role it plays in ensuring your
+application's compatibility with devices on which it may be installed.
+
+
The sections below provide information about API Level and how it affects
+your applications.
+
+
For information about how to use the "Filter by API Level" control
+available in the API reference documentation, see
+Filtering the documentation at the
+end of this document.
+
+
What is API Level?
+
+
API Level is an integer value that uniquely identifies the framework API
+revision offered by a version of the Android platform.
+
+
The Android platform provides a framework API that applications can use to
+interact with the underlying Android system. The framework API consists of:
+
+
+
A core set of packages and classes
+
A set of XML elements and attributes for declaring a manifest file
+
A set of XML elements and attributes for declaring and accessing resources
+
A set of Intents
+
A set of permissions that applications can request, as well as permission
+enforcements included in the system
+
+
+
Each successive version of the Android platform can include updates to the
+Android application framework API that it delivers.
+
+
Updates to the framework API are designed so that the new API remains
+compatible with earlier versions of the API. That is, most changes in the API
+are additive and introduce new or replacement functionality. As parts of the API
+are upgraded, the older replaced parts are deprecated but are not removed, so
+that existing applications can still use them. In a very small number of cases,
+parts of the API may be modified or removed, although typically such changes are
+only needed to ensure API robustness and application or system security. All
+other API parts from earlier revisions are carried forward without
+modification.
+
+
The framework API that an Android platform delivers is specified using an
+integer identifier called "API Level". Each Android platform version supports
+exactly one API Level, although support is implicit for all earlier API Levels
+(down to API Level 1). The initial release of the Android platform provided
+API Level 1 and subsequent releases have incremented the API Level.
+
+
The following table specifies the API Level supported by each version of the
+Android platform.
Platform Version
API Level
-
Android 1.0
1
-
Android 1.1
2
+
Android 2.0
5
+
Android 1.6
4
Android 1.5
3
-
Android Donut
Donut
+
Android 1.1
2
+
Android 1.0
1
-
Viewing the API Reference Based on API Level
+
Uses of API Level in Android
+
+
The API Level identifier serves a key role in ensuring the best possible
+experience for users and application developers:
+
+
+
It lets the Android platform describe the maximum framework API revision
+that it supports
+
It lets applications describe the framework API revision that they
+require
+
It lets the system negotiate the installation of applications on the user's
+device, such that version-incompatible applications are not installed.
+
+
+
Each Android platform version stores its API Level identifier internally, in
+the Android system itself.
+
+
Applications can use a manifest element provided by the framework API —
+<uses-sdk> — to describe the minimum and maximum API
+Levels under which they are able to run, as well as the preferred API Level that
+they are designed to support. The element offers two key attributes:
+
+
+
android:minSdkVersion — Specifies the minimum API Level
+on which the application is able to run. The default value is "1".
+
android:targetSdkVersion — Specifies the API Level
+on which the application is designed to run. In some cases, this allows the
+application to use manifest elements or behaviors defined in the target
+API Level, rather than being restricted to using only those defined
+for the minimum API Level.
+
android:maxSdkVersion — Specifies the maximum API Level
+on which the application is able to run.
+
+
+
For example, to specify the minimum system API Level that an application
+requires in order to run, the application would include in its manifest a
+<uses-sdk> element with a android:minSdkVersion
+attribute. The value of android:minSdkVersion would be the integer
+corresponding to the API Level of the earliest version of the Android platform
+under which the application can run.
+
+
When the user attempts to install an application, the Android system first
+checks the <uses-sdk> attributes in the application's
+manifest and compares them against its own internal API Level. The system
+allows the installation to begin only if these conditions are met:
+
+
+
If a android:minSdkVersion attribute is declared, its value
+must be less than or equal to the system's API Level integer. If not declared,
+the system assumes that the application requires API Level 1.
+
If a android:maxSdkVersion attribute is declared, its value
+must be equal to or greater than the system's API Level integer.
+If not declared, the system assumes that the application
+has no maximum API Level.
+
+
+
When declared in an application's manifest, a <uses-sdk>
+element might look like this:
The principal reason that an application would declare an API Level in
+android:minSdkVersion is to tell the Android system that it is
+using APIs that were introduced in the API Level specified. If the
+application were to be somehow installed on a platform with a lower API Level,
+then it would crash at run-time when it tried to access APIs that don't exist.
+The system prevents such an outcome by not allowing the application to be
+installed if the lowest API Level it requires is higher than that of the
+platform version on the target device.
+
+
For example, the {@link android.appwidget} package was introduced with API
+Level 3. If an application uses that API, it must declare a
+android:minSdkVersion attribute with a value of "3". The
+application will then be installable on platforms such as Android 1.5 (API Level
+3) and Android 1.6 (API Level 4), but not on the Android 1.1 (API Level 2) and
+Android 1.0 platforms (API Level 1).
+
+
For more information about how to specify an application's API Level
+requirements, see the <uses-sdk>
+ section of the manifest file documentation.
+
+
+
Development Considerations
+
+
The sections below provide information related to API level that you should
+consider when developing your application.
+
+
Application forward compatibility
+
+
Android applications are generally forward-compatible with new versions of
+the Android platform.
+
+
Because almost all changes to the framework API are additive, an Android
+application developed using any given version of the API (as specified by its
+API Level) is forward-compatible with later versions of the Android platform and
+higher API levels. The application should be able to run on all later versions
+of the Android platform, except in isolated cases where the application uses a
+part of the API that is later removed for some reason.
+
+
Forward compatibility is important because many Android-powered devices
+receive over-the-air (OTA) system updates. The user may install your
+application and use it successfully, then later receive an OTA update to a new
+version of the Android platform. Once the update is installed, your application
+will run in a new run-time version of the environment, but one that has the API
+and system capabilities that your application depends on.
+
+
In some cases, changes below the API, such those in the underlying
+system itself, may affect your application when it is run in the new
+environment. For that reason it's important for you, as the application
+developer, to understand how the application will look and behave in each system
+environment. To help you test your application on various versions of the Android
+platform, the Android SDK includes multiple platforms that you can download.
+Each platform includes a compatible system image that you can run in an AVD, to
+test your application.
+
+
Application backward compatibility
+
+
Android applications are not necessarily backward compatible with versions of
+the Android platform older than the version against which they were compiled.
+
+
+
Each new version of the Android platform can include new framework APIs, such
+as those that give applications access to new platform capabilities or replace
+existing API parts. The new APIs are accessible to applications when running on
+the new platform and, as mentioned above, also when running on later versions of
+the platform, as specified by API Level. Conversely, because earlier versions of
+the platform do not include the new APIs, applications that use the new APIs are
+unable to run on those platforms.
+
+
Although it's unlikely that an Android-powered device would be downgraded to
+a previous version of the platform, it's important to realize that there are
+likely to be many devices in the field that run earlier versions of the
+platform. Even among devices that receive OTA updates, some might lag and
+might not receive an update for a significant amount of time.
+
+
Selecting a platform version and API Level
+
+
When you are developing your application, you will need to choose
+the platform version against which you will compile the application. In
+general, you should compile your application against the lowest possible
+version of the platform that your application can support.
+
+
You can determine the lowest possible platform version by compiling the
+application against successively lower build targets. After you determine the
+lowest version, you should create an AVD using the corresponding platform
+version (and API Level) and fully test your application. Make sure to declare a
+android:minSdkVersion attribute in the application's manifest and
+set its value to the API Level of the platform version.
+
+
Declaring a minimum API Level
+
+
If you build an application that uses APIs or system features introduced in
+the latest platform version, you should set the
+android:minSdkVersion attribute to the API Level of the latest
+platform version. This ensures that users will only be able to install your
+application if their devices are running a compatible version of the Android
+platform. In turn, this ensures that your application can function properly on
+their devices.
+
+
If your application uses APIs introduced in the latest platform version but
+does not declare a android:minSdkVersion attribute, then
+it will run properly on devices running the latest version of the platform, but
+not on devices running earlier versions of the platform. In the latter
+case, the application will crash at runtime when it tries to use APIs that don't
+exist on the earlier versions.
+
+
Testing against higher API Levels
+
+
After compiling your application, you should make sure to test it on the
+platform specified in the application's android:minSdkVersion
+attribute. To do so, create an AVD that uses the platform version required by
+your application. Additionally, to ensure forward-compatibility, you should run
+and test the application on all platforms that use a higher API Level than that
+used by your application.
+
+
The Android SDK includes multiple platform versions that you can use,
+including the latest version, and provides an updater tool that you can use to
+download other platform versions as necessary.
+
+
To access the updater, use the android command-line tool,
+located in the <sdk>/tools directory. You can launch the Updater by using
+the android command without specifying any options. You can
+also simply double-click the android.bat (Windows) or android (OS X/Linux) file.
+In ADT, you can also access the updater by selecting
+Window > Android SDK and AVD
+Manager.
+
+
To run your application against different platform versions in the emulator,
+create an AVD for each platform version that you want to test. For more
+information about AVDs, see Android Virtual Devices. If
+you are using a physical device for testing, ensure that you know the API Level
+of the Android platform it runs. See the table at the top of this document for
+a list of platform versions and their API Levels.
+
+
+
Using a Provisional API Level
+
+
In some cases, an "Early Look" Android SDK platform may be available. To let
+you begin developing on the platform although the APIs may not be final, the
+platform's API Level integer will not be specified. You must instead use the
+platform's provisional API Level in your application manifest, in order
+to build applications against the platform. A provisional API Level is not an
+integer, but a string matching the codename of the unreleased platform version.
+The provisional API Level will be specified in the release notes for the Early
+Look SDK release notes and is case-sensitive.
+
+
The use of a provisional API Level is designed to protect developers and
+device users from inadvertently publishing or installing applications based on
+the Early Look framework API, which may not run properly on actual devices
+running the final system image.
+
+
The provisional API Level will only be valid while using the Early Look SDK
+and can only be used to run applications in the emulator. An application using
+the provisional API Level can never be installed on an Android device. At the
+final release of the platform, you must replace any instances of the provisional
+API Level in your application manifest with the final platform's actual API
+Level integer.
+
+
+
Filtering the Reference Documentation by API Level
-
The Android API reference includes information that specififies the minimum API Level required for each
-package, class, and member. You can see this information on the right side of each header or label.
+
Reference documentation pages on the Android Developers site offer a "Filter
+by API Level" control in the top-right area of each page. You can use the
+control to show documentation only for parts of the API that are actually
+accessible to your application, based on the API Level that it specifies in
+the android:minSdkVersion attribute of its manifest file.
-
By default, the reference documentation shows all APIs available with the latest SDK release.
-This means that the reference assumes you're using the latest API Level and will show you everything available
-with it. If you're developing applications for a version of Android that does not support the latest API Level,
-then you can filter the reference to reveal only the packages, classes, and members available for that API Level.
-When viewing the reference, use the "Filter by API Level" selection box (below the search box) to pick the API Level
-you'd like to view.
+
To use filtering, select the checkbox to enable filtering, just below the
+page search box. Then set the "Filter by API Level" control to the same API
+Level as specified by your application. Notice that APIs introduced in a later
+API Level are then grayed out and their content is masked, since they would not
+be accessible to your application.
+
Filtering by API Level in the documentation does not provide a view
+of what is new or introduced in each API Level — it simply provides a way
+to view the entire API associated with a given API Level, while excluding API
+elements introduced in later API Levels.
+
If you decide that you don't want to filter the API documentation, just
+disable the feature using the checkbox. By default, API Level filtering is
+disabled, so that you can view the full framework API, regardless of API Level.
+
+
Also note that the reference documentation for individual API elements
+specifies the API Level at which each element was introduced. The API Level
+for packages and classes is specified as "Since <api level>" at the
+top-right corner of the content area on each documentation page. The API Level
+for class members is specified in their detailed description headers,
+at the right margin.
diff --git a/docs/html/guide/appendix/faq/commontasks.jd b/docs/html/guide/appendix/faq/commontasks.jd
index 0f89e7534a68..e88a8672e98a 100644
--- a/docs/html/guide/appendix/faq/commontasks.jd
+++ b/docs/html/guide/appendix/faq/commontasks.jd
@@ -56,7 +56,7 @@ href="{@docRoot}guide/topics/fundamentals.html">Application Fundamentals
to understand the basics of how an Android application works.
You should also take a look at the ApiDemos application and the other sample
-applications included in the SDK, in the <sdk>/samples/
+applications included in the SDK, in the <sdk>/samples/
folder in the SDK.
Finally, a great way to started with Android development in Eclipse is to
@@ -281,6 +281,15 @@ protected void onActivityResult(int requestCode, int resultCode, Intent data){
//Hide the title bar
requestWindowFeature(Window.FEATURE_NO_TITLE);
+
A better way to achieve the same end is to specify a theme in your Android
+Manifest file:
This is preferable because it tells the system not to show a title bar while
+your application is starting up. With the explicit method call, your application
+will have a title bar visible to the user until onCreate runs.
+
(Note that this can be applied to either the <application>
+tag or to individual <activity> tags.)
Referring to localhost from the emulated environment
If you need to refer to your host computer's localhost, such as when you
@@ -427,7 +436,7 @@ user receiving new e-mail.
Activity
By setting the theme of an activity to
{@link android.R.style#Theme_Dialog
- android:theme="android:style/Theme.Dialog"},
+ android:theme="@android:style/Theme.Dialog"},
your activity will take on
the appearance of a normal dialog, floating on top of whatever was
underneath it. You usually set the theme through the
diff --git a/docs/html/guide/developing/device.jd b/docs/html/guide/developing/device.jd
index 5a2a751b4ab5..8fa4cec17311 100644
--- a/docs/html/guide/developing/device.jd
+++ b/docs/html/guide/developing/device.jd
@@ -11,8 +11,16 @@ page.title=Developing on a Device
@@ -117,27 +125,36 @@ would on the emulator. There are just a few things to do before you can start.
Turn on "USB Debugging" on your device.
On the device, go to the home screen, press MENU, select Applications > Development,
then enable USB debugging.
-
Setup your system to detect your device.
-
If you're developing on Windows, you need to install a USB driver for adb.
- Follow the steps below for Installing the WinUsb Driver.
+
If you're developing on Windows, you need to install a USB driver
+ for adb. See the Windows USB
+ Driver documentation.
If you're developing on Mac OS X, it just works. Skip this step.
-
If you're developing on Ubuntu Linux, you need to add a rules file:
+
If you're developing on Ubuntu Linux, you need to add a rules file
+that contains a USB configuration for each type of device you want to use for
+development. Each device manufacturer uses a different vendor ID. The
+example rules files below show how to add an entry for a single vendor ID
+(the HTC vendor ID). In order to support more devices, you will need additional
+lines of the same format that provide a different value for the
+SYSFS{idVendor} property. For other IDs, see the table of USB Vendor IDs, below.
-
Login as root and create this file: /etc/udev/rules.d/51-android.rules.
-
For Gusty/Hardy, edit the file to read:
- SUBSYSTEM=="usb", SYSFS{idVendor}=="0bb4", MODE="0666"
-
-
For Dapper, edit the file to read:
- SUBSYSTEM=="usb_device", SYSFS{idVendor}=="0bb4", MODE="0666"
+
Log in as root and create this file:
+ /etc/udev/rules.d/51-android.rules.
+
For Gusty/Hardy, edit the file to read:
+ SUBSYSTEM=="usb", SYSFS{idVendor}=="0bb4",
+ MODE="0666"
+
+
For Dapper, edit the file to read:
+ SUBSYSTEM=="usb_device", SYSFS{idVendor}=="0bb4",
+ MODE="0666"
Now execute:
- chmod a+rx /etc/udev/rules.d/51-android.rules
+ chmod a+r /etc/udev/rules.d/51-android.rules
-
@@ -149,157 +166,30 @@ with a Device Chooser dialog that lists the available emulator(s) and con
Select the device to install and run the application there.
If using the Android Debug Bridge (adb),
-you can issue commands with the -d flag to target your connected device.
-
-
-
-
-
Installing the WinUsb Driver
-
-
A WinUsb-based driver is needed in order to use your Android-powered device for development on a Windows machine.
-The USB installation package can be found in the <sdk>\usb_driver\
-folder of your SDK package.
-
-
Note: If you are connecting an Android-powered device to your computer
-for the first time, folllow the procedure to "Perform a fresh installation."
-Android SDKs older than version 1.6 included a non-WinUsb-based driver
-for connecting your device. If you installed the older USB driver and it is working properly,
-you do not need to upgrade to the new driver. However, if you are having problems with the driver or
-would simply like to upgrade to the latest version, follow the procedure to "Upgrade an existing
-driver."
-
-
Before you begin installing or upgrading the USB driver, you must
-copy the USB installation package to a secure location on your computer.
-For example, you might want to create a directory at C:\Android\Windows\USB\install\ and
-move it there. Once you've moved the installation package, select the appropriate procedure below,
-based on your operating system and whether you're installing for the first time or upgrading.
Caution:
-You may make changes to android_winusb.inf file found inside usb_driver\
-(e.g., to add support for new devices),
-however, this will lead to security warnings when you install or upgrade the
-driver. Making any other changes to the driver files may break the installation process.
-
-
Windows Vista: Perform a fresh installation
-
-
To install the Android USB driver on Windows Vista for the first time:
-
-
-
Connect your Android-powered device to your computer's USB port. Windows will detect the device
- and launch the Found New Hardware wizard.
-
Select "Locate and install driver software."
-
Select "Don't search online."
-
Select "I don't have the disk. Show me other options."
-
Select "Browse my computer for driver software."
-
Click "Browse..." and locate the folder where you copied the
- installation package. As long as you specified the exact location of the
- installation package, you may leave "Include subfolders" checked or unchecked—it doesn't matter.
-
Click "Next." Vista may prompt you to confirm the privilege elevation required for driver
- installation. Confirm it.
-
When Vista asks if you'd like to install the Google ADB Interface device, click "Install"
- to install the driver.
To upgrade an existing Android USB driver on Windows Vista with the new one:
-
-
-
Connect your Android-powered device to your computer's USB port.
-
Right-click on "Computer" from your desktop or Windows Explorer,
- and select "Manage."
-
Select "Device Manager" in the left pane of the Computer Management window.
-
Locate and expand "ADB Interface" in the right pane.
-
Right-click on "HTC Dream Composite ADB Interface", and select "Update Driver Software..."
-
When Vista starts updating the driver, a prompt will ask how you want to search for the driver
- software. Select "Browse my computer for driver software."
-
Click "Browse..." and locate the folder where you copied the
- installation package. As long as you specified the exact location of the
- installation package, you may leave "Include subfolders" checked or unchecked—it doesn't matter.
-
Click "Next." Vista may prompt you to confirm the privilege elevation required for driver
- installation. Confirm it.
-
When Vista asks if you'd like to install the Google ADB Interface device, click "Install"
- to install the driver.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+you can issue commands with the -d flag to target your
+connected device.
+
+
+
USB Vendor IDs
+
This table provides a reference to the vendor IDs needed in order to add
+device support on Linux. The USB Vendor ID is the value given to the
+SYSFS{idVendor} property in the rules file.
+
+
+
Manufacturer
USB Vendor ID
+
+
Acer
0502
+
+
HTC
0bb4
+
+
Huawei
12d1
+
+
LG
1004
+
+
Motorola
22b8
+
+
Samsung
04e8
+
+
Sony Ericsson
0fce
+
diff --git a/docs/html/guide/developing/eclipse-adt.jd b/docs/html/guide/developing/eclipse-adt.jd
index a5cf7358500c..667aa9f9cd4c 100644
--- a/docs/html/guide/developing/eclipse-adt.jd
+++ b/docs/html/guide/developing/eclipse-adt.jd
@@ -38,12 +38,12 @@ manifest and resource files.
To begin developing Android applications in the Eclipse IDE with ADT, you first need to
download the Eclipse IDE and then download and install the ADT plugin. To do so, follow the
-steps given in Installing
+steps given in Installing
the ADT Plugin.
If you are already developing applications using a version of ADT earlier than 0.9, make
sure to upgrade to the latest version before continuing. See the guide to
-Updating Your Eclipse ADT Plugin.
Note: This guide assumes you are using the latest version of
the ADT plugin. While most of the information covered also applies to previous
@@ -149,15 +149,15 @@ on running your applicaiton.
Creating an AVD
-
With ADT 0.9.2 and above, the Android AVD Manager provides a simple graphical interface
+
With ADT 0.9.3 and above, the Android SDK and AVD Manager provides a simple graphical interface
for creating and managing AVDs. (If you're using ADT version 0.9.1 or older, you must
use the android tool to create your AVDs—read the AVD guide to
Creating an AVD.)
-
To create an AVD with the Android AVD Manager:
+
To create an AVD with the AVD Manager:
-
Select Window > Android AVD Manager, or click the Android AVD Manager icon (a black device)
+
Select Window > Android SDK and AVD Manager, or click the Android SDK and AVD Manager icon (a black device)
in the Eclipse toolbar.
In the Virtual Devices panel, you'll see a list of existing AVDs. Click New
@@ -169,7 +169,7 @@ use the android tool to create your AVDs—read the AVD guide t
Click Create AVD.
-
Your AVD is now ready and you can close the Android AVD Manager.
+
Your AVD is now ready and you can close the AVD Manager.
In the next section, you'll see how the AVD is used
when launching your application on an emulator.
@@ -217,7 +217,7 @@ to start, the emulator options to use, and so on. When you first run a project
as an Android Application, ADT will automatically create a run configuration.
The default run configuration will
launch the default project Activity and use automatic target mode for device selection
-(with no preferred AVD). If the default setting don't suit your project, you can
+(with no preferred AVD). If the default settings don't suit your project, you can
customize the launch configuration or even create a new.
To create or modify a launch configuration, follow these steps as appropriate
@@ -256,6 +256,12 @@ for your Eclipse version:
You can specify any emulator options to the Additional Emulator Command
+ Line Options field. For example, you could add -scale 96dpi to
+ scale the AVD's screen to an accurate size, based on the dpi of your
+ computer monitor. For a full list of emulator options, see the Android Emulator
+document.
diff --git a/docs/html/guide/developing/other-ide.jd b/docs/html/guide/developing/other-ide.jd
index 8cdf0b91d7b8..2080873eaf58 100644
--- a/docs/html/guide/developing/other-ide.jd
+++ b/docs/html/guide/developing/other-ide.jd
@@ -85,7 +85,8 @@ command to generate all the necessary files and folders.
navigate to the tools/ directory of your SDK and run:
android create project \
---target <targetID> \
+--target <target_ID> \
+--name <your_project_name> \
--path /path/to/your/project \
--activity <your_activity_name> \
--package <your_package_namespace>
@@ -96,11 +97,14 @@ android create project \
to an Android platform library (including any add-ons, such as Google APIs) that you would like to
build your project against. To see a list of available targets and their corresponding IDs,
execute: android list targets.
+
name is the name for your project. This is optional. If provided, this name will be used
+ for your .apk filename when you build your application.
path is the location of your project directory. If the directory does not exist,
it will be created for you.
-
activity is the name for your {@link android.app.Activity} class. This class file
+
activity is the name for your default {@link android.app.Activity} class. This class file
will be created for you inside
- <path_to_your_project>/src/<your_package_namespace_path>/.
+ <path_to_your_project>/src/<your_package_namespace_path>/.
+ This will also be used for your .apk filename unless you provide a the name.
package is the package namespace for your project, following the same rules as for
packages in the Java programming language.
The tool generates the following files and directories:
@@ -123,7 +128,8 @@ android create project \
default.properties - Properties for the build system. Do not modify
this file.
build.properties - Customizable properties for the build system. You can edit this
- file to overried default build settings used by Ant.
+ file to override default build settings used by Ant and provide a pointer to your keystore and key alias
+ so that the build tools can sign your application when built in release mode.
src/your/package/namespace/ActivityName.java - The Activity class
you specified during project creation.
Before you start building your application in release mode, be aware that you must sign
+the resulting application package with your private key, and should then align it using the
+{@code zipalign} tool. There are two approaches to building in release mode:
+build an unsigned package in release mode and then manually sign and align
+the package, or allow the build script
+to sign and align the package for you.
+
+
Build unsigned
+
+
If you build your application unsigned, then you will need to
+manually sign and align the package.
+
+
To build an unsigned .apk in release mode:
Open a command-line and navigate to the root of your project directory.
Use Ant to compile your project in release mode:
ant release
-
This creates your Android application .apk file inside the project bin/
- directory, named <your_DefaultActivity_name>.apk.
-
Note: The .apk file is unsigned at this point.
- You can't install it on an emulator or device until you sign it with your private key.
-
Because release mode builds your application unsigned, your next step is to sign
-it with your private key, in order to distribute it to end-users. To complete this procedure,
+
This creates your Android application .apk file inside the project bin/
+directory, named <your_project_name>-unsigned.apk.
+
+
Note: The .apk file is unsigned at this point
+and can't be installed until signed with your private key.
+
+
Once you have created the unsigned .apk, your next step is to sign the .apk
+with your private key and then align it with {@code zipalign}. To complete this procedure,
read Signing Your Applications.
+
When your .apk has been signed and aligned, it's ready to be distributed to end-users.
+
+
Build signed and aligned
+
+
If you would like, you can configure the Android build script to automatically
+sign and align your application package. To do so, you must provide the path to your keystore
+and the name of your key alias in your project's {@code build.properties} file. With this
+information provided, the build script will prompt you for your keystore and alias password
+when you build in release mode and produce your final application package, which will be ready
+for distribution.
+
+
Caution: Due to the way Ant handles input, the password that
+you enter during the build process will be visible. If you are
+concerned about your keystore and alias password being visible on screen, then you
+may prefer to perform the application signing manually, via Jarsigner (or a similar tool). To instead
+perform the signing procedure manually, buid unsigned and then continue
+with Signing Your Applications.
+
+
To specify your keystore and alias, open the project {@code build.properties} file (found in the
+root of the project directory) and add entries for {@code key.store} and {@code key.alias}.
+For example:
Save your changes. Now you can build a signed .apk in release mode:
+
+
+
Open a command-line and navigate to the root of your project directory.
+
Use Ant to compile your project in release mode:
+
ant release
+
+
When prompted, enter you keystore and alias passwords.
+
Caution: As described above,
+ your password will be visible on the screen.
+
+
+
+
This creates your Android application .apk file inside the project bin/
+directory, named <your_project_name>-release.apk.
+This .apk file has been signed with the private key specified in
+{@code build.properties} and aligned with {@code zipalign}. It's ready for
+installation and distribution.
+
+
+
Once built and signed in release mode
+
Once you have signed your application with a private key, you can install it on an
emulator or device as discussed in the following section about
Running Your Application.
@@ -329,7 +402,7 @@ id:2
you'll use this in the next step.
Create a new AVD using your selected deployment target:
-
Next, you'll be asked whether you'd like to create a custom hardware profile.
If you respond "yes," you'll be presented with a series of prompts to define various aspects of the
device hardware (leave entries blank to use default values, which are shown in brackets). Otherwise,
diff --git a/docs/html/guide/developing/tools/adb.jd b/docs/html/guide/developing/tools/adb.jd
index b111047e60bf..e8c726f8cdc9 100644
--- a/docs/html/guide/developing/tools/adb.jd
+++ b/docs/html/guide/developing/tools/adb.jd
@@ -313,7 +313,7 @@ emulator-5558 device
<tty> — the tty for PPP stream. For example dev:/dev/omap_csmi_ttyl.
[parm]... &mdash zero or more PPP/PPPD options, such as defaultroute, local, notty, etc.
-
Note that you should not automatically start a PDP connection.
+
Note that you should not automatically start a PPP connection.
Make your class implement the {@link android.os.Parcelable} interface.
Implement the method public void writeToParcel(Parcel out) that takes the
current state of the object and writes it to a parcel.
-
Implement the method public void readFromParcel(Parcel in) that reads the
value in a parcel into your object.
Add a static field called CREATOR to your class which is an object implementing
the {@link android.os.Parcelable.Creator Parcelable.Creator} interface.
diff --git a/docs/html/guide/developing/tools/avd.jd b/docs/html/guide/developing/tools/avd.jd
index b8f205ec0f7e..06b1245c426d 100644
--- a/docs/html/guide/developing/tools/avd.jd
+++ b/docs/html/guide/developing/tools/avd.jd
@@ -11,6 +11,8 @@ page.title=Android Virtual Devices
hardware options, system image, and data storage.
You create AVD configurations to model different device environments
in the Android emulator.
+
The android tool offers a graphical Android AVD
+ Manager and a command-line interface for creating AVDs.
In this document
@@ -72,9 +74,18 @@ reference of emulator options, please see the Emulator
documentation.
-
@@ -89,11 +100,11 @@ you need to create an AVD before you can run any application in the emulator
-
To create an AVD, you use the android tool, a command-line utility
-available in the <sdk>/tools/ directory. Managing AVDs is one
-of the two main function of the android tool (the other is creating and updating
-Android projects). Open a terminal window and change to the
-<sdk>/tools/ directory, if needed
+
To create an AVD, you use the android tool, a command-line
+utility available in the <sdk>/tools/ directory. Managing
+AVDs is one of the two main function of the android tool (the other
+is creating and updating Android projects). Open a terminal window and change to
+the <sdk>/tools/ directory, if needed
To create each AVD, you issue the command android create avd,
with options that specify a name for the new AVD and the system image you want
@@ -118,11 +129,12 @@ version or that of any SDK add-on. Later, when applications use the AVD, they'll
be running on the system that you specify in the -t argument.
To specify the system image to use, you refer to its target ID
-— an integer — as assigned by the android tool. The target ID is not
-derived from the system image name, version, or API Level, or other attribute,
-so you need to have the android tool list the available system images and the
-target ID of each, as described in the next section. You should do this
-before you run the android create avd command.
+— an integer — as assigned by the android tool. The
+target ID is not derived from the system image name, version, or API Level, or
+other attribute, so you need to have the android tool list the
+available system images and the target ID of each, as described in the next
+section. You should do this before you run the android create
+avd command.
Listing targets
@@ -131,7 +143,7 @@ target ID of each, as described in the next section. You should do this
android list targets
-
The android tool scans the <sdk>/platforms and
+
The android tool scans the <sdk>/platforms and
<sdk>/add-ons directories looking for valid system images and
then generates the list of targets. Here's an example of the command output:
@@ -199,24 +211,22 @@ system image in the list above):
android create avd -n my_android1.5 -t 2
If the target you selected was a standard Android system image ("Type:
-platform"), the android tool next asks you whether you want to create a custom
-hardware profile.
-
+platform"), the android tool next asks you whether you want to
+create a custom hardware profile.
Android 1.5 is a basic Android platform.
Do you wish to create a custom hardware profile [no]
If you want to set custom hardware emulation options for the AVD, enter
"yes" and set values as needed. If you want to use the default hardware
emulation options for the AVD, just press the return key (the default is "no").
-The android tool creates the AVD with name and system image mapping you
+The android tool creates the AVD with name and system image mapping you
requested, with the options you specified.
-
If you are creating an AVD whose target is an SDK add-on,
-the android tool does not allow you to set hardware emulation options. It
-assumes that the provider of the add-on has set emulation options appropriately
-for the device that the add-on is modeling, and so prevents you from resetting
-the options.
-
+
If you are creating an AVD whose target is an SDK add-on, the
+android tool does not allow you to set hardware emulation options.
+It assumes that the provider of the add-on has set emulation options
+appropriately for the device that the add-on is modeling, and so prevents you
+from resetting the options.
For a list of options you can use in the android create avd
command, see the table in Command-line options for AVDs,
at the bottom of
@@ -225,11 +235,11 @@ this page.
Setting hardware emulation options
When are creating a new AVD that uses a standard Android system image ("Type:
-platform"), the android tool lets you set hardware emulation options for virtual
-device. The table below lists the options available and the default values, as
-well as the names of properties that store the emulated hardware options in the AVD's
-configuration file (the config.ini file in the AVD's local directory).
-
+platform"), the android tool lets you set hardware emulation
+options for virtual device. The table below lists the options available and the
+default values, as well as the names of properties that store the emulated
+hardware options in the AVD's configuration file (the config.ini file in the
+AVD's local directory).
@@ -249,7 +259,6 @@ configuration file (the config.ini file in the AVD's local directory).
Whether there is a touch screen or not on the device. Default value is "yes".
hw.touchScreen
-
Trackball support
Whether there is a trackball on the device. Default value is "yes".
@@ -339,23 +348,30 @@ configuration file (the config.ini file in the AVD's local directory).
Default value is "66MB".
disk.cachePartition.size
+
+
+
Abstracted LCD density
+
Sets the generalized density characteristic used by the AVD's screen. Default value is "160".
+
hw.lcd.density
+
+
Default location of the AVD files
-
When you create an AVD, the android tool creates a dedicated directory for it
+
When you create an AVD, the android tool creates a dedicated directory for it
on your development computer. The directory contains the AVD configuration file,
the user data image and SD card image (if available), and any other files
associated with the device. Note that the directory does not contain a system
image — instead, the AVD configuration file contains a mapping to the
system image, which it loads when the AVD is launched.
-
The android tool also creates a <AVD name>.ini file for the AVD at the
+
The android tool also creates a <AVD name>.ini file for the AVD at the
root of the .android/avd directory on your computer. The file specifies the
location of the AVD directory and always remains at the root the .android
directory.
-
By default, the android tool creates the AVD directory inside
+
By default, the android tool creates the AVD directory inside
~/.android/avd/ (on Linux/Mac), C:\Documents and
Settings\<user>\.android\ on Windows XP, and
C:\Users\<user>\.android\ on Windows Vista.
@@ -396,18 +412,18 @@ Error: Invalid value in image.sysdir. Run 'android update avd -n foo'
Deleting an AVD
-
You can use the android tool to delete an AVD. Here is the command usage:
+
You can use the android tool to delete an AVD. Here is the command usage:
android delete avd -n <name>
-
When you issue the command, the android tool looks for an AVD matching the
+
When you issue the command, the android tool looks for an AVD matching the
specified name deletes the AVD's directory and files.
Command-line options for AVDs
The table below lists the command-line options you can use with the
-android tool.
+android tool.
@@ -448,9 +464,9 @@ android tool.
-f
Force creation of the AVD
By default, if the name of the AVD being created matches that of an
- existing AVD, the android tool will not create the new AVD or overwrite
+ existing AVD, the android tool will not create the new AVD or overwrite
the existing AVD. If you specify the -f option, however, the
- android tool will automatically overwrite any existing AVD that has the
+ android tool will automatically overwrite any existing AVD that has the
same name as the new AVD. The files and data of the existing AVD are
deleted.
@@ -465,7 +481,7 @@ files.
-s <name> or -s <width>-<height>
The skin to use for this AVD, identified by name or dimensions.
-
The android tool scans for a matching skin by name or dimension in the
+
The android tool scans for a matching skin by name or dimension in the
skins/ directory of the target referenced in the -t
<targetID> argument. Example: -s HVGA-L
diff --git a/docs/html/guide/developing/tools/ddms.jd b/docs/html/guide/developing/tools/ddms.jd
index fa04216c39bf..f55940d18ae0 100644
--- a/docs/html/guide/developing/tools/ddms.jd
+++ b/docs/html/guide/developing/tools/ddms.jd
@@ -1,7 +1,7 @@
-page.title=Using Dalvik Debug Monitor Service (DDMS)
+page.title=Using the Dalvik Debug Monitor
@jd:body
-
Android ships with a debugging tool called the Dalvik Debug Monitor Service (DDMS),
+
Android ships with a debugging tool called the Dalvik Debug Monitor Server (DDMS),
which provides port-forwarding services, screen capture on the device, thread
and heap information on the device, logcat, process, and radio state information,
incoming call and SMS spoofing, location data spoofing, and more. This page
@@ -106,7 +106,7 @@ and some pretty cool tools.
utime - cumulative time spent executing user code, in "jiffies" (usually
- 10ms). Only available under Linux.
+ 10ms).
stime - cumulative time spent executing system code, in "jiffies" (usually
10ms).
Name - the name of the thread
@@ -214,14 +214,15 @@ the emulator from command line, be sure to mount the sdcard again.)
Screen Capture
You can capture screen images on the device or emulator by selecting Device
- > Screen capture... in the menu bar, or press CTRL-S.
+ > Screen capture... in the menu bar, or press CTRL-S.
+ Be sure to select a device first.
Exploring Processes
You can see the output of ps -x for a specific VM by selecting Device
> Show process status... in the menu bar.
Cause a GC to Occur
-
Cause garbage collection to occury by pressing the trash can button on the toolbar.
+
Cause garbage collection to occur in the selected application by pressing the trash can button on the toolbar.
Running Dumpsys and Dumpstate on the Device (logcat)
@@ -239,7 +240,7 @@ the emulator from command line, be sure to mount the sdcard again.)
Stop a Virtual Machine
You can stop a virtual machine by selecting Actions > Halt
-VM. Pressing this button causes the VM to call System.exit(1).
+VM. Pressing this button causes the VM to call Runtime.halt(1).
The Android SDK includes a mobile device emulator -- a virtual mobile device
that runs on your computer. The emulator lets you prototype, develop, and test
@@ -27,9 +27,13 @@ from which you can log kernel output, simulate application interrupts (such as
arriving SMS messages or phone calls), and simulate latency effects and dropouts
on the data channel.
Please set skin options using AVDs, rather than by using this emulator
+option. Using this option may yield unexpected and in some cases misleading
+results, since the density with which to render the skin may not be defined.
+AVDs let you associate each skin with a default density and override the default
+as needed. For more information, see Android Virtual Devices.
-skindir <dir>
-
Search for emulator skins in <dir>.
-
+
This emulator option is deprecated.
+
See comments for -skin, above.
@@ -1636,41 +1640,9 @@ kilobits/sec):
Using Emulator Skins
-
You can run the emulator with any of four default skins, as described in the table below. To specify a skin, use -skin <skinID> when starting the emulator.
-
-
For example:
-
-
emulator -skin HVGA-L
+
The Android SDK includes several Emulator skins that you can use to control the resolution and density of the emulated device's screen. To select a specific skin for running the emulator, create an AVD that uses that skin. Please do not use deprecated emulator options such as -skin to control the skin used by an emulator instance. For more information about AVDs, see Android Virtual Devices.
-
Note that you must enter the <skinID> in uppercase letters (if your development computer is case-sensitive).
-
-
-
-
skinID
-
Description
-
Skin
-
-
-
HVGA-L
-
480x320, landscape
-
-
-
-
HVGA-P
-
320x480, portrait (default)
-
-
-
-
QVGA-L
-
320x240, landscape
-
-
-
-
QVGA-P
-
240x320, portrait
-
-
-
diff --git a/docs/html/guide/developing/tools/index.jd b/docs/html/guide/developing/tools/index.jd
index 2c9e45df3117..6e9fde1fb0f4 100644
--- a/docs/html/guide/developing/tools/index.jd
+++ b/docs/html/guide/developing/tools/index.jd
@@ -30,6 +30,11 @@ applications on the emulator.
The Hierarchy Viewer tool allows you to debug and optimize your user interface.
It provides a visual representation of your layout's hierarchy of Views and a magnified inspector
of the current display with a pixel grid, so you can get your layout just right.
+
An important .apk optimization tool. This tool ensures that all uncompressed data starts
+ with a particular alignment relative to the start of the file. This should always be used
+ to align .apk files after they have been signed.
layoutopt is a command-line tool that helps you optimize the
+layouts and layout hierarchies of your applications. You can run it against your
+layout files or resource directories to quickly check for inefficiencies or
+other types of problems that could be affecting the performance of your
+application.
+
+
To run the tool, open a terminal and launch layoutopt
+<resources> from your SDK tools/ directory. In the
+command, supply a list of uncompiled resource xml files or directories that you
+want to analyze.
+
+
When run, the tool loads the specified XML files and analyzes their layout
+structures and hierarchies according to a set of predefined rules. If it detects
+issues, it outputs information about the issues, giving filename, line numbers,
+description of issue, and for some types of issues a suggested resolution.
+
+
Here's an example of the output:
+
+
$ layoutopt samples/
+samples/compound.xml
+ 7:23 The root-level <FrameLayout/> can be replaced with <merge/>
+ 11:21 This LinearLayout layout or its FrameLayout parent is useless
+samples/simple.xml
+ 7:7 The root-level <FrameLayout/> can be replaced with <merge/>
+samples/too_deep.xml
+ -1:-1 This layout has too many nested layouts: 13 levels, it should have <= 10!
+ 20:81 This LinearLayout layout or its LinearLayout parent is useless
+ 24:79 This LinearLayout layout or its LinearLayout parent is useless
+ 28:77 This LinearLayout layout or its LinearLayout parent is useless
+ 32:75 This LinearLayout layout or its LinearLayout parent is useless
+ 36:73 This LinearLayout layout or its LinearLayout parent is useless
+ 40:71 This LinearLayout layout or its LinearLayout parent is useless
+ 44:69 This LinearLayout layout or its LinearLayout parent is useless
+ 48:67 This LinearLayout layout or its LinearLayout parent is useless
+ 52:65 This LinearLayout layout or its LinearLayout parent is useless
+ 56:63 This LinearLayout layout or its LinearLayout parent is useless
+samples/too_many.xml
+ 7:413 The root-level <FrameLayout/> can be replaced with <merge/>
+ -1:-1 This layout has too many views: 81 views, it should have <= 80!
+samples/useless.xml
+ 7:19 The root-level <FrameLayout/> can be replaced with <merge/>
+ 11:17 This LinearLayout layout or its FrameLayout parent is useless
+
+
The layoutopt tool is available in SDK Tools, Revision 3 or
+later. If you do not have SDK Tools 3 or later installed in your SDK, you can
+download it from the Android SDK repository site using the Android SDK and AVD
+Manager. For information, see Adding SDK Components.
+
+
Usage
+
+
To run layoutopt against a given list of layout resources:
The sections below describe other tools that you can use when building Android applications.
+
The sections below describe other tools that you can use when building
+Android applications.
-
All of the tools are included in the Android SDK and are accessible from the <sdk>/tools/ directory.
+
All of the tools are included in the Android SDK and are accessible from the
+<sdk>/tools/ directory.
Contents
@@ -16,24 +18,32 @@ page.title=Other Tools
android
-
The android tool is a script that lets you create and manage Android Virtual Devices (AVDs) and, if you are developing using Ant, generate template Android projects to help you get started quickly.
+
{@code android} is an important development tool that lets you:
-
For information about how to use the android tool to manage AVDs, see Android Virtual Devices.
Update your Android SDK with new platforms, add-ons, and documentation. See
+ Adding SDK Components.
+
-
For information about how to use the android tool to create or update a project, see Developing in Other IDEs.
-
-
Note that if you are developing in Eclipse with the ADT plugin, you will use the android tool to manage the AVDs you create, but you will not use the android tool for creating a project. The ADT plugin provides a New Project Wizard that helps you set up an Android project in Eclipse.
-
-
If you are developing in Ant, you will use the android tool to manage your AVDs, and you can also use it to create or update a project.
-
-
Note: The android tool replaces the activitycreator tool provided in previous SDK releases.
+
If you develop in Eclipse with the ADT plugin, you can perform
+these tasks directly from the IDE. To create
+Android projects and AVDs from Eclipse, see Developing
+In Eclipse. To update your SDK from Eclipse, see
+Adding SDK Components.
+
mksdcard
-
The mksdcard tool lets you quickly create a FAT32 disk image that you can load in the emulator, to simulate the presence of an SD card in the device. Here is the usage for mksdcard:
+
The mksdcard tool lets you quickly create a FAT32 disk image that you can
+load in the emulator, to simulate the presence of an SD card in the device.
+Here is the usage for mksdcard:
mksdcard [-l label] <size>[K|M] <file>
@@ -53,7 +63,8 @@ page.title=Other Tools
size
An integer that specifies the size (in bytes) of disk image to create.
-You can also specify size in kilobytes or megabytes, by appending a "K" or "M" to <size>. For example, 1048576K, 1024M.
+You can also specify size in kilobytes or megabytes, by appending a "K" or "M" to
+<size>. For example, 1048576K, 1024M.
@@ -63,7 +74,9 @@ You can also specify size in kilobytes or megabytes, by appending a "K" or "M" t
-
Once you have created the disk image file, you can load it in the emulator at startup using the emulator's -sdcard option. For more information, see Android Emulator.
+
Once you have created the disk image file, you can load it in the emulator at
+startup using the emulator's -sdcard option. For more information, see
+Android Emulator.
emulator -sdcard <file>
@@ -71,7 +84,11 @@ You can also specify size in kilobytes or megabytes, by appending a "K" or "M" t
dx
-
The dx tool lets you generate Android bytecode from .class files. The tool converts target files and/or directories to Dalvik executable format (.dex) files, so that they can run in the Android environment. It can also dump the class files in a human-readable format and run a target unit test. You can get the usage and options for this tool by using dx --help.
+
The dx tool lets you generate Android bytecode from .class files. The tool
+converts target files and/or directories to Dalvik executable format (.dex) files,
+so that they can run in the Android environment. It can also dump the class files
+in a human-readable format and run a target unit test. You can get the usage and
+options for this tool by using dx --help.
zipalign is an archive alignment tool that provides important
+optimization to Android application (.apk) files.
+The purpose is to ensure that all uncompressed data starts
+with a particular alignment relative to the start of the file. Specifically,
+it causes all uncompressed data within the .apk, such as images or raw files,
+to be aligned on 4-byte boundaries. This
+allows all portions to be accessed directly with {@code mmap()} even if they
+contain binary data with alignment restrictions.
+The benefit is a reduction in the amount of RAM consumed
+when running the application.
+
+
This tool should always be used to align your .apk file before
+distributing it to end-users. The Android build tools can handle
+this for you. When using Eclipse with the ADT plugin, the Export Wizard
+will automatically zipalign your .apk after it signs it with your private key.
+The build scripts used
+when compiling your application with Ant will also zipalign your .apk,
+as long as you have provided the path to your keystore and the key alias in
+your project {@code build.properties} file, so that the build tools
+can sign the package first.
+
+
Caution: zipalign must only be performed
+after the .apk file has been signed with your private key.
+If you perform zipalign before signing, then the signing procedure will undo
+the alignment. Also, do not make alterations to the aligned package.
+Alterations to the archive, such as renaming or deleting entries, will
+potentially disrupt the alignment of the modified entry and all later
+entries. And any files added to an "aligned" archive will not be aligned.
+
+
The adjustment is made by altering the size of
+the "extra" field in the zip Local File Header sections. Existing data
+in the "extra" fields may be altered by this process.
+
+
For more information about how to use zipalign when building your
+application, please read Signing
+Your Application.
+
+
+
Usage
+
+
To align {@code infile.apk} and save it as {@code outfile.apk}:
The {@code <alignment>} is an integer that defines the byte-alignment boundaries.
+This must always be 4 (which provides 32-bit alignment) or else it effectively
+does nothing.
+
+
Flags:
+
+
+
{@code -f} : overwrite existing outfile.zip
+
{@code -v} : verbose output
+
{@code -c} : confirm the alignment of the given file
Applications can provide custom resources (primarily layouts) for any of the
+three generalized sizes, if needed, and they can also provide resources
+(primarily drawables such as images) for any of the three generalized densities.
+Applications do not need to work with the actual physical size or density of the
+device screen. At run time, the platform handles the loading of the correct size
+or density resources, based on the generalized size or density of the current
+device screen, and adapts them to the actual pixel map of the screen.
+
+
The range of screens supported by Android and the generalized screen
+configurations that the platform maps them to are shown in the table below.
+
+
+
+
+
+
+ Low density (120), ldpi
+
+
+ Medium density (160), mdpi
+
+
+ High density (240), hdpi
+
+
+
+
+ Small screen
+
+
+
+
QVGA (240x320), 2.6"-3.0" diagonal
+
+
+
+
+
+
+
+ Normal screen
+
+
+
+
WQVGA (240x400), 3.2"-3.5" diagonal
+
FWQVGA (240x432), 3.5"-3.8" diagonal
+
+
+
+
+
HVGA (320x480), 3.0"-3.5" diagonal
+
+
+
+
+
WVGA (480x800), 3.3"-4.0" diagonal
+
FWVGA (480x854), 3.5"-4.0" diagonal
+
+
+
+
+
+ Large screen
+
+
+
+
+
WVGA (480x800), 4.8"-5.5" diagonal
+
FWVGA (480x854), 5.0"-5.8" diagonal
+
+
+
+
+
+
+
+
Table
+1. Summary of device screens supported by Android.
+
+
As shown above, the various screen configurations are arranged around a
+baseline screen — HVGA (320x480) resolution on a 3.2" screen — which
+is assigned a size of "normal" and a density of "medium". The HVGA screen is
+used as the baseline because all applications written against Android 1.5 or
+earlier are (by definition) written for the HVGA screen used on the T-Mobile G1
+and similar devices.
+
+
+
+
Although the platform currently supports the nine possible size-density
+configurations listed in the table, you do not necessarily need to custom
+resources for each one of them. The platform provides robust compatibility
+features, described in the sections below, that can handle most of the work of
+rendering your application on the current device screen, provided that the UI is
+properly implemented. For more information, see Best Practices for Screen Independence.
+
+
+
How Android supports multiple screens
+
+
+
+
Using the alternate resources framework
+
+
The platform's support for loading screen size- and density-specific
+resources at run time is based on the alternate resources framework.
+
+
If you want to use size- or density-specific layouts or drawables in your
+application and you are not familiar with resource qualifiers or how the
+platform uses them, please read
+
+Alternate Resources.
+
+
+
+
The foundation of Android's support for multiple screens is a set of built-in
+compatibility features that together manage the rendering of application
+resources in an appropriate way for the current device screen. The platform
+handles most of the work of rendering your application, but also gives you two
+key ways to control the way your application is displayed, if you need or want
+to use them:
+
+
+
The platform provides a set of resource qualifiers that let you provide
+size- and density-specific resources, if needed. The qualifiers for
+size-specific resources are large, normal, and
+small, and those for density-specific resources are
+hdpi (high), mdpi (medium), and ldpi
+(low). The qualifiers correspond to the generalized densities given in
+Table 1, above.
+
The platform also provides a
+
+<supports-screens>
+element, whose attributes
+android:largeScreens, android:normalScreens, and
+android:smallScreens let you specify what generalized screen sizes
+your application supports. A fourth attribute, android:anyDensity,
+lets you indicate whether or not your application includes built-in support for
+multiple densities.
+
+
+
At run time, the platform provides three types of support to your
+application, to ensure the best possible display on the current device
+screen:
+
+
+
Pre-scaling of resources (such as image assets)
+
+
Based on the density of the current screen, the platform automatically
+loads any size- or density-specific resources from your application and displays
+them without scaling. If no matching resources are available, the platform loads
+the default resources and scales them up or down as needed to match the current
+screen's generalized density. The platform assumes that default resources are
+designed for proper display at the baseline screen density of "medium" (160),
+unless they are loaded from a density-specific resource directory.
+
+
For example, if the current screen's density is "high", the platform loads
+resources that are tagged with the qualifier hdpi and uses them
+without scaling. If no such resources are available, the platform uses the
+default resources instead, scaling them from the baseline density ("medium") to
+"high".
+
+
For more information about how to create size- and density-specific
+resources, see Resource qualifiers.
+
+
Auto-scaling of pixel dimensions and coordinates
+
+
If the application states that it does not support different screen
+densities, the platform auto-scales any absolute pixel coordinates, pixel
+dimension values, and pixel math used in the application (such as might be used
+for specifying the width or padding for a view). It does this to ensure that
+pixel-defined screen elements are displayed at approximately the same physical
+size as they would be at the baseline density of "medium" (160). The platform
+handles this scaling transparently to the application and also reports scaled
+overall pixel dimensions to the application, rather than physical pixel
+dimensions.
+
+
For instance, suppose a given device is using a WVGA high-denisty screen,
+which is 480x800 and about the same size as a traditional HVGA screen, but it's
+running an app that states that it does not support multiple densities. In this
+case, the system will "lie" to the application when it queries for screen
+dimensions, and report 320x533. Then, when the app does drawing operations, such
+as invalidating the rectangle from (10,10) to (100, 100), the system will
+likewise automatically transform the coordinates by scaling them the appropriate
+amount, and actually invalidate the region (15,15) to (150, 150). The same
+thing happens in the other direction, if the application is running on a
+lower-density screen, coordinates are scaled down.
To ensure the best experience for users on small-screen devices, Android
+Market only shows applications that explicitly declare support for small
+screens. If you developed an application on Android 1.5 or earlier and published
+it on Android Market, you need to test your application
+on small screens and then upload an updated version that explicitly
+indicates support for small screens.
+
+
+
+
Compatibility-mode display on larger screen-sizes
+
+
If the current screen's size is larger than your application supports, as
+specified in the supports-screens element, the platform displays
+the application at the baseline size ("normal") and density ("medium). For
+screens larger than baseline, the platform displays the application in a
+baseline-sized portion of the overall screen, against a black background.
+
+
For instance, suppose a given device is using a WVGA medium density screen,
+classified as a "large" screen, but the application states that it does not
+support large screens; in this case, the system will again "lie" to the
+application when it queries for screen dimensions, and report 320x480. Instead
+of scaling the application, however, the application's 320x480 interface will be
+placed as a "postage stamp" in the larger 480x800 screen.
In general, these compatibility features ensure that all applications,
+including those written against Android 1.5 and earlier platform versions, can
+display properly on most devices, especially when the device's screen is at the
+baseline "normal" size or larger.
+
+
However, note that applications written for the baseline HVGA screen may need
+minor adjustments before they display properly on smaller screens such as QVGA.
+With the reduced screen area of small screens, there may be tradeoffs in design,
+content, and function that you, as the application developer, need to consider.
+For more information about how to prepare an existing application for display on
+small screens, see Strategies for Legacy
+Applications.
+
+
The sections below provide more information how to take advantage of the
+platform's multiple-screens support.
+
+
+
Density independence
+
+
The goal of density independence is to preserve the physical size, from the
+user's point of view, of user interface elements declared in an application,
+when the application is displayed on screens with different densities. Density
+independence applies to both layouts and drawables such as icons. Maintaining
+density-independence is important because, other things being equal, a UI
+element (such as a button) whose height and width are defined in terms of screen
+pixels will appear physically larger on the lower density screen and smaller on
+the higher density screen. Such density-related size changes can cause problems
+in application layout, usability, and consistency with other applications
+installed on the device.
+
+
The platform provides density independence to applications by default. It
+does this in three ways:
+
+
+
Through pre-scaling of drawable resources (scaled at resource loading
+time)
+
Through auto-scaling of device-independent pixel (dip) values used in
+layouts
+
Through auto-scaling of absolute pixel values used in the application (only
+needed if the application has set android:anyDensity="false" in its
+manifest)
+
+
+
The example screens below illustrate the density independence provided by the
+platform. Note that both the layouts and launcher icons are displayed at the
+same physical sizes, although screen sizes, aspect ratios, and densities are
+different.
+
+
+
+
+
Figure 1. Examples of density independence on WVGA high
+density (left), HVGA medium density (center), and QVGA low density (right).
+
+
+
In most cases, you can take advantage of density independence in your
+application simply by making sure that your layouts specify all dimension values
+in density-independent pixels (dip or dp) or
+scale-independent pixels (sip or sp, for text only).
+If you are using absolute pixel values in the application and manifest includes
+android:anyDensity="true", you will also need
+to scale the pixel values. See Converting from dips to
+pixels for more information.
+
+
+
Manifest attributes for screens support
+
+
Android 1.6 introduced a new manifest element,
+<supports-screens>,
+whose attributes you can use to control the
+display of your application on different classes of device screens, as listed
+below. The smallScreens, normalScreens, and
+largeScreens attributes correspond to the generalized screen sizes
+shown in Table 1, earlier in this document.
+
+
+
+
+ Attribute
+
+
+ Description
+
+
+
+
+ android:smallScreens
+
+
+ Whether or not the application UI is designed for use on
+small screens — "true" if it is, and
+"false" if not. See Default values for
+attributes for information about the assumed value of this attribute, if not
+declared.
+
+
+
+
+ android:normalScreens
+
+
+ Whether or not the application UI is designed for use on
+normal screens — "true" if it is, and
+"false" if not. The default value is "true".
+
+
+
+
+ android:largeScreens
+
+
+ Whether or not the application UI is designed for use on
+large screens — "true" if it is, and
+"false" if not. See Default values for
+attributes for information about the assumed value of this attribute, if not
+declared.
+
+
+
+
+ android:anyDensity
+
+
+
Whether or not the application is designed to manage its UI properly
+in different density environments — "true" if so, and
+"false" if not.
+
+
If set to "true", the platform disables its
+density-compatibility features for all screen densities — specifically,
+the auto-scaling of absolute pixel units and math — and relies on the
+application to use density-independent pixel units and/or to manage the
+adaptation of pixel values according to density of the current screen.
+
+
If set to "false", the platform enables its
+density-compatibility features for all screen densities. In this case, the
+platform provides a scaled, virtual screen pixel map to the application, against
+which it can layout and draw its UI as though against a medium-density screen
+(160). The platform then transparently auto-scales the application's pixel units
+and math as needed to match the actual device screen density.
In general, when you declare a screen-size attribute
+(smallScreens, normalScreens, or
+largeScreens) as "true", you are signaling to the platform that
+your application wants to manage its UI by itself, for all screen sizes, without
+the platform applying any size-compatibility behaviors (such as a virtual HVGA
+display area). If you declare a screen-size attribute as "false", you are
+signaling that your application is not designed for that screen size. The
+effects are conditioned by the screen size that your application does not
+support:
+
+
+
If you declare largeScreens="false", your application can
+still be installed by users of devices with large screens. When run on a device
+with a large screen, this attribute value causes the platform to run the
+application in compatibility mode, rendering it in a baseline HVGA screen area
+(normal size, medium density) reserved on the larger screen. See
+Screen-Compatibility Examples for an
+illustration of what an application looks like when displayed in compatibility
+mode.
+
If you declare smallScreens="false", your application can
+still be installed by users of devices with small screens. However, this
+attribute value causes Android Market to filter your application from the list
+of applications available to such users. In effect, this prevents users from
+installing the application on small-screen devices.
+
+
+
If you declare the android:anyDensity attribute as "true", you
+are signaling to the platform that your application wants to manage its UI by
+itself, for all screen densities, using the actual screen dimensions and pixels.
+In this case, the application must ensure that it declares its UI dimensions
+using device-independent pixels and scales any actual pixel values or math by
+the scaling factor available from
+{@link android.util.DisplayMetrics#density android.util.DisplayMetrics.density}.
+
+
Note that the setting of the android:anyDensity attribute does
+not affect the platform's pre-scaling of drawable resources, such as bitmaps and
+nine-patch images, which always takes place by default.
+
+
The following example shows a manifest that declares support for large,
+normal, and small screens in any densities.
The default values for the <supports-screens> attributes
+differs, depending on the the value of the
+android:minSdkVersion
+ attribute in the application's manifest, as well as on
+the value of android:targetSdkVersion, if declared:
+
+
+
+
+ If android:minSdkVersion or
+android:targetSdkVersion is "3" (Android 1.5) or lower, the default
+value for everything except android:normalScreens is false. If you
+are primarily targeting pre-Android 1.6 platforms but also want to support other
+densities/screen sizes, you need to set the appropriate attributes to
+true.
+
+
+ If android:minSdkVersion or
+android:targetSdkVersion is "4" (Android 1.6) or higher, the
+default value for everything is true. If your application
+requires Android 1.6 features,
+but does not support these densities and/or screen sizes, you need to set the
+appropriate attributes to false.
+
+
+ Note that android:normalScreens always defaults to
+true.
+
+
+
+
+
+
Resource directory qualifiers for screen size and density
+
+
Android supports resource directory qualifiers for controlling the selection
+of resources based on the characteristics of the screen on which your application
+is running. You can use these qualifiers to provide size- and density-specific
+resources in your application. For more information about the generalized sizes
+and densities that correspond to the qualifiers, see Table
+1, earlier in this document.
+
+
+
+
Screen characteristic
+
Qualifier
+
Description
+
+
+
+
Size
+
small
+
Resources for small screens, such as QVGA low density.
+
+
+
normal
+
Resources for normal (baseline configuration) screens, such as T-Mobile
+G1/HTC Magic screen size, or equivalent.
+
+
+
large
+
Resources for large screens. Typical example is a tablet like device.
+
+
+
+
Density
+
ldpi
+
Low-density resources, for 100 to 140 dpi screens.
+
+
+
mdpi
+
Medium-density resources for 140 to 180 dpi screens.
+
+
+
hdpi
+
High-density resources for 190 to 250 dpi screens.
+
+
+
nodpi
+
Density-independent resources. The platform does not auto-scale resources
+tagged with this qualifier, regardless of the current screen's density.
+
+
+
+
Aspect ratio
+
long
+
Resources for screens of any size or density that have a significantly
+taller (in portrait mode) and wider (in landscape mode) aspect ratio than the
+baseline screen configuration.
+
+
+
notlong
+
Resources for use only on screens that have an aspect ratio that is similar
+to the baseline screen configuration.
+
+
+
Platform version
+
v<api-level>
+
Resources that are for use only on a specific API Level or higher. For
+example, if your application is designed to run on both Android 1.5 (API Level
+3) and Android 1.6 (API Level 4 and higher), you can use the -v4
+qualifier to tag any resources that should be excluded when your application is
+running on Android 1.5 (API Level 3). Using the version qualifier is necessary
+in some cases, if the older platform is inadvertently loading resources from a
+directory containing resources for a newer platform.
+
+
+
+
+Note that the density and the screen size are independent parameters and are
+interpreted by the system individually. For example, WVGA high density is
+considered a normal screen because its physical size is about the same as one of
+T-Mobile G1. On the other hand, a WVGA medium density screen is considered a
+large screen — it offers the same resolution but at lower pixel
+density, meaning that it is both physically larger than the baseline screen and
+can display significantly more information than a normal screen size.
+
+
+
Here is an example of the resource directory structure of an application that
+supports low and high density, and employs different layout schemes.
+
+
res/layout/my_layout.xml // layout for normal screen size
+res/layout-small/my_layout.xml // layout for small screen size
+res/layout-large/my_layout.xml // layout for large screen size
+res/layout-large-land/my_layout.xml // layout for large screen size in landscape mode
+
+res/drawable-ldpi/my_icon.png // icon image for low density
+res/drawable-mdpi/dpi/my_icon.png // icon for medium density
+res/drawable-hdpi/my_icon.png // icon image for high density
+
+res/drawable-nodpi/composite.xml // density independent resource
+
+
+
For more information about how to use resource qualifiers or how the platform
+selects them, please read
+
+Alternate Resources.
+
+
+
Best practices for Screen Independence
+
+
The objective of supporting multiple screens is to create an application that
+can run properly on any display and function properly on any of the screen
+configurations listed in Table 1 earlier in this document.
+
+
+
You can easily ensure that your application will display properly on
+different screens. Here is a quick checklist:
+
+
+
+ Prefer wrap_content, fill_parent and the dip unit to px in XML layout files
+
+
+ Avoid AbsoluteLayout
+
+
+ Do not use hard coded pixel values in your code
+
+
+ Use density and/or resolution specific resources
+
+
+
+
1. Prefer wrap_content, fill_parent and the dip unit to
+absolute pixels
+
+
When defining the layout_width and layout_height of
+views in an XML layout file, using wrap_content,
+fill_parent or the dip will guarantee that the view is
+given an appropriate size on the current device screen. For instance, a view
+with a layout_width="100dip" will measure 100 pixels wide on an
+HVGA@160 density display and 150 pixels on a WVGA@240 density display, but the
+view will occupy approximately the same physical space.
+
+
Similarly, you should prefer the sp (scale-independent pixel,
+the scale factor depends on a user setting) or dip (if you don't
+want to allow the user to scale the text) to define font sizes.
+
+
2. Avoid AbsoluteLayout
+
+
{@link android.widget.AbsoluteLayout AbsoluteLayout}
+is one of the layout containers offered by the Android UI toolkit. Unlike the
+other layouts however, AbsoluteLayout enforces the use of fixed
+positions which might easily lead to user interfaces that do not work well on
+different displays. Because of this, AbsoluteLayout was deprecated
+in Android 1.5 (API Level 3).
+
+
You can achieve much the same layout by using a
+{@link android.widget.FrameLayout FrameLayout} instead, and setting
+layout_margin attributes of the children. This approach is more
+flexible and will yield better results on different screens.
+
+
3. Do not use hard-coded pixel values in your code
+
+
For performance reasons and to keep the code simpler, the Android framework
+API uses pixels as the standard unit for expressing dimension or coordinate
+values. That means that the dimensions of a View are always expressed in the
+code in pixels. For instance, if myView.getWidth() returns 10, the
+view is 10 pixels wide. In some cases, you may need to scale the pixel values
+that you use in your code. The sections below provide more information.
+
+
Converting from dips to pixels
+
+
In some cases, you will need to express dimensions in dip and
+then convert them to pixels. Imagine an application in which a scroll gesture is
+recognized after the user's finger has moved by at least 16 pixels. On a
+baseline HVGA screen, the user will have to move his finger by 16 pixels / 160
+dpi = 1/10th of an inch (or 2.5 mm) before the gesture is recognized. On a
+device with a high (240) density display, the user will move his finger by only
+16 pixels / 240 dpi = 1/15th of an inch (or 1.7 mm.) The distance is much
+shorter and the application thus appears more sensitive to the user. To fix this
+issue, the gesture threshold must be expressed in the code in dip
+and then converted to actual pixels.
+
+
// The gesture threshold expressed in dip
+private static final float GESTURE_THRESHOLD_DIP = 16.0f;
+
+// Convert the dips to pixels
+final float scale = getContext().getResources().getDisplayMetrics().density;
+mGestureThreshold = (int) (GESTURE_THRESHOLD_DIP * scale + 0.5f);
+
+// Use mGestureThreshold as a distance in pixels
+
+
+
The {@link android.util.DisplayMetrics#density android.util.DisplayMetrics.density}
+field specifies the the scale factor you must use to
+convert dips to pixels according to the current screen density. You can access
+the current screen's metrics through a Context or
+Activity. On a medium (160) density screen,
+DisplayMetrics.density equals "1.0", whereas on a high (240)
+density screen it equals "1.5". You can refer to the documentation of the
+{@link android.util.DisplayMetrics DisplayMetrics}
+class for details.
+
+
Use pre-scaled configuration values
+
+
The {@link android.view.ViewConfiguration ViewConfiguration} class can be
+used to access the most common distances, speeds, and times used in the Android
+framework. For instance, the distance in pixels used by the framework as the
+scroll threshold can be obtained as follows:
Methods starting with the getScaled prefix are guaranteed to return a value in pixels that will display properly regardless of the current screen density.
+
+
4. Use density and/or size-specific resources
+
+
+
+
Figure 2. Comparison of pre-scaled and auto-scaled bitmaps.
+
+
+
Even with the size- and density-compatibility features that the platform
+provides, you may still want to make adjustments to the UI of your application
+when it displayed on certain screen sizes or densities. You can do this by
+providing size- or density-specific resources — assets, layouts, strings,
+and so on. If you want, you can also take control over the scaling of images
+assets. The sections below provide more information.
+
+
Custom resources and directories
+
+
If you need to control exactly how your application will look on various
+displays, simply adjust your assets and layouts in configuration-specific
+resources directories. For example, consider an icon that you want to display on
+medium and high density screens. Simply create your icon at two different sizes
+(for instance 100x100 for medium density and 150x150 for high density) and put
+the two variations in the appropriate directories, using the proper
+qualifiers:
If a density qualifier is not defined in a resource directory name, the
+platform assumes that the resources in that directory are designed for the
+baseline medium density. It is not recommended that you put density-specific
+resources such as images in the default directory.
+
+
For more information about valid resource qualifiers, see
+Resource directory qualifiers, earlier in this
+document.
+
+
Pre-scaling and auto-scaling of bitmaps and nine-patches
+
+
When a bitmap or nine-patch image is loaded from the application's resources,
+the platform attempts to pre-scale it to match the display's density. For
+instance, if you placed a 100x100 icon in the res/drawable/
+directory and loaded that icon as a bitmap on a high-density screen, Android
+would automatically scale up the icon and produce a 150x150 bitmap.
+
+
This pre-scaling mechanism works independently of the source. For instance,
+an application targeted for a high-density screen may have bitmaps only in the
+res/drawable-hdpi/ directory. If one of the bitmaps is a 240x240
+icon and is loaded on a medium-density screen, the resulting bitmap will measure
+160x160.
+
+
The platform pre-scales resources as needed, whether the application is
+running with density-compatibility features enabled or not (as specified by the
+value of android:anyDensity). However, when running with
+density-compatibility enabled, the platform continues to report the size of
+pre-scaled bitmaps and other resources as if they were loaded in a
+medium-density environment. For example, when density-compatibility is enabled,
+if you load a 76x76 image from the default resources for display on a
+high-density screen, the platform will pre-scale the image to 114x114
+internally. However, the API still reports the size of the image as 76x76. This
+discrepancy may cause unexpected behavior if your application somehow directly
+manipulates the scaled bitmap, but this was considered a reasonable trade-off to
+keep the performance of existing applications as good as possible.
+
+
This does not apply for the case that an application creates an in-memory
+bitmap internally and draws something on it, for later display on the screen.
+The platform auto-scales such bitmaps on the fly, at draw time. Other side
+effects of such a case might be that fonts drawn in such a bitmap will be scaled
+at the bitmap level, when the off-screen bitmap is finally rendered to the
+display, resulting in scaling artifacts.
+
+
There are situations in which you may not want Android to automatically scale
+a resource. The easiest way to accomplish this is to put it in a "nodpi"
+resource directory:
+
+
res/drawable-nodpi/icon.png
+
+
You can also take complete control of the scaling mechanism by using the
+{@link android.graphics.BitmapFactory.Options BitmapFactory.Options} class,
+which lets you define whether you want the bitmap to be pre-scaled and what the
+density of the bitmap should be. For instance, if you are loading a bitmap from
+a web server, you may want to force the bitmap's density to be high density.
+When pre-scaling is disabled, the resulting bitmap is in auto-scaling mode. The
+bitmap is associated with a density (that you may or may not have specified
+through the BitmapFactory.Options) which will be used to scale the
+bitmap on screen at drawing time.
+
+
Using auto-scaling instead of pre-scaling is more CPU expensive than
+pre-scaling but uses less memory. You can refer to the documentation of
+{@link android.graphics.BitmapFactory BitmapFactory},
+{@link android.graphics.Bitmap Bitmap}, and
+{@link android.graphics.Canvas Canvas} for more
+information on auto-scaling.
+
+
Figure 2, at right, demonstrates the results of the pre-scale and auto-scale
+mechanisms when loading low (120), medium (160) and high (240) density bitmaps
+on a baseline screen. The differences are subtle, because all of the bitmaps are
+being scaled to match the current screen density, however the scaled bitmaps
+have slightly different appearances depending on whether they are pre-scaled or
+auto-scaled at draw time.
+
+
Strategies for Legacy Applications
+
+
If you have already developed and published an Android application based on
+Android 1.5 or earlier platform version, you need to consider how you will adapt
+your application so that it is deployable to
+
+
+
Existing devices, which may be running Android 1.5 (or lower) platform
+version, as well as to
+
Newer devices that are running Android 1.6 (or higher) and offering various
+screen sizes and resolutions
+
+
+
To support the newer devices and the different screens they use, you might
+need to make some changes in your app, but at the same time your app may be very
+stable and so you want to minimize the changes. There are a variety of ways that
+you can extend your existing application to support new devices with multiple
+screens and existing devices running older platform versions. You
+should be able to make these changes to your application such that you can
+distribute a single .apk to any and all devices.
+
+
The recommended strategy is to develop against the most recent version of the
+platform you are targeting, and test on the minimum one you want to run on.
+Here's how to do that:
+
+
+
Maintain compatibility with existing devices by leaving your application's
+android:minSdkVersion attribute as it is. You do not need
+to increment the value of the attribute to support new devices and multiple
+screens.
+
Extend compatibility for Android 1.6 (and higher) devices by adding
+a new attribute — android:targetSdkVersion — to the
+uses-sdk element. Set the value of the attribute to
+"4". This allows your application to "inherit" the platform's
+multiple screens support, even though it is technically using an earlier version
+of the API.
+
Add an empty <supports-screens> element as a child of
+<manifest>. If you need to enable size or density attributes
+later, this is where you will add them.
+
Change your application's build properties, such that it compiles against
+the Android 1.6 (API Level 4) library, rather than against the Android 1.5 (or
+earlier) library. You will not be able to compile your application against the
+older platform because of the new manifest attribute.
+
Set up AVDs for testing your application on Android 1.6 and higher
+releases. Create AVDs that use the screen sizes and densities that you want to
+support. When you create the AVDs, make sure to select the Android 1.6 or higher
+platform as the system image to run. For more information, see How to Test Your Application on Multiple Screens,
+below.
+
Set up AVDs for testing your application on Android 1.5 (or earlier
+platform). You need AVDs running the older platforms you are targeting, so that
+you can test for compatibility and ensure that there are no functional
+regressions.
+
Compile your application against the Android 1.6 library and run it on the
+AVDs you created. Observe the way your application looks and runs, and test all
+of the user interactions.
+
Debug any display or functional issues. For issues that you resolve in
+your application code, make certain not to use any APIs
+introduced in API Level 4 or later. If you are in doubt, refer to SDK
+reference documentation and look for the API Level specifier for the API you
+want to use. Using an API introduced in API Level 4 or later will mean that your
+application will no longer be compatible with devices running Android 1.5 or
+earlier.
+
For resource-related issues, you can try resolving them by:
+
+
Adding a anyDensity="false" attribute to
+<supports-screens>, to enable density-compatibility
+scaling.
+
Creating any size- or density-specific resources you need and placing
+them in directories tagged with the correct
+qualifiers. Qualifiers must be arranged in a proscribed order. See
+
+Alternate Resources for more information.
+
Note that if you add size- or density-specific resource directories
+tagged with any of the resource qualifiers listed in this document, you should
+make sure to also tag those directories with the v<api-level>
+qualifier (for example, -v4). This ensures that those resources
+will be ignored when the application is run on Android 1.5 or lower platform
+versions.
+
+
+
If your application does not offer support (such as custom layouts) for
+large screens and you want the platform to display your application in
+screen-compatibility mode on larger screens, add a
+largeScreens="false" attribute to the
+<supports-screens> element in the manifest. See
+Screen-Compatibility Examples for
+illustrations of how the platform displays your application in this case.
+
If your application does not offer support (such as custom layouts) for
+small screens (such as on a QVGA low-density screen) and you do not want Android
+Market to offer the application to users of small-screen devices, you
+must add a smallScreens="false" attribute to the
+<supports-screens> element.
+
Continue testing and debugging until your application performs as expected
+on all of the platforms and screen sizes your application will support.
+
Export, zipalign, and sign your application using the same private key you
+used when publishing the previous version, then publish the application to users
+as an update.
+
+
+
In particular, remember to test your application on an AVD that emulates a
+small-screen device. Devices that offer screens with QVGA resolution at low
+density are available now. Users of those devices may want to download your
+application, so you should understand how your application will look and
+function on a small-screen device. In many cases, the reduced screen area and
+density mean that you may need to make tradeoffs in design, content, and
+function on those devices.
+
+
How to Test Your Application on Multiple Screens
+
+
Before publishing an application that supports multiple screens, you should
+thoroughly test it in all of the targeted screen sizes and densities. You can
+test how it displays with the platform's compatibility features enabled or with
+screen-specific UI resources included in your application. The Android SDK
+includes all the tools you need to test your application on any supported
+screen.
+
+
+
+
+
+
Figure 3.
+ A typical set of AVDs for testing screens support.
+
+
+
As a test environment for your applications, set up a series of AVDs that
+emulate the screen sizes and densities you want to support. The Android SDK
+includes six emulator skins to get you started. You can use the Android AVD
+Manager or the android tool to create AVDs that use the various
+emulator skins and you can also set up custom AVDs to test densities other than
+the defaults. For general information about working with AVDs, see
+Android Virtual
+Devices.
+
+
The Android SDK provides a set of default emulator skins that you can use for
+testing. The skins are included as part of each Android platform that you can
+install in your SDK. The Android 1.6 platform offers these default skins:
+
+
+
+ QVGA (240x320, low density, small screen)
+
+
+ HVGA (320x480, medium density, normal screen)
+
+
+ WVGA800 (480x800, high density, normal screen)
+
+
+ WVGA854 (480x854 high density, normal screen)
+
+
+
+
The Android 2.0 platform offers all of the Android 1.6 default skins,
+above, plus:
+
+
+
+ WQVGA400 (240x400, low density, normal screen)
+
+
+ WQVGA432 (240x432, low density, normal screen)
+
+
+
+
If you are using the android tool command line to create your
+AVDs, here's an example of how to specify the skin you want to use:
+
+
android create avd ... --skin WVGA800
+
+
We also recommend that you test your application in an emulator that is set
+up to run at a physical size that closely matches an actual device. This makes
+it a lot easier to compare the results at various resolutions and densities. To
+do so you will need to know the approximate density, in dpi, of your computer
+monitor (a 30" Dell monitor has for instance a density of about 96 dpi.). Use
+your monitor's dpi as the value of the -scale option, when
+launching the emulator, for example:
+
+
emulator -avd <name> -scale 96dpi
+
+
If you are working in Eclipse with ADT, you can specify the -scale
+96dpi option in the Target tab of run and debug configurations, under
+"Additional Emulator Command Line Options" field.
+
+
Note that starting the emulator with the -scale option will
+scale the entire emulator display, based on both the dpi of the skin and of your
+monitor. Using the default densities, the emulator skins included in the Android
+1.6 SDK will emulate the following screen sizes:
+
+
+
+ QVGA, low density: 3.3"
+
+
+ WQVGA, low density: 3.9"
+
+
+ WQVGA432, low density: 4.1"
+
+
+ HVGA, medium density: 3.6"
+
+
+ WVGA800, high density: 3.9"
+
+
+ WVGA854, high density: 4.1"
+
+
+
+
+
+
Figure 4.
+ Resolution and density options that you can use, when creating an AVD using the AVD Manager.
+
+
+
You should also make sure to test your application on different physical
+screen sizes within a single size-density configuration. For example, according
+to Table 1, the minimum supported diagonal of QVGA is 2.8".
+To display this is on a 30" monitor you will need to adjust the value passed to
+-scale to 96*2.8/3.3 = 81dpi. You can also pass a float value to
+-scale to specify your own scaling factor:
+
+
emulator -avd <name> -scale 0.6
+
+
If you would like to test your application on a screen that uses a resolution
+or density not supported by the built-in skins, you can either adjust an
+existing skin, or create an AVD
+that uses a custom resolution or density.
+
+
In the AVD Manager, you can specify a custom skin resolution or density in
+the Create New AVD dialog, as shown in Figure 4, at right.
+
+
In the android tool, follow these steps to create an AVD with a
+custom resolution or density:
+
+
+
Use the create avd command to create a new AVD, specifying
+the --skin option with a value that references either a default
+skin name (such as "WVGA800") or a custom skin resolution (such as 240x432).
+Here's an example:
+
To specify a custom density for the skin, answer "yes" when asked whether
+you want to create a custom hardware profile for the new AVD.
+
Continue through the various profile settings until the tool asks you to
+specify "Abstracted LCD density" (hw.lcd.density). Consult Table 1, earlier in this document, and enter the appropriate
+value. For example, enter "160" to use medium density for the WVGA800 screen.
+
Set any other hardware options and complete the AVD creation.
+
+
+
In the example above (WVGA medium density), the new AVD will emulate a 5.8"
+WVGA screen.
+
+
As an alternative to adjusting the emulator skin configuration, you can use
+the emulator skin's default density and add the -dpi-device option
+to the emulator command line when starting the AVD. For example,
This section provides examples of how the Android platform displays an
+application written for the baseline screen configuration — HVGA (320x480)
+resolution on a 3.2" screen — with all of the platform's size- and
+density-compatibility features enabled. That is, the examples show how
+the platform displays an application that doesn't provide built-in support
+for the screen on which it is being rendered, but which instead relies completely
+on the platform.
+
+
The platform's screen-compatibility features are designed to provide such
+an application with a virtual baseline screen environment against which to run,
+while at the same time ensuring for the user a physical display that is
+approximately the same as the baseline screen size and density.
+
+
Legacy applications that have not been modified to support multiple
+screens would be typical examples of such applications. In most cases,
+you would want to add multiple-screens support to a legacy application and
+publish an updated version, as described in Strategies
+for Legacy Applications. However, if you did not do so, the
+platform still performs best-effort rendering of your application, as
+illustrated below.
+
+
Internally, these are the compatibility features that the platform
+provides, based on the current device screen:
+
+
+
+ If the device's screen density is not medium, the application's
+layout and drawing of its content is as if the screen is medium density, but the
+framework scales the layout and images (if the image for the target density is
+not available) to fit the target density. It scales 1.5 times if the target
+density is high density (160->240 virtual dpi), or 0.75 times if the target
+density is low density (160 -> 120 virtual dpi).
+
+
+ If the device's screen size is small, there are few options
+options for making Android 1.5 applications work well on such a screen, so
+Android Market will filter applications that are not known to support these
+screens from the device.
+
+
+ If the device's screen size is large, it limits the application's
+screen to the normal size and draws a black background around the application.
+For example, if an application supports high density, but does not support large
+screens, it only uses a 480x720 area of the screen and the rest will be filled
+with a black background (see example below).
+
+
+
+
+
+
+ HVGA, normal size, normal density
+ [ emulator -skin HVGA ]
+
+
+
+ WVGA, normal size, high density
+ [emulator -skin WVGA854 -dpi-device 240]
+
+
The application occupies full screen as its considered to be normal size. (close to 480x720)
+
+
+
+
+ VGA, large size, medium density
+ [ emulator -skin 640x480 ]
+
+
The application occupies 320x480 of VGA.
+
+
+ SVGA, large size, high density
+ [ emulator -skin 800x600 -dpi-device 240]
+
+
The application occupies 480x720 (=1.5 x [320x480]) of 800x600.
+
+
+
+
+
+
Screen-compatibility limitations on small, low-density screens
+
+
Because these device has smaller state/resolution, there are known
+limitations when application runs in compatibility mode.
+
+
QVGA
+
+
Because QVGA (240x320) screens have less screen area available and lower
+density than normal, which is 240x360 in low density, some applications cannot
+render all their content properly on those screens. As a result, on a QVGA
+device, Android Market will filter out all applications that do not declare they
+support small screens.
+
+
Examples:
+
+
+
+
The part of z value graph is chopped.
+
The lap time area is chopped.
+
+
+
+
+
+
+
+
+
Images with 1 pixel height/width.
+
+
If an image has 1 pixel height or width, it may not be shown on the screen
+due to rounding issue. This is inevitable as it just does not have enough
+pixels.
+
+
For example, in the screen below, the divider in the menu is invisible
+because the width of the image is trancated to 0. (This particular problem is
+solvable because menu is handled inside framework, but there is no generic
+solution as it just does not have enough pixels.)
+
+
+
+
+
diff --git a/docs/html/guide/practices/ui_guidelines/icon_design.jd b/docs/html/guide/practices/ui_guidelines/icon_design.jd
index 5f0a278bed92..e5a1b5e29895 100644
--- a/docs/html/guide/practices/ui_guidelines/icon_design.jd
+++ b/docs/html/guide/practices/ui_guidelines/icon_design.jd
@@ -847,118 +847,118 @@ icons in your applications..
-
+
Alarm Clock
-
+
Browser
-
+
Calculator
-
+
Calendar
-
+
Camcorder
-
+
Camera
-
+
Contacts
-
+
Dialer
-
+
Email
-
+
Gallery
-
+
Generic application
-
+
Gmail
-
+
Google Talk
-
+
IM
-
+
Maps
-
+
Market
-
+
Messaging
-
+
Music
-
+
Settings
-
+
Voice Dialer
-
+
Voice Search
-
+
YouTube
diff --git a/docs/html/guide/publishing/app-signing.jd b/docs/html/guide/publishing/app-signing.jd
index a16c9106ad93..f0febc09785a 100644
--- a/docs/html/guide/publishing/app-signing.jd
+++ b/docs/html/guide/publishing/app-signing.jd
@@ -22,10 +22,11 @@ page.title=Signing Your Applications
@@ -71,6 +72,7 @@ application's signer certificate expires after the application is installed, the
will continue to function normally.
You can use standard tools — Keytool and Jarsigner — to generate keys and
sign your application .apk files.
+
Once you have signed the application, use the zipalign tool to optimize the final APK package.
The Android system will not install or run an application that is not signed appropriately. This
@@ -107,6 +109,9 @@ There are two ways to do this:
+
Once your application is signed, don't forget to run {@code zipalign} on the APK
+for additional optimization.
+
Signing Strategies
Some aspects of application signing may affect how you approach the development
@@ -171,16 +176,16 @@ use a suitable certificate to sign your applications.
Basic Setup for Signing
-
To support the generation of a keystore and debug key, you should first make sure that
+
Before you begin, you should make sure that
Keytool is available to the SDK build
-tools. In most cases, you can tell the SDK build tools how to find Keytool by making sure
-that your JAVA_HOME environment variable is set and that it references a suitable JDK.
-Alternatively, you can add the JDK version of Keytool to your PATH variable.
+tools. In most cases, you can tell the SDK build tools how to find Keytool by setting
+your JAVA_HOME environment variable to references a suitable JDK.
+Alternatively, you can add the JDK version of Keytool to your PATH variable.
If you are developing on a version of Linux that originally came with GNU Compiler for
Java, make sure that the system is using the JDK version of Keytool, rather than the gcj
-version. If Keytool is already in your PATH, it might be pointing to a symlink at
-/usr/bin/keytool. In this case, check the symlink target to make sure that it points
+version. If Keytool is already in your PATH, it might be pointing to a symlink at
+/usr/bin/keytool. In this case, check the symlink target to be sure it points
to the Keytool in the JDK.
If you will release your application to the public, you will also need to have
@@ -191,46 +196,50 @@ in the JDK.
The Android build tools provide a debug signing mode that makes it easier for you
to develop and debug your application, while still meeting the Android system
-requirement for signing your .apk when it is installed in the emulator or a device.
-When you use debug mode, the SDK tools invoke Keytool to create a debug
-keystore and key.
+requirement for signing your .apk.
+When using debug mode to build your app, the SDK tools invoke Keytool to automatically create
+a debug keystore and key. This debug key is then used to automatically sign the .apk, so
+you do not need to sign the package with your own key.
-
The SDK tools create the debug keystore/key with predetermined names/passwords;
+
The SDK tools create the debug keystore/key with predetermined names/passwords:
-
Keystore name – "debug.keystore"
-
Keystore password – "android"
-
Key alias – "androiddebugkey"
-
Key password – "android"
-
CN – "CN=Android Debug,O=Android,C=US"
+
Keystore name: "debug.keystore"
+
Keystore password: "android"
+
Key alias: "androiddebugkey"
+
Key password: "android"
+
CN: "CN=Android Debug,O=Android,C=US"
If necessary, you can change the location/name of the debug keystore/key or
-supply a custom debug keystore/key to use. In Eclipse/ADT, you can use
-Windows > Prefs >
-Android > Build. However, any custom debug
+supply a custom debug keystore/key to use. However, any custom debug
keystore/key must use the same keystore/key names and passwords as the default
-debug key (as described above).
+debug key (as described above). (To do so in Eclipse/ADT, go to
+Windows > Preferences >
+Android > Build.)
-
Note: You cannot release your application
+
Caution: You cannot release your application
to the public when signed with the debug certificate.
Eclipse Users
-
If you are developing in Eclipse/ADT and have set up Keytool as described
-above, signing in debug mode is enabled by default. When you run or debug your
-application, ADT signs the .apk with the debug certificate and installs it on
-the emulator. No specific action on your part is needed, provided ADT has
-access to Keytool.
+
If you are developing in Eclipse/ADT (and have set up Keytool as described above in
+Basic Setup for Signing),
+signing in debug mode is enabled by default. When you run or debug your
+application, ADT signs the .apk with the debug certificate, runs {@code zipalign} on the
+package, then installs it on
+the selected emulator or connected device. No specific action on your part is needed,
+provided ADT has access to Keytool.
Ant Users
-
If you use Ant to build your .apk files, debug signing mode
-is enabled by using the debug option, assuming that you are using a
-build.xml file generated by the
-android tool. When you run ant debug to
+
If you are using Ant to build your .apk files, debug signing mode
+is enabled by using the debug option with the ant command
+(assuming that you are using a build.xml file generated by the
+android tool). When you run ant debug to
compile your app, the build script generates a keystore/key and signs the .apk for you.
+The script then also aligns the .apk with the zipalign tool.
No other action on your part is needed. Read
-Developing In Other IDEs: Building
+Developing In Other IDEs: Building
in debug mode for more information.
@@ -268,51 +277,20 @@ certificate.
When your application is ready for release to other users, you must:
The sections below provide information about how to perform these steps.
-
-
If you use Eclipse with the ADT plugin, you can instead use the Export Wizard
-to compile and sign an .apk with your private key. The Export Wizard even allows you to
-generate a new keystore and private key in the process. Skip to
-Compiling and signing with Eclipse ADT.
-
-
-
Compiling for release
-
-
To prepare your application for release, you must first compile it in release mode.
-In release mode, the Android build tools compile your application as usual,
-but without signing it with the debug key.
-
-
Note:
-You can not release your application unsigned, or signed with the debug key.
+
If you are developing in Eclipse with the ADT plugin, you can use the Export Wizard
+to perform the compile, sign, and align procedures. The Export Wizard even allows you to
+generate a new keystore and private key in the process. So if you use Eclipse, you can
+skip to Compile and sign with Eclipse ADT.
-
Eclipse users
-
To export an unsigned .apk from Eclipse, right-click the project in the Package
-Explorer and select Android Tools > Export Unsigned Application
-Package. Then simply specify the file location for the unsigned .apk.
-(Alternatively, open your AndroidManifest.xml file in Eclipse, open
-the Overview tab, and click Export an unsigned .apk.)
If you are using Ant, all you need to do is specify the build target
-"release" in the Ant command. For example, if you are running Ant from the
-directory containing your build.xml file, the command would look like this:
-
-
$ ant release
-
-
The build script compiles the application .apk without signing it.
-
-
-
Obtaining a Suitable Private Key
+
1. Obtain a suitable private key
In preparation for signing your application, you must first ensure that
you have a suitable private key with which to sign. A suitable private
@@ -339,7 +317,8 @@ in Basic Setup.
command and pass any of the options listed below (and any others, as
needed).
-
Note: Before you run Keytool, make sure to read
+
Warning: Keep your private key secure.
+Before you run Keytool, make sure to read
Securing Your Private Key for a discussion of how to keep
your key secure and why doing so is critically important to you and to users. In
particular, when you are generating your key, you should select strong passwords
@@ -395,7 +374,6 @@ way, your password is not stored in your shell history.
-
Here's an example of a Keytool command that generates a private key:
When you are ready to actually sign your .apk for release, you can do so
+
2. Compile the application in release mode
+
+
In order to release your application to users, you must compile it in release mode.
+In release mode, the compiled application is not signed by default and you will need
+to sign it with your private key.
+
+
Caution:
+You can not release your application unsigned, or signed with the debug key.
+
+
With Eclipse
+
+
To export an unsigned .apk from Eclipse, right-click the project in the Package
+Explorer and select Android Tools > Export Unsigned Application
+Package. Then specify the file location for the unsigned .apk.
+(Alternatively, open your AndroidManifest.xml file in Eclipse, open
+the Overview tab, and click Export an unsigned .apk.)
If you are using Ant, you can enable release mode by using the release option
+with the ant command. For example, if you are running Ant from the
+directory containing your {@code build.xml} file, the command would look like this:
+
+
ant release
+
+
By default, the build script compiles the application .apk without signing it. The output file
+in your project {@code bin/} will be <your_project_name>-unsigned.apk.
+Because the application .apk is still unsigned, you must manually sign it with your private
+key and then align it using {@code zipalign}.
+
+
However, the Ant build script can also perform the signing
+and aligning for you, if you have provided the path to your keystore and the name of
+your key alias in the project's {@code build.properties} file. With this information provided,
+the build script will prompt you for your keystore and alias password when you perform
+ant release, it will sign the package and then align it. The final output
+file in {@code bin/} will instead be
+<your_project_name>-release.apk. With these steps
+automated for you, you're able to skip the manual procedures below (steps 3 and 4).
+To learn how to specify your keystore and alias in the {@code build.properties} file,
+see Developing In Other
+IDEs: Building in release mode.
+
+
+
+
3. Sign your application with your private key
+
+
When you have an application package that is ready to be signed, you can do sign it
using the Jarsigner tool. Make sure that you have Jarsigner available on your
machine, as described in Basic Setup. Also, make sure that
the keystore containing your private key is available.
When using Eclipse with ADT, you can use the Export Wizard to
+
Once you have signed the .apk with your private key, run zipalign on the file.
+This tool ensures that all uncompressed data starts with a particular byte alignment,
+relative to the start of the file. Ensuring alignment at 4-byte boundaries provides
+a performance optimization when installed on a device. When aligned, the Android
+system is able to read files with {@code mmap()}, even if
+they contain binary data with alignment restrictions, rather than copying all
+of the data from the package. The benefit is a reduction in the amount of
+RAM consumed by the running application.
+
+
The zipalign tool is provided with the Android SDK, inside the
+tools/ directory. To align your signed .apk, execute:
The {@code -v} flag turns on verbose output (optional). {@code 4} is the
+byte-alignment (don't use anything other than 4). The first file argument is
+your signed .apk (the input) and the second file is the destination .apk file (the output).
+If you're overriding an existing .apk, add the {@code -f} flag.
+
+
Caution: Your input .apk must be signed with your
+private key before you optimize the package with {@code zipalign}.
+If you sign it after using {@code zipalign}, it will undo the alignment.
+
+
For more information, read about the
+zipalign tool.
+
+
+
Compile and sign with Eclipse ADT
+
+
If you are using Eclipse with the ADT plugin, you can use the Export Wizard to
export a signed .apk (and even create a new keystore,
if necessary). The Export Wizard performs all the interaction with
-the Keytool and Jarsigner for you, which allows you to perform signing via a
-graphical interface instead of the command-line.
+the Keytool and Jarsigner for you, which allows you to sign the package using a GUI
+instead of performing the manual procedures to compile, sign,
+and align, as discussed above. Once the wizard has compiled and signed your package,
+it will also perfom package alignment with {@code zipalign}.
Because the Export Wizard uses both Keytool and Jarsigner, you should
ensure that they are accessible on your computer, as described above
in the Basic Setup for Signing.
-
To create a signed .apk, right-click the project in the Package
-Explorer and select Android Tools > Export Signed Application Package.
-(Alternatively, open your AndroidManifest.xml file in Eclipse, open
-the Overview tab, and click Use the Export Wizard.)
-The window that appears will display any errors found while
-attempting to export your application. If no errors are found, continue with the
-Export Wizard, which will guide you through the process of signing your application,
-including steps for selecting the private key with which to sign the .apk,
-or creating a new keystore and private key.
-
-
When you complete the Export Wizard, you'll
-have a signed .apk that's ready for distribution.
+
To create a signed and aligned .apk in Eclipse:
+
+
+
Select the project in the Package
+Explorer and select File > Export.
+
Open the Android folder, select Export Android Application,
+ and click Next.
+
The Export Android Application wizard now starts, which will
+ guide you through the process of signing your application,
+ including steps for selecting the private key with which to sign the .apk
+ (or creating a new keystore and private key).
+
Complete the Export Wizard and your application will be compiled,
+ signed, aligned, and ready for distribution.
+
+
Securing Your Private Key
diff --git a/docs/html/guide/publishing/preparing.jd b/docs/html/guide/publishing/preparing.jd
index b4eaea39607f..5357166eb17a 100644
--- a/docs/html/guide/publishing/preparing.jd
+++ b/docs/html/guide/publishing/preparing.jd
@@ -220,22 +220,20 @@ elements, any MapView elements referencing the old Key will not have permission
to download Maps data.
-
@@ -125,31 +125,44 @@ applications use the
{@link android.content.pm.PackageManager#getPackageInfo(java.lang.String, int)}
method of {@link android.content.pm.PackageManager PackageManager}.
-
Specifying Minimum System API Version
+
Specifying Your Application's System API Requirements
If your application requires a specific minimum version of the Android
-platform, you can specify that version as an API Level identifier
+platform, or is designed only to support a certain range of Android platform
+versions, you can specify those version requirements as API Level identifiers
in the application's manifest file. Doing so ensures that your
application can only be installed on devices that
are running a compatible version of the Android system.
-
To specify the minimum system version in the manifest, use this attribute:
+
To specify API Level requirements, add a <uses-sdk>
+element in the application's manifest, with one or more of these attributes:
-
android:minSdkVersion — An integer value corresponding to
-the code version of the Android platform.
-
When preparing to install an application, the system checks the value of this
+
android:minSdkVersion — The minimum version
+of the Android platform on which the application will run, specified
+by the platform's API Level identifier.
+
android:maxSdkVersion — The maximum version
+of the Android platform on which the application is designed to run,
+specified by the platform's API Level identifier.
+
+
+
When preparing to install your application, the system checks the value of this
attribute and compares it to the system version. If the
android:minSdkVersion value is greater than the system version, the
-system aborts the installation of the application.
+system aborts the installation of the application. Similarly, the system
+installs your application only if its android:maxSdkVersion
+is compatible with the platform version.
-
If you do not specify this attribute in your manifest, the system assumes
-that your application is compatible with all platform versions.
-
+
If you do not specify these attributes in your manifest, the system assumes
+that your application is compatible with all platform versions, with no
+maximum API Level.
To specify a minimum platform version for your application, add a
<uses-sdk> element as a child of
<manifest>, then define the
android:minSdkVersion as an attribute.
@@ -31,7 +32,7 @@ broadcast receivers — are activated through messages, called intents
@@ -40,7 +41,9 @@ delivering intents to each type of component:
An Intent object is passed to {@link android.content.Context#startActivity
Context.startActivity()} or {@link android.app.Activity#startActivityForResult
Activity.startActivityForResult()} to launch an activity or get an existing
-activity to do something new.
+activity to do something new. (It can also be passed to
+{@link android.app.Activity#setResult(int, Intent) Activity.setResult()}
+to return information to the activity that called {@code startActivityForResult()}.)
An Intent object is passed to {@link android.content.Context#startService
Context.startService()} to initiate a service or deliver new instructions to an
@@ -380,22 +383,12 @@ component's filters.
A component has separate filters for each job it can do, each face it can
-present to the user. For example, the principal activity of the sample
-NotePad application has three filters — one for starting up with a
-blank slate, another for starting with an assigned directory of notes
-that the user can view, edit, or select from, and a third for finding a
-particular note without an initial specification of its directory.
-
-
-
-An intent filter is an instance of the {@link android.content.IntentFilter} class.
-However, since the Android system must know about the capabilities of a component
-before it can launch that component, intent filters are generally not set up in
-Java code, but in the application's manifest file (AndroidManifest.xml) as
-{@code <intent-filter>} elements. (The one exception would be filters for
-broadcast receivers that are registered dynamically by calling {@link android.content.Context#registerReceiver(BroadcastReceiver, IntentFilter, String,
-Handler) Context.registerReceiver()}; they are directly created as
-IntentFilter objects.)
+present to the user. For example, the NoteEditor activity of the sample
+Note Pad application has two filters — one for starting up with a
+specific note that the user can view or edit, and another for starting
+with a new, blank note that the user can fill in and save. (All of Note
+Pad's filters are described in the Note Pad Example
+section, later.)
@@ -412,6 +405,18 @@ name the component as the target.
+
+An intent filter is an instance of the {@link android.content.IntentFilter} class.
+However, since the Android system must know about the capabilities of a component
+before it can launch that component, intent filters are generally not set up in
+Java code, but in the application's manifest file (AndroidManifest.xml) as
+<intent-filter>
+elements. (The one exception would be filters for
+broadcast receivers that are registered dynamically by calling {@link android.content.Context#registerReceiver(BroadcastReceiver, IntentFilter, String,
+Handler) Context.registerReceiver()}; they are directly created as
+IntentFilter objects.)
+
+
A filter has fields that parallel the action, data, and category fields of an
Intent object. An implicit intent is tested against the filter in all three areas.
@@ -429,8 +434,11 @@ Each of the three tests is described in detail below:
Action test
-
An {@code <intent-filter>} element in the manifest file lists actions
-as {@code <action>} subelements. For example:
+
An
+<intent-filter>
+element in the manifest file lists actions as
+<action>
+subelements. For example:
<intent-filter . . . >
<action android:name="com.example.project.SHOW_CURRENT" />
@@ -464,8 +472,9 @@ contains at least one action.
Category test
-
An {@code <intent-filter>} element also lists categories as subelements.
-For example:
+
An
+<intent-filter>
+element also lists categories as subelements. For example:
<intent-filter . . . >
<category android:name="android.intent.category.DEFAULT" />
@@ -512,14 +521,16 @@ is contained in a subelement. And, as in those cases, the subelement can appear
multiple times, or not at all. For example:
-Each {@code <data>} element can specify a URI and a data type (MIME media type).
-There are separate attributes — {@code scheme}, {@code host}, {@code port},
+Each
+<data>
+element can specify a URI and a data type (MIME media type). There are separate
+attributes — {@code scheme}, {@code host}, {@code port},
and {@code path} — for each part of the URI:
@@ -607,7 +618,7 @@ for example, tells Android that the component can get image data from a content
provider and display it:
-
<data android:type="image/*" />
+
<data android:mimeType="image/*" />
Since most available data is dispensed by content providers, filters that
@@ -681,6 +692,357 @@ can respond. There's a similar method,
queryBroadcastReceivers()}, for broadcast receivers.
+
Note Pad Example
+
+
+The Note Pad sample application enables users to browse through a list
+of notes, view details about individual items in the list, edit the items,
+and add a new item to the list. This section looks at the intent filters
+declared in its manifest file. (If you're working offline in the SDK, you
+can find all the source files for this sample application, including its
+manifest file, at {@code <sdk>/samples/NotePad/index.html}.
+If you're viewing the documentation online, the source files are in the
+Tutorials and Sample Code
+section here.)
+
+
+
+In its manifest file, the Note Pad application declares three activities,
+each with at least one intent filter. It also declares a content provider
+that manages the note data. Here is the manifest file in its entirety:
+
+The first activity, NotesList, is
+distinguished from the other activities by the fact that it operates
+on a directory of notes (the note list) rather than on a single note.
+It would generally serve as the initial user interface into the
+application. It can do three things as described by its three intent
+filters:
+
+This filter declares the main entry point into the Note Pad application.
+The standard {@code MAIN} action is an entry point that does not require
+any other information in the Intent (no data specification, for example),
+and the {@code LAUNCHER} category says that this entry point should be
+listed in the application launcher.
+
+This filter declares the things that the activity can do on a directory
+of notes. It can allow the user to view or edit the directory (via
+the {@code VIEW} and {@code EDIT} actions), or to pick a particular note
+from the directory (via the {@code PICK} action).
+
+
+
+The {@code mimeType} attribute of the
+<data>
+element specifies the kind of data that these actions operate on. It
+indicates that the activity can get a Cursor over zero or more items
+({@code vnd.android.cursor.dir}) from a content provider that holds
+Note Pad data ({@code vnd.google.note}). The Intent object that launches
+the activity would include a {@code content:} URI specifying the exact
+data of this type that the activity should open.
+
+
+
+Note also the {@code DEFAULT} category supplied in this filter. It's
+there because the {@link android.content.Context#startActivity
+Context.startActivity()} and
+{@link android.app.Activity#startActivityForResult
+Activity.startActivityForResult()} methods treat all intents
+as if they contained the {@code DEFAULT} category — with just
+two exceptions:
+
+
+
+
Intents that explicitly name the target activity
+
Intents consisting of the {@code MAIN} action and {@code LAUNCHER}
+category
+
+
+
+Therefore, the {@code DEFAULT} category is required for all
+filters — except for those with the {@code MAIN} action and
+{@code LAUNCHER} category. (Intent filters are not consulted for
+explicit intents.)
+
+This filter describes the activity's ability to return a note selected by
+the user without requiring any specification of the directory the user should
+choose from. The {@code GET_CONTENT} action is similar to the {@code PICK}
+action. In both cases, the activity returns the URI for a note selected by
+the user. (In each case, it's returned to the activity that called
+{@link android.app.Activity#startActivityForResult
+startActivityForResult()} to start the NoteList activity.) Here,
+however, the caller specifies the type of data desired instead of the
+directory of data the user will be picking from.
+
+
+
+The data type, vnd.android.cursor.item/vnd.google.note,
+indicates the type of data the activity can return — a URI for
+a single note. From the returned URI, the caller can get a Cursor for
+exactly one item ({@code vnd.android.cursor.item}) from the content
+provider that holds Note Pad data ({@code vnd.google.note}).
+
+
+
+In other words, for the {@code PICK} action in the previous filter,
+the data type indicates the type of data the activity could display to the
+user. For the {@code GET_CONTENT} filter, it indicates the type of data
+the activity can return to the caller.
+
+
+
+
+Given these capabilities, the following intents will resolve to the
+NotesList activity:
+
Launches the activity with no data selected specified.
+This is the actual intent used by the Launcher to populate its top-level
+list. All activities with filters that match this action and category
+are added to the list.
Asks the activity to display a list of all the notes under
+content://com.google.provider.NotePad/notes. The user can then
+browse through the list and get information about the items in it.
Asks the activity to display a list of the notes under
+content://com.google.provider.NotePad/notes.
+The user can then pick a note from the list, and the activity will return
+the URI for that item back to the activity that started the NoteList activity.
+
+
action: android.intent.action.GET_CONTENT
+ data type: vnd.android.cursor.item/vnd.google.note
+
Asks the activity to supply a single item of Note Pad data.
+
+
+
+The second activity, NoteEditor, shows
+users a single note entry and allows them to edit it. It can do two things
+as described by its two intent filters:
+
+
+The first, primary, purpose of this activity is to enable the user to
+interact with a single note &mdash to either {@code VIEW} the note or
+{@code EDIT} it. (The {@code EDIT_NOTE} category is a synonym for
+{@code EDIT}.) The intent would contain the URI for data matching the
+MIME type vnd.android.cursor.item/vnd.google.note —
+that is, the URI for a single, specific note. It would typically be a
+URI that was returned by the {@code PICK} or {@code GET_CONTENT}
+actions of the NoteList activity.
+
+
+
+As before, this filter lists the {@code DEFAULT} category so that the
+activity can be launched by intents that don't explicitly specify the
+NoteEditor class.
+
+The secondary purpose of this activity is to enable the user to create a new
+note, which it will {@code INSERT} into an existing directory of notes. The
+intent would contain the URI for data matching the MIME type
+vnd.android.cursor.dir/vnd.google.note — that
+is, the URI for the directory where the note should be placed.
+
+
+
+
+Given these capabilities, the following intents will resolve to the
+NoteEditor activity:
+
Asks the activity to display the content of the note identified
+by {@code ID}. (For details on how {@code content:} URIs
+specify individual members of a group, see
+Content Providers.)
+
+
Asks the activity to display the content of the note identified
+by {@code ID}, and to let the user edit it. If the user
+saves the changes, the activity updates the data for the note in the
+content provider.
Asks the activity to create a new, empty note in the notes list at
+content://com.google.provider.NotePad/notes
+and allow the user to edit it. If the user saves the note, its URI
+is returned to the caller.
+
+
+
+
The last activity, TitleEditor,
+enables the user to edit the title of a note. This could be implemented
+by directly invoking the activity (by explicitly setting its component
+name in the Intent), without using an intent filter. But here we take
+the opportunity to show how to publish alternative operations on existing
+data:
+
+The single intent filter for this activity uses a custom action called
+"com.android.notepad.action.EDIT_TITLE". It must be invoked on
+a specific note (data type vnd.android.cursor.item/vnd.google.note),
+like the previous {@code VIEW} and {@code EDIT} actions. However, here the
+activity displays the title contained in the note data, not the content of
+the note itself.
+
+
+
+In addition to supporting the usual {@code DEFAULT} category, the title
+editor also supports two other standard categories:
+{@link android.content.Intent#CATEGORY_ALTERNATIVE ALTERNATIVE}
+and {@link android.content.Intent#CATEGORY_SELECTED_ALTERNATIVE
+SELECTED_ALTERNATIVE}.
+These categories identify activities that can be presented to users in
+a menu of options (much as the {@code LAUNCHER} category identifies
+activities that should be presented to user in the application launcher).
+Note that the filter also supplies an explicit label (via
+android:label="@string/resolve_title") to better control
+what users see when presented with this activity as an alternative
+action to the data they are currently viewing. (For more information
+on these categories and building options menus, see the
+{@link android.content.pm.PackageManager#queryIntentActivityOptions
+PackageManager.queryIntentActivityOptions()} and
+{@link android.view.Menu#addIntentOptions Menu.addIntentOptions()}
+methods.)
+
+
+
+Given these capabilities, the following intent will resolve to the
+TitleEditor activity:
+
Asks the activity to display the title associated with note ID, and
+allow the user to edit the title.
+
+
diff --git a/docs/html/guide/topics/manifest/manifest-element.jd b/docs/html/guide/topics/manifest/manifest-element.jd
index a9d10906add0..48e598a4ef4a 100644
--- a/docs/html/guide/topics/manifest/manifest-element.jd
+++ b/docs/html/guide/topics/manifest/manifest-element.jd
@@ -44,8 +44,11 @@ to "{@code http://schemas.android.com/apk/res/android}".
{@code package}
A full Java package name for the application. The name should
-be unique. For example, applications published by Google could have
-names in the form com.google.app.application_name.
+be unique. The name may contain uppercase or lowercase letters ('A'
+through 'Z'), numbers, and underscores ('_'). However, individual
+package name parts may only start with letters. For example, applications
+published by Google could have names in the form
+com.google.app.application_name.
The package name serves as a unique identifier for the application.
diff --git a/docs/html/guide/topics/manifest/provider-element.jd b/docs/html/guide/topics/manifest/provider-element.jd
index 3942f95084be..98892f1aeb1a 100644
--- a/docs/html/guide/topics/manifest/provider-element.jd
+++ b/docs/html/guide/topics/manifest/provider-element.jd
@@ -111,7 +111,7 @@ temporarily overcoming the restriction imposed by the
writePermission, and
permission attributes
—
-"{@code true}" if permission can be granted, and "{@ code false}" if not.
+"{@code true}" if permission can be granted, and "{@code false}" if not.
If "{@code true}", permission can be granted to any of the content
provider's data. If "{@code false}", permission can be granted only
to the data subsets listed in
diff --git a/docs/html/guide/topics/manifest/supports-screens-element.jd b/docs/html/guide/topics/manifest/supports-screens-element.jd
index 00797edd5566..3fb0172addea 100644
--- a/docs/html/guide/topics/manifest/supports-screens-element.jd
+++ b/docs/html/guide/topics/manifest/supports-screens-element.jd
@@ -30,40 +30,8 @@ framework will scale down assets by a factor of 0.75 (low dpi screens)
or scale them up by a factor of 1.5 (high dpi screens).
The screen density is expressed as dots-per-inch (dpi).
diff --git a/docs/html/guide/topics/manifest/uses-sdk-element.jd b/docs/html/guide/topics/manifest/uses-sdk-element.jd
index ee8d03dc06d1..aa1e8aee4a41 100644
--- a/docs/html/guide/topics/manifest/uses-sdk-element.jd
+++ b/docs/html/guide/topics/manifest/uses-sdk-element.jd
@@ -36,30 +36,27 @@ and minor versions).
{@code android:minSdkVersion}
-
An integer designating the minimum level of the Android API that's required
- for the application to run.
+
An integer designating the minimum API Level required
+ for the application to run. The Android system will prevent the user from installing
+ the application if the system's API Level is lower than the value specified in
+ this attribute. You should always declare this attribute.
-
Prior to installing an application, the Android system checks the value of this
- attribute and allows the installation only if it
- is less than or equal to the API Level used by the system itself.
-
-
If you do not declare this attribute, then a value of "1" is assumed, which
+
Caution:
+ If you do not declare this attribute, then a value of "1" is assumed, which
indicates that your application is compatible with all versions of Android. If your
- application is not universally compatible (for instance if it uses APIs
- introduced in Android 1.5) and you have not declared the proper minSdkVersion,
- then when installed on a system with a lower API Level, the application
- will crash during runtime. For this reason, be certain to declare the appropriate API Level
+ application is not compatible with all versions (for instance, it uses APIs
+ introduced in API Level 3) and you have not declared the proper minSdkVersion,
+ then when installed on a system with an API Level less than 3, the application will crash
+ during runtime when attempting to access the unavailable APIs. For this reason,
+ be certain to declare the appropriate API Level
in the minSdkVersion attribute.
{@code android:maxSdkVersion}
-
An integer designating the maximum level of the Android API that the application is
- compatible with. You can use this to ensure your application is filtered out
- of later versions of the platform when you know you have incompatibility with them.
-
-
Prior to installing an application, the Android system checks the value of this
- attribute and allows the installation only it
- is greater than or equal to the API Level used by the system itself.
+
An integer designating the maximum API Level on which the application is
+ designed to run. The Android system will prevent the user from installing the
+ application if the system's API Level is higher than the value specified
+ in this attribute.
@@ -86,7 +87,7 @@ XML files such as layouts.
<color> tags.
- Resource source file location: res/values/colors.xml (file name is arbitrary)
+ Resource source file location: {@code res/values/colors.xml} (File name is arbitrary.)
Compiled resource datatype: Resource pointer to a Java int.
@@ -183,7 +184,7 @@ tags.
Source file format: XML file requiring a <?xml version="1.0" encoding="utf-8"?> declaration, and a root <resources> element containing one or more <string> tags.
- Resource source file location: res/values/strings.xml (file name is arbitrary)
+ Resource source file location: {@code res/values/strings.xml} (File name is arbitrary.)
Compiled resource datatype: Resource pointer to a Java CharSequence.
@@ -338,8 +339,8 @@ version="1.0" encoding="utf-8"?> declaration, and a root
<resources> element containing one or more
<dimen> tags.
-
Resource source file location: res/values/dimens.xml (File
-name is arbitrary; standard practice is to put all dimensions in one file
+
Resource source file location: {@code res/values/dimens.xml} (File
+name is arbitrary, but standard practice is to put all dimensions in one file
devoted to dimensions.)
Compiled resource datatype: Resource pointer to a
dimension.
@@ -424,7 +425,7 @@ res/drawable/my_picture.png would be referenced as R.drawable.my_picture).
Source file formats: png (preferred), jpg (acceptable), gif (discouraged). One resource per file.
- Resource file location: res/drawable/some_file.png or some_file.jpg or some_file.gif.
+ Resource file location: {@code res/drawable/some_file.png}
Compiled resource datatype: Resource pointer to a {@link android.graphics.drawable.BitmapDrawable BitmapDrawable}.
@@ -453,7 +454,8 @@ version="1.0" encoding="utf-8"?> declaration, and a root
<resources> element containing one or more
<drawable> tags.
- Resource source file location: res/values/colors.xml (File name is arbitrary; standard practice is to put the PaintDrawable items in the file along with the numeric color values.)
+ Resource source file location: {@code res/values/colors.xml} (File name is arbitrary, but standard practice is to put the PaintDrawable
+ items in the file along with the numeric color values.)
Compiled resource datatype: Resource pointer to a {@link android.graphics.drawable.PaintDrawable}.
@@ -540,7 +542,7 @@ tv.setBackground(redDrawable);
Source file format: PNG — one resource per file
- Resource source file location: res/drawable/some_name.9.png (must end in .9.png)
+ Resource source file location: {@code res/drawable/some_name.9.png} (Filename must end in {@code .9.png})
Compiled resource datatype: Resource pointer to an {@link android.view.animation.Animation}.
@@ -906,7 +908,7 @@ res/layout/some_file.xml.
<ViewGroupClass xmlns:android="http://schemas.android.com/apk/res/android"
- id="@+id/string_name" (attributes)>
+ android:id="@+id/string_name" (attributes)>
<widget or other nested ViewGroupClass>+
<requestFocus/>(0 or 1 per layout file, assigned to any element)
</ViewGroupClass>
@@ -917,7 +919,7 @@ res/layout/some_file.xml.
The file must have a single root element. This can be a ViewGroup class that contains other elements, or a widget (or custom item) if it's only one object. By default, you can use any (case-sensitive) Android {@link android.widget widget} or {@link android.view.ViewGroup ViewGroup} class name as an element. These elements support attributes that apply to the underlying class, but the naming is not as clear. How to discover what attributes are supported for what tags is discussed below. You should not assume that any nesting is valid (for example you cannot enclose <TextView> elements inside a <ListLayout>).
-
If a class derives from another class, the XML element inherits all the attributes from the element that it "derives" from. So, for example, <EditText> is the corresponding XML element for the EditText class. It exposes its own unique attributes (EditText_numeric), as well as all attributes supported by <TextView> and <View>. For the id attribute of a tag in XML, you should use a special syntax: "@+id/somestringvalue". The "@+" syntax creates a resource number in the R.id class, if one doesn't exist, or uses it, if it does exist. When declaring an ID value for an XML tag, use this syntax. Example: <TextView id="@+id/nameTextbox"/>, and refer to it this way in Java: findViewById(R.id.nameTextbox). All elements support the following values:
+
If a class derives from another class, the XML element inherits all the attributes from the element that it "derives" from. So, for example, <EditText> is the corresponding XML element for the EditText class. It exposes its own unique attributes (EditText_numeric), as well as all attributes supported by <TextView> and <View>. For the id attribute of a tag in XML, you should use a special syntax: "@+id/somestringvalue". The "@+" syntax creates a resource number in the R.id class, if one doesn't exist, or uses it, if it does exist. When declaring an ID value for an XML tag, use this syntax. Example: <TextView android:id="@+id/nameTextbox"/>, and refer to it this way in Java: findViewById(R.id.nameTextbox). All elements support the following values:
id - An ID value used to access this element in Java. Typically you will use the syntax @+id/string_name to generate an ID for you in the id.xml file if you haven't created one yourself.
@@ -1005,7 +1007,7 @@ res/layout/some_file.xml.
android:paddingBottom="4" // TextView.paddingBottom
android:text="@string/redirect_getter"/> // TextView.text
- <EditText id="@+id/text"
+ <EditText android:id="@+id/text"
android:layout_width="fill_parent" // EditText.LayoutParams.width
android:layout_height="wrap_content" // EditText.LayoutParams.height
android:layout_weight="0" // EditText.LinearLayoutParams.weight
@@ -1013,7 +1015,7 @@ res/layout/some_file.xml.
<requestFocus />
</EditText>
- <Button id="@+id/apply"
+ <Button android:id="@+id/apply"
android:layout_width="wrap_content" // Button.LayoutParams.width
android:layout_height="wrap_content" // Button.LayoutParams.height
android:text="@string/apply" /> // TextView.text
@@ -1045,7 +1047,7 @@ setContentView(R.layout.main_screen);
Java implementation file - The implementation file. The class must extend {@link android.view.View View} or a subclass. See LabelView.java in ApiDemos.
- res/values/attrs.xml - Defines the XML element, and the attributes that it supports, for clients to use to instantiate your object in their layout XML file. Define your element in a <declare-styleable id=your_java_class_name>. See res/layout/attrs.xml in ApiDemos.
+ res/values/attrs.xml - Defines the XML element, and the attributes that it supports, for clients to use to instantiate your object in their layout XML file. Define your element in a <declare-styleable name=your_java_class_name>. See res/values/attrs.xml in ApiDemos.
res/layout/your_class.xml [optional] - An optional XML file to describe the layout of your object. This could also be done in Java. See custom_view_1.xml in ApiDemos.
@@ -1055,7 +1057,7 @@ setContentView(R.layout.main_screen);
Source file format: XML file without an <?xml> declaration, and a <resources> root element containing one or more custom element tags.
- Resource file location: res/values/attrs.xml (file name is arbitrary).
+ Resource file location: {@code res/values/attrs.xml} (File name is arbitrary.)
Compiled resource datatype: Resource pointer to a {@link android.view.View} (or subclass) resource.
@@ -1084,7 +1086,7 @@ setContentView(R.layout.main_screen);
Source file format: XML file requiring a <?xml version="1.0" encoding="utf-8"?> declaration, and a root <resources> element containing one or more <style> tags.
- Resource source file location: res/values/styles.xml (file name is arbitrary). The file name is arbitrary, but standard practice is to put all styles into a file named styles.xml.
+ Resource source file location: {@code res/values/styles.xml} (File name is arbitrary, but standard practice is to put all styles into a file named styles.xml.)
Compiled resource datatype: Resource pointer to a Java CharSequence.
@@ -1133,3 +1135,317 @@ setContentView(R.layout.main_screen);
To make search appear to the user as a seamless system-wide feature, the Android framework
+offers APIs that let applications control how they are searched.
+Applications can customize how search is invoked, how the search dialog looks, and what type of
+search results are available, including suggestions that are shown as the user types.
+
+
In order to utilize the Android search framework, an application must provide a search configuration
+in the form of an XML resource.
+This section describes the search configuration XML in terms of its syntax and usage. For a more
+complete discussion about how to implement search features for your application, see
+
+{@link android.app.SearchManager}.
+
+
+ Source file format:
+ XML file requiring a <?xml version="1.0" encoding="utf-8"?>
+ declaration, and a root <searchable> element.
+
+
+
+ Resource source file location: {@code res/xml/searchable.xml}
+ (The file name is arbitrary, but standard practice is to use searchable.xml.)
+
+
+
+ Compiled resource datatype:
+ Resource pointer to an xml object.
+
+ Defines all application search configurations, including settings for text and voice searches
+ performed within the application. It accepts the following attributes:
+
+
+ label - Required. This is the name for your application, as it
+ will appear to the user. This will be visible only if searchMode is set to
+ "showSearchLabelAsBadge" (see below).
+
+
+ hint - This is the text to display in the search text field when no text has
+ been entered. This is recommended in order to provide context to the search about to be
+ performed (e.g., "Search the Dictionary").
+
+
+ searchMode - If provided and non-zero, this sets additional modes for control
+ of the search presentation. The following mode values are accepted:
+
+
+ showSearchLabelAsBadge - If set, this enables the display of the
+ search target (label) within the search bar.
+
+
+ queryRewriteFromData - If set, this causes the suggestion column
+ SUGGEST_COLUMN_INTENT_DATA to be considered as the text for suggestion query
+ rewriting. This should only be used when the values in
+ SUGGEST_COLUMN_INTENT_DATA are suitable for user inspection and editing -
+ typically, HTTP/HTTPS Uri's.
+
+
+ queryRewriteFromText - If set, this causes the suggestion
+ column SUGGEST_COLUMN_TEXT_1 to be considered as the text for suggestion query
+ rewriting. This should be used for suggestions in which no query
+ text is provided and the SUGGEST_COLUMN_INTENT_DATA values are not suitable
+ for user inspection and editing.
+
+
+
More than one of the above values for searchMode can be used at once. For
+ example, you can declare two modes at once, like this:
+ searchMode="queryRewriteFromData|queryRewriteFromText"
+
+
+ inputType - If provided, supplies a hint about the type of search text
+ the user will be entering. For most searches, in which free form text is expected,
+ this attribute is not needed. See
+ {@link android.R.attr#inputType} for a list of suitable values for this attribute.
+
+
+ imeOptions - If provided, supplies additional options for the input method.
+ For most searches, in which free form text is expected, this attribute is not needed,
+ and will default to "actionSearch". See
+ {@link android.R.attr#imeOptions} for a list of suitable values for this attribute.
+
+
+
+
If you have defined a content provider to generate search suggestions, you need to
+ provide some more searchable metadata in order to configure communications with the content
+ provider. The following are additional {@code <searchable>} attributes for use when
+ providing search suggestions:
+
+
+
+ searchSuggestAuthority - Required to provide search suggestions.
+ This value must match the authority string provided in the provider section of your manifest.
+
+
+ searchSuggestPath - If provided, this path will be inserted in the suggestions
+ query Uri, after the authority you have provide but before the standard suggestions path.
+ This is only required if you have a single content provider issuing different types
+ of suggestions (e.g. for different data types) and you need
+ a way to disambiguate the suggestions queries when they are received.
+
+
+ searchSuggestSelection - If provided, this value will be passed into your
+ query function as the selection parameter. Typically this will be a WHERE clause for
+ your database, and will contain a single question mark, which represents the actual query
+ string that has been typed by the user. However, you can also use any non-null value to simply
+ trigger the delivery of the query text (via selection arguments), and then use the query
+ text in any way appropriate for your provider (ignoring the actual text of the selection parameter.)
+
+
+ searchSuggestIntentAction - The default Intent action to be used when a user
+ clicks on a search suggestion.
+ If provided, and not overridden by the selected suggestion, this value will
+ be placed in the action field of the {@link android.content.Intent} when the
+ user clicks a suggestion.
+
+
+ searchSuggestIntentData - The default Intent data to be used when a user
+ clicks on a search suggestion.
+ If provided, and not overridden by the selected suggestion, this value will be
+ placed in the data field of the {@link android.content.Intent} when the user clicks
+ a suggestion.
+
+
+
+
Beyond providing search suggestions while using your application's local search, you
+ can also configure your search suggestions to be made available to Quick Search Box,
+ which will allow users so receive search suggestions from your application content from outside
+ your application. The following are additional {@code <searchable>} attributes for use when
+ providing search suggestions to Quick Search Box:
+
+
+
+ includeInGlobalSearch - Required to provide search suggestions in
+ Quick Search Box. If true, this indicates the search suggestions provided by your
+ application should be included in the globally accessible Quick Search Box. The user must
+ still enable your application as a searchable item in the system search settings in order
+ for your suggestions to appear in Quick Search Box.
+
+
+ searchSettingsDescription - If provided, this provides a brief description
+ of the search suggestions that you provide to Quick Search Box,
+ and will be displayed in the search settings entry for your application.
+
+
+ queryAfterZeroResults - Indicates whether a source should be invoked for
+ supersets of queries it has returned zero results for in the past. For example, if a
+ source returned zero results for "bo", it would be ignored for "bob". If set to false,
+ this source will only be ignored for a single session; the next time the search dialog
+ is invoked, all sources will be queried. The default value is false.
+
+
+ searchSuggestThreshold - Indicates the minimum number of characters needed to
+ trigger a source lookup from Quick Search Box. Only guarantees that a source will not be
+ queried for anything shorter than the threshold. The default value is 0.
+
+
+
+
To enable voice search for your Activity, you can add fields to the searchable metadata
+ that enable and configure voice search. The following are additional {@code <searchable>}
+ attributes for use when implementing voice search:
+
+
+
+ voiceSearchMode - Required to provide voice search
+ capabilities.
+ If provided and non-zero, enables voice search.
+ (Voice search may not be provided by the device, in which case these flags will
+ have no effect.) The following mode values are accepted:
+
+
+ showVoiceSearchButton - If set, display a voice search button. This only
+ takes effect if voice search is available on the device. If set, then "launchWebSearch"
+ or "launchRecognizer" must also be set.
+
+
+ launchWebSearch - If set, the voice search button will take the user directly
+ to a built-in voice web search activity. Most applications will not use this flag, as
+ it will take the user away from the activity in which search was invoked.
+
+
+ launchRecognizer - If set, the voice search button will take
+ the user directly to a built-in voice recording activity. This activity
+ will prompt the user to speak, transcribe the spoken text, and forward the resulting
+ query text to the searchable activity, just as if the user had typed it into the
+ search UI and clicked the search button.
+
+
+
+
+ voiceLanguageModel - A string constant from
+ {@link android.speech.RecognizerIntent}.
+ If provided, this specifies the language model that
+ should be used by the voice recognition system. See
+ {@link android.speech.RecognizerIntent#EXTRA_LANGUAGE_MODEL } for more
+ information. If not provided, the default value
+ {@link android.speech.RecognizerIntent#LANGUAGE_MODEL_FREE_FORM } will be used.
+
+
+ voicePromptText - A string. If provided, this specifies a prompt
+ that will be displayed during voice input. If not provided, a default prompt
+ will be displayed.
+
+
+ voiceLanguage - A string constant from {@link java.util.Locale}.
+ If provided, this specifies the spoken language to be expected.
+ This is only needed if it is different from the current value of
+ {@link java.util.Locale#getDefault()}.
+
+
+ voiceMaxResults - If provided, enforces the maximum number of results to return,
+ including the "best" result which will always be provided as the SEARCH intent's primary
+ query. Must be one or greater. Use EXTRA_RESULTS to get the results from the intent.
+ If not provided, the recognizer will choose how many results to return.
+
+
+
+
+
+ <actionkey>
+
+
+ Defines a shortcut key for a search action.
+
+
+ keycode - Required. This attribute denotes the action key
+ you wish to respond to. Note that not all action keys are actually supported using
+ this mechanism, as many of them are used for typing,
+ navigation, or system functions. This will be added to the
+ {@link android.content.Intent#ACTION_SEARCH ACTION_SEARCH} Intent that is passed to your
+ searchable Activity. To examine the key code, use
+ {@link android.content.Intent#getIntExtra getIntExtra(SearchManager.ACTION_KEY)}.
+ Note that, in addition to the keycode, you must also provide one or more of
+ the action specifier attributes below.
+
+
+ queryActionMsg - If you wish to handle an action key during normal
+ search query entry, you must define an action string here. This will be added to the
+ {@link android.content.Intent#ACTION_SEARCH ACTION_SEARCH} Intent that is
+ passed to your searchable Activity. To examine the string, use
+ {@link android.content.Intent#getStringExtra
+ getStringExtra(SearchManager.ACTION_MSG)}.
+
+
+ suggestActionMsg - If you wish to handle an action key while a
+ suggestion is being displayed and selected, there are two ways to handle this.
+ If all of your suggestions can handle the action key, you can simply define
+ the action message using this attribute. This will be added to the
+ {@link android.content.Intent#ACTION_SEARCH} Intent that is passed to your
+ searchable Activity. To examine the string,
+ use {@link android.content.Intent#getStringExtra
+ getStringExtra(SearchManager.ACTION_MSG)}.
+
+
+ suggestActionMsgColumn - If you wish to handle an action key while
+ a suggestion is being displayed and selected, but you do not wish to enable
+ this action key for every suggestion, then you can use this attribute to control
+ it on a suggestion-by-suggestion basis. First, you must define a column
+ (and name it here) where your suggestions will include the action string. Then,
+ in your content provider, you must provide this column, and when desired,
+ provide data in this column. The search manager will look at your suggestion cursor,
+ using the string provided here in order to select a column, and will use
+ that to select a string from the cursor. That string will be added to the
+ {@link android.content.Intent#ACTION_SEARCH ACTION_SEARCH}
+ Intent that is passed to your searchable Activity. To examine
+ the string, use {@link android.content.Intent#getStringExtra
+ getStringExtra(SearchManager.ACTION_MSG)}. If the data does not exist for the
+ selection suggestion, the action key will be ignored.
+
Android will run on many devices in many regions. To reach the most users,
+your application should handle text, audio files, numbers, currency, and
+graphics in ways appropriate to the locales where your application will be used.
+
+
+
This document describes best practices for localizing Android
+applications. The principles apply whether you are developing your application
+using ADT with Eclipse, Ant-based tools, or any other IDE.
+
+
You should already have a working knowledge of Java and be familiar with
+Android resource loading, the declaration of user interface elements in XML,
+development considerations such as Activity lifecycle, and general principles of
+internationalization and localization.
+
+
It is good practice to use the Android resource framework to separate the
+localized aspects of your application as much as possible from the core Java
+functionality:
+
+
+
You can put most or all of the contents of your application's
+user interface into resource files, as described in this document and in Resources.
+
The behavior of the user interface, on the other hand, is driven
+by your Java code.
+ For example, if users input data that needs to be formatted or sorted
+differently depending on locale, then you would use Java to handle the data
+programmatically. This document does not cover how to localize your Java code.
+
+
+
+
The Hello, L10N
+ tutorial takes you through the steps of creating a simple localized
+application that uses locale-specific resources in the way described in this
+document.
+
+
+
Overview: Resource-Switching in Android
+
+
Resources are text strings, layouts, sounds, graphics, and any other static
+data that your Android application needs. An application can include multiple
+sets of resources, each customized for a different device configuration. When a
+user runs the application, Android automatically selects and loads the
+resources that best match the device.
+
+
(This document focuses on localization and locale. For a complete description
+of resource-switching and all the types of configurations that you can
+specify — screen orientation, touchscreen type, and so on — see Alternate Resources.)
+
+
+
+
+ When you write your application:
+
+ You create a set of default resources, plus alternates to be used in
+ different locales.
+
+
+
+ When a user runs your application:
+
The Android system selects which resources to load, based on the
+ device's locale.
+
+
+
+
When you write your application, you create default and alternate resources
+for your application to use. To create resources, you place files within
+specially named subdirectories of the project's res/ directory.
+
+
+
+
+
Why Default Resources Are Important
+
+
Whenever the application runs in a locale for which you have not provided
+locale-specific text, Android will load the default strings from
+res/values/strings.xml. If this default file is absent, or if it
+is missing a string that your application needs, then your application will not run
+and will show an error.
+The example below illustrates what can happen when the default text file is incomplete.
+
+
Example:
+
An application's Java code refers to just two strings, text_a and
+ text_b. This application includes a localized resource file
+ (res/values-en/strings.xml) that defines text_a and
+ text_b in English. This application also includes a default
+ resource file (res/values/strings.xml) that includes a
+definition for text_a, but not for text_b:
+
+
This application might compile without a problem. An IDE such as Eclipse
+ will not highlight any errors if a resource is missing.
+
When this application is launched on a device with locale set to English,
+ the application might run without a problem, because
+ res/values-en/strings.xml contains both of the needed text
+ strings.
+
However, the user will see an error message and a Force Close
+ button when this application is launched on a device set to a
+ language other than English. The application will not load.
+
+
+
+
To prevent this situation, make sure that a res/values/strings.xml
+ file exists and that it defines every needed string. The situation applies to
+ all types of resources, not just strings: You
+ need to create a set of default resource files containing all
+ the resources that your application calls upon — layouts, drawables,
+ animations, etc. For information about testing, see
+ Testing for Default Resources.
+
+
Using Resources for Localization
+
+
How to Create Default Resources
+
+
Put the application's default text in
+a file with the following location and name:
+
res/values/strings.xml (required directory)
+
+
The text strings in res/values/strings.xml should use the
+default language, which is the language that you expect most of your application's users to
+speak.
+
+
The default resource set must also include any default drawables and layouts,
+ and can include other types of resources such as animations.
+
+ res/drawable/(required directory holding at least
+ one graphic file, for the application's icon in the Market)
+ res/layout/ (required directory holding an XML
+ file that defines the default layout)
+ res/anim/ (required if you have any
+ res/anim-<qualifiers> folders)
+ res/xml/ (required if you have any
+ res/xml-<qualifiers> folders)
+ res/raw/ (required if you have any
+ res/raw-<qualifiers> folders)
+
+
+
Tip: In your code, examine each reference to
+ an Android resource. Make sure that a default resource is defined for each
+ one. Also make sure that the default string file is complete: A
+ localized string file can contain a subset of the strings, but the
+ default string file must contain them all.
+
+
+
How to Create Alternate Resources
+
+
A large part of localizing an application is providing alternate text for
+different languages. In some cases you will also provide alternate graphics,
+sounds, layouts, and other locale-specific resources.
+
+
An application can specify many res/<qualifiers>/
+directories, each with different qualifiers. To create an alternate resource for
+a different locale, you use a qualifier that specifies a language or a
+language-region combination. (The name of a resource directory must conform
+to the naming scheme described in
+Alternate Resources,
+or else it will not compile.)
+
+
Example:
+
+
Suppose that your application's default language is English. Suppose also
+that you want to localize all the text in your application to French, and most
+of the text in your application (everything except the application's title) to
+Japanese. In this case, you could create three alternate strings.xml
+files, each stored in a locale-specific resource directory:
+
+
+
res/values/strings.xml
+ Contains English text for all the strings that the application uses,
+including text for a string named title.
+
res/values-fr/strings.xml
+ Contain French text for all the strings, including title.
+
res/values-ja/strings.xml
+ Contain Japanese text for all the strings except
+title.
+
+
+
+
If your Java code refers to R.string.title, here is what will
+happen at runtime:
+
+
+
If the device is set to any language other than French, Android will load
+title from the res/values/strings.xml file.
+
If the device is set to French, Android will load title from
+the res/values-fr/strings.xml file.
+
+
+
Notice that if the device is set to Japanese, Android will look for
+title in the res/values-ja/strings.xml file. But
+because no such string is included in that file, Android will fall back to the
+default, and will load title in English from the
+res/values/strings.xml file.
+
+
Which Resources Take Precedence?
+
+
If multiple resource files match a device's configuration, Android follows a
+set of rules in deciding which file to use. Among the qualifiers that can be
+specified in a resource directory name, locale almost always takes
+precedence.
+
Example:
+
+
Assume that an application includes a default set of graphics and two other
+sets of graphics, each optimized for a different device setup:
+
+
+
res/drawable/
+ Contains
+ default graphics.
+
res/drawable-small-land-stylus/
+ Contains graphics optimized for use with a device that expects input from a
+ stylus and has a QVGA low-density screen in landscape orientation.
+
res/drawable-ja/
+ Contains graphics optimized for use with Japanese.
+
+
+
If the application runs on a device that is configured to use Japanese,
+Android will load graphics from res/drawable-ja/, even if the
+device happens to be one that expects input from a stylus and has a QVGA
+low-density screen in landscape orientation.
+
+
Exception: The only qualifiers that take
+precedence over locale in the selection process are MCC and MNC (mobile country
+code and mobile network code).
+
+
Example:
+
+
Assume that you have the following situation:
+
+
+
The application code calls for R.string.text_a
+
Two relevant resource files are available:
+
+
res/values-mcc404/strings.xml, which includes
+text_a in the application's default language, in this case
+English.
+
res/values-hi/strings.xml, which includes
+text_a in Hindi.
+
+
+
The application is running on a device that has the following
+configuration:
+
+
The SIM card is connected to a mobile network in India (MCC 404).
+
The language is set to Hindi (hi).
+
+
+
+
+
Android will load text_a from
+res/values-mcc404/strings.xml (in English), even if the device is
+configured for Hindi. That is because in the resource-selection process, Android
+will prefer an MCC match over a language match.
In your application's Java code, you refer to resources using the syntax
+R.resource_type.resource_name or
+android.R.resource_type.resource_name.
+For more about this, see Using
+Resources in Code.
+
+
Localization Strategies
+
+
Design your application to work in any locale
+
+
You cannot assume anything about the device on which a user will
+run your application. The device might have hardware that you were not
+anticipating, or it might be set to a locale that you did not plan for or that
+you cannot test. Design your application so that it will function normally or fail gracefully no
+matter what device it runs on.
+
+
Important: Make sure that your application
+includes a full set of default resources.
Make sure to include
+res/drawable/ and a res/values/ folders (without any
+additional modifiers in the folder names) that contain all the images and text
+that your application will need.
+
+
If an application is missing even one default resource, it will not run on a
+ device that is set to an unsupported locale. For example, the
+ res/values/strings.xml default file might lack one string that
+ the application needs: When the application runs in an unsupported locale and
+ attempts to load res/values/strings.xml, the user will see an
+ error message and a Force Close button. An IDE such as Eclipse will not
+ highlight this kind of error, and you will not see the problem when you
+ test the application on a device or emulator that is set to a supported locale.
If you need to rearrange your layout to fit a certain language (for example
+German with its long words), you can create an alternate layout for that
+language (for example res/layout-de/main.xml). However, doing this
+can make your application harder to maintain. It is better to create a single
+layout that is more flexible.
+
+
Another typical situation is a language that requires something different in
+its layout. For example, you might have a contact form that should include two
+name fields when the application runs in Japanese, but three name fields when
+the application runs in some other language. You could handle this in either of
+two ways:
+
+
+
Create one layout with a field that you can programmatically enable or
+disable, based on the language, or
+
Have the main layout include another layout that includes the changeable
+field. The second layout can have different configurations for different
+languages.
+
+
+
Avoid creating more resource files and text strings than you need
+
+
You probably do not need to create a locale-specific
+alternative for every resource in your application. For example, the layout
+defined in the res/layout/main.xml file might work in any locale,
+in which case there would be no need to create any alternate layout files.
+
+
+
Also, you might not need to create alternate text for every
+string. For example, assume the following:
+
+
+
Your application's default language is American
+English. Every string that the application uses is defined, using American
+English spellings, in res/values/strings.xml.
+
+
For a few important phrases, you want to provide
+British English spelling. You want these alternate strings to be used when your
+application runs on a device in the United Kingdom.
+
+
+
To do this, you could create a small file called
+res/values-en-rGB/strings.xml that includes only the strings that
+should be different when the application runs in the U.K. For all the rest of
+the strings, the application will fall back to the defaults and use what is
+defined in res/values/strings.xml.
+
+
Use the Android Context object for manual locale lookup
+
+
You can look up the locale using the {@link android.content.Context} object
+that Android makes available:
Keep in mind that the device you are testing may be significantly different from
+ the devices available to consumers in other geographies. The locales available
+ on your device may differ from those available on other devices. Also, the
+ resolution and density of the device screen may differ, which could affect
+ the display of strings and drawables in your UI.
+
+
To change the locale on a device, use the Settings application (Home >
+Menu > Settings > Locale & text > Select locale).
A "custom" locale is a language/region combination that the
+Android system image does not explicitly support. (For a list of supported
+locales, see the Android
+Version Notes.) You can test how your application will run in a custom
+locale by creating a custom locale in the emulator. There are two ways to do
+this:
+
+
+
Use the Custom Locale application, which is accessible from the
+Application tab. (After you create a custom locale, switch to it by
+pressing and holding the locale name.)
+
Change to a custom locale from the adb shell, as described below.
+
+
+
When you set the emulator to a locale that is not available in the Android
+system image, the system itself will display in its default language. Your
+application, however, should localize properly.
+
+
Changing the emulator locale from the adb shell
+
+
To change the locale in the emulator by using the adb shell.
+
+
+
Pick the locale you want to test and determine its language and region codes, for
+example fr for French and CA for Canada.
+
+
Launch an emulator.
+
From a command-line shell on the host computer, run the following
+command:
+ adb shell
+ or if you have a device attached, specify that you want the emulator by adding
+the -e option:
+ adb -e shell
+
At the adb shell prompt (#), run this command:
+ setprop persist.sys.language [language code];setprop
+persist.sys.country [country code];stop;sleep 5;start
+ Replace bracketed sections with the appropriate codes from Step
+1.
This will cause the emulator to restart. (It will look like a full reboot,
+but it is not.) Once the Home screen appears again, re-launch your application (for
+example, click the Run icon in Eclipse), and the application will launch with
+the new locale.
+
+
Testing for Default Resources
+
Here's how to test whether an application includes every string resource that it needs:
+
Set the emulator or device to a language that your application does not
+ support. For example, if the application has French strings in
+ res/values-fr/ but does not have any Spanish strings in
+ res/values-es/, then set the emulator's locale to Spanish.
+ (You can use the Custom Locale application to set the emulator to an
+ unsupported locale.)
+
Run the application.
+
If the application shows an error message and a Force Close button, it might
+ be looking for a string that is not available. Make sure that your
+ res/values/strings.xml file includes a definition for
+ every string that the application uses.
+
+
+
+
If the test is successful, repeat it for other types of
+ configurations. For example, if the application has a layout file called
+ res/layout-land/main.xml but does not contain a file called
+ res/layout-port/main.xml, then set the emulator or device to
+ portrait orientation and see if the application will run.
+
+
Publishing Localized Applications
+
+
The Android Market is
+ the main application distribution system for Android devices. To publish a
+ localized application, you need to sign your application, version it, and go
+through all the other steps described in Preparing to Publish.
+
+
If you split your application in several .apk files, each targeted to a
+different locale, follow these guidelines:
+
+
+
Sign each .apk file with the same certificate. For more about this, see Signing
+Strategies.
+
Give each .apk file a different application name. Currently it is
+impossible to put two applications into the Android Market that have exactly the
+same name.
+
Include a complete set of default resources in each .apk file.
+
+
+
Localization Checklists
+
+
These checklists summarize the process of localizing an Android application.
+Not everything on these lists will apply to every application.
+
+
Planning and Design Checklist
+
+
+
+
+
Choose a localization strategy. Which countries and which languages will
+your application support? What is your application's default country and
+language? How will your application behave when it does not have specific
+resources available for a given locale?
+
+
+
+
Identify everything in your application that will need to be
+localized:
+
+
Consider specific details of your application — text, images,
+sounds, music, numbers, money, dates and times. You might not need to localize
+everything. For example, you don't need to localize text that the user never
+sees, or images that are culturally neutral, or icons that convey the same
+meaning in every locale.
+
Consider broad themes. For example, if you hope to sell your
+application in two very culturally different markets, you might want to design
+your UI and present your application in an entirely different way for each
+locale.
+
+
+
+
+
Design your Java code to externalize resources wherever possible:
+
+
Use R.string and strings.xml files instead
+of hard-coded strings or string constants.
+
Use R.drawable and R.layout instead of
+hard-coded drawables or layouts.
+
+
+
+
Content Checklist
+
+
+
+
Create a full set of default resources in res/values/ and
+other res/ folders, as described in Creating Default Resources.
+
+
+
+
Obtain reliable translations of the static text, including menu text,
+button names, error messages, and help text. Place the translated strings in
+res/values-<qualifiers>/strings.xml files.
+
+
+
+
Make sure that your application correctly formats dynamic text (for
+example numbers and dates) for each supported locale. Make sure that your
+application handles word breaks, punctuation, and alphabetical sorting correctly
+for each supported language.
+
+
+
+
If necessary, create locale-specific versions of your graphics and
+layout, and place them in res/drawable-<qualifiers>/ and
+res/layout-<qualifiers>/ folders.
+
+
+
+
Create any other localized content that your application requires; for
+example, create recordings of sound files for each language, as needed.
+
+
+
Testing and Publishing Checklist
+
+
+
+
Test your application for each supported locale. If possible, have a
+person who is native to each locale test your application and give you
+feedback.
+
+
+
+
Test the default resources by loading a locale that is not available on
+ the device or emulator. For instructions, see
+ Testing for Default Resources.
+
+
+
+
Test the localized strings in both landscape and portrait display modes.
+
+
+
+
Sign your application and create your final build or builds.
+
+
+
+
Upload your .apk file or files to Market, selecting the appropriate
+languages as
+ you upload. (For more details, see Publishing Your
+Applications.)
+
+
\ No newline at end of file
diff --git a/docs/html/guide/topics/resources/res-selection-flowchart.png b/docs/html/guide/topics/resources/res-selection-flowchart.png
deleted file mode 100755
index d738b3f0c866..000000000000
Binary files a/docs/html/guide/topics/resources/res-selection-flowchart.png and /dev/null differ
diff --git a/docs/html/guide/topics/resources/resources-i18n.jd b/docs/html/guide/topics/resources/resources-i18n.jd
index 85b89d1c409c..091bc62bc15a 100755
--- a/docs/html/guide/topics/resources/resources-i18n.jd
+++ b/docs/html/guide/topics/resources/resources-i18n.jd
@@ -441,7 +441,7 @@ resources for a fully specified configuration would look like this:
More typically, you will only specify a few specific configuration options. You may drop any of the values from the
@@ -574,6 +574,14 @@ MyApp/
Primary text input method
nokeys, qwerty, 12key
+
+
Whether the navigation keys are available to the user
+
navexposed, navhidden
+
+ If the hardware's navigation keys are currently available to
+ the user, the navexposed resources will be used; if they are not
+ available (such as behind a closed lid), navhidden will be used.
+
Primary non-touchscreen
navigation method
@@ -685,7 +693,7 @@ MyApp/res/drawable-en-port/
Tip: The precedence of the qualifiers is more important than the number of qualifiers that exactly match the device. For example, in step 4 above, the last choice on the list includes three qualifiers that exactly match the device (orientation, touchscreen type, and input method), while drawable-en has only one parameter that matches (language). However, language has a higher precedence, so drawable-port-notouch-12key is out.
This flowchart summarizes how Android selects resource directories to load.
-
+
Terminology
The resource system brings a number of different pieces together to
form the final complete resource functionality. To help understand the
diff --git a/docs/html/guide/topics/ui/declaring-layout.jd b/docs/html/guide/topics/ui/declaring-layout.jd
index 7ef22a6be241..80ad7b868088 100644
--- a/docs/html/guide/topics/ui/declaring-layout.jd
+++ b/docs/html/guide/topics/ui/declaring-layout.jd
@@ -25,6 +25,7 @@ parent.link=index.html
+
@@ -41,14 +42,17 @@ application can create View and ViewGroup objects (and manipulate their properti
The Android framework gives you the flexibility to use either or both of these methods for declaring and managing your application's UI. For example, you could declare your application's default layouts in XML, including the screen elements that will appear in them and their properties. You could then add code in your application that would modify the state of the screen objects, including those declared in XML, at run time.
-
The Android Development Tools
- (ADT) plugin for Eclipse offers a layout preview of your XML —
- with the XML file opened, select the Layout tab.
-
You should also try the
+
+
The ADT
+ Plugin for Eclipse offers a layout preview of your XML —
+ with the XML file opened, select the Layout tab.
+
You should also try the
Hierarchy Viewer tool,
for debugging layouts — it reveals layout property values,
draws wireframes with padding/margin indicators, and full rendered views while
- you debug on the emulator or device.
+ you debug on the emulator or device.
+
The layoutopt tool lets
+ you quickly analyze your layouts and hierarchies for inefficiencies or other problems.
The advantage to declaring your UI in XML is that it enables you to better separate the presentation of your application from the code that controls its behavior. Your UI descriptions are external to your application code, which means that you can modify or adapt it without having to modify your source code and recompile. For example, you can create XML layouts for different screen orientations, different device screen sizes, and different languages. Additionally, declaring the layout in XML makes it easier to visualize the structure of your UI, so it's easier to debug problems. As such, this document focuses on teaching you how to declare your layout in XML. If you're
diff --git a/docs/html/guide/topics/ui/dialogs.jd b/docs/html/guide/topics/ui/dialogs.jd
index c0c0b1bc58da..4e4ca14bb821 100644
--- a/docs/html/guide/topics/ui/dialogs.jd
+++ b/docs/html/guide/topics/ui/dialogs.jd
@@ -624,7 +624,7 @@ AlertDialog.Builder builder;
AlertDialog alertDialog;
Context mContext = getApplicationContext();
-LayoutInflater inflater = (LayoutInflater) mContext.getSystemService(LAYOUT_INFLATER);
+LayoutInflater inflater = (LayoutInflater) mContext.getSystemService(LAYOUT_INFLATER_SERVICE);
View layout = inflater.inflate(R.layout.custom_dialog,
(ViewGroup) findViewById(R.id.layout_root));
diff --git a/docs/html/guide/topics/ui/ui-events.jd b/docs/html/guide/topics/ui/ui-events.jd
index f4d114a30e7d..5628d46e2bcc 100644
--- a/docs/html/guide/topics/ui/ui-events.jd
+++ b/docs/html/guide/topics/ui/ui-events.jd
@@ -28,8 +28,8 @@ the specific View object that the user interacts with. The View class provides t
methods that look useful for UI events. These methods are called by the Android framework when the
respective action occurs on that object. For instance, when a View (such as a Button) is touched,
the onTouchEvent() method is called on that object. However, in order to intercept this, you must extend
-the class and override the method. Obviously, extending every View object
-you want to use (just to handle an event) would be obsurd. This is why the View class also contains
+the class and override the method. However, extending every View object
+in order to handle such an event would not be practical. This is why the View class also contains
a collection of nested interfaces with callbacks that you can much more easily define. These interfaces,
called event listeners, are your ticket to capturing the user interaction with your UI.
You may also find it more conventient to implement OnClickListener as a part of your Activity.
+
You may also find it more convenient to implement OnClickListener as a part of your Activity.
This will avoid the extra class load and object allocation. For example:
public class ExampleActivity extends Activity implements OnClickListener {
@@ -168,7 +168,7 @@ you'll learn see some of the common callbacks used for event handling, including
{@link android.view.View#onTouchEvent} - Called when a touch screen motion event occurs.
{@link android.view.View#onFocusChanged} - Called when the view gains or loses focus.
-
There are some other methods that you should be awere of, which are not part of the View class,
+
There are some other methods that you should be aware of, which are not part of the View class,
but can directly impact the way you're able to handle events. So, when managing more complex events inside
a layout, consider these other methods:
diff --git a/docs/html/guide/tutorials/hello-world.jd b/docs/html/guide/tutorials/hello-world.jd
index 79b723d162d6..58d1a1613892 100644
--- a/docs/html/guide/tutorials/hello-world.jd
+++ b/docs/html/guide/tutorials/hello-world.jd
@@ -29,7 +29,7 @@ You can then return to this tutorial and ignore anything about Eclipse.
Before you start, you should already have the very latest SDK installed, and if you're using
Eclipse, you should have installed the ADT plugin as well. If you have not installed these, see
-Installing the Android SDK and return
+Installing the Android SDK and return
here when you've completed the installation.
In this tutorial, we will create a Hello, L10N application that uses the
+Android framework to selectively load resources. Then we will localize the
+application by adding resources to the res/ directory.
+
+
This tutorial uses the practices described in the Localization
+document.
+
+
+
Create an Unlocalized Application
+
+
The first version of the Hello, L10N application will use only the default
+resource directories (res/drawable, res/layout, and
+res/values). These resources are not localized — they are the
+graphics, layout, and strings that we expect the application to use most often.
+When a user runs the application in the default locale, or in a locale that the
+application does not specifically support, the application will load resources
+from these default directories.
+
+
The application consists of a simple user interface that displays two
+{@link android.widget.TextView} objects and a {@link android.widget.Button} image with a
+ background image of a national flag. When clicked, the button displays an
+{@link android.app.AlertDialog} object that shows additional text.
+
+
Create the Project and Layout
+
+
For this application, the default language will be British English and the
+default location the United Kingdom.
+
+
+
Start a new project and Activity called "HelloL10N." If you are
+using Eclipse, fill out these values in the New Android Project wizard:
+
+
Project name: HelloL10N
+
Application name: Hello, L10N
+
Package name: com.example.hellol10n (or your own private
+namespace)
+
Create Activity: HelloL10N
+
Min SDK Version: 3
+
+
The basic project contains a res/ directory with
+subdirectories for the three most common types of resources: graphics
+(res/drawable/), layouts (res/layout/) and strings
+(res/values/). Most of the localization work you do later in this
+tutorial will involve adding more subdirectories to the res/
+directory.
+
+
+
Open the res/layout/main.xml file and replace it with the
+following code:
+
The LinearLayout has two {@link android.widget.TextView} objects that will
+display localized text and one {@link android.widget.Button} that shows a flag.
+
+
+
+
+
Create Default Resources
+
+
The layout refers to resources that need to be defined.
+
+
+
Create default text strings. To do this, open the res/values/strings.xml file and replace it with the following code:
+
<?xml version="1.0" encoding="utf-8"?>
+<resources>
+ <string name="app_name">Hello, L10N</string>
+ <string name="text_a">Shall I compare thee to a summer"'"s day?</string>
+ <string name="text_b">Thou art more lovely and more temperate.</string>
+ <string name="dialog_title">No Localisation</string>
+ <string name="dialog_text">This dialog box"'"s strings are not localised. For every locale, the text here will come from values/strings.xml.</string>
+</resources>
+
+
This code provides British English text for each string that the application
+will use. When we localize this application, we will provide alternate text in
+German, French, and Japanese for some of the strings.
+
+
Add a default flag graphic to the res/drawable folder by
+saving flag.png as
+res/drawable/flag.png. When the application is not localized, it
+will show a British flag.
+
+
+
Open HelloL10N.java (in the src/ directory) and add the
+following code inside the onCreate() method (after
+setContentView).
+
+
// assign flag.png to the button, loading correct flag image for current locale
+Button b;
+(b = (Button)findViewById(R.id.flag_button)).setBackgroundDrawable(this.getResources().getDrawable(R.drawable.flag));
+
+// build dialog box to display when user clicks the flag
+AlertDialog.Builder builder = new AlertDialog.Builder(this);
+builder.setMessage(R.string.dialog_text)
+ .setCancelable(false)
+ .setTitle(R.string.dialog_title)
+ .setPositiveButton("Done", new DialogInterface.OnClickListener() {
+ public void onClick(DialogInterface dialog, int id) {
+ dialog.dismiss();
+ }
+ });
+final AlertDialog alert = builder.create();
+
+// set click listener on the flag to show the dialog box
+b.setOnClickListener(new View.OnClickListener() {
+ public void onClick(View v) {
+ alert.show();
+ }
+ });
+
+
Tip: In Eclipse, use
+Ctrl-Shift-O (Cmd-Shift-O, on Mac) to find and
+add missing import packages to your project, then save the HelloL10N.java
+file.
+
+
The code that you added does the following:
+
+
+
It assigns the correct flag icon to the button.
+ For now, no resources are defined other than the default, so this code
+will always assign the contents of res/drawable/flag.png (the
+British flag) as the flag icon, no matter what the locale. Once we add more
+flags for different locales, this code will sometimes assign a different flag.
+
+
It creates an {@link android.app.AlertDialog} object and sets a click listener so that when the
+user clicks the button, the AlertDialog will display.
+ We will not localize the dialog text;
+the AlertDialog will always display the dialog_text that is located
+within res/values/strings.xml.
+
+
+
+
+
+
The project structure now looks like this:
+
+
+
+
Tip: If you will want to run the application on
+a device and not just on an emulator, open AndroidManifest.xml and
+add android:debuggable="true" inside the
+<application> element. For information about setting up the
+device itself so it can run applications from your system, see Developing on a Device.
+
+
+
Run the Unlocalized Application
+
+
Save the project and run the application to see how it works. No matter what
+locale your device or emulator is set to, the application runs the same way. It
+should look something like this:
+
+
+
+
The unlocalized application, running in any locale:
+
After clicking the flag, in any locale:
+
+
+
+
+
+
+
Plan the Localization
+
The first step in localizing an application is to plan how the application
+will render differently in different locales. In this application, the default
+locale will be the United Kingdom. We will add some locale-specific information
+for Germany, France, Canada, Japan, and the United States. Table 1 shows the
+plan for how the application will appear in different locales.
+
+
Table 1
+
+
+
+
Region /
+ Language
+
United Kingdom
+
Germany
+
France
+
Canada
+
Japan
+
United States
+
Other Location
+
+
+
+ English
+
British English text; British flag (default)
+
-
+
-
+
British English text; Canadian flag
+
-
+
British English text; U.S. flag
+
British English text; British flag (default)
+
+
+
German
+
-
+
German text for app_name, text_a and
+text_b; German flag
+
-
+
-
+
-
+
-
+
German text for app_name, text_a and
+text_b; British flag
+
+
+
French
+
-
+
-
+
French text for app_name, text_a and
+text_b; French flag
+
French text for app_name, text_a and
+text_b; Canadian flag
+
-
+
-
+
French text for app_name, text_a and
+text_b; British flag
+
+
+
Japanese
+
-
+
-
+
-
+
-
+
Japanese text for text_a and text_b; Japanese
+flag
+
-
+
Japanese text for text_a and text_b; British
+flag
+
+
+
Other Language
+
-
+
-
+
-
+
-
+
-
+
-
+
British English text; British flag (default)
+
+
+
+
Note that other behaviors are possible; for example, the
+application could support Canadian English or U.S. English text. But given the
+small amount of text involved, adding more versions of English would not make
+this application more useful.
+
+
As shown in the table above, the plan calls for five flag icons in addition
+to the British flag that is already in the res/drawable/ folder. It
+also calls for three sets of text strings other than the text that is in
+res/values/strings.xml.
+
+
Table 2 shows where the needed text strings and flag icons will go, and
+specifies which ones will be loaded for which locales. (For more about the
+locale codes, see
+Alternate Resources.)
+
Table 2
+
+
+
+
Locale Code
+
Language / Country
+
Location of strings.xml
+
Location of flag.png
+
+
+
Default
+
English / United Kingdom
+
res/values/
+
res/drawable/
+
+
+
de-rDE
+
German / Germany
+
res/values-de/
+
res/drawable-de-rDE/
+
+
+
fr-rFR
+
French / France
+
res/values-fr/
+
res/drawable-fr-rFR/
+
+
+
fr-rCA
+
French / Canada
+
res/values-fr/
+
res/drawable-fr-rCA/
+
+
+
en-rCA
+
English / Canada
+
(res/values/)
+
res/drawable-en-rCA/
+
+
+
ja-rJP
+
Japanese / Japan
+
res/values-ja/
+
res/drawable-ja-rJP/
+
+
+
en-rUS
+
English / United States
+
(res/values/)
+
res/drawable-en-rUS/
+
+
+
+
Tip: A folder qualifer cannot specify a region
+without a language. Having a folder named res/drawable-rCA/,
+for example, will prevent the application from compiling.
+
+
At run time, the application will select a set of resources to load based on the locale
+that is set in the user's device. In cases where no locale-specific resources
+are available, the application will fall back on the defaults.
+
+
For example, assume that the device's language is set to German and its
+location to Switzerland. Because this application does not have a
+res/drawable-de-rCH/ directory with a flag.png file in it, the system
+will fall back on the default, which is the UK flag located in
+res/drawable/flag.png. The language used will be German. Showing a
+British flag to German speakers in Switzerland is not ideal, but for now we will
+just leave the behavior as it is. There are several ways you could improve this
+application's behavior if you wanted to:
+
+
+
Use a generic default icon. In this application, it might be something
+that represents Shakespeare.
+
Create a res/drawable-de/ folder that includes an icon that
+the application will use whenever the language is set to German but the location
+is not Germany.
+
+
+
+
Localize the Application
+
+
Localize the Strings
+
+
The application requires three more strings.xml files, one
+each for German, French, and Japanese. To create these resource files within
+Eclipse:
+
+
+
Select File > New > Android
+XML File to open the New Android XML File wizard. You can also open
+the wizard by clicking its icon in the toolbar:
+
+
Select L10N for the Project field, and type strings.xml into
+the File field. In the left-hand list, select Language, then click the right arrow.
+
+
Type de in the Language box and click Finish.
+
+
A new file, res/values-de/strings.xml, now appears among the project
+files.
+
Repeat the steps twice more, for the language codes fr and
+ ja.
+Now the project includes these new skeleton files:
+ res/values-de/strings.xml
+ res/values-fr/strings.xml
+ res/values-ja/strings.xml
+
+
Add localized text to the new files. To do
+this, open the res/values-<qualifier>/strings.xml files and
+replace the code as follows:
+
+
+
+
+
File
+
Replace the contents with the following code:
+
+
+
res/values-de/strings.xml
+
<?xml version="1.0" encoding="utf-8"?>
+<resources>
+ <string name="app_name">Hallo, Lokalisierung</string>
+ <string name="text_a">Soll ich dich einem Sommertag vergleichen,</string>
+ <string name="text_b">Der du viel lieblicher und sanfter bist?</string>
+</resources>
+
+
+
res/values-fr/strings.xml
+
<?xml version="1.0" encoding="utf-8"?>
+<resources>
+ <string name="app_name">Bonjour, Localisation</string>
+ <string name="text_a">Irai-je te comparer au jour d'été?</string>
+ <string name="text_b">Tu es plus tendre et bien plus tempéré.</string>
+</resources>
Tip: In the
+values-<qualifier>/strings.xml files, you only need to
+include text for strings that are different from the default strings. For
+example, when the application runs on a device that is configured for Japanese,
+the plan is for text_a and text_b to be in Japanese
+while all the other text is in English, so
+res/values-ja/strings.xml only needs to include text_a
+and text_b.
+
+
Localize the Images
+
+
As shown in Table 2, the application needs six more
+drawable folders, each containing a flag.png icon. Add the needed
+icons and folders to your project:
+
+
+
Save this German flag icon
+as res/drawable-de-rDE/flag.png in the application's project
+workspace.
+
For example:
+
+
Click the link to open the flag image.
+
Save the image in
+your-workspace/HelloL10N/res/drawable-de-rDE/ .
+
+
+
Save this French flag icon
+as res/drawable-fr-rFR/flag.png in the application's project
+workspace.
+
Save this Canadian flag icon
+as res/drawable-fr-rCA/flag.png in the project workspace.
+
Save the Canadian flag icon
+again, this time as res/drawable-en-rCA/flag.png in the project
+workspace. (Why not have just one folder that contains the Canadian
+flag? Because a folder qualifer cannot specify a region without a language.
+You cannot have a folder named drawable-rCA/; instead you must
+create two separate folders, one for each of the Canadian languages represented
+in the application.)
+
Save this Japanese flag icon
+as res/drawable-ja-rJP/flag.png in the project workspace.
If you are using Eclipse, refresh the project (F5). The new
+res/drawable-<qualifier>/ folders should appear in the
+project view.
+
+
+
Run and Test the Localized Application
+
+
Once you've added the localized string and image resources, you are ready to
+ run the application and test its handling of them. To change the locale
+ on a device or in the emulator, use the Settings
+application (Home > Menu > Settings > Locale & text > Select
+locale). Depending on how a device was configured, it might not offer any
+alternate locales via the Settings application, or might offer only a few. The
+emulator, on the other hand, will offer a selection of all the locales that are
+available in the Android system image.
+
+
To set the emulator to a locale that is not available in the system image,
+use the Custom Locale application, which is available in the Application
+tab:
+
+
+
+
To switch to a new locale, long-press a locale name:
+
+
+
+
For a list of locales available on different versions of the Android platform,
+refer to the platform notes documents, listed under "Downloadable SDK Components"
+in the "SDK" tab. For example, Android 2.0 locales.
+
+
Run the application for each of the expected locales, plus one unexpected
+locale. Here are some of the results you should see:
+
+
+
+
Locale
+
Opening screen of application
+
+
+
German / Germany
+ Specifically supported by the Hello, L10N application.
+
+
+
+
French / Canada
+ Specifically supported by the Hello, L10N application.
+
+
+
+
German / Switzerland
+ Only the language is specifically supported by
+the Hello, L10N application.
+
`
+
+
+
Japanese
+ Specifically supported by the Hello, L10N application.
+
+
`
+
+
+
Romansh / Switzerland (custom locale rm_CH)
+ Not specifically supported by the Hello, L10N
+application, so the application uses the default resources.
+
+
+
diff --git a/docs/html/images/emulator-wvga800l.png b/docs/html/images/emulator-wvga800l.png
new file mode 100644
index 000000000000..a2140338a469
Binary files /dev/null and b/docs/html/images/emulator-wvga800l.png differ
diff --git a/docs/html/images/hello_l10n/copy_res_files.png b/docs/html/images/hello_l10n/copy_res_files.png
new file mode 100755
index 000000000000..9e704b255242
Binary files /dev/null and b/docs/html/images/hello_l10n/copy_res_files.png differ
diff --git a/docs/html/images/hello_l10n/custom_locale_app.png b/docs/html/images/hello_l10n/custom_locale_app.png
new file mode 100755
index 000000000000..f89648ea62b8
Binary files /dev/null and b/docs/html/images/hello_l10n/custom_locale_app.png differ
diff --git a/docs/html/images/hello_l10n/drawable-de-rDE/flag.png b/docs/html/images/hello_l10n/drawable-de-rDE/flag.png
new file mode 100755
index 000000000000..2cc58c79f962
Binary files /dev/null and b/docs/html/images/hello_l10n/drawable-de-rDE/flag.png differ
diff --git a/docs/html/images/hello_l10n/drawable-en-rCA/flag.png b/docs/html/images/hello_l10n/drawable-en-rCA/flag.png
new file mode 100755
index 000000000000..b441d2e2ae64
Binary files /dev/null and b/docs/html/images/hello_l10n/drawable-en-rCA/flag.png differ
diff --git a/docs/html/images/hello_l10n/drawable-en-rUS/flag.png b/docs/html/images/hello_l10n/drawable-en-rUS/flag.png
new file mode 100755
index 000000000000..47a11792c4da
Binary files /dev/null and b/docs/html/images/hello_l10n/drawable-en-rUS/flag.png differ
diff --git a/docs/html/images/hello_l10n/drawable-fr-rCA/flag.png b/docs/html/images/hello_l10n/drawable-fr-rCA/flag.png
new file mode 100755
index 000000000000..b441d2e2ae64
Binary files /dev/null and b/docs/html/images/hello_l10n/drawable-fr-rCA/flag.png differ
diff --git a/docs/html/images/hello_l10n/drawable-fr-rFR/flag.png b/docs/html/images/hello_l10n/drawable-fr-rFR/flag.png
new file mode 100755
index 000000000000..cdbe85fa90e5
Binary files /dev/null and b/docs/html/images/hello_l10n/drawable-fr-rFR/flag.png differ
diff --git a/docs/html/images/hello_l10n/drawable-ja-rJP/flag.png b/docs/html/images/hello_l10n/drawable-ja-rJP/flag.png
new file mode 100755
index 000000000000..7b93ee97613a
Binary files /dev/null and b/docs/html/images/hello_l10n/drawable-ja-rJP/flag.png differ
diff --git a/docs/html/images/hello_l10n/flag.png b/docs/html/images/hello_l10n/flag.png
new file mode 100755
index 000000000000..c2321326e70c
Binary files /dev/null and b/docs/html/images/hello_l10n/flag.png differ
diff --git a/docs/html/images/hello_l10n/frenchCA_screenshot.png b/docs/html/images/hello_l10n/frenchCA_screenshot.png
new file mode 100755
index 000000000000..f8e65176aef9
Binary files /dev/null and b/docs/html/images/hello_l10n/frenchCA_screenshot.png differ
diff --git a/docs/html/images/hello_l10n/germanCH_screenshot.png b/docs/html/images/hello_l10n/germanCH_screenshot.png
new file mode 100755
index 000000000000..240104aeeae7
Binary files /dev/null and b/docs/html/images/hello_l10n/germanCH_screenshot.png differ
diff --git a/docs/html/images/hello_l10n/german_screenshot.png b/docs/html/images/hello_l10n/german_screenshot.png
new file mode 100755
index 000000000000..3d1b1979947e
Binary files /dev/null and b/docs/html/images/hello_l10n/german_screenshot.png differ
diff --git a/docs/html/images/hello_l10n/japanese_screenshot.png b/docs/html/images/hello_l10n/japanese_screenshot.png
new file mode 100755
index 000000000000..e1ffbf911d35
Binary files /dev/null and b/docs/html/images/hello_l10n/japanese_screenshot.png differ
diff --git a/docs/html/images/hello_l10n/nonlocalized_project.png b/docs/html/images/hello_l10n/nonlocalized_project.png
new file mode 100755
index 000000000000..8df9a060ee7f
Binary files /dev/null and b/docs/html/images/hello_l10n/nonlocalized_project.png differ
diff --git a/docs/html/images/hello_l10n/nonlocalized_screenshot1.png b/docs/html/images/hello_l10n/nonlocalized_screenshot1.png
new file mode 100755
index 000000000000..02ace4b58a31
Binary files /dev/null and b/docs/html/images/hello_l10n/nonlocalized_screenshot1.png differ
diff --git a/docs/html/images/hello_l10n/nonlocalized_screenshot2.png b/docs/html/images/hello_l10n/nonlocalized_screenshot2.png
new file mode 100755
index 000000000000..e5a771b91be6
Binary files /dev/null and b/docs/html/images/hello_l10n/nonlocalized_screenshot2.png differ
diff --git a/docs/html/images/hello_l10n/plain_project.png b/docs/html/images/hello_l10n/plain_project.png
new file mode 100755
index 000000000000..f3c2b576e565
Binary files /dev/null and b/docs/html/images/hello_l10n/plain_project.png differ
diff --git a/docs/html/images/hello_l10n/romanshCH_screenshot.png b/docs/html/images/hello_l10n/romanshCH_screenshot.png
new file mode 100755
index 000000000000..a3fd1941298f
Binary files /dev/null and b/docs/html/images/hello_l10n/romanshCH_screenshot.png differ
diff --git a/docs/html/images/hello_l10n/using_custom_locale.png b/docs/html/images/hello_l10n/using_custom_locale.png
new file mode 100755
index 000000000000..61b4c055bff8
Binary files /dev/null and b/docs/html/images/hello_l10n/using_custom_locale.png differ
diff --git a/docs/html/images/hello_l10n/xml_file_wizard_shortcut.png b/docs/html/images/hello_l10n/xml_file_wizard_shortcut.png
new file mode 100755
index 000000000000..f72554da657f
Binary files /dev/null and b/docs/html/images/hello_l10n/xml_file_wizard_shortcut.png differ
diff --git a/docs/html/images/hello_l10n/xml_wizard1.png b/docs/html/images/hello_l10n/xml_wizard1.png
new file mode 100755
index 000000000000..35dc09fbb961
Binary files /dev/null and b/docs/html/images/hello_l10n/xml_wizard1.png differ
diff --git a/docs/html/images/hello_l10n/xml_wizard2.png b/docs/html/images/hello_l10n/xml_wizard2.png
new file mode 100755
index 000000000000..6bcd28b4e154
Binary files /dev/null and b/docs/html/images/hello_l10n/xml_wizard2.png differ
diff --git a/docs/html/images/resources/arrow.png b/docs/html/images/resources/arrow.png
new file mode 100755
index 000000000000..78ad5421b97a
Binary files /dev/null and b/docs/html/images/resources/arrow.png differ
diff --git a/docs/html/images/resources/res-selection-flowchart.png b/docs/html/images/resources/res-selection-flowchart.png
new file mode 100755
index 000000000000..d738b3f0c866
Binary files /dev/null and b/docs/html/images/resources/res-selection-flowchart.png differ
diff --git a/docs/html/images/resources/right-arrow.png b/docs/html/images/resources/right-arrow.png
new file mode 100755
index 000000000000..092f029a7ab1
Binary files /dev/null and b/docs/html/images/resources/right-arrow.png differ
diff --git a/docs/html/images/screens_support/afdvfckr9j_14fj6dhsc3_b.png b/docs/html/images/screens_support/afdvfckr9j_14fj6dhsc3_b.png
new file mode 100644
index 000000000000..ff4fbbf0303a
Binary files /dev/null and b/docs/html/images/screens_support/afdvfckr9j_14fj6dhsc3_b.png differ
diff --git a/docs/html/images/screens_support/afdvfckr9j_15dcsvrscg_b.png b/docs/html/images/screens_support/afdvfckr9j_15dcsvrscg_b.png
new file mode 100644
index 000000000000..7a987dd2e95a
Binary files /dev/null and b/docs/html/images/screens_support/afdvfckr9j_15dcsvrscg_b.png differ
diff --git a/docs/html/images/screens_support/afdvfckr9j_16g95wjqg3_b.png b/docs/html/images/screens_support/afdvfckr9j_16g95wjqg3_b.png
new file mode 100644
index 000000000000..20835b61cd74
Binary files /dev/null and b/docs/html/images/screens_support/afdvfckr9j_16g95wjqg3_b.png differ
diff --git a/docs/html/images/screens_support/afdvfckr9j_17p2w4txgc_b.png b/docs/html/images/screens_support/afdvfckr9j_17p2w4txgc_b.png
new file mode 100644
index 000000000000..8895d4958230
Binary files /dev/null and b/docs/html/images/screens_support/afdvfckr9j_17p2w4txgc_b.png differ
diff --git a/docs/html/images/screens_support/afdvfckr9j_18c6mhm3cm_b.png b/docs/html/images/screens_support/afdvfckr9j_18c6mhm3cm_b.png
new file mode 100644
index 000000000000..ef6ec66932b3
Binary files /dev/null and b/docs/html/images/screens_support/afdvfckr9j_18c6mhm3cm_b.png differ
diff --git a/docs/html/images/screens_support/afdvfckr9j_19c743p6cr_b.png b/docs/html/images/screens_support/afdvfckr9j_19c743p6cr_b.png
new file mode 100644
index 000000000000..34be21293e6c
Binary files /dev/null and b/docs/html/images/screens_support/afdvfckr9j_19c743p6cr_b.png differ
diff --git a/docs/html/images/screens_support/afdvfckr9j_20fvptbbdd_b.png b/docs/html/images/screens_support/afdvfckr9j_20fvptbbdd_b.png
new file mode 100644
index 000000000000..2415b52093e4
Binary files /dev/null and b/docs/html/images/screens_support/afdvfckr9j_20fvptbbdd_b.png differ
diff --git a/docs/html/images/screens_support/avd-density.png b/docs/html/images/screens_support/avd-density.png
new file mode 100644
index 000000000000..e3fc36ec5c69
Binary files /dev/null and b/docs/html/images/screens_support/avd-density.png differ
diff --git a/docs/html/images/screens_support/avds-config.png b/docs/html/images/screens_support/avds-config.png
new file mode 100644
index 000000000000..7db8c7388a01
Binary files /dev/null and b/docs/html/images/screens_support/avds-config.png differ
diff --git a/docs/html/images/screens_support/dip.png b/docs/html/images/screens_support/dip.png
new file mode 100644
index 000000000000..3cbad5754bf8
Binary files /dev/null and b/docs/html/images/screens_support/dip.png differ
diff --git a/docs/html/images/screens_support/scale-test.png b/docs/html/images/screens_support/scale-test.png
new file mode 100644
index 000000000000..f4fc6623a630
Binary files /dev/null and b/docs/html/images/screens_support/scale-test.png differ
diff --git a/docs/html/images/sdk_manager_packages.png b/docs/html/images/sdk_manager_packages.png
new file mode 100755
index 000000000000..463be8f38749
Binary files /dev/null and b/docs/html/images/sdk_manager_packages.png differ
diff --git a/docs/html/index.jd b/docs/html/index.jd
index 823ec96192e5..9d349ca27f58 100644
--- a/docs/html/index.jd
+++ b/docs/html/index.jd
@@ -15,12 +15,12 @@ home=true
The second Android Developer Challenge has begun! In this contest,
real-world users will help review and score applications and the overall winner will
- take away $250,000. The deadline for submitting an application to the contest is August 31, 2009.
+ take away $250,000. The deadline for submissions was August 31, 2009.
Android 2.0 includes exciting new features and APIs. "
+ + "For information about what's included in the new platform, read "
+ + "the Android 2.0 version notes.
"
+ + "
If you have the Android 1.6 SDK, you can update your environment "
+ + "by installing the Android 2.0 platform and updated tools as "
+ + "SDK components. Otherwise, "
+ + "download a new Android SDK.
The Google I/O developer conference took place May 27-28 in San Francisco. If you missed the conference, you can experience the Android sessions by viewing YouTube videos.
Run and debug your Android applications directly on this device. Modify and rebuild the Android operating system, and flash it onto the phone. The Android Dev Phone 1 is carrier independent, and available for purchase by any developer registered with Android Market.
If you're writing an Android application that uses Google Maps (with MapView), you must register your application to obtain a Maps API Key. Without the key, your maps application will not work on Android devices. Obtaining a key requires just a couple of steps.
Run and debug your Android applications directly on this device. Modify and rebuild the Android operating system, and flash it onto the phone. The Android Dev Phone 1 is carrier independent, and available for purchase by any developer registered with Android Market.
The Google I/O developer conference took place May 27-28 in San Francisco. If you missed the conference, you can experience the Android sessions by viewing YouTube videos.
If you've downloaded the Android SDK for the first time...
-
If you're upgrading from a previously installed version, then refer to the
-Upgrading guide.
+
Follow the online guide to
+Installing
+the Android SDK, which will help you setup your development environment
+(including the Android Development Tools plugin for Eclipse)
+so you can start developing Android apps.
-
Once you've completed the SDK installation, you can start learning about
-development on the Android framework by reading the Developer's Guide. The SDK package
-also includes a wide variety of code samples specific to each Android
-platform. You can find the samples at this location:
+
Once your environment is setup, look at the
+Next
+Steps for some suggestions on how to begin learning about Android.
-
<sdk>/platforms/android-<version>/samples/
+
If you've just installed new SDK components using the SDK and AVD Manager...
-
Please note that you are currently viewing a local, offline version of the
-Android developer documentation. The offline documentation offers the same
-content and features as the online documentation, but since the search
-capability is network-based, it will not work while you are offline.
-Autocompletion for API packages and classes, also offered from the search box,
-is available both online and offline and loads the reference documentation for
-the item you select.
+
There's no additional setup.
+
+
Newly installed Android platforms are automatically saved in the
+<sdk_dir>/platforms/ directory of your existing SDK;
+new add-ons are saved in the <sdk_dir>/add-ons/
+directory; and new documentation is saved in the existing
+<sdk_dir>/docs/ directory (old docs are replaced).
+
+
+
+
+
Note that you are currently viewing a local, offline version of the
+Android developer documentation. The offline documentation offers almost all the same
+content and features as the online documentation. Because some features
+such as search and videos are network-based, not everything will work if you
+are not connected to the Internet.
+
+
For the most current documentation and a fully-functional experience, please visit:
diff --git a/docs/html/sdk/1.0_r1/requirements.jd b/docs/html/sdk/1.0_r1/requirements.jd
index af0667548dcc..4163513174c2 100644
--- a/docs/html/sdk/1.0_r1/requirements.jd
+++ b/docs/html/sdk/1.0_r1/requirements.jd
@@ -14,7 +14,13 @@ developing Android applications using the Android SDK tools included in Android
Windows XP or Vista
Mac OS X 10.4.8 or later (x86 only)
-
Linux (tested on Linux Ubuntu Dapper Drake)
+
Linux (tested on Linux Ubuntu Dapper Drake)
+
+
64-bit distributions must be capable of running 32-bit applications.
+ For information about how to add support for 32-bit applications, see
+ the Installation Notes.
64-bit distributions must be capable of running 32-bit applications.
+ For information about how to add support for 32-bit applications, see
+ the Installation Notes.
64-bit distributions must be capable of running 32-bit applications.
+ For information about how to add support for 32-bit applications, see
+ the Installation Notes.
64-bit distributions must be capable of running 32-bit applications.
+ For information about how to add support for 32-bit applications, see
+ the Installation Notes.
+
+
Supported Development Environments
diff --git a/docs/html/sdk/1.5_r2/installing.jd b/docs/html/sdk/1.5_r2/installing.jd
index 1530dc56e1db..1e4e0f2479c8 100644
--- a/docs/html/sdk/1.5_r2/installing.jd
+++ b/docs/html/sdk/1.5_r2/installing.jd
@@ -323,7 +323,7 @@ begin developing applications. Here are a few ways you can get started:
If JDK is already installed on your development computer, please
take a moment to make sure that it meets the version requirements listed
- in the System Requirements.
+ in the System Requirements.
In particular, note that some Linux distributions may include JDK 1.4 or Gnu
Compiler for Java, both of which are not supported for Android development.
64-bit distributions must be capable of running 32-bit applications.
+ For information about how to add support for 32-bit applications, see
+ the Installation Notes.
+
+
Supported Development Environments
diff --git a/docs/html/sdk/1.5_r3/installing.jd b/docs/html/sdk/1.5_r3/installing.jd
index 8c3e8ee84186..ac475d1260c7 100644
--- a/docs/html/sdk/1.5_r3/installing.jd
+++ b/docs/html/sdk/1.5_r3/installing.jd
@@ -323,7 +323,7 @@ begin developing applications. Here are a few ways you can get started:
If JDK is already installed on your development computer, please
take a moment to make sure that it meets the version requirements listed
- in the System Requirements.
+ in the System Requirements.
In particular, note that some Linux distributions may include JDK 1.4 or Gnu
Compiler for Java, both of which are not supported for Android development.
64-bit distributions must be capable of running 32-bit applications.
+ For information about how to add support for 32-bit applications, see
+ the Installation Notes.
+
+
Supported Development Environments
diff --git a/docs/html/sdk/1.5_r3/upgrading.jd b/docs/html/sdk/1.5_r3/upgrading.jd
index c79b65682a07..f853d252dc01 100644
--- a/docs/html/sdk/1.5_r3/upgrading.jd
+++ b/docs/html/sdk/1.5_r3/upgrading.jd
@@ -187,7 +187,7 @@ uninstall procedure and continue to Install the 0.9 ADT pl
For more information on this SDK release, read the
+Release Notes.
+
+
SDK Contents
+
+
Development tools
+
+
The SDK includes a full set of tools for developing and debugging application
+code and designing an application UI. You can read about the tools in the Dev Guide and access them
+in the <sdk>/tools/ directory.
+
+
The tools package in this SDK includes updates from those provided in the
+previous SDK. The tools use the same project structure as in the previous SDK
+(Android 1.5). If you have application projects developed in the Android 1.5
+SDK, you can migrate them to the latest SDK without modification. For more
+information about how to migrate, see Upgrading the
+SDK.
+
+
Android Platforms
+
+
This SDK includes multiple Android platform versions that you can use to
+develop applications. For each version, both a fully compliant Android library
+and system image are provided. The table below lists the platform versions
+included in this SDK. For more information about a platform version —
+features, applications included, localizations, API changes, and so on —
+see its Version Notes.
Includes a standard Android 1.6 library and system image with a set of
+development applications. Does not include any external libraries (such as the
+Maps external library).
Includes a standard Android 1.5 library and system image with a set of
+development applications. Does not include any external libraries (such as the
+Maps external library).
+
+
+
+
Note that you can use the Android SDK and AVD Manager to download other
+platform versions into your development environment..
+
+
SDK Add-Ons
+
+
An SDK add-on provides a development environment for an Android external
+library or a customized (but fully compliant) Android system image. This SDK
+includes the SDK add-ons listed below. The Android system API Level required by
+the add-ons are noted.
+
+
+
+
Add-On
API Level
+
Notes
Description
+
+
+
Google APIs
+
4
+
+
Includes the com.google.android.maps external library, a compliant
+Android 1.6 system image, a {@link android.location.Geocoder Geocoder}
+backend service implementation, documentation, and sample code.
+
+
+
Google APIs
+
3
+
+
Includes the com.google.android.maps external library, a compliant
+Android 1.5 system image, a {@link android.location.Geocoder Geocoder}
+backend service implementation, documentation, and sample code.
+
+
+
+
Sample Code and Applications
+
+
You can look at a variety of tutorials and samples in the Dev Guide and access the sample
+code itself in the <sdk>/platforms/<platform>/samples/
+directory of the SDK package. Note the new location — the SDK now includes
+multiple platform versions that you can develop against and each has its own
+sample code directory.
+
+
For example, to view or build the samples available for the Android
+1.6 platform (AVD target "Android 1.6"), you will find the samples in the
+<sdk>/platforms/android-1.6/samples/ directory of the SDK
+package.
+
+
Documentation
+
+
The SDK package includes a full set of local documentation. To view it, open
+the <sdk>/documentation.html file in a web browser. If you
+are developing in an IDE such as Eclipse, you can also view the reference
+documentation directly in the IDE.
+
+
The most current documentation is always available on the Android Developers
+site:
This page describes how to install the Android SDK and set up your
+development environment.
+
+
If you encounter any problems during installation, see the
+Installation Notes at the bottom of
+this page.
+
+
Upgrading?
+
If you have already developed applications using an earlier version
+of the Android SDK, please read Upgrading the SDK, instead.
+
+
+
+
Prepare for Installation
+
+
Before you begin, take a moment to confirm that your development machine
+meets the System Requirements.
+
+
If you will be developing on Eclipse with the Android Development
+Tools (ADT) Plugin — the recommended path if you are new to
+Android — make sure that you have a suitable version of Eclipse
+installed on your computer (3.4 or newer is recommended). If you need
+to install Eclipse, you can download it from this location:
After downloading the Android SDK, unpack the Android SDK .zip archive
+to a suitable location on your machine. By default, the SDK files are unpacked
+into a directory named android_sdk_<platform>_<release>.
+
+
Make a note of the name and location of the unpacked SDK directory on your system — you
+will need to refer to the SDK directory later, when setting up the Android plugin or when
+using the SDK tools.
+
+
Optionally, you may want to add the location of the SDK's primary tools directory
+to your system PATH. The primary tools/ directory is located at the root of the
+SDK folder. Adding tools to your path lets you run Android Debug Bridge (adb) and
+the other command line tools without
+needing to supply the full path to the tools directory.
+
+
On Linux, edit your ~/.bash_profile or ~/.bashrc file. Look
+ for a line that sets the PATH environment variable and add the
+ full path to the tools/ directory to it. If you don't
+ see a line setting the path, you can add one:
+
+
export PATH=${PATH}:<your_sdk_dir>/tools
+
+
On a Mac, look in your home directory for .bash_profile and
+ proceed as for Linux. You can create the .bash_profile if
+ you haven't already set one up on your machine.
+
+
On Windows, right-click on My Computer, and select Properties.
+ Under the Advanced tab, hit the Environment Variables button, and in the
+ dialog that comes up, double-click on Path (under System Variables). Add the full path to the
+ tools/ directory to the path.
+
+
+
Note that, if you update your SDK in the future, you
+should remember to update your PATH settings to point to the new location, if different.
+
+
If you will be using the Eclipse IDE as your development environment,
+the next section describes how to install the Android Development Tools (ADT) plugin and set up Eclipse.
+If you choose not to use Eclipse, you can
+develop Android applications in an IDE of your choice and then compile, debug and deploy using
+the tools included in the SDK (skip to Next Steps).
+
+
+
Install the ADT Plugin for Eclipse
+
+
Android offers a custom plugin for the Eclipse IDE, called Android
+Development Tools (ADT), that is designed to give you a powerful,
+integrated environment in which to build Android applications. It
+extends the capabilites of Eclipse to let you quickly set up new Android
+projects, create an application UI, add components based on the Android
+Framework API, debug your applications using the Android SDK tools, and even export
+signed (or unsigned) APKs in order to distribute your application.
+
+
In general, using Eclipse with ADT is a highly recommended approach to
+Android development and is the fastest way to get started. (If you prefer to
+work in an IDE other than Eclipse, you do not need to install Eclipse or ADT,
+instead, you can directly use the SDK tools to build and debug your
+application—skip to Next Steps.)
+
+
Once you have the Eclipse IDE installed, as described in Preparing for Installation, follow the steps below to
+download the ADT plugin and install it in your respective Eclipse environment.
+
+
+
+
Eclipse 3.4 (Ganymede)
Eclipse 3.5 (Galileo)
+
+
+
+
+
Start Eclipse, then select Help > Software Updates....
+ In the dialog that appears, click the Available Software tab.
+
Click Add Site...
+
In the Add Site dialog that appears, enter this URL in the "Location" field:
+
https://dl-ssl.google.com/android/eclipse/
+
Note: If you have trouble aqcuiring the plugin, try using "http" in the Location URL,
+ instead of "https" (https is preferred for security reasons).
+
Click OK.
+
Back in the Available Software view, you should see the plugin listed by the URL,
+ with "Developer Tools" nested within it. Select the checkbox next to
+ Developer Tools and click Install...
+
On the subsequent Install window, "Android DDMS" and "Android Development Tools"
+ should both be checked. Click Next.
+
Read and accept the license agreement, then click Finish.
+
Restart Eclipse.
+
+
+
+
+
+
+
Start Eclipse, then select Help > Install
+ New Softare.
+
In the Available Software dialog, click Add....
+
In the Add Site dialog that appears, enter a name for the remote site
+ (e.g., "Android Plugin") in the "Name" field.
+
In the "Location" field, enter this URL:
+
https://dl-ssl.google.com/android/eclipse/
+
Note: If you have trouble aqcuiring the plugin, you can try
+ using "http" in the URL, instead of "https" (https is preferred for
+ security reasons).
+
Click OK.
+
+
Back in the Available Software view, you should now see "Developer
+ Tools" added to the list. Select the checkbox next to Developer Tools,
+ which will automatically select the nested tools Android DDMS and Android
+ Development Tools.
+ Click Next.
+
In the resulting Install Details dialog, the Android DDMS and Android
+ Development Tools features are listed. Click Next to
+ read and accept the license agreement and install any dependencies,
+ then click Finish.
+
Restart Eclipse.
+
+
+
+
+
+
+
Now modify your Eclipse preferences to point to the Android SDK directory:
+
+
Select Window > Preferences... to open the Preferences
+ panel (Mac: Eclipse > Preferences).
+
Select Android from the left panel.
+
For the SDK Location in the main panel, click Browse... and
+ locate your downloaded SDK directory.
+
Click Apply, then OK.
+
+
+
Done! If you haven't encountered any problems, then you're ready to
+begin developing Android applications. See the
+Next Steps section for suggestions on how to start.
+
+
+
Contents of the SDK
+
+
Once you've downloaded and unpacked the SDK, open the SDK directory
+and take a look at what's inside.
+
+
The table below describes the SDK directory contents.
+
+
+
+
Name
Description
+
+
+
add-ons/
+
Contains add-ons to the Android SDK development
+environment, which let you develop against external libraries that are available on some
+devices.
+
+
+
docs/
+
A full set of documentation in HTML format, including the Developer's Guide,
+API Reference, and other information.
+
+
+
platforms/
+
Contains a set of Android platform versions that you can develop
+applications against, each in a separate directory.
+
+
+
+
<platform>/
+
Platform version directory, for example "Android 1.6". All platform version
+directories contain a similar set of files and subdirectory structure.
+
+
+
+
+
+
data/
+
Storage area for default fonts and resource definitions.
+
+
+
+
+
images/
+
Storage area for default disk images, including the Android system image,
+the default userdata image, the default ramdisk image, and more. The images
+are used in emulator sessions.
+
+
+
+
+
samples/
+
Contains a wide variety of sample applications that you can load as projects
+into your development environment, compile, and run on the emulator.
+
+
+
+
+
skins/
+
A set of emulator skins available for the platform version. Each skin is
+designed for a specific screen resolution.
+
+
+
+
+
templates/
+
Storage area for file templates used by the SDK development tools.
+
+
+
+
+
tools/
+
Any development tools that are specific to the platform version.
+
+
+
+
+
android.jar
+
The Android library used when compiling applications against this platform
+version.
+
+
+
tools/
+
Contains the set of development and profiling tools available to you, such
+as the emulator, the android tool, adb, ddms, and more.
+
+
+
RELEASE_NOTES.html
+
A file that loads the local version of the SDK release notes, if
+available.
+
+
+
documentation.html
+
A file that loads the entry page for the local Android SDK
+documentation.
+
+
+
+
+
Next Steps
+
Once you have completed installation, you are ready to
+begin developing applications. Here are a few ways you can get started:
+
+
Learn about Android
+
+
Take a look at the Dev
+ Guide and the types of information it provides
Create a new project for one of the other sample applications
+ included in <sdk>/platforms/<platform>/samples,
+ then compile and run it in your development environment
+
+
+
Visit the Android developer groups
+
+
Take a look at the Community tab to see a list of
+ Android developers groups. In particular, you might want to look at the
+ Android
+ Developers group to get a sense for what the Android developer
+ community is like.
+
+
+
+
Installation Notes
+
+
Ubuntu Linux Notes
+
+
+
If you need help installing and configuring Java on your
+ development machine, you might find these resources helpful:
+
Here are the steps to install Java and Eclipse, prior to installing
+ the Android SDK and ADT Plugin.
+
+
If you are running a 64-bit distribution on your development
+ machine, you need to install the ia32-libs package using
+ apt-get::
+
apt-get install ia32-libs
+
+
Next, install Java:
apt-get install sun-java6-bin
+
The Ubuntu package manager does not currently offer an Eclipse 3.3
+ version for download, so we recommend that you download Eclipse from
+ eclipse.org (http://www.eclipse.org/
+ downloads/). A Java or RCP version of Eclipse is recommended.
+
Follow the steps given in previous sections to install the SDK
+ and the ADT plugin.
+
+
+
+
+
Other Linux Notes
+
+
+
If JDK is already installed on your development computer, please
+ take a moment to make sure that it meets the version requirements listed
+ in the System Requirements.
+ In particular, note that some Linux distributions may include JDK 1.4 or Gnu
+ Compiler for Java, both of which are not supported for Android development.
+
+
+
+
Troubleshooting ADT Installation
+
+
If you are having trouble downloading the ADT plugin after following the
+steps above, here are some suggestions:
+
+
+
If Eclipse can not find the remote update site containing the ADT plugin,
+try changing the remote site URL to use http, rather than https. That is, set
+the Location for the remote site to:
+
http://dl-ssl.google.com/android/eclipse/
+
If you are behind a firewall (such as a corporate firewall), make sure that
+you have properly configured your proxy settings in Eclipse. In Eclipse 3.3/3.4,
+you can configure proxy information from the main Eclipse menu in
+Window (on Mac, Eclipse) >
+Preferences > General > Network
+Connections.
+
+
+
If you are still unable to use Eclipse to download the ADT plugin as a
+remote update site, you can download the ADT zip file to your local machine and
+manually install it:
In Eclipse 3.5 only, enter a name for the local update site (e.g.,
+ "Android Plugin") in the "Name" field.
+
Click OK.
+
Follow the remaining procedures as listed for
+ default installation above,
+ starting from step 4.
+
+
+
To update your plugin once you've installed using the zip file, you will have
+to follow these steps again instead of the default update instructions.
+
+
Other install errors
+
+
Note that there are features of ADT that require some optional
+Eclipse components (for example, WST). If you encounter an error when
+installing ADT, your Eclipse installion might not include these components.
+For information about how to quickly add the necessary components to your
+Eclipse installation, see the troubleshooting topic
+ADT
+Installation Error: "requires plug-in org.eclipse.wst.sse.ui".
+
+
For Linux users
+
If you encounter this error when installing the ADT Plugin for Eclipse:
+
+An error occurred during provisioning.
+Cannot connect to keystore.
+JKS
+
+...then your development machine lacks a suitable Java VM. Installing Sun
+Java 6 will resolve this issue and you can then reinstall the ADT
+Plugin.
The sections below describe the system and software requirements for developing
+Android applications using the Android SDK tools included in Android
+ SDK, Release .
+
+
Supported Operating Systems
+
+
Windows XP (32-bit) or Vista (32- or 64-bit)
+
Mac OS X 10.4.8 or later (x86 only)
+
Linux (tested on Linux Ubuntu Hardy Heron)
+
+
64-bit distributions must be capable of running 32-bit applications.
+ For information about how to add support for 32-bit applications, see
+ the Installation Notes.
Apache Ant 1.6.5 or later for Linux and Mac, 1.7 or later for Windows
+
Not compatible with Gnu Compiler for Java (gcj)
+
+
+
+
+
Note: If JDK is already installed on your development computer, please take a moment to make sure that it meets the version requirements listed above. In
+particular, note that some Linux distributions may include JDK 1.4 or Gnu Compiler for Java, both of which are not supported for Android development.
+
+
Hardware requirements
+
+
For the base SDK package, at least 600MB of available disk space. For each platform downloaded into the SDK, an additional 100MB is needed.
+
+
diff --git a/docs/html/sdk/1.6_r1/upgrading.jd b/docs/html/sdk/1.6_r1/upgrading.jd
new file mode 100644
index 000000000000..ebe6a95c8ee9
--- /dev/null
+++ b/docs/html/sdk/1.6_r1/upgrading.jd
@@ -0,0 +1,386 @@
+page.title=Upgrading the SDK
+sdk.version=1.6
+sdk.preview=0
+@jd:body
+
+
+
+
+
+
Upgrading the SDK
+
+
If you are developing on the Android 1.5 SDK, migrating your
+applications is straightforward and typically requires no modifications.
+
For Eclipse users, a new version of ADT is available. To use the Android
+1.6 SDK, please upgrade to ADT 0.9.3 (or later).
+
For Windows users, the SDK includes a new USB driver that you can
+install, if you are developing on a device.
+
A new Android SDK and AVD Manager tool is available. To access
+it, run the android tool without options.
This document describes how to move your development environment and existing
+Android applications from an Android 1.5 SDK to the Android 1.6 SDK. If you are
+migrating applications from an SDK older than 1.5, please also read the
+upgrading document available in the Android 1.5 SDK package.
+
+
There are several compelling reasons to upgrade, such as new SDK tools that
+make developing more efficient and new APIs that allow you to expand the
+feature-set of your applications. However, even if you or your applications
+don't require these enhancements, it's important that you upgrade to ensure that
+your applications run properly on the upcoming Android platform.
+
+
The Android 1.6 platform will soon be deployable to devices around the world.
+If you have already released Android applications to the public, you should test
+the forward-compatibility of your applications on the latest version of the
+platform as soon as possible. It's unlikely that you'll encounter problems in
+your applications, but in the interest of maintaining the best user experience,
+you should take no risks. So, please install the new Android SDK and test your
+applications on the new platform.
If you haven't yet downloaded the SDK, download it from
+here and unpack it into a safe location.
+
+
If you had previously setup your PATH variable to point to the SDK
+tools directory, then you need to update it to point to the new SDK. For example, for
+a .bashrc or .bash_profile file:
A new version of the ADT Plugin, ADT 0.9.3, is available in conjunction with
+this SDK release. To use the SDK, you must upgrade your ADT Plugin to version
+0.9.3. With ADT 0.9.3, you can still compile your existing applications against
+multiple platform versions, such as Android 1.5, Android 1.1, and so on. However,
+ADT 0.9.3 is not compatible with previous versions of the SDK and its tools, so
+make sure that you upgrade both your SDK and the ADT Plugin.
+
+The upgrade steps for ADT are described below. For information about new features in ADT, see the Release Notes document.
+
+
If you're currently using a version of ADT older than version 0.9,
+then you must uninstall ADT before you proceed (read how to Uninstall your previous
+ADT plugin). If you currently have version 0.9 or 0.9.1, then you don't need
+to uninstall and can continue with the procedure below.
+
+
+
Eclipse 3.4 (Ganymede)
Eclipse 3.5 (Galileo)
+
+
+
+
+
Select Help > Software Updates.
+
Select the Available Software tab.
+
Select the checkboxes next to Android DDMS and Android Developer Tools,
+ then click Update.
+
In the resulting Available Updates dialog, ensure that both Android DDMS
+ and Android Development Tools are selected, then click
+ Next.
+
Read and accept the license agreement and then click Finish.
+ This will download and install the latest version of Android DDMS and
+ Android Development Tools.
+
Restart Eclipse.
+
+
+
+
+
+
Select Help > Check for Updates.
+
In the resulting Available Updates dialog, locate the Android DDMS and
+ Android Development Tools features in the list and ensure that the checkboxes
+ next to them are selected. Click Next.
+
If the Available Updates dialog does not list Android DDMS and Android
+ Development tools, make sure that you have set up a remote update site
+ for them, as described in
+ Installing the ADT Plugin.
+
+
In the Update Details dialog, click Next.
+
Read and accept the license agreement and then click Finish.
+ This will download and install the latest version of Android DDMS and
+ Android Development Tools.
The last step is to update your Eclipse preferences to point to the new
+SDK directory:
+
+
Select Window > Preferences to open
+ the Preferences panel (Mac: Eclipse > Preferences
+ ).
+
Select Android from the left panel.
+
For the SDK Location, click Browse
+ and locate your SDK directory.
+
Click Apply, then OK.
+
+
+
+
Run Your Applications to Test Forward Compatibility
+
+
Now that you have installed the Android 1.6 SDK, we encourage you run each of
+your existing applications on the Android 1.6 system image that is included in
+the SDK, to ensure that it functions properly on the new platform.
+Testing forward-compatibility in this way is especially important for
+applications that you may have already published and that may be installed on
+devices that will upgrade to the new platform.
+
+
In most cases, your applications will function properly when run on the new
+version of the platform. However, it is possible that you will encounter
+unexpected behavior, because of changes in the API or underlying platform. If
+you do find problems, you can use the SDK tools to compile and publish an update
+to the applications, which users can then download.
+
+
To test forward-compatibility, simply run your application, as-is, on an
+instance of the Android Emulator that uses an AVD targeted to the "Android 1.6"
+system image. Here are the steps:
+
+
+
Make no changes to your application code.
+
Create a new AVD that runs the new "Android 1.6" platform.
+
Launch your application in an emulator running the new AVD.
+
Perform normal testing on your application to ensure everything works as
+ expected.
+
+
+
Note that, for the purposes of forward-compatibility testing, you should not
+change how your application is compiled. That is, you should continue to compile
+the application against the same version of the Android library as before. The
+only change needed is to the AVD, which controls the version of the Android
+system image (run-time environment) on which the application is run.
+
+
The new version of the Android platform includes several new APIs, but
+very few actual changes to existing APIs. This means that, in most
+cases, your applications written with earlier versions of the Android library
+should run properly on the Android 1.6 platform.
+
+
However, here are some areas to pay attention to as you test forward-compatibility:
+
+
+
Make sure your application doesn't use internal APIs. Your
+application should not use any APIs that are not officially supported and are
+not published in the Android reference documentation. Unofficial APIs can change
+at any time without notice and — if your application happens to be using
+them — such a change could cause the application to break.
+
+
Watch for assumptions about available hardware. Remember
+that not all compatible devices offer the same hardware capabilities —
+screens, keyboards, and physical keys, and so on. As you test your application,
+watch for areas where your application depends on the presence of specific
+hardware capabilities. If you find dependencies, you can design around them by
+building in alternate support or graceful degradation, or you can specify them
+as hardware requirements in a
+<uses-configuration>.
+element in the application's manifest file. Also see the <uses-feature>
+manifest element, which lets your application declare a requirement for
+specific features, such as an OpenGL ES version or a camera that has
+autofocus capability.
+
+
+
Watch for assumptions about available features. Not all
+compatible devices offer equal support for embedded features. same hardware capabilities —
+screens, keyboards, and physical keys, and so on. As you test your application,
+watch for areas where your application depends on the presence of specific
+hardware capabilities. If you find dependencies, you can design around them by
+building in alternate support or graceful degradation, or you can specify them
+as hardware requirements in a
+<uses-configuration>.
+element in the application's manifest file.
+
+
When testing forward-compatibility, try running your application in various
+AVDs that emulate different hardware configurations. For example, you can create
+an AVD that does not offer a physical keyboard or one that uses a dpad instead
+of a trackball. Running your application in different emulated hardware
+configurations will give you an idea of where its dependencies are and help you
+identify problems.
+
+
+
Watch for assumptions about screen resolution and
+density. A device's screen resolution and density is likely to affect
+the way that your application's UI is rendered, especially if your app specifies
+dimensions or positions using pixels or absolute layouts. To ensure consistent
+UI across screens, your app should specify the dimensions and positions of
+layouts and drawables in relative units that can be scaled by the system as
+appropriate, according to the density of the device's screen. Alternatively, you
+can create custom sets of layout/drawable resources for specific screens, which
+the system can then load as appropriate, based on the current device screen.
+
+
When testing forward-compatibility, try running your application in various
+AVDs that emulate different screen resolutions and densities. Also note that,
+starting with Android 1.6, the platform provides a Compatibility Mode that
+automatically scales the UI of applications if they do not explicitly indicate
+support for the current screen in the
+<supports-screen>
+element in their manifest files. As part of testing, you should evaluate how
+your application is displayed in Compatibility Mode on different screens.
+
+
+
Avoid performing layout orientation changes based on the
+acceletometer (or via other sensors). Some Android-powered devices will
+automatically rotate the orientation (and all devices have the option to turn on
+auto-rotation), so if your application also attempts to rotate the orientation,
+it can result in strange behavior. In addition, if your application uses the
+accelerometer to detect shaking and you do not want to rotate the orientation,
+then you should lock the current orientation with android:screenOrientation.
+
+
+
+
+
Migrate Your Applications
+
+
If you want to use any of the new Android 1.6 APIs in your existing
+applications, you must first migrate the applications to the new Android
+platform version. Generally, migrating an application includes:
+
+
+
Referencing the proper API Level in the application's manifest file,
+and
+
Resetting its project properties so that it is compiled against the Android
+1.6 build target.
+
+
+
Additionally, to run your application in the emulator, you need to
+create an AVD that uses the Android 1.6 system image.
+
+
Note: You only need migrate your application as
+described in this section if the application will actually use APIs
+introduced in the Android 1.6 platform (which are not available on
+devices running older versions of the Android platform). If your application
+does not use any new APIs, you can compile and run it without modification and
+not migration is necessary.
+
+
Reference the Proper API Level
+
+
If your application is using APIs introduced in Android 1.6, you must
+reference that dependency in the application's manifest file so that it can be
+deployed to devices running the Android 1.6 platform.
+
+
Open the manifest file and locate the minSdkVersion attribute
+in the <uses-sdk> manifest element. Set the value of
+minSdkVersion to "4" (the API Level
+identifier corresponding to Android 1.6). Here's an example:
Once you've changed the minSdkVersion value in your
+application's manifest, you need to set the application's project properties so
+that the application will be compiled against the Android 1.6 library. To do so,
+follow the steps below for your respective development environment.
+
+
Eclipse Users
+
+
+
Right-click on the individual project (in the Package Explorer)
+ and select Properties.
+
In the properties, open the Android panel and select a new Project Build Target.
+ Select "Android 1.6" to target the new platform (or "Google APIs" with the "4"
+ API Level, if your application uses the Google Maps APIs).
+
Click Apply, then OK.
+
+
+
Ant Users
+
+
Use the android tool (located in
+your_sdk/tools/) to create a new build.xml
+that references the new platform target. To see a list of available targets,
+execute:
+
+
android list targets
+
+
Select the target id that corresponds to the "Android 1.6" platform
+and pass it with the --target parameter when updating your project.
+For example:
If your application uses the Google Maps APIs (i.e., MapView), be certain to
+select a Google APIs target.
+
+
Create an AVD that Uses the Android 1.6 Platform
+
+
Finally, you need to set up a new AVD that uses the Android 1.6 platform, so that
+you can run your application in the emulator.
+
+
To set up the new AVD, use the android tool, available in the
+tools/ directory of the SDK. You can run the AVD manager by simply
+changing to the tools/ directory and entering android
+at the command line. Click "New" to create the AVD and set its properties.
+
+
When creating the AVD, make sure to select a target of "Android 1.6 - API
+Level 4". If your application uses the Google Maps APIs (MapView), select the
+target "Google APIs (Google Inc.) - API Level 4".
This document provides version-specific information about Android SDK
-releases. For the latest known issues, please ensure that you're viewing this
-page at http://developer.android.com/sdk/RELEASENOTES.html.
+releases.
+
+
Android SDK
+
+
The Android SDK has changed! If you've worked with the Android SDK before,
+you will notice several important differences:
+
+
+
The SDK downloadable package includes only
+the latest version of the Android SDK Tools.
+
Once you've installed the SDK, you now use the Android SDK and AVD Manager
+to download all of the SDK components that you need, such as Android platforms,
+SDK add-ons, tools, and documentation.
+
The new approach is modular — you can install only the components you
+need and update any or all components without affecting your development
+environment.
+
In short, once you've installed the new SDK, you will not need to download
+an SDK package again. Instead, you will use the Android SDK and AVD Manager to
+keep your development environment up-to-date.
+
+
+
Note that if you are currently using the Android 1.6 SDK, you do not
+necessarily need to install the new SDK, since your existing SDK already
+includes the Android SDK and AVD Manager tool. To develop against Android 2.0,
+for example, you could just download the Android 2.0 platform into your existing
+SDK.
+
+
Release notes for Android platforms and other SDK components are
+now available from the "SDK" tab, under "Downloadable SDK Components."
This SDK provides updates to the development tools and Android system that
+you use to create applications for compliant Android-powered devices.
+
+
Release Overview
+
+
This SDK release includes several new features for developers. Highlights of the
+changes include:
+
+
+
Emulator support for multiple screen sizes/densities, including new
+skins.
+
Android SDK and AVD Manager, a graphical UI to let you manage your
+SDK and AVD environments more easily. The tool lets you create and manage
+your Android Virtual
+Devices and download new SDK packages (such as platform versions and
+add-ons) into your environment.
+
Improved support for test packages in New Project Wizard
+
The reference documentation now offers a "Filter by API Level"
+capability that lets you display only the parts of the API that are actually
+available to your application, based on the android:minSdkVersion
+value the application declares in its manifest. For more information, see
+Android API Levels
+
+
+
For details about the Android platforms included in the SDK — including
+bug fixes, features, and API changes — please read the Version Notes
+documents available at left. For a list of Android platforms included in this
+release, see the Download
+page. Note that you can use the Android SDK and AVD Manager to download
+additional platforms.
+
+
Installation and Upgrade Notes
+
+
If you've been developing an application using an Android 1.1 SDK, you need
+to make a few changes to your development environment to migrate to the new SDK.
+Tools and documentation are provided to assist you. No changes to the source
+code of an existing application should be needed, provided that your application
+is not using Android internal structures or APIs.
+
+
To ensure that your existing application will work properly on a device
+running the latest version of the Android platform, you are strongly encouraged
+to migrate the application to the new SDK, compile it using the platform
+matching the application's original API Level, and run it against the most
+current platform.
+
+
If you're installing the Android SDK for the first time, please see
+the instructions in Installing the SDK.
+
+
ADT Plugin for Eclipse
+
+
An updated version of the ADT Plugin for Eclipse is available with the
+Android 1.6 SDK. The new version, ADT 0.9.3, provides several new
+features, including integrated support for the Android SDK and AVD Manager
+and zipalign tool. In addition, the New Project Wizard now
+lets you create a test package containing tests for your application. These
+features are described in the sections below.
+
+
If you are developing in Eclipse with ADT and want to get started with the
+Android 1.6 SDK, you should download and install a compatible version of the ADT
+Plugin (0.9.3 or higher).
+
+
The new version of ADT is downloadable from the usual remote update site or
+is separately downloadable as a .zip archive. For instructions on how to
+download the plugin, please see Upgrading
+Your Eclipse Plugin.
+
+
Android SDK and AVD Manager
+
+
The SDK offers a new tool called Android SDK and AVD Manager that lets you
+manage your SDK and AVD environments more efficiently.
+
+
Using the tool, you can quickly check what Android platforms, add-ons,
+extras, and documentation packages are available in your SDK environment, what
+their versions are, and whether updated versions are available. You can then
+download one or more items from remote repositories and install them directly in
+your SDK environment. For example, the tool lets you obtain updates to SDK tools
+incrementally, as they are made available, without having to wait for the next
+SDK release. You can also download Android platform versions into your
+environment that were not included in the SDK package.
+
+
The tool also lets you quickly create new AVDs, manage
+their properties, and run a target AVD from a single window.
+
+
If you are developing in Eclipse with ADT, you can access the Android SDK
+and AVD Manager from the Window menu.
+
+
If you are developing in another IDE, you can access the Android SDK and
+AVD Manager through the android command-line tool, located in the
+<sdk>/tools directory. You can launch the tool with a graphical UI by
+using the android command without specifying any options. You can
+also simply double-click the android.bat (Windows) or android (OS X/Linux) file.
+You can still use android commands to create and manage AVDs,
+including AVDs with custom hardware configurations.
+
+
Integration with zipalign
+
+
The Android system offers a performance optimization for installed
+application packages whose contained uncompressed files are all aligned on
+4-byte boundaries. For these .apks, the system can read the files by mmap'ing
+the zip file, rather than by copying all the data out of them. This reduces
+the amount of memory used by the application at run time. The SDK includes
+a tool called zipalign that you can run against your .apks, to
+align them properly and enable them to benefit from this optimization.
+
+
The ADT Plugin and the Ant build tools both provide integrated support for
+aligning your application packages. After you build an .apk, the SDK tools can
+sign and then run zipalign against it. The SDK includes the
+standalone version of the zipalign tool, so you can run also run it
+manually from the command line if you choose.
+
+
+
If you are developing in Eclipse with ADT, support for
+zipalign is integrated into the Export Wizard. When you use the
+Wizard to export a signed application package, ADT signs and then automatically
+runs zipalign against the exported package. If you use the Wizard
+to export an unsigned application package, then it will not zipalign the
+package because zipalign must be performed only after the APK has been signed.
+You must manually sign and zipalign the package after export.
+
If you are developing using Ant and are compiling in release mode, the
+build tools will automatically sign and then zipalign the
+application package, provided that you have specified the location of a valid
+keystore in the build properties file. If you are compiling in debug mode, the
+build tools will sign the package with the debug key and then zipalign
+it.
+
To use zipalign manually, change to the SDK tools directory
+and use the command syntax $ zipalign 4 <infile>
+<outfile>
+
+
+
In general, note that you must zipalign an application only
+after it has been signed, as signing will disrupt the package
+alignment.
+
+
Support for Test Packages in New Project Wizard
+
+
The New Project Wizard available in the ADT 0.9.3 now lets you add a test
+package containing Instrumentation or other classes of tests while you are
+creating or importing a new Android application project.
+
+
New USB Driver for Windows
+
+
If you are using Windows and want to develop or test your application on an
+Android-powered device (such as the T-Mobile G1), you need an appropriate USB
+driver.
+
+
The Windows version of the Android 1.6 SDK includes a new, WinUSB-based
+driver that you can install. The driver is compatible with both 32- and 64-bit
+versions of Windows XP and Vista. The driver represents an upgrade from the USB
+driver included in previous Android SDKs, although installing the new driver is
+not required.
+
+
If you installed the USB driver from a previous SDK release and it is working
+properly, you do not need to upgrade to the new driver. However, we recommend
+upgrading if you have had any problems with the older driver or simply want
+to upgrade to the latest version.
+
+
The USB driver files are located in the
+<SDK>/usb_driver directory. For driver installation or
+upgrade instructions, see Installing the WinUSB
+Driver.
+
+
+
Emulator Skins, Android 1.6 Platform
+
+
The Android 1.6 platform included in the SDK provides a new set of emulator
+skins, including:
+
+
+
QVGA — 240 x 320, low density (120 dpi)
+
HVGA — 320 x 480, medium density (160 dpi)
+
WVGA800 — 480 x 800, high density (240 dpi)
+
WVGA854 — 480 x 854, high density (240 dpi)
+
+
+
Besides these defaults, You can also create an AVD that overrides the default
+density for each skin, to create any combination of resolution/density (WVGA
+with medium density, for instance). To do so, use the android tool
+command line to create a new AVD that uses a custom hardware configuration. See
+Creating an
+AVD for more information.
+
+
Other Notes and Resolved Issues
+
+
+
This SDK release adds support for Eclipse 3.5 (Galileo) and deprecates
+support for Eclipse 3.3 (Europa).
+
We regret to inform developers that Android 1.6 will not include support
+for RFC 2549
+
The issue preventing adb from recognizing Samsung Galaxy devices (linux SDK
+only) has been fixed.
Adding and updating components in your Android SDK is fast and easy. To
+perform an update, use the Android SDK and AVD Manager to
+install or update the individual SDK components that you need. The Android SDK
+and AVD Manager tool is included in Android 1.6 and later SDK packages.
+
+
It only takes a couple of clicks to install
+individual versions of the Android platform, new development tools, new documentation, and
+SDK add-ons. The new SDK components are automatically installed into your existing SDK
+directory, so you don't need to update your development environment to specify a
+new SDK location.
+
+
Because each version of the Android platform can be installed as an individual component
+of your SDK, you can customize your development environment to the Android platforms
+you are targetting. Testing your app on multiple versions of
+the platform is very important in order to successfully operate on as many devices as possible.
+Be sure to install each version of the Android platform with which your app is compatible, then test
+your apps on AVDs that run each platform.
+
+
If you develop applications using Eclipse, you may also need to update your
+ADT plugin when you update your development tools or in order to compile against
+a new version of the platform. See the SDK Tools Notes document for ADT
+compatibility.
+
+
+
Installing SDK Components
+
+
Use the Android SDK and AVD Manager to install new SDK components.
+
+
Important: Before you install SDK components,
+we recommend that you disable any antivirus programs that may be running on
+your computer.
+
+
You can launch the SDK and AVD Manager in one of these ways:
+
+
Execute the {@code android} tool command with no options. If you
+haven't used the tool before, change to the <sdk>/tools
+directory and run the command:
+
$ android
+
If you have downloaded the SDK Tools (Revision 3 or higher) and are
+ running Windows, you can double-click "SDK Setup.exe" in the SDK directory.
+
If you are developing in Eclipse with ADT, you can select
+ Window >Android SDK and AVD Manager.
+
+
+
+
+
When a new platform version, add-on, set of development tools or
+documentation becomes available, you can quickly install them into your existing
+Android SDK:
+
+
Select Available Components in the left panel.
+ This will reveal all components currently available for download.
+
Select the components you'd like to install and click Install
+ Selected.
+
Verify and accept the components you want and click Install
+ Accepted. The components will now be installed into your existing
+ Android SDK directories.
+
+
+
New platforms are automatically saved into the
+<sdk>/platforms/ directory of your SDK;
+new add-ons are saved in the <sdk>/add-ons/
+directory; and new documentation is saved in the existing
+<sdk>/docs/ directory (old docs are replaced).
+
+
Tip:
+Use the "Display updates only" checkbox to show only the components
+you do not have.
+
+
+
Adding New Sites
+
+
By default, Available Components only shows the default
+repository site, which offers platforms, SDK tools, documentation, the
+Google APIs Add-on, and other components. You can add other sites that host
+their own Android SDK add-ons, then download the SDK add-ons
+from those sites.
+
+
For example, a mobile carrier or device manufacturer might offer additional
+API libraries that are supported by their own Android-powered devices. In order
+to develop using their libraries, you must install their Android SDK add-on.
+
+
If a carrier or device manufacturer has hosted an SDK add-on repository file
+on their web site, follow these steps to add their site to the SDK and AVD
+Manager:
+
+
+
Select Available Components in the left panel.
+
Click Add Site and enter the URL of the
+{@code repository.xml} file. Click OK.
+
+
Any SDK components available from the site will now be listed under
+Available Components.
+
+
+
SDK Component Dependencies
+
+
In some cases, a specific SDK component may require a specific minimum
+version of another component or SDK tool. Such dependencies are documented
+in the release notes for each component.
+
+
For example, there may be a dependency between the ADT plugin for Eclipse and
+a specific version of the SDK Tools component. When you install the SDK Tools
+component, you would then need to upgrade to the required version of ADT (if you
+are developing in Eclipse). In this case, you would find dependencies listed in
+the ADT Plugin Notes and SDK Tools Notes documents.
+
+
Additionally, the development tools will notify you with debug warnings
+if there is dependency that you need to address.
Android Development Tools (ADT) is a development plugin for the Eclipse IDE. It
+extends the capabilites of Eclipse to let you quickly set up new Android
+projects, create an application UI, add components based on the Android
+Framework API, debug your applications using the Android SDK tools, and even export
+signed (or unsigned) APKs in order to distribute your application.
+
+
This document provides version-specific information about ADT releases. To
+keep up-to-date on new releases, make sure that you view this page at http://developer.
+android.com/sdk/adt-notes.html.
+
+
To install ADT in your Eclipse IDE environment, use the Eclipse Update Site
+feature. For more information, see Installing and Updating ADT.
+
+
ADT 0.9.4
+
+
ADT 0.9.4 provides several new features for developers, as described below.
+
+
+
Dependencies
+
+
ADT 0.9.4 requires features provided in SDK Tools, Revision 3. If you install
+ADT 0.9.4, which is highly recommended, you should use the Android SDK and AVD
+Manager to download SDK Tools 3 or higher into your SDK. For more information,
+see Adding SDK Components.
+
+
+
Project Creation Wizard
+
+
New option to create a project from a sample by choosing it from a list.
+
+
+
Layout Editor
+
+
Improved Configuration selector that lets you see how your layout will
+render on different devices. Default device descriptions include ADP1
+and Google Ion, while SDK add-ons can also provide new descriptions.
+A new UI allows you to create custom descriptions.
+
Adds a new clipping toggle, to let you see your full layout even if it's
+bigger than the screen.
+
+
+
DDMS Integration
+
+
Includes the improvements from the standlone DDMS, revision 3.
+
Adds an option to open HPROF files into eclipse instead of writing them on
+disk. If a profiler such as MAT (Memory Analyzer
+Tool) is installed, it'll open the file.
+
+
+
Android SDK and AVD Manager integration
+
+
Includes the improvements from the standalone Android SDK and AVD Manager,
+revision 3.
+
\ No newline at end of file
diff --git a/docs/html/sdk/adt_download.jd b/docs/html/sdk/adt_download.jd
index d7b9ac328082..6ce76343aa81 100644
--- a/docs/html/sdk/adt_download.jd
+++ b/docs/html/sdk/adt_download.jd
@@ -1,21 +1,18 @@
-page.title=Download the ADT Plugin Zip File
+page.title=Download the ADT Zip File
@jd:body
-
-If you use this approach, in order to update the plugin, you will need to
+from your computer (archived site) instead.
+
+
If you use this approach, in order to update the plugin, you will need to
download the latest version from this page, uninstall the old version from
Eclipse, then install the new version. For more details on the procedure,
-see Troubleshooting ADT Installation in the
- installation
-page.
-
Required for users of Android 1.6 SDK only . Updated from 0.9.1. September 2009
Obsolete Versions of ADT
-
The table below lists older versions of the ADT Plugin that are no longer supported. If you are developing applications that are intended to be deployable to Android-powered devices, make sure that you upgrade to the most current SDK release available and use the most current version of the ADT Plugin, as listed in the section above.
+
The table below lists older versions of the ADT Plugin that are no longer
+supported. If you are developing applications that are intended to be deployable
+to Android-powered devices, make sure that you upgrade to the most current SDK
+release available and use the most current version of the ADT Plugin, as listed
+in the section above.
-
If you are not sure what version of ADT is installed in your Eclipse environment, open Eclipse and from the main menu select Help > About Eclipse > Features Details. Locate "com.android.ide.eclipse.adt" in the
-Feature ID column and look at its version number.
+
If you are not sure what version of ADT is installed in your Eclipse
+environment, open Eclipse and from the main menu select Help
+> About Eclipse > Features Details.
+Locate "com.android.ide.eclipse.adt" in the Feature ID column and look at its
+version number.
ADT Version
Notes
-
+
+
0.9.1
+
Required for users of Android 1.5 SDK. Updated from 0.9.0. 6 May 2009
+
+
+
0.8.0
+
Required for users of Android 1.0/1.1 SDKs. 23 Sep 2008
+
0.7.1
-
Required for users of Android 0.9 SDK beta. As of this version, Eclipse 3.2 is no longer supported.
- Please upgrade to Eclipse Ganymede (3.4) or Europa (3.3) if you are still using 3.2. 18 Aug 2008
+
Required for users of the Android 0.9 SDK beta. 18 Aug 2008
0.4.0
-
Required if you are using the M5 SDK. See the SDK Release Notes for details on changes and enhancements in this version. 12 Feb 2008
+
Required for users of the Android M5 Early Look SDK. 12 Feb 2008
0.3.3
-
Some significant enhancements (see m3-rc37 SDK Release Notes). 14 Dec 2007
+
Required for users of the Android M3-RC37 Early Look SDK. 14 Dec 2007
0.3.1
-
Initial Release. Required for Android m3-rc20 SDK and Android m3-rc22 SDK.21 Nov 2007
+
Initial Release. Required for users of the Android M3-RC20/22 SDKs.21 Nov 2007
Android {@sdkPlatformVersion} is a {@sdkPlatformMajorMinor} platform release
+deployable to Android-powered handsets starting in {@sdkPlatformDeployableDate}.
+The release includes new features for users and developers, as well as changes
+in the Android framework API.
-
This document provides version notes for the Android 1.5 system image included in the SDK.
+
For developers, the Android {@sdkPlatformVersion} platform is available as a
+downloadable component for the Android SDK. The downloadable platform includes a
+fully compliant Android library and system image, as well as a set of emulator
+skins, sample applications, and more. The downloadable platform is fully
+compliant and includes no external libraries.
To get started developing or testing against the Android
+{@sdkPlatformVersion} platform, use the Android SDK and AVD Manager tool to
+download the platform into your Android 1.6 or later SDK. For more information,
+see Adding SDK
+Components.
-
Overview
-
The Android 1.5 system delivered in the SDK (as library and system image) is
-the development counterpart to the Android 1.5 production system image,
-deployable to Android-powered handsets starting in May 2009. The system is fully
-compliant and includes no external libraries. This is the first version of the
-Android SDK that does not include the Maps external library.
The Android 1.5 system delivers an updated version of the framework
-API. As with previous versions, the Android 1.5 API
-is assigned an integer identifier — 3 — 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.
-
-
Applications can reference a specific API Level value in their
-manifest files, to indicate the minimum version of the Android system
-required to run the application. To reference a minimum API Level, applications
-can add an android:minSdkVersion attribute in their manifest files.
-The value of the attribute is an integer corresponding to an API Level
-identifier. Prior to installing an application, the system then checks the value of
-android:minSdkVersion and allows the install only
-if the referenced integer is less than or equal to the API Level integer stored
-in the system itself.
-
-
When you migrate your application to the new SDK, you will need to choose
-the platform version against which you will compile your application. In
-general, you should compile your application against the lowest possible
-version of the platform that your application can support. After you determine
-the lowest version, you should ensure that your application's manifest file
-defines the API Level of the lowest compatible platform version in the
-android:minSdkVersion attribute.
-
-
After compiling your application, you should make sure to test it on the
-platform specified in the application's android:minSdkVersion attribute. To
-ensure forward-compatibility, you should also run the application on platforms
-using a higher API Level than that used by your application. To run your
-application against different platform versions in the emulator, you create an
-AVD for each platform version that you want to test. For more information about
-AVDs, see Android Virtual
-Devices. If you are using a physical device for testing, ensure that you
-know the API Level of the Android platform it runs.
-
-
If you build an application using the Android 1.5 library and your
-application makes use of any APIs introduced in API Level 3, you must set the
-android:minSdkVersion attribute in the application's manifest to
-"3".
-
-
Specifically, you define the android:minSdkVersion
-attribute in a <uses-sdk> element as a child of
-<manifest> in the manifest file. When set, the
-attribute looks like this:
By setting android:minSdkVersion in this way, you ensure that
-users will only be able to install your application if their devices are running
-a compatible version of the Android platform. In turn, this ensures that your
-application will function properly on their devices. This is especially
-important if your application uses APIs or system features
-introduced in Android 1.5.
-
-
If your application uses APIs introduced in Android 1.5 but does not
-declare <uses-sdk android:minSdkVersion="3" />, then it will
-run properly on Android 1.5 devices but not on Android 1.0
-devices. In the latter case, the application will crash at runtime when
-it tries to use the Android 1.5 APIs.
-
-
Conversely, if your application does not use any new APIs introduced in
-Android 1.5, the application will in most cases function normally on devices
-running a later version of the platform. However, if you have published
-the application, you are strongly encouraged to install and test your
-application on the Android 1.5 system image included in the SDK. This will
-ensure a smooth transition for users, as they upgrade their devices to
-the new version of the Android platform.
-
-
Finally, if your application does not use any new APIs introduced since
-Android 1.1, you can indicate general Android 1.1 compatibility by
-setting the attribute to "2". If your application does not use any
-new APIs introduced since Android 1.0, you can remove the attribute or
-set it to "1". However,
-before publishing your application, you must make sure to compile your
-application against the Android library that corresponds to the application's
-android:minSdkVeresion value.
Built-in Applications
-
The system image includes these built-in applications:
+
The system image included in the downloadable platform provides these
+built-in applications:
+
+
+
+
Alarm Clock
Browser
@@ -122,6 +78,10 @@ application against the Android library that corresponds to the application's
Contacts
Custom Locale (developer app)
Dev Tools (developer app)
+
+
+
+
Dialer
Email
Gallery
@@ -131,18 +91,22 @@ application against the Android library that corresponds to the application's
Settings
Spare Parts (developer app)
+
+
+
-
Locales
+
Locales
-
The system image 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 will be
-available in the Android 1.5 system image are listed below (with
-language_country/region locale descriptor).
+
The system image included in the downloadable 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).
-
+
-
+
Chinese, PRC (zh_CN)
Chinese, Taiwan (zh_TW)
@@ -151,7 +115,7 @@ available in the Android 1.5 system image are listed below (with
Dutch, Belgium (nl_BE)
English, US (en_US)
English, Britain (en_GB)
-
English, Canada(en_CA)
+
English, Canada (en_CA)
English, Australia (en_AU)
English, New Zealand (en_NZ)
English, Singapore(en_SG)
@@ -159,11 +123,11 @@ available in the Android 1.5 system image are listed below (with
French, Belgium (fr_BE)
-
+
French, Canada (fr_CA)
French, Switzerland (fr_CH)
German, Germany (de_DE)
-
German, Austria(de_AT)
+
German, Austria (de_AT)
German, Switzerland (de_CH)
German, Liechtenstein (de_LI)
Italian, Italy (it_IT)
@@ -177,29 +141,65 @@ available in the Android 1.5 system image are listed below (with
-
Localized UI strings match the locales that are displayable in
-the emulator, accessible through the device Settings application.
+
Localized UI strings match the locales that are accessible
+through Settings.
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:
-
API Changes
+
+
+ QVGA-P (240x320, low density, small screen)
+
+
+ QVGA-L (320x480, low density, small screen)
+
+
+ HVGA (320x480, medium density, normal screen)
+
+
+ HVGA-P (320x480, medium density, normal screen)
+
+
+ HVGA-L (320x480, medium density, normal screen)
+
+
-
Overview
+
For more information about how to develop an application that displays and functions properly on all Android-powered devices, see Supporting Multiple Screens.
-
-
UI framework
+
+
Framework API
+
+
The sections below provide information about the application framework API provided by the Android {@sdkPlatformVersion} platform.
+
+
+
API level
+
+
The Android {@sdkPlatformVersion} platform delivers an updated version of the framework
+API. As with previous versions, 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 to
+set the proper value, "{@sdkPlatformApiLevel}", in the attributes of the <uses-sdk>
+element in your application's manifest.
+
+
For more information about how to use API Level, see the API Levels document.
+
+
API changes summary
+
+
UI framework
Framework for easier background/UI thread interaction
New {@link android.widget.SlidingDrawer SlidingDrawer} widget
New {@link android.widget.HorizontalScrollView HorizontalScrollview} widget
-
-
AppWidget framework
+
AppWidget framework
APIs for creating secure home screen {@link android.appwidget
AppWidgets}. For information about how to use AppWidgets, see the Developer's
@@ -211,9 +211,8 @@ framework on the Android Developer's Blog.
APIs for populating {@link android.provider.LiveFolders Live Folders}
with custom content.
-
-
Media framework
+
Media framework
Raw audio recording and playback APIs
Interactive MIDI playback engine
@@ -221,37 +220,33 @@ framework on the Android Developer's Blog.
Applications can now use a new element in their manifest files, <uses-
-configuration> to indicate to the Android system what hardware features
+href="{@docRoot}guide/topics/manifest/uses-configuration-element.html"><uses-configuration>
+ to indicate to the Android system what hardware features
they require in order to function properly. For example, an application might
use the element to specify that it requires a physical keyboard or a particular
navigation device, such as a trackball. Prior to installing the application, the
Android system checks the attributes defined for the
<uses-configuration> element and allows the installation to
continue only if the required hardware is present.
-
-
Speech recognition framework
+
Speech recognition framework
Support for using speech recognition libraries via Intent. See {@link
android.speech.RecognizerIntent RecognizerIntent}.
-
-
Miscellaneous API additions
+
Miscellaneous API additions
LocationManager - Applications can get location change updates via
Intent
Broadcast Intent for app update install succeeded - for smoother app
upgrade experience
-
-
-
-
-
API Change Details
-
-
For a detailed view of API changes in this platform (API Level 3), see the API Differences Report.
-
-
-
+
API differences report
+
For a detailed view of API changes in Android {@sdkPlatformVersion} (API Level {@sdkPlatformApiLevel}), as compared to
+the previous version, see the API
+Differences Report.
Android 1.6 includes a redesigned search framework that provides a quick,
+effective, and consistent way for users to search across multiple sources—such as
+browser bookmarks & history, contacts, and the web—directly from
+the home screen.
+
+
The system constantly learns which search results are more relevant based on what is
+clicked. So popular contacts or apps that have previously been picked will bubble up to
+the top when a user types the first few letters of a relevant query.
+
+
The search framework also provides developers a way to easily expose relevant
+content from their applications in Quick Search Box.
+
+
Camera, Camcorder, and Gallery
+
+
An updated user interface provides an integrated camera, camcorder, and gallery experience.
+Users can quickly toggle between still and video capture modes. Additionally, the gallery
+enables users to select multiple photos for deletion.
+
+
Android 1.6 also provides a much faster camera experience.
+Compared to the previous release, launching the camera is now 39% faster,
+and there is a 28% improvement in the time from completing one shot to the next.
+
+
+
VPN, 802.1x
+
+
A new Virtual Private Network (VPN) control panel in Settings allows users
+to configure and connect to the following types of VPNs:
+
+
+
L2TP/IPSEC pre-shared key based VPN
+
L2TP/IPsec certificate based VPN
+
L2TP only VPN
+
PPTP only VPN
+
+
+
+
Battery usage indicator
+
+
A new battery usage screen lets users see which apps and services are consuming
+battery power. If the user determines that a particular service or application is
+using too much power, they can take action to save the battery by
+adjusting settings, stopping the application, or uninstalling the application.
+
+
+
Accessibility
+
+
Users will be able to download new accessibility services built
+on the new accessibility framework and enable them in Settings.
+
+
+
+
+
Android Market Updates
+
+
+
+New Android Market UI
+
+
+
For devices with Android Market, the latest version improves the overall user experience and makes
+it easier for users to discover great apps and games from developers.
+
+
+
At the homescreen, users can choose among Apps, Games, and Downloads.
+
Inside a category, users can explore titles that are Top paid, Top free, and Just in.
+
For each title, users can now see screenshots submitted by developers in addition to
+ reviews from other users.
+
+
+
+
+
+
New Platform Technologies
+
+
Expanded Search Framework
+
+
The Android search framework has been redesigned and expanded to provide
+third-party applications the opportunity to surface
+content from their applications in Quick Search Box, the global search tool.
+To do this, developers will need to make their app "searchable" and provide
+suggestions in response to user queries.
+To enable application search suggestions, users simply select each application from which
+they'd like to receive suggestions, under Searchable items in the Search settings.
+
+
+
Text-to-speech engine
+
+
Android 1.6 features a multi-lingual speech synthesis engine called Pico.
+It allows any Android application to "speak" a string of text with an accent that matches the language.
+The engine supports the following languages: English (American and British accents), French,
+Italian, German and Spanish. If you're using a T-Mobile G1 or Dream device, you'll need to download the
+SpeechSynthesis Data Installer from Android Market, which includes the "voices" needed by the
+text-to-speech engine.
+
+
+
Gestures
+
+
A new gestures framework provides application developers with a framework for creating, storing,
+loading, and recognizing gestures and associating them with specific actions.
+
+
Developers can use the new GestureBuilder tool included in the Android 1.6 SDK to generate libraries
+of gestures to include with their application.
+
+
+
Accessibility
+
+
Android 1.6 provides a new accessibility framework.
+With this framework, developers can create accessibility plugins that respond to user input,
+such as making a sound when a new window is shown, vibrating when navigating to the top of
+a list, and providing spoken feedback.
+
+
+
Expanded support for screen densities and resolutions
+
+
Android 1.6 adds screen support that enables applications to be rendered properly on different
+display resolutions and densities. Developers can also specify the types of screens supported by their
+application.
+
+
+
Telephony support for CDMA
+
+
Android 1.6 includes support for CDMA in the telephony stack.
+
+
+
New version of OpenCore
+
+
Android 1.6 includes the updated OpenCore 2 media engine, which has:
+
+
+
Support for OpenMAX encoders
+
Support for additional audio codecs in AuthorEngine
+
Improved buffering model supports shared buffers allocated in the decoder
+
+
+
2.6.29 Linux kernel
+
+
Android 1.6 upgrades the Linux kernel from 2.6.27 to 2.6.29.
+
+
+
New Framework APIs
+
+
For a detailed overview of new APIs, see the
+Version Notes.
+For a complete report of all API changes, see the
+API Differences Report.
diff --git a/docs/html/sdk/android-1.6.jd b/docs/html/sdk/android-1.6.jd
new file mode 100644
index 000000000000..4b659a1af62f
--- /dev/null
+++ b/docs/html/sdk/android-1.6.jd
@@ -0,0 +1,373 @@
+page.title=Android 1.6, Release 1
+sdk.platform.version=1.6
+sdk.platform.apiLevel=4
+sdk.platform.majorMinor=minor
+sdk.platform.releaseDate=September 2009
+sdk.platform.deployableDate=October 2009
+
+@jd:body
+
+
Android {@sdkPlatformVersion} is a {@sdkPlatformMajorMinor} platform release
+deployable to Android-powered handsets starting in {@sdkPlatformDeployableDate}.
+The release includes new features for users and developers, as well as changes
+in the Android framework API.
+
+
For developers, the Android {@sdkPlatformVersion} platform is available as a
+downloadable component for the Android SDK. The downloadable platform includes a
+fully compliant Android library and system image, as well as a set of emulator
+skins, sample applications, and more. The downloadable platform is fully
+compliant and includes no external libraries.
+
+
To get started developing or testing against the Android
+{@sdkPlatformVersion} platform, use the Android SDK and AVD Manager tool to
+download the platform into your Android 1.6 or later SDK. For more information,
+see Adding SDK
+Components.
The system image included in the downloadable platform provides these
+built-in applications:
+
+
+
+
+
+
Alarm Clock
+
Browser
+
Calculator
+
Camcorder
+
Camera
+
Contacts
+
Custom Locale (developer app)
+
Dev Tools (developer app)
+
Dialer
+
+
+
+
+
Email
+
Gallery
+
Gestures Builder
+
IME for Japanese text input
+
Messaging
+
Music
+
Settings
+
Spare Parts (developer app)
+
+
+
+
+
+
Locales
+
+
The system image included in the downloadable 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).
+
+
+
+
+
+
Chinese, PRC (zh_CN)
+
Chinese, Taiwan (zh_TW)
+
Czech (cs_CZ)
+
Dutch, Netherlands (nl_NL)
+
Dutch, Belgium (nl_BE)
+
English, US (en_US)
+
English, Britain (en_GB)
+
English, Canada (en_CA)
+
English, Australia (en_AU)
+
English, New Zealand (en_NZ)
+
English, Singapore(en_SG)
+
French, France (fr_FR)
+
French, Belgium (fr_BE)
+
+
+
+
French, Canada (fr_CA)
+
French, Switzerland (fr_CH)
+
German, Germany (de_DE)
+
German, Austria (de_AT)
+
German, Switzerland (de_CH)
+
German, Liechtenstein (de_LI)
+
Italian, Italy (it_IT)
+
Italian, Switzerland (it_CH)
+
Japanese (ja_JP)
+
Korean (ko_KR)
+
Polish (pl_PL)
+
Russian (ru_RU)
+
Spanish (es_ES)
+
+
+
+
+
Localized UI strings match the locales that are accessible
+through Settings.
+
+
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:
+
+
+
+ QVGA (240x320, low density, small screen)
+
+
+ HVGA (320x480, medium density, normal screen)
+
+
+ WVGA800 (480x800, high density, normal screen)
+
+
+ WVGA854 (480x854 high density, normal screen)
+
+
+
+
For more information about how to develop an application that displays and functions properly on all Android-powered devices, see Supporting Multiple Screens.
+
+
+
Framework API
+
+
The sections below provide information about the application framework API provided by the Android {@sdkPlatformVersion} platform.
+
+
+
API level
+
+
The Android {@sdkPlatformVersion} platform delivers an updated version of the framework
+API. As with previous versions, 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 to
+set the proper value, "{@sdkPlatformApiLevel}", in the attributes of the <uses-sdk>
+element in your application's manifest.
+
+
For more information about how to use API Level, see the API Levels document.
+
+
API changes summary
+
+
UI framework
+
+
New classes in {@link android.view.animation}
+ to control the behavior of animations:
+
+
AnticipateInterpolator
+
AnticipateOvershootInterpolator
+
BounceInterpolator
+
OvershootInterpolator
+
+
+
New XML attribute android:onClick to specify a View's
+View.OnClickListener
+from a layout file.
+
+
New support for dealing with varying screen densities. Density
+information is associated with Bitmap and Canvas for performing the
+correct scaling. The framework will automatically scale bitmaps and
+nine-patches based on the density the resource was found under and the
+density of the screen, etc.
+
To use APIs introduced in Android {@sdkPlatformVersion} in your application, you need to
+set the proper value, "{@sdkPlatformApiLevel}", in the attributes of the <uses-sdk>
+element in your application's manifest.
+
+
+
Search framework
+
+
Applications can now expose relevant content to users as search
+suggestions in the Quick Search Box, a new device-wide search capability that is
+accessible from the home screen. To support this, the search framework adds new
+attributes to the searchable metadata file. For complete information, see the
+{@link android.app.SearchManager SearchManager} documentation.
+
+
+
+
Accessibility framework
+
+
New {@link android.view.accessibility android.accessibility} package
+that includes classes for capturing accessibility events and forwarding them to
+an {@link android.accessibilityservice AccessibilityService} handler.
+
New {@link android.accessibilityservice AccessibilityService} package
+that lets your application track user events and provide visual, audible, or
+haptic feedback to the user.
+
+
+
Gesture Input
+
+
New {@link android.gesture gesture} API for creating, recognizing,
+loading, and saving gestures.
+
+
+
Text-to-speech
+
+
New {@link android.speech.tts android.speech.tts} package provides
+classes for synthesizing speech from text, for immediate playback or to create a
+sound file.
+
+
+
Graphics
+
+
Classes in {@link android.graphics android.graphics} now support scaling
+for different screen densities.
+
+
+
Telephony
+
+
New {@link android.telephony.SmsManager SmsManager} and other classes
+for sending and receiving SMS messages.
+
+
+
Utilities
+
+
New {@link android.util.DisplayMetrics DisplayMetrics} fields for
+determining the density of the current device screen.
+
+
+
Android Manifest elements
+
+
+
New {@code
+ <supports-screens>} element lets you specify the device screen sizes that your
+ application is designed and tested to support, where "size" is a combination
+ of resolution and density. If your application is run on a device whose screen
+ size is not specified in the <supports-screen> element, the system
+ displays the application in compatibility mode, which performs best-effort scaling
+ of the application UI to match the resolution and density of the screen.
+
+
The attributes available for defining an application's screen support are:
+
+
+
+
smallScreen: Boolean value that indicates whether the
+ application is designed to run on devices with small screens.
+ Examples: QVGA low density; VGA high density.
+
+
normalScreens: Boolean value that indicates whether
+ the application is designed to run on devices with normal screens.
+ Examples: WQVGA low density; HVGA medium density; WVGA high density.
+
+
largeScreens: Boolean value that indicates whether
+ the application is designed to run on devices with significantly
+ larger screens, such that special care may be required on
+ the application's part to make proper use of the screen area.
+ Examples: VGA medium density; WVGA medium density.
+
+
anyDensity: Boolean value that indicates whether
+ the application can accommodate any screen density.
+
+
resizable: Boolean value that indicates whether
+ the application can expand its layout to fit slightly larger screens.
+
+
+
+
+
+
New {@code <uses-feature>}
+ element lets an application specify hardware (or other)
+ features that it requires to function normally. When an application
+ specifies such features, the system allows the application to be installed only
+ on devices that offer the required features. The element supports these
+ attributes:
+
+
name: The name of the feature required by the application. Currently accepts
+ "android.hardware.camera" and "android.hardware.camera.autofocus" values, which specify that a
+ camera and camera autofocus are required, respectively.
+
glEsVersion: Indicates the minimum version of OpenGL ES required.
maxSdkVersion: This indicates the maximum API Level on which an application is
+ designed to run. If an application declares this attribute, the Android system prevents the user
+ from installing the application if the system's API Level is higher than the value specified in
+ this attribute.
+
targetSdkVersion: This indicates the API Level that the application is targeting.
+ It is able to run on older versions (down to minSdkVersion), but was explicitly tested to
+ work with the version specified here. Specifying this version allows the platform to
+ disable compatibility code that is not required or enable newer features that are not
+ available to older applications.
+
+
+
+
+
+
+
New Permissions
+
+
+
{@link android.Manifest.permission#CHANGE_WIFI_MULTICAST_STATE
+ CHANGE_WIFI_MULTICAST_STATE}: Allows applications to enter Wi-Fi
+ Multicast mode.
+
+
{@link android.Manifest.permission#GLOBAL_SEARCH}: Allows the
+ global search system to access the data of a specified content provider.
+
+
{@link android.Manifest.permission#INSTALL_LOCATION_PROVIDER INSTALL_LOCATION_PROVIDER}:
+ Allows an application to install a location provider into the Location Manager.
+
+
{@link android.Manifest.permission#READ_HISTORY_BOOKMARKS READ_HISTORY_BOOKMARKS}:
+ Allows an application to read (but not write) the user's browsing history
+ and bookmarks.
+
+
{@link android.Manifest.permission#WRITE_HISTORY_BOOKMARKS WRITE_HISTORY_BOOKMARKS}:
+ Allows an application to write (but not read) the user's browsing history
+ and bookmarks.
+
+
{@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE WRITE_EXTERNAL_STORAGE}:
+ Allows an application to write to external storage. Applications using API Level 3
+ and lower will be implicitly granted this permission (and this will be visible to
+ the user); Applications using API Level 4 or higher must explicitly request this
+ permission.
+
+
+
+
+
API differences report
+
+
For a detailed view of API changes in Android {@sdkPlatformVersion} (API Level {@sdkPlatformApiLevel}), as compared to
+the previous version, see the API
+Differences Report.
The Android 2.0 platform introduces many new and exciting features for
+users and developers. This document provides a glimpse at some of the new features
+and technologies in Android 2.0.
Multiple accounts can be added to a device for email and contact
+synchronization, including Exchange accounts. (Handset manufacturers can
+choose whether to include Exchange support in their devices.)
+
Developers can create sync adapters that provide synchronization with
+additional data sources.
+
Quick Contact for Android provides instant access to
+a contact's information and communication modes. For example, a user can tap a
+contact photo and select to call, SMS, or email the person. Other applications
+such as Email, Messaging, and Calendar can also reveal the Quick Contact widget
+when you touch a contact photo or status icon.
+
+
+
+
+
+
Email
+
+
+
Exchange support.
+
Combined inbox to browse email from multiple accounts in one page.
+
+
+
+
Messaging
+
+
+
Search functionality for all saved SMS and MMS messages.
+
Auto delete the oldest messages
+ in a conversation when a defined limit is reached.
+
+
+
+
Camera
+
+
+
Built-in flash support
+
Digital zoom
+
Scene mode
+
White balance
+
Color effect
+
Macro focus
+
+
+
Android virtual keyboard
+
+
+
An improved keyboard layout to makes it easier to hit the correct characters
+ and improve typing speed.
+
The framework's multi-touch support ensures that key presses aren't missed
+ while typing rapidly with two fingers.
+
A smarter dictionary learns from word usage and automatically includes
+ contact names as suggestions.
+
+
+
+
Browser
+
+
+
Refreshed UI with actionable browser URL bar enables users to directly
+ tap the address bar for instant searches and navigation.
+
Bookmarks with web page thumbnails.
+
Support for double-tap zoom.
+
Support for HTML5:
+
+
Database API support, for client-side databases using SQL.
+
Application cache support, for offline applications.
+
Geolocation API support, to provide location information about the device.
+
{@code <video>} tag support in fullscreen mode.
+
+
+
+
+
+
Calendar
+
+
Agenda view provides infinite scrolling.
+
Events indicate the attending status for each invitee.
+
Invite new guests to events.
+
+
+
+
New Platform Technologies
+
+
Media Framework
+
+
Revamped graphics architecture for improved performance that enables better
+hardware acceleration.
+
+
+
Bluetooth
+
+
+
Bluetooth 2.1
+
New BT profiles: Object Push Profile (OPP) and Phone Book Access Profile (PBAP)
+
+
+
+
New Framework APIs
+
+
Android 2.0 includes several new developer APIs.
+For an overview of new APIs, see the
+Android 2.0 version notes.
Android {@sdkPlatformVersion} is a {@sdkPlatformMajorMinor} platform release
+deployable to Android-powered handsets starting in {@sdkPlatformDeployableDate}.
+The release includes new features for users and developers, as well as changes
+in the Android framework API.
+
+
For developers, the Android {@sdkPlatformVersion} platform is available as a
+downloadable component for the Android SDK. The downloadable platform includes a
+fully compliant Android library and system image, as well as a set of emulator
+skins, sample applications, and more. The downloadable platform is fully
+compliant and includes no external libraries.
+
+
To get started developing or testing against the Android
+{@sdkPlatformVersion} platform, use the Android SDK and AVD Manager tool to
+download the platform into your Android 1.6 or later SDK. For more information,
+see Adding SDK
+Components.
The system image included in the downloadable platform provides these
+built-in applications:
+
+
+
+
+
+
Alarm Clock
+
Browser
+
Calculator
+
Camcorder
+
Camera
+
Contacts
+
Custom Locale (developer app)
+
Dev Tools (developer app)
+
Dialer
+
+
+
+
+
Email
+
Gallery
+
Gestures Builder
+
IME for Japanese text input
+
Messaging
+
Music
+
Settings
+
Spare Parts (developer app)
+
+
+
+
+
+
Locales
+
+
The system image included in the downloadable 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).
+
+
+
+
+
+
Chinese, PRC (zh_CN)
+
Chinese, Taiwan (zh_TW)
+
Czech (cs_CZ)
+
Dutch, Netherlands (nl_NL)
+
Dutch, Belgium (nl_BE)
+
English, US (en_US)
+
English, Britain (en_GB)
+
English, Canada (en_CA)
+
English, Australia (en_AU)
+
English, New Zealand (en_NZ)
+
English, Singapore(en_SG)
+
French, France (fr_FR)
+
French, Belgium (fr_BE)
+
+
+
+
French, Canada (fr_CA)
+
French, Switzerland (fr_CH)
+
German, Germany (de_DE)
+
German, Austria (de_AT)
+
German, Switzerland (de_CH)
+
German, Liechtenstein (de_LI)
+
Italian, Italy (it_IT)
+
Italian, Switzerland (it_CH)
+
Japanese (ja_JP)
+
Korean (ko_KR)
+
Polish (pl_PL)
+
Russian (ru_RU)
+
Spanish (es_ES)
+
+
+
+
+
Localized UI strings match the locales that are accessible
+through Settings.
+
+
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:
+
+
+
+ QVGA (240x320, low density, small screen)
+
+
+ WQVGA (240x400, low density, normal screen)
+
+
+ FWQVGA (240x432, low density, normal screen)
+
+
+ HVGA (320x480, medium density, normal screen)
+
+
+ WVGA800 (480x800, high density, normal screen)
+
+
+ WVGA854 (480x854 high density, normal screen)
+
+
+
+
For more information about how to develop an application that displays and functions properly on all Android-powered devices, see Supporting Multiple Screens.
+
+
Developer Features
+
+
The sections below provide information about new developer features offered by the downloadable Android 2.0 platform component.
+
+
Ant Support
+
+
+
Debug- and release-mode application signing. Release-mode signing includes integrated support for zipalign optimization. For more information, see Signing Your Applications.
+
+
Adds new Ant build system with support for Emma instrumentation projects (code coverage).
+
+
+
Framework API
+
+
The sections below provide information about the application framework API provided by the Android {@sdkPlatformVersion} platform.
+
+
+
API level
+
+
The Android {@sdkPlatformVersion} platform delivers an updated version of the framework
+API. As with previous versions, 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 to
+set the proper value, "{@sdkPlatformApiLevel}", in the attributes of the <uses-sdk>
+element in your application's manifest.
+
+
For more information about how to use API Level, see the API Levels document.
+
+
+
API changes summary
+
+
Bluetooth
+
+
Turn on/off Bluetooth
+
Device and service discovery
+
Connect to a remote device using RFCOMM and send/receive data
+
Advertise RFCOMM services and listen for incoming RFCOMM connection
+
+
+
Sync adapters
+
+
New APIs for sync adapters to connect to any backend
+
+
+
Account Manager
+
+
Centralized account manager API to securely store and access auth tokens/passwords
+
+
+
Contacts
+
+
New contacts APIs that allow for data from multiple accounts
+
New Quick Contact framework APIs enable developers to create contact badges in their app. Clicking on the badge opens a window with a list of ways to contact the person with one click.
New parameters for color effect, scene mode, flash mode, focus mode, white balance, rotation, and other settings.
+
New ZoomCallback interface to perform actions when the zoom level has changed.
+
+
+
Media
+
+
MediaScanner now generates thumbnails for all images when they are inserted into MediaStore.
+
New Thumbnail API for retrieving image and video thumbnails on demand.
+
+
+
Other Framework
+
+
New system themes in android.R.style to easily display activities on top of the current system wallpaper or keep the previous activity visible in the background.
+
New WallpaperManager API replaces and extends the wallpaper APIs that were previously in Context, to allow applications to request and set the system wallpaper.
+
New Service APIs to help applications correctly handle Service life-cycle, in particular low memory situations where a Service may be killed while it is running.
+
+
Service.setForeground() has been deprecated and now effectively performs no operation. This is replaced with a new API, startForeground(), that helps (and requires) associating an ongoing notification with the foreground state.
+
+
+
MotionEvent can now report simultaneous-touch information for devices that support it. Up to three pointers can be tracked simultaneously.
+
KeyEvent has new key dispatching APIs, to help implement action-on-up and long press behavior, as well a new mechanism to cancel key presses (for virtual keys).
+
WindowManager.LayoutParams has new constants that allow a window to wake up the screen when it is displayed and show the window even if the screen is locked. This allows applications to more cleanly implement things like alarm clocks that should wake the device.
+
New Intent APIs that broadcast the docking state of the device and allow applications to launch special activities when the device is placed in a desktop or car dock.
+
+
+
Key events executed on key-up
+
+
Android 2.0 is designed to run on devices that use virtual keys for HOME,
+MENU, BACK, and SEARCH, rather than physical keys. To support the best user
+experience on those devices, the Android platform now executes these buttons at
+key-up, for a key-down/key-up pair, rather than key-down. This helps prevent
+accidental button events and lets the user press the button area and then drag
+out of it without generating an event.
+
+
This change in behavior should only affect your application if it is
+intercepting button events and taking an action on key-down, rather than on
+key-up. Especially if your application is intercepting the BACK key, you should
+make sure that your application is handling the key events properly.
+
+
In general, intercepting the BACK key in an application is not recommended,
+however, if your application is doing so and it invokes some action on
+key-down, rather than key-up, you should modify your code.
+
+
If your application will use APIs introduced in Android 2.0 (API Level 5),
+you can take advantage of new APIs for managing key-event pairs:
+
+
+
If you are intercepting the BACK key in an activity or dialog, just
+implement the new {@link android.app.Activity#onBackPressed()} method.
+
If you are intercepting the BACK key in a view, you should track the key
+event on key-down (through the new {@link android.view.KeyEvent#startTracking}
+method), then invoke the action at key up. Here's a pattern you can use:
If you want to update a legacy application so that its handling of the BACK
+key works properly for both Android 2.0 and older platform versions, you
+can use an approach similar to that shown above. Your code can catch the
+target button event on key-down, set a flag to track the key event, and
+then also catch the event on key-up, executing the desired action if the tracking
+flag is set. You'll also want to watch for focus changes and clear the tracking
+flag when gaining/losing focus.
+
+
API differences report
+
+
For a detailed view of API changes in Android {@sdkPlatformVersion} (API Level {@sdkPlatformApiLevel}), as compared to
+the previous version, see the API Differences Report.