diff options
Diffstat (limited to 'docs/html/guide')
35 files changed, 4333 insertions, 629 deletions
diff --git a/docs/html/guide/appendix/api-levels.jd b/docs/html/guide/appendix/api-levels.jd index 8fc899b..cebd2d4 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 +<div id="qv-wrapper"> +<div id="qv"> -<p>The Android <em>API Level</em> 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.</p> - -<p>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 -<code><uses-sdk></code> element inside the Android manifest, like this:</p> - -<pre><uses-sdk android:minSdkVersion="3" /></pre> - -<p>The value for <code>minSdkVersion</code> 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 <code><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></a></code> -documentation for more about declaring the API Level in your manifest.</p> - -<p>For example, the {@link android.appwidget} package was introduced with API Level 3. If your application -has set <code>minSdkVersion</code> 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 <code>minSdkVersion</code> -to 3 or higher. When the <code>minSdkVersion</code> 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.</p> - -<p>Despite the name of the manifest attribute (<code>minSdkVersion</code>), 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 -<a href="#VersionsVsApiLevels">Platform Versions vs. API Levels</a>, below.</p> - -<p class="note"><strong>Note:</strong> 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 <code>minSdkVersion</code>. 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.</p> - -<h2 id="VersionsVsApiLevels">Platform Versions vs. API Levels</h2> - -<p>The following table specifies the <em>maximum</em> API Level supported by each version of the Android platform. -(Every platform is backward-compatible to API Level 1.)</p> + <h2>In this document</h2> +<ol> + <li><a href="intro">What is API Level?</a></li> + <li><a href="#uses">Uses of API Level in Android</a></li> + <li><a href="#considerations">Development Considerations</a> + <ol> + <li><a href="#fc">Application forward compatibility</a></li> + <li><a href="#bc">Application backward compatibility</a></li> + <li><a href="#platform">Selecting a platform version and API Level</a></li> + <li><a href="#apilevel">Declaring a minimum API Level</a></li> + <li><a href="#testing">Testing against higher API Levels</a></li> + </ol> + </li> + <li><a href="#provisional">Using a Provisional API Level</a></li> + <li><a href="#filtering">Filtering the Documentation</a></li> +</ol> + + <h2>See also</h2> + <ol> + <li><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></a> manifest element</li> + </ol> + +</div> +</div> + +<p>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. </p> + +<p>The sections below provide information about API Level and how it affects +your applications. </p> + +<p>For information about how to use the "Filter by API Level" control +available in the API reference documentation, see +<a href="#filtering">Filtering the documentation</a> at the +end of this document. </p> + +<h2 id="intro">What is API Level?</h2> + +<p>API Level is an integer value that uniquely identifies the framework API +revision offered by a version of the Android platform.</p> + +<p>The Android platform provides a framework API that applications can use to +interact with the underlying Android system. The framework API consists of:</p> + +<ul> +<li>A core set of packages and classes</li> +<li>A set of XML elements and attributes for declaring a manifest file</li> +<li>A set of XML elements and attributes for declaring and accessing resources</li> +<li>A set of Intents</li> +<li>A set of permissions that applications can request, as well as permission +enforcements included in the system</li> +</ul> + +<p>Each successive version of the Android platform can include updates to the +Android application framework API that it delivers. </p> + +<p>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.</p> + +<p>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.</p> + +<p>The following table specifies the API Level supported by each version of the +Android platform.</p> <table> <tr><th>Platform Version</th><th>API Level</th></tr> - <tr><td>Android 1.0</td><td>1</td></tr> - <tr><td>Android 1.1</td><td>2</td></tr> + <tr><td>Android 2.0</td><td>5</td></tr> + <tr><td>Android 1.6</td><td>4</td></tr> <tr><td>Android 1.5</td><td>3</td></tr> - <tr><td>Android Donut</td><td>Donut</td></tr> + <tr><td>Android 1.1</td><td>2</td></tr> + <tr><td>Android 1.0</td><td>1</td></tr> </table> -<h2 id="ViewingTheApiReference">Viewing the API Reference Based on API Level</h2> +<h2 id="uses">Uses of API Level in Android</h2> + +<p>The API Level identifier serves a key role in ensuring the best possible +experience for users and application developers: + +<ul> +<li>It lets the Android platform describe the maximum framework API revision +that it supports</li> +<li>It lets applications describe the framework API revision that they +require</li> +<li>It lets the system negotiate the installation of applications on the user's +device, such that version-incompatible applications are not installed.</li> +</ul> + +<p>Each Android platform version stores its API Level identifier internally, in +the Android system itself. </p> + +<p>Applications can use a manifest element provided by the framework API — +<code><uses-sdk></code> — 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:</p> + +<ul> +<li><code>android:minSdkVersion</code> — Specifies the minimum API Level +on which the application is able to run. The default value is "1".</li> +<li><code>android:targetSdkVersion</code> — 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.</li> +<li><code>android:maxSdkVersion</code> — Specifies the maximum API Level +on which the application is able to run.</li> +</ul> + +<p>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 +<code><uses-sdk></code> element with a <code>android:minSdkVersion</code> +attribute. The value of <code>android:minSdkVersion</code> would be the integer +corresponding to the API Level of the earliest version of the Android platform +under which the application can run. </p> + +<p>When the user attempts to install an application, the Android system first +checks the <code><uses-sdk></code> 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:</p> + +<ul> +<li>If a <code>android:minSdkVersion</code> 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. </li> +<li>If a <code>android:maxSdkVersion</code> 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. </li> +</ul> + +<p>When declared in an application's manifest, a <code><uses-sdk></code> +element might look like this: </p> + +<pre><manifest> + ... + <uses-sdk android:minSdkVersion="5" /> + ... +</manifest></pre> + +<p>The principal reason that an application would declare an API Level in +<code>android:minSdkVersion</code> is to tell the Android system that it is +using APIs that were <em>introduced</em> 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.</p> + +<p>For example, the {@link android.appwidget} package was introduced with API +Level 3. If an application uses that API, it must declare a +<code>android:minSdkVersion</code> 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).</p> + +<p>For more information about how to specify an application's API Level +requirements, see the <a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code><uses-sdk></code></a> + section of the manifest file documentation.</p> + + +<h2 id="considerations">Development Considerations</h2> + +<p>The sections below provide information related to API level that you should +consider when developing your application.</p> + +<h3 id="fc">Application forward compatibility</h3> + +<p>Android applications are generally forward-compatible with new versions of +the Android platform.</p> + +<p>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. </p> + +<p>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. </p> + +<p>In some cases, changes <em>below</em> 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. </p> + +<h3 id="bc">Application backward compatibility</h3> + +<p>Android applications are not necessarily backward compatible with versions of +the Android platform older than the version against which they were compiled. +</p> + +<p>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.</p> + +<p>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. </p> + +<h3 id="platform">Selecting a platform version and API Level</h3> + +<p>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. + +<p>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 +<code>android:minSdkVersion</code> attribute in the application's manifest and +set its value to the API Level of the platform version. </p> + +<h3 id="apilevel">Declaring a minimum API Level</h3> + +<p>If you build an application that uses APIs or system features introduced in +the latest platform version, you should set the +<code>android:minSdkVersion</code> 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. </p> + +<p>If your application uses APIs introduced in the latest platform version but +does <em>not</em> declare a <code>android:minSdkVersion</code> attribute, then +it will run properly on devices running the latest version of the platform, but +<em>not</em> 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.</p> + +<h3 id="testing">Testing against higher API Levels</h3> + +<p>After compiling your application, you should make sure to test it on the +platform specified in the application's <code>android:minSdkVersion</code> +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. </p> + +<p>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. </p> + +<p>To access the updater, use the <code>android</code> command-line tool, +located in the <sdk>/tools directory. You can launch the Updater by using +the <code>android</code> 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 +<strong>Window</strong> > <strong>Android SDK and AVD +Manager</strong>.</p> + +<p>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 <a +href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a>. 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. </p> + + +<h2 id="provisional">Using a Provisional API Level</h2> + +<p>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 <em>provisional API Level</em> 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.</p> + +<p>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.</p> + +<p>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.</p> + + +<h2 id="filtering">Filtering the Reference Documentation by API Level</h2> -<p>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.</p> +<p>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 <code>android:minSdkVersion</code> attribute of its manifest file. </p> -<p>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.</p> +<p>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. </p> +<p>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.</p> +<p>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. +</p> +<p>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. </p> diff --git a/docs/html/guide/appendix/faq/commontasks.jd b/docs/html/guide/appendix/faq/commontasks.jd index 0f89e75..e88a867 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</a> to understand the basics of how an Android application works.</p> <p>You should also take a look at the ApiDemos application and the other sample -applications included in the SDK, in the <code><sdk>/samples/ +applications included in the SDK, in the <code><sdk>/samples/</code> folder in the SDK.</p> <p>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){ <pre>//Hide the title bar requestWindowFeature(Window.FEATURE_NO_TITLE); </pre> +<p>A better way to achieve the same end is to specify a theme in your Android +Manifest file:</p> +<pre><application android:icon="@drawable/icon" android:theme="@android:style/Theme.NoTitleBar"> +</pre> +<p>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 <code>onCreate</code> runs.</p> +<p>(Note that this can be applied to either the <code><application></code> +tag or to individual <code><activity></code> tags.)</p> <a name="localhostalias" id="localhostalias"></a><h2>Referring to localhost from the emulated environment</h2> <p> If you need to refer to your host computer's <em>localhost</em>, such as when you @@ -427,7 +436,7 @@ user receiving new e-mail.</p> <td>Activity</td> <td>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 5a2a751..8fa4cec 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 <li><a href="#dev-phone-1">Android Dev Phone 1</a></li> </ol> </li> - <li><a href="#setting-up">Setting up a Device for Development</a></li> - <li><a href="#WinUsbDriver">Installing the WinUsb Driver</a></li> + <li><a href="#setting-up">Setting up a Device for Development</a> + <ol> + <li><a href="#VendorIds">USB Vendor IDs</a></li> + </ol> + </li> + </ol> + <h2>See also</h2> + <ol> + <li><a + href="{@docRoot}sdk/win-usb.html">USB Driver for Windows</a></li> </ol> </div> </div> @@ -117,27 +125,36 @@ would on the emulator. There are just a few things to do before you can start.</ <li>Turn on "USB Debugging" on your device. <p>On the device, go to the home screen, press <b>MENU</b>, select <b>Applications</b> > <b>Development</b>, then enable <b>USB debugging</b>.</p> - </li> <li>Setup your system to detect your device. <ul> - <li>If you're developing on Windows, you need to install a USB driver for adb. - Follow the steps below for <a href="#WinUsbDriver">Installing the WinUsb Driver</a>.</li> + <li>If you're developing on Windows, you need to install a USB driver + for adb. See the <a href="{@docRoot}sdk/win-usb.html">Windows USB + Driver</a> documentation.</li> <li>If you're developing on Mac OS X, it just works. Skip this step.</li> - <li>If you're developing on Ubuntu Linux, you need to add a rules file: + <li>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 +<code>SYSFS{idVendor}</code> property. For other IDs, see the table of <a +href="#VendorIds">USB Vendor IDs</a>, below. <ol> - <li>Login as root and create this file: <code>/etc/udev/rules.d/51-android.rules</code>. - <p>For Gusty/Hardy, edit the file to read: <br/> - <code>SUBSYSTEM=="usb", SYSFS{idVendor}=="0bb4", MODE="0666"</code></p> - - <p>For Dapper, edit the file to read: <br/> - <code>SUBSYSTEM=="usb_device", SYSFS{idVendor}=="0bb4", MODE="0666"</code></p> + <li>Log in as root and create this file: + <code>/etc/udev/rules.d/51-android.rules</code>. + <p>For Gusty/Hardy, edit the file to read:<br/> + <code>SUBSYSTEM=="usb", SYSFS{idVendor}=="0bb4", + MODE="0666"</code></p> + + <p>For Dapper, edit the file to read:<br/> + <code>SUBSYSTEM=="usb_device", SYSFS{idVendor}=="0bb4", + MODE="0666"</code></p> </li> <li>Now execute:<br/> - <code>chmod a+rx /etc/udev/rules.d/51-android.rules</code> + <code>chmod a+r /etc/udev/rules.d/51-android.rules</code> </li> </ol> - </li> </ul> </li> @@ -149,157 +166,30 @@ with a <b>Device Chooser</b> dialog that lists the available emulator(s) and con Select the device to install and run the application there.</p> <p>If using the <a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a> (adb), -you can issue commands with the <code>-d</code> flag to target your connected device.</p> - - - - -<h2 id="WinUsbDriver">Installing the WinUsb Driver</h2> - -<p>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 <code><em><sdk></em>\usb_driver\</code> -folder of your SDK package.</p> - -<p class="note"><strong>Note:</strong> 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." </p> - -<p>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 <code>C:\Android\Windows\USB\install\</code> 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.</p> - -<ol class="nolist"> - <li>Windows Vista: - <ol class="nolist"> - <li><a href="#VistaFreshInstall">Perform a fresh installation</a></li> - <li><a href="#VistaUprade">Upgrade an existing driver</a></li> - </ol> - </li> - <li>Windows XP: - <ol class="nolist"> - <li><a href="#XPFreshInstall">Perform a fresh installation</a></li> - <li><a href="#XPUpgrade">Upgrade an existing driver</a></li> - </ol> - </li> -</ol> - - -<p class="caution"><strong>Caution:</strong> -You may make changes to <code>android_winusb.inf</code> file found inside <code>usb_driver\</code> -(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.</p> - -<h3 id="VistaFreshInstall">Windows Vista: Perform a fresh installation</h3> - -<p>To install the Android USB driver on Windows Vista for the first time:</p> - -<ol> - <li>Connect your Android-powered device to your computer's USB port. Windows will detect the device - and launch the Found New Hardware wizard.</li> - <li>Select "Locate and install driver software."</li> - <li>Select "Don't search online."</li> - <li>Select "I don't have the disk. Show me other options."</li> - <li>Select "Browse my computer for driver software."</li> - <li>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.</li> - <li>Click "Next." Vista may prompt you to confirm the privilege elevation required for driver - installation. Confirm it.</li> - <li>When Vista asks if you'd like to install the Google ADB Interface device, click "Install" - to install the driver.</li> -</ol> - -<p>Return to <a href="#setting-up">Setting up a Device for Development</a>.</p> - - - -<h3 id="VistaUpgrade">Windows Vista: Upgrade an existing driver</h3> - -<p>To upgrade an existing Android USB driver on Windows Vista with the new one:</p> - -<ol> - <li>Connect your Android-powered device to your computer's USB port.</li> - <li>Right-click on "Computer" from your desktop or Windows Explorer, - and select "Manage."</li> - <li>Select "Device Manager" in the left pane of the Computer Management window.</li> - <li>Locate and expand "ADB Interface" in the right pane.</li> - <li>Right-click on "HTC Dream Composite ADB Interface", and select "Update Driver Software..."</li> - <li>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."</li> - <li>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.</li> - <li>Click "Next." Vista may prompt you to confirm the privilege elevation required for driver - installation. Confirm it.</li> - <li>When Vista asks if you'd like to install the Google ADB Interface device, click "Install" - to install the driver.</li> -</ol> - -<p>Return to <a href="#setting-up">Setting up a Device for Development</a>.</p> - - - -<h3 id="XPFreshInstall">Windows XP: Perform a fresh installation</h3> - -<p>To install the Android USB driver on Windows XP for the first time:</p> - -<ol> - <li>Connect your Android-powered device to your computer's USB port. Windows - will detect the device and launch the Hardware Update Wizard.</li> - <li>Select "Install from a list or specific location" and click - "Next."</li> - <li>Select "Search for the best driver in these locations"; uncheck "Search - removable media"; and check "Include this location in the search."</li> - <li>Click "Browse..." and locate the folder where you copied the installation - package.</li> - <li>Click "Next" to install the driver.</li> -</ol> - -<p>Return to <a href="#setting-up">Setting up a Device for Development</a>.</p> - - - -<h3 id="XPUpgrade">Windows XP: Upgrade an existing driver</h3> - -<p>To upgrade an existing Android USB driver on Windows XP with the new one:</p> - -<ol> - <li>Connect your Android-powered device to your computer's USB port.</li> - <li>Right-click on "My Computer" from your desktop or Windows Explorer, - and select "Manage."</li> - <li>Select "Device Manager" in the left pane of the Computer Management window.</li> - <li>Locate and expand "Android Phone" in the right pane.</li> - <li>Right-click "Android Composite ADB Interface" and select "Update Driver..." - This will launch the Hardware Update Wizard.</li> - <li>Select "Install from a list or specific location" and click - "Next."</li> - <li>Select "Search for the best driver in these locations"; uncheck "Search - removable media"; and check "Include this location in the search."</li> - <li>Click "Browse..." and locate the folder where you copied the installation - package.</li> - <li>Click "Next" to install the driver.</li> -</ol> - -<p>Return to <a href="#setting-up">Setting up a Device for Development</a>.</p> - - - - - - - - - - - - - - +you can issue commands with the <code>-d</code> flag to target your +connected device.</p> + + +<h3 id="VendorIds">USB Vendor IDs</h3> +<p>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 +<code>SYSFS{idVendor}</code> property in the rules file.</p> +<table> + <tr> + <th>Manufacturer</th><th>USB Vendor ID</th></tr> + <tr> + <td>Acer</td><td>0502</td></tr> + <tr> + <td>HTC</td><td>0bb4</td></tr> + <tr> + <td>Huawei</td><td>12d1</td></tr> + <tr> + <td>LG</td><td>1004</td></tr> + <tr> + <td>Motorola</td><td>22b8</td></tr> + <tr> + <td>Samsung</td><td>04e8</td></tr> + <tr> + <td>Sony Ericsson</td><td>0fce</td></tr> +</table> diff --git a/docs/html/guide/developing/eclipse-adt.jd b/docs/html/guide/developing/eclipse-adt.jd index a5cf735..667aa9f 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.</li> <p>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 <a href="{@docRoot}sdk/{@sdkCurrent}/installing.html#installingplugin">Installing +steps given in <a href="{@docRoot}sdk/eclipse-adt.html#installing">Installing the ADT Plugin</a>.</p> <p>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 -<a href="{@docRoot}sdk/{@sdkCurrent}/upgrading.html#UpdateAdt">Updating Your Eclipse ADT Plugin</a>.</p> +<a href="{@docRoot}sdk/eclipse-adt.html#updating">Updating Your ADT Plugin</a>.</p> <p class="note"><strong>Note:</strong> 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.</p> <h3 id="CreatingAnAvd">Creating an AVD</h3> -<p>With ADT 0.9.2 and above, the Android AVD Manager provides a simple graphical interface +<p>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 <code>android</code> tool to create your AVDs—read the AVD guide to <a href="{@docRoot}guide/developing/tools/avd.html#creating">Creating an AVD</a>.) -<p>To create an AVD with the Android AVD Manager:</p> +<p>To create an AVD with the AVD Manager:</p> <ol> - <li>Select <strong>Window > Android AVD Manager</strong>, or click the Android AVD Manager icon (a black device) + <li>Select <strong>Window > Android SDK and AVD Manager</strong>, or click the Android SDK and AVD Manager icon (a black device) in the Eclipse toolbar.</p> </li> <li>In the Virtual Devices panel, you'll see a list of existing AVDs. Click <strong>New</strong> @@ -169,7 +169,7 @@ use the <code>android</code> tool to create your AVDs—read the AVD guide t <li>Click <strong>Create AVD</strong>.</li> </ol> -<p>Your AVD is now ready and you can close the Android AVD Manager. +<p>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.</p> @@ -217,7 +217,7 @@ to start, the emulator options to use, and so on. When you first run a project as an <em>Android Application</em>, 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.</p> <p>To create or modify a launch configuration, follow these steps as appropriate @@ -256,6 +256,12 @@ for your Eclipse version:</p> when selecting an AVD to run your application. See the following section on <a href=#AutoAndManualModes">Automatic and manual target modes</a>).</p> + <p>You can specify any emulator options to the Additional Emulator Command + Line Options field. For example, you could add <code>-scale 96dpi</code> 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 <a + href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a> +document.</p> </li> </ol> diff --git a/docs/html/guide/developing/other-ide.jd b/docs/html/guide/developing/other-ide.jd index 8cdf0b9..2080873 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.</p> navigate to the <code>tools/</code> directory of your SDK and run:</p> <pre> android create project \ ---target <em><targetID></em> \ +--target <em><target_ID></em> \ +--name <em><your_project_name></em> \ --path <em>/path/to/your/project</em> \ --activity <em><your_activity_name></em> \ --package <em><your_package_namespace></em> @@ -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: <code>android list targets</code>.</li> + <li><code>name</code> 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.</li> <li><code>path</code> is the location of your project directory. If the directory does not exist, it will be created for you.</li> - <li><code>activity</code> is the name for your {@link android.app.Activity} class. This class file + <li><code>activity</code> is the name for your default {@link android.app.Activity} class. This class file will be created for you inside - <code><em><path_to_your_project></em>/src/<em><your_package_namespace_path></em>/</code>.</li> + <code><em><path_to_your_project></em>/src/<em><your_package_namespace_path></em>/</code>. + This will also be used for your .apk filename unless you provide a the <code>name</code>.</li> <li><code>package</code> is the package namespace for your project, following the same rules as for packages in the Java programming language.</li> </ul> @@ -109,9 +113,10 @@ android create project \ <pre> android create project \ --target 1 \ ---path ./myProject \ ---activity MyActivity \ ---package com.example.myproject +--name MyAndroidApp \ +--path ./MyAndroidAppProject \ +--activity MyAndroidAppActivity \ +--package com.example.myandroid </pre> <p>The tool generates the following files and directories:</p> @@ -123,7 +128,8 @@ android create project \ <li><code>default.properties</code> - Properties for the build system. <em>Do not modify this file</em>.</li> <li><code>build.properties</code> - Customizable properties for the build system. You can edit this - file to overried default build settings used by Ant.</li> + 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.</li> <li><code>src<em>/your/package/namespace/ActivityName</em>.java</code> - The Activity class you specified during project creation.</li> <li><code>bin/</code> - Output directory for the build script.</li> @@ -141,7 +147,7 @@ that you must use the <a href="{@docRoot}guide/developing/tools/adb.html">Androi to the emulator (discussed later). So you need access between your project solution and the <code>tools/</code> folder.</p> -<p class="warning"><strong>Note:</strong> You should refrain from moving the +<p class="caution"><strong>Caution:</strong> You should refrain from moving the location of the SDK directory, because this will break the build scripts. (They will need to be manually updated to reflect the new SDK location before they will work again.)</p> @@ -153,14 +159,15 @@ work again.)</p> a new project from existing code, use the <code>android update project</code> command to update the project to the new development environment. You can also use this command to revise the build target of an existing project -(with the <code>--target</code> option). The <code>android</code> tool will generate any files and +(with the <code>--target</code> option) and the project name (with the <code>--name</code> +option). The <code>android</code> tool will generate any files and folders (listed in the previous section) that are either missing or need to be updated, as needed for the Android project.</p> <p>To update an existing Android project, open a command-line and navigate to the <code>tools/</code> directory of your SDK. Now run:</p> <pre> -android update project --target <em><targetID></em> --path <em>path/to/your/project/</em> +android update project --name <em><project_name></em> --target <em><target_ID></em> --path <em>path/to/your/project/</em> </pre> <ul> @@ -169,11 +176,13 @@ android update project --target <em><targetID></em> --path <em>path/to/you like to build your project against. To see a list of available targets and their corresponding IDs, execute: <code>android list targets</code>.</li> <li><code>path</code> is the location of your project directory.</li> + <li><code>name</code> is the name for the project. This is optional—if you're not + changing the project name, you don't need this.</li> </ul> <p>Here's an example:</p> <pre> -android update project --target 2 --path ./myProject +android update project --name MyApp --target 2 --path ./MyAppProject </pre> @@ -237,8 +246,9 @@ install JDK in a non-space directory, for example: <code>c:\java\jdk1.6.0_02</co <h3 id="DebugMode">Building in debug mode</h3> <p>For immediate application testing and debugging, you can build your application -in debug mode and immediately install it on an emulator. In debug mode, the build tools automatically -sign your application with a debug key. However, you can (and should) also test your +in debug mode and immediately install it on an emulator. In debug mode, the build tools +automatically sign your application with a debug key and optimize the package with +{@code zipalign}. However, you can (and should) also test your application in release mode. Debug mode simply allows you to run your application without manually signing the application.</p> @@ -248,9 +258,9 @@ manually signing the application.</p> <li>Open a command-line and navigate to the root of your project directory.</li> <li>Use Ant to compile your project in debug mode: <pre>ant debug</pre> - <p>This creates your Android application .apk file inside the project <code>bin/</code> - directory, named <code><em><your_DefaultActivity_name></em>-debug.apk</code>. The file - is already signed with the debug key.</p> + <p>This creates your debug .apk file inside the project <code>bin/</code> + directory, named <code><em><your_project_name></em>-debug.apk</code>. The file + is already signed with the debug key and has been aligned with {@code zipalign}.</p> </li> </ol> @@ -267,23 +277,86 @@ about <a href="#Running">Running Your Application</a>.</p> your application in release mode. Once you have built in release mode, it's a good idea to perform additional testing and debugging with the final .apk.</p> -<p>To build in release mode:</p> +<p>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.</p> + +<h4 id="ManualReleaseMode">Build unsigned</h4> + +<p>If you build your application <em>unsigned</em>, then you will need to +manually sign and align the package.</p> + +<p>To build an <em>unsigned</em> .apk in release mode:</p> <ol> <li>Open a command-line and navigate to the root of your project directory.</li> <li>Use Ant to compile your project in release mode: <pre>ant release</pre> - <p>This creates your Android application .apk file inside the project <code>bin/</code> - directory, named <code><em><your_DefaultActivity_name></em>.apk</code>.</p> - <p class="note"><strong>Note:</strong> The .apk file is <em>unsigned</em> at this point. - You can't install it on an emulator or device until you sign it with your private key.</p> </li> </ol> -<p>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, +<p>This creates your Android application .apk file inside the project <code>bin/</code> +directory, named <code><em><your_project_name></em>-unsigned.apk</code>.</p> + +<p class="note"><strong>Note:</strong> The .apk file is <em>unsigned</em> at this point +and can't be installed until signed with your private key.</p> + +<p>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 <a href="{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a>.</p> +<p>When your .apk has been signed and aligned, it's ready to be distributed to end-users.</p> + +<h4 id="AutoReleaseMode">Build signed and aligned</h4> + +<p>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.</p> + +<p class="caution"><strong>Caution:</strong> Due to the way Ant handles input, the password that +you enter during the build process <strong>will be visible</strong>. 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, <a href="#ManualReleaseMode">buid unsigned</a> and then continue +with <a href="{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a>.</p> + +<p>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:</p> + +<pre> +key.store=/path/to/my.keystore +key.alias=mykeystore +</pre> + +<p>Save your changes. Now you can build a <em>signed</em> .apk in release mode:</p> + +<ol> + <li>Open a command-line and navigate to the root of your project directory.</li> + <li>Use Ant to compile your project in release mode: + <pre>ant release</pre> + </li> + <li>When prompted, enter you keystore and alias passwords. + <p class="caution"><strong>Caution:</strong> As described above, + your password will be visible on the screen.</p> + </li> +</ol> + +<p>This creates your Android application .apk file inside the project <code>bin/</code> +directory, named <code><em><your_project_name></em>-release.apk</code>. +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.</p> + + +<h4>Once built and signed in release mode</h4> + <p>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 <a href="#Running">Running Your Application</a>. @@ -329,7 +402,7 @@ id:2 you'll use this in the next step.</p> </li> <li>Create a new AVD using your selected deployment target: - <pre>android create avd --name <em><your_avd_name></em> --target <em><targetID></em></pre> + <pre>android create avd --name <em><your_avd_name></em> --target <em><target_ID></em></pre> <li>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 b111047..e8c726f 100644 --- a/docs/html/guide/developing/tools/adb.jd +++ b/docs/html/guide/developing/tools/adb.jd @@ -313,7 +313,7 @@ emulator-5558 device</pre> <li><code><tty></code> — the tty for PPP stream. For example <code>dev:/dev/omap_csmi_ttyl</code>. </li> <li><code>[parm]... </code> &mdash zero or more PPP/PPPD options, such as <code>defaultroute</code>, <code>local</code>, <code>notty</code>, etc.</li></ul> -<p>Note that you should not automatically start a PDP connection. </p></td> +<p>Note that you should not automatically start a PPP connection. </p></td> <td></td> </tr> diff --git a/docs/html/guide/developing/tools/aidl.jd b/docs/html/guide/developing/tools/aidl.jd index f370a80..abfa8b1 100644 --- a/docs/html/guide/developing/tools/aidl.jd +++ b/docs/html/guide/developing/tools/aidl.jd @@ -194,7 +194,6 @@ started.</p> <li>Make your class implement the {@link android.os.Parcelable} interface.</li> <li>Implement the method <code>public void writeToParcel(Parcel out)</code> that takes the current state of the object and writes it to a parcel.</li> -<li>Implement the method <code>public void readFromParcel(Parcel in)</code> that reads the value in a parcel into your object.</li> <li>Add a static field called <code>CREATOR</code> to your class which is an object implementing the {@link android.os.Parcelable.Creator Parcelable.Creator} interface.</li> diff --git a/docs/html/guide/developing/tools/avd.jd b/docs/html/guide/developing/tools/avd.jd index b8f205e..06b1245 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. <li>You create AVD configurations to model different device environments in the Android emulator.</li> + <li>The <code>android</code> tool offers a graphical Android AVD + Manager and a command-line interface for creating AVDs.</li> </ul> <h2>In this document</h2> <ol> @@ -72,9 +74,18 @@ reference of emulator options, please see the <a href="{@docRoot}guide/developing/tools/emulator.html">Emulator</a> documentation. </p> -<p>To create and manage AVDs, you use the android tool provided in the Android -SDK. For more information about how to work with AVDs from inside -your development environment, see <a +<p>To create and manage AVDs, you use the <code>android</code> tool provided in +the <code>tools/</code> directory of the Android SDK. The tool provides both a +graphical AVD manager and a command-line interface that you can use to +create AVDs. To access the graphical AVD manager, run the +<code>android</code> tool without options. The sections below describe how to +use the <code>android</code> command-line interface to create and manage AVDs. +Note that some functionality, such as the capability to create an AVD with a +custom hardware configuration, are only available through the command-line +interface. </p> + +<p>For more information about how to work with AVDs from inside your development +environment, see <a href="{@docRoot}guide/developing/eclipse-adt.html">Developing in Eclipse with ADT</a> or <a href="{@docRoot}guide/developing/other-ide.html">Developing in Other IDEs</a>, as appropriate for your environment.</p> @@ -89,11 +100,11 @@ you need to create an AVD before you can run any application in the emulator </div> </div> -<p>To create an AVD, you use the android tool, a command-line utility -available in the <code><sdk>/tools/</code> 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 -<code><sdk>/tools/</code> directory, if needed</p> +<p>To create an AVD, you use the <code>android</code> tool, a command-line +utility available in the <code><sdk>/tools/</code> directory. Managing +AVDs is one of the two main function of the <code>android</code> tool (the other +is creating and updating Android projects). Open a terminal window and change to +the <code><sdk>/tools/</code> directory, if needed</p> <p>To create each AVD, you issue the command <code>android create avd</code>, 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 <code>-t</code> argument.<p> <p>To specify the system image to use, you refer to its <em>target ID</em> -— 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 -<em>before</em> you run the <code>android create avd</code> command. +— an integer — as assigned by the <code>android</code> 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 <code>android</code> tool list the +available system images and the target ID of each, as described in the next +section. You should do this <em>before</em> you run the <code>android create +avd</code> command. </p> <h3 id="listingtargets">Listing targets</h3> @@ -131,7 +143,7 @@ target ID of each, as described in the next section. You should do this <pre>android list targets</pre> -<p>The android tool scans the <code><sdk>/platforms</code> and +<p>The <code>android</code> tool scans the <code><sdk>/platforms</code> and <code><sdk>/add-ons</code> directories looking for valid system images and then generates the list of targets. Here's an example of the command output: </p> @@ -199,24 +211,22 @@ system image in the list above): </p> <pre>android create avd -n my_android1.5 -t 2</pre> <p>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. </p> - +platform"), the <code>android</code> tool next asks you whether you want to +create a custom hardware profile. </p> <pre>Android 1.5 is a basic Android platform. Do you wish to create a custom hardware profile [no]</pre> <p>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 <code>android</code> tool creates the AVD with name and system image mapping you requested, with the options you specified. -<p class="note">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. </p> - +<p class="note">If you are creating an AVD whose target is an SDK add-on, the +<code>android</code> 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. </p> <p>For a list of options you can use in the <code>android create avd</code> command, see the table in <a href="#options">Command-line options for AVDs</a>, at the bottom of @@ -225,11 +235,11 @@ this page. </p> <h3 id="hardwareopts">Setting hardware emulation options</h3> <p>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). </p> - +platform"), the <code>android</code> 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). </p> <table> <tr> @@ -249,7 +259,6 @@ configuration file (the config.ini file in the AVD's local directory). </p> <td>Whether there is a touch screen or not on the device. Default value is "yes".</td> <td>hw.touchScreen - <tr> <td>Trackball support </td> <td>Whether there is a trackball on the device. Default value is "yes".</td> @@ -339,23 +348,30 @@ configuration file (the config.ini file in the AVD's local directory). </p> <td>Default value is "66MB".</td> <td>disk.cachePartition.size </td> </tr> + +<tr> +<td>Abstracted LCD density</td> +<td>Sets the generalized density characteristic used by the AVD's screen. Default value is "160".</td> +<td>hw.lcd.density </td> +</tr> + </table> <h3 id="location">Default location of the AVD files</h3> -<p>When you create an AVD, the android tool creates a dedicated directory for it +<p>When you create an AVD, the <code>android</code> 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. </p> -<p>The android tool also creates a <AVD name>.ini file for the AVD at the +<p>The <code>android</code> 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.</p> -<p>By default, the android tool creates the AVD directory inside +<p>By default, the <code>android</code> tool creates the AVD directory inside <code>~/.android/avd/</code> (on Linux/Mac), <code>C:\Documents and Settings\<user>\.android\</code> on Windows XP, and <code>C:\Users\<user>\.android\</code> on Windows Vista. @@ -396,18 +412,18 @@ Error: Invalid value in image.sysdir. Run 'android update avd -n foo' </pre> <h3 id="deleting">Deleting an AVD</h3> -<p>You can use the android tool to delete an AVD. Here is the command usage:</p> +<p>You can use the <code>android</code> tool to delete an AVD. Here is the command usage:</p> <pre>android delete avd -n <name> </pre> -<p>When you issue the command, the android tool looks for an AVD matching the +<p>When you issue the command, the <code>android</code> tool looks for an AVD matching the specified name deletes the AVD's directory and files. </p> <h2 id="options">Command-line options for AVDs</h2> <p>The table below lists the command-line options you can use with the -android tool. </p> +<code>android</code> tool. </p> <table> @@ -448,9 +464,9 @@ android tool. </p> <td><code>-f</code></td> <td>Force creation of the AVD</td> <td>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 <code>android</code> tool will not create the new AVD or overwrite the existing AVD. If you specify the <code>-f</code> option, however, the - android tool will automatically overwrite any existing AVD that has the + <code>android</code> 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. </td> </tr> @@ -465,7 +481,7 @@ files.</td> <td><code>-s <name></code> or <br> <code>-s <width>-<height></code> </td> <td>The skin to use for this AVD, identified by name or dimensions.</td> - <td>The android tool scans for a matching skin by name or dimension in the + <td>The <code>android</code> tool scans for a matching skin by name or dimension in the <code>skins/</code> directory of the target referenced in the <code>-t <targetID></code> argument. Example: <code>-s HVGA-L</code></td> </tr> diff --git a/docs/html/guide/developing/tools/ddms.jd b/docs/html/guide/developing/tools/ddms.jd index fa04216..f55940d 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 -<p>Android ships with a debugging tool called the Dalvik Debug Monitor Service (DDMS), +<p>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.</p> </ul> </li> <li> <strong>utime</strong> - cumulative time spent executing user code, in "jiffies" (usually - 10ms). Only available under Linux. </li> + 10ms). </li> <li> <strong>stime</strong> - cumulative time spent executing system code, in "jiffies" (usually 10ms). </li> <li> <strong>Name</strong> - the name of the thread</li> @@ -214,14 +214,15 @@ the emulator from command line, be sure to mount the sdcard again.)</p> <h2 id="screen-capture">Screen Capture</h2> <p>You can capture screen images on the device or emulator by selecting <strong>Device</strong> - > <strong>Screen capture...</strong> in the menu bar, or press CTRL-S.</p> + > <strong>Screen capture...</strong> in the menu bar, or press CTRL-S. + Be sure to select a device first.</p> <h2 id="exploring-processes">Exploring Processes</h2> <p>You can see the output of <code>ps -x</code> for a specific VM by selecting <strong>Device</strong> > <strong>Show process status</strong>... in the menu bar.</p> <h2 id="cause-a-gc-to-occur">Cause a GC to Occur</h2> -<p>Cause garbage collection to occury by pressing the trash can button on the toolbar. </p> +<p>Cause garbage collection to occur in the selected application by pressing the trash can button on the toolbar. </p> <h2 id="running-dumpsys-and-dumpstate">Running Dumpsys and Dumpstate on the Device (logcat)<a name="logcat" id="logcat"></a> </h2> <ul> @@ -239,7 +240,7 @@ the emulator from command line, be sure to mount the sdcard again.)</p> <h2 id="stop-a-vitrual-machine">Stop a Virtual Machine </h2> <p>You can stop a virtual machine by selecting <strong>Actions</strong> > <strong>Halt -VM</strong>. Pressing this button causes the VM to call <code>System.exit(1)</code>.</p> +VM</strong>. Pressing this button causes the VM to call <code>Runtime.halt(1)</code>.</p> <h2 id="known-issues" style="color:#FF0000">Known issues with DDMS </h2> <p>DDMS has the following known limitations:</p> diff --git a/docs/html/guide/developing/tools/emulator.jd b/docs/html/guide/developing/tools/emulator.jd index 82d3c8d..a9b6914 100644 --- a/docs/html/guide/developing/tools/emulator.jd +++ b/docs/html/guide/developing/tools/emulator.jd @@ -1,7 +1,7 @@ page.title=Android Emulator @jd:body -<img src="{@docRoot}images/emulator-hvga-p.png" alt="Image of the Android Emulator" width="271" height="524" style="margin-left:0em;margin-top:-4em;float:right;"/> +<div style="padding:1em;"><img src="/images/emulator-wvga800l.png" alt="Image of the Android Emulator" width="367" height="349" style="margin-left:2em;margin-top:-4em;float:right;"/></div> <p>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.</p> -<div class="inline-toc" style="whitespace:nowrap;"> -<h4>In this document:</h4> -<div class="g-unit g-first" style="whitespace:nowrap;width:35%;"> +<table> +<tr> +<td colspan="2" style="border:0;"><strong>In this document:</strong></td> +</tr> +<tr> +<td style="border:0;"> + <ol class="toc"> <li><a href="#overview">Overview</a></li> <li><a href="#starting">Starting and Stopping the Emulator</a></li> @@ -53,9 +57,9 @@ on the data channel.</p> <li><a href="#calling">Sending a Voice Call or SMS to Another Emulator Instance</a></li> </ol></li> </ol> -</div> +</td> -<div class="g-unit" style="whitespace:nowrap;"> +<td style="border:0;"> <ol class="toc"> <li><a href="#console">Using the Emulator Console</a> <ol class="toc"> @@ -85,9 +89,9 @@ on the data channel.</p> <li><a href="#troubleshooting">Troubleshooting Emulator Problems</a></li> <li><a href="#limitations">Emulator Limitations</a></li> </ol> -</div> +</td> -</div> +</table> <a name="overview"></a> @@ -260,11 +264,11 @@ the keys of your keyboard. </p> </tr> <tr> <td>Switch to previous layout orientation (for example, portrait, landscape)</td> - <td>KEYPAD_7, F11</td> + <td>KEYPAD_7, Ctrl-F11</td> </tr> <tr> <td>Switch to next layout orientation (for example, portrait, landscape)</td> - <td>KEYPAD_9, F12</td> + <td>KEYPAD_9, Ctrl-F12</td> </tr> <tr> <td>Toggle cell networking on/off</td> @@ -721,19 +725,19 @@ scale in direct relationship with <delay> values.</p> </tr> <tr> <td><code>-skin <skinID></code></td> - <td>Start the emulator with the specified skin. </td> - <td>The standard Android platforms includes a <a href="#skins">choice of - four skins</a>:<br /> - <li>HVGA-L (480x320, landscape)</li> - <li>HVGA-P (320x480, portrait) (default) </li> - <li>QVGA-L (320x240, landscape)</li> - <li>QVGA-P (240x320, portrait) </li> + <td>This emulator option is deprecated. </td> + <td>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 <a +href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a>. </td> </tr> <tr> <td><code>-skindir <dir></code></td> - <td>Search for emulator skins in <dir>. </td> - <td> </td></tr> + <td>This emulator option is deprecated. </td> + <td>See comments for <code>-skin</code>, above.</td></tr> </table> <a name="diskimages"></a> @@ -1636,41 +1640,9 @@ kilobits/sec):</p> <h2>Using Emulator Skins</h2> -<p>You can run the emulator with any of four default skins, as described in the table below. To specify a skin, use <code>-skin <skinID></code> when starting the emulator. </p> - -<p>For example: </p> - -<pre>emulator -skin HVGA-L</pre> +<p>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 <code>-skin</code> to control the skin used by an emulator instance. For more information about AVDs, see <a +href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a>. </p> -<p>Note that you must enter the <code><skinID></code> in uppercase letters (if your development computer is case-sensitive).</p> - -<table border="0" style="clear:left;padding:2em;"> - <tr> - <th width="20%">skinID</th> - <th >Description</th> - <th >Skin</th> - </tr> - <tr> - <td><code>HVGA-L</code></td> - <td>480x320, landscape</td> - <td><img src="{@docRoot}images/e-mini-hvga-l.png" width="219" height="113"></td> - </tr> - <tr> - <td><code>HVGA-P</code></td> - <td>320x480, portrait (default)</td> - <td><img src="{@docRoot}images/e-mini-hvga-p.png" width="113" height="219"></td> - </tr> - <tr> - <td><code>QVGA-L</code></td> - <td>320x240, landscape</td> - <td><img src="{@docRoot}images/e-mini-qvga-l.png" width="119" height="197"></td> - </tr> - <tr> - <td><code>QVGA-P</code></td> - <td>240x320, portrait</td> - <td><img src="{@docRoot}images/e-mini-qvga-p.png" width="95" height="173"></td> - </tr> -</table> <a name="multipleinstances"></a> diff --git a/docs/html/guide/developing/tools/index.jd b/docs/html/guide/developing/tools/index.jd index 2c9e45d..6e9fde1 100644 --- a/docs/html/guide/developing/tools/index.jd +++ b/docs/html/guide/developing/tools/index.jd @@ -32,6 +32,11 @@ applications on the emulator. </p> of the current display with a pixel grid, so you can get your layout just right. </dd> + <dt><a href="layoutopt.html">layoutopt</a></dt> + <dd>This tool lets you quickly analyze your application's layouts for +efficiency. + </dd> + <dt><a href="draw9patch.html">Draw 9-patch</a></dt> <dd>The Draw 9-patch tool allows you to easily create a {@link android.graphics.NinePatch} graphic using a WYSIWYG editor. It also previews stretched @@ -89,5 +94,10 @@ applications on the emulator. </p> <dd>A script that lets you manage AVDs and generate <a href="http://ant.apache.org/" title="Ant">Ant</a> build files that you can use to compile your Android applications. </dd> + + <dt><a href="zipalign.html">zipalign</a></dt> + <dd>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.</dd> </dl> diff --git a/docs/html/guide/developing/tools/layoutopt.jd b/docs/html/guide/developing/tools/layoutopt.jd new file mode 100644 index 0000000..72a110d --- /dev/null +++ b/docs/html/guide/developing/tools/layoutopt.jd @@ -0,0 +1,62 @@ +page.title=layoutopt +@jd:body + +<p><code>layoutopt</code> 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. </p> + +<p>To run the tool, open a terminal and launch <code>layoutopt +<resources></code> from your SDK <code>tools/</code> directory. In the +command, supply a list of uncompiled resource xml files or directories that you +want to analyze. </p> + +<p>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. </p> + +<p>Here's an example of the output:</p> + +<pre>$ 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</pre> + +<p>The <code>layoutopt</code> 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 <a +href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a>.</p> + +<h3>Usage</h3> + +<p>To run <code>layoutopt</code> against a given list of layout resources:</p> + +<pre>layoutopt <list of xml files or directories></pre> + +<p>For example:</p> + +<pre>$ layoutopt res/layout-land</pre> +<pre>$ layoutopt res/layout/main.xml res/layout-land/main.xml</pre> diff --git a/docs/html/guide/developing/tools/othertools.jd b/docs/html/guide/developing/tools/othertools.jd index 603609e..00f0b8d 100644 --- a/docs/html/guide/developing/tools/othertools.jd +++ b/docs/html/guide/developing/tools/othertools.jd @@ -1,9 +1,11 @@ page.title=Other Tools @jd:body -<p>The sections below describe other tools that you can use when building Android applications. </p> +<p>The sections below describe other tools that you can use when building +Android applications. </p> -<p>All of the tools are included in the Android SDK and are accessible from the <code><sdk>/tools/</code> directory.</p> +<p>All of the tools are included in the Android SDK and are accessible from the +<code><sdk>/tools/</code> directory.</p> <h2>Contents</h2> @@ -16,24 +18,32 @@ page.title=Other Tools <a name="activitycreator"></a> <h2 id="android">android</h2> -<p>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. </p> +<p>{@code android} is an important development tool that lets you:</p> -<p>For information about how to use the android tool to manage AVDs, see <a href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a>. </p> +<ul> + <li>Create, delete, and view Android Virtual Devices (AVDs). See + <a href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a>.</li> + <li>Create and update Android projects. See + <a href="{@docRoot}guide/developing/other-ide.html">Developing in Other IDEs</a>.</li> + <li>Update your Android SDK with new platforms, add-ons, and documentation. See + <a href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a>.</li> +</ul> -<p>For information about how to use the android tool to create or update a project, see <a href="{@docRoot}guide/developing/other-ide.html">Developing in Other IDEs</a>. </p> - -<p>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. </p> - -<p>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. </p> - -<p class="note">Note: The android tool replaces the activitycreator tool provided in previous SDK releases.</p> +<p>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 <a href="{@docRoot}guide/developing/eclipse-adt.html">Developing +In Eclipse</a>. To update your SDK from Eclipse, see +<a href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a>. +</p> <a name="mksdcard"></a> <h2>mksdcard</h2> -<p>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:</p> +<p>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:</p> <pre>mksdcard [-l label] <size>[K|M] <file></pre> @@ -53,7 +63,8 @@ page.title=Other Tools <tr> <td><code>size</code></td> <td>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, <code>1048576K</code>, <code>1024M</code>.</td> +You can also specify size in kilobytes or megabytes, by appending a "K" or "M" to +<size>. For example, <code>1048576K</code>, <code>1024M</code>.</td> </tr> <tr> @@ -63,7 +74,9 @@ You can also specify size in kilobytes or megabytes, by appending a "K" or "M" t </table> -<p>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 <a href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a>.</p> +<p>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 +<a href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a>.</p> <pre>emulator -sdcard <file></pre> @@ -71,7 +84,11 @@ You can also specify size in kilobytes or megabytes, by appending a "K" or "M" t <h2>dx</h2> -<p>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 <code>dx --help</code>.</p> +<p>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 <code>dx --help</code>.</p> diff --git a/docs/html/guide/developing/tools/zipalign.jd b/docs/html/guide/developing/tools/zipalign.jd new file mode 100644 index 0000000..6231798 --- /dev/null +++ b/docs/html/guide/developing/tools/zipalign.jd @@ -0,0 +1,65 @@ +page.title=zipalign +@jd:body + +<p>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.</p> + +<p>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.</p> + +<p class="caution"><strong>Caution:</strong> zipalign must only be performed +<strong>after</strong> 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.</p> + +<p>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.</p> + +<p>For more information about how to use zipalign when building your +application, please read <a href="{@docRoot}guide/publishing/app-signing.html">Signing +Your Application</a>.</p> + + +<h3>Usage</h3> + +<p>To align {@code infile.apk} and save it as {@code outfile.apk}:</p> + +<pre>zipalign [-f] [-v] <alignment> infile.apk outfile.apk</pre> + +<p>To confirm the alignment of {@code existing.apk}:</p> + +<pre>zipalign -c -v <alignment> existing.apk</pre> + +<p>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.</p> + +<p>Flags:</p> + +<ul> + <li>{@code -f} : overwrite existing outfile.zip</li> + <li>{@code -v} : verbose output</li> + <li>{@code -c} : confirm the alignment of the given file</li> +</ul> + + + diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs index a5dadbc..5215202 100644 --- a/docs/html/guide/guide_toc.cs +++ b/docs/html/guide/guide_toc.cs @@ -98,7 +98,7 @@ </li> <li class="toggle-list"> <div><a href="<?cs var:toroot ?>guide/topics/resources/index.html"> - <span class="en">Resources and Assests</span> + <span class="en">Resources and Assets</span> </a></div> <ul> <li><a href="<?cs var:toroot ?>guide/topics/resources/resources-i18n.html"> @@ -107,6 +107,9 @@ <li><a href="<?cs var:toroot ?>guide/topics/resources/available-resources.html"> <span class="en">Available Resource Types</span> </a></li> + <li><a href="<?cs var:toroot ?>guide/topics/resources/localization.html"> + <span class="en">Localization</span> + </a></li> </ul> </li> <li><a href="<?cs var:toroot ?>guide/topics/intents/intents-filters.html"> @@ -252,10 +255,12 @@ <li><a href="<?cs var:toroot ?>guide/developing/tools/draw9patch.html">Draw 9-Patch</a></li> <li><a href="<?cs var:toroot ?>guide/developing/tools/emulator.html">Emulator</a></li> <li><a href="<?cs var:toroot ?>guide/developing/tools/hierarchy-viewer.html">Hierarchy Viewer</a></li> + <li><a href="<?cs var:toroot ?>guide/developing/tools/layoutopt.html">layoutopt</a></li> <li><a href="<?cs var:toroot ?>guide/developing/tools/othertools.html#mksdcard">mksdcard</a></li> <li><a href="<?cs var:toroot ?>guide/developing/tools/monkey.html">Monkey</a></li> <li><a href="<?cs var:toroot ?>guide/developing/tools/adb.html#sqlite">sqlite3</a></li> <li><a href="<?cs var:toroot ?>guide/developing/tools/traceview.html" >Traceview</a></li> + <li><a href="<?cs var:toroot ?>guide/developing/tools/zipalign.html" >zipalign</a></li> </ul> </li> <!--<li><a href="<?cs var:toroot ?>guide/developing/instrumentation/index.html">Instrumentation</a></li> @@ -321,6 +326,9 @@ <span class="zh-TW">最佳實務</span> </h2> <ul> + <li><a href="<?cs var:toroot ?>guide/practices/screens_support.html"> + <span class="en">Supporting Multiple Screens</span> + </a></li> <li class="toggle-list"> <div><a href="<?cs var:toroot ?>guide/practices/ui_guidelines/index.html"> <span class="en">UI Guidelines</span> @@ -340,6 +348,8 @@ </a></li> </ul> </li> + </ul> + <ul> <li><a href="<?cs var:toroot ?>guide/practices/design/performance.html"> <span class="en">Designing for Performance</span> </a></li> @@ -369,6 +379,9 @@ <li><a href="<?cs var:toroot ?>guide/tutorials/views/index.html"> <span class="en">Hello Views</span> </a></li> + <li><a href="<?cs var:toroot ?>guide/tutorials/localization/index.html"> + <span class="en">Hello Localization</span> + </a></li> <li><a href="<?cs var:toroot ?>guide/tutorials/notepad/index.html"> <span class="en">Notepad Tutorial</span> </a></li> diff --git a/docs/html/guide/practices/design/responsiveness.jd b/docs/html/guide/practices/design/responsiveness.jd index ecd743d..1d5a235 100644 --- a/docs/html/guide/practices/design/responsiveness.jd +++ b/docs/html/guide/practices/design/responsiveness.jd @@ -80,7 +80,7 @@ responsive to input and thus avoid ANR dialogs caused by the 5 second input event timeout. These same practices should be followed for any other threads that display UI, as they are also subject to the same timeouts.</p> -<p>The specific constraint on IntentReciever execution time emphasizes what +<p>The specific constraint on IntentReceiver execution time emphasizes what they were meant to do: small, discrete amounts of work in the background such as saving a setting or registering a Notification. So as with other methods called in the main thread, applications should avoid potentially long-running diff --git a/docs/html/guide/practices/screens_support.jd b/docs/html/guide/practices/screens_support.jd new file mode 100644 index 0000000..88975f8 --- /dev/null +++ b/docs/html/guide/practices/screens_support.jd @@ -0,0 +1,1337 @@ +page.title=Supporting Multiple Screens + +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + + <h2>Multiple screens quickview: </h2> + <ul> + <li>Android runs on devices that have different screen sizes and resolutions.</li> + <li>The screen on which your application is displayed can affect its user interface.</li> + <li>The platform handles most of the work of adapting your app to the current screen.</li> + <li>You can create screen-specific resources for precise control of your UI, if needed. </li> + <li>Older applications run in a compatibility mode that provides best-effort rendering on the current screen.</li> + <li>It's important to follow the best practices described in this document and test your application in all supported screens. </li> + </ul> + + <h2>In this document</h2> + <ol> + <li><a href="#overview">Overview of Screen Support</a></li> + <ol> + <li><a href="#range">Range of screens supported</a></li> + <li><a href="#support">How Android supports multiple screens</a></li> + <li><a href="#density-independence">Density independence</a></li> + <li><a href="#attrs">Manifest attributes</a></li> + <li><a href="#qualifiers">Resource qualifiers</a></li> + </ol> + <li style="padding-top:4px;"><a href="#screen-independence">Best Practices for Screen Independence</a></li> + <li><a href="#strategies">Strategies for Legacy Apps</a></li> + <li><a href="#testing">How to Test Your App</a></li> + + </ol> + + <h2>See Also</h2> + <ol> + <li><code><a href="{@docRoot}guide/topics/manifest/supports-screens-element.html"><supports-screens></a></code></li> + <li><code><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></a></code></li> + <li><a href="{@docRoot}guide/topics/resources/resources-i18n.html#AlternateResources">Alternate Resources</a></li> + <li><a href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a></li> + </ol> + +</div> +</div> + +<p>Android is designed to run on a variety of devices that offer a range of +screen sizes and resolutions. For applications, the platform provides a +consistent environment across devices and handles much of the complexity of +adapting an application's UI to the screen on which it is being displayed. At +the same time, the platform exposes APIs that give application developers +precise control over their application's UI when displayed on specific screen +sizes and resolutions. </p> + +<p>This document explains the screens-support features provided by the platform +and how you use them in your application. By following the practices described +here, you can easily create an application that displays properly on all +supported device screens and that you can deploy to any device as a single .apk. +</p> + +<p>If you have already developed and published an application for Android 1.5 or +earlier, you should read this document and consider how you may need to adapt +your application for proper display on new devices that offer different screens +and that are running Android 1.6 or later. In most cases, only minor adjustments +are needed, however you should make sure to <a href="#testing">test your +application</a> on all supported screens. </p> + +<p>In particular, if you have an existing application that you would like to +make available for users of devices with small screens (such as QVGA), please +see <a href="#strategies">Strategies for Legacy Applications</a> for more +information about how to do that. </p> + + +<h2 id="overview">Overview of Screens Support</h2> + +<p>The sections below provide an overview of the Android platform's support for +multiple screens, including an introduction to terms and concepts used in this +document and in the API, a summary of the screen configurations that the +platform supports, and an overview of the API and underlying +screen-compatibility features.</p> + + +<h3>Terms and Concepts</h3> + +<dl> +<dt><em>Screen size</em></dt> + <dd>Actual physical size, measured as the screen's diagonal. + + <p>For simplicity, Android collapses all actual screen sizes into three +generalized sizes: large, normal, and small. Applications can provide custom +layouts for each of these three sizes — the platform transparently handles +the rendering of the layouts at the actual screen size.</p></dd> + +<dt><em>Aspect ratio</em></dt> + <dd>The porportional relationship of the screen's physical width to its +height. Applications can provide layout resources for specific aspect ratios by +using the resource qualifiers <code>long</code> and <code>notlong</code>. </dd> + +<dt><em>Resolution</em></dt> + <dd>The total number of physical pixels on a screen. Note that, although +resolution is often expressed as <em>width</em> x <em>height</em>, resolution +does not imply a specific aspect ratio. In Android, applications do not work +directly with resolution.</dd> + +<dt><em>Density</em></dt> + <dd>Based on the screen resolution, the spread of pixels across the physical +width and height of the screen. + + <p>A screen with lower density has fewer available pixels spread across the +screen width and height, where a screen with higher density has more — +sometimes significantly more — pixels spread across the same area. The +density of a screen 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 larger on the lower density screen and smaller on the higher density +screen. </p> + + <p>For simplicity, Android collapses all actual screen densities into three +generalized densities: high, medium, and low. Applications can provide custom +resources for each of these three densities — the platform handles the +scaling of the resources up or down to meet the actual screen density. </p></dd> +<dt><em>Density independent pixel (dip)</em></dt> + <dd>A virtual pixel unit that applications can use in defining their UI, to +express layout dimensions or position in a density-independent way. + <p>The density-independent pixel is equivalent to one physical pixel on a 160 +dpi screen, the baseline density assumed by the platform (as described later in +this document). At run time, the platform transparently handles any scaling of +the dip units needed, based on the actual density of the screen in use. The +conversion of dip units to screen pixels is simple: <code>pixels = dips * +(density / 160)</code>. For example, on 240 dpi screen, 1 dip would equal 1.5 +physical pixels. Using dip units to define your application's UI is highly +recommended, as a way of ensuring proper display of your UI on different +screens. </p></dd> +</dl> + + +<h3 id="range">Range of Screens Supported</h3> + +<p>Android 1.5 and earlier versions of the platform were designed to support a +single screen configuration — HVGA (320x480) resolution on a 3.2" screen. +Because the platform targeted just one screen, application developers could +write their applications specifically for that screen, without needing to worry +about how their applications would be displayed on other screens. </p> + +<p>Starting from Android 1.6, the platform adds support for multiple screen +sizes and resolutions, reflecting the many new types and sizes of devices on +which the platform will run. This means that developers must design their +applications for proper display on a range of devices and screens.</p> + +<p>To simplify the way application developers design their user interfaces for +multiple devices, and to allow more devices to participate without impacting +applications, the platform divides the range of actual supported screen sizes +and resolutions into:</p> + +<ul> +<li>A set of three generalized sizes: <em>large</em>, <em>normal</em>, and <em>small</em>, and </li> +<li>A set of three generalized densities: high (<em>hdpi</em>), medium (<em>mdpi</em>), and low (<em>ldpi</em>) +</ul> + +<!--<p>Applications use to these generalized sizesThe to let you apply custom UI +and enable/disable functionality according to the generalized class of screen, +rather than by the specific screen. When you are developing your application, +you use these generalized sizes and densities and Applications can use these +generalized sizes and densities to tell the platform I will do it or you do it. +Or a combination of both. --> + +<p>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.</p> + +<p>The range of screens supported by Android and the generalized screen +configurations that the platform maps them to are shown in the table below. </p> + + <table id="screens-table" width="80%" style="margin-top:2em;"> + <tbody> + <tr> + <td></td> + <td style="background-color:#f3f3f3"> + <nobr>Low density (120), <em>ldpi</em></nobr> + </td> + <td style="background-color:#f3f3f3"> + <nobr>Medium density (160), <em>mdpi</em></nobr> + </td> + <td style="background-color:#f3f3f3"> + <nobr>High density (240), <em>hdpi</em><nobr> + </td> + </tr> + <tr> + <td style="background-color:#f3f3f3"> + <em>Small</em> screen + </td> + <td style="font-size:.9em;"> + <ul style="padding:0"> + <li style="margin: 0 0 0 1em;padding:.25em 0 0 0; font-size:.9em;">QVGA (240x320), <nobr>2.6"-3.0" diagonal</nobr></li> + </ul> + </td> + <td></td> + <td></td> + </tr> + <tr> + <td style="background-color:#f3f3f3"> + <em>Normal</em> screen + </td> + <td style="font-size:.9em;"> + <ul style="padding:0"> + <li style="margin: 0 0 0 1em;padding:.25em 0 0 0; font-size:.9em;">WQVGA (240x400), <nobr>3.2"-3.5" diagonal</nobr></li> + <li style="margin: 0 0 0 1em;padding:.25em 0 0 0; font-size:.9em;">FWQVGA (240x432), <nobr>3.5"-3.8" diagonal</nobr></li> + </ul> + </td> + <td style="font-size:.9em;background-color:#FFE;"> + <ul style="padding:0"> + <li style="margin: 0 0 0 1em;padding:.25em 0 0 0; font-size:.9em;">HVGA (320x480), <nobr>3.0"-3.5" diagonal</nobr></li> + </ul> + </td> + <td style="font-size:.9em;"> + <ul style="padding:0"> + <li style="margin: 0 0 0 1em;padding:.25em 0 0 0; font-size:.9em;">WVGA (480x800), <nobr>3.3"-4.0" diagonal</nobr></li> + <li style="margin: 0 0 0 1em;padding:.25em 0 0 0; font-size:.9em;">FWVGA (480x854), <nobr>3.5"-4.0" diagonal</nobr></li> + </ul> + </td> + </tr> + <tr> + <td style="background-color:#f3f3f3"> + <em>Large</em> screen + </td> + <td></td> + <td style="font-size:.9em;"> + <ul style="padding:0"> + <li style="margin: 0 0 0 1em;padding:.25em 0 0 0; font-size:.9em;">WVGA (480x800), <nobr>4.8"-5.5" diagonal</nobr></li> + <li style="margin: 0 0 0 1em;padding:.25em 0 0 0; font-size:.9em;">FWVGA (480x854), <nobr>5.0"-5.8" diagonal</nobr></li> + </ul> + </td> + <td></td> + </tr> + </tbody> + </table> + +<p class="caption" style="margin-top:1em;margin-bottom:1.5em;"><strong>Table +1.</strong> Summary of device screens supported by Android. </p> + +<p>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.</p> + +<!-- <p>Note that each screen configuration spans a range of actual resolutions +and physical screen sizes. For example, the The baseline configuration spans a +range of actual screen sizes — from 3.0" to 3.5" diagonal — all with +the same HVGA resolution. That means that the actual pixel density of devices in +a single screen configuration can vary. </p> + +Because differences in density can affect the displayed size of UI elements +declared in pixels, the framework provides a density-independent pixel (dip) +unit that applications can use to declare UI dimensions, letting the platform +automatically handle the scaling to the actual pixel density of the screen. When +UI dimensions are declared in dip, the result is that they are displayed at the +same physical size on all screens in a given configuration. </p> --> + +<p>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 <a +href="#screen-independence">Best Practices for Screen Independence</a>.</p> + + +<h3 id="support">How Android supports multiple screens</h3> + +<div class="sidebox-wrapper"> +<div class="sidebox"> +<h2>Using the alternate resources framework</h2> + +<p>The platform's support for loading screen size- and density-specific +resources at run time is based on the alternate resources framework. + +<p> 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 +<a href="{@docRoot}guide/topics/resources/resources-i18n.html#AlternateResources"> +Alternate Resources</a>. +</div> +</div> + +<p>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:</p> + +<ul> + <li>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 <code>large</code>, <code>normal</code>, and +<code>small</code>, and those for density-specific resources are +<code>hdpi</code> (high), <code>mdpi</code> (medium), and <code>ldpi</code> +(low). The qualifiers correspond to the generalized densities given in +<a href="#range">Table 1</a>, above.</li> + <li>The platform also provides a +<a href="{@docRoot}guide/topics/manifest/supports-screens-element.html"> +<code><supports-screens></code></a> +element, whose attributes +<code>android:largeScreens</code>, <code>android:normalScreens</code>, and +<code>android:smallScreens</code> let you specify what generalized screen sizes +your application supports. A fourth attribute, <code>android:anyDensity</code>, +lets you indicate whether or not your application includes built-in support for +multiple densities.</li> +</ul> + +<p>At run time, the platform provides three types of support to your +application, to ensure the best possible display on the current device +screen:</p> + +<ol> +<li><em>Pre-scaling of resources (such as image assets)</em> + + <p>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.</p> + + <p>For example, if the current screen's density is "high", the platform loads +resources that are tagged with the qualifier <code>hdpi</code> 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". </p> + + <p>For more information about how to create size- and density-specific +resources, see <a href="#qualifiers">Resource qualifiers</a>.</p></li> + +<li><em>Auto-scaling of pixel dimensions and coordinates</em> + + <p>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. </p> + + <p>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.<p> + + <p>For more information, see the <code>android:anyDensity</code> attribute in +<a href="#attrs">Manifest attributes for screens support</a>.</p></li> + +<div class="sidebox-wrapper" xstyle="margin-bottom:2em;margin-top:.5em;width:90%;"> + <img id="rule" src="{@docRoot}assets/images/grad-rule-qv.png"> + <div id="qv-sub-rule"> + <img src="{@docRoot}assets/images/icon_market.jpg" style="float:left;margin:0;padding:0;"> + <p style="color:#669999;">Publishing to Small Screen Devices</p> + <p>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 <a href="#testing">test your application</a> +on small screens and then upload an updated version that explicitly +<a href="#attrs">indicates support for small screens</a>. </p> + </div> +</div> + +<li><em>Compatibility-mode display on larger screen-sizes</em> + + <p>If the current screen's size is larger than your application supports, as +specified in the <code>supports-screens</code> 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. </p> + + <p>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.</p> + + <p>For more information, see the <code>android:anyDensity</code> attribute in +<a href="#attrs">Manifest elements for screens support</a> and the +<a href="#compatibility-examples">Screen-Compatibility Examples</a> +section.</p></li> +</ol> + +<p>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. </p> + +<p>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 <a href="#strategies">Strategies for Legacy +Applications</a>.</p> + +<p>The sections below provide more information how to take advantage of the +platform's multiple-screens support. </p> + + +<h3 id="density-independence">Density independence</h3> + +<p>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.</p> + +<p>The platform provides density independence to applications by default. It +does this in three ways: </p> + +<ul> +<li>Through pre-scaling of drawable resources (scaled at resource loading +time)</li> +<li>Through auto-scaling of device-independent pixel (dip) values used in +layouts</li> +<li>Through auto-scaling of absolute pixel values used in the application (only +needed if the application has set <code>android:anyDensity="false"</code> in its +manifest)</li> +</ul> + +<p>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.</p> + + +<div id=vi09 style=TEXT-ALIGN:left> +<img src="{@docRoot}images/screens_support/dip.png" style="padding-bottom:0;margin-bottom:0;" /> +<p class="caption" style="margin:0 0 1.5em 1em;padding:0 0 0 +1em;"><strong>Figure 1.</strong> Examples of density independence on WVGA high +density (left), HVGA medium density (center), and QVGA low density (right). </p> +</div> + +<p>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 (<code>dip</code> or <code>dp</code>) or +scale-independent pixels (<code>sip</code> or <code>sp</code>, for text only). +If you are using absolute pixel values in the application and manifest includes +<a href="#attrs"><code>android:anyDensity="true"</code></a>, you will also need +to scale the pixel values. See <a href="#dips-pels">Converting from dips to +pixels</a> for more information. </p> + + +<h3 id="attrs">Manifest attributes for screens support</h3> + +<p> Android 1.6 introduced a new manifest element, +<a href="{@docRoot}guide/topics/manifest/supports-screens-element.html"><code><supports-screens></code></a>, +whose attributes you can use to control the +display of your application on different classes of device screens, as listed +below. The <code>smallScreens</code>, <code>normalScreens</code>, and +<code>largeScreens</code> attributes correspond to the generalized screen sizes +shown in <a href="#range">Table 1</a>, earlier in this document.</p> + + <table id="vrr8"> + <tr> + <th> + Attribute + </th> + <th > + Description + </th> + </tr> + <tr> + <td> + <code>android:smallScreens</code> + </td> + <td> + Whether or not the application UI is designed for use on +<em>small</em> screens — "<code>true</code>" if it is, and +"<code>false</code>" if not. See <a href="#defaults">Default values for +attributes</a> for information about the assumed value of this attribute, if not +declared. + </td> + </tr> + <tr> + <td> + <code>android:normalScreens</code> + </td> + <td> + Whether or not the application UI is designed for use on +<em>normal</em> screens — "<code>true</code>" if it is, and +"<code>false</code>" if not. The default value is "<code>true</code>". + </td> + </tr> + <tr> + <td> + <code>android:largeScreens</code> + </td> + <td> + Whether or not the application UI is designed for use on +<em>large</em> screens — "<code>true</code>" if it is, and +"<code>false</code>" if not. See <a href="#defaults">Default values for +attributes</a> for information about the assumed value of this attribute, if not +declared. + </td> + </tr> + <tr> + <td> + <code>android:anyDensity</code> + </td> + <td> + <p>Whether or not the application is designed to manage its UI properly +in different density environments — "<code>true</code>" if so, and +"<code>false</code>" if not. </p> + <ul> + <li>If set to "<code>true</code>", 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. </li> + + <li>If set to "<code>false</code>", 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. </li> + </ul> + <p>See <a href="#defaults">Default values for attributes</a> for +information about the assumed value of this attribute, if not declared.</p> + </td> + </tr> + </table> + +<p>In general, when you declare a screen-size attribute +(<code>smallScreens</code>, <code>normalScreens</code>, or +<code>largeScreens</code>) 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:</p> + +<ul> + <li>If you declare <code>largeScreens="false"</code>, 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 +<a href="#compatibility-examples">Screen-Compatibility Examples</a> for an +illustration of what an application looks like when displayed in compatibility +mode.</li> + <li>If you declare <code>smallScreens="false"</code>, 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. </li> +</ul> + +<p>If you declare the <code>android:anyDensity</code> 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}.</p> + +<p>Note that the setting of the <code>android:anyDensity</code> 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. </p> + +<p>The following example shows a manifest that declares support for large, +normal, and small screens in any densities.</p> + +<pre><manifest xmlns:android="http://schemas.android.com/apk/res/android"> + + <supports-screens + android:largeScreens="true" + android:normalScreens="true" + android:smallScreens="true" + android:resizable="true" + android:anyDensity="true" /> + </manifest> +</pre> + +<h4 id="defaults"> + Default values for attributes +</h4> + +<p>The default values for the <code><supports-screens></code> attributes +differs, depending on the the value of the +<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code>android:minSdkVersion</code></a> + attribute in the application's manifest, as well as on +the value of <code>android:targetSdkVersion</code>, if declared:</p> + +<div> + <ul> + <li> + If <code>android:minSdkVersion</code> or +<code>android:targetSdkVersion</code> is "3" (Android 1.5) or lower, the default +value for everything except android:normalScreens is <code>false</code>. 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 +<code>true</code>. + </li> + <li> + If <code>android:minSdkVersion</code> or +<code>android:targetSdkVersion</code> is "4" (Android 1.6) or higher, the +default value for everything is <code>true</code>. If your application +requires <span style=BACKGROUND-COLOR:#ffffff>Android 1.6 </span>features, +but does not support these densities and/or screen sizes, you need to set the +appropriate attributes to <code>false</code>. + </li> + <li> + Note that <code>android:normalScreens</code> always defaults to +<code>true</code>. + </li> + </ul> +</div> + + +<h3 id="qualifiers">Resource directory qualifiers for screen size and density</h3> + +<p>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 <a href="#range">Table +1</a>, earlier in this document.</p> + +<table> +<tr> +<th>Screen characteristic</th> +<th>Qualifier</th> +<th>Description</th> +</tr> + +<tr> + <td rowspan="3">Size</td> + <td><code>small</code></td> + <td>Resources for small screens, such as QVGA low density.</td> +</tr> +<tr> + <td><code>normal</code></td> + <td>Resources for normal (baseline configuration) screens, such as T-Mobile +G1/HTC Magic screen size, or equivalent.</td> +</tr> +<tr> +<td><code>large</code></td> +<td>Resources for large screens. Typical example is a tablet like device.</td> +</tr> + +<tr> +<td rowspan="4">Density</td> +<td><code>ldpi</code></td> +<td>Low-density resources, for 100 to 140 dpi screens.</td> +</tr> +<tr> +<td><code>mdpi</code></td> +<td>Medium-density resources for 140 to 180 dpi screens.</td> +</tr> +<tr> +<td><code>hdpi</code></td> +<td>High-density resources for 190 to 250 dpi screens.</td> +</tr> +<tr> +<td><code>nodpi</code></td> +<td>Density-independent resources. The platform does not auto-scale resources +tagged with this qualifier, regardless of the current screen's density.</td> +</tr> + +<tr> +<td rowspan="2">Aspect ratio</td> +<td><code>long</code></td> +<td>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.</td> +</tr> +<tr> +<td><code>notlong</code></td> +<td>Resources for use only on screens that have an aspect ratio that is similar +to the baseline screen configuration.</td> +</tr> +<tr> +<td>Platform version</td> +<td><nobr><code>v<api-level></code></nobr></td> +<td>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 <code>-v4</code> +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. </td> +</tr> +</table> + +<p> +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 +<i>large</i> 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. +</p> + +<p>Here is an example of the resource directory structure of an application that +supports low and high density, and employs different layout schemes.</p> + +<pre>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 +</pre> + +<p>For more information about how to use resource qualifiers or how the platform +selects them, please read +<a href="{@docRoot}guide/topics/resources/resources-i18n.html#AlternateResources"> +Alternate Resources</a>.</p> + + +<h2 id="screen-independence">Best practices for Screen Independence</h2> + +<p>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 <a href="#range">Table 1</a> earlier in this document. +</p> + +<p>You can easily ensure that your application will display properly on +different screens. Here is a quick checklist:</p> + +<ol> + <li> + Prefer wrap_content, fill_parent and the dip unit to px in XML layout files + </li> + <li> + Avoid AbsoluteLayout + </li> + <li> + Do not use hard coded pixel values in your code + </li> + <li> + Use density and/or resolution specific resources + </li> +</ol> + +<h3 id="use-relative">1. Prefer wrap_content, fill_parent and the dip unit to +absolute pixels<br> </h3> + +<p>When defining the <code>layout_width</code> and <code>layout_height</code> of +views in an XML layout file, using <code>wrap_content</code>, +<code>fill_parent</code> or the <code>dip</code> will guarantee that the view is +given an appropriate size on the current device screen. For instance, a view +with a <code>layout_width="100dip"</code> 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. </p> + +<p>Similarly, you should prefer the <code>sp</code> (scale-independent pixel, +the scale factor depends on a user setting) or <code>dip</code> (if you don't +want to allow the user to scale the text) to define font sizes.</p> + +<h3 id="avoid-absolute">2. Avoid AbsoluteLayout </h3> + +<p>{@link android.widget.AbsoluteLayout AbsoluteLayout} +is one of the layout containers offered by the Android UI toolkit. Unlike the +other layouts however, <code>AbsoluteLayout</code> enforces the use of fixed +positions which might easily lead to user interfaces that do not work well on +different displays. Because of this, <code>AbsoluteLayout</code> was deprecated +in Android 1.5 (API Level 3). </p> + +<p>You can achieve much the same layout by using a +{@link android.widget.FrameLayout FrameLayout} instead, and setting +<code>layout_margin</code> attributes of the children. This approach is more +flexible and will yield better results on different screens.</p> + +<h3>3. Do not use hard-coded pixel values in your code</h3> + +<p>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 <code>myView.getWidth()</code> 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. </p> + +<h4 id="dips-pels">Converting from dips to pixels</h4> + +<p>In some cases, you will need to express dimensions in <code>dip</code> 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 <code>dip</code> +and then converted to actual pixels.</p> + +<pre>// 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);</span> + +// Use mGestureThreshold as a distance in pixels +</pre> + +<p>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 <code>Context</code> or +<code>Activity</code>. On a medium (160) density screen, +<code>DisplayMetrics.density</code> 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.</p> + +<h4>Use pre-scaled configuration values</h4> + +<p>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:</p> + +<pre>ViewConfiguration.get(aContext).getScaledTouchSlop()</pre> + +<p>Methods starting with the <code>getScaled</code> prefix are guaranteed to return a value in pixels that will display properly regardless of the current screen density.</p> + +<h3>4. Use density and/or size-specific resources</h3> + +<div style="float: right;background-color:#fff;margin: 0;padding: 20px 0 20px 20px;"> +<img src="{@docRoot}images/screens_support/scale-test.png" style="padding:0;margin:0;"> +<p class="caption" style="margin:0;padding:0;"><strong>Figure 2.</strong> Comparison of pre-scaled and auto-scaled bitmaps.</p> +</div> + +<p>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.</p> + +<h4 id="resource-dirs">Custom resources and directories</h4> + +<p>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:</p> + +<p style="margin-left:2em;"><code>res/drawable-mdpi/icon.png // +for medium-density screens</code></p> + +<p style="margin-left:2em;"><code>res/drawable-hdpi/icon.png // +for high-density screens</code></p> + +<p>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.</p> + +<p>For more information about valid resource qualifiers, see +<a href="#qualifiers">Resource directory qualifiers</a>, earlier in this +document.</p> + +<h4 id="scaling">Pre-scaling and auto-scaling of bitmaps and nine-patches</h4> + +<p>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 <code>res/drawable/</code> +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.</p> + +<p>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 +<code>res/drawable-hdpi/</code> directory. If one of the bitmaps is a 240x240 +icon and is loaded on a medium-density screen, the resulting bitmap will measure +160x160.</p> + +<p>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 <code>android:anyDensity</code>). 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.</p> + +<p>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.</p> + +<p>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:</p> + +<p style="margin-left:2em;"><code>res/drawable-nodpi/icon.png</code></p> + +<p>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 <code>BitmapFactory.Options</code>) which will be used to scale the +bitmap on screen <em>at drawing time</em>. + +<p>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.</p> + +<p>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.</p> + +<h2 id="strategies">Strategies for Legacy Applications</h2> + +<p>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 </p> + +<ul> +<li>Existing devices, which may be running Android 1.5 (or lower) platform +version, as well as to </li> +<li>Newer devices that are running Android 1.6 (or higher) and offering various +screen sizes and resolutions</li> +</ul> + +<p>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 <em>and</em> 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.</p> + +<p>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:</p> + +<ol> + <li>Maintain compatibility with existing devices by leaving your application's +<code>android:minSdkVersion</code> attribute as it is. You <em>do not</em> need +to increment the value of the attribute to support new devices and multiple +screens. </li> + <li>Extend compatibility for Android 1.6 (and higher) devices by adding +a new attribute — <code>android:targetSdkVersion</code> — to the +<code>uses-sdk</code> element. Set the value of the attribute to +"<code>4</code>". This allows your application to "inherit" the platform's +multiple screens support, even though it is technically using an earlier version +of the API. </li> + <li>Add an empty <code><supports-screens></code> element as a child of +<code><manifest></code>. If you need to enable size or density attributes +later, this is where you will add them.</li> + <li>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. </li> + <li>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 <a +href="#testing">How to Test Your Application on Multiple Screens</a>, +below.</li> + <li>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. </li> + <li>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. </li> + <li>Debug any display or functional issues. For issues that you resolve in +your application code, <span style="color:red">make certain not to use any APIs +introduced in API Level 4 or later</span>. 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.</li> + <li>For resource-related issues, you can try resolving them by: + <ul> + <li>Adding a <code>anyDensity="false"</code> attribute to +<code><supports-screens></code>, to enable density-compatibility +scaling.</li> + <li>Creating any size- or density-specific resources you need and placing +them in directories tagged with the <a href="#qualifiers">correct +qualifiers</a>. Qualifiers must be arranged in a proscribed order. See +<a href="{@docRoot}guide/topics/resources/resources-i18n.html#AlternateResources"> +Alternate Resources</a> for more information. </li> + <li>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 <code>v<api-level></code> +qualifier (for example, <code>-v4</code>). This ensures that those resources +will be ignored when the application is run on Android 1.5 or lower platform +versions.</p></li> + </ul> + </li> + <li>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 +<code>largeScreens="false"</code> attribute to the +<code><supports-screens></code> element in the manifest. See +<a href="#compatibility-examples">Screen-Compatibility Examples</a> for +illustrations of how the platform displays your application in this case.</li> + <li>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 +<em>must</em> add a <code>smallScreens="false"</code> attribute to the +<code><supports-screens></code> element. </li> + <li>Continue testing and debugging until your application performs as expected +on all of the platforms and screen sizes your application will support.</li> + <li>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. </li> +</ol> + +<p>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. </p> + +<h2 id="testing">How to Test Your Application on Multiple Screens</h2> + +<p>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.</p> + +<!-- You can test in any minsdk, and you can test with compatabiltiy code or +not. Once you've tested your application and found that it displays properly on +various screen sizes, you should make sure to add the corresponding size +attribute(s) to your application's manifest. --> + +<div id="f9.5" style="float:right;margin:0;padding:0;"> + <img src="{@docRoot}images/screens_support/avds-config.png" style="padding:0;margin:0;"> + <p class="caption" style="margin:0 0 1.5em 1em;padding:0 0 0 1em;"><strong>Figure 3.</strong> + A typical set of AVDs for testing screens support.</p> +</div> + +<p>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 <code>android</code> 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 +<a href="{@docRoot}guide/developing/tools/avd.html">Android Virtual +Devices</a>.</p> + +<p>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:</p> + +<ul> + <li> + QVGA (240x320, low density, small screen) + </li> + <li> + HVGA (320x480, medium density, normal screen) + </li> + <li> + WVGA800 (480x800, high density, normal screen) + </li> + <li> + WVGA854 (480x854 high density, normal screen) + </li> +</ul> + +<p>The Android 2.0 platform offers all of the Android 1.6 default skins, +above, plus:</p> + +<ul> + <li> + WQVGA400 (240x400, low density, normal screen) + </li> + <li> + WQVGA432 (240x432, low density, normal screen) + </li> +</ul> + +<p>If you are using the <code>android</code> tool command line to create your +AVDs, here's an example of how to specify the skin you want to use:</p> + +<pre>android create avd ... --skin WVGA800</pre> + +<p>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 <code>-scale</code> option, when +launching the emulator, for example:</p> + +<pre>emulator -avd <name> -scale 96dpi</pre> + +<p>If you are working in Eclipse with ADT, you can specify the <code>-scale +96dpi</code> option in the Target tab of run and debug configurations, under +"Additional Emulator Command Line Options" field. </p> + +<p>Note that starting the emulator with the <code>-scale</code> 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:</p> + +<ul> + <li> + QVGA, low density: 3.3" + </li> + <li> + WQVGA, low density: 3.9" + </li> + <li> + WQVGA432, low density: 4.1" + </li> + <li> + HVGA, medium density: 3.6" + </li> + <li> + WVGA800, high density: 3.9" + </li> + <li> + WVGA854, high density: 4.1" + </li> +</ul> + +<div style="float: right;background-color:#fff;margin: 0;padding: 20px 0 20px 20px;width:520px;"> + <img src="{@docRoot}images/screens_support/avd-density.png" style="padding:0;margin:0;"> + <p class="caption" style="margin:0 0 1.5em 1em;padding:0 0 0 1em; width:280px;"><strong>Figure 4.</strong> + Resolution and density options that you can use, when creating an AVD using the AVD Manager.</p> +</div> + +<p>You should also make sure to test your application on different physical +screen sizes within a single size-density configuration. For example, according +to <a href="#range">Table 1</a>, 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 +<code>-scale</code> to 96*2.8/3.3 = 81dpi. You can also pass a float value to +<code>-scale</code> to specify your own scaling factor:</p> + +<pre>emulator -avd <name> -scale 0.6</pre> + +<p>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.</p> + +<p>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.</p> + +<p>In the <code>android</code> tool, follow these steps to create an AVD with a +custom resolution or density:</p> + +<ol> + <li>Use the <code>create avd</code> command to create a new AVD, specifying +the <code>--skin</code> 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: + <pre>android create avd -n <name> -t <targetID> --skin WVGA800</pre> + </li> + <li>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.</li> + <li>Continue through the various profile settings until the tool asks you to +specify "Abstracted LCD density" (<em>hw.lcd.density</em>). Consult <a +href="#range">Table 1</a>, earlier in this document, and enter the appropriate +value. For example, enter "160" to use medium density for the WVGA800 screen.</li> + <li>Set any other hardware options and complete the AVD creation.</li> +</ol> + +<p>In the example above (WVGA medium density), the new AVD will emulate a 5.8" +WVGA screen.</p> + +<p>As an alternative to adjusting the emulator skin configuration, you can use +the emulator skin's default density and add the <code>-dpi-device</code> option +to the emulator command line when starting the AVD. For example, </p> + +<pre>emulator -avd WVGA800 -scale 96dpi -dpi-device 160</pre> + + +<h2 id="compatibility-examples">Screen-Compatibility Examples</h2> + +<p>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.</p> + +<p>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. </p> + +<p>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 <a href="#strategies">Strategies +for Legacy Applications</a>. However, if you did not do so, the +platform still performs best-effort rendering of your application, as +illustrated below.</p> + +<p> Internally, these are the compatibility features that the platform +provides, based on the current device screen:</p> + + <ul> + <li> + If the device's screen density is <em>not medium</em>, the application's +layout and drawing of its content is as if the screen <em>is</em> 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). + </li> + <li> + If the device's screen size is <em>small</em>, 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. + </li> + <li> + If the device's screen size is <em>large</em>, 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). + </li> + </ul> + +<table style="width:10%;margin-left:.5em;"> + <tr> + <td> + HVGA, normal size, normal density<br> + [ emulator -skin HVGA ]<br> + <img height=149 src="{@docRoot}images/screens_support/afdvfckr9j_15dcsvrscg_b.png" width=225> + </td> + <td> + WVGA, normal size, high density<br> + [emulator -skin WVGA854 -dpi-device 240]<br> + <img height=143 src="{@docRoot}images/screens_support/afdvfckr9j_18c6mhm3cm_b.png" width=254><br> + <p>The application occupies full screen as its considered to be normal size. (close to 480x720)</p> + </td> + </tr> + <tr> + <td> + VGA, large size, medium density<br> + [ emulator -skin 640x480 ]<br> + <img height=243 src="{@docRoot}images/screens_support/afdvfckr9j_14fj6dhsc3_b.png" width=324> + <p>The application occupies 320x480 of VGA.</p> + </td> + <td> + SVGA, large size, high density<br> + [ emulator -skin 800x600 -dpi-device 240]<br> + <img height=223 src="{@docRoot}images/screens_support/afdvfckr9j_19c743p6cr_b.png" width=294> + <p>The application occupies 480x720 (=1.5 x [320x480]) of 800x600.</p> + </td> + </tr> +</table> + + +<h3>Screen-compatibility limitations on small, low-density screens</h3> + +<p>Because these device has smaller state/resolution, there are known +limitations when application runs in compatibility mode.</p> + +<h4>QVGA</h4> + +<p>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.</p> + +<p>Examples:</p> + +<table style="width:10%;margin-left:.5em;"> + <tr> + <td>The part of z value graph is chopped.</td> + <td>The lap time area is chopped.<br></td> + </tr> + <tr> + <td><img height=207 src="{@docRoot}images/screens_support/afdvfckr9j_16g95wjqg3_b.png" width="155"></td> + <td><img height=186 src="{@docRoot}images/screens_support/afdvfckr9j_17p2w4txgc_b.png" width="139"></td> + </tr> +</table> + + +<h4>Images with 1 pixel height/width.</h4> + +<p>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.</p> + +<p>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.)</p> + +<img height=222 src="{@docRoot}images/screens_support/afdvfckr9j_20fvptbbdd_b.png" width=166> + + + diff --git a/docs/html/guide/practices/ui_guidelines/icon_design.jd b/docs/html/guide/practices/ui_guidelines/icon_design.jd index 5f0a278..e5a1b5e 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.</code>. <tr> <td class="image-caption-i image-list"> - <img src="/images/icon_design/ic_launcher_alarmclock.png" alt="Android asset" /> + <img src="{@docRoot}images/icon_design/ic_launcher_alarmclock.png" alt="Android asset" /> <div class="caption">Alarm Clock</div></td> <td class="image-caption-i image-list"> - <img src="/images/icon_design/ic_launcher_browser.png" alt="Android asset" /> + <img src="{@docRoot}images/icon_design/ic_launcher_browser.png" alt="Android asset" /> <div class="caption">Browser</div></td> <td class="image-caption-i image-list"> - <img src="/images/icon_design/ic_launcher_calculator.png" alt="Android asset" /> + <img src="{@docRoot}images/icon_design/ic_launcher_calculator.png" alt="Android asset" /> <div class="caption">Calculator</div></td> <td class="image-caption-i image-list"> - <img src="/images/icon_design/ic_launcher_calendar.png" alt="Android asset" /> + <img src="{@docRoot}images/icon_design/ic_launcher_calendar.png" alt="Android asset" /> <div class="caption">Calendar</div></td> <td class="image-caption-i image-list"> - <img src="/images/icon_design/ic_launcher_video_camera.png" alt="Android asset" /> + <img src="{@docRoot}images/icon_design/ic_launcher_video_camera.png" alt="Android asset" /> <div class="caption">Camcorder</div></td> <td class="image-caption-i image-list"> - <img src="/images/icon_design/ic_launcher_camera.png" alt="Android asset" /> + <img src="{@docRoot}images/icon_design/ic_launcher_camera.png" alt="Android asset" /> <div class="caption">Camera</div></td> <td class="image-caption-i image-list"> - <img src="/images/icon_design/ic_launcher_contacts.png" alt="Android asset" /> + <img src="{@docRoot}images/icon_design/ic_launcher_contacts.png" alt="Android asset" /> <div class="caption">Contacts</div></td> </tr> <tr> <td class="image-caption-i image-list"> - <img src="/images/icon_design/ic_launcher_phone_dialer.png" alt="Android asset" /> + <img src="{@docRoot}images/icon_design/ic_launcher_phone_dialer.png" alt="Android asset" /> <div class="caption">Dialer</div></td> <td class="image-caption-i image-list"> - <img src="/images/icon_design/ic_launcher_email_generic.png" alt="Android asset" /> + <img src="{@docRoot}images/icon_design/ic_launcher_email_generic.png" alt="Android asset" /> <div class="caption">Email</div></td> <td class="image-caption-i image-list"> - <img src="/images/icon_design/ic_launcher_gallery.png" alt="Android asset" /> + <img src="{@docRoot}images/icon_design/ic_launcher_gallery.png" alt="Android asset" /> <div class="caption">Gallery</div></td> <td class="image-caption-i image-list"> - <img src="/images/icon_design/ic_launcher_generic_application.png" alt="Android asset" /> + <img src="{@docRoot}images/icon_design/ic_launcher_generic_application.png" alt="Android asset" /> <div class="caption">Generic application</div></td> <td class="image-caption-i image-list"> - <img src="/images/icon_design/ic_launcher_email.png" alt="Android asset" /> + <img src="{@docRoot}images/icon_design/ic_launcher_email.png" alt="Android asset" /> <div class="caption">Gmail</div></td> <td class="image-caption-i image-list"> - <img src="/images/icon_design/ic_launcher_google_talk.png" alt="Android asset" /> + <img src="{@docRoot}images/icon_design/ic_launcher_google_talk.png" alt="Android asset" /> <div class="caption">Google Talk</div></td> <td class="image-caption-i image-list"> - <img src="/images/icon_design/ic_launcher_IM.png" alt="Android asset" /> + <img src="{@docRoot}images/icon_design/ic_launcher_IM.png" alt="Android asset" /> <div class="caption">IM</div></td> </tr> <tr> <td class="image-caption-i image-list"> - <img src="/images/icon_design/ic_launcher_maps.png" alt="Android asset" /> + <img src="{@docRoot}images/icon_design/ic_launcher_maps.png" alt="Android asset" /> <div class="caption">Maps</div></td> <td class="image-caption-i image-list"> - <img src="/images/icon_design/ic_launcher_marketplace.png" alt="Android asset" /> + <img src="{@docRoot}images/icon_design/ic_launcher_marketplace.png" alt="Android asset" /> <div class="caption">Market </div></td> <td class="image-caption-i image-list"> - <img src="/images/icon_design/ic_launcher_sms_mms.png" alt="Android asset" /> + <img src="{@docRoot}images/icon_design/ic_launcher_sms_mms.png" alt="Android asset" /> <div class="caption">Messaging </div></td> <td class="image-caption-i image-list"> - <img src="/images/icon_design/ic_launcher_musicplayer_2.png" alt="Android asset" /> + <img src="{@docRoot}images/icon_design/ic_launcher_musicplayer_2.png" alt="Android asset" /> <div class="caption">Music</div></td> <td class="image-caption-i image-list"> - <img src="/images/icon_design/ic_launcher_settings.png" alt="Android asset" /> + <img src="{@docRoot}images/icon_design/ic_launcher_settings.png" alt="Android asset" /> <div class="caption">Settings</div></td> <td class="image-caption-i image-list"> - <img src="/images/icon_design/ic_launcher_voicedial.png" alt="Android asset" /> + <img src="{@docRoot}images/icon_design/ic_launcher_voicedial.png" alt="Android asset" /> <div class="caption">Voice Dialer</div></td> <td class="image-caption-i image-list"> - <img src="/images/icon_design/ic_launcher_voicesearch.png" alt="Android asset" /> + <img src="{@docRoot}images/icon_design/ic_launcher_voicesearch.png" alt="Android asset" /> <div class="caption">Voice Search</div></td> </tr> <tr> <td class="image-caption-i image-list"> - <img src="/images/icon_design/ic_launcher_youtube.png" alt="Android asset" /> + <img src="{@docRoot}images/icon_design/ic_launcher_youtube.png" alt="Android asset" /> <div class="caption">YouTube</div></td> </tr> </table> diff --git a/docs/html/guide/publishing/app-signing.jd b/docs/html/guide/publishing/app-signing.jd index a16c910..f0febc0 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 <li><a href="#debugmode">Signing in Debug Mode</a></li> <li><a href="#releasemode">Signing for Public Release</a> <ol> - <li><a href="#releasecompile">Compiling for release</a></li> - <li><a href="#cert">Obtaining a suitable private key</a></li> - <li><a href="#signapp">Signing your application</a></li> - <li><a href="#ExportWizard">Compiling and signing with Eclipse ADT</a></li> + <li><a href="#cert">Obtain a suitable private key</a></li> + <li><a href="#releasecompile">Compile the application in release mode</a></li> + <li><a href="#signapp">Sign your application with your private key</a></li> + <li><a href="#align">Align the final APK package</a></li> + <li><a href="#ExportWizard">Compile and sign with Eclipse ADT</a></li> </ol> </li> <li><a href="#secure-key">Securing Your Private Key</a></li> @@ -71,6 +72,7 @@ application's signer certificate expires after the application is installed, the will continue to function normally.</li> <li>You can use standard tools — Keytool and Jarsigner — to generate keys and sign your application .apk files.</li> + <li>Once you have signed the application, use the <code>zipalign</code> tool to optimize the final APK package.</li> </ul> <p>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: </li> </ul> +<p>Once your application is signed, don't forget to run {@code zipalign} on the APK +for additional optimization.</p> + <h2 id="strategies">Signing Strategies</h2> <p>Some aspects of application signing may affect how you approach the development @@ -171,16 +176,16 @@ use a <a href="#cert">suitable certificate</a> to sign your applications. </p> <h2 id="setup">Basic Setup for Signing</h2> -<p>To support the generation of a keystore and debug key, you should first make sure that +<p>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.</p> +tools. In most cases, you can tell the SDK build tools how to find Keytool by setting +your <code>JAVA_HOME</code> environment variable to references a suitable JDK. +Alternatively, you can add the JDK version of Keytool to your <code>PATH</code> variable.</p> <p>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 -<code>/usr/bin/keytool</code>. In this case, check the symlink target to make sure that it points +version. If Keytool is already in your <code>PATH</code>, it might be pointing to a symlink at +<code>/usr/bin/keytool</code>. In this case, check the symlink target to be sure it points to the Keytool in the JDK.</p> <p>If you will release your application to the public, you will also need to have @@ -191,46 +196,50 @@ in the JDK. </p> <p>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.</p> +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.</p> -<p>The SDK tools create the debug keystore/key with predetermined names/passwords;</p> +<p>The SDK tools create the debug keystore/key with predetermined names/passwords:</p> <ul> -<li>Keystore name – "debug.keystore"</li> -<li>Keystore password – "android"</li> -<li>Key alias – "androiddebugkey"</li> -<li>Key password – "android"</li> -<li>CN – "CN=Android Debug,O=Android,C=US"</li> +<li>Keystore name: "debug.keystore"</li> +<li>Keystore password: "android"</li> +<li>Key alias: "androiddebugkey"</li> +<li>Key password: "android"</li> +<li>CN: "CN=Android Debug,O=Android,C=US"</li> </ul></p> <p>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 -<strong>Windows</strong> > <strong>Prefs</strong> > -<strong>Android</strong> > <strong>Build</strong>. 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).</p> +debug key (as described above). (To do so in Eclipse/ADT, go to +<strong>Windows</strong> > <strong>Preferences</strong> > +<strong>Android</strong> > <strong>Build</strong>.) </p> -<p class="note"><strong>Note:</strong> You <em>cannot</em> release your application +<p class="caution"><strong>Caution:</strong> You <em>cannot</em> release your application to the public when signed with the debug certificate.</p> <h3>Eclipse Users</h3> -<p>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.</p> +<p>If you are developing in Eclipse/ADT (and have set up Keytool as described above in +<a href="#setup">Basic Setup for Signing</a>), +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.</p> <h3>Ant Users</h3> -<p>If you use Ant to build your .apk files, debug signing mode -is enabled by using the <code>debug</code> option, assuming that you are using a -<code>build.xml</code> file generated by the -<code>android</code> tool. When you run <code>ant debug</code> to +<p>If you are using Ant to build your .apk files, debug signing mode +is enabled by using the <code>debug</code> option with the <code>ant</code> command +(assuming that you are using a <code>build.xml</code> file generated by the +<code>android</code> tool). When you run <code>ant debug</code> 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 <code>zipalign</code> tool. No other action on your part is needed. Read -<a href="{@docRoot}guide/developing/other-ide.html#DebugMode">Developing In Other IDEs: Building +<a href="{@docRoot}guide/developing/other-ide.html#DebugMode">Developing In Other IDEs: Building in debug mode</a> for more information.</p> @@ -268,51 +277,20 @@ certificate</a>. </p> <p>When your application is ready for release to other users, you must:</p> <ol> - <li>Compile the application in release mode</li> - <li>Obtain a suitable private key</li> - <li>Sign the application with your private key</li> + <li><a href="#cert">Obtain a suitable private key</a></li> + <li><a href="#releasecompile">Compile the application in release mode</li> + <li><a href="#signapp">Sign your application with your private key</a></li> + <li><a href="#align">Align the final APK package</a></li> </ol> -<p>The sections below provide information about how to perform these steps.</p> - -<p>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 -<a href="#ExportWizard">Compiling and signing with Eclipse ADT</a>.</p> - - -<h3 id="releasecompile">Compiling for release</h3> - -<p>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.</p> - -<p class="warning"><strong>Note:</strong> -You can not release your application unsigned, or signed with the debug key.</p> +<p>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 <a href="#ExportWizard">Compile and sign with Eclipse ADT</a>.</p> -<h4>Eclipse users</h4> -<p>To export an <em>unsigned</em> .apk from Eclipse, right-click the project in the Package -Explorer and select <strong>Android Tools</strong> > <strong>Export Unsigned Application -Package</strong>. Then simply specify the file location for the unsigned .apk. -(Alternatively, open your <code>AndroidManifest.xml</code> file in Eclipse, open -the <em>Overview</em> tab, and click <strong>Export an unsigned .apk</strong>.)</p> - -<p>You can also combine the compiling and signing steps with the Export Wizard. See -<a href="#ExportWizard">Compiling and signing with Eclipse ADT</a>.</p> -<h4>Ant users</h4> - -<p>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:</p> - -<pre>$ ant release</pre> - -<p>The build script compiles the application .apk without signing it.</p> - - -<h3 id="cert">Obtaining a Suitable Private Key</h3> +<h3 id="cert">1. Obtain a suitable private key</h3> <p>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 <a href="#setup">Basic Setup</a>.</p> command and pass any of the options listed below (and any others, as needed). </p> -<p class="warning"><strong>Note:</strong> Before you run Keytool, make sure to read +<p class="warning"><strong>Warning:</strong> Keep your private key secure. +Before you run Keytool, make sure to read <a href="#secure-key">Securing Your Private Key</a> 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.</p></td> </tr> </table> - <p>Here's an example of a Keytool command that generates a private key:</p> <pre>$ keytool -genkey -v -keystore my-release-key.keystore @@ -415,9 +393,57 @@ href="http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security"> http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security</a></p> -<h3 id="signapp">Signing your application</h3> -<p>When you are ready to actually sign your .apk for release, you can do so +<h3 id="releasecompile">2. Compile the application in release mode</h3> + +<p>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.</p> + +<p class="caution"><strong>Caution:</strong> +You can not release your application unsigned, or signed with the debug key.</p> + +<h4>With Eclipse</h4> + +<p>To export an <em>unsigned</em> .apk from Eclipse, right-click the project in the Package +Explorer and select <strong>Android Tools</strong> > <strong>Export Unsigned Application +Package</strong>. Then specify the file location for the unsigned .apk. +(Alternatively, open your <code>AndroidManifest.xml</code> file in Eclipse, open +the <em>Overview</em> tab, and click <strong>Export an unsigned .apk</strong>.)</p> + +<p>Note that you can combine the compiling and signing steps with the Export Wizard. See +<a href="#ExportWizard">Compiling and signing with Eclipse ADT</a>.</p> + +<h4>With Ant</h4> + +<p>If you are using Ant, you can enable release mode by using the <code>release</code> option +with the <code>ant</code> command. For example, if you are running Ant from the +directory containing your {@code build.xml} file, the command would look like this:</p> + +<pre>ant release</pre> + +<p>By default, the build script compiles the application .apk without signing it. The output file +in your project {@code bin/} will be <code><em><your_project_name></em>-unsigned.apk</code>. +Because the application .apk is still unsigned, you must manually sign it with your private +key and then align it using {@code zipalign}.</p> + +<p>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 +<code>ant release</code>, it will sign the package and then align it. The final output +file in {@code bin/} will instead be +<code><em><your_project_name></em>-release.apk</code>. 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 <a href="{@docRoot}guide/developing/other-ide.html#ReleaseMode">Developing In Other +IDEs: Building in release mode</a>.</p> + + + +<h3 id="signapp">3. Sign your application with your private key</h3> + +<p>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 <a href="#setup">Basic Setup</a>. Also, make sure that the keystore containing your private key is available.</p> @@ -492,29 +518,63 @@ key.</p> http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security</a></p> -<h3 id="ExportWizard">Compiling and signing with Eclipse ADT</h3> +<h3 id="align">4. Align the final APK package</h3> -<p>When using Eclipse with ADT, you can use the Export Wizard to +<p>Once you have signed the .apk with your private key, run <code>zipalign</code> 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.</p> + +<p>The <code>zipalign</code> tool is provided with the Android SDK, inside the +<code>tools/</code> directory. To align your signed .apk, execute:</p> + +<pre>zipalign -v 4 <em>your_project_name</em>-unaligned.apk <em>your_project_name</em>.apk</pre> + +<p>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.</p> + +<p class="caution"><strong>Caution:</strong> Your input .apk must be signed with your +private key <strong>before</strong> you optimize the package with {@code zipalign}. +If you sign it after using {@code zipalign}, it will undo the alignment.</p> + +<p>For more information, read about the +<a href="{@docRoot}guide/developing/tools/zipalign.html">zipalign</a> tool. + + +<h3 id="ExportWizard">Compile and sign with Eclipse ADT</h3> + +<p>If you are using Eclipse with the ADT plugin, you can use the Export Wizard to export a <em>signed</em> .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 <a href=#setup">Basic Setup for Signing</a>.</p> -<p>To create a signed .apk, right-click the project in the Package -Explorer and select <strong>Android Tools > Export Signed Application Package</strong>. -(Alternatively, open your <code>AndroidManifest.xml</code> file in Eclipse, open -the <em>Overview</em> tab, and click <strong>Use the Export Wizard</strong>.) -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.</p> - -<p>When you complete the Export Wizard, you'll -have a signed .apk that's ready for distribution.</p> +<p>To create a signed and aligned .apk in Eclipse:</p> + +<ol> + <li>Select the project in the Package +Explorer and select <strong>File > Export</strong>.</li> + <li>Open the Android folder, select Export Android Application, + and click <strong>Next</strong>. + <p>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).</p> + <li>Complete the Export Wizard and your application will be compiled, + signed, aligned, and ready for distribution.</li> +</ol> + <h2 id="secure-key">Securing Your Private Key</h2> diff --git a/docs/html/guide/publishing/preparing.jd b/docs/html/guide/publishing/preparing.jd index b4eaea3..5357166 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. </li> </ol> -<p>For more information about signing and your private key, see <a -href="{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a>.</p> - - <h2 id="compile">Compile your application</h2> <p>When you've prepared your application as described in the previous sections, -you can compile your application for release. </p> +you can compile your application for release.</p> + <h2 id="post-compile">After compiling your application</h2> <h3 id="signapp">8. Sign your application</h3> -<p>Sign your application using your private key. Signing your application -correctly is critically important. Please see -<a href="{@docRoot}guide/publishing/app-signing.html">Signing Your +<p>Sign your application using your private key and then +align it with the {@code zipalign} tool. Signing your application +correctly is critically important. Please see +<a href="{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a> for complete information. </p> <h3 id="testapp">9. Test your compiled and signed application</h3> diff --git a/docs/html/guide/publishing/versioning.jd b/docs/html/guide/publishing/versioning.jd index d0eafcd..0bec658 100644 --- a/docs/html/guide/publishing/versioning.jd +++ b/docs/html/guide/publishing/versioning.jd @@ -17,7 +17,7 @@ page.title=Versioning Your Applications <ol> <li><a href="#appversion">Setting Application Version</a></li> -<li><a href="#minsdkversion">Specifying Minimum System API Version</a> +<li><a href="#minsdkversion">Specifying Your Application's System API Requirements</a> </ol> @@ -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}. </p> -<h2 id="minsdkversion">Specifying Minimum System API Version</h2> +<h2 id="minsdkversion">Specifying Your Application's System API Requirements</h2> <p>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. </p> -<p>To specify the minimum system version in the manifest, use this attribute: </p> +<p>To specify API Level requirements, add a <code><uses-sdk></code> +element in the application's manifest, with one or more of these attributes: </p> <ul> -<li><code>android:minSdkVersion</code> — An integer value corresponding to -the code version of the Android platform. -<p>When preparing to install an application, the system checks the value of this +<li><code>android:minSdkVersion</code> — The minimum version +of the Android platform on which the application will run, specified +by the platform's API Level identifier. </li> +<li><code>android:maxSdkVersion</code> — The maximum version +of the Android platform on which the application is designed to run, +specified by the platform's API Level identifier. </li> +</ul> + +<p>When preparing to install your application, the system checks the value of this attribute and compares it to the system version. If the <code>android:minSdkVersion</code> value is greater than the system version, the -system aborts the installation of the application. </p> +system aborts the installation of the application. Similarly, the system +installs your application only if its <code>android:maxSdkVersion</code> +is compatible with the platform version.</p> -<p>If you do not specify this attribute in your manifest, the system assumes -that your application is compatible with all platform versions.</p></li> -</ul> +<p>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. </p> <p>To specify a minimum platform version for your application, add a <code><uses-sdk></code> element as a child of <code><manifest></code>, then define the <code>android:minSdkVersion</code> as an attribute. </p> -<p>For more information, also see the <a href="{@docRoot}sdk/android-1.1.html">Android System Image 1.1 Version Notes</a>.</p> +<p>For more information, see the <a +href="{@docRoot}guide/developing/manifest/uses-sdk-element.html"><code><uses- +sdk></code></a> manifest element documentation and the <a +href="{@docRoot}guide/appendix/api-levels.html">API Levels</a> document.</p> diff --git a/docs/html/guide/topics/intents/intents-filters.jd b/docs/html/guide/topics/intents/intents-filters.jd index fd20ca1..962a001 100644 --- a/docs/html/guide/topics/intents/intents-filters.jd +++ b/docs/html/guide/topics/intents/intents-filters.jd @@ -16,10 +16,11 @@ page.title=Intents and Intent Filters <h2>In this document</h2> <ol> <li><a href="#iobjs">Intent Objects</a></li> -<li><a href="#ires">Intent Resolution</a>, including:</li> +<li><a href="#ires">Intent Resolution</a></li> <li style="margin-left: 2em"><a href="#ifs">Intent filters</a></li> <li style="margin-left: 2em"><a href="#ccases">Common cases</a></li> <li style="margin-left: 2em"><a href="#imatch">Using intent matching</a></li> +<li><a href="#npex">Note Pad Example</a></li> </ol> </div> </div> @@ -31,7 +32,7 @@ broadcast receivers — are activated through messages, called <i>intents</i Intent messaging is a facility for late run-time binding between components in the same or different applications. The intent itself, an {@link android.content.Intent} object, is a passive data structure holding an abstract description of an operation -to be performed — or, in the case of broadcasts, a description of something +to be performed — or, often in the case of broadcasts, a description of something that has happened and is being announced. There are separate mechanisms for delivering intents to each type of component: </p> @@ -40,7 +41,9 @@ delivering intents to each type of component: <li>An Intent object is passed to <code>{@link android.content.Context#startActivity Context.startActivity()}</code> or <code>{@link android.app.Activity#startActivityForResult Activity.startActivityForResult()}</code> to launch an activity or get an existing -activity to do something new.</li> +activity to do something new. (It can also be passed to +<code>{@link android.app.Activity#setResult(int, Intent) Activity.setResult()}</code> +to return information to the activity that called {@code startActivityForResult()}.)</li> <li><p>An Intent object is passed to <code>{@link android.content.Context#startService Context.startService()}</code> to initiate a service or deliver new instructions to an @@ -380,22 +383,12 @@ component's filters. <p> 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. -</p> - -<p> -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 <code>{@link android.content.Context#registerReceiver(BroadcastReceiver, IntentFilter, String, -Handler) Context.registerReceiver()}</code>; 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 <a href="#npex">Note Pad Example</a> +section, later.) </p> <div class="sidebox-wrapper"> @@ -413,6 +406,18 @@ name the component as the target. </div> <p> +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><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> +elements. (The one exception would be filters for +broadcast receivers that are registered dynamically by calling <code>{@link android.content.Context#registerReceiver(BroadcastReceiver, IntentFilter, String, +Handler) Context.registerReceiver()}</code>; they are directly created as +IntentFilter objects.) +</p> + +<p> 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. To be delivered to the component that owns the filter, it must pass all three tests. @@ -429,8 +434,11 @@ Each of the three tests is described in detail below: <dl> <dt><b>Action test</b></dt> -<dd>An {@code <intent-filter>} element in the manifest file lists actions -as {@code <action>} subelements. For example: +<dd>An +<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> +element in the manifest file lists actions as +<code><a href="{@docRoot}guide/topics/manifest/action-element.html"><action></a></code> +subelements. For example: <pre><intent-filter . . . > <action android:name="com.example.project.SHOW_CURRENT" /> @@ -464,8 +472,9 @@ contains at least one action.</p></li> </dd> <dt><b>Category test</b></dt> -<dd>An {@code <intent-filter>} element also lists categories as subelements. -For example: +<dd>An +<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> +element also lists categories as subelements. For example: <pre><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: <pre><intent-filter . . . > - <data android:type="video/mpeg" android:scheme="http" . . . /> - <data android:type="audio/mpeg" android:scheme="http" . . . /> + <data android:mimeType="video/mpeg" android:scheme="http" . . . /> + <data android:mimeType="audio/mpeg" android:scheme="http" . . . /> . . . </intent-filter></pre> <p> -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 +<code><a href="{@docRoot}guide/topics/manifest/data-element.html"><data></a></code> +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: </p> @@ -607,7 +618,7 @@ for example, tells Android that the component can get image data from a content provider and display it: </p> -<pre><data android:type="image/*" /></pre> +<pre><data android:mimeType="image/*" /></pre> <p> 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. </p> +<h2 id="npex">Note Pad Example</h2> + +<p> +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 +<a href="{@docRoot}guide/samples/index.html">Tutorials and Sample Code</a> +section <a href="{@docRoot}guide/samples/NotePad/index.html">here</a>.) +</p> + +<p> +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: +</p> + +<pre><manifest xmlns:android="http://schemas.android.com/apk/res/android" + package="com.example.android.notepad"> + <application android:icon="@drawable/app_notes" + android:label="@string/app_name" > + + <provider android:name="NotePadProvider" + android:authorities="com.google.provider.NotePad" /> + + <activity android:name="NotesList" android:label="@string/title_notes_list"> + <intent-filter> + <action android:name="android.intent.action.MAIN" /> + <category android:name="android.intent.category.LAUNCHER" /> + </intent-filter> + <intent-filter> + <action android:name="android.intent.action.VIEW" /> + <action android:name="android.intent.action.EDIT" /> + <action android:name="android.intent.action.PICK" /> + <category android:name="android.intent.category.DEFAULT" /> + <data android:mimeType="vnd.android.cursor.dir/vnd.google.note" /> + </intent-filter> + <intent-filter> + <action android:name="android.intent.action.GET_CONTENT" /> + <category android:name="android.intent.category.DEFAULT" /> + <data android:mimeType="vnd.android.cursor.item/vnd.google.note" /> + </intent-filter> + </activity> + + <activity android:name="NoteEditor" + android:theme="@android:style/Theme.Light" + android:label="@string/title_note" > + <intent-filter android:label="@string/resolve_edit"> + <action android:name="android.intent.action.VIEW" /> + <action android:name="android.intent.action.EDIT" /> + <action android:name="com.android.notepad.action.EDIT_NOTE" /> + <category android:name="android.intent.category.DEFAULT" /> + <data android:mimeType="vnd.android.cursor.item/vnd.google.note" /> + </intent-filter> + <intent-filter> + <action android:name="android.intent.action.INSERT" /> + <category android:name="android.intent.category.DEFAULT" /> + <data android:mimeType="vnd.android.cursor.dir/vnd.google.note" /> + </intent-filter> + </activity> + + <activity android:name="TitleEditor" + android:label="@string/title_edit_title" + android:theme="@android:style/Theme.Dialog"> + <intent-filter android:label="@string/resolve_title"> + <action android:name="com.android.notepad.action.EDIT_TITLE" /> + <category android:name="android.intent.category.DEFAULT" /> + <category android:name="android.intent.category.ALTERNATIVE" /> + <category android:name="android.intent.category.SELECTED_ALTERNATIVE" /> + <data android:mimeType="vnd.android.cursor.item/vnd.google.note" /> + </intent-filter> + </activity> + + </application> +</manifest></pre> + +<p> +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: +</p> + +<ol> +<li><pre><intent-filter> + <action android:name="android.intent.action.MAIN" /> + <category android:name="android.intent.category.LAUNCHER" /> +</intent-filter></pre> + +<p> +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. +</p></li> + +<li><pre><intent-filter> + <action android:name="android.intent.action.VIEW" /> + <action android:name="android.intent.action.EDIT" /> + <action android:name="android.intent.action.PICK" /> + <category android:name="android.intent.category.DEFAULT" /> + <data android:mimeType="vnd.android.cursor.dir/vnd.google.note" /> +</intent-filter></pre> + +<p> +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). +</p> + +<p> +The {@code mimeType} attribute of the +<code><a href="{@docRoot}guide/topics/manifest/data-element.html"><data></a></code> +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. +</p> + +<p> +Note also the {@code DEFAULT} category supplied in this filter. It's +there because the <code>{@link android.content.Context#startActivity +Context.startActivity()}</code> and +<code>{@link android.app.Activity#startActivityForResult +Activity.startActivityForResult()}</code> methods treat all intents +as if they contained the {@code DEFAULT} category — with just +two exceptions: +</p> + +<ul> +<li>Intents that explicitly name the target activity</li> +<li>Intents consisting of the {@code MAIN} action and {@code LAUNCHER} +category</li> +</ul> + +<p> +Therefore, the {@code DEFAULT} category is <em>required</em> for all +filters — except for those with the {@code MAIN} action and +{@code LAUNCHER} category. (Intent filters are not consulted for +explicit intents.) +</p></li> + +<li><pre><intent-filter> + <action android:name="android.intent.action.GET_CONTENT" /> + <category android:name="android.intent.category.DEFAULT" /> + <data android:mimeType="vnd.android.cursor.item/vnd.google.note" /> +</intent-filter></pre> + +<p> +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 +<code>{@link android.app.Activity#startActivityForResult +startActivityForResult()}</code> 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. +</p> + +<p> +The data type, <code>vnd.android.cursor.item/vnd.google.note</code>, +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}). +</p> + +<p> +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. +</p></li> +</ol> + +<p> +Given these capabilities, the following intents will resolve to the +NotesList activity: +</p> + +<dl style="margin-left: 2em"> +<dt>action: <code>android.intent.action.MAIN</code></dt> +<dd>Launches the activity with no data specified.</dd> + +<dt>action: <code>android.intent.action.MAIN</code> +<br/>category: <code>android.intent.category.LAUNCHER</code></dt> +<dd> 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.</dd> + +<dt>action: <code>android.intent.action.VIEW</code> +<br/>data: <code>content://com.google.provider.NotePad/notes</code></dt> +<dd>Asks the activity to display a list of all the notes under +<code>content://com.google.provider.NotePad/notes</code>. The user can then +browse through the list and get information about the items in it.</dd> + +<dt>action: <code>android.intent.action.PICK</code> +<br/>data: <code>content://com.google.provider.NotePad/notes</code></dt> +<dd>Asks the activity to display a list of the notes under +<code>content://com.google.provider.NotePad/notes</code>. +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.</dd> + +<dt>action: <code>android.intent.action.GET_CONTENT</code> +<br/>data type: <code>vnd.android.cursor.item/vnd.google.note</code></dt> +<dd>Asks the activity to supply a single item of Note Pad data.</dd> +</dl> + +<p> +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: + +<ol> +<li><pre><intent-filter android:label="@string/resolve_edit"> + <action android:name="android.intent.action.VIEW" /> + <action android:name="android.intent.action.EDIT" /> + <action android:name="com.android.notepad.action.EDIT_NOTE" /> + <category android:name="android.intent.category.DEFAULT" /> + <data android:mimeType="vnd.android.cursor.item/vnd.google.note" /> +</intent-filter></pre> + +<p> +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 <code>vnd.android.cursor.item/vnd.google.note</code> — +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. +</p> + +<p> +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. +</p></li> + +<li><pre><intent-filter> + <action android:name="android.intent.action.INSERT" /> + <category android:name="android.intent.category.DEFAULT" /> + <data android:mimeType="vnd.android.cursor.dir/vnd.google.note" /> +</intent-filter></pre> + +<p> +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 +<code>vnd.android.cursor.dir/vnd.google.note</code> — that +is, the URI for the directory where the note should be placed. +</p></li> +</ol> + +<p> +Given these capabilities, the following intents will resolve to the +NoteEditor activity: +</p> + +<dl style:"margin-left: 2em"> +<dt>action: <code>android.intent.action.VIEW</code> +<br/>data: <code>content://com.google.provider.NotePad/notes/<var>ID</var></code></dt> +<dd>Asks the activity to display the content of the note identified +by {@code <var>ID</var>}. (For details on how {@code content:} URIs +specify individual members of a group, see +<a href="{@docRoot}guide/topics/provider/content-providers.html">Content Providers</a>.) + +<dt>action: <code>android.intent.action.EDIT</code> +<br/>data: <code>content://com.google.provider.NotePad/notes/<var>ID</var></code></dt> +<dd>Asks the activity to display the content of the note identified +by {@code <var>ID</var>}, 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.</dd> + +<dt>action: <code>android.intent.action.INSERT</code> +<br/>data: <code>content://com.google.provider.NotePad/notes</code></dt> +<dd>Asks the activity to create a new, empty note in the notes list at +<code>content://com.google.provider.NotePad/notes</code> +and allow the user to edit it. If the user saves the note, its URI +is returned to the caller. +</dd> +</dl> + +<p>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: +</p> + +<pre><intent-filter android:label="@string/resolve_title"> + <action android:name="com.android.notepad.action.EDIT_TITLE" /> + <category android:name="android.intent.category.DEFAULT" /> + <category android:name="android.intent.category.ALTERNATIVE" /> + <category android:name="android.intent.category.SELECTED_ALTERNATIVE" /> + <data android:mimeType="vnd.android.cursor.item/vnd.google.note" /> +</intent-filter></pre> + +<p> +The single intent filter for this activity uses a custom action called +"<code>com.android.notepad.action.EDIT_TITLE</code>". It must be invoked on +a specific note (data type <code>vnd.android.cursor.item/vnd.google.note</code>), +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. +</p> + +<p> +In addition to supporting the usual {@code DEFAULT} category, the title +editor also supports two other standard categories: +<code>{@link android.content.Intent#CATEGORY_ALTERNATIVE ALTERNATIVE}</code> +and <code>{@link android.content.Intent#CATEGORY_SELECTED_ALTERNATIVE +SELECTED_ALTERNATIVE}</code>. +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 +<code>android:label="@string/resolve_title"</code>) 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 +<code>{@link android.content.pm.PackageManager#queryIntentActivityOptions +PackageManager.queryIntentActivityOptions()}</code> and +<code>{@link android.view.Menu#addIntentOptions Menu.addIntentOptions()}</code> +methods.) +</p> + +<p> +Given these capabilities, the following intent will resolve to the +TitleEditor activity: +</p> + +<dl style="margin-left: 2em"> +<dt>action: <code>com.android.notepad.action.EDIT_TITLE</code> +<br/>data: <code>content://com.google.provider.NotePad/notes/<var>ID</var></code></dt> +<dd>Asks the activity to display the title associated with note <var>ID</var>, and +allow the user to edit the title.</dd> +</dl> + diff --git a/docs/html/guide/topics/manifest/manifest-element.jd b/docs/html/guide/topics/manifest/manifest-element.jd index a9d1090..48e598a 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}".</dd> <dt><a name="package"></a>{@code package}</dt> <dd>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 <code>com.google.app.<i>application_name</i></code>. +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 +<code>com.google.app.<i>application_name</i></code>. <p> 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 3942f95..98892f1 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 <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#wprmsn">writePermission</a></code>, and <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#prmsn">permission</a></code> 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 00797ed..3fb0172 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).</p> -<p>Currently supported densities:</p> -<ul> - <li>Low density: 120 dpi</li> - <li>Medium density: 160 dpi</li> - <li>High density: 240 dpi</li> -</ul> - -<p>Table of display types:</p> - -<table> -<tr> - <th></th><th>Low Density</th><th>Medium Density</th><th>High Density</th> -</tr> -<tr> - <th>Small Screen</th> - <td>QVGA</td> - <td>n/a</td> - <td>VGA</td> -</tr> -<tr> - <th>Normal Screen</th> - <td>WQVGA</td> - <td>HVGA</td> - <td>WVGA, FWVGA</td> -</tr> -<tr> - <th>Large Screen</th> - <td>n/a</td> - <td>VGA, WVGA, FWVGA</td> - <td>n/a</td> -</tr> -</table> - -</dd> +<p>For more information, see +<a href="{@docRoot}guide/practices/screens_suppport.html">Multiple Screens Support</a>.</p> <dt>attributes:</dt> @@ -116,6 +84,7 @@ The screen density is expressed as dots-per-inch (dpi).</p> <dt>see also:</dt> <dd> <ul> + <li><a href="{@docRoot}guide/practices/screens_suppport.html">Multiple Screens Support</a></li> <li>{@link android.util.DisplayMetrics}</li> </ul> </dd> diff --git a/docs/html/guide/topics/manifest/uses-sdk-element.jd b/docs/html/guide/topics/manifest/uses-sdk-element.jd index ee8d03d..aa1e8ae 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).</p> <dd> <dl class="attr"> <dt><a name="min"></a>{@code android:minSdkVersion}</dt> - <dd>An integer designating the minimum level of the Android API that's required - for the application to run. + <dd>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. - <p>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.</p> - - <p>If you do not declare this attribute, then a value of "1" is assumed, which + <p class="caution"><strong>Caution:</strong> + 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 <em>not</em> universally compatible (for instance if it uses APIs - introduced in Android 1.5) and you have not declared the proper <code>minSdkVersion</code>, - 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 <em>not</em> compatible with all versions (for instance, it uses APIs + introduced in API Level 3) and you have not declared the proper <code>minSdkVersion</code>, + 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 <code>minSdkVersion</code> attribute.</p> </dd> <dt><a name="max"></a>{@code android:maxSdkVersion}</dt> - <dd>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.</p> - - <p>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.</p> + <dd>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. <p>Introduced in: API Level 4</p> </dd> diff --git a/docs/html/guide/topics/resources/available-resources.jd b/docs/html/guide/topics/resources/available-resources.jd index 2a6a6ac..f5f1475 100644 --- a/docs/html/guide/topics/resources/available-resources.jd +++ b/docs/html/guide/topics/resources/available-resources.jd @@ -36,6 +36,7 @@ parent.link=index.html </ol> </li> <li><a href="#stylesandthemes">Styles and Themes</a></li> + <li><a href="#Searchable">Searchable</a></li> </ol> </div> @@ -86,7 +87,7 @@ XML files such as <a href="#layoutresources">layouts</a>.</p> <code><color></code> tags. </p> <p> - <strong>Resource source file location</strong>: res/values/<em>colors</em>.xml (file name is arbitrary) + <strong>Resource source file location</strong>: {@code res/values/<em>colors</em>.xml} (File name is arbitrary.) </p> <p> <strong>Compiled resource datatype:</strong> Resource pointer to a Java int. @@ -183,7 +184,7 @@ tags. <strong>Source file format:</strong> XML file requiring a <code><?xml version="1.0" encoding="utf-8"?></code> declaration, and a root <code><resources></code> element containing one or more <code><string></code> tags. </p> <p> - <strong>Resource source file location</strong>: res/values/<em>strings</em>.xml (file name is arbitrary) + <strong>Resource source file location</strong>: {@code res/values/<em>strings</em>.xml} (File name is arbitrary.) </p> <p> <strong>Compiled resource datatype:</strong> Resource pointer to a Java CharSequence. @@ -338,8 +339,8 @@ version="1.0" encoding="utf-8"?></code> declaration, and a root <code><resources></code> element containing one or more <code><dimen></code> tags.</p> -<p><strong>Resource source file location</strong>: res/values/dimens.xml (File -name is arbitrary; standard practice is to put all dimensions in one file +<p><strong>Resource source file location</strong>: {@code res/values/dimens.xml} (File +name is arbitrary, but standard practice is to put all dimensions in one file devoted to dimensions.)</p> <p><strong>Compiled resource datatype:</strong> Resource pointer to a dimension.</p> @@ -424,7 +425,7 @@ res/drawable/my_picture.png would be referenced as R.drawable.my_picture).</p> <strong>Source file formats:</strong> png (preferred), jpg (acceptable), gif (discouraged). One resource per file. </p> <p> - <strong>Resource file location</strong>: res/drawable/<em>some_file</em>.png or <em>some_file</em>.jpg or <em>some_file</em>.gif. + <strong>Resource file location</strong>: {@code res/drawable/<em>some_file</em>.png} </p> <p> <strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.graphics.drawable.BitmapDrawable BitmapDrawable}. @@ -453,7 +454,8 @@ version="1.0" encoding="utf-8"?></code> declaration, and a root <code><resources></code> element containing one or more <code><drawable></code> tags.</p> <p> - <strong>Resource source file location</strong>: res/values/colors.xml (File name is arbitrary; standard practice is to put the PaintDrawable items in the file along with the <a href="resources-i18n.html#numericcolorresources">numeric color values</a>.) + <strong>Resource source file location</strong>: {@code res/values/colors.xml} (File name is arbitrary, but standard practice is to put the PaintDrawable + items in the file along with the <a href="resources-i18n.html#numericcolorresources">numeric color values</a>.) </p> <p> <strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.graphics.drawable.PaintDrawable}. @@ -540,7 +542,7 @@ tv.setBackground(redDrawable); <strong>Source file format:</strong> PNG — one resource per file </p> <p> - <strong>Resource source file location</strong>: res/drawable/<em>some_name</em>.9.png (must end in .9.png) + <strong>Resource source file location</strong>: {@code res/drawable/<em>some_name</em>.9.png} (Filename must end in {@code .9.png}) </p> <p> <strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.graphics.drawable.NinePatchDrawable NinePatchDrawable}. @@ -573,7 +575,7 @@ in <a href="{@docRoot}guide/topics/graphics/2d-graphics.html#nine-patch">2D Grap <strong>Source file format:</strong> XML file, one resource per file, one root tag with no <code><?xml></code> declaration </p> <p> - <strong>Resource file location</strong>: res/anim/<em>some_file</em>.xml + <strong>Resource file location</strong>: {@code res/anim/<em>some_file</em>.xml} </p> <p> <strong>Compiled resource datatype:</strong> Resource pointer to an {@link android.view.animation.Animation}. @@ -906,7 +908,7 @@ res/layout/<em>some_file</em>.xml.</p> </p> <pre> <<em>ViewGroupClass</em> xmlns:android="http://schemas.android.com/apk/res/android" - id="@+id/<em>string_name</em>" (attributes)> + android:id="@+id/<em>string_name</em>" (attributes)> <<em>widget</em> or other nested <em>ViewGroupClass</em>>+ <requestFocus/>(0 or 1 per layout file, assigned to any element) </<em>ViewGroupClass</em>> @@ -917,7 +919,7 @@ res/layout/<em>some_file</em>.xml.</p> </dt> <dd> <p>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 <code><TextView></code> elements inside a <code><ListLayout></code>).</p> - <p>If a class derives from another class, the XML element inherits all the attributes from the element that it "derives" from. So, for example, <code><EditText></code> is the corresponding XML element for the EditText class. It exposes its own unique attributes (<code>EditText_numeric</code>), as well as all attributes supported by <code><TextView></code> and <code><View></code>. For the <em>id</em> attribute of a tag in XML, you should use a special syntax: "@+id/<em>somestringvalue</em>". 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: <code><TextView id="@+id/nameTextbox"/></code>, and refer to it this way in Java: <code>findViewById(R.id.nameTextbox)</code>. All elements support the following values:</p> + <p>If a class derives from another class, the XML element inherits all the attributes from the element that it "derives" from. So, for example, <code><EditText></code> is the corresponding XML element for the EditText class. It exposes its own unique attributes (<code>EditText_numeric</code>), as well as all attributes supported by <code><TextView></code> and <code><View></code>. For the <em>id</em> attribute of a tag in XML, you should use a special syntax: "@+id/<em>somestringvalue</em>". 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: <code><TextView android:id="@+id/nameTextbox"/></code>, and refer to it this way in Java: <code>findViewById(R.id.nameTextbox)</code>. All elements support the following values:</p> <ul> <li> <em>id</em> - An ID value used to access this element in Java. Typically you will use the syntax @+id/<em>string_name</em> to generate an ID for you in the id.xml file if you haven't created one yourself. @@ -1005,7 +1007,7 @@ res/layout/<em>some_file</em>.xml.</p> 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/<em>some_file</em>.xml.</p> <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); <strong>Java implementation file</strong> - The implementation file. The class must extend {@link android.view.View View} or a subclass. See LabelView.java in ApiDemos. </li> <li> - <strong>res/values/attrs.xml</strong> - 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 <code><declare-styleable id=<em>your_java_class_name</em>></code>. See res/layout/attrs.xml in ApiDemos. + <strong>res/values/attrs.xml</strong> - 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 <code><declare-styleable name=<em>your_java_class_name</em>></code>. See res/values/attrs.xml in ApiDemos. </li> <li> <strong>res/layout/<em>your_class</em>.xml</strong> [<em>optional</em>] - 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); <strong>Source file format:</strong> XML file without an <code><?xml></code> declaration, and a <code><resources></code> root element containing one or more custom element tags. </p> <p> - <strong>Resource file location</strong>: res/values/<em>attrs</em>.xml (file name is arbitrary). + <strong>Resource file location</strong>: {@code res/values/<em>attrs</em>.xml} (File name is arbitrary.) </p> <p> <strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.view.View} (or subclass) resource. @@ -1084,7 +1086,7 @@ setContentView(R.layout.main_screen); <strong>Source file format:</strong> XML file requiring a <code><?xml version="1.0" encoding="utf-8"?></code> declaration, and a root <code><resources></code> element containing one or more <code><style></code> tags. </p> <p> - <strong>Resource source file location</strong>: 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. + <strong>Resource source file location</strong>: {@code res/values/styles.xml} (File name is arbitrary, but standard practice is to put all styles into a file named styles.xml.) </p> <p> <strong>Compiled resource datatype:</strong> Resource pointer to a Java CharSequence. @@ -1133,3 +1135,317 @@ setContentView(R.layout.main_screen); <p>For examples of how to declare and apply styles and themes, read <a href="{@docRoot}guide/topics/ui/themes.html">Applying Styles and Themes</a>.</p> + + + +<h2 id="Searchable">Searchable</h2> + +<p>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.</p> + +<p>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 +<!-- <a href="{@docRoot}guide/topics/search/index.html">Search</a> --> +{@link android.app.SearchManager}.</p> + +<p> + <strong>Source file format:</strong> + XML file requiring a <code><?xml version="1.0" encoding="utf-8"?></code> + declaration, and a root <code><searchable></code> element. +</p> + +<p> + <strong>Resource source file location</strong>: {@code res/xml/searchable.xml} + (The file name is arbitrary, but standard practice is to use searchable.xml.) +</p> + +<p> + <strong>Compiled resource datatype:</strong> + Resource pointer to an xml object. +</p> + +<p> + <strong>Resource reference name:</strong> +</p> + +<ul> + <li> + <strong>Java:</strong> + <code>R.xml.<em>filename</em></code>. + </li> + <li> + <strong>XML:</strong> + <code>@[<em>package</em>:]xml/<em>filename</em></code> (e.g., <code>@xml/searchable</code>). + </li> +</ul> + +<p> + <strong>Syntax</strong> +</p> + +<pre> +<searchable xmlns:android="http://schemas.android.com/apk/res/android + android:label="@string/search_label" + ... > + <em><actionkey + android:keycode="KEYCODE_CALL" + ... ></em> +</searchable> +</pre> + +<dl> + <dt> + <searchable> + </dt> + <dd> + Defines all application search configurations, including settings for text and voice searches + performed within the application. It accepts the following attributes: + <ul> + <li> + <em>label</em> - <strong>Required</strong>. This is the name for your application, as it + will appear to the user. This will be visible only if <em>searchMode</em> is set to + "showSearchLabelAsBadge" (see below). + </li> + <li> + <em>hint</em> - 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"). + </li> + <li> + <em>searchMode</em> - If provided and non-zero, this sets additional modes for control + of the search presentation. The following mode values are accepted: + <ul> + <li> + <em>showSearchLabelAsBadge</em> - If set, this enables the display of the + search target (label) within the search bar. + </li> + <li> + <em>queryRewriteFromData</em> - 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. + </li> + <li> + <em>queryRewriteFromText</em> - 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. + </li> + </ul> + <p>More than one of the above values for <em>searchMode</em> can be used at once. For + example, you can declare two modes at once, like this: + <code>searchMode="queryRewriteFromData|queryRewriteFromText"</code> + </li> + <li> + <em>inputType</em> - 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. + </li> + <li> + <em>imeOptions</em> - 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. + </li> + </ul> + + <p>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:</p> + + <ul> + <li> + <em>searchSuggestAuthority</em> - <strong>Required to provide search suggestions</strong>. + This value must match the authority string provided in the provider section of your manifest. + </li> + <li> + <em>searchSuggestPath</em> - 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. + </li> + <li> + <em>searchSuggestSelection</em> - 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.) + </li> + <li> + <em>searchSuggestIntentAction</em> - 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. + </li> + <li> + <em>searchSuggestIntentData</em> - 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. + </li> + </ul> + + <p>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:</p> + + <ul> + <li> + <em>includeInGlobalSearch</em> - <strong>Required to provide search suggestions in + Quick Search Box</strong>. 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. + </li> + <li> + <em>searchSettingsDescription</em> - 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. + </li> + <li> + <em>queryAfterZeroResults</em> - 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. + </li> + <li> + <em>searchSuggestThreshold</em> - 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. + </li> + </ul> + + <p>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:</p> + + <ul> + <li> + <em>voiceSearchMode</em> - <strong>Required to provide voice search + capabilities</strong>. + 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: + <ul> + <li> + <em>showVoiceSearchButton</em> - 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. + </li> + <li> + <em>launchWebSearch</em> - 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. + </li> + <li> + <em>launchRecognizer</em> - 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. + </li> + </ul> + </li> + <li> + <em>voiceLanguageModel</em> - 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. + </li> + <li> + <em>voicePromptText</em> - A string. If provided, this specifies a prompt + that will be displayed during voice input. If not provided, a default prompt + will be displayed. + </li> + <li> + <em>voiceLanguage</em> - 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()}. + </li> + <li> + <em>voiceMaxResults</em> - 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. + </li> + </ul> + </dd> + + <dt> + <actionkey> + </dt> + <dd> + Defines a shortcut key for a search action. + <ul> + <li> + <em>keycode</em> - <strong>Required</strong>. 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. + </li> + <li> + <em>queryActionMsg</em> - 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)}. + </li> + <li> + <em>suggestActionMsg</em> - 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)}. + </li> + <li> + <em>suggestActionMsgColumn</em> - 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. + </li> + </ul> + </dd> +</dl> + + + + + diff --git a/docs/html/guide/topics/resources/localization.jd b/docs/html/guide/topics/resources/localization.jd new file mode 100755 index 0000000..f32f1ac --- /dev/null +++ b/docs/html/guide/topics/resources/localization.jd @@ -0,0 +1,644 @@ +page.title=Localization
+parent.title=Resources and Assets
+parent.link=index.html
+@jd:body
+
+<div id="qv-wrapper">
+ <div id="qv">
+
+<h2>Localization quickview</h2>
+
+<ul>
+ <li>Android lets you create different resource sets for different locales.</li>
+ <li>When your application runs, Android will load the resource set
+that match the device's locale.</li>
+ <li>If locale-specific resources are not available, Android falls back to
+defaults.</li>
+ <li>The emulator has features for testing localized apps. </li>
+</ul>
+
+<h2>In this document</h2>
+<ol>
+ <li><a href="#resource-switching">Overview: Resource-Switching in Android</a>
+
+</li>
+<ol><li><a href="#defaults-r-important">Why Default Resources Are Important</a></li></ol>
+<li><a href="#using-framework">Using Resources for Localization</a>
+ <ol>
+ <li><a href="#creating-defaults">How to Create Default Resources</a></li><li>
+ <a href="#creating-alternates">How to Create Alternate Resources</a></li>
+ <li><a href="#resource-precedence">Which Resources Take Precedence?</a></li>
+ <li><a href="#referring-to-resources">Referring to Resources in Java</a></li>
+
+ </ol>
+</li>
+<li><a href="#strategies">Localization Strategies</a></li>
+<li><a href="#testing">Testing Localized Applications</a></li>
+ <ol>
+ <li><a href="#device">Testing on a Device</a></li>
+ <li><a href="#emulator">Testing on an Emulator</a></li>
+ <li><a href="#test-for-default">Testing for Default Resources</a></li>
+ </ol>
+<li><a href="#publishing">Publishing</a></li>
+<li><a href="#checklist">Localization Checklists</a></li>
+ <ol>
+ <li><a href="#planning-checklist">Planning and Design Checklist</a></li>
+ <li><a href="#content-checklist">Content Checklist</a></li>
+ <li><a href="#testing-checklist">Testing and Publishing Checklist</a></li>
+ </ol>
+</ol>
+
+<h2>See also</h2>
+ <ol>
+ <li><a
+href="{@docRoot}guide/tutorials/localization/index.html">Hello, L10N Tutorial</a></li>
+ <li><a href="resources-i18n.html">Resources</a></li>
+ <li><a href="{@docRoot}guide/topics/ui/declaring-layout.html">Declaring Layout</a></li>
+ <li><a href="{@docRoot}reference/android/app/Activity.html#ActivityLifecycle">Activity Lifecycle</a></li>
+</ol>
+</div>
+</div>
+
+<p>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.
+</p>
+
+<p>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. </p>
+
+<p>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. </p>
+
+<p>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:</p>
+
+<ul>
+ <li>You can put most or all of the <em>contents</em> of your application's
+user interface into resource files, as described in this document and in <a
+href="index.html">Resources</a>. </li>
+ <li>The <em>behavior</em> 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.
+</li>
+</ul>
+
+<p>The <a
+href="{@docRoot}guide/tutorials/localization/index.html">Hello, L10N
+</a> tutorial takes you through the steps of creating a simple localized
+application that uses locale-specific resources in the way described in this
+document. </p>
+
+
+<h2 id="resource-switching">Overview: Resource-Switching in Android</h2>
+
+<p>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.</p>
+
+<p>(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 <a
+href="resources-i18n.html#AlternateResources">Alternate Resources</a>.)</p>
+
+<table border="0" cellspacing="0" cellpadding="0">
+ <tr border="0">
+ <td width="180" style="border: 0pt none ;"><p class="special-note">
+ <strong>When you write your application:</strong>
+ <br><br>
+ You create a set of default resources, plus alternates to be used in
+ different locales.</p></td>
+ <td style="border: 0pt none; padding:0">
+ <p style="border:0; padding:0"><img src="../../../images/resources/right-arrow.png" alt="right-arrow"
+ width="51" height="17"></p></td>
+ <td width="180" style="border: 0pt none ;"><p class="special-note">
+ <strong>When a user runs your application:</strong>
+ <br><br>The Android system selects which resources to load, based on the
+ device's locale.</p></td>
+ </tr>
+</table>
+
+<p>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 <code>res/</code> directory.
+</p>
+
+
+
+<h3 id="defaults-r-important">Why Default Resources Are Important</h3>
+
+<p>Whenever the application runs in a locale for which you have not provided
+locale-specific text, Android will load the default strings from
+<code>res/values/strings.xml</code>. 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. </p>
+
+<p><em>Example:</em>
+<p>An application's Java code refers to just two strings, <code>text_a</code> and
+ <code>text_b</code>. This application includes a localized resource file
+ (<code>res/values-en/strings.xml</code>) that defines <code>text_a</code> and
+ <code>text_b</code> in English. This application also includes a default
+ resource file (<code>res/values/strings.xml</code>) that includes a
+definition for <code>text_a</code>, but not for <code>text_b</code>:
+<ul>
+ <li>This application might compile without a problem. An IDE such as Eclipse
+ will not highlight any errors if a resource is missing.</li>
+ <li>When this application is launched on a device with locale set to English,
+ the application might run without a problem, because
+ <code>res/values-en/strings.xml</code> contains both of the needed text
+ strings.</li>
+ <li>However, <strong>the user will see an error message and a Force Close
+ button</strong> when this application is launched on a device set to a
+ language other than English. The application will not load.</li>
+</ul>
+
+
+<p>To prevent this situation, make sure that a <code>res/values/strings.xml</code>
+ 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 <a href="#test-for-default">
+ Testing for Default Resources</a>.</p>
+
+<h2 id="using-framework">Using Resources for Localization</h2>
+
+<h3 id="creating-defaults">How to Create Default Resources</h3>
+
+<p>Put the application's default text in
+a file with the following location and name:</p>
+<p><code> res/values/strings.xml</code> (required directory)</p>
+
+<p>The text strings in <code>res/values/strings.xml</code> should use the
+default language, which is the language that you expect most of your application's users to
+speak. </p>
+
+<p>The default resource set must also include any default drawables and layouts,
+ and can include other types of resources such as animations.
+<br>
+ <code> res/drawable/</code>(required directory holding at least
+ one graphic file, for the application's icon in the Market)<br>
+ <code> res/layout/</code> (required directory holding an XML
+ file that defines the default layout)<br>
+ <code> res/anim/</code> (required if you have any
+ <code>res/anim-<em><qualifiers></em></code> folders)<br>
+ <code> res/xml/</code> (required if you have any
+ <code>res/xml-<em><qualifiers></em></code> folders)<br>
+ <code> res/raw/</code> (required if you have any
+ <code>res/raw-<em><qualifiers></em></code> folders)
+</p>
+
+<p class="note"><strong>Tip:</strong> 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 <em>
+ localized</em> string file can contain a subset of the strings, but the
+ <em>default</em> string file must contain them all.
+</p>
+
+<h3 id="creating-alternates">How to Create Alternate Resources</h3>
+
+<p>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. </p>
+
+<p>An application can specify many <code>res/<em><qualifiers></em>/</code>
+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
+<a href="resources-i18n.html#AlternateResources">Alternate Resources</a>,
+or else it will not compile.)</p>
+
+<p><em>Example:</em></p>
+
+<p>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 <code>strings.xml</code>
+files, each stored in a locale-specific resource directory:</p>
+
+<ol>
+ <li><code>res/values/strings.xml</code><br>
+ Contains English text for all the strings that the application uses,
+including text for a string named <code>title</code>.</li>
+ <li><code>res/values-fr/strings.xml</code><br>
+ Contain French text for all the strings, including <code>title</code>.</li>
+ <li><code>res/values-ja/strings.xml</code><br>
+ Contain Japanese text for all the strings <em>except</em>
+<code>title</code>.<br>
+ <code></code></li>
+</ol>
+
+<p>If your Java code refers to <code>R.string.title</code>, here is what will
+happen at runtime:</p>
+
+<ul>
+ <li>If the device is set to any language other than French, Android will load
+<code>title</code> from the <code>res/values/strings.xml</code> file.</li>
+ <li>If the device is set to French, Android will load <code>title</code> from
+the <code>res/values-fr/strings.xml</code> file.</li>
+</ul>
+
+<p>Notice that if the device is set to Japanese, Android will look for
+<code>title</code> in the <code>res/values-ja/strings.xml</code> file. But
+because no such string is included in that file, Android will fall back to the
+default, and will load <code>title</code> in English from the
+<code>res/values/strings.xml</code> file. </p>
+
+<h3 id="resource-precedence">Which Resources Take Precedence?</h3>
+
+<p> 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, <strong>locale almost always takes
+precedence</strong>. </p>
+<p><em>Example:</em></p>
+
+<p>Assume that an application includes a default set of graphics and two other
+sets of graphics, each optimized for a different device setup:</p>
+
+<ul>
+ <li><code>res/drawable/</code><br>
+ Contains
+ default graphics.</li>
+ <li><code>res/drawable-small-land-stylus/</code><br>
+ Contains graphics optimized for use with a device that expects input from a
+ stylus and has a QVGA low-density screen in landscape orientation.</li>
+ <li><code>res/drawable-ja/</code> <br>
+ Contains graphics optimized for use with Japanese.</li>
+</ul>
+
+<p>If the application runs on a device that is configured to use Japanese,
+Android will load graphics from <code>res/drawable-ja/</code>, even if the
+device happens to be one that expects input from a stylus and has a QVGA
+low-density screen in landscape orientation.</p>
+
+<p class="note"><strong>Exception:</strong> The only qualifiers that take
+precedence over locale in the selection process are MCC and MNC (mobile country
+code and mobile network code). </p>
+
+<p><em>Example:</em></p>
+
+<p>Assume that you have the following situation:</p>
+
+<ul>
+ <li>The application code calls for <code>R.string.text_a</code></li>
+ <li>Two relevant resource files are available:
+ <ul>
+ <li><code>res/values-mcc404/strings.xml</code>, which includes
+<code>text_a</code> in the application's default language, in this case
+English.</li>
+ <li><code>res/values-hi/strings.xml</code>, which includes
+<code>text_a</code> in Hindi.</li>
+ </ul>
+ </li>
+ <li>The application is running on a device that has the following
+configuration:
+ <ul>
+ <li>The SIM card is connected to a mobile network in India (MCC 404).</li>
+ <li>The language is set to Hindi (<code>hi</code>).</li>
+ </ul>
+ </li>
+</ul>
+
+<p>Android will load <code>text_a</code> from
+<code>res/values-mcc404/strings.xml</code> (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. </p>
+
+<p>The selection process is not always as straightforward as these examples
+suggest. Please read <a href="resources-i18n.html#best-match">How Android finds
+the best matching directory</a> for a more nuanced description of the
+process. All the qualifiers are described and listed in order of
+precedence in <a href="resources-i18n.html#table2">Table 2 in the Resources
+document</a>.</p>
+
+<h3 id="referring-to-resources">Referring to Resources in Java</h3>
+
+<p>In your application's Java code, you refer to resources using the syntax
+<code>R.<em>resource_type</em>.<em>resource_name</em></code> or
+<code>android.R.<em>resource_type</em>.<em>resource_name</em></code><em>.</em>
+For more about this, see <a href="resources-i18n.html#ResourcesInCode">Using
+Resources in Code</a>.</p>
+
+<h2 id="strategies">Localization Strategies</h2>
+
+<h4 id="failing2">Design your application to work in any locale</h4>
+
+<p>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.</p>
+
+<p class="note"><strong>Important:</strong> Make sure that your application
+includes a full set of default resources.</p> <p>Make sure to include
+<code>res/drawable/</code> and a <code>res/values/</code> folders (without any
+additional modifiers in the folder names) that contain all the images and text
+that your application will need. </p>
+
+<p>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
+ <code>res/values/strings.xml</code> default file might lack one string that
+ the application needs: When the application runs in an unsupported locale and
+ attempts to load <code>res/values/strings.xml</code>, 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.</p>
+
+<p>For more information, see <a href="#test-for-default">Testing for Default Resources</a>.</p>
+
+<h4>Design a flexible layout</h4>
+
+<p> 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 <code>res/layout-de/main.xml</code>). However, doing this
+can make your application harder to maintain. It is better to create a single
+layout that is more flexible.</p>
+
+<p>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:</p>
+
+<ul>
+ <li>Create one layout with a field that you can programmatically enable or
+disable, based on the language, or</li>
+ <li>Have the main layout include another layout that includes the changeable
+field. The second layout can have different configurations for different
+languages.</li>
+</ul>
+
+<h4>Avoid creating more resource files and text strings than you need</h4>
+
+<p>You probably do not need to create a locale-specific
+alternative for every resource in your application. For example, the layout
+defined in the <code>res/layout/main.xml</code> file might work in any locale,
+in which case there would be no need to create any alternate layout files.
+</p>
+
+<p>Also, you might not need to create alternate text for every
+string. For example, assume the following:</p>
+
+<ul>
+ <li>Your application's default language is American
+English. Every string that the application uses is defined, using American
+English spellings, in <code>res/values/strings.xml</code>. </li>
+
+ <li>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. </li>
+</ul>
+
+<p>To do this, you could create a small file called
+<code>res/values-en-rGB/strings.xml</code> 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 <code>res/values/strings.xml</code>.</p>
+
+<h4>Use the Android Context object for manual locale lookup</h4>
+
+<p>You can look up the locale using the {@link android.content.Context} object
+that Android makes available:</p>
+
+<pre>String locale = context.getResources().getConfiguration().locale.getDisplayName();</pre>
+
+<h2 id="testing">Testing Localized Applications</h2>
+
+<h3 id="device">Testing on a Device</h3>
+<p>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.</p>
+
+<p>To change the locale on a device, use the Settings application (Home >
+Menu > Settings > Locale & text > Select locale). </p>
+
+<h3 id="emulator">Testing on an Emulator</h3>
+
+<p>For details about using the emulator, see See <a
+href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a>.</p>
+<h4>Creating and using a custom locale</h4>
+
+<p>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 <a href="{@docRoot}sdk/android-{@sdkCurrentVersion}.html">Android
+Version Notes</a>.) 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:</p>
+
+<ul>
+ <li>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.)</li>
+ <li>Change to a custom locale from the adb shell, as described below.</li>
+</ul>
+
+<p>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.</p>
+
+<h4>Changing the emulator locale from the adb shell</h4>
+
+<p>To change the locale in the emulator by using the adb shell. </p>
+
+<ol>
+ <li>Pick the locale you want to test and determine its language and region codes, for
+example <code>fr</code> for French and <code>CA</code> for Canada.<br>
+ </li>
+ <li>Launch an emulator.</li>
+ <li>From a command-line shell on the host computer, run the following
+command:<br>
+ <code>adb shell</code><br>
+ or if you have a device attached, specify that you want the emulator by adding
+the <code>-e</code> option:<br>
+ <code>adb -e shell</code></li>
+ <li>At the adb shell prompt (<code>#</code>), run this command: <br>
+ <code>setprop persist.sys.language [<em>language code</em>];setprop
+persist.sys.country [<em>country code</em>];stop;sleep 5;start <br>
+ </code>Replace bracketed sections with the appropriate codes from Step
+1.</li>
+</ol>
+
+<p>For instance, to test in Canadian French:</p>
+
+<p><code>setprop persist.sys.language fr;setprop persist.sys.country
+CA;stop;sleep 5;start </code></p>
+
+<p>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. </p>
+
+<h3 id="test-for-default">Testing for Default Resources</h3>
+<p>Here's how to test whether an application includes every string resource that it needs: </p>
+<ol><li>Set the emulator or device to a language that your application does not
+ support. For example, if the application has French strings in
+ <code>res/values-fr/</code> but does not have any Spanish strings in
+ <code>res/values-es/</code>, then set the emulator's locale to Spanish.
+ (You can use the Custom Locale application to set the emulator to an
+ unsupported locale.)</li>
+ <li>Run the application.</li>
+<li>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
+ <code>res/values/strings.xml</code> file includes a definition for
+ every string that the application uses.</li>
+</ol>
+</p>
+
+<p>If the test is successful, repeat it for other types of
+ configurations. For example, if the application has a layout file called
+ <code>res/layout-land/main.xml</code> but does not contain a file called
+ <code>res/layout-port/main.xml</code>, then set the emulator or device to
+ portrait orientation and see if the application will run.
+
+<h2 id="publishing">Publishing Localized Applications</h2>
+
+<p>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 <a
+href="{@docRoot}guide/publishing/preparing.html">Preparing to Publish</a>. </p>
+
+<p>If you split your application in several .apk files, each targeted to a
+different locale, follow these guidelines:</p>
+
+<ul>
+ <li>Sign each .apk file with the same certificate. For more about this, see <a
+href="{@docRoot}guide/publishing/app-signing.html#strategies">Signing
+Strategies</a>. </li>
+ <li>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.</li>
+<li>Include a complete set of default resources in each .apk file.</li>
+</ul>
+
+<h2 id="checklist">Localization Checklists</h2>
+
+<p>These checklists summarize the process of localizing an Android application.
+Not everything on these lists will apply to every application.</p>
+
+<h3 id="planning-checklist">Planning and Design Checklist</h3>
+
+<table width="100%" border="0" cellpadding="5" cellspacing="0">
+ <tr>
+ <td valign="top" align="center"><img src="../../../images/resources/arrow.png" alt="arrow" width="26"
+border="0"></td>
+ <td>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?</td>
+ </tr>
+ <tr>
+ <td valign="top" align="center"><img src="../../../images/resources/arrow.png" alt="arrow" width="26"
+border="0"></td>
+ <td><p>Identify everything in your application that will need to be
+localized: </p>
+ <ul>
+ <li>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. </li>
+ <li>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.</li>
+ </ul></td>
+ </tr>
+ <tr>
+ <td valign="top" align="center"><img src="../../../images/resources/arrow.png" alt="arrow" width="26"
+border="0"></td>
+ <td><p>Design your Java code to externalize resources wherever possible:</p>
+ <ul>
+ <li>Use <code>R.string</code> and <code>strings.xml</code> files instead
+of hard-coded strings or string constants. </li>
+ <li>Use <code>R.drawable</code> and <code>R.layout</code> instead of
+hard-coded drawables or layouts. </li>
+ </ul></td>
+ </tr>
+</table>
+<h3 id="content-checklist">Content Checklist</h3>
+<table border="0" cellspacing="0" cellpadding="5" width="100%">
+ <tr>
+ <td valign="top" align="center"><img src="../../../images/resources/arrow.png" alt="arrow" width="26"
+border="0"></td>
+ <td>Create a full set of default resources in <code>res/values/</code> and
+other <code>res/</code> folders, as described in <a
+href="#creating-defaults">Creating Default Resources</a>.</td>
+ </tr>
+ <tr>
+ <td valign="top" align="center"><img src="../../../images/resources/arrow.png" alt="arrow" width="26"
+border="0"></td>
+ <td>Obtain reliable translations of the static text, including menu text,
+button names, error messages, and help text. Place the translated strings in
+<code>res/values-<em><qualifiers></em>/strings.xml</code> files. </td>
+ </tr>
+ <tr>
+ <td valign="top" align="center"><img src="../../../images/resources/arrow.png" alt="arrow" width="26"
+border="0"></td>
+ <td>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.</td>
+ </tr>
+ <tr>
+ <td valign="top" align="center"><img src="../../../images/resources/arrow.png" alt="arrow" width="26"
+border="0"></td>
+ <td>If necessary, create locale-specific versions of your graphics and
+layout, and place them in <code>res/drawable-<em><qualifiers></em>/</code> and
+<code>res/layout-<em><qualifiers></em>/</code> folders.</td>
+ </tr>
+ <tr>
+ <td valign="top" align="center"><img src="../../../images/resources/arrow.png" alt="arrow" width="26"
+border="0"></td>
+ <td>Create any other localized content that your application requires; for
+example, create recordings of sound files for each language, as needed.</td>
+ </tr>
+</table>
+<h3 id="testing-checklist">Testing and Publishing Checklist</h3>
+ <table border="0" cellspacing="0" cellpadding="5" width="100%">
+ <tr>
+ <td valign="top" align="center"><img src="../../../images/resources/arrow.png" alt="arrow" width="26"
+border="0"></td>
+ <td>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.</td>
+ </tr>
+ <tr>
+ <td valign="top" align="center"><img src="../../../images/resources/arrow.png" alt="arrow" width="26"
+border="0"></td>
+ <td>Test the default resources by loading a locale that is not available on
+ the device or emulator. For instructions, see <a href="#test-for-default">
+ Testing for Default Resources</a>. </td>
+ </tr>
+ <tr>
+ <td valign="top" align="center"><img src="../../../images/resources/arrow.png" alt="arrow" width="26"
+border="0"></td>
+ <td>Test the localized strings in both landscape and portrait display modes.</td>
+ </tr>
+ <tr>
+ <td valign="top" align="center"><img src="../../../images/resources/arrow.png" alt="arrow" width="26"
+border="0"></td>
+ <td>Sign your application and create your final build or builds.</td>
+ </tr>
+ <tr>
+ <td valign="top" align="center"><img src="../../../images/resources/arrow.png" alt="arrow" width="26"
+border="0"></td>
+ <td>Upload your .apk file or files to Market, selecting the appropriate
+languages as
+ you upload. (For more details, see <a
+href="{@docRoot}guide/publishing/publishing.html">Publishing Your
+Applications</a>.)</td>
+ </tr>
+</table>
\ 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 Binary files differdeleted file mode 100755 index d738b3f..0000000 --- a/docs/html/guide/topics/resources/res-selection-flowchart.png +++ /dev/null diff --git a/docs/html/guide/topics/resources/resources-i18n.jd b/docs/html/guide/topics/resources/resources-i18n.jd index 85b89d1..091bc62 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:</p> <pre> MyApp/ res/ - drawable-en-rUS-large-long-port-mdpi-finger-keysexposed-qwerty-dpad-480x320/ + drawable-en-rUS-large-long-port-mdpi-finger-keysexposed-qwerty-navexposed-dpad-480x320/ </pre> <p>More typically, you will only specify a few specific configuration options. You may drop any of the values from the @@ -575,6 +575,14 @@ MyApp/ <td><code>nokeys</code>, <code>qwerty</code>, <code>12key</code> </td> </tr> <tr> + <td>Whether the navigation keys are available to the user</td> + <td><p><code>navexposed</code>, <code>navhidden</code> + </p><p> + 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.</p></td> + </tr> + <tr> <td>Primary non-touchscreen<br /> navigation method</td> <td><code>nonav</code>, <code>dpad</code>, <code>trackball</code>, <code>wheel</code> </td> @@ -685,7 +693,7 @@ MyApp/res/drawable-en-port/ </ol> <p class="note"><strong>Tip:</strong> The <em>precedence</em> 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 <code>drawable-en</code> has only one parameter that matches (language). However, language has a higher precedence, so <code>drawable-port-notouch-12key</code> is out.</p> <p>This flowchart summarizes how Android selects resource directories to load.</p> -<p><img src="res-selection-flowchart.png" alt="resource-selection" width="461" height="471" style="margin:15px"></p> +<p><img src="../../../images/resources/res-selection-flowchart.png" alt="resource-selection" width="461" height="471" style="margin:15px"></p> <h3>Terminology</h3> <p>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 7ef22a6..80ad7b8 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 <li><a href="#SizePaddingMargin">Size, Padding and Margins</a></li> <li><a href="#example">Example Layout</a></li> </ol> + </div> </div> @@ -41,14 +42,17 @@ application can create View and ViewGroup objects (and manipulate their properti <p>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. </p> <div class="sidebox"> - <p>The <a href="{@docRoot}guide/developing/tools/adt.html">Android Development Tools</a> - (ADT) plugin for Eclipse offers a layout preview of your XML — - with the XML file opened, select the <strong>Layout</strong> tab.</p> - <p>You should also try the + <ul> + <li>The <a href="{@docRoot}sdk/eclipse-adt.html">ADT + Plugin for Eclipse</a> offers a layout preview of your XML — + with the XML file opened, select the <strong>Layout</strong> tab.</li> + <li>You should also try the <a href="{@docRoot}guide/developing/tools/hierarchy-viewer.html">Hierarchy Viewer</a> 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.</p> + you debug on the emulator or device.</li> + <li>The <a href="{@docRoot}guide/developing/tools/layoutopt.html">layoutopt</a> tool lets + you quickly analyze your layouts and hierarchies for inefficiencies or other problems.</li> </div> <p>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 c0c0b1b..4e4ca14 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 f4d114a..5628d46 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 <code>onTouchEvent()</code> 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 <a href="#EventListeners">event listeners</a>, are your ticket to capturing the user interaction with your UI.</p> @@ -102,7 +102,7 @@ protected void onCreate(Bundle savedValues) { } </pre> -<p>You may also find it more conventient to implement OnClickListener as a part of your Activity. +<p>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:</p> <pre> 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 <li><code>{@link android.view.View#onTouchEvent}</code> - Called when a touch screen motion event occurs.</li> <li><code>{@link android.view.View#onFocusChanged}</code> - Called when the view gains or loses focus.</li> </ul> -<p>There are some other methods that you should be awere of, which are not part of the View class, +<p>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:</p> <ul> diff --git a/docs/html/guide/tutorials/hello-world.jd b/docs/html/guide/tutorials/hello-world.jd index 79b723d..58d1a16 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.</p> <p>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 -<a href="{@docRoot}sdk/{@sdkCurrent}/installing.html">Installing the Android SDK</a> and return +<a href="{@docRoot}sdk/installing.html">Installing the Android SDK</a> and return here when you've completed the installation.</p> <h2 id="avd">Create an AVD</h2> diff --git a/docs/html/guide/tutorials/localization/index.jd b/docs/html/guide/tutorials/localization/index.jd new file mode 100755 index 0000000..8a60814 --- /dev/null +++ b/docs/html/guide/tutorials/localization/index.jd @@ -0,0 +1,593 @@ +page.title=Hello, L10N
+@jd:body
+
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol>
+ <li><a href="#unlocalized">Create an Unlocalized App</a>
+ <ol>
+ <li><a href="#create">Create the Project and Layout</a></li>
+ <li><a href="#default">Create Default Resources</a></li>
+ </ol>
+ </li>
+ <li><a href="#run">Run the Unlocalized App</a></li>
+ <li><a href="#plan">Plan the Localization</a></li>
+ <li><a href="#localize">Localize the App</a>
+ <ol>
+ <li><a href="#localize_strings">Localize the Strings</a></li>
+ <li><a href="#localize_images">Localize the Images</a></li>
+ </ol>
+ </li>
+ <li><a href="#test_localized">Run and Test the Localized App</a></li>
+ </ol>
+ <h2>See also</h2>
+ <ol>
+<li>{@link android.widget.Button}</li>
+<li>{@link android.widget.TextView}</li>
+<li>{@link android.app.AlertDialog}</li>
+</ol>
+ </div>
+</div>
+
+<p>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 <code>res/</code> directory. </p>
+
+<p>This tutorial uses the practices described in the <a
+href="{@docRoot}guide/topics/resources/localization.html">Localization</a>
+document. </p>
+
+
+<h2 id="unlocalized">Create an Unlocalized Application</h2>
+
+<p>The first version of the Hello, L10N application will use only the default
+resource directories (<code>res/drawable</code>, <code>res/layout</code>, and
+<code>res/values</code>). 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.</p>
+
+<p>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. </p>
+
+<h3 id="create">Create the Project and Layout</h3>
+
+<p>For this application, the default language will be British English and the
+default location the United Kingdom. </p>
+
+<ol>
+ <li>Start a new project and Activity called "HelloL10N." If you are
+using Eclipse, fill out these values in the New Android Project wizard:
+ <ul>
+ <li><em>Project name:</em> HelloL10N</li>
+ <li><em>Application name:</em> Hello, L10N</li>
+ <li><em>Package name:</em> com.example.hellol10n (or your own private
+namespace)</li>
+ <li><em>Create Activity:</em> HelloL10N</li>
+ <li><em>Min SDK Version:</em> 3</li>
+ </ul>
+ <p>The basic project contains a <code>res/</code> directory with
+subdirectories for the three most common types of resources: graphics
+(<code>res/drawable/</code>), layouts (<code>res/layout/</code>) and strings
+(<code>res/values/</code>). Most of the localization work you do later in this
+tutorial will involve adding more subdirectories to the <code>res/</code>
+directory.</p>
+ <img src="{@docRoot}images/hello_l10n/plain_project.png" alt="plain project" width="194"
+height="229">
+ </li>
+ <li>Open the <code>res/layout/main.xml</code> file and replace it with the
+following code:
+ <pre><?xml version="1.0" encoding="utf-8"?>
+<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
+ android:orientation="vertical"
+ android:layout_width="fill_parent"
+ android:layout_height="fill_parent"
+ >
+<TextView
+ android:layout_width="fill_parent"
+ android:layout_height="wrap_content"
+ android:gravity="center_horizontal"
+ android:text="@string/text_a"
+ />
+<TextView
+ android:layout_width="fill_parent"
+ android:layout_height="wrap_content"
+ android:gravity="center_horizontal"
+ android:text="@string/text_b"
+ />
+<Button
+ android:id="@+id/flag_button"
+ android:layout_width="wrap_content"
+ android:layout_height="wrap_content"
+ android:layout_gravity="center"
+ />
+</LinearLayout>
+ </pre>
+
+ <p>The LinearLayout has two {@link android.widget.TextView} objects that will
+display localized text and one {@link android.widget.Button} that shows a flag.
+</p>
+ </li>
+</ol>
+
+<h3 id="default">Create Default Resources</h3>
+
+<p>The layout refers to resources that need to be defined. </p>
+
+<ol>
+ <li>Create default text strings. To do this, open the <code>res/values/strings.xml</code> file and replace it with the following code:<br>
+ <pre><?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></pre>
+
+ <p>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.</p>
+ </li>
+ <li>Add a default flag graphic to the <code>res/drawable</code> folder by
+saving <a href="../../../images/hello_l10n/flag.png">flag.png</a> as
+<code>res/drawable/flag.png</code>. When the application is not localized, it
+will show a British flag.<br>
+
+ </li>
+ <li>Open HelloL10N.java (in the <code>src/</code> directory) and add the
+following code inside the <code>onCreate()</code> method (after
+<code>setContentView</code>).
+
+ <pre>// 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();
+ }
+ });</pre>
+
+ <p class="note"><strong>Tip:</strong> In Eclipse, use
+<strong>Ctrl-Shift-O</strong> (<strong>Cmd-Shift-O</strong>, on Mac) to find and
+add missing import packages to your project, then save the HelloL10N.java
+file.</p>
+
+ <p>The code that you added does the following:</p>
+
+ <ul>
+ <li>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 <code>res/drawable/flag.png</code> (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.
+</li>
+ <li>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 <code>dialog_text</code> that is located
+within <code>res/values/strings.xml</code>. </li>
+ </ul>
+
+ </li>
+</ol>
+
+<p>The project structure now looks like this:</p>
+
+ <img src="{@docRoot}images/hello_l10n/nonlocalized_project.png" alt="nonlocalized" width="394"
+height="320">
+
+<p class="note"><strong>Tip:</strong> If you will want to run the application on
+a device and not just on an emulator, open <code>AndroidManifest.xml</code> and
+add <code>android:debuggable="true"</code> inside the
+<code><application></code> element. For information about setting up the
+device itself so it can run applications from your system, see <a
+href="{@docRoot}guide/developing/device.html">Developing on a Device</a>.</p>
+
+
+<h2 id="run">Run the Unlocalized Application</h2>
+
+<p>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:</p>
+
+<table border="0" cellspacing="0" cellpadding="30">
+ <tr>
+ <th scope="col">The unlocalized application, running in any locale:</th>
+ <th scope="col">After clicking the flag, in any locale:</th>
+ </tr>
+ <tr>
+ <td valign="top"><img src="{@docRoot}images/hello_l10n/nonlocalized_screenshot1.png"
+alt="nonlocalized" width="321" height="366"></td>
+ <td><img src="{@docRoot}images/hello_l10n/nonlocalized_screenshot2.png" alt="nonlocalized2"
+width="321" height="366"></td>
+ </tr>
+</table>
+<h2 id="plan">Plan the Localization</h2>
+<p>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.</p>
+
+<p class="caption">Table 1</p>
+
+<table border="0" cellspacing="0" cellpadding="10">
+ <tr>
+ <th scope="col" valign="bottom">Region /<br />
+ Language</th>
+ <th scope="col">United Kingdom</th>
+ <th scope="col">Germany</th>
+ <th scope="col">France</th>
+ <th scope="col">Canada</th>
+ <th scope="col">Japan</th>
+ <th scope="col">United States</th>
+ <th scope="col">Other Location</th>
+ </tr>
+ <tr>
+ <th scope="row"><br>
+ English</th>
+ <td> British English text; British flag <em>(default)</em></td>
+ <td><em>-</em></td>
+ <td><em>-</em></td>
+ <td> British English text; Canadian flag</td>
+ <td>-</td>
+ <td> British English text; U.S. flag</td>
+ <td> British English text; British flag <em>(default)</em></td>
+ </tr>
+ <tr>
+ <th scope="row">German</th>
+ <td>-</td>
+ <td>German text for <code>app_name</code>, <code>text_a</code> and
+<code>text_b</code>; German flag</td>
+ <td>-</td>
+ <td>-</td>
+ <td>-</td>
+ <td>-</td>
+ <td>German text for <code>app_name</code>, <code>text_a</code> and
+<code>text_b</code>; British flag</td>
+ </tr>
+ <tr>
+ <th scope="row">French</th>
+ <td>-</td>
+ <td>-</td>
+ <td>French text for <code>app_name</code>, <code>text_a</code> and
+<code>text_b</code>; French flag</td>
+ <td>French text for <code>app_name</code>, <code>text_a</code> and
+<code>text_b</code>; Canadian flag</td>
+ <td>-</td>
+ <td>-</td>
+ <td>French text for <code>app_name</code>, <code>text_a</code> and
+<code>text_b</code>; British flag</td>
+ </tr>
+ <tr>
+ <th scope="row">Japanese</th>
+ <td>-</td>
+ <td>-</td>
+ <td>-</td>
+ <td>-</td>
+ <td>Japanese text for <code>text_a</code> and <code>text_b</code>; Japanese
+flag</td>
+ <td>-</td>
+ <td>Japanese text for <code>text_a</code> and <code>text_b</code>; British
+flag</td>
+ </tr>
+ <tr>
+ <th scope="row">Other Language</th>
+ <td>-</td>
+ <td>-</td>
+ <td>-</td>
+ <td>-</td>
+ <td>-</td>
+ <td>-</td>
+ <td> British English text; British flag <em>(default)</em></td>
+ </tr>
+</table>
+
+<p class="note"> 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.</p>
+
+<p>As shown in the table above, the plan calls for five flag icons in addition
+to the British flag that is already in the <code>res/drawable/</code> folder. It
+also calls for three sets of text strings other than the text that is in
+<code>res/values/strings.xml</code>.</p>
+
+<p>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, <em></em>see <a
+href="{@docRoot}guide/topics/resources/resources-i18n.html#AlternateResources">
+Alternate Resources</a>.)</p>
+<p class="caption" id="table2">Table 2</p>
+
+<table border="1" cellspacing="0" cellpadding="5">
+ <tr>
+ <th scope="col">Locale Code</th>
+ <th scope="col">Language / Country</th>
+ <th scope="col">Location of strings.xml</th>
+ <th scope="col">Location of flag.png</th>
+ </tr>
+ <tr>
+ <td><em>Default</em></td>
+ <td>English / United Kingdom</td>
+ <td>res/values/</td>
+ <td>res/drawable/</td>
+ </tr>
+ <tr>
+ <td>de-rDE</td>
+ <td>German / Germany</td>
+ <td>res/values-de/</td>
+ <td>res/drawable-de-rDE/</td>
+ </tr>
+ <tr>
+ <td>fr-rFR</td>
+ <td>French / France</td>
+ <td>res/values-fr/</td>
+ <td>res/drawable-fr-rFR/</td>
+ </tr>
+ <tr>
+ <td>fr-rCA</td>
+ <td>French / Canada</td>
+ <td>res/values-fr/</td>
+ <td>res/drawable-fr-rCA/</td>
+ </tr>
+ <tr>
+ <td>en-rCA</td>
+ <td>English / Canada</td>
+ <td><em>(res/values/)</em></td>
+ <td>res/drawable-en-rCA/</td>
+ </tr>
+ <tr>
+ <td>ja-rJP</td>
+ <td>Japanese / Japan</td>
+ <td>res/values-ja/</td>
+ <td>res/drawable-ja-rJP/</td>
+ </tr>
+ <tr>
+ <td>en-rUS</td>
+ <td>English / United States</td>
+ <td><em>(res/values/)</em></td>
+ <td>res/drawable-en-rUS/</td>
+ </tr>
+</table>
+
+<p class="note"><strong>Tip: </strong>A folder qualifer cannot specify a region
+without a language. Having a folder named <code>res/drawable-rCA/</code>,
+for example, will prevent the application from compiling. </p>
+
+<p>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. </p>
+
+<p>For example, assume that the device's language is set to German and its
+location to Switzerland. Because this application does not have a
+<code>res/drawable-de-rCH/</code> directory with a <code>flag.png</code> file in it, the system
+will fall back on the default, which is the UK flag located in
+<code>res/drawable/flag.png</code>. 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:</p>
+
+<ul>
+ <li>Use a generic default icon. In this application, it might be something
+that represents Shakespeare. </li>
+ <li>Create a <code>res/drawable-de/</code> folder that includes an icon that
+the application will use whenever the language is set to German but the location
+is not Germany. </li>
+</ul>
+
+
+<h2 id="localize">Localize the Application</h2>
+
+<h3 id="localize_strings">Localize the Strings</h3>
+
+<p>The application requires three more <code>strings.xml</code> files, one
+each for German, French, and Japanese. To create these resource files within
+Eclipse:</p>
+
+<ol>
+<li>Select <strong>File</strong> > <strong>New</strong> > <strong>Android
+XML File</strong> to open the New Android XML File wizard. You can also open
+the wizard by clicking its icon in the toolbar:<br />
+<img src="{@docRoot}images/hello_l10n/xml_file_wizard_shortcut.png"
+alt="file_wizard_shortcut" width="297"
+height="90" style="margin:15px"></li>
+ <li>Select L10N for the Project field, and type <code>strings.xml</code> into
+the File field. In the left-hand list, select Language, then click the right arrow.<br>
+<img src="{@docRoot}images/hello_l10n/xml_wizard1.png" alt="res_file_copy" width="335"
+height="406" style="margin:15px"></li>
+ <li>Type <code>de</code> in the Language box and click Finish.<br>
+ <img src="{@docRoot}images/hello_l10n/xml_wizard2.png" alt="res_file_copy" width="306"
+height="179">
+<p>A new file, <code>res/values-de/strings.xml</code>, now appears among the project
+files.</p></li>
+<li>Repeat the steps twice more, for the language codes <code>fr</code> and
+ <code>ja</code>.
+Now the project includes these new skeleton files: <br />
+ <code>res/<strong>values-de</strong>/strings.xml</code><br />
+ <code>res/<strong>values-fr</strong>/strings.xml</code><br />
+ <code>res/<strong>values-ja</strong>/strings.xml</code><br />
+ </li>
+ <li>Add localized text to the new files. To do
+this, open the <code>res/values-<em><qualifier></em>/strings.xml</code> files and
+replace the code as follows:</li>
+</ol>
+
+<table border="0" cellspacing="0" cellpadding="0">
+ <tr>
+ <th scope="col">File</th>
+ <th scope="col">Replace the contents with the following code:</th>
+ </tr>
+ <tr>
+ <td><code>res/values-de/strings.xml</code></td>
+ <td><pre><?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></pre></td>
+ </tr>
+ <tr>
+ <td><code>res/values-fr/strings.xml</code></td>
+ <td><pre><?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> </pre></td>
+ </tr>
+ <tr>
+ <td><code>res/values-ja/strings.xml</code></td>
+ <td>
+<pre><?xml version="1.0" encoding="utf-8"?>
+<resources>
+ <string name="text_a">あなたをなにかにたとえるとしたら夏の一日でしょうか？</string>
+ <string name="text_b">だがあなたはもっと美しく、もっとおだやかです。</string>
+</resources></pre></td>
+ </tr>
+</table>
+
+<p class="note"><b>Tip:</b> In the
+<code>values-<em><qualifier></em>/strings.xml</code> 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 <code>text_a</code> and <code>text_b</code> to be in Japanese
+while all the other text is in English, so
+<code>res/values-ja/strings.xml</code> only needs to include <code>text_a</code>
+and <code>text_b</code>.</p>
+
+<h3 id="localize_images">Localize the Images</h3>
+
+<p>As shown in <a href="#table2">Table 2</a>, the application needs six more
+drawable folders, each containing a <code>flag.png</code> icon. Add the needed
+icons and folders to your project:</p>
+
+<ol>
+ <li>Save this <a href="../../../images/hello_l10n/drawable-de-rDE/flag.png">German flag icon</a>
+as <code>res/drawable-de-rDE/flag.png</code> in the application's project
+workspace.
+ <p>For example:</p>
+ <ol>
+ <li>Click the link to open the flag image.</li>
+ <li>Save the image in
+<code><em>your-workspace</em>/HelloL10N/res/drawable-de-rDE/</code> .</li>
+ </ol>
+ </li>
+ <li>Save this <a href="../../../images/hello_l10n/drawable-fr-rFR/flag.png">French flag icon</a>
+as <code>res/drawable-fr-rFR/flag.png</code> in the application's project
+workspace. </li>
+ <li>Save this <a href="../../../images/hello_l10n/drawable-fr-rCA/flag.png">Canadian flag icon</a>
+as <code>res/drawable-fr-rCA/flag.png</code> in the project workspace. </li>
+ <li>Save the <a href="../../../images/hello_l10n/drawable-en-rCA/flag.png">Canadian flag icon</a>
+again, this time as <code>res/drawable-en-rCA/flag.png</code> in the project
+workspace. (Why not have just <em>one</em> folder that contains the Canadian
+flag? Because a folder qualifer cannot specify a region without a language.
+You cannot have a folder named <code>drawable-rCA/</code>; instead you must
+create two separate folders, one for each of the Canadian languages represented
+in the application.)</li>
+ <li>Save this <a href="../../../images/hello_l10n/drawable-ja-rJP/flag.png">Japanese flag icon</a>
+as <code>res/drawable-ja-rJP/flag.png</code> in the project workspace. </li>
+ <li>Save this <a href="../../../images/hello_l10n/drawable-en-rUS/flag.png">United States flag
+icon</a> as <code>res/drawable-en-rUS/flag.png</code> in the project workspace.
+ </li>
+</ol>
+
+<p>If you are using Eclipse, refresh the project (F5). The new
+<code>res/drawable-<em><qualifier></em>/</code> folders should appear in the
+project view. </p>
+
+
+<h2 id="test_localized">Run and Test the Localized Application</h2>
+
+<p>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. </p>
+
+<p>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:</p>
+
+<p><img src="{@docRoot}images/hello_l10n/custom_locale_app.png" alt="custom locale app" width="163"
+height="158" style="margin-left:15px"></p>
+
+<p>To switch to a new locale, long-press a locale name:</p>
+
+<p><img src="{@docRoot}images/hello_l10n/using_custom_locale.png" alt="using custom locale"
+width="512" height="299" style="margin-left:15px"></p>
+
+<p>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, <a
+href="{@docRoot}sdk/android-2.0.html#locs">Android 2.0 locales</a>.</p>
+
+<p>Run the application for each of the expected locales, plus one unexpected
+locale. Here are some of the results you should see:</p>
+
+<table border="0" cellspacing="0" cellpadding="05">
+ <tr>
+ <th scope="col">Locale</th>
+ <th scope="col">Opening screen of application</th>
+ </tr>
+ <tr>
+ <td>German / Germany
+ <br />Specifically supported by the Hello, L10N application.</td>
+ <td><img src="{@docRoot}images/hello_l10n/german_screenshot.png" alt="custom locale app"
+width="321" height="175" align="right"
+style="margin-left:10px;margin-right:20px"></td>
+ </tr>
+ <tr>
+ <td>French / Canada
+ <br />Specifically supported by the Hello, L10N application.</td>
+ <td><img src="{@docRoot}images/hello_l10n/frenchCA_screenshot.png" alt="custom locale app"
+width="321" height="175" align="right"
+style="margin-left:10px;margin-right:20px"></td>
+ </tr>
+ <tr>
+ <td>German / Switzerland
+ <br />Only the language is specifically supported by
+the Hello, L10N application.</td>
+ <td><img src="{@docRoot}images/hello_l10n/germanCH_screenshot.png" alt="custom locale app"
+width="321" height="175" align="right"
+style="margin-left:10px;margin-right:20px">`</td>
+ </tr>
+ <tr>
+ <td>Japanese
+ <br />Specifically supported by the Hello, L10N application.
+ </td>
+ <td><img src="{@docRoot}images/hello_l10n/japanese_screenshot.png" alt="custom locale app"
+width="321" height="220" align="right"
+style="margin-left:10px;margin-right:20px">`</td>
+ </tr>
+ <tr>
+ <td>Romansh / Switzerland (custom locale <code>rm_CH</code>)
+ <br />Not specifically supported by the Hello, L10N
+application, so the application uses the default resources.</td>
+ <td><img src="{@docRoot}images/hello_l10n/romanshCH_screenshot.png" alt="custom locale app"
+width="321" height="175" align="right"
+style="margin-left:10px;margin-right:20px"></td>
+ </tr>
+</table>
|
