diff options
Diffstat (limited to 'docs')
17 files changed, 752 insertions, 254 deletions
diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs index d0318cf..35ce17e 100644 --- a/docs/html/guide/guide_toc.cs +++ b/docs/html/guide/guide_toc.cs @@ -220,9 +220,16 @@ <li><a style="color:gray;">Accelerometer</a></li> </ul> </li> --> - <li><a href="<?cs var:toroot ?>guide/topics/location/index.html"> - <span class="en">Location and Maps</span> - </a></li> + <li class="toggle-list"> + <div><a href="<?cs var:toroot ?>guide/topics/location/index.html"> + <span class="en">Location and Maps</span> + </a></div> + <ul> + <li><a href="<?cs var:toroot ?>guide/topics/location/obtaining-user-location.html"> + <span class="en">Obtaining User Location</span> + </a> <span class="new">new!</span></li> + </ul> + </li> <!--<li class="toggle-list"> <div><a style="color:gray;">Wireless Controls</a></div> <ul> diff --git a/docs/html/guide/publishing/licensing.jd b/docs/html/guide/publishing/licensing.jd index e3b9135..07af68d 100644 --- a/docs/html/guide/publishing/licensing.jd +++ b/docs/html/guide/publishing/licensing.jd @@ -154,7 +154,7 @@ published on that account. </p> <p>When the application receives a signed response, it uses the embedded public key to verify the data. The use of public key cryptography in the licensing service makes it possible for the application to detect responses that have been -tampered with or are spoofed.</p> +tampered with or that are spoofed.</p> <h4>Use of licensing in your application</h4> @@ -184,7 +184,7 @@ The LVL greatly simplifies the process of adding licensing to your application and helps ensure a more secure, robust implementation for your application. The LVL provides internal classes that handle most of the standard operations of a license query, such as contacting Android Market to initiate a license request -and decrypting and validating the responses. It also exposes key interfaces that +and verifying and validating the responses. It also exposes key interfaces that let you easily plug in your custom code for defining licensing policy and managing access as needed by your application. The key LVL interfaces are: </p> @@ -211,7 +211,7 @@ needs:</p> <li><a href="#ServerManagedPolicy">ServerManagedPolicy</a> is a flexible Policy that uses settings provided by the licensing server to manage response caching and access to the application while the device is offline (such as when the -user is on on an airplane). For most applications, the use of +user is on an airplane). For most applications, the use of ServerManagedPolicy is highly recommended. </li> <li><a href="#StrictPolicy">StrictPolicy</a> is a restrictive Policy that does not cache any response data and allows the application access <em>only</em> @@ -233,10 +233,10 @@ physical device.</p> <h4>Requirements and limitations</h4> <p>Android Market Licensing is designed to let you apply license controls to -applications that you publish through Android Market and that users download -from Market. The service is not designed to let you control access to -applications that are not published through Android Market or that are run -on devices that do not offer the Android Market client. </p> +applications that you publish through Android Market. The service is not +designed to let you control access to applications that are not published +through Android Market or that are run on devices that do not offer the Android +Market client. </p> <p>Here are some points to keep in mind as you implement licensing in your application: </p> @@ -267,14 +267,15 @@ you won't be able to upload a new version that uses licensing.</li> <p>Android Market Licensing is a flexible, secure mechanism for controlling access to your applications. It effectively replaces the copy-protection -mechanism and gives you wider distribution potential for your applications. </p> +mechanism offered on Android Market and gives you wider distribution +potential for your applications. </p> <ul> -<li>A limitation of copy protection is that applications using it can be -installed only on compatible devices that provide a secure internal storage -environment. For example, a copy-protected application cannot be downloaded -from Market to a device that provides root access, and the application -cannot be installed to a device's SD card. </li> +<li>A limitation of the legacy copy-protection mechanism on Android Market is +that applications using it can be installed only on compatible devices that +provide a secure internal storage environment. For example, a copy-protected +application cannot be downloaded from Market to a device that provides root +access, and the application cannot be installed to a device's SD card. </li> <li>With Android Market licensing, you can move to a license-based model in which access is not bound to the characteristics of the host device, but to your publisher account on Android Market and the licensing policy that you define. @@ -338,7 +339,7 @@ let you: </p> <ul> <li>Set up multiple "test accounts", identified by email address. The licensing server allows users signed into test accounts on a device or emulator to send -license checks and receive static test reponses.</li> +license checks and receive static test responses.</li> <li>Obtain the account's public key for licensing. When you are implementing licensing in an application, you must copy the public key string into the application.</li> @@ -402,7 +403,7 @@ href="#download-lvl">Downloading the LVL</a>.</p> <p>If you haven't done so, you need to download the Android SDK before you can develop Android applications. The SDK provides the tools that you need to build and debug Android applications, including applications that use Android Market -licensing. For complete information, including installation intructions, see +licensing. For complete information, including installation instructions, see the <a href="{@docRoot}sdk/index.html">Android SDK</a>. </p> <p>If you have already installed the SDK, make sure to update the @@ -472,7 +473,7 @@ However, it does provide: </p> <ul> <li>An Android Market background service that implements the -<code>ILicensingService</code> remote interface, so that your application can +ILicensingService remote interface, so that your application can send license checks over the network to the licensing server. </li> <li>A set of underlying account services that let you add an a Google account on the AVD and sign in using your publisher account or test account credentials. @@ -492,7 +493,7 @@ developing licensing on an emulator.</p> <img src="{@docRoot}images/licensing_gapis_8.png" style="text-align:left;margin-bottom:0;" /> <div style="margin:0 2em;padding:0"><strong>Figure 3.</strong> Google APIs Add-On, API 8 (release 2) or higher lets you debug and test your licensing -implemention in an emulator.</div> +implementation in an emulator.</div> </div> <p>To set up an emulator for adding licensing to an application, follow @@ -581,9 +582,9 @@ Licensing package contains the LVL and the LVL sample application. </div> <p>When the download is complete, the Android SDK and AVD Manager installs both the LVL library project and the example application into these directories: </p> -<p style="margin-left:2em"><code><<em>sdk</em>>/marketlicensing/library/</code> +<p style="margin-left:2em"><code><<em>sdk</em>>/market_licensing/library/</code> (the LVL library project)<br /> -<code><<em>sdk</em>>/marketlicensing/sample/</code> (the example +<code><<em>sdk</em>>/market_licensing/sample/</code> (the example application)</p> <p>If you aren't familiar with how to download components into your SDK, see the @@ -601,20 +602,21 @@ since it lets you reuse your licensing code across multiple applications and maintain it more easily over time. Note that the LVL is not designed to be compiled separately and added to an application as a static .jar file. </p> -<h4>Moving the library sources out location</h4> +<h4>Moving the library sources to a new location</h4> <p>Because you will be customizing the LVL sources to some extent, you should make sure to <em>move or copy</em> the library sources (the entire -directory at <code><<em>sdk</em>>/marketlicensing/library/</code>) -to a working directory outside of the SDK. You can then add the sources -in the working location to your source-code management system, rather -than those in the SDK.</p> +directory at <code><<em>sdk</em>>/market_licensing/library/</code>) +to a working directory outside of the SDK. You should then use the relocated +sources as your working set. If you are using a source-code management +system, add and track the sources that are in the working location rather +than those in default location in the SDK. </p> <p>Moving the library sources is important is because, when you later update the Market licensing package, the SDK installs the new files to the same location as the older files. Moving your working library files to a safe location ensures -that they won't be inadvertently overwritten when you download a new version of -the LVL.</p> +that your work won't be inadvertently overwritten should you download a new +version of the LVL.</p> <h4>Creating the LVL as a library project</h4> @@ -639,11 +641,11 @@ Other IDEs</a>, as appropriate for your environment.</p> <em>library project</em>. A library project is a type of development project that holds shared Android source code and resources. Other Android application projects can reference the library project and, at build time, include its -compiled sources in their <code>.apk</code> files. In the context of licensing, this means -that you can do most of your licensing development once, in a library project, -then include the library sources in your various application projects. In this -way, you can easily maintain a uniform implementation of licensing across all of -your projects and maintain it centrally. </p> +compiled sources in their <code>.apk</code> files. In the context of licensing, +this means that you can do most of your licensing development once, in a library +project, then include the library sources in your various application projects. +In this way, you can easily maintain a uniform implementation of licensing +across all of your projects and maintain it centrally. </p> <p>The LVL is provided as a configured library project — once you have downloaded it, you can start using it right away. </p> @@ -675,9 +677,8 @@ in Eclipse with ADT</a>.</p> <p>As an alternative to adding the LVL as a library project, you can copy the library sources directly into your application. To do so, copy (or import) the -directory -<code><<em>sdk</em>>/extras/marketlicensing/library/src/com</code> into -your application's <code>src/</code> directory.</p> +LVL's <code>library/src/com</code> directory into your application's +<code>src/</code> directory.</p> <p>If you add the LVL sources directly to your application, you can skip the next section and start working with the library, as described in <a @@ -688,10 +689,10 @@ href="#app-integration"></a>.</p> application</h3> <p>If you want to use the LVL sources as a library project, you need to add a -reference to the LVL library project in your project properties. This tells +reference to the LVL library project in your application project properties. This tells build tools to include the LVL library project sources in your application at -compile time. The process for adding a reference to a library project varies, -based on your development environment, as described below.</p> +compile time. The process for adding a reference to a library project depends +on your development environment, as described below.</p> <p> If you are developing in Eclipse with ADT, you should already have added the library project to your workspace, as described in the previous section. If you @@ -793,10 +794,10 @@ android:name="com.android.vending.CHECK_LICENSE"></code></p> </pre> <p class="note"><strong>Note:</strong> Currently, you cannot declare the -<code>CHECK_LICENSE</code> permission in the LVL's manifest, because the SDK -Tools will not merge it into the manifests of dependent applications. Instead, -you must declare the permission in the manifest of each dependent application. -</p> +<code>CHECK_LICENSE</code> permission in the LVL library project's manifest, +because the SDK Tools will not merge it into the manifests of dependent +applications. Instead, you must declare the permission in each dependent +application's manifest. </p> <h3 id="impl-Policy">Implementing a Policy</h3> @@ -856,7 +857,7 @@ licensing server or from cache) or other application-specific information. For example, your implementation of <code>allowAccess()</code> could take into account additional criteria, such as usage or other data retrieved from a backend server. In all cases, an implementation of <code>allowAccess()</code> -should only return <code>true</code> if there user is licensed to use the +should only return <code>true</code> if the user is licensed to use the application, as determined by the licensing server, or if there is a transient network or system problem that prevents the license check from completing. In such cases, your implementation can maintain a count of retry responses and @@ -866,7 +867,8 @@ provisionally allow access until the next license check is complete.</li> <p>To simplify the process of adding licensing to your application and to provide an illustration of how a Policy should be designed, the LVL includes -two full Policy implementations that you can use without modification:</p> +two full Policy implementations that you can use without modification or +adapt to your needs:</p> <ul> <li><a href="#ServerManagedPolicy">ServerManagedPolicy</a>, a flexible Policy @@ -886,7 +888,7 @@ the LVL sample application.</p> <p>In your licensing implementation, you can use one of the complete policies provided in the LVL (ServerManagedPolicy or StrictPolicy) or you can create a -custom Policy. For any type of custom policy, there are several important design +custom policy. For any type of custom policy, there are several important design points to understand and account for in your implementation.</p> <p>The licensing server applies general request limits to guard against overuse @@ -896,7 +898,7 @@ passed through to your application as a general server error. This means that no license response will be available to the user until the limit is reset, which can affect the user for an indefinite period.</p> -<p>If you are designing a custom Policy, we recommend that the Policy: +<p>If you are designing a custom policy, we recommend that the Policy: <ol> <!-- <li>Limits the number of points at which your app calls for a license check to the minimum. </li> --> @@ -904,12 +906,12 @@ to the minimum. </li> --> in local persistent storage.</li> <li>Returns the cached response for all license checks, for as long as the cached response is valid, rather than making a request to the licensing server. -Setting the response validity accrording to the server-provided <code>VT</code> +Setting the response validity according to the server-provided <code>VT</code> extra is highly recommended. See <a href="#extras">Server Response Extras</a> for more information.</li> -<li>Uses an exponential backoff period if retrying any requests the result in -errors. However, because the Android Market client automatically retries failed -requests, the Policy does not need to do so, in most cases.</li> +<li>Uses an exponential backoff period, if retrying any requests the result in +errors. Note that the Android Market client automatically retries failed +requests, so in most cases there is no need for your Policy to retry them.</li> <li>Provides for a "grace period" that allows the user to access your application for a limited time or number of uses, while a license check is being retried. The grace period benefits the user by allowing access until the next @@ -942,7 +944,7 @@ settings to the responses, to help the application manage licensing effectively. <p style="margin-top:.5em;">See <a href="#extras">Server Response Extras</a> for a list of settings and <code>ServerManagedPolicy.java</code> for information -about how a Policy can usethe extras.</p> +about how a Policy can use the extras.</p> </div> </div> @@ -965,8 +967,8 @@ responses.</p> server-provided settings as the basis for managing licensing across an application's refund period and through varying network and error conditions. When an application contacts the Android Market server for a license check, the -server appends several settings as key-value pairs in the license response -extras field. For example, the server provides recommended values for the +server appends several settings as key-value pairs in the extras field of certain +license response types. For example, the server provides recommended values for the application's license validity period, retry grace period, and maximum allowable retry count, among others. ServerManagedPolicy extracts the values from the license response in its <code>processServerResponse()</code> method and checks @@ -1019,8 +1021,7 @@ with the cached data and obtain access to the application.</p> means that they won't be able to access the application when there is no network (cell or wi-fi) connection available. Another side-effect is that your application will send more license check requests to the server, since using a -cached response is not possible. Depending on network conditions, this might -prove challenging for users also.</p> +cached response is not possible.</p> <p>Overall, this policy represents a tradeoff of some degree of user convenience for absolute security and control over access. Consider the tradeoff carefully @@ -1058,7 +1059,7 @@ data is persistent. </p> <p>Because the Policy will use stored license response data to determine whether to allow or disallow access to the application, it <em>must</em> ensure that any -stored data is secure and can not be reused or manipulated by a root user on a +stored data is secure and cannot be reused or manipulated by a root user on a device. Specifically, the Policy must always obfuscate the data before storing it, using a key that is unique for the application and device. Obfuscating using a key that is both application-specific and device-specific is critical, because @@ -1066,20 +1067,18 @@ it prevents the obfuscated data from being shared among applications and devices.</p> <p>The LVL assists the application with storing its license response data in a -secure, persistent manner. First, it provides an <code>Obfuscator</code> +secure, persistent manner. First, it provides an Obfuscator interface that lets your application supply the obfuscation algorithm of its choice for stored data. Building on that, the LVL provides the helper class -<code>PreferenceObfuscator</code>, which handles most of the work of calling the +PreferenceObfuscator, which handles most of the work of calling the application's Obfuscator class and reading and writing the obfuscated data in a SharedPreferences instance. </p> <p>The LVL provides a full Obfuscator implementation called -<code>AESObfuscator</code> that uses AES encryption to obfuscate data. You can -use <code>AESObfuscator</code> in your application without modification or you +AESObfuscator that uses AES encryption to obfuscate data. You can +use AESObfuscator in your application without modification or you can adapt it to your needs. For more information, see the next section.</p> -<p>Alternatively, you can write a custom Obfuscator based on your own code -or use an obfuscator program such as ProGuard for additional security.</p> <h4 id="AESObfuscator">AESObfuscator</h4> @@ -1118,14 +1117,16 @@ queries the system settings for the <code>android.Settings.Secure.ANDROID_ID</code>, which is unique to each device. </p> -<p>Note that, depending on the APIs you use to derive device-specific -information, your application might need to request additional permissions in -order to secure device-specific information. For example, if you query the -TelephonyManager to obtain the device IMEI or related data, your application -will also need to request the <code>android.permission.READ_PHONE_STATE</code> -permission in its manifest. Before requesting permissions in this way, consider -how doing so might affect your application or its filtering of your application -on Android Market (since some permissions can cause the SDK build tools to add +<p>Note that, depending on the APIs you use, your application might need to +request additional permissions in order to acquire device-specific information. +For example, to query the {@link android.telephony.TelephonyManager} to obtain +the device IMEI or related data, the application will also need to request the +<code>android.permission.READ_PHONE_STATE</code> permission in its manifest.</p> + +<p>Before requesting new permissions for the <em>sole purpose</em> of acquiring +device-specific information for use in your Obfuscator, consider +how doing so might affect your application or its filtering on Android Market +(since some permissions can cause the SDK build tools to add the associated <code><uses-feature></code>).</p> <p>Finally, construct an instance of AESObfuscator, passing the salt, @@ -1441,7 +1442,7 @@ licensing. </li> </ul> <p>If you are using ServerManagedPolicy, you won't need to access the class -directly, so you can instantiate it directly in the LicenseChecker constructor, +directly, so you can instantiate it in the LicenseChecker constructor, as shown in the example below. Note that you need to pass a reference to a new Obfuscator instance when you construct ServerManagedPolicy.</p> @@ -1510,7 +1511,7 @@ sample application calls <code>checkAccess()</code> from a <h4 id="account-key">Embed your public key for licensing</h4> <p>For each publisher account, the Android Market service automatically -generates a 2048-bit RSA public/private key pair that is used exlusively for +generates a 2048-bit RSA public/private key pair that is used exclusively for licensing. The key pair is uniquely associated with the publisher account and is shared across all applications that are published through the account. Although associated with a publisher account, the key pair is <em>not</em> the same as @@ -1562,14 +1563,14 @@ LicenseChecker to properly close any open IPC connection to the Android Market application's ILicensingService and removes any local references to the service and handler.</p> -<p>Failing to add the call the LicenseChecker's <code>onDestroy()</code> method +<p>Failing to call the LicenseChecker's <code>onDestroy()</code> method can lead to problems over the lifecycle of your application. For example, if the user changes screen orientation while a license check is active, the application {@link android.content.Context} is destroyed. If your application does not properly close the LicenseChecker's IPC connection, your application will crash when the response is received. Similarly, if the user exits your application while a license check is in progress, your application will crash when the -response is received, unless your application has properly called the +response is received, unless it has properly called the LicenseChecker's <code>onDestroy()</code> method to disconnect from the service. </p> @@ -1608,7 +1609,7 @@ user ID string extracted from the response.</p> required</strong> — the LicenseChecker class automatically uses a default implementation called NullDeviceLimiter. As the name suggests, NullDeviceLimiter is a "no-op" class whose <code>allowDeviceAccess()</code> method simply returns -a LICENSED response for all users and devices. </p> +a <code>LICENSED</code> response for all users and devices. </p> <div style="border-left:4px solid #FFCF00;margin:1em;padding: 0 0 0 .5em"> <p><strong>Caution:</strong> Per-device licensing is <em>not recommended for @@ -1634,15 +1635,15 @@ error conditions.</p> <ul> <li>A "Test response" configuration in your publisher account that lets you -control the licensing response returned, when the server processes a license -check for an uploaded application from the publisher account or a test -account.</li> -<li>An optional set of test accounts that will receive the configured test -response when checking the license of an application that you have uploaded +set the static licensing response returned, when the server processes a +license check for an application uploaded to the publisher account, from a user +signed in to the publisher account or a test account.</li> +<li>An optional set of test accounts that will receive the static test +response when they check the license of an application that you have uploaded (regardless whether the application is published or not).</li> <li>A runtime environment for the application that includes the Android Market application or Google APIs Add-On, on which the user is signed in to the -publisher account or one of the test accounts. +publisher account or one of the test accounts.</li> </ul> <p>Setting up the test environment properly involves:</p> @@ -1659,11 +1660,12 @@ publisher account or one of the test accounts. <h3 id="test-response">Setting test responses for license checks</h3> <p>Android Market provides a configuration setting in your publisher account -that lets you override the normal processing of a license check for an -application you have uploaded and return a specified response code. The setting -is for testing only and applies <em>only</em> to license checks for applications -that you have uploaded. For other users (users not signed in to test accounts), -the server always processes license checks according to normal rules. </p> +that lets you override the normal processing of a license check and return a +specified static response code. The setting is for testing only and applies +<em>only</em> to license checks for applications that you have uploaded, made by +any user signed in to an emulator or device using the credentials of the +publisher account or a registered test account. For other users, the server +always processes license checks according to normal rules. </p> <p>To set a test response for your account, sign in to your publisher account and click "Edit Profile". In the Edit Profile page, locate the Test Response @@ -1672,9 +1674,9 @@ valid server response codes to control the response or condition you want to test in your application.</p> <p>In general, you should make sure to test your application's licensing -implementation with every response code available in the Test Response" menu. +implementation with every response code available in the Test Response menu. For a description of the codes, see <a href="#server-response-codes">Server -Response Codes</a>, below.</p> +Response Codes</a> in the Appendix of this document.</p> <div style="margin-bottom:2em;" id="licensing_test_response"> @@ -1688,10 +1690,11 @@ Test Response menu.</div> that is, it applies not to a single application, but to <em>all</em> applications associated with the publisher account. If you are testing multiple applications at once, changing the test response will affect all of those -applications on their next license check.</p> +applications on their next license check (if the user is signed into +the emulator or device using the publisher account or a test account).</p> -<p>Finally, before you can successfully send these test responses to your -application, you must sign in to the device or emulator on which the application +<p>Before you can successfully receive a test response for a license check, +you must sign in to the device or emulator on which the application is installed, and from which it is querying the server. Specifically, you must sign using either your publisher account or one of the test accounts that you have set up. For more information about test accounts, see the next section.</p> @@ -1799,7 +1802,7 @@ upload a new version if the local application increments the <p>The licensing server handles static test responses in the normal way, including signing the license response data, adding extras parameters, and so on. To support developers who are implementing licensing using test accounts, -rather than having access to the publisher account, you will need to distribute +rather than the publisher account, you will need to distribute your public key to them. Developers without access to the publisher site do not have access to your public key, and without the key they won't be able to verify license responses. </p> @@ -2176,7 +2179,7 @@ that is not installed on the device. </td> <td>No </td> <td></td> <td><em>Do not retry the license check.</em> -<p style="margin-top:.5em;">Typically caused by a developement error.</p> +<p style="margin-top:.5em;">Typically caused by a development error.</p> </td> </tr> <tr> @@ -2187,7 +2190,7 @@ application. </td> <td>No </td> <td></td> <td><em>Do not retry the license check.</em> -<p style="margin-top:.5em;">Typically caused by a developement error.</p> +<p style="margin-top:.5em;">Typically caused by a development error.</p> </td> </tr> <tr> @@ -2295,7 +2298,7 @@ the server sets a validity period as follows:</p> <ul> <li>For a paid application, the server sets the initial license validity period -so that the license reponse remains valid for as long as the application is +so that the license response remains valid for as long as the application is refundable. A licensing Policy in the application may cache the result of the initial license check and does not need to recheck the license until the validity period has expired.</li> diff --git a/docs/html/guide/topics/fundamentals.jd b/docs/html/guide/topics/fundamentals.jd index f780e7c..6d6abd8 100644 --- a/docs/html/guide/topics/fundamentals.jd +++ b/docs/html/guide/topics/fundamentals.jd @@ -770,9 +770,9 @@ return to what that instance was doing before the new intent arrived. </p> <p> -For more on launch modes, see the description of the -<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> -element. +For more on launch modes, see the description of the <code><a +href="{@docRoot}guide/topics/manifest/activity-element.html#lmode"><activity></a></code> +element. </p> diff --git a/docs/html/guide/topics/location/index.jd b/docs/html/guide/topics/location/index.jd index e988ecb..5f98902 100644 --- a/docs/html/guide/topics/location/index.jd +++ b/docs/html/guide/topics/location/index.jd @@ -4,94 +4,63 @@ page.title=Location and Maps <div id="qv-wrapper"> <div id="qv"> - <h2>Location and Maps quickview</h2> + <h2>Quickview</h2> <ul> - <li>Android provides a location framework that your application can use to determine the device's location and bearing and register for updates.</li> - <li>A Google Maps external library is available that lets you display and manage Maps data.</li> + <li>Android provides a location framework that your application can use to determine the +device's location and bearing and register for updates</li> + <li>A Google Maps external library is available that lets you display and manage Maps data</li> </ul> - <h2>In this document</h2> + + <h2>Topics</h2> <ol> - <li><a href="#location">Location Services</a></li> - <li><a href="#maps">Google Maps External Library</a></li> + <li><a href="{@docRoot}guide/topics/location/obtaining-user-location.html">Obtaining User +Location</a></li> </ol> + <h2>See Also</h2> <ol> - <li><a href="http://code.google.com/android/add-ons/google-apis/index.html">Google APIs add-on download»</a></li> + <li><a +href="http://code.google.com/android/add-ons/google-apis/maps-overview.html">Google +Maps External Library »</a></li> </ol> </div> </div> -<p>Location- and maps-based applications and services are compelling for mobile device users. You can build these capabilities into your applications using the classes of the {@link android.location} package and the Google Maps external library. The sections below provide details. </p> +<p>Location and maps-based applications are compelling for mobile device users. You +can build these capabilities into your applications using the classes of the {@link +android.location} package and the Google Maps external library. The sections below provide details. +</p> <h2 id="location">Location Services</h2> <p>Android gives your applications access to the location services supported by -the device through the classes in the <code>android.location</code> package. The +the device through the classes in the {@code android.location} package. The central component of the location framework is the -{@link android.location.LocationManager} system service, which provides an API to -determine location and bearing if the underlying device (if it supports location -capabilities). </p> +{@link android.location.LocationManager} system service, which provides APIs to +determine location and bearing of the underlying device (if available). </p> -<p>As with other system services, you do not instantiate a LocationManager directly. -Rather, you request an LocationManager instance from the system by calling -{@link android.content.Context#getSystemService(String) getSystemService(Context.LOCATION_SERVICE)}. -The method returns a handle to a new LocationManager instance.</p> +<p>As with other system services, you do not instantiate a {@link android.location.LocationManager} +directly. Rather, you request an instance from the system by calling +{@link android.content.Context#getSystemService(String) +getSystemService(Context.LOCATION_SERVICE)}. The method returns a handle to a new {@link +android.location.LocationManager} instance.</p> -<p>Once your application has a handle to a LocationManager instance, your application -will be able to do three things:</p> +<p>Once your application has a {@link android.location.LocationManager}, your application +is able to do three things:</p> <ul> - <li>Query for the list of all LocationProviders known to the - LocationManager for its last known location.</li> - <li>Register/unregister for periodic updates of current location from a - LocationProvider (specified either by Criteria or name).</li> - <li>Register/unregister for a given Intent to be fired if the device comes - within a given proximity (specified by radius in meters) of a given - lat/long.</li> + <li>Query for the list of all {@link android.location.LocationProvider}s for the last known +user location.</li> + <li>Register/unregister for periodic updates of the user's current location from a + location provider (specified either by criteria or name).</li> + <li>Register/unregister for a given {@link android.content.Intent} to be fired if the device +comes within a given proximity (specified by radius in meters) of a given lat/long.</li> </ul> -<p>However, during initial development in the emulator, you may not have access to real -data from a real location provider (Network or GPS). In that case, it may be necessary to -spoof some data for your application using a mock location provider.</p> - -<p class="note"><strong>Note:</strong> If you've used mock LocationProviders in -previous versions of the SDK, you can no longer provide canned LocationProviders -in the /system/etc/location directory. These directories will be wiped during boot-up. -Please follow the new procedures outlined below.</p> - -<h3>Providing Mock Location Data</h3> - -<p>When testing your application on the Android emulator, there are a couple different -ways to send it some mock location data: you can use the DDMS tool or the "geo" command -option in the emulator console.</p> - -<h4 id="ddms">Using DDMS</h4> -<p>With the DDMS tool, you can simulate location data a few different ways:</p> -<ul> - <li>Manually send individual longitude/latitude coordinates to the device.</li> - <li>Use a GPX file describing a route for playback to the device.</li> - <li>Use a KML file describing individual placemarks for sequenced playback to the device.</li> -</ul> -<p>For more information on using DDMS to spoof location data, see the -<a href="{@docRoot}guide/developing/tools/ddms.html#emulator-control">Using DDMS guide</a>. - -<h4 id="geo">Using the "geo" command in the emulator console</h4> -<p>Launch your application in the Android emulator and open a terminal/console in -your SDK's <code>/tools</code> directory. Connect to the emulator console. Now you can use:</p> -<ul><li><code>geo fix</code> to send a fixed geo-location. - <p>This command accepts a longitude and latitude in decimal degrees, and - an optional altitude in meters. For example:</p> - <pre>geo fix -121.45356 46.51119 4392</pre> - </li> - <li><code>geo nmea</code> to send an NMEA 0183 sentence. - <p>This command accepts a single NMEA sentence of type '$GPGGA' (fix data) or '$GPRMC' (transit data). - For example:</p> - <pre>geo nmea $GPRMC,081836,A,3751.65,S,14507.36,E,000.0,360.0,130998,011.3,E*62</pre> - </li> -</ul> +<p>For more information, read the guide to <a +href="{@docRoot}guide/topics/location/obtaining-user-location.html">Obtaining User +Location</a>.</p> -<p>For information about how to connect to the emulator console, see -<a href="{@docRoot}guide/developing/tools/emulator.html#console">Using the Emulator Console</a>.</p> <h2 id="maps">Google Maps External Library</h2> @@ -128,9 +97,9 @@ Google APIs add-on, visit</p> <p style="margin-left:2em;"><a href="http://code.google.com/android/add-ons/google-apis">http://code.google.com/android/add-ons/google-apis</a></p> -<p>For your convenience, the Google APIs add-on is also included in the Android -SDK. <!-- To learn now to use the Maps external library in your application, see -[[Using External Libraries]].--></p> +<p>For your convenience, the Google APIs add-on is also available as a downloadable component from +the Android SDK and AVD Manager (see <a href="{@docRoot}sdk/adding-components.html">Adding SDK +Components</a>).</p> <p class="note"><strong>Note:</strong> In order to display Google Maps data in a MapView, you must register with the Google Maps service and obtain a Maps API diff --git a/docs/html/guide/topics/location/obtaining-user-location.jd b/docs/html/guide/topics/location/obtaining-user-location.jd new file mode 100644 index 0000000..bc782d2 --- /dev/null +++ b/docs/html/guide/topics/location/obtaining-user-location.jd @@ -0,0 +1,454 @@ +page.title=Obtaining User Location +parent.title=Location and Maps +parent.link=index.html +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + + <h2>Quickview</h2> + <ul> + <li>The Network Location Provider provides good location data without using GPS</li> + <li>Obtaining user location can consume a lot of battery, so be careful how +long you listen for updates</li> + </ul> + <h2>In this document</h2> + <ol> + <li><a href="#Challenges">Challenges in Determining User Location</a></li> + <li><a href="#Updates">Requesting Location Updates</a> + <ol> + <li><a href="#Permission">Requesting User Permissions</a></li> + </ol> + </li> + <li><a href="#BestPerformance">Defining a Model for the Best Performance</a> + <ol> + <li><a href="#Flow">Flow for obtaining user location</a></li> + <li><a href="#StartListening">Deciding when to start listening for updates</a></li> + <li><a href="#FastFix">Getting a fast fix with the last known location</a></li> + <li><a href="#StopListening">Deciding when to stop listening for updates</a></li> + <li><a href="#BestEstimate">Maintaining a current best estimate</a></li> + <li><a href="#Adjusting">Adjusting the model to save battery and data exchange</a></li> + </ol> + </li> + <li><a href="#MockData">Providing Mock Location Data</a></li> + </ol> + <h2>Key classes</h2> + <ol> + <li>{@link android.location.LocationManager}</li> + <li>{@link android.location.LocationListener}</li> + </ol> +</div> +</div> + + <p>Knowing where the user is allows your application to be smarter and deliver +better information to the user. When developing a location-aware application for Android, you can +utilize GPS and Android's Network Location Provider to acquire the user location. Although +GPS is most accurate, it only works outdoors, it quickly consumes battery power, and doesn't return +the location as quickly as users want. Android's Network Location Provider determines user location +using cell tower and Wi-Fi signals, providing location information in a way that +works indoors and outdoors, responds faster, and uses less battery power. To obtain the user +location in your application, you can use both GPS and the Network Location Provider, or just +one.</p> + + +<h2 id="Challenges">Challenges in Determining User Location</h2> + +<p>Obtaining user location from a mobile device can be complicated. There are several reasons +why a location reading (regardless of the source) can contain errors and be inaccurate. +Some sources of error in the user location include:</p> + +<ul> + <li><b>Multitude of location sources</b> + <p>GPS, Cell-ID, and Wi-Fi can each provide a clue to users location. Determining which to use +and trust is a matter of trade-offs in accuracy, speed, and battery-efficiency.</p> + </li> + <li><b>User movement</b> + <p>Because the user location changes, you must account for movement by re-estimating user +location every so often.</p> + </li> + <li><b>Varying accuracy</b> + <p>Location estimates coming from each location source are not consistent in their +accuracy. A location obtained 10 seconds ago from one source might be more accurate than the newest +location from another or same source.</p> + </li> +</ul> + + <p>These problems can make it difficult to obtain a reliable user location reading. This +document provides information to help you meet these challenges to obtain a reliable location +reading. It also provides ideas that you can use in your +application to provide the user with an accurate and responsive geo-location experience.</p> + + +<h2 id="Updates">Requesting Location Updates</h2> + + <p>Before addressing some of the location errors described above, here is an introduction to +how you can obtain user location on Android.</p> + + <p>Getting user location in Android works by means of callback. You indicate that you'd +like to receive location updates from the {@link android.location.LocationManager} ("Location +Manager") by calling {@link android.location.LocationManager#requestLocationUpdates +requestLocationUpdates()}, passing it a +{@link android.location.LocationListener}. Your {@link android.location.LocationListener} must +implement several callback methods that the Location Manager calls when the user location +changes or when the status of the service changes.</p> + +<p>For example, the following code shows how to define a {@link android.location.LocationListener} +and request location updates: + </p> + +<pre> +// Acquire a reference to the system Location Manager +LocationManager locationManager = (LocationManager) this.getSystemService(Context.LOCATION_SERVICE); + +// Define a listener that responds to location updates +LocationListener locationListener = new LocationListener() { + public void onLocationChanged(Location location) { + // Called when a new location is found by the network location provider. + makeUseOfNewLocation(location); + } + + public void onStatusChanged(String provider, int status, Bundle extras) {} + + public void onProviderEnabled(String provider) {} + + public void onProviderDisabled(String provider) {} + }; + +// Register the listener with the Location Manager to receive location updates +locationManager.requestLocationUpdates(LocationManager.NETWORK_PROVIDER, 0, 0, locationListener); +</pre> + + <p>The first parameter in {@link +android.location.LocationManager#requestLocationUpdates requestLocationUpdates()} is the type of +location provider to use (in this case, the Network Location Provider for cell tower and Wi-Fi +based location). You can control the frequency at which your listener receives updates +with the second and third parameter—the second is the minimum time interval between +notifications and the third is the minimum change in distance between notifications—setting +both to zero requests location notifications as frequently as possible. The last parameter is your +{@link android.location.LocationListener}, which receives callbacks for location updates.</p> + +<p>To request location updates from the GPS provider, +substitute <code>GPS_PROVIDER</code> for <code>NETWORK_PROVIDER</code>. You can also request +location updates from both the GPS and the Network Location Provider by calling {@link +android.location.LocationManager#requestLocationUpdates requestLocationUpdates()} twice—once +for <code>NETWORK_PROVIDER</code> and once for <code>GPS_PROVIDER</code>.</p> + + +<h3 id="Permission">Requesting User Permissions</h3> + +<p>In order to receive location updates from <code>NETWORK_PROVIDER</code> or +<code>GPS_PROVIDER</code>, you must request user permission by declaring either the {@code +ACCESS_COARSE_LOCATION} or {@code ACCESS_FINE_LOCATION} permission, respectively, in your Android +manifest file. For example:</p> + +<pre> +<manifest ... > + <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" /> + ... +</manifest> +</pre> + +<p>Without these permissions, your application will fail at runtime when requesting +location updates.</p> + +<p class="note"><strong>Note:</strong> If you are using both <code>NETWORK_PROVIDER</code> and +<code>GPS_PROVIDER</code>, then you need to request only the {@code ACCESS_FINE_LOCATION} +permission, because it includes permission for both providers. (Permission for {@code +ACCESS_COARSE_LOCATION} includes permission only for <code>NETWORK_PROVIDER</code>.)</p> + + +<h2 id="BestPerformance">Defining a Model for the Best Performance</h2> + + <p>Location-based applications are now commonplace, but due to the less than optimal +accuracy, user movement, the multitude of methods to obtain the location, and the desire to conserve +battery, getting user location is complicated. To overcome the obstacles of obtaining a good user +location while preserving battery power, you must define a consistent model that specifies how your +application obtains the user location. This model includes when you start and stop listening for +updates and when to use cached location data.</p> + + + <h3 id="Flow">Flow for obtaining user location</h3> + + <p>Here's the typical flow of procedures for obtaining the user location:</p> + + <ol> + <li>Start application.</li> + <li>Sometime later, start listening for updates from desired location providers.</li> + <li>Maintain a "current best estimate" of location by filtering out new, but less accurate +fixes.</li> + <li>Stop listening for location updates.</li> + <li>Take advantage of the last best location estimate.</li> + </ol> + + <p>Figure 1 demonstrates this model in a timeline that visualizes the period in which an +application is listening for location updates and the events that occur during that time.</p> + +<img src="{@docRoot}images/location/getting-location.png" alt="" /> +<p class="img-caption"><strong>Figure 1.</strong> A timeline representing the window in which an +application listens for location updates.</p> + + <p>This model of a window—during which location updates are received—frames many of +the decisions you need to make when adding location-based services to your application.</p> + + + <h3 id="StartListening">Deciding when to start listening for updates</h3> + + <p>You might want to start listening for location updates as soon as your application starts, or +only after users activate a certain feature. Be aware that long windows of listening for location +fixes can consume a lot of battery power, but short periods might not allow for sufficient +accuracy.</p> + + <p>As demonstrated above, you can begin listening for updates by calling {@link +android.location.LocationManager#requestLocationUpdates requestLocationUpdates()}:</p> + +<pre> +LocationProvider locationProvider = LocationManager.NETWORK_PROVIDER; +// Or, use GPS location data: +// LocationProvider locationProvider = LocationManager.GPS_PROVIDER; + +locationManager.requestLocationUpdates(locationProvider, 0, 0, locationListener); +</pre> + + + <h3 id="FastFix">Getting a fast fix with the last known location</h3> + + <p>The time it takes for your location listener to receive the first location fix is often too +long for users wait. Until a more accurate location is provided to your location listener, you +should utilize a cached location by calling {@link +android.location.LocationManager#getLastKnownLocation}:</p> +<pre> +LocationProvider locationProvider = LocationManager.NETWORK_PROVIDER; +// Or use LocationManager.GPS_PROVIDER + +Location lastKnownLocation = locationManager.getLastKnownLocation(locationProvider); +</pre> + + + <h3 id="StopListening">Deciding when to stop listening for updates</h3> + + <p>The logic of deciding when new fixes are no longer necessary might range from very simple to +very complex depending on your application. A short gap between when the location is acquired and +when the location is used, improves the accuracy of the estimate. Always beware that listening for a +long time consumes a lot of battery power, so as soon as you have the information you need, you +should stop +listening for updates by calling {@link android.location.LocationManager#removeUpdates}:</p> +<pre> +// Remove the listener you previously added +locationManager.removeUpdates(locationListener); +</pre> + + + <h3 id="BestEstimate">Maintaining a current best estimate</h3> + + <p>You might expect that the most recent location fix is the most accurate. +However, because the accuracy of a location fix varies, the most recent fix is not always the best. +You should include logic for choosing location fixes based on several criteria. The criteria also +varies depending on the use-cases of the application and field testing.</p> + + <p>Here are a few steps you can take to validate the accuracy of a location fix:</p> + <ul> + <li>Check if the location retrieved is significantly newer than the previous estimate.</li> + <li>Check if the accuracy claimed by the location is better or worse than the previous +estimate.</li> + <li>Check which provider the new location is from and determine if you trust it more.</li> + </ul> + + <p>An elaborate example of this logic can look something like this:</p> + +<pre> +private static final int TWO_MINUTES = 1000 * 60 * 2; + +/** Determines whether one Location reading is better than the current Location fix + * @param location The new Location that you want to evaluate + * @param currentBestLocation The current Location fix, to which you want to compare the new one + */ +protected boolean isBetterLocation(Location location, Location currentBestLocation) { + if (currentBestLocation == null) { + // A new location is always better than no location + return true; + } + + // Check whether the new location fix is newer or older + long timeDelta = location.getTime() - currentBestLocation.getTime(); + boolean isSignificantlyNewer = timeDelta > TWO_MINUTES; + boolean isSignificantlyOlder = timeDelta < -TWO_MINUTES; + boolean isNewer = timeDelta > 0; + + // If it's been more than two minutes since the current location, use the new location + // because the user has likely moved + if (isSignificantlyNewer) { + return true; + // If the new location is more than two minutes older, it must be worse + } else if (isSignificantlyOlder) { + return false; + } + + // Check whether the new location fix is more or less accurate + int accuracyDelta = (int) (location.getAccuracy() - currentBestLocation.getAccuracy()); + boolean isLessAccurate = accuracyDelta > 0; + boolean isMoreAccurate = accuracyDelta < 0; + boolean isSignificantlyLessAccurate = accuracyDelta > 200; + + // Check if the old and new location are from the same provider + boolean isFromSameProvider = isSameProvider(location.getProvider(), + currentBestLocation.getProvider()); + + // Determine location quality using a combination of timeliness and accuracy + if (isMoreAccurate) { + return true; + } else if (isNewer && !isLessAccurate) { + return true; + } else if (isNewer && !isSignificantlyLessAccurate && isFromSameProvider) { + return true; + } + return false; +} + +/** Checks whether two providers are the same */ +private boolean isSameProvider(String provider1, String provider2) { + if (provider1 == null) { + return provider2 == null; + } + return provider1.equals(provider2); +} +</pre> + + + <h3 id="Adjusting">Adjusting the model to save battery and data exchange</h3> + + <p>As you test your application, you might find that your model for providing good location and +good performance needs some adjustment. Here are some things you might change to find a good +balance between the two.</p> + + <h4>Reduce the size of the window</h4> + + <p>A smaller window in which you listen for location updates means less interaction with GPS and +network location services, thus, preserving battery life. But it also allows for fewer locations +from which to choose a best estimate.</p> + + <h4>Set the location providers to return updates less frequently</h4> + + <p>Reducing the rate at which new updates appear during the window can also improve battery +efficiency, but at the cost of accuracy. The value of the trade-off depends on how your +application is used. You can reduce the rate of updates by increasing the parameters in {@link +android.location.LocationManager#requestLocationUpdates requestLocationUpdates()} that specify the +interval time and minimum distance change.</p> + + <h4>Restrict a set of providers</h4> + + <p>Depending on the environment where your application is used or the desired level of accuracy, +you might choose to use only the Network Location Provider or only GPS, instead of both. Interacting +with only one of the services reduces battery usage at a potential cost of accuracy.</p> + + + <h2>Common application cases</h2> + + <p>There are many reasons you might want to obtain the user location in your application. Below +are a couple scenarios in which you can use the user location to enrich your application. Each +scenario also describes good practices for when you should start and stop listening for the +location, in order to get a good reading and help preserve battery life.</p> + + + <h3>Tagging user-created content with a location</h3> + + <p>You might be creating an application where user-created content is tagged with a location. +Think of users sharing their local experiences, posting a review for a restaurant, or recording some +content that can be augmented with their current location. A model of how this +interaction might happen, with respect to the location services, is visualized in figure 2.</p> + + <img src="{@docRoot}images/location/content-tagging.png" alt="" /> +<p class="img-caption"><strong>Figure 2.</strong> A timeline representing the window in which +the user location is obtained and listening stops when the user consumes the current location.</p> + + <p>This lines up with the previous model of how user location is obtained in code (figure 1). For +best location accuracy, you might choose to start listening for location updates when users begin +creating +the content or even when the application starts, then stop listening for updates when content is +ready to be posted or recorded. You might need to consider how long a typical task of creating the +content takes and judge if this duration allows for efficient collection of a location estimate.</p> + + + <h3>Helping the user decide on where to go</h3> + + <p>You might be creating an application that attempts to provide users with a set +of options about where to go. For example, you're looking to provide a list of nearby restaurants, +stores, and entertainment and the order of recommendations changes depending on the user +location.</p> + + <p>To accommodate such a flow, you might choose to:</p> + <ul> + <li>Rearrange recommendations when a new best estimate is obtained</li> + <li>Stop listening for updates if the order of recommendations has stabilized</li> + </ul> + + <p>This kind of model is visualized in figure 3.</p> + + <img src="{@docRoot}images/location/where-to-go.png" alt="" /> +<p class="img-caption"><strong>Figure 3.</strong> A timeline representing the window in which a +dynamic set of data is updated each time the user location updates.</p> + + + + +<h2 id="MockData">Providing Mock Location Data</h2> + +<p>As you develop your application, you'll certainly need to test how well your model for obtaining +user location works. This is most easily done using a real Android-powered device. If, however, you +don't have a device, you can still test your location-based features by mocking location data in +the Android emulator. There are three different ways to send your application mock location +data: using Eclipse, DDMS, or the "geo" command in the emulator console.</p> + +<p class="note"><strong>Note:</strong> Providing mock location data is injected as GPS location +data, so you must request location updates from <code>GPS_PROVIDER</code> in order for mock location +data to work.</p> + +<h3 id="MockEclipse">Using Eclipse</h3> + +<p>Select <b>Window</b> > <b>Show View</b> > <b>Other</b> > <b>Emulator Control</b>.</p> + +<p>In the Emulator Control panel, enter GPS coordinates under Location Controls as individual +lat/long coordinates, with a GPX file for route playback, or a KML file for multiple place marks. +(Be sure that you have a device selected in the Devices panel—available from <b>Window</b> +> <b>Show View</b> > <b>Other</b> > <b>Devices</b>.)</p> + + +<h3 id="MockDdms">Using DDMS</h3> + +<p>With the DDMS tool, you can simulate location data a few different ways:</p> +<ul> + <li>Manually send individual longitude/latitude coordinates to the device.</li> + <li>Use a GPX file describing a route for playback to the device.</li> + <li>Use a KML file describing individual place marks for sequenced playback to the device.</li> +</ul> + +<p>For more information on using DDMS to spoof location data, see the +<a href="{@docRoot}guide/developing/tools/ddms.html#emulator-control">Using DDMS guide</a>. + + +<h3 id="MockGeo">Using the "geo" command in the emulator console</h3> + +<p>To send mock location data from the command line:</p> + +<ol> + <li>Launch your application in the Android emulator and open a terminal/console in your SDK's +<code>/tools</code> directory.</li> + <li>Connect to the emulator console: +<pre>telnet localhost <em><console-port></em></pre></li> + <li>Send the location data:</p> + <ul><li><code>geo fix</code> to send a fixed geo-location. + <p>This command accepts a longitude and latitude in decimal degrees, and + an optional altitude in meters. For example:</p> + <pre>geo fix -121.45356 46.51119 4392</pre> + </li> + <li><code>geo nmea</code> to send an NMEA 0183 sentence. + <p>This command accepts a single NMEA sentence of type '$GPGGA' (fix data) or '$GPRMC' (transit + data). + For example:</p> + <pre>geo nmea $GPRMC,081836,A,3751.65,S,14507.36,E,000.0,360.0,130998,011.3,E*62</pre> + </li> + </ul> + </li> +</ol> + +<p>For information about how to connect to the emulator console, see +<a href="{@docRoot}guide/developing/tools/emulator.html#console">Using the Emulator Console</a>.</p> diff --git a/docs/html/guide/topics/manifest/activity-element.jd b/docs/html/guide/topics/manifest/activity-element.jd index de8ca6d..e030a4c 100644 --- a/docs/html/guide/topics/manifest/activity-element.jd +++ b/docs/html/guide/topics/manifest/activity-element.jd @@ -336,10 +336,10 @@ it can also be set as a raw string. </p></dd> <dt><a name="lmode"></a>{@code android:launchMode}</dt> -<dd>An instruction on how the activity should be launched. There are four modes +<dd>An instruction on how the activity should be launched. There are four modes that work in conjunction with activity flags ({@code FLAG_ACTIVITY_*} constants) -in {@link android.content.Intent} objects to determine what should happen when -the activity is called upon to handle an intent. They are: +in {@link android.content.Intent} objects to determine what should happen when +the activity is called upon to handle an intent. They are:</p> <p style="margin-left: 2em">"{@code standard}" <br>"{@code singleTop}" @@ -351,56 +351,110 @@ The default mode is "{@code standard}". </p> <p> -The modes fall into two main groups, with "{@code standard}" and -"{@code singleTop}" activities on one side, and "{@code singleTask}" and -"{@code singleInstance}" activities on the other. An activity with the -"{@code standard}" or "{@code singleTop}" launch mode can be instantiated -multiple times. The instances can belong to any task and can be located -anywhere in the activity stack. Typically, they're launched into the task -that called +As shown in the table below, the modes fall into two main groups, with +"{@code standard}" and "{@code singleTop}" activities on one side, and +"{@code singleTask}" and "{@code singleInstance}" activities on the other. +An activity with the "{@code standard}" or "{@code singleTop}" launch mode +can be instantiated multiple times. The instances can belong to any task +and can be located anywhere in the activity stack. Typically, they're +launched into the task that called <code>{@link android.content.Context#startActivity startActivity()}</code> -(unless the Intent object contains a -<code>{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK}</code> -instruction, in which case a different task is chosen — see the +(unless the Intent object contains a +<code>{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK}</code> +instruction, in which case a different task is chosen — see the <a href="#aff">taskAffinity</a> attribute). </p> <p> -In contrast, "{@code singleTask}" and "{@code singleInstance}" activities -can only begin a task. They are always at the root of the activity stack. -Moreover, the device can hold only one instance of the activity at a time +In contrast, "<code>singleTask</code>" and "<code>singleInstance</code>" activities +can only begin a task. They are always at the root of the activity stack. +Moreover, the device can hold only one instance of the activity at a time — only one such task. </p> <p> The "{@code standard}" and "{@code singleTop}" modes differ from each other -in just one respect: Every time there's new intent for a "{@code standard}" -activity, a new instance of the class is created to respond to that intent. +in just one respect: Every time there's a new intent for a "{@code standard}" +activity, a new instance of the class is created to respond to that intent. Each instance handles a single intent. -Similarly, a new instance of a "{@code singleTop}" activity may also be -created to handle a new intent. However, if the target task already has an -existing instance of the activity at the top of its stack, that instance -will receive the new intent (in an +Similarly, a new instance of a "{@code singleTop}" activity may also be +created to handle a new intent. However, if the target task already has an +existing instance of the activity at the top of its stack, that instance +will receive the new intent (in an <code>{@link android.app.Activity#onNewIntent onNewIntent()}</code> call); a new instance is not created. -In other circumstances — for example, if an existing instance of the -"{@code singleTop}" activity is in the target task, but not at the top of -the stack, or if it's at the top of a stack, but not in the target task +In other circumstances — for example, if an existing instance of the +"{@code singleTop}" activity is in the target task, but not at the top of +the stack, or if it's at the top of a stack, but not in the target task — a new instance would be created and pushed on the stack. -</p> +</p> <p> -The "{@code singleTask}" and "{@code singleInstance}" modes also differ from -each other in only one respect: A "{@code singleTask}" activity allows other -activities to be part of its task. It's at the root of the activity stack, -but other activities (necessarily "{@code standard}" and "{@code singleTop}" -activities) can be launched into the same task. A "{@code singleInstance}" -activity, on the other hand, permits no other activities to be part of its -task. It's the only activity in the task. If it starts another activity, -that activity is assigned to a different task — as if {@code +The "{@code singleTask}" and "{@code singleInstance}" modes also differ from +each other in only one respect: A "{@code singleTask}" activity allows other +activities to be part of its task. It's always at the root of its task, but +other activities (necessarily "{@code standard}" and "{@code singleTop}" +activities) can be launched into that task. A "{@code singleInstance}" +activity, on the other hand, permits no other activities to be part of its task. +It's the only activity in the task. If it starts another activity, that +activity is assigned to a different task — as if {@code FLAG_ACTIVITY_NEW_TASK} was in the intent. </p> +<table> +<tr> +<th>Use Cases</th> +<th>Launch Mode</th> +<th>Multiple Instances?</th> +<th>Comments</th> +</tr> +<tr> +<td rowspan="2" style="width:20%;">Normal launches for most activities</td> +<td>"<code>standard</code>"</td> +<td>Yes</td> +<td>Default. The system always creates a new instance of the activity in the +target task and routes the intent to it.</td> +</tr> +<tr> +<td>"<code>singleTop</code>"</td> +<td>Conditionally</td> +<td>If an instance of the activity already exists at the top of the target task, +the system routes the intent to that instance through a call to its {@link +android.app.Activity#onNewIntent onNewIntent()} method, rather than creating a +new instance of the activity.</td> +</tr> +<tr> +<td rowspan="2">Specialized launches<br> +<em>(not recommended for general use)</em></td> +<td>"<code>singleTask</code>"</td> +<td>No</td> +<td>The system creates the activity at the root of a new task and routes the +intent to it. However, if an instance of the activity already exists, the system +routes the intent to existing instance through a call to its {@link +android.app.Activity#onNewIntent onNewIntent()} method, rather than creating a +new one.</td> +</tr> +<tr> +<td>"<code>singleInstance</code>"</td> +<td>No</td> +<td>Same as "<code>singleTask"</code>, except that the system doesn't launch any +other activities into the task holding the instance. The activity is always the +single and only member of its task.</td> +</tr> +</table> + +<p>As shown in the table above, <code>standard</code> is the default mode and is +appropriate for most types of activities. <code>SingleTop</code> is also a +common and useful launch mode for many types of activities. The other modes +— <code>singleTask</code> and <code>singleInstance</code> — are +<span style="color:red">not appropriate for most applications</span>, +since they result in an interaction model that is likely to be unfamiliar to +users and is very different from most other applications. + +<p>Regardless of the launch mode that you choose, make sure to test the usability +of the activity during launch and when navigating back to it from +other activities and tasks using the BACK key. </p> + <p>For more information on launch modes and their interaction with Intent flags, see the <a href="{@docRoot}guide/topics/fundamentals.html#acttask">Activities and diff --git a/docs/html/guide/topics/resources/color-list-resource.jd b/docs/html/guide/topics/resources/color-list-resource.jd index 449b66f..b20915c 100644 --- a/docs/html/guide/topics/resources/color-list-resource.jd +++ b/docs/html/guide/topics/resources/color-list-resource.jd @@ -55,7 +55,6 @@ In XML: <code>@[<em>package</em>:]color/<em>filename</em></code> android:state_pressed=["true" | "false"] android:state_focused=["true" | "false"] android:state_selected=["true" | "false"] - android:state_active=["true" | "false"] android:state_checkable=["true" | "false"] android:state_checked=["true" | "false"] android:state_enabled=["true" | "false"] diff --git a/docs/html/guide/topics/resources/drawable-resource.jd b/docs/html/guide/topics/resources/drawable-resource.jd index 1c3cc4d..035ddb9 100644 --- a/docs/html/guide/topics/resources/drawable-resource.jd +++ b/docs/html/guide/topics/resources/drawable-resource.jd @@ -638,7 +638,6 @@ In XML: <code>@[<em>package</em>:]drawable/<em>filename</em></code> android:state_pressed=["true" | "false"] android:state_focused=["true" | "false"] android:state_selected=["true" | "false"] - android:state_active=["true" | "false"] android:state_checkable=["true" | "false"] android:state_checked=["true" | "false"] android:state_enabled=["true" | "false"] diff --git a/docs/html/guide/topics/resources/more-resources.jd b/docs/html/guide/topics/resources/more-resources.jd index 1f03446..a647571 100644 --- a/docs/html/guide/topics/resources/more-resources.jd +++ b/docs/html/guide/topics/resources/more-resources.jd @@ -310,7 +310,7 @@ float fontSize = res.{@link android.content.res.Resources#getDimension(int) getD <TextView android:layout_height="@dimen/textview_height" android:layout_width="@dimen/textview_width" - android:textSize="@dimen/sixteen_sp"/> + android:textSize="@dimen/font_size"/> </pre> </dl> </dd> <!-- end example --> diff --git a/docs/html/images/location/content-tagging.png b/docs/html/images/location/content-tagging.png Binary files differnew file mode 100644 index 0000000..d58bfee --- /dev/null +++ b/docs/html/images/location/content-tagging.png diff --git a/docs/html/images/location/getting-location.png b/docs/html/images/location/getting-location.png Binary files differnew file mode 100644 index 0000000..a5905ec --- /dev/null +++ b/docs/html/images/location/getting-location.png diff --git a/docs/html/images/location/where-to-go.png b/docs/html/images/location/where-to-go.png Binary files differnew file mode 100644 index 0000000..59f5983 --- /dev/null +++ b/docs/html/images/location/where-to-go.png diff --git a/docs/html/index.jd b/docs/html/index.jd index 01940e8..f37a122 100644 --- a/docs/html/index.jd +++ b/docs/html/index.jd @@ -163,12 +163,11 @@ href="{@docRoot}resources/dashboard/platform-versions.html">Learn more »</ 'img':"devphone-large.png", 'title':"Android Dev Phones", 'desc': "<p>Run and debug your Android applications directly on one of these " - + "device. Modify and rebuild the Android operating system, and flash it onto " - + "the phone. The Android Dev Phones are carrier independent, and available for " - + "purchase by any developer registered with <a " - + "href='http://market.android.com/publish'>Android Market</a>.</p><p><a " - + "href='/guide/developing/device.html#dev-phone-1'>Learn more about the " - + "Android Dev Phones »</a></p>" + + "devices. Modify and rebuild the Android operating system, and flash it onto " + + "the phone. The Android Dev Phones are carrier-independent, and available for " + + "purchase by developers through their Android Market publisher accounts.</p><p> " + + "<a href='http://market.android.com/publish'>Visit Android Market " + + "to learn more »</a></p>" }, 'mapskey': { diff --git a/docs/html/resources/community-groups.jd b/docs/html/resources/community-groups.jd index 6d59648..599c4ae 100644 --- a/docs/html/resources/community-groups.jd +++ b/docs/html/resources/community-groups.jd @@ -87,27 +87,27 @@ phrasing your questions, read <a href="http://www.catb.org/%7Eesr/faqs/smart-que <h3 id="ApplicationDeveloperLists">Application developer mailing lists</h3> <ul> <li><strong><a href="http://groups.google.com/group/android-developers">android-developers</a></strong> -(<a href="mailto:android-developers-subscribe@googlegroups.com">subscribe via email</a>)<br> +(<a href="http://groups.google.com/group/android-developers/subscribe">subscribe</a>)<br> You're now an experienced Android application developer. You've grasped the basics of Android app development, you're comfortable using the SDK, now you want to move to advanced topics. Get help here with troubleshooting applications, advice on implementation, and strategies for improving your application's performance and user experience. This is the not the right place to discuss user issues (use android-discuss for that) or beginner questions with the Android SDK (use android-beginners for that). </li> <li><strong><a href="http://groups.google.com/group/android-discuss">android-discuss</a></strong> -(<a href="mailto:android-discuss-subscribe@googlegroups.com">subscribe via email</a>)<br> +(<a href="http://groups.google.com/group/android-discuss/subscribe">subscribe</a>)<br> The "water cooler" of Android discussion. You can discuss just about anything Android-related here, ideas for the Android platform, announcements about your applications, discussions about Android devices, community resources... As long as your discussion is related to Android, it's on-topic here. However, if you have a discussion here that could belong on another list, you are probably not reaching all of your target audience here and may want to consider shifting to a more targeted list. </li> <li><strong><a href="http://groups.google.com/group/android-ndk">android-ndk</a></strong> -(<a href="mailto:android-ndk-subscribe@googlegroups.com">subscribe via email</a>)<br> +(<a href="http://groups.google.com/group/android-ndk/subscribe">subscribe</a>)<br> A place for discussing the Android NDK and topics related to using native code in Android applications. </li> <li><strong><a href="http://groups.google.com/group/android-security-discuss">android-security-discuss</a></strong> -(<a href="mailto:android-security-discuss-subscribe@googlegroups.com">subscribe via email</a>)<br> +(<a href="http://groups.google.com/group/android-security-discuss/subscribe">subscribe</a>)<br> A place for open discussion on secure development, emerging security concerns, and best practices for and by android developers. Please don't disclose vulnerabilities directly on this list, you'd be putting all Android users at risk. </li> <li><strong><a href="http://groups.google.com/group/android-security-announce">android-security-announce</a></strong> -(<a href="mailto:android-security-announce-subscribe@googlegroups.com">subscribe via email</a>)<br> +(<a href="http://groups.google.com/group/android-security-announce/subscribe">subscribe</a>)<br> A low-volume group for security-related announcements by the Android Security Team. </li> </ul> diff --git a/docs/html/resources/dashboard/platform-versions.jd b/docs/html/resources/dashboard/platform-versions.jd index d4b6db5..ec47796 100644 --- a/docs/html/resources/dashboard/platform-versions.jd +++ b/docs/html/resources/dashboard/platform-versions.jd @@ -52,8 +52,9 @@ Android Market within a 14-day period ending on the data collection date noted b <div class="dashboard-panel"> <img alt="" height="250" width="460" -src="http://chart.apis.google.com/chart?&cht=p&chs=460x250&chd=t:0.3,18.9,22.1,55.5,3.3&chl=Other*| -Android%201.5|Android%201.6|Android%202.1|Android%202.2&chco=c4df9b,6fad0c" /> +src="http://chart.apis.google.com/chart?&cht=p&chs=460x250&chd=t:15.3,20.3,0.2,59.7,4.5&chl= +Android%201.5|Android%201.6|Other*|Android%202.1|Android%202.2&chco=c4df9b, +6fad0c" /> <table> <tr> @@ -61,14 +62,14 @@ Android%201.5|Android%201.6|Android%202.1|Android%202.2&chco=c4df9b,6fad0c" /> <th>API Level</th> <th>Distribution</th> </tr> -<tr><td>Android 1.5</td><td>3</td><td>18.9%</td></tr> -<tr><td>Android 1.6</td><td>4</td><td>22.1%</td></tr> -<tr><td>Android 2.1</td><td>7</td><td>55.5%</td></tr> -<tr><td>Android 2.2</td><td>8</td><td>3.3%</td></tr> +<tr><td>Android 1.5</td><td>3</td><td>15.3%</td></tr> +<tr><td>Android 1.6</td><td>4</td><td>20.3%</td></tr> +<tr><td>Android 2.1</td><td>7</td><td>59.7%</td></tr> +<tr><td>Android 2.2</td><td>8</td><td>4.5%</td></tr> </table> -<p><em>Data collected during two weeks ending on July 15, 2010</em></p> -<p style="font-size:.9em">* <em>Other: 0.3% of devices running obsolete versions</em></p> +<p><em>Data collected during two weeks ending on August 2, 2010</em></p> +<p style="font-size:.9em">* <em>Other: 0.2% of devices running obsolete versions</em></p> </div><!-- end dashboard-panel --> @@ -94,21 +95,20 @@ Android Market within a 14-day period ending on the date indicated on the x-axis <div class="dashboard-panel"> -<img alt="" height="265" width="700" style="padding:5px;background:#fff" -src="http://chart.apis.google.com/chart?&cht=lc&chs=700x265&chxt=x,y,r&chxr=0,0,10%7C1,0,100%7C2,0, -100&chxl=0%3A%7C2010/02/01%7C02/15%7C03/01%7C03/15%7C04/01%7C04/15%7C05/01%7C05/15%7C06/01%7C06/15% -7C2010/07/01%7C1%3A%7C0%25%7C25%25%7C50%25%7C75%25%7C100%25%7C2%3A%7C0%25%7C25%25%7C50%25%7C75%25% -7C100%25&chxp=0,0,1,2,3,4,5,6,7,8,9,10&chxtc=0,5&chd=t:99.0,99.2,99.4,99.5,99.6,99.6,99.6,99.7,100.6 -,101.1,99.9%7C63.4,62.5,61.6,60.6,61.5,61.7,62.3,63.5,73.0,76.4,78.6%7C22.6,23.2,24.3,25.4,29.4,30.2 -,32.7,35.3,46.2,51.3,55.1%7C0.0,0.0,0.0,0.0,4.0,28.3,32.0,34.9,45.9,51.0,54.9%7C0.0,0.0,0.0,0.0,0.0, -0.0,0.0,0.0,0.8,1.2,1.8&chm=tAndroid%201.5,7caa36,0,0,15,,t::-5%7Cb,c3df9b,0,1,0%7CtAndroid%201.6, -638d23,1,0,15,,t::-5%7Cb,b0db6e,1,2,0%7CtAndroid%202.0.1,496c13,2,0,15,,t::-5%7Cb,9ddb3d,2,3,0% -7CtAndroid%202.1,2f4708,3,5,15,,t::-5%7Cb,89cf19,3,4,0%7CB,6fad0c,4,5,0&chg=9,25&chdl=Android%201.5% -20(API%20Level%203)%7CAndroid%201.6%20(API%20Level%204)%7CAndroid%202.0.1%20(API%20Level%206)% -7CAndroid%202.1%20(API%20Level%207)%7CAndroid%202.2%20(API%20Level %208)&chco=add274, -9ad145,84c323,6ba213,507d08" /> - -<p><em>Last historical dataset collected during two weeks ending on July 1, 2010</em></p> +<img alt="" height="250" width="660" style="padding:5px;background:#fff" +src="http://chart.apis.google.com/chart?&cht=lc&chs=660x250&chxt=x,y,r&chxr=0,0,12|1,0,100|2,0,100& +chxl=0%3A%7C2010/02/01%7C02/15%7C03/01%7C03/15%7C04/01%7C04/15%7C05/01%7C05/15%7C06/01%7C06/15%7C07/ +01%7C07/15%7C2010/08/01%7C1%3A%7C0%25%7C25%25%7C50%25%7C75%25%7C100%25%7C2%3A%7C0%25%7C25%25%7C50%25 +%7C75%25%7C100%25&chxp=0,0,1,2,3,4,5,6,7,8,9,10,11,12&chxtc=0,5&chd=t:99.0,99.2,99.4,99.5,99.6,99.6, +99.6,99.7,100.6,101.1,99.9,100.0,100.0|63.4,62.5,61.6,60.6,61.5,61.7,62.3,63.5,73.0,76.4,78.6,81.1, +84.5|22.6,23.2,24.3,25.4,29.4,30.2,32.7,35.3,46.2,51.3,55.1,59.0,64.1|0.0,0.0,0.0,0.0,4.0,28.3,32.0, +34.9,45.9,51.0,54.9,58.8,64.0|0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.8,1.2,1.8,3.3,4.3&chm=tAndroid%201.5 +,7caa36,0,0,15,,t::-5|b,c3df9b,0,1,0|tAndroid%201.6,638d23,1,0,15,,t::-5|b,b0db6e,1,2,0|tAndroid%202 +.0.1,496c13,2,0,15,,t::-5|b,9ddb3d,2,3,0|tAndroid%202.1,2f4708,3,5,15,,t::-5|b,89cf19,3,4,0|B,6fad0c +,4,5,0&chg=7,25&chdl=Android%201.5|Android%201.6|Android%202.0.1|Android%202.1|Android%202.2&chco= +add274,9ad145,84c323,6ba213,507d08" /> + +<p><em>Last historical dataset collected during two weeks ending on August 2, 2010</em></p> </div><!-- end dashboard-panel --> diff --git a/docs/html/resources/dashboard/screens.jd b/docs/html/resources/dashboard/screens.jd index b20b17d..90f3f1a 100644 --- a/docs/html/resources/dashboard/screens.jd +++ b/docs/html/resources/dashboard/screens.jd @@ -49,8 +49,8 @@ ending on the data collection date noted below.</p> <div class="dashboard-panel"> <img alt="" width="460" height="250" -src="http://chart.apis.google.com/chart?&cht=p&chs=460x250&chd=t:1.8,51.5,46.6&chl=Small%20/%20ldpi| -Normal%20/%20mdpi|Normal%20/%20hdpi&chco=c4df9b,6fad0c" /> +src="http://chart.apis.google.com/chart?&cht=p&chs=460x250&chd=t:2.3,0.4,45.9,51.2&chl=Small%20/% +20ldpi|Normal%20/%20ldpi|Normal%20/%20mdpi|Normal%20/%20hdpi&chco=c4df9b,6fad0c" /> <table> <tr> @@ -60,22 +60,22 @@ Normal%20/%20mdpi|Normal%20/%20hdpi&chco=c4df9b,6fad0c" /> <th scope="col">High Density</th> </tr> <tr><th scope="row">Small</th> -<td class='cent hi'>1.8%</td> +<td class='cent hi'>2.3%</td> <td></td> <td></td> </tr> <tr><th scope="row">Normal</th> -<td></td> -<td class='cent hi'>51.5%</td> -<td class='cent hi'>46.6%</td> +<td class='cent '>0.4%</td> +<td class='cent hi'>45.9%</td> +<td class='cent hi'>51.2%</td> </tr> <tr><th scope="row">Large</th> <td></td> <td></td> <td></td> -</tr> +</tr> </table> -<p><em>Data collected during two weeks ending on July 15, 2010</em></p> +<p><em>Data collected during two weeks ending on August 2, 2010</em></p> </div> diff --git a/docs/html/resources/tutorials/views/hello-formstuff.jd b/docs/html/resources/tutorials/views/hello-formstuff.jd index 3dd5f21..b9f6c16 100644 --- a/docs/html/resources/tutorials/views/hello-formstuff.jd +++ b/docs/html/resources/tutorials/views/hello-formstuff.jd @@ -32,9 +32,19 @@ public void onCreate(Bundle savedInstanceState) { } </pre> +<p>Now select which kind of form widget you'd like to create:</p> +<ul> + <li><a href="#CustomButton">Custom Button</a></li> + <li><a href="#EditText">Edit Text</a></li> + <li><a href="#Checkbox">Checkbox</a></li> + <li><a href="#RadioButtons">Radio Buttons</a></li> + <li><a href="#ToggleButton">Toggle Button</a></li> + <li><a href="#RatingBar">Rating Bar</a></li> +</ul> -<h2>Custom Button</h2> + +<h2 id="CustomButton">Custom Button</h2> <p>In this section, you will create a button with a custom image instead of text, using the {@link android.widget.Button} widget and an XML file that defines three different images to use for the @@ -111,7 +121,8 @@ defines the action to be made when the button is clicked. In this example, a </ol> -<h2>EditText</h2> + +<h2 id="EditText">Edit Text</h2> <p>In this section, you will create a text field for user input, using the {@link android.widget.EditText} widget. Once text has been entered into the field, the "Enter" key will @@ -158,7 +169,8 @@ result in a carriage return in the text field).</p> </ol> -<h2>CheckBox</h2> + +<h2 id="Checkbox">Checkbox</h2> <p>In this section, you will create a checkbox for selecting items, using the {@link android.widget.CheckBox} widget. When the checkbox is pressed, a toast message will @@ -209,7 +221,8 @@ use the {@link android.widget.CompoundButton#setChecked(boolean)} or {@link android.widget.CompoundButton#toggle()} method.</p> -<h2>RadioButton</h2> + +<h2 id="RadioButtons">Radio Buttons</h2> <p>In this section, you will create two mutually-exclusive radio buttons (enabling one disables the other), using the {@link android.widget.RadioGroup} and {@link android.widget.RadioButton} @@ -274,7 +287,8 @@ use the {@link android.widget.CompoundButton#setChecked(boolean)} or {@link android.widget.CompoundButton#toggle()} method.</p> -<h2>ToggleButton</h2> + +<h2 id="ToggleButton">Toggle Button</h2> <p>In this section, you'll create a button used specifically for toggling between two states, using the {@link android.widget.ToggleButton} widget. This widget is an excellent @@ -330,7 +344,7 @@ android.widget.CompoundButton#toggle()} method.</p> -<h2>RatingBar</h2> +<h2 id="RatingBar">Rating Bar</h2> <p>In this section, you'll create a widget that allows the user to provide a rating, with the {@link android.widget.RatingBar} widget.</p> |
