diff options
Diffstat (limited to 'docs/html/guide')
39 files changed, 549 insertions, 256 deletions
diff --git a/docs/html/guide/appendix/api-levels.jd b/docs/html/guide/appendix/api-levels.jd index 7d119ca..cc98f8f 100644 --- a/docs/html/guide/appendix/api-levels.jd +++ b/docs/html/guide/appendix/api-levels.jd @@ -154,7 +154,7 @@ Highlights</a></td></tr> <td>2</td> <td>{@link android.os.Build.VERSION_CODES#BASE_1_1}</td><td></td></tr> - <tr><td><a href="{@docRoot}sdk/android-1.0.html">Android 1.0</td> + <tr><td>Android 1.0</td> <td>1</td> <td>{@link android.os.Build.VERSION_CODES#BASE}</td> <td></td></tr> diff --git a/docs/html/guide/appendix/market-filters.jd b/docs/html/guide/appendix/market-filters.jd index 6610f5f..07b9370 100644 --- a/docs/html/guide/appendix/market-filters.jd +++ b/docs/html/guide/appendix/market-filters.jd @@ -398,8 +398,8 @@ country (as determined by SIM carrier) in which paid apps are available.</p></td the device's SIM (for GSM devices), not the current roaming carrier.</p></li></ul> </td> </tr> <tr> <td valign="top">Native Platform</td> <td valign="top"><p>An application that includes native - libraries that target a specific platform (ARM EABI v7, for example) will only be - visible on devices that support that platform. For details about the NDK and using + libraries that target a specific platform (ARM EABI v7 or x86, for example) are + visible only on devices that support that platform. For details about the NDK and using native libraries, see <a href="{@docRoot}sdk/ndk/index.html#overview">What is the Android NDK?</a></p> </tr> <tr> <td valign="top">Copy-Protected Applications</td> <td valign="top"><p>To diff --git a/docs/html/guide/developing/device.jd b/docs/html/guide/developing/device.jd index 62ebfee..c4d08ed 100644 --- a/docs/html/guide/developing/device.jd +++ b/docs/html/guide/developing/device.jd @@ -79,10 +79,8 @@ located in <strong>Settings > Developer options</strong>).</p> <a href="{@docRoot}sdk/oem-usb.html">OEM USB Drivers</a> document.</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 <a -href="http://www.kernel.org/pub/linux/utils/kernel/hotplug/udev.html"> -<code>udev</code></a> -rules file that contains a USB configuration for each type of device + <li>If you're developing on Ubuntu Linux, you need to add a +<code>udev</code> rules file that contains a USB configuration for each type of device you want to use for development. In the rules file, each device manufacturer is identified by a unique vendor ID, as specified by the <code>ATTR{idVendor}</code> property. For a list of vendor IDs, see <a diff --git a/docs/html/guide/developing/devices/emulator.jd b/docs/html/guide/developing/devices/emulator.jd index 8211275..02dcb68 100644 --- a/docs/html/guide/developing/devices/emulator.jd +++ b/docs/html/guide/developing/devices/emulator.jd @@ -480,7 +480,7 @@ on disk images, use <code>-help-disk-images</code>.</p> <td>Enable the root shell (as in <code>-shell</code> and specify the QEMU character device to use for communication with the shell.</td> <td><device> must be a QEMU device type. See the documentation for '-serial <em>dev</em>' at - <a href="http://www.nongnu.org/qemu/qemu-doc.html#SEC10">http://www.bellard.org/qemu/qemu-doc.html#SEC10</a> + <a href="http://wiki.qemu.org/download/qemu-doc.html">http://wiki.qemu.org/download/qemu-doc.html</a> for a list of device types. <p>Here are some examples: </p> @@ -619,7 +619,7 @@ scale in direct relationship with <delay> values.</p> <td>Use this command to emulate an NMEA-compatible GPS unit connected to an external character device or socket. The format of <code><device></code> must be QEMU-specific serial device specification. See the documentation for 'serial -dev' at - <a href="http://www.bellard.org/qemu/qemu-doc.html#SEC10">http://www.bellard.org/qemu/qemu-doc.html#SEC10</a>. + <a href="http://wiki.qemu.org/download/qemu-doc.html">http://wiki.qemu.org/download/qemu-doc.html</a>. </td> </tr> <tr> @@ -638,7 +638,7 @@ scale in direct relationship with <delay> values.</p> <td>Redirect radio mode to the specified character device.</td> <td>The format of <code><device></code> must be QEMU-specific serial device specification. See the documentation for 'serial -dev' at -<a href="http://www.bellard.org/qemu/qemu-doc.html#SEC10">http://www.bellard.org/qemu/qemu-doc.html#SEC10</a>. +<a href="http://wiki.qemu.org/download/qemu-doc.html">http://wiki.qemu.org/download/qemu-doc.html</a>. </td> </tr> <tr> diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs index 3b1642f..be0ca0e 100644 --- a/docs/html/guide/guide_toc.cs +++ b/docs/html/guide/guide_toc.cs @@ -755,20 +755,20 @@ applications</span> <li class="toggle-list"> <div><a href="<?cs var:toroot ?>guide/practices/ui_guidelines/icon_design.html"> <span class="en">Icon Design</span> - </a> <span class="new">updated</span></div> + </a></div> <ul> <li><a href="<?cs var:toroot ?>guide/practices/ui_guidelines/icon_design_launcher.html"> <span class="en">Launcher Icons</span> - </a> <span class="new">updated</span></li> + </a></li> <li><a href="<?cs var:toroot ?>guide/practices/ui_guidelines/icon_design_menu.html"> <span class="en">Menu Icons</span> </a></li> <li><a href="<?cs var:toroot ?>guide/practices/ui_guidelines/icon_design_action_bar.html"> <span class="en">Action Bar Icons</span> - </a> <span class="new">new!</span></li> + </a></li> <li><a href="<?cs var:toroot ?>guide/practices/ui_guidelines/icon_design_status_bar.html"> <span class="en">Status Bar Icons</span> - </a> <span class="new">updated</span></li> + </a></li> <li><a href="<?cs var:toroot ?>guide/practices/ui_guidelines/icon_design_tab.html"> <span class="en">Tab Icons</span> </a></li> diff --git a/docs/html/guide/practices/screens-support-1.5.jd b/docs/html/guide/practices/screens-support-1.5.jd index 9f033b4..4c6fb99 100644 --- a/docs/html/guide/practices/screens-support-1.5.jd +++ b/docs/html/guide/practices/screens-support-1.5.jd @@ -46,7 +46,7 @@ android:targetSdkVersion}</a> set to {@code "4"} or higher, then this document i default, an application written for Android 1.5 or below that does not set the <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code android:targetSdkVersion}</a> set to {@code "4"} or higher runs in <a -href="screen-compat-mode">screen compatibility mode</a> when on a device with a screen larger than +href="screen-compat-mode.html">screen compatibility mode</a> when on a device with a screen larger than the <em>normal</em> screen size (basically, the system displays the application in a small window that is roughly the size of the normal screen size).</p> diff --git a/docs/html/guide/practices/security.jd b/docs/html/guide/practices/security.jd index 476c301..eeaac44 100644 --- a/docs/html/guide/practices/security.jd +++ b/docs/html/guide/practices/security.jd @@ -126,8 +126,8 @@ applications.</p> <p>Use of <a href="{@docRoot}reference/android/content/Context.html#MODE_WORLD_WRITEABLE"> world writable</a> or <a -href="{@docRoot}reference/android/content/Context.html#MODE_WORLD_READABLE -">world readable</a> files for IPC is discouraged because it does not provide +href="{@docRoot}reference/android/content/Context.html#MODE_WORLD_READABLE">world +readable</a> files for IPC is discouraged because it does not provide the ability to limit data access to particular applications, nor does it provide any control on data format. As an alternative, you might consider using a ContentProvider which provides read and write permissions, and can make @@ -199,10 +199,10 @@ ContentProvider</a></code>.</p> <p>ContentProviders can also provide more granular access by declaring the <a href="{@docRoot}guide/topics/manifest/provider-element.html#gprmsn"> grantUriPermissions</a> element and using the <code><a -href="{@docRoot}reference/android/content/Intent.html#FLAG_GRANT_READ_URI_PERMIS -SION">FLAG_GRANT_READ_URI_PERMISSION</a></code> and <code><a -href="{@docRoot}reference/android/content/Intent.html#FLAG_GRANT_WRITE_URI_PERMI -SSION">FLAG_GRANT_WRITE_URI_PERMISSION</a></code> flags in the Intent object +href="{@docRoot}reference/android/content/Intent.html#FLAG_GRANT_READ_URI_PERMISSION">FLAG_GRANT_READ_URI_PERMISSION</a></code> +and <code><a +href="{@docRoot}reference/android/content/Intent.html#FLAG_GRANT_WRITE_URI_PERMISSION">FLAG_GRANT_WRITE_URI_PERMISSION</a></code> +flags in the Intent object that activates the component. The scope of these permissions can be further limited by the <code><a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html"> @@ -211,14 +211,9 @@ grant-uri-permission element</a></code>.</p> <p>When accessing a <code> <a href="{@docRoot}reference/android/content/ContentProvider.html"> ContentProvider</a></code>, use parameterized query methods such as <code> -<a href="{@docRoot}reference/android/content/ContentProvider.html#query(android.net -.Uri,%20java.lang.String[],%20java.lang.String,%20java.lang.String[],%20java.lan -g.String)">query()</a></code>, <code><a -href="{@docRoot}reference/android/content/ContentProvider.html#update(android.ne -t.Uri,%20android.content.ContentValues,%20java.lang.String,%20java.lang.String[] -)">update()</a></code>, and <code><a -href="{@docRoot}reference/android/content/ContentProvider.html#delete(android.ne -t.Uri,%20java.lang.String,%20java.lang.String[])">delete()</a></code> to avoid +<a href="{@docRoot}reference/android/content/ContentProvider.html#query(android.net.Uri,%20java.lang.String[],%20java.lang.String,%20java.lang.String[],%20java.lang.String)">query()</a></code>, <code><a +href="{@docRoot}reference/android/content/ContentProvider.html#update(android.net.Uri,%20android.content.ContentValues,%20java.lang.String,%20java.lang.String[])">update()</a></code>, and <code><a +href="{@docRoot}reference/android/content/ContentProvider.html#delete(android.net.Uri,%20java.lang.String,%20java.lang.String[])">delete()</a></code> to avoid potential <a href="http://en.wikipedia.org/wiki/SQL_injection">SQL Injection</a> from untrusted data. Note that using parameterized methods is not sufficient if the <code>selection</code> is built by concatenating user data @@ -249,8 +244,9 @@ href="{@docRoot}reference/android/R.styleable.html#AndroidManifestActivity"> Activities</a>, and <a href="{@docRoot}reference/android/R.styleable.html#AndroidManifestService"> Services</a> are all declared in the application manifest. If your IPC mechanism is -not intended for use by other applications, set the android:exported property -to false. This is useful for applications that consist of multiple processes +not intended for use by other applications, set the <a +href="{@docRoot}guide/topics/manifest/service-element.html#exported">{@code android:exported}</a> +property to false. This is useful for applications that consist of multiple processes within the same UID, or if you decide late in development that you do not actually want to expose functionality as IPC but you don’t want to rewrite the code.</p> @@ -276,11 +272,10 @@ activity.</p> <p>Intents are the preferred mechanism for asynchronous IPC in Android. Depending on your application requirements, you might use <code><a -href="{@docRoot}reference/android/content/Context.html#sendBroadcast(android.con -tent.Intent)">sendBroadcast()</a></code>, <code><a -href="{@docRoot}reference/android/content/Context.html#sendOrderedBroadcast(andr -oid.content.Intent,%20java.lang.String)">sendOrderedBroadcast()</a></code>, or -direct an intent to a specific application component.</p> +href="{@docRoot}reference/android/content/Context.html#sendBroadcast(android.content.Intent)">sendBroadcast()</a></code>, +<code><a +href="{@docRoot}reference/android/content/Context.html#sendOrderedBroadcast(android.content.Intent,%20java.lang.String)">sendOrderedBroadcast()</a></code>, +or direct an intent to a specific application component.</p> <p>Note that ordered broadcasts can be “consumed” by a recipient, so they may not be delivered to all applications. If you are sending an Intent where @@ -311,14 +306,13 @@ and/or access controls on a specific binder interface, those controls must be explicitly added as code in the interface.</p> <p>If providing an interface that does require access controls, use <code><a -href="{@docRoot}reference/android/content/Context.html#checkCallingPermission(ja -va.lang.String)">checkCallingPermission()</a></code> to verify whether the +href="{@docRoot}reference/android/content/Context.html#checkCallingPermission(java.lang.String)">checkCallingPermission()</a></code> +to verify whether the caller of the Binder has a required permission. This is especially important before accessing a Service on behalf of the caller, as the identify of your application is passed to other interfaces. If invoking an interface provided by a Service, the <code><a -href="{@docRoot}reference/android/content/Context.html#bindService(android.conte -nt.Intent,%20android.content.ServiceConnection,%20int)">bindService()</a></code> +href="{@docRoot}reference/android/content/Context.html#bindService(android.content.Intent,%20android.content.ServiceConnection,%20int)">bindService()</a></code> invocation may fail if you do not have permission to access the given Service. If calling an interface provided locally by your own application, it may be useful to use the <code><a @@ -332,14 +326,14 @@ an intent.</p> <p>By default, receivers are exported and can be invoked by any other application. If your <code><a -href={@docRoot}reference/android/content/BroadcastReceiver.html"> +href="{@docRoot}reference/android/content/BroadcastReceiver.html"> BroadcastReceivers</a></code> is intended for use by other applications, you may want to apply security permissions to receivers using the <code><a -href="{@docRoot}reference/android/R.styleable.html#AndroidManifestReceiver"> +href="{@docRoot}guide/topics/manifest/receiver-element.html"> <receiver></a></code> element within the application manifest. This will prevent applications without appropriate permissions from sending an intent to the <code><a -href={@docRoot}reference/android/content/BroadcastReceiver.html"> +href="{@docRoot}reference/android/content/BroadcastReceiver.html"> BroadcastReceivers</a></code>.</p> <h3>Using Services</h3> @@ -349,19 +343,21 @@ use. Each service class must have a corresponding <service> declaration in its package's AndroidManifest.xml.</p> <p>By default, Services are exported and can be invoked by any other -application. Services can be protected using the android:permission attribute +application. Services can be protected using the <a +href="{@docRoot}guide/topics/manifest/service-element.html#prmsn">{@code android:permission}</a> +attribute within the manifest’s <code><a -href="{@docRoot}reference/android/R.styleable.html#AndroidManifestService"> +href="{@docRoot}guide/topics/manifest/service-element.html"> <service></a></code> tag. By doing so, other applications will need to declare a corresponding <code><a -href="{@docRoot}reference/android/R.styleable.html#AndroidManifestService_permis -sion"><uses-permission></a></code> element in their own manifest to be +href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a> +</code> element in their own manifest to be able to start, stop, or bind to the service.</p> <p>A Service can protect individual IPC calls into it with permissions, by calling <code><a -href="{@docRoot}reference/android/content/Context.html#checkCallingPermission(ja -va.lang.String)">checkCallingPermission()</a></code>before executing +href="{@docRoot}reference/android/content/Context.html#checkCallingPermission(java.lang.String)">checkCallingPermission()</a></code> +before executing the implementation of that call. We generally recommend using the declarative permissions in the manifest, since those are less prone to oversight.</p> @@ -376,9 +372,9 @@ Service to handle IPC, since this modular approach reduces the risk of exposing functionality that is not intended for use by other applications.</p> <p>If you do expose an Activity for purposes of IPC, the <code><a -href="{@docRoot}reference/android/R.styleable.html#AndroidManifestActivity_permi -ssion">android:permission</a></code> attribute in the <code><a -href="{@docRoot}reference/android/R.styleable.html#AndroidManifestActivity"> +href="{@docRoot}guide/topics/manifest/activity-element.html#prmsn">android:permission</a></code> +attribute in the <code><a +href="{@docRoot}guide/topics/manifest/activity-element.html"> <activity></a></code> declaration in the application manifest can be used to restrict access to only those applications which have the stated permissions.</p> @@ -432,8 +428,8 @@ rkeley.edu/~afelt/felt_usenixsec2011.pdf</a></p> <p>Generally, you should strive to create as few permissions as possible while satisfying your security requirements. Creating a new permission is relatively uncommon for most applications, since <a -href="{@docRoot}reference/android/Manifest.permission.html"> -system-defined permissions</a> cover many situations. Where appropriate, +href="{@docRoot}reference/android/Manifest.permission.html">system-defined +permissions</a> cover many situations. Where appropriate, perform access checks using existing permissions.</p> <p>If you must create a new permission, consider whether you can accomplish @@ -560,17 +556,14 @@ href="{@docRoot}reference/android/webkit/WebView.html">WebView</a></code> does not execute JavaScript so cross-site-scripting is not possible.</p> <p>Use <code><a -href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(jav -a.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> with +href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(java.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> with particular care because it allows JavaScript to invoke operations that are normally reserved for Android applications. Only expose <code><a -href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(jav -a.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> to +href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(java.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> to sources from which all input is trustworthy. If untrusted input is allowed, untrusted JavaScript may be able to invoke Android methods. In general, we recommend only exposing <code><a -href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(jav -a.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> to +href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(java.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> to JavaScript that is contained within your application APK.</p> <p>Do not trust information downloaded over HTTP, use HTTPS instead. Even if @@ -578,13 +571,11 @@ you are connecting only to a single website that you trust or control, HTTP is subject to <a href="http://en.wikipedia.org/wiki/Man-in-the-middle_attack">MiTM</a> attacks and interception of data. Sensitive capabilities using <code><a -href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(jav -a.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> should +href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(java.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> should not ever be exposed to unverified script downloaded over HTTP. Note that even with the use of HTTPS, <code><a -href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(jav -a.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> +href="{@docRoot}reference/android/webkit/WebView.html#addJavascriptInterface(java.lang.Object,%20java.lang.String)">addJavaScriptInterface()</a></code> increases the attack surface of your application to include the server infrastructure and all CAs trusted by the Android-powered device.</p> @@ -683,8 +674,7 @@ discussed in the Requesting Permissions section.</p> <p>If a GUID is required, create a large, unique number and store it. Do not use phone identifiers such as the phone number or IMEI which may be associated with personal information. This topic is discussed in more detail in the <a -href="http://android-developers.blogspot.com/2011/03/identifying-app-installatio -ns.html">Android Developer Blog</a>.</p> +href="http://android-developers.blogspot.com/2011/03/identifying-app-installations.html">Android Developer Blog</a>.</p> <p>Application developers should be careful writing to on-device logs. In Android, logs are a shared resource, and are available @@ -724,9 +714,8 @@ credentials to the wrong application.</p> <p>If credentials are to be used only by applications that you create, then you can verify the application which accesses the <code><a href="{@docRoot}reference/android/accounts/AccountManager.html"> -AccountManager</a></code> using <code><a href="<code><a -href="{@docRoot}h/reference/android/content/pm/PackageManager.html#checkSignatur -es(java.lang.String,%20java.lang.String)">checkSignature()</a></code>. +AccountManager</a></code> using <code><a +href="{@docRoot}reference/android/content/pm/PackageManager.html#checkSignatures(java.lang.String,%20java.lang.String)">checkSignature()</a></code>. Alternatively, if only one application will use the credential, you might use a <code><a href={@docRoot}reference/java/security/KeyStore.html">KeyStore</a></code> for @@ -756,15 +745,15 @@ RSA provided in the <code><a href="{@docRoot}reference/javax/crypto/Cipher.html">Cipher</a></code> class.</p> <p>Use a secure random number generator ( -<a href="http://developer.android.com/reference/java/security/SecureRandom.html"> +<a href="{@docRoot}reference/java/security/SecureRandom.html"> <code>SecureRandom</code></a>) to initialize any cryptographic keys (<a -href="http://developer.android.com/reference/javax/crypto/KeyGenerator.html"> +href="{@docRoot}reference/javax/crypto/KeyGenerator.html"> <code>KeyGenerator</code></a>). Use of a key that is not generated with a secure random number generator significantly weakens the strength of the algorithm, and may allow offline attacks.</p> <p>If you need to store a key for repeated use, use a mechanism like <code><a -href={@docRoot}reference/java/security/KeyStore.html">KeyStore</a></code> that +href="{@docRoot}reference/java/security/KeyStore.html">KeyStore</a></code> that provides a mechanism for long term storage and retrieval of cryptographic keys.</p> diff --git a/docs/html/guide/practices/tablets-and-handsets.jd b/docs/html/guide/practices/tablets-and-handsets.jd index dc35801..3f4aaa9 100644 --- a/docs/html/guide/practices/tablets-and-handsets.jd +++ b/docs/html/guide/practices/tablets-and-handsets.jd @@ -481,7 +481,7 @@ href="{@docRoot}guide/topics/ui/actionbar.html#Home">Action Bar</a> developer gu information in each list item based on the available space. That is, you can create alternative layouts to be used by the items in your list adapter such that a large screen might display more detail for each item.</li> - <li>Create <a href="{@docRoot}guide/topics/resources/more-resources.html ">alternative resource + <li>Create <a href="{@docRoot}guide/topics/resources/more-resources.html">alternative resource files</a> for values such as integers, dimensions, and even booleans. Using size qualifiers for these resources, you can easily apply different layout sizes, font sizes, or enable/disable features based on the current screen size.</li> diff --git a/docs/html/guide/practices/ui_guidelines/activity_task_design.jd b/docs/html/guide/practices/ui_guidelines/activity_task_design.jd index 31ad466..5faa7ec 100644 --- a/docs/html/guide/practices/ui_guidelines/activity_task_design.jd +++ b/docs/html/guide/practices/ui_guidelines/activity_task_design.jd @@ -40,7 +40,7 @@ parent.link=index.html <li><a href=#reusing_tip>Handle case where no activity matches</a></li> <li><a href=#activity_launching_tip>Consider how to launch your activities</a></li> <li><a href=#activities_added_to_task_tip>Allow activities to add to current task</a></li> - <li><a href=#notifications_get_back_tip>Notifications should let user easily get back</li> + <li><a href=#notifications_get_back_tip>Notifications and App Widgets should provide consistent back behavior</li> <li><a href=#use_notification_tip>Use the notification system</a></li> <li><a href=#taking_over_back_key>Don't take over BACK key unless you absolutely need to</a></li> </ol> @@ -1063,110 +1063,23 @@ MAIN and </p> -<h3 id="notifications_get_back_tip">Notifications should let the user easily get back to the previous activity</h3> +<h3 id="notifications_get_back_tip">Notifications and App Widgets should provide consistent back behavior</h3> <p> - Applications that are in the background or not running can have - services that send out notifications to the user letting them know about - events of interest. Two examples are Calendar, which can send out notifications of - upcoming events, and Email, which can send out notifications when new - messages arrive. One of the user interface guidelines is that when the - user is in activity A, gets a notification for activity B and - picks that notification, when they press the BACK key, they should - go back to activity A. + Notifications and app widgets are two common ways that a user can launch + your app through something besides its main icon in Launcher. You must + take care when implementing these so that the user has a consistent experience + with the back button, not causing surprises in where they return to or the + state the application ends up in. </p> <p> - The following scenario shows how the activity stack should work - when the user responds to a notification. -</p> - -<ol> - <li> - User is creating a new event in Calendar. They realize they - need to copy part of an email message into this event - </li> - <li> - The user chooses Home > Gmail - </li> - <li> - While in Gmail, they receive a notification from Calendar for an upcoming meeting - </li> - <li> - So they choose that notification, which takes them to a - dedicated Calendar activity that displays brief details of the - upcoming meeting - </li> - <li> - The user chooses this short notice to view further details - </li> - <li> - When done viewing the event, the user presses the BACK - key. They should be taken to Gmail, which is where they were - when they took the notification - </li> -</ol> - -<p> -This behavior doesn't necessarily happen by default. -</p> - -<p> -Notifications generally happen primarily in one of two ways: -</p> - - <ul> - <li> - <b>The chosen activity is dedicated for notification only</b> - - For example, when the user receives a - Calendar notification, choosing that - notification starts a special activity that displays a list - of upcoming calendar events — this view is available only - from the notification, not through the Calendar's own user - interface. After viewing this upcoming event, to ensure that - the user pressing the BACK key will return to the activity - the user was in when they picked the notification, you would - make sure this dedicated activity does not have the same - task affinity as the Calendar or any other activity. (You do - this by setting task affinity to the empty string, which - means it has no affinity to anything.) The explanation for - this follows. - - <p> - Because of the way tasks work, if the taskAffinity of the - dedicated activity is kept as its default, then pressing the - BACK key (in step 6, above) would go to Calendar, rather - than Gmail. The reason is that, by default, all activities - in a given application have the same task - affinity. Therefore, the task affinity of the dedicated - activity matches the Calendar task, which is already running - in step 1. This means in step 4, choosing the notification - brings the existing Calendar event (in step 1) forward and - starts the dedicated activity on top of it. This is not - what you want to have happen. Setting the dedicated - activity's taskAffinity to empty string fixes this. - </p> - </li> - - <li> - <b>The chosen activity is not dedicated, but always comes to - the foreground in its initial state</b> - For example, in - response to a notification, when the Gmail application comes - to the foreground, it always presents the list of conversations. - You can ensure this happens by setting a "clear top" flag in the - intent that the notification triggers. This ensures that when the - activity is launched, it displays its initial activity, preventing - Gmail from coming to the foreground in whatever state the user last - happened to be viewing it. (To do this, you put {@link - android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP - FLAG_ACTIVITY_CLEAR_TOP} in the intent you pass to startActivity()). - </li> - </ul> - -<p> - There are other ways to handle notifications, such as bringing the - activity to the foreground, set to display specific data, such as - displaying the text message thread for the person who just sent a - new text message. + The + <a href="{@docRoot}guide/topics/ui/notifiers/notifications.html#HandlingNotifications">Handling + Notifications</a> section of the developer guide's + <a href="{@docRoot}guide/topics/ui/notifiers/notifications.html">Status Bar Notifications</a> + documentation provides an overview of how to write code to correctly handle + notification. This dicussion applies equally to handling interactions with + app widgets. </p> <p> diff --git a/docs/html/guide/practices/ui_guidelines/icon_design.jd b/docs/html/guide/practices/ui_guidelines/icon_design.jd index 07b73bb..96aecf5 100644 --- a/docs/html/guide/practices/ui_guidelines/icon_design.jd +++ b/docs/html/guide/practices/ui_guidelines/icon_design.jd @@ -57,6 +57,16 @@ Screens</a></li> </div> </div> + +<div class="design-announce"> +<p><strong>New Guides for App Designers!</strong></p> +<p>Check out the new documents for designers at <strong><a +href="{@docRoot}design/index.html">Android Design</a></strong>, including more guidelines +for <a href="{@docRoot}design/style/iconography.html">Iconography</a>.</p> +</div> + + + <p>Creating a unified look and feel throughout a user interface adds value to your product. Streamlining the graphic style will also make the UI seem more professional to users.</p> diff --git a/docs/html/guide/practices/ui_guidelines/icon_design_action_bar.jd b/docs/html/guide/practices/ui_guidelines/icon_design_action_bar.jd index 449c27f..2476255 100644 --- a/docs/html/guide/practices/ui_guidelines/icon_design_action_bar.jd +++ b/docs/html/guide/practices/ui_guidelines/icon_design_action_bar.jd @@ -29,6 +29,12 @@ Screens</a></li> </div> </div> +<div class="design-announce"> +<p><strong>New Guides for App Designers!</strong></p> +<p>Check out the new documents for designers at <strong><a +href="{@docRoot}design/index.html">Android Design</a></strong>, including more guidelines +for <a href="{@docRoot}design/style/iconography.html">Iconography</a>.</p> +</div> <p>Action Bar icons are graphical elements placed in the <a diff --git a/docs/html/guide/practices/ui_guidelines/icon_design_dialog.jd b/docs/html/guide/practices/ui_guidelines/icon_design_dialog.jd index f78bd86..9b8cce7 100644 --- a/docs/html/guide/practices/ui_guidelines/icon_design_dialog.jd +++ b/docs/html/guide/practices/ui_guidelines/icon_design_dialog.jd @@ -27,6 +27,12 @@ Screens</a></li> </div> </div> +<div class="design-announce"> +<p><strong>New Guides for App Designers!</strong></p> +<p>Check out the new documents for designers at <strong><a +href="{@docRoot}design/index.html">Android Design</a></strong>, including more guidelines +for <a href="{@docRoot}design/style/iconography.html">Iconography</a>.</p> +</div> <p>Dialog icons are shown in pop-up dialog boxes that prompt the user for diff --git a/docs/html/guide/practices/ui_guidelines/icon_design_launcher.jd b/docs/html/guide/practices/ui_guidelines/icon_design_launcher.jd index 3f6061c..6b686b1 100644 --- a/docs/html/guide/practices/ui_guidelines/icon_design_launcher.jd +++ b/docs/html/guide/practices/ui_guidelines/icon_design_launcher.jd @@ -26,6 +26,15 @@ Screens</a></li> </div> +<div class="design-announce"> +<p><strong>New Guides for App Designers!</strong></p> +<p>Check out the new documents for designers at <strong><a +href="{@docRoot}design/index.html">Android Design</a></strong>, including more guidelines +for <a href="{@docRoot}design/style/iconography.html">Iconography</a>.</p> +</div> + + + <p>A launcher icon is a graphic that represents your application. Launcher icons are used by Launcher applications and appear on the user’s Home screen. Launcher icons can also be used to represent shortcuts into your application (for example, a contact shortcut icon that opens detail diff --git a/docs/html/guide/practices/ui_guidelines/icon_design_list.jd b/docs/html/guide/practices/ui_guidelines/icon_design_list.jd index 7bf34cc..fd4dc6b 100644 --- a/docs/html/guide/practices/ui_guidelines/icon_design_list.jd +++ b/docs/html/guide/practices/ui_guidelines/icon_design_list.jd @@ -28,6 +28,13 @@ Screens</a></li> </div> +<div class="design-announce"> +<p><strong>New Guides for App Designers!</strong></p> +<p>Check out the new documents for designers at <strong><a +href="{@docRoot}design/index.html">Android Design</a></strong>, including more guidelines +for <a href="{@docRoot}design/style/iconography.html">Iconography</a>.</p> +</div> + <p>List view icons look a lot like dialog icons, but they use an inner shadow effect where the light source is above the object. They are also designed to be diff --git a/docs/html/guide/practices/ui_guidelines/icon_design_menu.jd b/docs/html/guide/practices/ui_guidelines/icon_design_menu.jd index 974e48f..e267013 100644 --- a/docs/html/guide/practices/ui_guidelines/icon_design_menu.jd +++ b/docs/html/guide/practices/ui_guidelines/icon_design_menu.jd @@ -32,6 +32,13 @@ Screens</a></li> </div> +<div class="design-announce"> +<p><strong>New Guides for App Designers!</strong></p> +<p>Check out the new documents for designers at <strong><a +href="{@docRoot}design/index.html">Android Design</a></strong>, including more guidelines +for <a href="{@docRoot}design/style/iconography.html">Iconography</a>.</p> +</div> + <p>Menu icons are graphical elements placed in the options menu shown to users when they press the Menu button. They are drawn in a flat-front perspective and diff --git a/docs/html/guide/practices/ui_guidelines/icon_design_status_bar.jd b/docs/html/guide/practices/ui_guidelines/icon_design_status_bar.jd index b8e07b5..a20c1ee 100644 --- a/docs/html/guide/practices/ui_guidelines/icon_design_status_bar.jd +++ b/docs/html/guide/practices/ui_guidelines/icon_design_status_bar.jd @@ -40,6 +40,13 @@ Screens</a></li> </div> +<div class="design-announce"> +<p><strong>New Guides for App Designers!</strong></p> +<p>Check out the new documents for designers at <strong><a +href="{@docRoot}design/index.html">Android Design</a></strong>, including more guidelines +for <a href="{@docRoot}design/style/iconography.html">Iconography</a>.</p> +</div> + <p>Status bar icons are used to represent notifications from your application in the status bar.</p> diff --git a/docs/html/guide/practices/ui_guidelines/icon_design_tab.jd b/docs/html/guide/practices/ui_guidelines/icon_design_tab.jd index 271bd85..f85398d 100644 --- a/docs/html/guide/practices/ui_guidelines/icon_design_tab.jd +++ b/docs/html/guide/practices/ui_guidelines/icon_design_tab.jd @@ -32,6 +32,13 @@ Screens</a></li> </div> +<div class="design-announce"> +<p><strong>New Guides for App Designers!</strong></p> +<p>Check out the new documents for designers at <strong><a +href="{@docRoot}design/index.html">Android Design</a></strong>, including more guidelines +for <a href="{@docRoot}design/style/iconography.html">Iconography</a>.</p> +</div> + <p>Tab icons are graphical elements used to represent individual tabs in a multi-tab interface. Each tab icon has two states: unselected and selected.</p> diff --git a/docs/html/guide/practices/ui_guidelines/index.jd b/docs/html/guide/practices/ui_guidelines/index.jd index 0e42788..3255275 100644 --- a/docs/html/guide/practices/ui_guidelines/index.jd +++ b/docs/html/guide/practices/ui_guidelines/index.jd @@ -2,18 +2,28 @@ page.title=User Interface Guidelines @jd:body -<img src="{@docRoot}assets/images/uiguidelines1.png" alt="" align="right"> + +<div class="design-announce" style="background:none;overflow:auto;padding:10px 5px"> + <a href="{@docRoot}design/index.html"><img src="{@docRoot}images/home/android-design.png" alt="" +style="float:left;margin:0 1em 0 0;"/></a> +<p><strong>New Guides for App Designers!</strong></p> +<p>The Android UX team has put together a set of guidelines for the interaction and +visual design of Android applications. The new collection provides an overview of +Android styles, design patterns, building blocks for exceptional Android designs, and more.</p> +<p><strong><a href="{@docRoot}design/index.html">Android Design</a></strong></p> + +<p>Over time, the documents below will be deprecated as more design information is published at +the new location.</p> +</div> + -<p>The Android UI team has begun developing guidelines for the interaction and -visual design of Android applications. Look here for articles that describe -these guidelines as we release them.</p> <dl> <dt><a href="{@docRoot}guide/practices/ui_guidelines/icon_design.html">Icon Design Guidelines</a> and <a href="{@docRoot}shareables/icon_templates-v4.0.zip">Android Icon Templates Pack -» </a> <span class="new">updated</span></dt> +» </a></dt> <dd>Your applications need a wide variety of icons, from a launcher icon to icons in menus, dialogs, tabs, the status bar, and lists. The Icon Guidelines describe each kind of icon in detail, with specifications for the size, color, @@ -22,7 +32,8 @@ The Icon Templates Pack is an archive of Photoshop and Illustrator templates and filters that make it much simpler to create conforming icons.</dd> </dl> <dl> - <dt><a href="{@docRoot}guide/practices/ui_guidelines/widget_design.html">Widget Design Guidelines</a> <span class="new">updated</span></dt> + <dt><a href="{@docRoot}guide/practices/ui_guidelines/widget_design.html">Widget Design +Guidelines</a> </dt> <dd>A widget displays an application's most important or timely information at a glance, on a user's Home screen. These design guidelines describe how to design widgets that fit with others on the Home screen. They include links to @@ -43,7 +54,7 @@ graphics files and templates that will make your designer's life easier.</dd> <dd>Android applications make use of Option menus and Context menus that enable users to perform operations and navigate to other parts of your application or to other applications. These guidelines describe - the difference between Options and Context menus, how to arrange + the difference between Options anontext menus, how to arrange menu items, when to put commands on-screen, and other details about menu design. </dd> diff --git a/docs/html/guide/practices/ui_guidelines/widget_design.jd b/docs/html/guide/practices/ui_guidelines/widget_design.jd index f63f3c4..d789407 100644 --- a/docs/html/guide/practices/ui_guidelines/widget_design.jd +++ b/docs/html/guide/practices/ui_guidelines/widget_design.jd @@ -44,6 +44,13 @@ parent.link=index.html </div> +<div class="design-announce"> +<p><strong>New Guides for App Designers!</strong></p> +<p>Check out the new documents for designers at <strong><a +href="{@docRoot}design/index.html">Android Design</a></strong>.</p> +</div> + + <p>App widgets (sometimes just "widgets") are a feature introduced in Android 1.5 and vastly improved in Android 3.0 and 3.1. A widget can display an application's most timely or otherwise relevant information at a glance, on a user's Home screen. The standard Android system image diff --git a/docs/html/guide/publishing/preparing.jd b/docs/html/guide/publishing/preparing.jd index 5ed55fe..4d3bffa 100644 --- a/docs/html/guide/publishing/preparing.jd +++ b/docs/html/guide/publishing/preparing.jd @@ -120,8 +120,8 @@ suitable private key</a>.</p> <p>You may also have to obtain other release keys if your application accesses a service or uses a third-party library that requires you to use a key that is based on your private key. For example, if your application uses the <a -href="http://code.google.com/android/add-ons/google-apis/reference/com/google/android/maps/ MapView. -html">MapView</a> class, which is part of the <a +href="http://code.google.com/android/add-ons/google-apis/reference/com/google/android/maps/MapView.html">MapView</a> +class, which is part of the <a href="http://code.google.com/android/add-ons/google-apis/maps-overview.html">Google Maps external library</a>, you will need to register your application with the Google Maps service and obtain a Maps API key. For information about getting a Maps API key, see <a diff --git a/docs/html/guide/publishing/publishing_overview.jd b/docs/html/guide/publishing/publishing_overview.jd index a0f6ae3..e30360b 100755 --- a/docs/html/guide/publishing/publishing_overview.jd +++ b/docs/html/guide/publishing/publishing_overview.jd @@ -21,7 +21,7 @@ page.title=Publishing Overview </ol> <h2>See also</h2> <ol> - <li><a href="{@docRoot}guide/publishing/publishing_preparing.html">Preparing for + <li><a href="{@docRoot}guide/publishing/preparing.html">Preparing for Release</a></li> <li><a href="{@docRoot}guide/publishing/publishing.html">Publishing on Android Market</a></li> </ol> diff --git a/docs/html/guide/topics/appwidgets/index.jd b/docs/html/guide/topics/appwidgets/index.jd index 7b869a0..ba7b67c 100644 --- a/docs/html/guide/topics/appwidgets/index.jd +++ b/docs/html/guide/topics/appwidgets/index.jd @@ -518,15 +518,12 @@ method. From within the Service, you can perform your own updates to the App Widget without worrying about the AppWidgetProvider closing down due to an <a href="{@docRoot}guide/practices/design/responsiveness.html">Application Not Responding</a> (ANR) error. See the <a -href="http://code.google.com/p/wiktionary-android/source/browse/trunk/Wiktionary -/src/com/example/android/wiktionary/WordWidget.java">Wiktionary sample's -AppWidgetProvider</a> for an example of an App Widget running a {@link +href="http://code.google.com/p/wiktionary-android/source/browse/trunk/Wiktionary/src/com/example/android/wiktionary/WordWidget.java">Wiktionary sample's AppWidgetProvider</a> for an example of an App Widget running a {@link android.app.Service}.</p> <p>Also see the <a -href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/ -appwidget/ExampleAppWidgetProvider.html"> -ExampleAppWidgetProvider.java</a> sample class.</p> +href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/appwidget/ExampleAppWidgetProvider.html">ExampleAppWidgetProvider.java</a> +sample class.</p> <h3 id="ProviderBroadcasts">Receiving App Widget broadcast Intents</h3> @@ -683,9 +680,8 @@ cancelled and the App Widget will not be added.</p> <p>See the <a -href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/ -appwidget/ExampleAppWidgetConfigure.html"> -ExampleAppWidgetConfigure.java</a> sample class in ApiDemos for an example.</p> +href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/appwidget/ExampleAppWidgetConfigure.html">ExampleAppWidgetConfigure.java</a> +sample class in ApiDemos for an example.</p> <h2 id="preview">Setting a Preview Image</h2> diff --git a/docs/html/guide/topics/fundamentals/tasks-and-back-stack.jd b/docs/html/guide/topics/fundamentals/tasks-and-back-stack.jd index 5a1f7a2..086ba71 100644 --- a/docs/html/guide/topics/fundamentals/tasks-and-back-stack.jd +++ b/docs/html/guide/topics/fundamentals/tasks-and-back-stack.jd @@ -34,7 +34,9 @@ to perform other tasks without losing their work</li> <h2>See also</h2> <ol> - <li><a><a href="{@docRoot}videos/index.html#v=fL6gSd4ugSI">Application Lifecycle video</a></li> + <li><a href="{@docRoot}design/patterns/navigation.html">Android Design: +Navigation</a></li> + <li><a href="{@docRoot}videos/index.html#v=fL6gSd4ugSI">Application Lifecycle video</a></li> <li><a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>} manifest element</a></li> @@ -172,6 +174,13 @@ destroyed. The previous activity in the stack is resumed. When an activity is de </ul> +<div class="design-announce"> +<p><strong>Navigation Design</strong></p> + <p>For more about how app navigation works on Android, read Android Design's <a +href="{@docRoot}design/patterns/navigation.html">Navigation</a> guide.</p> +</div> + + <h2 id="ActivityState">Saving Activity State</h2> <p>As discussed above, the system's default behavior preserves the state of an activity when it is diff --git a/docs/html/guide/topics/manifest/activity-element.jd b/docs/html/guide/topics/manifest/activity-element.jd index e23fb0ec..e76a6be 100644 --- a/docs/html/guide/topics/manifest/activity-element.jd +++ b/docs/html/guide/topics/manifest/activity-element.jd @@ -59,7 +59,7 @@ by the system and will never be run. <dt>attributes:</dt> <dd><dl class="attr"> -<dt><a href name="reparent"></a>{@code android:allowTaskReparenting}</dt> +<dt><a name="reparent"></a>{@code android:allowTaskReparenting}</dt> <dd>Whether or not the activity can move from the task that started it to the task it has an affinity for when that task is next brought to the front — "{@code true}" if it can move, and "{@code false}" if it diff --git a/docs/html/guide/topics/manifest/application-element.jd b/docs/html/guide/topics/manifest/application-element.jd index 4f1964c..df6f61a 100644 --- a/docs/html/guide/topics/manifest/application-element.jd +++ b/docs/html/guide/topics/manifest/application-element.jd @@ -249,7 +249,7 @@ of that name is created. A global process can be shared with other applications, reducing resource usage. </p></dd> -<dt><a href name="restoreany"></a>{@code android:restoreAnyVersion}</dt> +<dt><a name="restoreany"></a>{@code android:restoreAnyVersion}</dt> <dd>Indicate that the application is prepared to attempt a restore of any backed-up data set, even if the backup was stored by a newer version of the application than is currently installed on the device. Setting @@ -260,7 +260,7 @@ incompatible. <em>Use with caution!</em> <p>The default value of this attribute is {@code false}. </p></dd> -<dt><a href name="aff"></a>{@code android:taskAffinity}</dt> +<dt><a name="aff"></a>{@code android:taskAffinity}</dt> <dd>An affinity name that applies to all activities within the application, except for those that set a different affinity with their own <code><a href="{@docRoot}guide/topics/manifest/activity-element.html#aff">taskAffinity</a></code> diff --git a/docs/html/guide/topics/manifest/uses-sdk-element.jd b/docs/html/guide/topics/manifest/uses-sdk-element.jd index b371f34..99c91f6 100644 --- a/docs/html/guide/topics/manifest/uses-sdk-element.jd +++ b/docs/html/guide/topics/manifest/uses-sdk-element.jd @@ -60,7 +60,7 @@ href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a>.</p> attribute, the system assumes a default value of "1", which indicates that your application is compatible with all versions of Android. If your 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>android:minSdkVersion</code>, + 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 @@ -68,18 +68,32 @@ href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a>.</p> </dd> <dt><a name="target"></a>{@code android:targetSdkVersion}</dt> - <dd>An integer designating the API Level that the application is targetting. - - <p>With this attribute set, the application says that it is able to run on - older versions (down to {@code minSdkVersion}), but was explicitly tested to - work with the version specified here. Specifying this target version allows the - platform to disable compatibility settings that are not required for the target - version (which may otherwise be turned on in order to maintain - forward-compatibility) or enable newer features that are not available to older - applications. This does not mean that you can program different features for - different versions of the platform—it simply informs the platform that you - have tested against the target version and the platform should not perform any - extra work to maintain forward-compatibility with the target version.</p> + <dd>An integer designating the API Level that the application targets. If not set, the default +value equals that given to {@code minSdkVersion}. + + <p>This attribute informs the system that you have tested against the target version and the +system should not enable any compatibility behaviors to maintain your app's forward-compatibility +with the target version. The application is still able to run on older versions (down to {@code +minSdkVersion}).</p> + + <p>As Android evolves with each new version, some behaviors and even appearances might change. +However, if the API level of the platform is higher than the version declared by your app's {@code +targetSdkVersion}, the system may enable compatibility behaviors to ensure that your app +continues to work the way you expect. You can disable such compatibility +behaviors by specifying {@code targetSdkVersion} to match the API +level of the platform on which it's running. For example, setting this value to "11" or higher +allows the system to apply a new default theme (Holo) to your app when running on Android 3.0 or +higher and also disables <a href="{@docRoot}guide/practices/screen-compat-mode.html">screen +compatibility mode</a> when running on larger screens (because support for API level 11 implicitly +supports larger screens).</p> + + <p>There are many compatibility behaviors that the system may enable based on the value you set +for this attribute. Several of these behaviors are described by the corresponding platform versions +in the {@link android.os.Build.VERSION_CODES} reference.</p> + + <p>To maintain your application along with each Android release, you should increase +the value of this attribute to match the latest API level, then thoroughly test your application on +the corresponding platform version.</p> <p>Introduced in: API Level 4</p> </dd> @@ -89,25 +103,25 @@ href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a>.</p> designed to run. <p>In Android 1.5, 1.6, 2.0, and 2.0.1, the system checks the value of this - attribute when installing an application and when revalidating the application + attribute when installing an application and when re-validating the application after a system update. In either case, if the application's - <code>android:maxSdkVersion</code> attribute is lower than the API Level used by + <code>maxSdkVersion</code> attribute is lower than the API Level used by the system itself, then the system will not allow the application to be - installed. In the case of revalidation after system update, this effectively + installed. In the case of re-validation after system update, this effectively removes your application from the device. <p>To illustrate how this attribute can affect your application after system updates, consider the following example: </p> - <p>An application declaring <code>android:maxSdkVersion="5"</code> in its + <p>An application declaring <code>maxSdkVersion="5"</code> in its manifest is published on Android Market. A user whose device is running Android 1.6 (API Level 4) downloads and installs the app. After a few weeks, the user receives an over-the-air system update to Android 2.0 (API Level 5). After the update is installed, the system checks the application's - <code>android:maxSdkVersion</code> and successfully revalidates it. The + <code>maxSdkVersion</code> and successfully re-validates it. The application functions as normal. However, some time later, the device receives another system update, this time to Android 2.0.1 (API Level 6). After the - update, the system can no longer revalidate the application because the system's + update, the system can no longer re-validate the application because the system's own API Level (6) is now higher than the maximum supported by the application (5). The system prevents the application from being visible to the user, in effect removing it from the device.</p> @@ -120,7 +134,7 @@ href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a>.</p> provided it uses only standard APIs and follows development best practices. Second, note that in some cases, declaring the attribute can <strong>result in your application being removed from users' devices after a system - update</strong> to a higher API Level. Most devices on which your appplication + update</strong> to a higher API Level. Most devices on which your application is likely to be installed will receive periodic system updates over the air, so you should consider their effect on your application before setting this attribute.</p> @@ -128,8 +142,8 @@ href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a>.</p> <p style="margin-bottom:1em;">Introduced in: API Level 4</p> <div class="special">Future versions of Android (beyond Android 2.0.1) will no -longer check or enforce the <code>android:maxSdkVersion</code> attribute during -installation or revalidation. Android Market will continue to use the attribute +longer check or enforce the <code>maxSdkVersion</code> attribute during +installation or re-validation. Android Market will continue to use the attribute as a filter, however, when presenting users with applications available for download. </div> </dd> diff --git a/docs/html/guide/topics/media/mediaplayer.jd b/docs/html/guide/topics/media/mediaplayer.jd index b3ca7dd..002d113 100644 --- a/docs/html/guide/topics/media/mediaplayer.jd +++ b/docs/html/guide/topics/media/mediaplayer.jd @@ -251,7 +251,7 @@ href="{@docRoot}guide/topics/resources/runtime-changes.html">Handling Runtime Ch "background media" even when the user leaves your activity, much in the same way that the built-in Music application behaves. In this case, what you need is a {@link android.media.MediaPlayer MediaPlayer} controlled by a {@link android.app.Service}, as -discussed in <a href="mpandservices">Using a Service with MediaPlayer</a>.</p> +discussed in <a href="#mpandservices">Using a Service with MediaPlayer</a>.</p> <h2 id="mpandservices">Using a Service with MediaPlayer</h2> diff --git a/docs/html/guide/topics/nfc/nfc.jd b/docs/html/guide/topics/nfc/nfc.jd index 175bc7c..83873c3 100644 --- a/docs/html/guide/topics/nfc/nfc.jd +++ b/docs/html/guide/topics/nfc/nfc.jd @@ -666,7 +666,7 @@ Android Market is launched to download the application.</p> potentially handling specific tags that you have deployed. AARs are only supported at the application level, because of the package name constraint, and not at the Activity level as with intent filtering. If you want to handle an intent at the Activity level, <a -href="filtering-intents">use intent filters</a>. +href="#filtering-intents">use intent filters</a>. </p> @@ -795,8 +795,8 @@ depending on what the user is doing in your application.</p> <p>The following sample shows how a simple activity calls {@link android.nfc.NfcAdapter.CreateNdefMessageCallback} in the <code>onCreate()</code> method of an -activity (see <a href="{@docRoot}resources/samples/AndroidBeam/index.html"></a> for the -complete sample). This example also has methods to help you create a MIME record:</p> +activity (see <a href="{@docRoot}resources/samples/AndroidBeamDemo/index.html">AndroidBeamDemo</a> +for the complete sample). This example also has methods to help you create a MIME record:</p> <pre id="code-example"> package com.example.android.beam; diff --git a/docs/html/guide/topics/renderscript/index.jd b/docs/html/guide/topics/renderscript/index.jd index 148705c..63f341a 100644 --- a/docs/html/guide/topics/renderscript/index.jd +++ b/docs/html/guide/topics/renderscript/index.jd @@ -376,7 +376,7 @@ describes how these classes are generated through reflection.</p> you call the constructor for the {@link android.renderscript.Script.FieldBase} class and specify the amount of structures that you want to allocate memory for. To allocate memory for a primitive type pointer, you must build an allocation manually, using the memory management classes - described in <a href="mem-mgmt-table">Table 1</a>. The example below allocates memory for both + described in <a href="#mem-mgmt-table">Table 1</a>. The example below allocates memory for both the <code>intPointer</code> and <code>touchPoints</code> pointer and binds it to the RenderScript:</p> <pre> diff --git a/docs/html/guide/topics/resources/animation-resource.jd b/docs/html/guide/topics/resources/animation-resource.jd index eaa698f..6473155 100644 --- a/docs/html/guide/topics/resources/animation-resource.jd +++ b/docs/html/guide/topics/resources/animation-resource.jd @@ -335,7 +335,7 @@ set.start(); <dd> <ul> <li><a href="{@docRoot}guide/topics/graphics/animation.html">Property Animation</a></li> - <li><a href="http://zoso:8080/resources/samples/ApiDemos/src/com/example/android/apis/animation/index.html">API Demos</a> for examples + <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/animation/index.html">API Demos</a> for examples on how to use the property animation system.</li> </ul> </dd> diff --git a/docs/html/guide/topics/resources/providing-resources.jd b/docs/html/guide/topics/resources/providing-resources.jd index 3a176e6..380791a 100644 --- a/docs/html/guide/topics/resources/providing-resources.jd +++ b/docs/html/guide/topics/resources/providing-resources.jd @@ -231,6 +231,9 @@ for which these resources are to be used (defined in table 2).</li> </ul> <p>You can append more than one <em>{@code <qualifier>}</em>. Separate each one with a dash.</p> + <p class="caution"><strong>Caution:</strong> When appending multiple qualifiers, you must +place them in the same order in which they are listed in table 2. If the qualifiers are ordered +wrong, the resources are ignored.</p> </li> <li>Save the respective alternative resources in this new directory. The resource files must be named exactly the same as the default resource files.</li> @@ -254,20 +257,14 @@ screen density, but the filenames are exactly the same. This way, the resource ID that you use to reference the {@code icon.png} or {@code background.png} image is always the same, but Android selects the version of each resource that best matches the current device, by comparing the device -configuration information with the qualifiers in the alternative resource directory name.</p> +configuration information with the qualifiers in the resource directory name.</p> <p>Android supports several configuration qualifiers and you can add multiple qualifiers to one directory name, by separating each qualifier with a dash. Table 2 lists the valid configuration qualifiers, in order of precedence—if you use multiple -qualifiers for one resource directory, they must be added to the directory name in the order they +qualifiers for a resource directory, you must add them to the directory name in the order they are listed in the table.</p> -<p class="note"><strong>Note:</strong> Some configuration qualifiers were added after Android 1.0, -so not -all versions of Android support all the qualifiers listed in table 2. New qualifiers -indicate the version in which they were added. To avoid any issues, always include a set of default -resources for resources that your application uses. For more information, see the section about <a -href="#Compatibility">Providing the Best Device Compatibility with Resources</a>.</p> <p class="table-caption" id="table2"><strong>Table 2.</strong> Configuration qualifier names.</p> @@ -752,6 +749,17 @@ href="#KnownIssues">Known Issues</a> for more information.</p> </table> +<p class="note"><strong>Note:</strong> Some configuration qualifiers have been added since Android +1.0, so not all versions of Android support all the qualifiers. Using a new qualifier implicitly +adds the platform version qualifier so that older devices are sure to ignore it. For example, using +a <code>w600dp</code> qualifier will automatically include the <code>v13</code> qualifier, because +the available-width qualifier was new in API level 13. To avoid any issues, always include a set of +default resources (a set of resources with <em>no qualifiers</em>). For more information, see the +section about <a href="#Compatibility">Providing the Best Device Compatibility with +Resources</a>.</p> + + + <h3 id="QualifierRules">Qualifier name rules</h3> <p>Here are some rules about using configuration qualifier names:</p> diff --git a/docs/html/guide/topics/sensors/sensors_motion.jd b/docs/html/guide/topics/sensors/sensors_motion.jd index 3f712b2..b6c3cb4 100644 --- a/docs/html/guide/topics/sensors/sensors_motion.jd +++ b/docs/html/guide/topics/sensors/sensors_motion.jd @@ -28,7 +28,7 @@ parent.link=index.html href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/os/RotationVectorDemo.html"> API Demos (OS - RotationVectorDemo)</a></li> <li><a -href="{@docRoot}/resources/samples/ApiDemos/src/com/example/android/apis/os/RotationVectorDemo.html" +href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/os/RotationVectorDemo.html" >API Demos (OS - Sensors)</a></li> </ol> <h2>See also</h2> diff --git a/docs/html/guide/topics/testing/testing_android.jd b/docs/html/guide/topics/testing/testing_android.jd index c8a3f6e..adbc59d 100755 --- a/docs/html/guide/topics/testing/testing_android.jd +++ b/docs/html/guide/topics/testing/testing_android.jd @@ -318,7 +318,7 @@ parent.link=index.html A useful general test case class, especially if you are just starting out with Android testing, is {@link android.test.AndroidTestCase}. It extends both {@link junit.framework.TestCase} and {@link junit.framework.Assert}. It provides the - JUnit-standard <code>setUp()</code> and <code>tearDown()</code> methods, as well as well as + JUnit-standard <code>setUp()</code> and <code>tearDown()</code> methods, as well as all of JUnit's Assert methods. In addition, it provides methods for testing permissions, and a method that guards against memory leaks by clearing out certain class references. </p> @@ -401,7 +401,7 @@ parent.link=index.html Mock objects isolate tests from a running system by stubbing out or overriding normal operations. For example, a {@link android.test.mock.MockContentResolver} replaces the normal resolver framework with its own local framework, which is isolated - from the rest of the system. MockContentResolver also also stubs out the + from the rest of the system. MockContentResolver also stubs out the {@link android.content.ContentResolver#notifyChange(Uri, ContentObserver, boolean)} method so that observer objects outside the test environment are not accidentally triggered. </p> diff --git a/docs/html/guide/topics/ui/actionbar.jd b/docs/html/guide/topics/ui/actionbar.jd index 3c0ef26..b83bde7 100644 --- a/docs/html/guide/topics/ui/actionbar.jd +++ b/docs/html/guide/topics/ui/actionbar.jd @@ -73,8 +73,10 @@ href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/inde API Demos</a></li> </ol> - <h2>See also</h2>item + <h2>See also</h2> <ol> + <li><a +href="{@docRoot}design/patterns/actionbar.html">Android Design: Action Bar</a></li> <li><a href="{@docRoot}guide/topics/ui/menus.html">Menus</a></li> <li><a href="{@docRoot}guide/practices/tablets-and-handsets.html">Supporting Tablets and Handsets</a></li> @@ -124,6 +126,14 @@ landscape handset), showing the logo on the left, navigation tabs, and an action right (plus the overflow menu button).</p> +<div class="design-announce"> +<p><strong>Action Bar Design</strong></p> + <p>For design guidelines, read Android Design's <a +href="{@docRoot}design/patterns/actionbar.html">Action Bar</a> guide.</p> +</div> + + + <div class="sidebox-wrapper"> <div class="sidebox"> <h2>Remaining backward-compatible</h2> @@ -536,6 +546,12 @@ the email application, but presses the action bar icon to navigate up, rather th <p class="img-caption"><strong>Figure 6.</strong> Example behavior for UP navigation after entering the Email app from the People app.</p> +<div class="design-announce"> +<p><strong>Navigation Design</strong></p> + <p>For more about how <em>Up</em> and <em>Back</em> navigation differ, read Android Design's <a +href="{@docRoot}design/patterns/navigation.html">Navigation</a> guide.</p> +</div> + <p>To enable the icon for up navigation (which displays the "up" indicator next to the icon), call {@link android.app.ActionBar#setDisplayHomeAsUpEnabled setDisplayHomeAsUpEnabled(true)} on your {@link android.app.ActionBar}:</p> @@ -642,7 +658,7 @@ work as designed otherwise.</p> <p>Adding this value requires that you set your build target to Android 4.0 or higher in order to compile. Older versions of Android ignore the {@code "collapseActionView"} value because they don't understand it. Just be sure not to use other APIs in your source code that are not supported in the -version declared by your <a href="{@docRoot}guide/topics/manifest/uses-sdk-elementl.html#min">{@code +version declared by your <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a>, unless you add the appropriate version check at runtime.</p> </div> </div> @@ -843,8 +859,8 @@ you <em>do not</em> need to handle click events from the {@link android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} callback method.</p> <p>For a sample using the share action provider, see -<a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/ActionBarActionProviderActivity.html" ->ActionBarActionProviderActivity</a>. +<a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/ActionBarShareActionProviderActivity.html" +>ActionBarShareActionProviderActivity</a>. diff --git a/docs/html/guide/topics/ui/dialogs.jd b/docs/html/guide/topics/ui/dialogs.jd index 16f14cb..82cbfd1 100644 --- a/docs/html/guide/topics/ui/dialogs.jd +++ b/docs/html/guide/topics/ui/dialogs.jd @@ -37,6 +37,11 @@ DatePicker</a></li> <li><a href="{@docRoot}resources/tutorials/views/hello-timepicker.html">Hello TimePicker</a></li> </ol> + + <h2>See also</h2> + <ol> + <li><a href="{@docRoot}design/building-blocks/dialogs.html">Android Design: Dialogs</a></li> + </ol> </div> </div> @@ -70,6 +75,13 @@ of the following subclasses:</p> base {@link android.app.Dialog} object or any of the subclasses listed above and define a new layout. See the section on <a href="#CustomDialog">Creating a Custom Dialog</a> below.</p> +<div class="design-announce"> +<p><strong>Dialog Design</strong></p> + <p>For design guidelines, read Android Design's <a +href="{@docRoot}design/building-blocks/dialogs.html">Dialogs</a> guide.</p> +</div> + + <h2 id="ShowingADialog">Showing a Dialog</h2> diff --git a/docs/html/guide/topics/ui/notifiers/notifications.jd b/docs/html/guide/topics/ui/notifiers/notifications.jd index 7bc1cde..33b0fec 100644 --- a/docs/html/guide/topics/ui/notifiers/notifications.jd +++ b/docs/html/guide/topics/ui/notifiers/notifications.jd @@ -16,6 +16,7 @@ user clicks it</li> <h2>In this document</h2> <ol> <li><a href="#Basics">The Basics</a></li> + <li><a href="#HandlingNotifications">Responding to Notifications</a></li> <li><a href="#ManageYourNotifications">Managing your Notifications</a></li> <li><a href="#CreateANotification">Creating a Notification</a> <ol> @@ -33,6 +34,12 @@ user clicks it</li> <li>{@link android.app.Notification}</li> <li>{@link android.app.NotificationManager}</li> </ol> + + <h2>See also</h2> + <ol> + <li><a href="{@docRoot}design/patterns/notifications.html">Android +Design: Notifications</a></li> + </ol> </div> </div> @@ -61,6 +68,14 @@ when selected by the user.</p> <p class="img-caption"><strong>Figure 2.</strong> The notifications window.</p> +<div class="design-announce"> +<p><strong>Notification Design</strong></p> + <p>For design guidelines, read Android Design's <a +href="{@docRoot}design/patterns/notifications.html">Notifications</a> guide.</p> +</div> + + + <h2 id="Basics">The Basics</h2> <p>An {@link android.app.Activity} or {@link android.app.Service} can initiate a status bar @@ -123,6 +138,138 @@ mNotificationManager.notify(HELLO_ID, notification); </ol> +<h2 id="HandlingNotifications">Responding to Notifications</h2> + +<p>A central part of the user's experience with a notification revolves around +how it interacts with the application's UI flow. You must implement +this correctly to provide a consistent user experience within your app.</p> + +<p>Two typical examples of notifications are provided by Calendar, which can send out +notifications of upcoming events, and Email, which can send out notifications +when new messages arrive. These represent the two recommended patterns for handling +notifications: either launching into an activity that is separate from the +main application, or launching an entirely new instance of the application +showing the appropriate point for the notification.</p> + +<p>The following scenario shows how the activity stack should work +in these two typical notification flows, first handling a Calendar notification: +</p> + +<ol> + <li>User is creating a new event in Calendar. They realize they + need to copy part of an email message into this event. + </li> + <li> + The user chooses Home > Email. + </li> + <li> + While in Email, they receive a notification from Calendar for an upcoming + meeting. + </li> + <li> + So they choose that notification, which takes them to a + dedicated Calendar activity that displays brief details of the + upcoming meeting. + </li> + <li> + The user has seen enough to know they have a meeting coming up, + so they press the BACK button. They are now returned to Email, which + is where they were when they took the notification. + </li> +</ol> + +<p>Handling an Email notification:</p> + +<ol> + <li> + The user is currently in Email composing a message, and needs to + check a date in their calendar. + </li> + <li> + The user chooses Home > Calendar. + </li> + <li> + While in Calendar, they receive a notification from Email about a new + message. + </li> + <li> + They select the notification, which brings them to Email with the message + details displayed. This has replaced what they were previously doing + (writing an e-mail), but that message is still saved in their drafts. + </li> + <li> + The user presses BACK once to go to the message list (the typical flow in the + Email app), and press BACK again to return to Calendar as they left it. + </li> +</ol> + +<p>In an Email style of notification, the UI launched by the notification +shows the main application in a state representing that notification. +For example, when the Email application comes to the foreground from its +notification, it displays either the conversion list or a specific +conversation depending on whether there are multiple or only one new +email. To achieve this, we want to completely replace whatever current +state the application is in with a new activity stack representing the +new notification state.</p> + +<p>The following code illustrates how to show this kind of notification. Of +most interest is the <code>makeMessageIntentStack()</code> method, which constructs +an array of intents representing the app's new activity stack for this state. +(If you are using fragments, you may need to initialize your fragment and +app state so that pressing BACK will switch the UI back to its parent state.) +The core of this is the {@link android.content.Intent#makeRestartActivityTask +Intent.makeRestartActivityTask()} method, which constructs the root activity +of the stack with the appropriate flags, such as +{@link android.content.Intent#FLAG_ACTIVITY_CLEAR_TASK Intent.FLAG_ACTIVITY_CLEAR_TASK}.</p> + +{@sample development/samples/ApiDemos/src/com/example/android/apis/app/IncomingMessage.java + app_notification} + +<p>In a Calendar style of notification, the UI launched by the notification +is a dedicated activity that is not part of the normal application flow. +For example, when the user receives a Calendar notification, choosing that +notification starts a special activity that displays a list +of upcoming calendar events — this view is available only +from the notification, not through the Calendar's normal user +interface.</p> + +<p>The code for posting this type of notification is very straight-forward; it +is like the above, but the {@link android.app.PendingIntent} is for just a single +activity, our dedicated notification activity.</p> + +{@sample development/samples/ApiDemos/src/com/example/android/apis/app/IncomingMessage.java + interstitial_notification} + +<p>This is not enough, however. Normally Android considers all activities within +an application to be part of that application's UI flow, so simply launching the +activity like this can cause it to be mixed with your normal application back stack +in undesired ways. To make it behave correctly, in the manifest declaration +for the activity the attributes +<code>android:launchMode="singleInstance"</code> and +<code>android:excludeFromRecents="true"</code> +must be set. The full activity declaration for this sample is:</p> + +{@sample development/samples/ApiDemos/AndroidManifest.xml interstitial_affinity} + +<p>Because of the use of <code>singleInstance</code>, you must be careful about launching +any other activities from this one. These activities will be launched +in their own task, and care must be taken to make sure this interacts +well with the current state of your application's task. This is essentially +the same as switching to the main application as described for the Email style +notification shown before. Given the <code>makeMessageIntentStack()</code> +method previously shown, handling a click here would look something like this:</p> + +{@sample development/samples/ApiDemos/src/com/example/android/apis/app/IncomingMessageInterstitial.java + app_launch} + +<p>If you don't want to use the <code>singleInstance</code> launch mode for +this activity, an alternative approach is to use <code>android:taskAffinity=""</code>. +This tells Android that the activity should not be treated as part of the +main application flow, so it will not get mixed together with that. All of the +other issues discussed here do still apply, though this would allow you to start +additional activities that are part of this notification task instead of switching +to and replacing the main application task.</p> + <h2 id="ManageYourNotifications">Managing your Notifications</h2> <p>The {@link android.app.NotificationManager} is a system service that manages all diff --git a/docs/html/guide/topics/usb/accessory.jd b/docs/html/guide/topics/usb/accessory.jd index b0f4881..8b74bc0 100644 --- a/docs/html/guide/topics/usb/accessory.jd +++ b/docs/html/guide/topics/usb/accessory.jd @@ -169,8 +169,9 @@ UsbAccessory accessory = (UsbAccessory) intent.getParcelableExtra(UsbManager.EXT include a <code><uses-feature></code> element that declares that your application uses the <code>android.hardware.usb.accessory</code> feature.</li> - <li>If you are using the <a href="addon">add-on library</a>, add the - <code><uses-library></code> element specifying + <li>If you are using the + <a href="http://code.google.com/android/add-ons/google-apis/index.html">add-on library</a>, + add the <code><uses-library></code> element specifying <code>com.android.future.usb.accessory</code> for the library.</li> <li>Set the minimum SDK of the application to API Level 10 if you are using the add-on library diff --git a/docs/html/guide/topics/usb/adk.jd b/docs/html/guide/topics/usb/adk.jd index 6c7ab0d..4d5fbfa 100644 --- a/docs/html/guide/topics/usb/adk.jd +++ b/docs/html/guide/topics/usb/adk.jd @@ -281,16 +281,17 @@ page.title=Android Open Accessory Development Kit <p>On Mac:</p> <ol type="a"> - <li>Right-click on the Arduino application in Finder and select <strong>Show Package - Contents</strong>.</li> + <li>Create, if it does not already exist, an <code>Arduino</code> + directory inside your user account's <code>Documents</code> directory, and within + that, a <code>libraries</code> directory.</li> <li>Copy the <code>firmware/arduino_libs/AndroidAccessory</code> and - <code>firmware/arduino_libs/USB_Host_Shield</code> directories (the complete directories, - not just the files within) to the <code>Contents/Resources/Java/libraries</code> directory - inside the Arduino application.</li> + <code>firmware/arduino_libs/USB_Host_Shield</code> directories (the + complete directories, not just the files within) to your + <code>Documents/Arduino/libraries/</code> directory.</li> - <li>Create a <code>CapSense</code> directory in the - <code>Contents/Resources/Java/libraries</code> directory.</li> + <li>Create a <code>CapSense</code> directory in your + <code>Documents/Arduino/libraries/</code> directory.</li> <li>Copy <code>CapSense.cpp</code> and <code>CapSense.h</code> from the unzipped CapSense download to the <code>CapSense</code> directory.</li> @@ -699,7 +700,7 @@ bool AndroidAccessory::switchDevice(byte addr) </pre>If this method returns false, the board waits until a new device is connected. If it is successful, the device displays itself on the USB bus as being in accessory mode when the ADK board re-enumerates the bus. When the device is in accessory mode, the accessory then <a href= -"establish-adk">establishes communication with the device</a>. +"#establish-adk">establishes communication with the device</a>. <h3 id="establish-adk">Establish communication with the device</h3> diff --git a/docs/html/guide/topics/wireless/bluetooth.jd b/docs/html/guide/topics/wireless/bluetooth.jd index 0af1d2c..76da08e 100644 --- a/docs/html/guide/topics/wireless/bluetooth.jd +++ b/docs/html/guide/topics/wireless/bluetooth.jd @@ -29,6 +29,7 @@ other devices</li> <li><a href="#Profiles">Working with Profiles</a> <ol> <li><a href="#AT-Commands">Vendor-specific AT commands</a> + <li><a href="#HDP">Health Device Profile</a> </ol></li> </ol> @@ -43,6 +44,7 @@ other devices</li> <h2>Related samples</h2> <ol> <li><a href="{@docRoot}resources/samples/BluetoothChat/index.html">Bluetooth Chat</a></li> + <li><a href="{@docRoot}resources/samples/BluetoothHDP/index.html">Bluetooth HDP (Health Device Profile)</a></li> </ol> </div> @@ -132,11 +134,27 @@ Headset and Hands-Free (v1.5) profiles.</dd> audio can be streamed from one device to another over a Bluetooth connection. "A2DP" stands for Advanced Audio Distribution Profile.</dd> -<dt>{@link android.bluetooth.BluetoothProfile.ServiceListener}</dt> +<dt>{@link android.bluetooth.BluetoothHealth}</dt> +<dd> Represents a Health Device Profile proxy that controls the Bluetooth service.</dd> + +<dt>{@link android.bluetooth.BluetoothHealthCallback}</dt> + +<dd>An abstract class that you use to implement {@link +android.bluetooth.BluetoothHealth} callbacks. You must extend this class and +implement the callback methods to receive updates about changes in the +application’s registration state and Bluetooth channel state.</dd> + +<dt>{@link android.bluetooth.BluetoothHealthAppConfiguration}</dt> + +<dd>Represents an application configuration that the Bluetooth Health third-party +application registers to communicate with a remote Bluetooth health +device.</dd> + +<dt>{@link android.bluetooth.BluetoothProfile.ServiceListener}</dt> <dd>An interface that notifies {@link android.bluetooth.BluetoothProfile} IPC clients when they have been connected to or disconnected from the service (that -is, the internal service that runs a particular profile). </dd> +is, the internal service that runs a particular profile). </dd> </dl> @@ -889,7 +907,7 @@ Bluetooth Headset Service via interprocess communication (<a href="{@docRoot}guide/topics/fundamentals/processes-and-threads.html#IPC">IPC</a >). This includes both Bluetooth Headset and Hands-Free (v1.5) profiles. The {@link android.bluetooth.BluetoothHeadset} class includes support for AT commands. -For more discussion of this topic, see <a href="#AT-Commands">Vendor-specific AT commands</a></li> +For more discussion of this topic, see <a href="#AT-Commands">Vendor-specific AT commands</a></li> <li><strong>A2DP</strong>. The Advanced Audio Distribution Profile (A2DP) profile defines how high quality audio can be streamed from one device to @@ -897,13 +915,25 @@ another over a Bluetooth connection. Android provides the {@link android.bluetooth.BluetoothA2dp} class, which is a proxy for controlling the Bluetooth A2DP Service via IPC.</li> + <li><strong>Health Device</strong>. Android 4.0 (API level 14) introduces +support for the Bluetooth Health Device Profile (HDP). This lets you create +applications that use Bluetooth to communicate with health devices that support +Bluetooth, such as heart-rate monitors, blood meters, thermometers, scales, and +so on. For a list of supported devices and their corresponding device data +specialization codes, refer to <strong>Bluetooth Assigned Numbers</strong> at <a +href="http://www.bluetooth.org">www.bluetooth.org</a>. Note that these values +are also referenced in the ISO/IEEE 11073-20601 [7] specification as +MDC_DEV_SPEC_PROFILE_* in the Nomenclature Codes Annex. For more discussion of +HDP, see <a href="#HDP">Health Device Profile</a>.</li> + </ul> <p>Here are the basic steps for working with a profile:</p> <ol> - <li>Get the default adapter, as described in <a href="{@docRoot}guide/topics/wireless/bluetooth. -html#SettingUp">Setting Up Bluetooth</a>.</li> + <li>Get the default adapter, as described in + <a href="{@docRoot}guide/topics/wireless/bluetooth.html#SettingUp">Setting Up + Bluetooth</a>.</li> <li>Use {@link android.bluetooth.BluetoothAdapter#getProfileProxy(android.content.Context, @@ -925,7 +955,9 @@ to the profile proxy object.</li> state of the connection and perform other operations that are relevant to that profile.</li> </ol> -<p> For example, this code snippet shows how to connect to a {@link android.bluetooth.BluetoothHeadset} proxy object so that you can control the + +<p> For example, this code snippet shows how to connect to a {@link +android.bluetooth.BluetoothHeadset} proxy object so that you can control the Headset profile:</p> <pre>BluetoothHeadset mBluetoothHeadset; @@ -955,6 +987,8 @@ private BluetoothProfile.ServiceListener mProfileListener = new BluetoothProfile mBluetoothAdapter.closeProfileProxy(mBluetoothHeadset); </pre> + + <h3 id="AT-Commands">Vendor-specific AT commands</h3> <p>Starting in Android 3.0, applications can register to receive system @@ -964,3 +998,81 @@ broadcasts that indicate a connected device's battery level and could notify the user or take other action as needed. Create a broadcast receiver for the {@link android.bluetooth.BluetoothHeadset#ACTION_VENDOR_SPECIFIC_HEADSET_EVENT} intent to handle vendor-specific AT commands for the headset.</p> + +<h3 id="HDP">Health Device Profile</h3> + +<p>Android 4.0 (API level 14) introduces support for the Bluetooth Health Device +Profile (HDP). This lets you create applications that use Bluetooth to +communicate with health devices that support Bluetooth, such as heart-rate +monitors, blood meters, thermometers, and scales. The Bluetooth Health API +includes the classes {@link android.bluetooth.BluetoothHealth}, {@link +android.bluetooth.BluetoothHealthCallback}, and {@link +android.bluetooth.BluetoothHealthAppConfiguration}, which are described in <a +href="#TheBasics">The Basics</a>. </p> + +<p>In using the Bluetooth Health API, it's helpful to understand these key HDP concepts:</p> +<table> + <tr> + <th>Concept</th> + <th>Description</th> + </tr> + <tr> + <td><strong>Source</strong></td> + + <td>A role defined in HDP. A <em>source</em> is a health device that +transmits medical data (weight scale, glucose meter, thermometer, etc.) to a +smart device such as an Android phone or tablet. </td> + </tr> + <tr> + <td><strong>Sink</strong></td> + + <td>A role defined in HDP. In HDP, a <em>sink</em> is the smart device that +receives the medical data. In an Android HDP application, the sink is +represented by a {@link android.bluetooth.BluetoothHealthAppConfiguration} +object.</td> + </tr> + <tr> + <td><strong>Registration</strong></td> + <td>Refers to registering a sink for a particular health device.</td> + </tr> + <tr> + <td><strong>Connection</strong></td> + + <td>Refers to opening a channel between a health device and a smart device +such as an Android phone or tablet.</td> + </tr> +</table> + +<h4>Creating an HDP Application</h4> + +<p>Here are the basic steps involved in creating an Android HDP application:</p> +<ol> + + <li>Get a reference to the {@link android.bluetooth.BluetoothHealth} proxy +object. <p>Similar to regular headset and A2DP profile devices, you must call +{@link android.bluetooth.BluetoothAdapter#getProfileProxy getProfileProxy()} +with a {@link android.bluetooth.BluetoothProfile.ServiceListener} and the {@link +android.bluetooth.BluetoothProfile.ServiceListener#HEALTH} profile type to +establish a connection with the profile proxy object.</p> </li> + + <li>Create a {@link android.bluetooth.BluetoothHealthCallback} and register an +application configuration +({@link android.bluetooth.BluetoothHealthAppConfiguration}) +that acts as a health +sink.</li> + + <li>Establish a connection to a health device. Some devices will initiate the +connection. It is unnecessary to carry out this step for those devices.</li> + + <li>When connected successfully to a health device, read/write to the health +device using the file descriptor. <p>The received data needs to be interpreted +using a health manager which implements the IEEE 11073-xxxxx +specifications.</p></li> + + <li>When done, close the health channel and unregister the application. The +channel also closes when there is extended inactivity.</li> +</ol> + +<p>For a complete code sample that illustrates these steps, see <a +href="{@docRoot}resources/samples/BluetoothHDP/index.html">Bluetooth HDP (Health +Device Profile)</a>. </p> |