diff options
Diffstat (limited to 'docs/html/guide')
100 files changed, 1677 insertions, 1677 deletions
diff --git a/docs/html/guide/appendix/app-intents.jd b/docs/html/guide/appendix/app-intents.jd index 8898927f240f..5fb004fff856 100644 --- a/docs/html/guide/appendix/app-intents.jd +++ b/docs/html/guide/appendix/app-intents.jd @@ -89,13 +89,13 @@ excludeFromSuggestions=true <tr><td>pitch</td><td>Panorama center-of-view in degrees from -90 (look straight up) to 90 (look straight down.)</td></tr> <tr><td>zoom</td><td>Panorama zoom. 1.0 = normal zoom, 2.0 = zoomed in 2x, 3.0 = zoomed in 4x, and so on.<br /> - A zoom of 1.0 is 90 degree horizontal FOV for a nominal - landscape mode 4 x 3 aspect ratio display. - Android phones in portrait mode will adjust the zoom so that - the vertical FOV is approximately the same as the landscape vertical - FOV. This means that the horizontal FOV of an Android phone in portrait - mode is much narrower than in landscape mode. This is done to minimize - the fisheye lens effect that would be present if a 90 degree horizontal + A zoom of 1.0 is 90 degree horizontal FOV for a nominal + landscape mode 4 x 3 aspect ratio display. + Android phones in portrait mode will adjust the zoom so that + the vertical FOV is approximately the same as the landscape vertical + FOV. This means that the horizontal FOV of an Android phone in portrait + mode is much narrower than in landscape mode. This is done to minimize + the fisheye lens effect that would be present if a 90 degree horizontal FOV was used in portrait mode.</td></tr> <tr><td>mapZoom</td><td>The map zoom of the map location associated with this panorama. This value is passed on to the Maps activity when the Street View "Go to Maps" menu item is chosen. It corresponds to the <em>z</em> parameter in diff --git a/docs/html/guide/appendix/g-app-intents.jd b/docs/html/guide/appendix/g-app-intents.jd index 9ec72db2411f..21c927b913b7 100644 --- a/docs/html/guide/appendix/g-app-intents.jd +++ b/docs/html/guide/appendix/g-app-intents.jd @@ -83,7 +83,7 @@ href="{@docRoot}guide/components/intents-filters.html">Intents and Intent Filter </td> </tr> <tr> - <td>Google Streetview</td> + <td>Google Streetview</td> <td>google.streetview:cbll=<em>lat</em>,<em>lng</em>&cbp=1,<em>yaw</em>,,<em>pitch</em>,<em>zoom</em>&mz=<em>mapZoom</em> </td> <td>VIEW</td> diff --git a/docs/html/guide/appendix/glossary.jd b/docs/html/guide/appendix/glossary.jd index a200a6c0ff0e..75a533ad9084 100755 --- a/docs/html/guide/appendix/glossary.jd +++ b/docs/html/guide/appendix/glossary.jd @@ -15,7 +15,7 @@ excludeFromSuggestions=true </dd> <dt id="dex">.dex file </dt> - <dd>Compiled Android application code file. + <dd>Compiled Android application code file. <p>Android programs are compiled into .dex (Dalvik Executable) files, which are in turn zipped into a single .apk file on the device. .dex files can be created by automatically translating compiled applications written in @@ -26,7 +26,7 @@ excludeFromSuggestions=true a string value assigned to an Intent. Action strings can be defined by Android or by a third-party developer. For example, android.intent.action.VIEW for a Web URL, or com.example.rumbler.SHAKE_PHONE for a custom application - to vibrate the phone. + to vibrate the phone. <p>Related: <a href="#intent">Intent</a>.</p> </dd> @@ -41,8 +41,8 @@ excludeFromSuggestions=true <dt id="adb">adb</dt> <dd>Android Debug Bridge, a command-line debugging application included with the SDK. It provides tools to browse the device, copy tools on the device, and - forward ports for debugging. If you are developing in Android Studio, - adb is integrated into your development environment. See + forward ports for debugging. If you are developing in Android Studio, + adb is integrated into your development environment. See <a href="{@docRoot}tools/help/adb.html">Android Debug Bridge</a> for more information. </dd> @@ -90,7 +90,7 @@ excludeFromSuggestions=true <dt id="ddms">DDMS</dt> <dd>Dalvik Debug Monitor Service, a GUI debugging application included with the SDK. It provides screen capture, log dump, and process - examination capabilities. If you are developing in Android Studio, + examination capabilities. If you are developing in Android Studio, DDMS is integrated into your development environment. See <a href="{@docRoot}tools/debugging/ddms.html">Using DDMS</a> to learn more about the program.</dd> @@ -100,7 +100,7 @@ excludeFromSuggestions=true is not intended to persist in the history stack, contain complex layout, or perform complex actions. Android provides a default simple dialog for you with optional buttons, though you can define your own dialog layout. - The base class for dialogs is {@link android.app.Dialog Dialog}. + The base class for dialogs is {@link android.app.Dialog Dialog}. <p>Related: <a href="#activity">Activity</a>.</p></dd> <dt id="drawable">Drawable</dt> @@ -113,7 +113,7 @@ excludeFromSuggestions=true — xml or bitmap files that describe the image. Drawable resources are compiled into subclasses of {@link android.graphics.drawable}. For more information about drawables and other resources, see <a - href="{@docRoot}guide/topics/resources/resources-i18n.html">Resources</a>. + href="{@docRoot}guide/topics/resources/resources-i18n.html">Resources</a>. <p>Related: <a href="#resources">Resources</a>, <a href="#canvas">Canvas </a></p></dd> @@ -133,7 +133,7 @@ excludeFromSuggestions=true based on the criteria supplied in the Intent and the Intent Filters defined by other applications. For more information, see <a href="{@docRoot}guide/components/intents-filters.html">Intents and - Intent Filters</a>. + Intent Filters</a>. <p>Related: <a href="#intentfilter">Intent Filter</a>, <a href="#broadcastreceiver">Broadcast Receiver</a>.</p></dd> @@ -147,7 +147,7 @@ excludeFromSuggestions=true application/activity that best matches the Intent and criteria. For more information, see <a href="{@docRoot}guide/components/intents-filters.html">Intents and - Intent Filters</a>. + Intent Filters</a>. <p>Related: <a href="#intent">Intent</a>, <a href="#broadcastreceiver">Broadcast Receiver</a>.</p></dd> @@ -155,12 +155,12 @@ excludeFromSuggestions=true <dd>An application class that listens for Intents that are broadcast, rather than being sent to a single target application/activity. The system delivers a broadcast Intent to all interested broadcast receivers, which - handle the Intent sequentially. - <p>Related: <a href="#intent">Intent</a>, <a href="#intentfilter">Intent + handle the Intent sequentially. + <p>Related: <a href="#intent">Intent</a>, <a href="#intentfilter">Intent Filter</a>.</p> </dd> - + <dt id="layoutresource">Layout Resource</dt> - <dd>An XML file that describes the layout of an Activity screen. + <dd>An XML file that describes the layout of an Activity screen. <p>Related: <a href="#resources">Resources</a></p></dd> <dt id="manifest">Manifest File</dt> @@ -175,15 +175,15 @@ excludeFromSuggestions=true <dd>A resizeable bitmap resource that can be used for backgrounds or other images on the device. See <a href="{@docRoot}guide/topics/resources/available-resources.html#ninepatch"> - Nine-Patch Stretchable Image</a> for more information. + Nine-Patch Stretchable Image</a> for more information. <p>Related: <a href="#resources">Resources</a>.</p></dd> <dt id="opengles">OpenGL ES</dt> <dd> Android provides OpenGL ES libraries that you can use for fast, complex 3D images. It is harder to use than a Canvas object, but - better for 3D objects. The {@link android.opengl} and - {@link javax.microedition.khronos.opengles} packages expose - OpenGL ES functionality. + better for 3D objects. The {@link android.opengl} and + {@link javax.microedition.khronos.opengles} packages expose + OpenGL ES functionality. <p>Related: <a href="#canvas">Canvas</a>, <a href="#surface">Surface</a></p></dd> <dt id="resources">Resources</dt> @@ -205,15 +205,15 @@ excludeFromSuggestions=true <dt id="service">Service</dt> <dd>An object of class {@link android.app.Service} that runs in the background (without any UI presence) to perform various persistent - actions, such as playing music or monitoring network activity. + actions, such as playing music or monitoring network activity. <p>Related: <a href="#activity">Activity</a></p></dd> <dt id="surface">Surface</dt> <dd>An object of type {@link android.view.Surface} representing a block of memory that gets composited to the screen. A Surface holds a Canvas object for drawing, and provides various helper methods to draw layers and resize - the surface. You should not use this class directly; use - {@link android.view.SurfaceView} instead. + the surface. You should not use this class directly; use + {@link android.view.SurfaceView} instead. <p>Related: <a href="#canvas">Canvas</a></p></dd> <dt id="surfaceview">SurfaceView</dt> @@ -249,7 +249,7 @@ excludeFromSuggestions=true windows, and so on). It receives calls from its parent object (see viewgroup, below)to draw itself, and informs its parent object about where and how big it would like to be (which may or may not be respected by the - parent). For more information, see {@link android.view.View}. + parent). For more information, see {@link android.view.View}. <p>Related: <a href="#viewgroup">Viewgroup</a>, <a href="#widget">Widget </a></p></dd> @@ -259,18 +259,18 @@ excludeFromSuggestions=true they can be, as well as for calling each to draw itself when appropriate. Some viewgroups are invisible and are for layout only, while others have an intrinsic UI (for instance, a scrolling list box). Viewgroups are all - in the {@link android.widget widget} package, but extend - {@link android.view.ViewGroup ViewGroup}. + in the {@link android.widget widget} package, but extend + {@link android.view.ViewGroup ViewGroup}. <p>Related: <a href="#view">View</a></p></dd> <dt id="widget">Widget</dt> <dd>One of a set of fully implemented View subclasses that render form elements and other UI components, such as a text box or popup menu. Because a widget is fully implemented, it handles measuring and drawing - itself and responding to screen events. Widgets are all in the + itself and responding to screen events. Widgets are all in the {@link android.widget} package. </dd> - <!-- + <!-- <dt id="panel">Panel</dt> <dd> A panel is a concept not backed by a specific class. It is a View of some sort that is tied in closely to a parent window, but can handle diff --git a/docs/html/guide/components/activities.jd b/docs/html/guide/components/activities.jd index 070154d805e7..e757288424d8 100644 --- a/docs/html/guide/components/activities.jd +++ b/docs/html/guide/components/activities.jd @@ -622,7 +622,7 @@ android.app.Activity#onSaveInstanceState onSaveInstanceState()}.</p> <p>The system calls {@link android.app.Activity#onSaveInstanceState onSaveInstanceState()} before making the activity vulnerable to destruction. The system passes this method -a {@link android.os.Bundle} in which you can save +a {@link android.os.Bundle} in which you can save state information about the activity as name-value pairs, using methods such as {@link android.os.Bundle#putString putString()} and {@link android.os.Bundle#putInt putInt()}. Then, if the system kills your application diff --git a/docs/html/guide/components/fragments.jd b/docs/html/guide/components/fragments.jd index f9c2a26d62e9..951d04211bde 100644 --- a/docs/html/guide/components/fragments.jd +++ b/docs/html/guide/components/fragments.jd @@ -36,7 +36,7 @@ parent.link=activities.html <li>{@link android.app.FragmentManager}</li> <li>{@link android.app.FragmentTransaction}</li> </ol> - + <h2>See also</h2> <ol> <li><a href="{@docRoot}training/basics/fragments/index.html">Building a Dynamic UI with Fragments</a></li> @@ -306,7 +306,7 @@ ID for a fragment:</p> <ul> <li>Supply the {@code android:id} attribute with a unique ID.</li> <li>Supply the {@code android:tag} attribute with a unique string.</li> - <li>If you provide neither of the previous two, the system uses the ID of the container + <li>If you provide neither of the previous two, the system uses the ID of the container view.</li> </ul> </div> @@ -365,7 +365,7 @@ findFragmentByTag()}.</p> <p>For an example activity that uses a fragment as a background worker, without a UI, see the {@code FragmentRetainInstance.java} sample, which is included in the SDK samples (available through the -Android SDK Manager) and located on your system as +Android SDK Manager) and located on your system as <code><sdk_root>/APIDemos/app/src/main/java/com/example/android/apis/app/FragmentRetainInstance.java</code>.</p> @@ -381,7 +381,7 @@ get it, call {@link android.app.Activity#getFragmentManager()} from your activit <li>Get fragments that exist in the activity, with {@link android.app.FragmentManager#findFragmentById findFragmentById()} (for fragments that provide a UI in the activity layout) or {@link android.app.FragmentManager#findFragmentByTag -findFragmentByTag()} (for fragments that do or don't provide a UI).</li> +findFragmentByTag()} (for fragments that do or don't provide a UI).</li> <li>Pop fragments off the back stack, with {@link android.app.FragmentManager#popBackStack()} (simulating a <em>Back</em> command by the user).</li> <li>Register a listener for changes to the back stack, with {@link @@ -568,7 +568,7 @@ public static class FragmentA extends ListFragment { <p>If the activity has not implemented the interface, then the fragment throws a {@link java.lang.ClassCastException}. -On success, the {@code mListener} member holds a reference to activity's implementation of +On success, the {@code mListener} member holds a reference to activity's implementation of {@code OnArticleSelectedListener}, so that fragment A can share events with the activity by calling methods defined by the {@code OnArticleSelectedListener} interface. For example, if fragment A is an extension of {@link android.app.ListFragment}, each time @@ -798,7 +798,7 @@ android.widget.FrameLayout}), or start a new activity (where the fragment can be <p>The second fragment, {@code DetailsFragment} shows the play summary for the item selected from the list from {@code TitlesFragment}:</p> - + {@sample development/samples/ApiDemos/src/com/example/android/apis/app/FragmentLayout.java details} <p>Recall from the {@code TitlesFragment} class, that, if the user clicks a list item and the @@ -811,7 +811,7 @@ the selected play summary when the screen is in portrait orientation:</p> {@sample development/samples/ApiDemos/src/com/example/android/apis/app/FragmentLayout.java details_activity} - + <p>Notice that this activity finishes itself if the configuration is landscape, so that the main activity can take over and display the {@code DetailsFragment} alongside the {@code TitlesFragment}. This can happen if the user begins the {@code DetailsActivity} while in portrait orientation, but diff --git a/docs/html/guide/components/index.jd b/docs/html/guide/components/index.jd index 811d015b82bc..d596b3be3462 100644 --- a/docs/html/guide/components/index.jd +++ b/docs/html/guide/components/index.jd @@ -1,7 +1,7 @@ page.title=App Components page.landing=true -page.landing.intro=Android's application framework lets you create rich and innovative apps using a set of reusable components. This section explains how you can build the components that define the building blocks of your app and how to connect them together using intents. -page.metaDescription=Android's application framework lets you create rich and innovative apps using a set of reusable components. This section explains how you can build the components that define the building blocks of your app and how to connect them together using intents. +page.landing.intro=Android's application framework lets you create rich and innovative apps using a set of reusable components. This section explains how you can build the components that define the building blocks of your app and how to connect them together using intents. +page.metaDescription=Android's application framework lets you create rich and innovative apps using a set of reusable components. This section explains how you can build the components that define the building blocks of your app and how to connect them together using intents. page.landing.image=images/develop/app_components.png page.image=images/develop/app_components.png @@ -11,7 +11,7 @@ page.image=images/develop/app_components.png <div class="col-6"> <h3>Blog Articles</h3> - + <a href="http://android-developers.blogspot.com/2012/05/using-dialogfragments.html"> <h4>Using DialogFragments</h4> <p>In this post, I’ll show how to use DialogFragments with the v4 support library (for backward compatibility on pre-Honeycomb devices) to show a simple edit dialog and return a result to the calling Activity using an interface.</p> @@ -21,7 +21,7 @@ page.image=images/develop/app_components.png <h4>Fragments For All</h4> <p>Today we’ve released a static library that exposes the same Fragments API (as well as the new LoaderManager and a few other classes) so that applications compatible with Android 1.6 or later can use fragments to create tablet-compatible user interfaces. </p> </a> - + <a href="http://android-developers.blogspot.com/2010/07/multithreading-for-performance.html"> <h4>Multithreading for Performance</h4> @@ -33,7 +33,7 @@ handled in a different thread.</p> <div class="col-6"> <h3>Training</h3> - + <a href="http://developer.android.com/training/basics/activity-lifecycle/index.html"> <h4>Managing the Activity Lifecycle</h4> <p>This class explains important lifecycle callback methods that each Activity diff --git a/docs/html/guide/components/loaders.jd b/docs/html/guide/components/loaders.jd index ddd513b2a2c5..7c4baa846ae3 100644 --- a/docs/html/guide/components/loaders.jd +++ b/docs/html/guide/components/loaders.jd @@ -21,14 +21,14 @@ parent.link=activities.html </ol> </li> </ol> - + <h2>Key classes</h2> <ol> <li>{@link android.app.LoaderManager}</li> <li>{@link android.content.Loader}</li> - </ol> - + </ol> + <h2>Related samples</h2> <ol> <li> <a @@ -53,7 +53,7 @@ content changes.</li> recreated after a configuration change. Thus, they don't need to re-query their data.</li> </ul> - + <h2 id="summary">Loader API Summary</h2> <p>There are multiple classes and interfaces that may be involved in using @@ -131,10 +131,10 @@ of {@link android.content.Loader} or {@link android.content.AsyncTaskLoader} to load data from some other source.</li> <li>An implementation for {@link android.app.LoaderManager.LoaderCallbacks}. This is where you create new loaders and manage your references to existing -loaders.</li> +loaders.</li> <li>A way of displaying the loader's data, such as a {@link android.widget.SimpleCursorAdapter}.</li> - <li>A data source, such as a {@link android.content.ContentProvider}, when using a + <li>A data source, such as a {@link android.content.ContentProvider}, when using a {@link android.content.CursorLoader}.</li> </ul> <h3 id="starting">Starting a Loader</h3> @@ -142,7 +142,7 @@ android.widget.SimpleCursorAdapter}.</li> <p>The {@link android.app.LoaderManager} manages one or more {@link android.content.Loader} instances within an {@link android.app.Activity} or {@link android.app.Fragment}. There is only one {@link -android.app.LoaderManager} per activity or fragment.</p> +android.app.LoaderManager} per activity or fragment.</p> <p>You typically initialize a {@link android.content.Loader} within the activity's {@link @@ -159,13 +159,13 @@ the following parameters:</p> <ul> <li>A unique ID that identifies the loader. In this example, the ID is 0.</li> <li>Optional arguments to supply to the loader at -construction (<code>null</code> in this example).</li> +construction (<code>null</code> in this example).</li> <li>A {@link android.app.LoaderManager.LoaderCallbacks} implementation, which the {@link android.app.LoaderManager} calls to report loader events. In this example, the local class implements the {@link android.app.LoaderManager.LoaderCallbacks} interface, so it passes a reference -to itself, {@code this}.</li> +to itself, {@code this}.</li> </ul> <p>The {@link android.app.LoaderManager#initLoader initLoader()} call ensures that a loader is initialized and active. It has two possible outcomes:</p> @@ -196,7 +196,7 @@ the life of the loader automatically. The {@link android.app.LoaderManager} starts and stops loading when necessary, and maintains the state of the loader and its associated content. As this implies, you rarely interact with loaders directly (though for an example of using loader methods to fine-tune a loader's -behavior, see the <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LoaderThrottle.html"> LoaderThrottle</a> sample). +behavior, see the <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LoaderThrottle.html"> LoaderThrottle</a> sample). You most commonly use the {@link android.app.LoaderManager.LoaderCallbacks} methods to intervene in the loading process when particular events occur. For more discussion of this topic, see <a @@ -249,7 +249,7 @@ Instantiate and return a new {@link android.content.Loader} for the given ID. — Called when a previously created loader has finished its load. </li></ul> <ul> - <li>{@link android.app.LoaderManager.LoaderCallbacks#onLoaderReset onLoaderReset()} + <li>{@link android.app.LoaderManager.LoaderCallbacks#onLoaderReset onLoaderReset()} — Called when a previously created loader is being reset, thus making its data unavailable. </li> @@ -344,11 +344,11 @@ public void onLoadFinished(Loader<Cursor> loader, Cursor data) { <h4 id="onLoaderReset">onLoaderReset</h4> -<p>This method is called when a previously created loader is being reset, thus +<p>This method is called when a previously created loader is being reset, thus making its data unavailable. This callback lets you find out when the data is about to be released so you can remove your reference to it.  </p> -<p>This implementation calls -{@link android.widget.SimpleCursorAdapter#swapCursor swapCursor()} +<p>This implementation calls +{@link android.widget.SimpleCursorAdapter#swapCursor swapCursor()} with a value of <code>null</code>:</p> <pre> @@ -370,7 +370,7 @@ public void onLoaderReset(Loader<Cursor> loader) { android.app.Fragment} that displays a {@link android.widget.ListView} containing the results of a query against the contacts content provider. It uses a {@link android.content.CursorLoader} to manage the query on the provider.</p> - + <p>For an application to access a user's contacts, as shown in this example, its manifest must include the permission {@link android.Manifest.permission#READ_CONTACTS READ_CONTACTS}.</p> diff --git a/docs/html/guide/components/processes-and-threads.jd b/docs/html/guide/components/processes-and-threads.jd index 7bb3c65a373b..250799853c92 100644 --- a/docs/html/guide/components/processes-and-threads.jd +++ b/docs/html/guide/components/processes-and-threads.jd @@ -121,7 +121,7 @@ required to keep the user interface responsive.</p></li> <ul> <li>It hosts an {@link android.app.Activity} that is not in the foreground, but is still -visible to the user (its {@link android.app.Activity#onPause onPause()} method has been called). +visible to the user (its {@link android.app.Activity#onPause onPause()} method has been called). This might occur, for example, if the foreground activity started a dialog, which allows the previous activity to be seen behind it.</li> diff --git a/docs/html/guide/practices/index.jd b/docs/html/guide/practices/index.jd index b61272b91ad7..f34a6ba2eef4 100644 --- a/docs/html/guide/practices/index.jd +++ b/docs/html/guide/practices/index.jd @@ -1,7 +1,7 @@ page.title=Best Practices excludeFromSuggestions=true page.landing=true -page.landing.intro=Design and build apps the right way. Learn how to create apps that look great and perform well on as many devices as possible, from phones to tablets and more. +page.landing.intro=Design and build apps the right way. Learn how to create apps that look great and perform well on as many devices as possible, from phones to tablets and more. page.landing.image= @jd:body @@ -10,20 +10,20 @@ page.landing.image= <div class="col-12"> <h3>Blog Articles</h3> - + <a href="http://android-developers.blogspot.com/2010/10/improving-app-quality.html"> <h4>Improving App Quality</h4> <p>One way of improving your app’s visibility in the ecosystem is by deploying well-targeted mobile advertising campaigns and cross-app promotions. However, there’s another time-tested method of fueling the impression-install-ranking cycle: improve the product!</p> </a> - + <a href="http://android-developers.blogspot.com/2012/01/say-goodbye-to-menu-button.html"> <h4>Say Goodbye to the Menu Button</h4> <p>As Ice Cream Sandwich rolls out to more devices, it's important that you begin to migrate your designs to the action bar in order to promote a consistent Android user experience.</p> </a> - + <a href="http://android-developers.blogspot.com/2011/07/new-tools-for-managing-screen-sizes.html"> <h4>New Tools For Managing Screen Sizes</h4> <p>Android 3.2 includes new tools for supporting devices with a wide range of screen sizes. @@ -31,14 +31,14 @@ One important result is better support for a new size of screen; what is typical tablet. This release also offers several new APIs to simplify developers’ work in adjusting to different screen sizes.</p> </a> - + <a href="http://android-developers.blogspot.com/2011/03/identifying-app-installations.html"> <h4>Identifying App Installations</h4> <p>It is very common, and perfectly reasonable, for a developer to want to track individual installations of their apps. It sounds plausible just to call TelephonyManager.getDeviceId() and use that value to identify the installation. There are problems with this</p> </a> - + <a href="http://android-developers.blogspot.com/2011/11/making-android-games-that-play-nice.html"> <h4>Making Android Games that Play Nice</h4> @@ -46,7 +46,7 @@ href="http://android-developers.blogspot.com/2011/11/making-android-games-that-p often multi-core, multi-purpose system like Android is trickier. Even the best developers frequently make mistakes in the way they interact with the Android system and with other applications</p> </a> - + </div> diff --git a/docs/html/guide/practices/optimizing-for-3.0.jd b/docs/html/guide/practices/optimizing-for-3.0.jd index 8d07eb9847d8..db45e19ce0da 100644 --- a/docs/html/guide/practices/optimizing-for-3.0.jd +++ b/docs/html/guide/practices/optimizing-for-3.0.jd @@ -4,7 +4,7 @@ excludeFromSuggestions=true <div id="deprecatedSticker"> - <a href="#" + <a href="#" onclick="$('#naMessage').show();$('#deprecatedSticker').hide();return false"> <strong>This doc is deprecated</strong></a> </div> @@ -181,7 +181,7 @@ larger screens.</p> <li>Perform your usual tests to be sure everything works and looks as expected.</li> </ol> </li> - + <li><b>Apply the new "holographic" theme to your application</b> <ol> <li>Open your manifest file and update the <a @@ -191,7 +191,7 @@ href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code android:targetSdkVersion}</a> to {@code "11"}. For example: <pre> <manifest ... > - <uses-sdk android:minSdkVersion="4" + <uses-sdk android:minSdkVersion="4" android:targetSdkVersion="11" /> <application ... > ... @@ -446,7 +446,7 @@ Multi-choice List</a>: An example of how to provide multiple-choice selection fo GridView.</li> <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LoaderThrottle.html"> -Content Loaders</a>: An example using new Loader APIs to asynchronously load data.</li> +Content Loaders</a>: An example using new Loader APIs to asynchronously load data.</li> <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/animation/index.html"> Property Animation</a>: Several samples using the new animation APIs to animate object @@ -624,7 +624,7 @@ landscape orientation and that is how most users will use them. So, you should e application can function in landscape. Even if you want to avoid rotating the screen while your application is running, you should not assume that portrait is the device's default orientation. You should either ensure that your layout is usable in both portrait and landscape orientations or -provide an <a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources" +provide an <a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources" >alternative layout resource</a> for landscape orientation.</p> <p>If you believe your application or game provides its best experience when the screen is tall, diff --git a/docs/html/guide/practices/screen-compat-mode.jd b/docs/html/guide/practices/screen-compat-mode.jd index 34580ba824cf..18a089e1d119 100644 --- a/docs/html/guide/practices/screen-compat-mode.jd +++ b/docs/html/guide/practices/screen-compat-mode.jd @@ -75,7 +75,7 @@ android:targetSdkVersion}</a> to {@code "4"} or higher, or set <a href="{@docRoot}guide/topics/manifest/supports-screens-element.html#resizeable">{@code android:resizeable}</a> to {@code "true"}.</p> </dd> - + <dt>Version 2 (Android 3.2 and greater)</dt> <dd>The system draws the application's layout the same as it would on a normal size handset (approximately emulating a 320dp x 480dp screen), then scales it @@ -151,9 +151,9 @@ android:xlargeScreens}</a> attribute to {@code "true"}:</p> system will always resize your layout to fit the screen. This works regardless of what values you've set in the <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code <uses-sdk>}</a> -attributes.</p> +attributes.</p> </li> - + <li><strong>Easy but has other effects:</strong> <p>In your manifest's <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code <uses-sdk>}</a> diff --git a/docs/html/guide/practices/screens_support.jd b/docs/html/guide/practices/screens_support.jd index 2223dbf3096d..ea9f988daac7 100644 --- a/docs/html/guide/practices/screens_support.jd +++ b/docs/html/guide/practices/screens_support.jd @@ -139,7 +139,7 @@ or position in a density-independent way. <p>The density-independent pixel is equivalent to one physical pixel on a 160 dpi screen, which is the baseline density assumed by the system for a "medium" density screen. At runtime, the system transparently handles any scaling of the dp units, as necessary, based on the actual density of the -screen in use. The conversion of dp units to screen pixels is simple: +screen in use. The conversion of dp units to screen pixels is simple: <nobr><code>px = dp * (dpi / 160)</code></nobr>. For example, on a 240 dpi screen, 1 dp equals 1.5 physical pixels. You should always use dp units when defining your application's UI, to ensure proper display of your UI on screens with different @@ -214,7 +214,7 @@ changes in screen density.</p> </ul> <p class="note"><strong>Note:</strong> These minimum screen sizes were not as well defined prior to -Android 3.0, so you may encounter some devices that are mis-classified between normal and large. +Android 3.0, so you may encounter some devices that are mis-classified between normal and large. These are also based on the physical resolution of the screen, so may vary across devices—for example a 1024x720 tablet with a system bar actually has a bit less space available to the application due to it being used by the system bar.</p> @@ -904,7 +904,7 @@ href="{@docRoot}guide/topics/manifest/supports-screens-element.html"><support manifest element:</p> <dl> - + <dt><a href="{@docRoot}guide/topics/manifest/supports-screens-element.html#requiresSmallest"> {@code android:requiresSmallestWidthDp}</a></dt> diff --git a/docs/html/guide/practices/tablets-and-handsets.jd b/docs/html/guide/practices/tablets-and-handsets.jd index 85327b6d7036..a1bafd3d7dec 100644 --- a/docs/html/guide/practices/tablets-and-handsets.jd +++ b/docs/html/guide/practices/tablets-and-handsets.jd @@ -89,7 +89,7 @@ href="{@docRoot}guide/components/fragments.html">Fragments</a> developer guide.< </li> - <li><strong>Use the action bar</strong>, but follow best practices and ensure your design + <li><strong>Use the action bar</strong>, but follow best practices and ensure your design is flexible enough for the system to adjust the action bar layout based on the screen size. <p>The {@link android.app.ActionBar} is a UI component for activities that replaces the traditional 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 f6669e4f36b4..b66fdd42a1f4 100644 --- a/docs/html/guide/practices/ui_guidelines/activity_task_design.jd +++ b/docs/html/guide/practices/ui_guidelines/activity_task_design.jd @@ -8,7 +8,7 @@ parent.link=index.html <div id="deprecatedSticker"> - <a href="#" + <a href="#" onclick="$('#naMessage').show();$('#deprecatedSticker').hide();return false"> <strong>This doc is deprecated</strong></a> </div> @@ -105,7 +105,7 @@ need to</a></li> <p> It illustrates activities and tasks with examples, and describes some of their underlying principles and mechanisms, such as navigation, - multitasking, activity re-use, intents, and the activity stack. + multitasking, activity re-use, intents, and the activity stack. The document also highlights design decisions that are available to you and what control they give you over the UI of your application. </p> @@ -146,7 +146,7 @@ document), <p> An Android <em>application</em> typically consists of one or more - related, loosely bound activities <!--(and possibly + related, loosely bound activities <!--(and possibly <a href=#services_broadcast_receivers title="other components">other components</a>)--> for the user to interact with, typically bundled up in a single file (with an .apk suffix). Android ships with a rich set @@ -186,10 +186,10 @@ document), seamless, activity after activity, <a href="#tasks">task</a> after task. </p> - + <p> An activity handles a particular type of content (data) and accepts a - set of related user actions. Each activity has a + set of related user actions. Each activity has a <a href="{@docRoot}guide/components/activities.html#Lifecycle">lifecycle</a> that is independent of the other activities in its application or task — each activity is @@ -283,7 +283,7 @@ independent of the other to the activity stack, so that pressing <em>Back</em> displays the previous activity on the stack. However, the user cannot use the <em>Back</em> button to go back further than the last visit to Home. The adding of an activity to - the current stack happens whether or not that activity begins a new + the current stack happens whether or not that activity begins a new <a href=#tasks title=task>task</a> (as long as that task was started without going Home), so going back can let the user go back to activities in previous tasks. The user can get to tasks earlier than @@ -297,7 +297,7 @@ independent of the other designing the navigation, if you have screen A and you want the user to be able go to a subsequent screen B and then use the <em>Back</em> button to go back to screen A, then the screen A needs to be implemented as an - activity. The one exception to this rule is if your application + activity. The one exception to this rule is if your application <a href="#taking_over_back_key">takes control of the <em>Back</em> button</a> and manages the navigation itself. @@ -340,7 +340,7 @@ itself. Send a text message with an attachment </li> <li> - View a YouTube video and share it by email with someone else + View a YouTube video and share it by email with someone else </li> </ul> @@ -666,7 +666,7 @@ itself. mailto:info@example.com link, they are actually initiating an Intent object, or just an <em>intent</em>, which then gets resolved to a particular component (we consider only activity components here). - So, the result of a user touching a mailto: link is an Intent object + So, the result of a user touching a mailto: link is an Intent object that the system tries to match to an activity. If that Intent object was written explicitly naming an activity (an <em>explicit intent</em>), then the system immediately launches that activity in response to the user @@ -925,7 +925,7 @@ href="{@docRoot}guide/components/intents-filters.html">Intents and Intent Filter For instance, you could disable the user control that initiates the Intent object, or display a message to the user that lets them go to a location, such as Google Play, to download its application. - In this way, your code can start the activity (using either startActivity() + In this way, your code can start the activity (using either startActivity() or startActivityForResult()) only if the intent has tested to resolve to an activity that is actually present. </p> @@ -947,7 +947,7 @@ href="{@docRoot}guide/components/intents-filters.html">Intents and Intent Filter launcher</em> (typically implemented as a sliding drawer on the Home screen), or from a shortcut icon on the Home screen, or from the task switcher. (The mechanism for this is for the - activity to have an + activity to have an <a href={@docRoot}guide/components/intents-filters.html>intent filter</a> with action MAIN and category LAUNCHER.) @@ -1103,7 +1103,7 @@ MAIN and activity to be run. </p> - + <h3 id="notifications_get_back_tip">Notifications and App Widgets should provide consistent back behavior</h3> <p> Notifications and app widgets are two common ways that a user can launch diff --git a/docs/html/guide/practices/ui_guidelines/icon_design.jd b/docs/html/guide/practices/ui_guidelines/icon_design.jd index 07266607ed4c..6b546c9fd21d 100644 --- a/docs/html/guide/practices/ui_guidelines/icon_design.jd +++ b/docs/html/guide/practices/ui_guidelines/icon_design.jd @@ -58,7 +58,7 @@ Screens</a></li> <div class="note design"> -<p><strong>New Guides for App Designers!</strong></p> +<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> @@ -72,13 +72,13 @@ professional to users.</p> <p>This document provides information to help you create icons for various parts of your application’s user interface that match the general styles used by the -Android 2.x framework. Following these guidelines will help you to create a +Android 2.x framework. Following these guidelines will help you to create a polished and unified experience for the user.</p> <p>The following documents discuss detailed guidelines for the common types of icons used throughout Android applications:</p> -<dl> +<dl> <dt><strong><a href="icon_design_launcher.html">Launcher Icons</a></strong></dt> <dd>A Launcher icon is a graphic that represents your application on the device's Home screen and in the Launcher window.</dd> @@ -103,7 +103,7 @@ icons used throughout Android applications:</p> graphically represent list items. An example is the Settings application.</dd> </dl> -<p>To get started creating your icons more quickly, you can download +<p>To get started creating your icons more quickly, you can download the Android Icon Templates Pack.</p> @@ -142,7 +142,7 @@ section in the box at the top-right corner of this page.</p> <p>Android is designed to run on a variety of devices that offer a range of screen sizes and resolutions. When you design the icons for your application, it's important keep in mind that your application may be installed on any of -those devices. As described in the <a +those devices. As described in the <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a> document, the Android platform makes it straightforward for you to provide icons in such a way that they will be displayed properly on any device, @@ -158,7 +158,7 @@ your application, see <a href="{@docRoot}guide/practices/screens_support.html#qualifiers">Resource directory qualifiers for screen size and density</a>. </p> -<p>For tips on how to create and manage icon sets for multiple densities, see +<p>For tips on how to create and manage icon sets for multiple densities, see <a href="#design-tips">Tips for Designers</a>.</p> @@ -290,7 +290,7 @@ initially draw launcher icons on an 864x864 artboard, it will be easier and cleaner to tweak the icons when you scale the artboard down to the target sizes for final asset creation.</p> - + <h3>When scaling, redraw bitmap layers as needed</h3> 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 831de4569edd..37657f4d1ecc 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 @@ -31,7 +31,7 @@ Screens</a></li> </div> <div class="note design"> -<p><strong>New Guides for App Designers!</strong></p> +<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> 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 c958ed9a655e..a7ee73f41a78 100644 --- a/docs/html/guide/practices/ui_guidelines/icon_design_dialog.jd +++ b/docs/html/guide/practices/ui_guidelines/icon_design_dialog.jd @@ -29,7 +29,7 @@ Screens</a></li> </div> <div class="note design"> -<p><strong>New Guides for App Designers!</strong></p> +<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> 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 f47e186790a9..3bb1a627c85c 100644 --- a/docs/html/guide/practices/ui_guidelines/icon_design_launcher.jd +++ b/docs/html/guide/practices/ui_guidelines/icon_design_launcher.jd @@ -28,7 +28,7 @@ Screens</a></li> <div class="note design"> -<p><strong>New Guides for App Designers!</strong></p> +<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> diff --git a/docs/html/guide/practices/ui_guidelines/icon_design_launcher_archive.jd b/docs/html/guide/practices/ui_guidelines/icon_design_launcher_archive.jd index 2df3a2250ef5..483e076ac52f 100644 --- a/docs/html/guide/practices/ui_guidelines/icon_design_launcher_archive.jd +++ b/docs/html/guide/practices/ui_guidelines/icon_design_launcher_archive.jd @@ -95,7 +95,7 @@ but rather they are meant to emphasize the common approaches that your icons can share with others on the device. Figure 1, at right, provides examples. </p> <div class="figure"> - <img src="{@docRoot}images/icon_design/IconGraphic_Icons_i.png" + <img src="{@docRoot}images/icon_design/IconGraphic_Icons_i.png" width="340"> <p class="img-caption"> <strong>Figure 1.</strong> Example launcher icons for Android 2.0 and 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 29e1a9380de7..fa350bc2b6a7 100644 --- a/docs/html/guide/practices/ui_guidelines/icon_design_list.jd +++ b/docs/html/guide/practices/ui_guidelines/icon_design_list.jd @@ -30,7 +30,7 @@ Screens</a></li> <div class="note design"> -<p><strong>New Guides for App Designers!</strong></p> +<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> 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 a5b35977fc0e..25b23d0f628c 100644 --- a/docs/html/guide/practices/ui_guidelines/icon_design_menu.jd +++ b/docs/html/guide/practices/ui_guidelines/icon_design_menu.jd @@ -34,7 +34,7 @@ Screens</a></li> <div class="note design"> -<p><strong>New Guides for App Designers!</strong></p> +<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> @@ -267,7 +267,7 @@ menu icon <a href="#palette1">color palette</a>. </li> appropriate. For example, in Figure 3 the logical place for rounded corners is the roof and not the rest of the building.</span></li> -<li>All dimensions specified on this page are based on a 48x48 pixel artboard +<li>All dimensions specified on this page are based on a 48x48 pixel artboard size with a 6 pixel safeframe.</li> <li>The menu icon effect (the outer glow) described in <a @@ -277,7 +277,7 @@ safeframe.</li> <li><strong>Final art must be exported as a transparent PNG file.</strong></li> -<li>Templates for creating menu icons in Adobe Photoshop are available in the +<li>Templates for creating menu icons in Adobe Photoshop are available in the Icon Templates Pack.</li> </ul> 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 4993adb0328b..27df450e1673 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 @@ -42,7 +42,7 @@ Screens</a></li> <div class="note design"> -<p><strong>New Guides for App Designers!</strong></p> +<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> 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 cbe6706fb067..308e6d092c1e 100644 --- a/docs/html/guide/practices/ui_guidelines/icon_design_tab.jd +++ b/docs/html/guide/practices/ui_guidelines/icon_design_tab.jd @@ -34,7 +34,7 @@ Screens</a></li> <div class="note design"> -<p><strong>New Guides for App Designers!</strong></p> +<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> @@ -291,10 +291,10 @@ your application. </p> the Android platform.</p> <p class="warning"><strong>Warning:</strong> -Because these resources can change between platform versions, you +Because these resources can change between platform versions, you should not reference the system's copy of the resources. If you want to use any icons or other internal drawable resources, you should store a -local copy of those icons or drawables in your application resources, +local copy of those icons or drawables in your application resources, then reference the local copy from your application code. In that way, you can maintain control over the appearance of your icons, even if the system's copy changes. Note that the grid below is not intended to be complete.</p> diff --git a/docs/html/guide/practices/ui_guidelines/index.jd b/docs/html/guide/practices/ui_guidelines/index.jd index 91a0725b82e3..713109cf2bcf 100644 --- a/docs/html/guide/practices/ui_guidelines/index.jd +++ b/docs/html/guide/practices/ui_guidelines/index.jd @@ -7,7 +7,7 @@ excludeFromSuggestions=true <div class="note design" 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><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> diff --git a/docs/html/guide/practices/ui_guidelines/menu_design.jd b/docs/html/guide/practices/ui_guidelines/menu_design.jd index bf87bdd124e7..949752588a12 100644 --- a/docs/html/guide/practices/ui_guidelines/menu_design.jd +++ b/docs/html/guide/practices/ui_guidelines/menu_design.jd @@ -8,7 +8,7 @@ parent.link=index.html <div id="deprecatedSticker"> - <a href="#" + <a href="#" onclick="$('#naMessage').show();$('#deprecatedSticker').hide();return false"> <strong>This doc is deprecated</strong></a> </div> @@ -16,7 +16,7 @@ parent.link=index.html <div id="naMessage" style="display:block"> <div><p><strong>This document has been deprecated.</strong></p> - <p>For design guidelines about adding user actions and other options, read the design guidelines + <p>For design guidelines about adding user actions and other options, read the design guidelines for <a href="{@docRoot}design/patterns/actionbar.html">Action Bar</a> or the developer guide about <a href="{@docRoot}guide/topics/ui/menus.html">Menus</a>.</p> @@ -25,7 +25,7 @@ for <a href="{@docRoot}design/patterns/actionbar.html">Action Bar</a> or the dev onclick="$('#naMessage').hide();$('#deprecatedSticker').show()" /> </div> </div> - + @@ -37,7 +37,7 @@ onclick="$('#naMessage').hide();$('#deprecatedSticker').show()" /> <div id="qv-wrapper"> <div id="qv"> - + <h2>Quickview</h2> <ul> @@ -85,15 +85,15 @@ onclick="$('#naMessage').hide();$('#deprecatedSticker').show()" /> </ol> </div> -</div> +</div> <p> A menu holds a set of commands (user actions) that are normally hidden, and are accessible by a button, key, or gesture. Menu commands provide a means - for performing operations and for navigating to other parts of your + for performing operations and for navigating to other parts of your application or other applications. Menus are useful for freeing screen space, as an alternative to placing functionality and navigation, in buttons or other - user controls in the content area of your application. + user controls in the content area of your application. </p> <p> @@ -102,7 +102,7 @@ onclick="$('#naMessage').hide();$('#deprecatedSticker').show()" /> the functionality and navigation for your application. Briefly: <ul> <li>The <em>Options menu</em> contains primary functionality that applies - globally to the current activity or starts a related activity. + globally to the current activity or starts a related activity. It is typically invoked by a user pressing a hard button, often labeled <em>Menu</em>.</li> <li>The <em>Context menu</em> contains secondary functionality for the currently selected item. It is typically invoked by a user's touch & hold @@ -113,11 +113,11 @@ onclick="$('#naMessage').hide();$('#deprecatedSticker').show()" /> <p> All but the simplest applications have menus. The system automatically - lays the menus out and provides standard ways for users to access them. + lays the menus out and provides standard ways for users to access them. In this sense, they are familiar and dependable ways for users to access functionality across all applications. All menus are panels that "float" on top of the activity screen and are smaller than full screen, so that the - application is still visible around its edges. This is a visual reminder + application is still visible around its edges. This is a visual reminder that a menu is an intermediary operation that disappears once it's used. </p> @@ -127,8 +127,8 @@ onclick="$('#naMessage').hide();$('#deprecatedSticker').show()" /> <h2 id="tour_of_the_menus">Tour of the Menus</h2> -<p class="note"><strong>Note:</strong> Your menus and screens might not look -like those shown in this document; they may vary from one version of Android +<p class="note"><strong>Note:</strong> Your menus and screens might not look +like those shown in this document; they may vary from one version of Android or device to another. </p> @@ -137,13 +137,13 @@ or device to another. <p> The Options menu contains commands that apply globally across the current activity, or can start another activity. They do not apply to a selected - item in the content (a <a href="#context_menu">Context menu</a> does that). + item in the content (a <a href="#context_menu">Context menu</a> does that). </p> <p> - On most devices, a user presses the <em>Menu</em> button to access the Options menu, - as shown in the screenshot below. To close the menu, the user presses - <em>Menu</em> again, or presses the <em>Back</em> button. + On most devices, a user presses the <em>Menu</em> button to access the Options menu, + as shown in the screenshot below. To close the menu, the user presses + <em>Menu</em> again, or presses the <em>Back</em> button. In fact, to cancel out of any menu, press the <em>Back</em> button. (Pressing the <em>Menu</em> button or touching outside the menu also works.) Note that how to invoke this menu may be different on different devices. @@ -153,15 +153,15 @@ or device to another. Each <a href="{@docRoot}guide/practices/ui_guidelines/activity_task_design.html#activities">activity</a> activity has its own set of operations and therefore its own Options menu. - An application with multiple activities would have a different Options menu - for each activity. + An application with multiple activities would have a different Options menu + for each activity. </p> <p> For example, in the message list view of an email program, the Options menu - might let you search the messages, compose a new message, refresh the list, - or change the email settings. The compose view of an email program would - have a different Options menu, such as adding a CC field, attaching a file, + might let you search the messages, compose a new message, refresh the list, + or change the email settings. The compose view of an email program would + have a different Options menu, such as adding a CC field, attaching a file, or discarding the message. </p> @@ -179,7 +179,7 @@ or device to another. <li> <b>Options expanded menu</b> - If the activity has more menu items than will fit on the icon menu, then the last icon is labeled "More" — selecting it - displays a list that can contain any number of menu items and will scroll + displays a list that can contain any number of menu items and will scroll as necessary. </li> </ul> @@ -202,18 +202,18 @@ or device to another. <p> A user can touch & hold on content on the screen to - access a Context menu (if one exists), as shown in the screenshot below. + access a Context menu (if one exists), as shown in the screenshot below. A Context menu is a list of menu items (commands) that can operate on the selected content. The command can either be part of the current - activity, or the system can pass the selected content along to - an operation in another activity (by way of an + activity, or the system can pass the selected content along to + an operation in another activity (by way of an <a href="{@docRoot}guide/practices/ui_guidelines/activity_task_design.html#intents">intent</a>). </p> <p> For example, in an email message list, a user can touch & hold on an email message to open a Context menu containing commands to read, - archive, or delete the message. + archive, or delete the message. </p> <p id="location"> @@ -231,7 +231,7 @@ or device to another. In the above example, if the user performs touch & hold on the contact "Obi Wan Kenobi", a Context menu opens. The commands provided in this Context menu are the complete set of actions that can be performed - on this contact. + on this contact. </p> <p> @@ -246,7 +246,7 @@ or device to another. <p> Also note, as shown in the following screenshot, the Context menu and the next screen both hold the same complete set of commands that can be performed - on this contact. The Context menu displays the commands in a list, + on this contact. The Context menu displays the commands in a list, while the "View contact" activity splits them into various items in the Options menu, icon buttons and list items. </p> @@ -268,10 +268,10 @@ or device to another. <h4>Text Commands in Context Menu</h4> <p> - Text links and text fields in the content both have system-provided operations + Text links and text fields in the content both have system-provided operations that are common across all applications: operations such as "Select all", "Select text", - "Copy all", and "Add to dictionary". If the text field is editable, it also - has other operations, such as "Cut all" and "Input Method", and if text + "Copy all", and "Add to dictionary". If the text field is editable, it also + has other operations, such as "Cut all" and "Input Method", and if text is also on the clipboard, it has "Paste". The system automatically inserts the appropriate menu items into the Context menu of text links and text fields, as shown in the following screenshot. @@ -342,7 +342,7 @@ or device to another. An example of a selection-specific Context menu is when a user performs a touch & hold on a person's name in a list view of a contacts application. The Context menu would typically contain commands "View contact", "Call contact", - and "Edit contact". + and "Edit contact". </p> <h3 id="most_frequently_used">Place the most frequently used operations first</h3> @@ -365,7 +365,7 @@ or device to another. <h3 id="dont_put_commands">Don't put commands <em>only</em> in a Context menu</h3> <p> - If a user can fully access your application without using Context menus, + If a user can fully access your application without using Context menus, then it's designed properly! In general, if part of your application is inaccessible without using Context menus, then you need to duplicate those commands elsewhere. </p> @@ -373,8 +373,8 @@ or device to another. <p> Before opening a Context menu, it has no visual representation that identifies its presence (whereas the Options menu has the <em>Menu</em> button), and so is not - particularly discoverable. - Therefore, in general, a Context menu should <em>duplicate</em> commands + particularly discoverable. + Therefore, in general, a Context menu should <em>duplicate</em> commands found in the corresponding activity screen. For example, while it's useful to let the user call a phone number from a Context menu invoked by touch & hold on a name in a list of contacts, that operation should <em>also</em> @@ -388,7 +388,7 @@ or device to another. As described under <a href="#context_menu_shortcut">shortcut</a>, touching on an item in the content should activate the same command as touching the first item in the Context menu. Both cases should be the most intuitive - operation for that item. + operation for that item. </p> <h3 id="selecting_content_item">Selecting an item in the content should perform the most intuitive operation</h3> @@ -427,13 +427,13 @@ or device to another. <h3 id="context_menu_should_identify">A Context menu should identify the selected item</h3> <p> - When a user does touch & hold on an item, the Context menu should - contain the name of the selected item. Therefore, + When a user does touch & hold on an item, the Context menu should + contain the name of the selected item. Therefore, when creating a Context menu, be sure to include a title and the name of the - selected item so that it's clear to the user what the context is. + selected item so that it's clear to the user what the context is. For example, if a user selects a contact "Joan of Arc", put that name in the title of the Context menu (using - {@link android.view.ContextMenu#setHeaderTitle(java.lang.CharSequence) setHeaderTitle}). + {@link android.view.ContextMenu#setHeaderTitle(java.lang.CharSequence) setHeaderTitle}). Likewise, a command to edit the contact should be called "Edit contact", not just "Edit". </p> @@ -442,7 +442,7 @@ or device to another. <h3 id="most_important_commands">Put only the most important commands fixed on the screen</h3> <p> - By putting commands in menus, you free up the screen to hold more content. + By putting commands in menus, you free up the screen to hold more content. On the other hand, fixing commands in the content area of an activity makes them more prominent and easy to use. </p> @@ -456,7 +456,7 @@ or device to another. To give a command the highest prominence, ensuring the command is obvious and won't be overlooked.<br> Example: A "Buy" button in a store application. </li> - <li> + <li> When quick access to the command is important and going to the menu would be tedious or slow.<br> Example: Next/Previous buttons or Zoom In/Out buttons in an image viewing application. @@ -494,7 +494,7 @@ or device to another. When a dialog is displayed, pressing the <em>Menu</em> button should do nothing. This also holds true for activities that look like dialogs. A dialog box is recognizable by being - smaller than full-screen, having zero to three buttons, is non-scrollable, and + smaller than full-screen, having zero to three buttons, is non-scrollable, and possibly a list of selectable items that can include checkboxes or radio buttons. <!--For examples of dialogs, see Text Guidelines.--> </p> @@ -520,12 +520,12 @@ true <p> Sometimes a menu item's action cannot be performed — for example, - the "Forward" button in a browser cannot work until after the "Back" + the "Forward" button in a browser cannot work until after the "Back" button has been pressed. We recommend: </p> <ul> - <li> + <li> <b>In Options menu</b> - disable the menu item, which dims the text and icon, turning it gray. This applies to menu items in both the icon menu and the "More" menu. It would be disorienting for the icon menu to change from 6 diff --git a/docs/html/guide/practices/ui_guidelines/widget_design.jd b/docs/html/guide/practices/ui_guidelines/widget_design.jd index cf2cd64d483a..95c594dba972 100644 --- a/docs/html/guide/practices/ui_guidelines/widget_design.jd +++ b/docs/html/guide/practices/ui_guidelines/widget_design.jd @@ -46,7 +46,7 @@ parent.link=index.html <div class="note design"> -<p><strong>New Guides for App Designers!</strong></p> +<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> diff --git a/docs/html/guide/topics/admin/device-admin.jd b/docs/html/guide/topics/admin/device-admin.jd index e2fef04b7537..2a8583a83e7d 100644 --- a/docs/html/guide/topics/admin/device-admin.jd +++ b/docs/html/guide/topics/admin/device-admin.jd @@ -135,60 +135,60 @@ can require PIN or passwords to have at least six characters. </td> </tr> combination of letters and numbers. They may include symbolic characters. </td> </tr> - + <tr> <td>Complex password required</td> <td>Requires that passwords must contain at least a letter, a numerical digit, and a special symbol. Introduced in Android 3.0. </td> </tr> - -<tr> + +<tr> <td>Minimum letters required in password</td> <td>The minimum number of -letters required in the password for all admins or a particular one. Introduced in Android 3.0.</td> +letters required in the password for all admins or a particular one. Introduced in Android 3.0.</td> </tr> - - - <tr> - <td>Minimum lowercase letters required in password</td> - <td>The minimum number of lowercase -letters required in the password for all admins or a particular one. Introduced in Android 3.0.</td> + + + <tr> + <td>Minimum lowercase letters required in password</td> + <td>The minimum number of lowercase +letters required in the password for all admins or a particular one. Introduced in Android 3.0.</td> </tr> - - <tr> - <td>Minimum non-letter characters required in password</td> + + <tr> + <td>Minimum non-letter characters required in password</td> <td>The minimum number of -non-letter characters required in the password for all admins or a particular one. Introduced in Android 3.0.</td> +non-letter characters required in the password for all admins or a particular one. Introduced in Android 3.0.</td> </tr> - -<tr> - <td>Minimum numerical digits required in password</td> - <td>The minimum number of numerical digits required in the password for all admins or a particular one. Introduced in Android 3.0.</td> + +<tr> + <td>Minimum numerical digits required in password</td> + <td>The minimum number of numerical digits required in the password for all admins or a particular one. Introduced in Android 3.0.</td> </tr> -<tr> - <td>Minimum symbols required in password</td> - <td>The minimum number of symbols required in the password for all admins or a particular one. Introduced in Android 3.0.</td> +<tr> + <td>Minimum symbols required in password</td> + <td>The minimum number of symbols required in the password for all admins or a particular one. Introduced in Android 3.0.</td> </tr> -<tr> - <td>Minimum uppercase letters required in password</td> - <td>The minimum number of uppercase letters required in the password for all admins or a particular one. Introduced in Android 3.0.</td> +<tr> + <td>Minimum uppercase letters required in password</td> + <td>The minimum number of uppercase letters required in the password for all admins or a particular one. Introduced in Android 3.0.</td> </tr> -<tr> - <td>Password expiration timeout</td> - <td>When the password will expire, expressed as a delta in milliseconds from when a device admin sets the expiration timeout. Introduced in Android 3.0.</td> +<tr> + <td>Password expiration timeout</td> + <td>When the password will expire, expressed as a delta in milliseconds from when a device admin sets the expiration timeout. Introduced in Android 3.0.</td> </tr> -<tr> - <td>Password history restriction</td> +<tr> + <td>Password history restriction</td> <td>This policy prevents users from reusing the last <em>n</em> unique passwords. This policy is typically used in conjunction with {@link android.app.admin.DevicePolicyManager#setPasswordExpirationTimeout(android.content.ComponentName,long) setPasswordExpirationTimeout()}, which forces users to update their passwords after a specified amount of time has elapsed. -Introduced in Android 3.0.</td> +Introduced in Android 3.0.</td> </tr> - + <tr> <td>Maximum failed password attempts </td> <td>Specifies how many times a user can enter the wrong password before the @@ -203,18 +203,18 @@ pressed a button before the device locks the screen. When this happens, users need to enter their PIN or passwords again before they can use their devices and access data. The value can be between 1 and 60 minutes.</td> </tr> -<tr> -<td>Require storage encryption</td> -<td>Specifies that the storage area should be encrypted, if the device supports it. +<tr> +<td>Require storage encryption</td> +<td>Specifies that the storage area should be encrypted, if the device supports it. Introduced in Android 3.0.</td> </tr> <tr> <td>Disable camera</td> - + <td>Specifies that the camera should be disabled. Note that this doesn't have to be a permanent disabling. The camera can be enabled/disabled dynamically based on context, time, and so on. Introduced in Android 4.0.</td> - + </tr> @@ -234,7 +234,7 @@ Administration API lets you do the following:</p> <ul> <p>The examples used in this document are based on the Device Administration API sample, which is included in the SDK samples (available through the -Android SDK Manager) and located on your system as +Android SDK Manager) and located on your system as <code><sdk_root>/ApiDemos/app/src/main/java/com/example/android/apis/app/DeviceAdminSample.java</code>.</p> <p>The sample application offers a demo of device admin features. It presents users @@ -250,8 +250,8 @@ policies, the system returns an error.</li> <li>Set how many failed password attempts can occur before the device is wiped (that is, restored to factory settings).</li> <li>Set how long from now the password will expire.</li> -<li>Set the password history length (<em>length</em> refers to number of old passwords stored in the history). -This prevents users from reusing +<li>Set the password history length (<em>length</em> refers to number of old passwords stored in the history). +This prevents users from reusing one of the last <em>n</em> passwords they previously used.</li> <li>Specify that the storage area should be encrypted, if the device supports it.</li> <li>Set the maximum amount of inactive time that can elapse before the device @@ -259,7 +259,7 @@ locks.</li> <li>Make the device lock immediately.</li> <li>Wipe the device's data (that is, restore factory settings).</li> <li>Disable the camera.</li> - + </ul> @@ -454,8 +454,8 @@ changes to prompt the user to activate the device admin application, as shown in <img src="{@docRoot}images/admin/device-admin-activate-prompt.png"/> <p class="img-caption"><strong>Figure 2.</strong> Sample Application: Activating the Application</p> -<p>Below is the code that gets executed when the user clicks the <strong>Enable Admin</strong> checkbox. This has the effect of triggering the -{@link android.preference.Preference.OnPreferenceChangeListener#onPreferenceChange(android.preference.Preference, java.lang.Object) onPreferenceChange()} +<p>Below is the code that gets executed when the user clicks the <strong>Enable Admin</strong> checkbox. This has the effect of triggering the +{@link android.preference.Preference.OnPreferenceChangeListener#onPreferenceChange(android.preference.Preference, java.lang.Object) onPreferenceChange()} callback. This callback is invoked when the value of this {@link android.preference.Preference} has been changed by the user and is about to be set and/or persisted. If the user is enabling the application, the display changes to prompt the user to activate the device admin application, as shown in figure 2. Otherwise, the device admin application is disabled. </p> @@ -556,7 +556,7 @@ containing at least numeric characters.</dd> <dt>{@link android.app.admin.DevicePolicyManager#PASSWORD_QUALITY_COMPLEX}</dt><dd>The user must have entered a password containing at least a letter, a numerical digit and -a special symbol.</dd> +a special symbol.</dd> <dt>{@link android.app.admin.DevicePolicyManager#PASSWORD_QUALITY_SOMETHING}</dt><dd>The policy requires some kind @@ -581,7 +581,7 @@ example, you could set a policy that states that passwords must contain at least contents:</p> <ul> -<li>{@link android.app.admin.DevicePolicyManager#setPasswordMinimumLetters(android.content.ComponentName,int) setPasswordMinimumLetters()}</li> +<li>{@link android.app.admin.DevicePolicyManager#setPasswordMinimumLetters(android.content.ComponentName,int) setPasswordMinimumLetters()}</li> <li>{@link android.app.admin.DevicePolicyManager#setPasswordMinimumLowerCase(android.content.ComponentName,int) setPasswordMinimumLowerCase()}</li> @@ -622,8 +622,8 @@ int maxFailedPw; mDPM.setMaximumFailedPasswordsForWipe(mDeviceAdminSample, maxFailedPw);</pre> <h5 id="expiration">Set password expiration timeout</h5> -<p>Beginning with Android 3.0, you can use the -{@link android.app.admin.DevicePolicyManager#setPasswordExpirationTimeout(android.content.ComponentName,long) setPasswordExpirationTimeout()} +<p>Beginning with Android 3.0, you can use the +{@link android.app.admin.DevicePolicyManager#setPasswordExpirationTimeout(android.content.ComponentName,long) setPasswordExpirationTimeout()} method to set when a password will expire, expressed as a delta in milliseconds from when a device admin sets the expiration timeout. For example:</p> <pre>DevicePolicyManager mDPM; @@ -632,18 +632,18 @@ long pwExpiration; ... mDPM.setPasswordExpirationTimeout(mDeviceAdminSample, pwExpiration); </pre> - + <h5 id="history">Restrict password based on history</h5> -<p>Beginning with Android 3.0, you can use the -{@link android.app.admin.DevicePolicyManager#setPasswordHistoryLength(android.content.ComponentName,int) setPasswordHistoryLength()} +<p>Beginning with Android 3.0, you can use the +{@link android.app.admin.DevicePolicyManager#setPasswordHistoryLength(android.content.ComponentName,int) setPasswordHistoryLength()} method to limit users' ability to reuse old passwords. This method takes a <em>length</em> parameter, which specifies how many old passwords are stored. When this policy is active, users cannot enter a new password that matches the last <em>n</em> passwords. This prevents users from using the same password over and over. This policy is typically used -in conjunction with +in conjunction with {@link android.app.admin.DevicePolicyManager#setPasswordExpirationTimeout(android.content.ComponentName,long) setPasswordExpirationTimeout()}, which forces users to update their passwords after a specified amount of time has elapsed. </p> @@ -705,7 +705,7 @@ mDPM.setCameraDisabled(mDeviceAdminSample, mDisableCameraCheckbox.isChecked());< <h4 id="storage">Storage encryption</h4> <p>Beginning with Android 3.0, you can use the -{@link android.app.admin.DevicePolicyManager#setStorageEncryption(android.content.ComponentName,boolean) setStorageEncryption()} +{@link android.app.admin.DevicePolicyManager#setStorageEncryption(android.content.ComponentName,boolean) setStorageEncryption()} method to set a policy requiring encryption of the storage area, where supported.</p> <p>For example:</p> diff --git a/docs/html/guide/topics/appwidgets/host.jd b/docs/html/guide/topics/appwidgets/host.jd index 169e388918e2..7b00019239be 100644 --- a/docs/html/guide/topics/appwidgets/host.jd +++ b/docs/html/guide/topics/appwidgets/host.jd @@ -4,7 +4,7 @@ page.tags=AppWidgetHost,home screen,launcher <div id="qv-wrapper"> <div id="qv"> - + <h2>In this document</h2> <ol> <li><a href="#host-binding">Binding App Widgets</a> @@ -32,58 +32,58 @@ to embed <a href="{@docRoot}guide/topics/appwidgets/index.html">app widgets</a> access to content. If you're building a Home replacement or a similar app, you can also allow the user to embed app widgets by implementing an {@link android.appwidget.AppWidgetHost}. -This is not something that most apps will ever need to do, but if you are -creating your own host, it's important to understand the contractual obligations +This is not something that most apps will ever need to do, but if you are +creating your own host, it's important to understand the contractual obligations a host implicitly agrees to.</p> -<p>This document focuses on the responsibilities involved in implementing a custom -{@link android.appwidget.AppWidgetHost}. For an example of how to implement an +<p>This document focuses on the responsibilities involved in implementing a custom +{@link android.appwidget.AppWidgetHost}. For an example of how to implement an {@link android.appwidget.AppWidgetHost}, see the source code for the -Android Home screen +Android Home screen <a href="https://android.googlesource.com/platform/packages/apps/Launcher2/+/master/src/com/android/launcher2/Launcher.java"> -Launcher</a>. +Launcher</a>. -<p>Here is an overview of key classes and concepts involved in implementing a custom +<p>Here is an overview of key classes and concepts involved in implementing a custom {@link android.appwidget.AppWidgetHost}:</p> <ul> - <li><strong>App Widget Host</strong>— - The {@link android.appwidget.AppWidgetHost} provides the interaction -with the AppWidget service for apps, like the home screen, that want to embed -app widgets in their UI. An {@link android.appwidget.AppWidgetHost} must have -an ID that is unique within the host's own package. This ID remains persistent + <li><strong>App Widget Host</strong>— + The {@link android.appwidget.AppWidgetHost} provides the interaction +with the AppWidget service for apps, like the home screen, that want to embed +app widgets in their UI. An {@link android.appwidget.AppWidgetHost} must have +an ID that is unique within the host's own package. This ID remains persistent across all uses of the host. The ID is typically a hard-coded value that you assign in your application.</li> - + <li><strong>App Widget ID</strong>— - Each app widget instance is assigned a unique ID at the time of binding -(see {@link android.appwidget.AppWidgetManager#bindAppWidgetIdIfAllowed bindAppWidgetIdIfAllowed()}, -discussed in more detail in <a href="#binding">Binding app widgets</a>). -The unique ID is obtained by the host using {@link android.appwidget.AppWidgetHost#allocateAppWidgetId() allocateAppWidgetId()}. This ID is persistent across the lifetime of the widget, -that is, until it is deleted from the host. Any host-specific state (such as the -size and location of the widget) should be persisted by the hosting package and + Each app widget instance is assigned a unique ID at the time of binding +(see {@link android.appwidget.AppWidgetManager#bindAppWidgetIdIfAllowed bindAppWidgetIdIfAllowed()}, +discussed in more detail in <a href="#binding">Binding app widgets</a>). +The unique ID is obtained by the host using {@link android.appwidget.AppWidgetHost#allocateAppWidgetId() allocateAppWidgetId()}. This ID is persistent across the lifetime of the widget, +that is, until it is deleted from the host. Any host-specific state (such as the +size and location of the widget) should be persisted by the hosting package and associated with the app widget ID. </li> - - <li><strong>App Widget Host View</strong>— - {@link android.appwidget.AppWidgetHostView} can be thought of as a frame -that the widget is wrapped in whenever it needs to be displayed. An app widget -is assigned to an {@link android.appwidget.AppWidgetHostView} every time the + + <li><strong>App Widget Host View</strong>— + {@link android.appwidget.AppWidgetHostView} can be thought of as a frame +that the widget is wrapped in whenever it needs to be displayed. An app widget +is assigned to an {@link android.appwidget.AppWidgetHostView} every time the widget is inflated by the host. </li> <li><strong>Options Bundle</strong>— -The {@link android.appwidget.AppWidgetHost} uses the options bundle to communicate -information to the {@link android.appwidget.AppWidgetProvider} about how the -widget is being displayed (for example, size range, and whether the widget is on -a lockscreen or the home screen). This information allows the -{@link android.appwidget.AppWidgetProvider} to tailor the widget's contents +The {@link android.appwidget.AppWidgetHost} uses the options bundle to communicate +information to the {@link android.appwidget.AppWidgetProvider} about how the +widget is being displayed (for example, size range, and whether the widget is on +a lockscreen or the home screen). This information allows the +{@link android.appwidget.AppWidgetProvider} to tailor the widget's contents and appearance based on how and where it is displayed. -You use +You use {@link android.appwidget.AppWidgetHostView#updateAppWidgetOptions(android.os.Bundle) updateAppWidgetOptions()} -and +and {@link android.appwidget.AppWidgetHostView#updateAppWidgetSize updateAppWidgetSize()} -to modify an app widget's -bundle. Both of these methods trigger a callback to the +to modify an app widget's +bundle. Both of these methods trigger a callback to the {@link android.appwidget.AppWidgetProvider}.</p></li> </ul> @@ -98,15 +98,15 @@ app is running on.</p> <h3 id="binding-pre">Binding app widgets on Android 4.0 and lower</h3> -<p>On devices running Android version 4.0 and lower, users add app widgets -via a system activity that allows users to select a widget. This implicitly -does a permission check—that is, by adding the app widget, the user is -implicitly granting permission to your app to add app widgets to the host. -Here is an example that illustrates -this approach, taken from the original -<a href="https://android.googlesource.com/platform/packages/apps/Launcher/+/master/src/com/android/launcher/Launcher.java">Launcher</a>. In this snippet, an event handler invokes -{@link android.app.Activity#startActivityForResult(android.content.Intent,int) startActivityForResult()} -with the request code {@code REQUEST_PICK_APPWIDGET} in response to a +<p>On devices running Android version 4.0 and lower, users add app widgets +via a system activity that allows users to select a widget. This implicitly +does a permission check—that is, by adding the app widget, the user is +implicitly granting permission to your app to add app widgets to the host. +Here is an example that illustrates +this approach, taken from the original +<a href="https://android.googlesource.com/platform/packages/apps/Launcher/+/master/src/com/android/launcher/Launcher.java">Launcher</a>. In this snippet, an event handler invokes +{@link android.app.Activity#startActivityForResult(android.content.Intent,int) startActivityForResult()} +with the request code {@code REQUEST_PICK_APPWIDGET} in response to a user action:</p> <pre> @@ -118,9 +118,9 @@ public void onClick(DialogInterface dialog, int which) { ... case AddAdapter.ITEM_APPWIDGET: { ... - int appWidgetId = + int appWidgetId = Launcher.this.mAppWidgetHost.allocateAppWidgetId(); - Intent pickIntent = + Intent pickIntent = new Intent(AppWidgetManager.ACTION_APPWIDGET_PICK); pickIntent.putExtra (AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId); @@ -135,7 +135,7 @@ public void onClick(DialogInterface dialog, int which) { app widget to your activity. In the following example, the activity responds by calling {@code addAppWidget()} to add the app widget:</p> -<pre>public final class Launcher extends Activity +<pre>public final class Launcher extends Activity implements View.OnClickListener, OnLongClickListener { ... @Override @@ -152,7 +152,7 @@ by calling {@code addAppWidget()} to add the app widget:</p> completeAddAppWidget(data, mAddItemCellInfo, !mDesktopLocked); break; } - } + } ... } }</pre> @@ -164,7 +164,7 @@ needs to be configured before it's added:</p> int appWidgetId = data.getIntExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, -1); String customWidget = data.getStringExtra(EXTRA_CUSTOM_WIDGET); - AppWidgetProviderInfo appWidget = + AppWidgetProviderInfo appWidget = mAppWidgetManager.getAppWidgetInfo(appWidgetId); if (appWidget.configure != null) { @@ -183,7 +183,7 @@ see <a href="{@docRoot}guide/topics/appwidgets/index.html#Configuring">Creating App Widget Configuration Activity</a>.</p> <p>Once the app widget is ready, the next step is to do the -actual work of adding it to the workspace. The +actual work of adding it to the workspace. The <a href="https://android.googlesource.com/platform/packages/apps/Launcher/+/master/src/com/android/launcher/Launcher.java">original Launcher</a> uses a method called {@code completeAddAppWidget()} to do this.</p> @@ -201,12 +201,12 @@ binding. To use this improved process, your app must declare the <p>But this is just the first step. At runtime the user must explicitly grant permission to your app to allow it to add app widgets to the host. To test whether your app has permission to add the widget, -you use the -{@link android.appwidget.AppWidgetManager#bindAppWidgetIdIfAllowed bindAppWidgetIdIfAllowed()} -method. +you use the +{@link android.appwidget.AppWidgetManager#bindAppWidgetIdIfAllowed bindAppWidgetIdIfAllowed()} +method. If {@link android.appwidget.AppWidgetManager#bindAppWidgetIdIfAllowed bindAppWidgetIdIfAllowed()} returns {@code false}, your app must display a dialog prompting the -user to grant permission +user to grant permission ("allow" or "always allow," to cover all future app widget additions). This snippet gives an example of how to display the dialog:</p> @@ -218,9 +218,9 @@ intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options); startActivityForResult(intent, REQUEST_BIND_APPWIDGET); </pre> -<p>The host also has to check whether the user added +<p>The host also has to check whether the user added an app widget that needs configuration. For more discussion of this topic, -see +see <a href="{@docRoot}guide/topics/appwidgets/index.html#Configuring">Creating an App Widget Configuration Activity</a>.</p> @@ -229,23 +229,23 @@ an App Widget Configuration Activity</a>.</p> <div class="sidebox-wrapper"> <div class="sidebox"> <h2>What Version are You Targeting?</h2> - <p>The approach you use in implementing your host should depend on what Android version -you're targeting. Many of the features described in this section were introduced + <p>The approach you use in implementing your host should depend on what Android version +you're targeting. Many of the features described in this section were introduced in 3.0 or later. For example:</p> <ul> <li>Android 3.0 (API Level 11) introduces auto-advance behavior for widgets.</li> <li>Android 3.1 (API Level 12) introduces the ability to resize widgets.</li> <li>Android 4.0 (API Level 15) introduces a change in padding policy that -puts the responsibility on the +puts the responsibility on the host to manage padding.</li> <li>Android 4.1 (API Level 16) adds an API that allows the widget provider to get more detailed information about the environment in which its widget instances are being hosted.</li> -<li>Android 4.2 (API Level 17) introduces the options bundle and the -{@link android.appwidget.AppWidgetManager#bindAppWidgetIdIfAllowed(int,android.content.ComponentName,android.os.Bundle) bindAppWidgetIdIfAllowed()} +<li>Android 4.2 (API Level 17) introduces the options bundle and the +{@link android.appwidget.AppWidgetManager#bindAppWidgetIdIfAllowed(int,android.content.ComponentName,android.os.Bundle) bindAppWidgetIdIfAllowed()} method. It also introduces lockscreen widgets.</li> </ul> -<p>If you are targeting earlier devices, refer to the original +<p>If you are targeting earlier devices, refer to the original <a href="https://android.googlesource.com/platform/packages/apps/Launcher/+/master/src/com/android/launcher/Launcher.java">Launcher</a> as an example. </div> </div> @@ -273,7 +273,7 @@ from the Configuration Activity</a>. This is a necessary step for many app widge they can be properly displayed.</li> <li>Every app widget specifies a minimum width and height in dps, as defined in the {@link android.appwidget.AppWidgetProviderInfo} metadata -(using {@link android.appwidget.AppWidgetProviderInfo#minWidth android:minWidth} and +(using {@link android.appwidget.AppWidgetProviderInfo#minWidth android:minWidth} and {@link android.appwidget.AppWidgetProviderInfo#minHeight android:minHeight}). Make sure that the widget is laid out with at least this many dps. For example, many hosts align icons and widgets in a grid. In this scenario, @@ -379,7 +379,7 @@ so it is not explicitly required to set this for a home screen host.</p> for your app—for example, if your host is a home screen, ensure that the {@link android.appwidget.AppWidgetProviderInfo#widgetCategory android:widgetCategory} -attribute in the +attribute in the {@link android.appwidget.AppWidgetProviderInfo} metadata includes the flag {@link android.appwidget.AppWidgetProviderInfo#WIDGET_CATEGORY_HOME_SCREEN}. Similarly, for the lockscreen, ensure that field includes the flag {@link android.appwidget.AppWidgetProviderInfo#WIDGET_CATEGORY_KEYGUARD}. For more diff --git a/docs/html/guide/topics/appwidgets/index.jd b/docs/html/guide/topics/appwidgets/index.jd index c9575e025f05..7d555ed2d8d8 100644 --- a/docs/html/guide/topics/appwidgets/index.jd +++ b/docs/html/guide/topics/appwidgets/index.jd @@ -4,7 +4,7 @@ page.tags=home,AppWidgetProvider <div id="qv-wrapper"> <div id="qv"> - + <h2>In this document</h2> <ol> <li><a href="#Basics">The Basics</a></li> @@ -21,7 +21,7 @@ Intents</a></li> Activity</a> <ol> <li><a href="#UpdatingFromTheConfiguration">Updating the App Widget -from +from the Configuration Activity</a></li> </ol> </li> @@ -33,7 +33,7 @@ from collections </a></li> <li><a href="#fresh">Keeping Collection Data Fresh</a></li> - </ol> + </ol> </li> </ol> @@ -50,10 +50,10 @@ collections <p>App Widgets are miniature application views that can be embedded in other applications (such as the Home screen) and receive periodic updates. These views are -referred +referred to as Widgets in the user interface, and you can publish one with an App Widget provider. An application component -that is +that is able to hold other App Widgets is called an App Widget host. The screenshot below shows the Music App Widget.</p> @@ -85,14 +85,14 @@ update frequency, <dd>Defines the basic methods that allow you to programmatically interface with the App Widget, based on broadcast events. Through it, you will receive broadcasts when the -App Widget is updated, +App Widget is updated, enabled, disabled and deleted.</dd> <dt>View layout</dt> <dd>Defines the initial layout for the App Widget, defined in XML.</dd> </dl> <p>Additionally, you can implement an App Widget configuration Activity. This is -an optional +an optional {@link android.app.Activity} that launches when the user adds your App Widget and allows him or her to modify App Widget settings at create-time.</p> @@ -117,7 +117,7 @@ application's </pre> <p>The <code><receiver></code> element requires the -<code>android:name</code> +<code>android:name</code> attribute, which specifies the {@link android.appwidget.AppWidgetProvider} used by the App Widget.</p> @@ -133,7 +133,7 @@ automatically sends all other App Widget broadcasts to the AppWidgetProvider as necessary.</p> <p>The <code><meta-data></code> element specifies the -{@link android.appwidget.AppWidgetProviderInfo} resource and requires the +{@link android.appwidget.AppWidgetProviderInfo} resource and requires the following attributes:</p> <ul> <li><code>android:name</code> - Specifies the metadata name. Use @@ -141,21 +141,21 @@ following attributes:</p> to identify the data as the {@link android.appwidget.AppWidgetProviderInfo} descriptor.</li> <li><code>android:resource</code> - Specifies the {@link -android.appwidget.AppWidgetProviderInfo} +android.appwidget.AppWidgetProviderInfo} resource location.</li> </ul> <h2 id="MetaData">Adding the AppWidgetProviderInfo Metadata</h2> -<p>The {@link android.appwidget.AppWidgetProviderInfo} defines the essential +<p>The {@link android.appwidget.AppWidgetProviderInfo} defines the essential qualities of an App Widget, such as its minimum layout dimensions, its initial layout resource, how often to update the App Widget, and (optionally) a configuration Activity to launch at create-time. Define the AppWidgetProviderInfo object in an XML resource using a single <code><appwidget-provider></code> element and save it in the project's -<code>res/xml/</code> +<code>res/xml/</code> folder.</p> <p>For example:</p> @@ -167,7 +167,7 @@ folder.</p> android:updatePeriodMillis="86400000" android:previewImage="@drawable/preview" android:initialLayout="@layout/example_appwidget" - android:configure="com.example.android.ExampleAppWidgetConfigure" + android:configure="com.example.android.ExampleAppWidgetConfigure" android:resizeMode="horizontal|vertical" android:widgetCategory="home_screen"> </appwidget-provider> @@ -206,33 +206,33 @@ folder.</p> <li>The <code>updatePeriodMillis</code> attribute defines how often the App Widget framework should request an update from the {@link -android.appwidget.AppWidgetProvider} by calling the -{@link android.appwidget.AppWidgetProvider#onUpdate(android.content.Context,android.appwidget.AppWidgetManager,int[]) onUpdate()} +android.appwidget.AppWidgetProvider} by calling the +{@link android.appwidget.AppWidgetProvider#onUpdate(android.content.Context,android.appwidget.AppWidgetManager,int[]) onUpdate()} callback method. The actual update is not guaranteed to occur exactly on time with this value and we suggest updating as infrequently as possible—perhaps no more than once an hour to conserve the battery. You might also allow the user to adjust the frequency in a configuration—some people might want a stock ticker to update every 15 -minutes, or maybe only four times a day. +minutes, or maybe only four times a day. <p class="note"><strong>Note:</strong> If the device is asleep when it -is time for an update +is time for an update (as defined by <code>updatePeriodMillis</code>), then the device will -wake up in order +wake up in order to perform the update. If you don't update more than once per hour, this -probably won't +probably won't cause significant problems for the battery life. If, however, you need -to update more +to update more frequently and/or you do not need to update while the device is asleep, -then you can instead +then you can instead perform updates based on an alarm that will not wake the device. To do -so, set an alarm with +so, set an alarm with an Intent that your AppWidgetProvider receives, using the {@link -android.app.AlarmManager}. +android.app.AlarmManager}. Set the alarm type to either {@link -android.app.AlarmManager#ELAPSED_REALTIME} or +android.app.AlarmManager#ELAPSED_REALTIME} or {@link android.app.AlarmManager#RTC}, which will only deliver the alarm when the device is awake. Then set -<code>updatePeriodMillis</code> to +<code>updatePeriodMillis</code> to zero (<code>"0"</code>).</p> </li> <li>The <code>initialLayout</code> attribute points to the layout resource @@ -244,7 +244,7 @@ android.app.Activity} to launch when Widget properties. This is optional (read <a href="#Configuring">Creating an App Widget Configuration Activity</a> below).</li> - + <li>The <code>previewImage</code> attribute specifies a preview of what the app widget will look like after it's configured, which the user sees when selecting the app widget. If not supplied, the user instead sees your @@ -255,7 +255,7 @@ using <code>previewImage</code>, see <a href="#preview">Setting a Preview Image</a>. Introduced in Android 3.0.</li> <li>The <code>autoAdvanceViewId</code> attribute specifies the view ID of the -app widget subview that should be auto-advanced by the widget's host. Introduced in Android 3.0.</li> +app widget subview that should be auto-advanced by the widget's host. Introduced in Android 3.0.</li> <li>The <code>resizeMode</code> attribute specifies the rules by which a widget can be resized. You use this attribute to make homescreen widgets @@ -264,7 +264,7 @@ widget to show its resize handles, then drag the horizontal and/or vertical handles to change the size on the layout grid. Values for the <code>resizeMode</code> attribute include "horizontal", "vertical", and "none". To declare a widget as resizeable horizontally and vertically, supply the value -"horizontal|vertical". Introduced in Android 3.1.</li> +"horizontal|vertical". Introduced in Android 3.1.</li> <li>The <code>minResizeHeight</code> attribute specifies the minimum height (in dps) to which the widget can be resized. This field has no effect if it is greater than {@code minHeight} or if @@ -296,7 +296,7 @@ View objects listed below, but before you begin designing your App Widget, please read and understand the <a href="{@docRoot}guide/practices/ui_guidelines/widget_design.html">App Widget -Design +Design Guidelines</a>.</p> <p>Creating the App Widget layout is simple if you're @@ -306,7 +306,7 @@ However, you must be aware that App Widget layouts are based on {@link android.widget.RemoteViews}, which do not support every kind of layout or view widget.</p> -<p>A RemoteViews object (and, consequently, an App Widget) can support the +<p>A RemoteViews object (and, consequently, an App Widget) can support the following layout classes:</p> <ul class="nolist"> @@ -334,7 +334,7 @@ following layout classes:</p> <p>Descendants of these classes are not supported.</p> -<p>RemoteViews also supports {@link android.view.ViewStub}, which is an invisible, zero-sized View you can use +<p>RemoteViews also supports {@link android.view.ViewStub}, which is an invisible, zero-sized View you can use to lazily inflate layout resources at runtime.</p> @@ -386,7 +386,7 @@ to lazily inflate layout resources at runtime.</p> <div class="sidebox-wrapper"> <div class="sidebox"> <p>You must declare your AppWidgetProvider class implementation as a -broadcast receiver +broadcast receiver using the <code><receiver></code> element in the AndroidManifest (see <a href="#Manifest">Declaring an App Widget in the Manifest</a> above).</p> </div> @@ -403,11 +403,11 @@ method calls:</p> <dl> <dt> - {@link android.appwidget.AppWidgetProvider#onUpdate(android.content.Context,android.appwidget.AppWidgetManager,int[]) onUpdate()} + {@link android.appwidget.AppWidgetProvider#onUpdate(android.content.Context,android.appwidget.AppWidgetManager,int[]) onUpdate()} </dt> <dd>This is called to update the App Widget at intervals defined by the <code>updatePeriodMillis</code> - attribute in the AppWidgetProviderInfo (see <a href="#MetaData">Adding the + attribute in the AppWidgetProviderInfo (see <a href="#MetaData">Adding the AppWidgetProviderInfo Metadata</a> above). This method is also called when the user adds the App Widget, so it should perform the essential setup, such as define event handlers for Views and start a temporary @@ -415,25 +415,25 @@ method calls:</p> configuration Activity, <strong>this method is not called</strong> when the user adds the App Widget, - but is called for the subsequent updates. It is the responsibility of the + but is called for the subsequent updates. It is the responsibility of the configuration Activity to perform the first update when configuration is done. (See <a href="#Configuring">Creating an App Widget Configuration -Activity</a> below.)</dd> +Activity</a> below.)</dd> <dt> - {@link android.appwidget.AppWidgetProvider#onAppWidgetOptionsChanged onAppWidgetOptionsChanged()} + {@link android.appwidget.AppWidgetProvider#onAppWidgetOptionsChanged onAppWidgetOptionsChanged()} </dt> <dd> This is called when the widget is first placed and any time the widget is resized. You can use this callback to show or hide content based on the widget's size ranges. You get the size ranges by calling {@link android.appwidget.AppWidgetManager#getAppWidgetOptions getAppWidgetOptions()}, which returns a {@link android.os.Bundle} that includes the following:<br /><br /> <ul> - <li>{@link android.appwidget.AppWidgetManager#OPTION_APPWIDGET_MIN_WIDTH}—Contains + <li>{@link android.appwidget.AppWidgetManager#OPTION_APPWIDGET_MIN_WIDTH}—Contains the lower bound on the current width, in dp units, of a widget instance.</li> - <li>{@link android.appwidget.AppWidgetManager#OPTION_APPWIDGET_MIN_HEIGHT}—Contains + <li>{@link android.appwidget.AppWidgetManager#OPTION_APPWIDGET_MIN_HEIGHT}—Contains the lower bound on the current height, in dp units, of a widget instance.</li> <li>{@link android.appwidget.AppWidgetManager#OPTION_APPWIDGET_MAX_WIDTH}—Contains the upper bound on the current width, in dp units, of a widget instance.</li> - <li>{@link android.appwidget.AppWidgetManager#OPTION_APPWIDGET_MAX_HEIGHT}—Contains + <li>{@link android.appwidget.AppWidgetManager#OPTION_APPWIDGET_MAX_HEIGHT}—Contains the upper bound on the current width, in dp units, of a widget instance.</li> </ul> @@ -444,34 +444,34 @@ This callback was introduced in API Level 16 (Android 4.1). If you implement thi host.</dd> <dt>{@link android.appwidget.AppWidgetProvider#onEnabled(Context)}</dt> <dd>This is called when an instance the App Widget is created for the first -time. For example, if the user +time. For example, if the user adds two instances of your App Widget, this is only called the first time. If you need to open a new database or perform other setup that only needs to -occur once - for all App Widget instances, then this is a good place to do it.</dd> +occur once + for all App Widget instances, then this is a good place to do it.</dd> <dt>{@link android.appwidget.AppWidgetProvider#onDisabled(Context)}</dt> <dd>This is called when the last instance of your App Widget is deleted from -the App Widget host. - This is where you should clean up any work done in - {@link android.appwidget.AppWidgetProvider#onEnabled(Context)}, - such as delete a temporary database.</dd> +the App Widget host. + This is where you should clean up any work done in + {@link android.appwidget.AppWidgetProvider#onEnabled(Context)}, + such as delete a temporary database.</dd> <dt>{@link android.appwidget.AppWidgetProvider#onReceive(Context,Intent)}</dt> <dd>This is called for every broadcast and before each of the above callback methods. You normally don't need to implement this method because the default -AppWidgetProvider - implementation filters all App Widget broadcasts and calls the above - methods as appropriate.</dd> +AppWidgetProvider + implementation filters all App Widget broadcasts and calls the above + methods as appropriate.</dd> </dl> -<p>The most important AppWidgetProvider callback is -{@link android.appwidget.AppWidgetProvider#onUpdate(android.content.Context, android.appwidget.AppWidgetManager, int[]) onUpdate()} +<p>The most important AppWidgetProvider callback is +{@link android.appwidget.AppWidgetProvider#onUpdate(android.content.Context, android.appwidget.AppWidgetManager, int[]) onUpdate()} because it is called when each App Widget is added to a host (unless you use a configuration Activity). If your App Widget accepts any user interaction events, then you need to register the event handlers in this callback. If your App Widget doesn't create temporary -files or databases, or perform other work that requires clean-up, then -{@link android.appwidget.AppWidgetProvider#onUpdate(android.content.Context, android.appwidget.AppWidgetManager, int[]) onUpdate()} +files or databases, or perform other work that requires clean-up, then +{@link android.appwidget.AppWidgetProvider#onUpdate(android.content.Context, android.appwidget.AppWidgetManager, int[]) onUpdate()} may be the only callback method you need to define. For example, if you want an App Widget with a button that launches an Activity when clicked, you could use the following @@ -503,9 +503,9 @@ public class ExampleAppWidgetProvider extends AppWidgetProvider { } </pre> -<p>This AppWidgetProvider defines only the +<p>This AppWidgetProvider defines only the {@link -android.appwidget.AppWidgetProvider#onUpdate(android.content.Context, android.appwidget.AppWidgetManager, int[]) onUpdate()} +android.appwidget.AppWidgetProvider#onUpdate(android.content.Context, android.appwidget.AppWidgetManager, int[]) onUpdate()} method for the purpose of defining a {@link android.app.PendingIntent} that launches an {@link android.app.Activity} and attaching it to the App Widget's button with {@link @@ -528,8 +528,8 @@ running after the callback methods return (see {@link android.content.BroadcastReceiver} for information about the broadcast lifecycle). If your App Widget setup process can take several seconds (perhaps while performing web requests) and you require that your process continues, -consider starting a {@link android.app.Service} in the -{@link android.appwidget.AppWidgetProvider#onUpdate(Context,AppWidgetManager,int[]) onUpdate()} +consider starting a {@link android.app.Service} in the +{@link android.appwidget.AppWidgetProvider#onUpdate(Context,AppWidgetManager,int[]) onUpdate()} 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/responsiveness.html">Application @@ -537,7 +537,7 @@ 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 android.app.Service}.</p> -<p>Also see the <a +<p>Also see the <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/appwidget/ExampleAppWidgetProvider.html">ExampleAppWidgetProvider.java</a> sample class.</p> @@ -546,9 +546,9 @@ sample class.</p> <p>{@link android.appwidget.AppWidgetProvider} is just a convenience class. If you would like -to receive the App Widget broadcasts directly, you can implement your own -{@link android.content.BroadcastReceiver} or override the -{@link android.appwidget.AppWidgetProvider#onReceive(Context,Intent)} callback. +to receive the App Widget broadcasts directly, you can implement your own +{@link android.content.BroadcastReceiver} or override the +{@link android.appwidget.AppWidgetProvider#onReceive(Context,Intent)} callback. The Intents you need to care about are as follows:</p> <ul> <li>{@link android.appwidget.AppWidgetManager#ACTION_APPWIDGET_UPDATE}</li> @@ -565,11 +565,11 @@ The Intents you need to care about are as follows:</p> <p>If you would like the user to configure settings when he or she adds a new App Widget, you can create an App Widget configuration Activity. This {@link -android.app.Activity} +android.app.Activity} will be automatically launched by the App Widget host and allows the user to configure available settings for the App Widget at create-time, such as the App Widget -color, size, +color, size, update period or other functionality settings.</p> <p>The configuration Activity should be declared as a normal Activity in the @@ -588,8 +588,8 @@ so the Activity needs to accept this Intent. For example:</p> </pre> <p>Also, the Activity must be declared in the AppWidgetProviderInfo XML file, -with the -<code>android:configure</code> attribute (see <a href="#MetaData">Adding +with the +<code>android:configure</code> attribute (see <a href="#MetaData">Adding the AppWidgetProviderInfo Metadata</a> above). For example, the configuration Activity can be declared like this:</p> @@ -597,13 +597,13 @@ can be declared like this:</p> <pre> <appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android" ... - android:configure="com.example.android.ExampleAppWidgetConfigure" + android:configure="com.example.android.ExampleAppWidgetConfigure" ... > </appwidget-provider> </pre> <p>Notice that the Activity is declared with a fully-qualified namespace, -because +because it will be referenced from outside your package scope.</p> <p>That's all you need to get started with a configuration Activity. Now all you @@ -612,21 +612,21 @@ Activity. There are, however, two important things to remember when you implement the Activity:</p> <ul> <li>The App Widget host calls the configuration Activity and the configuration -Activity should always +Activity should always return a result. The result should include the App Widget ID passed by the Intent that launched the Activity (saved in the Intent extras as {@link android.appwidget.AppWidgetManager#EXTRA_APPWIDGET_ID}).</li> - <li>The - {@link android.appwidget.AppWidgetProvider#onUpdate(Context,AppWidgetManager,int[]) onUpdate()} + <li>The + {@link android.appwidget.AppWidgetProvider#onUpdate(Context,AppWidgetManager,int[]) onUpdate()} method <strong>will not be called</strong> when the App Widget is created (the system will not send the ACTION_APPWIDGET_UPDATE broadcast when a configuration Activity is launched). It is the responsibility of the configuration Activity to -request an update from the - AppWidgetManager when the App Widget is first created. However, -{@link android.appwidget.AppWidgetProvider#onUpdate(Context,AppWidgetManager,int[]) onUpdate()} +request an update from the + AppWidgetManager when the App Widget is first created. However, +{@link android.appwidget.AppWidgetProvider#onUpdate(Context,AppWidgetManager,int[]) onUpdate()} will be called for subsequent updates—it is only skipped the first time.</li> </ul> @@ -641,8 +641,8 @@ configuration Activity</h3> <p>When an App Widget uses a configuration Activity, it is the responsibility of the Activity -to update the App Widget when configuration is complete. -You can do so by requesting an update directly from the +to update the App Widget when configuration is complete. +You can do so by requesting an update directly from the {@link android.appwidget.AppWidgetManager}.</p> <p>Here's a summary of the procedure to properly update the App Widget and close @@ -655,7 +655,7 @@ Intent intent = getIntent(); Bundle extras = intent.getExtras(); if (extras != null) { mAppWidgetId = extras.getInt( - AppWidgetManager.EXTRA_APPWIDGET_ID, + AppWidgetManager.EXTRA_APPWIDGET_ID, AppWidgetManager.INVALID_APPWIDGET_ID); } </pre> @@ -696,7 +696,7 @@ reaching the end, the App Widget host is notified that the configuration was cancelled and the App Widget will not be added.</p> -<p>See the <a +<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> @@ -708,7 +708,7 @@ sample class in ApiDemos for an example.</p> android.appwidget.AppWidgetProviderInfo#previewImage} field, which specifies a preview of what the app widget looks like. This preview is shown to the user from the widget picker. If this field is not supplied, the app widget's icon is used for -the preview.</p> +the preview.</p> <p>This is how you specify this setting in XML:</p> @@ -742,12 +742,12 @@ list. For an example, see the Gmail app widget. </dd> <dt>{@link android.widget.GridView}</dt> <dd>A view that shows items in two-dimensional scrolling grid. For an example, see the Bookmarks app -widget.</dd> +widget.</dd> <dt>{@link android.widget.StackView}</dt> <dd>A stacked card view (kind of like a rolodex), where the user can flick the front card up/down to see the previous/next card, respectively. Examples include -the YouTube and Books app widgets. </dd> +the YouTube and Books app widgets. </dd> <dt>{@link android.widget.AdapterViewFlipper}</dt> <dd>An adapter-backed simple {@link @@ -764,7 +764,7 @@ must include extra architecture to support their use in app widgets. In the context of an app widget, the {@link android.widget.Adapter} is replaced by a {@link android.widget.RemoteViewsService.RemoteViewsFactory RemoteViewsFactory}, which is simply a thin wrapper around the {@link android.widget.Adapter} -interface. +interface. When requested for a specific item in the collection, the {@link android.widget.RemoteViewsService.RemoteViewsFactory RemoteViewsFactory} creates @@ -782,7 +782,7 @@ interface for an adapter between a collection view (such as {@link android.widget.ListView}, {@link android.widget.GridView}, and so on) and the underlying data for that view. From the <a href="{@docRoot}resources/samples/StackWidget/index.html">StackView Widget -sample</a>, here is an example of the boilerplate code you use to implement +sample</a>, here is an example of the boilerplate code you use to implement this service and interface: </p> @@ -813,13 +813,13 @@ sample</a>:</p> <p>This sample consists of a stack of 10 views, which display the values <code>"0!"</code> through <code>"9!"</code> The sample -app widget has these primary behaviors:</p> +app widget has these primary behaviors:</p> <ul> <li>The user can vertically fling the top view in the app widget to display the next or previous view. This is a built-in StackView -behavior.</li> +behavior.</li> <li>Without any user interaction, the app widget automatically advances through @@ -828,17 +828,17 @@ its views in sequence, like a slide show. This is due to the setting <code>res/xml/stackwidgetinfo.xml</code> file. This setting applies to the view ID, which in this case is the view ID of the stack view.</li> - + <li>If the user touches the top view, the app widget displays the {@link android.widget.Toast} message "Touched view <em>n</em>," where <em>n</em> is the index (position) of the touched view. For more discussion of -how this is implemented, see +how this is implemented, see <a href="#behavior">Adding behavior to individual items</a>.</li> </ul> <h3 id="implementing_collections">Implementing app widgets with collections</h3> -<p>To implement an app widget with collections, you follow the same basic steps +<p>To implement an app widget with collections, you follow the same basic steps you would use to implement any app widget. The following sections describe the additional steps you need to perform to implement an app widget with collections.</p> @@ -940,7 +940,7 @@ collection:</p> int[] appWidgetIds) { // update each of the app widgets with the remote adapter for (int i = 0; i < appWidgetIds.length; ++i) { - + // Set up the intent that starts the StackViewService, which will // provide the views for this collection. Intent intent = new Intent(context, StackWidgetService.class); @@ -949,13 +949,13 @@ int[] appWidgetIds) { intent.setData(Uri.parse(intent.toUri(Intent.URI_INTENT_SCHEME))); // Instantiate the RemoteViews object for the app widget layout. RemoteViews rv = new RemoteViews(context.getPackageName(), R.layout.widget_layout); - // Set up the RemoteViews object to use a RemoteViews adapter. + // Set up the RemoteViews object to use a RemoteViews adapter. // This adapter connects // to a RemoteViewsService through the specified intent. // This is how you populate the data. rv.setRemoteAdapter(appWidgetIds[i], R.id.stack_view, intent); - - // The empty view is displayed when the collection has no items. + + // The empty view is displayed when the collection has no items. // It should be in the same layout used to instantiate the RemoteViews // object above. rv.setEmptyView(R.id.stack_view, R.id.empty_view); @@ -963,12 +963,12 @@ int[] appWidgetIds) { // // Do additional processing specific to this app widget... // - - appWidgetManager.updateAppWidget(appWidgetIds[i], rv); + + appWidgetManager.updateAppWidget(appWidgetIds[i], rv); } super.onUpdate(context, appWidgetManager, appWidgetIds); }</pre> - + <h4>RemoteViewsService class</h4> <div class="sidebox-wrapper"> @@ -984,7 +984,7 @@ lifecycle.</p> </div> <p>As described above, your {@link android.widget.RemoteViewsService} subclass provides the {@link android.widget.RemoteViewsService.RemoteViewsFactory -RemoteViewsFactory} used to populate the remote collection view.</p> +RemoteViewsFactory} used to populate the remote collection view.</p> <p>Specifically, you need to perform these steps:</p> @@ -993,7 +993,7 @@ perform these steps:</p> <li>Subclass {@link android.widget.RemoteViewsService}. {@link android.widget.RemoteViewsService} is the service through which a remote adapter can request {@link android.widget.RemoteViews}. </li> - + <li>In your {@link android.widget.RemoteViewsService} subclass, include a class that implements the {@link android.widget.RemoteViewsService.RemoteViewsFactory RemoteViewsFactory} @@ -1027,12 +1027,12 @@ functions as an adapter to glue the data to the remote collection view.</p> <p>The two most important methods you need to implement for your {@link android.widget.RemoteViewsService.RemoteViewsFactory RemoteViewsFactory} -subclass are +subclass are {@link android.widget.RemoteViewsService.RemoteViewsFactory#onCreate() onCreate()} and {@link android.widget.RemoteViewsService.RemoteViewsFactory#getViewAt(int) getViewAt()} -.</p> +.</p> <p>The system calls {@link android.widget.RemoteViewsService.RemoteViewsFactory#onCreate() onCreate()} when @@ -1047,7 +1047,7 @@ array and the text they contain is displayed </p> <p>Here is an excerpt from the <a href="{@docRoot}resources/samples/StackWidget/index.html">StackView Widget</a> -sample's +sample's {@link android.widget.RemoteViewsService.RemoteViewsFactory RemoteViewsFactory} implementation that shows portions of the {@link android.widget.RemoteViewsService.RemoteViewsFactory#onCreate() onCreate()} @@ -1081,7 +1081,7 @@ RemoteViewsService.RemoteViewsFactory { RemoteViewsFactory} method {@link android.widget.RemoteViewsService.RemoteViewsFactory#getViewAt(int) getViewAt()} returns a {@link android.widget.RemoteViews} object corresponding to the data at -the specified <code>position</code> in the data set. Here is an excerpt from +the specified <code>position</code> in the data set. Here is an excerpt from the <a href="http://developer.android.com/resources/samples/StackWidget/index.html"> StackView Widget</a> sample's {@link @@ -1089,8 +1089,8 @@ android.widget.RemoteViewsService.RemoteViewsFactory RemoteViewsFactory} implementation:</p> <pre>public RemoteViews getViewAt(int position) { - - // Construct a remote views item based on the app widget item XML file, + + // Construct a remote views item based on the app widget item XML file, // and set the text based on the position. RemoteViews rv = new RemoteViews(mContext.getPackageName(), R.layout.widget_item); rv.setTextViewText(R.id.widget_item, mWidgetItems.get(position).text); @@ -1104,7 +1104,7 @@ implementation:</p> <p>The above sections show you how to bind your data to your app widget collection. But what if you want to add dynamic behavior to the individual items -in your collection view?</p> +in your collection view?</p> <p> As described in <a href="#AppWidgetProvider">Using the AppWidgetProvider Class</a>, you normally use {@link @@ -1122,7 +1122,7 @@ android.widget.RemoteViews#setOnClickFillInIntent(int, android.content.Intent) setOnClickFillInIntent()}. This entails setting up up a pending intent template for your collection view, and then setting a fill-in intent on each item in the collection via your {@link android.widget.RemoteViewsService.RemoteViewsFactory -RemoteViewsFactory}.</p> +RemoteViewsFactory}.</p> <p>This section uses the <a href="{@docRoot}resources/samples/StackWidget/index.html">StackView Widget sample</a> to describe how to add behavior to individual items. In the <a @@ -1138,7 +1138,7 @@ android.appwidget.AppWidgetProvider} subclass) creates a pending intent that has a custom action called <code>TOAST_ACTION</code>.</li> <li>When the user touches a view, the intent is fired and it broadcasts <code>TOAST_ACTION</code>.</li> - + <li>This broadcast is intercepted by the <code>StackWidgetProvider</code>'s {@link android.appwidget.AppWidgetProvider#onReceive(android.content.Context, android.content.Intent) onReceive()} method, and the app widget displays the @@ -1154,7 +1154,7 @@ href="{@docRoot}resources/samples/StackWidget/index.html">StackView Widget sample</a> uses a broadcast, but typically an app widget would simply launch an activity in a scenario like this one.</p> -<h5>Setting up the pending intent template</h5> +<h5>Setting up the pending intent template</h5> <p>The <code>StackWidgetProvider</code> ({@link android.appwidget.AppWidgetProvider} subclass) sets up a pending intent. @@ -1162,7 +1162,7 @@ Individuals items of a collection cannot set up their own pending intents. Instead, the collection as a whole sets up a pending intent template, and the individual items set a fill-in intent to create unique behavior on an item-by-item -basis.</p> +basis.</p> <p>This class also receives the broadcast that is sent when the user touches a view. It processes this event in its {@link @@ -1179,7 +1179,7 @@ message for the current view.</p>   ... // Called when the BroadcastReceiver receives an Intent broadcast. - // Checks to see whether the intent's action is TOAST_ACTION. If it is, the app widget + // Checks to see whether the intent's action is TOAST_ACTION. If it is, the app widget // displays a Toast message for the current item. @Override public void onReceive(Context context, Intent intent) { @@ -1192,12 +1192,12 @@ message for the current view.</p>   }   super.onReceive(context, intent); } - + @Override public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) { // update each of the app widgets with the remote adapter   for (int i = 0; i < appWidgetIds.length; ++i) { - +   // Sets up the intent that points to the StackViewService that will   // provide the views for this collection.   Intent intent = new Intent(context, StackWidgetService.class); @@ -1207,7 +1207,7 @@ message for the current view.</p>   intent.setData(Uri.parse(intent.toUri(Intent.URI_INTENT_SCHEME)));   RemoteViews rv = new RemoteViews(context.getPackageName(), R.layout.widget_layout);   rv.setRemoteAdapter(appWidgetIds[i], R.id.stack_view, intent); - +   // The empty view is displayed when the collection has no items. It should be a sibling   // of the collection view.   rv.setEmptyView(R.id.stack_view, R.id.empty_view); @@ -1227,13 +1227,13 @@ message for the current view.</p>   PendingIntent toastPendingIntent = PendingIntent.getBroadcast(context, 0, toastIntent,   PendingIntent.FLAG_UPDATE_CURRENT);   rv.setPendingIntentTemplate(R.id.stack_view, toastPendingIntent); - +   appWidgetManager.updateAppWidget(appWidgetIds[i], rv); } super.onUpdate(context, appWidgetManager, appWidgetIds); } }</pre> - + <h5><strong>Setting the fill-in Intent</strong></h5> <p>Your {@link android.widget.RemoteViewsService.RemoteViewsFactory @@ -1274,17 +1274,17 @@ class StackRemoteViewsFactory implements RemoteViewsService.RemoteViewsFactory {     ...   }   ... - - // Given the position (index) of a WidgetItem in the array, use the item's text value in + + // Given the position (index) of a WidgetItem in the array, use the item's text value in // combination with the app widget item XML file to construct a RemoteViews object.   public RemoteViews getViewAt(int position) {     // position will always range from 0 to getCount() - 1. - +     // Construct a RemoteViews item based on the app widget item XML file, and set the     // text based on the position.     RemoteViews rv = new RemoteViews(mContext.getPackageName(), R.layout.widget_item);     rv.setTextViewText(R.id.widget_item, mWidgetItems.get(position).text); - +     // Next, set a fill-intent, which will be used to fill in the pending intent template     // that is set on the collection view in StackWidgetProvider.     Bundle extras = new Bundle(); @@ -1294,9 +1294,9 @@ class StackRemoteViewsFactory implements RemoteViewsService.RemoteViewsFactory { // Make it possible to distinguish the individual on-click // action of a given item   rv.setOnClickFillInIntent(R.id.widget_item, fillInIntent); - +   ... - +   // Return the RemoteViews object.   return rv; } diff --git a/docs/html/guide/topics/connectivity/bluetooth-le.jd b/docs/html/guide/topics/connectivity/bluetooth-le.jd index 3d606863052a..ba742eeef8a2 100644 --- a/docs/html/guide/topics/connectivity/bluetooth-le.jd +++ b/docs/html/guide/topics/connectivity/bluetooth-le.jd @@ -171,7 +171,7 @@ include the following in your app's manifest:</p> </pre> <p>However, if you want to make your app available to devices that don't support BLE, -you should still include this element in your app's manifest, but set {@code required="false"}. +you should still include this element in your app's manifest, but set {@code required="false"}. Then at run-time you can determine BLE availability by using {@link android.content.pm.PackageManager#hasSystemFeature PackageManager.hasSystemFeature()}: diff --git a/docs/html/guide/topics/connectivity/bluetooth.jd b/docs/html/guide/topics/connectivity/bluetooth.jd index 96008c5c5701..07fcd09a751c 100644 --- a/docs/html/guide/topics/connectivity/bluetooth.jd +++ b/docs/html/guide/topics/connectivity/bluetooth.jd @@ -4,55 +4,55 @@ page.tags=wireless,bluetoothadapter,bluetoothdevice <div id="qv-wrapper"> <div id="qv"> - + <h2>In this document</h2> - <ol> + <ol> <li><a href="#TheBasics">The Basics</a></li> <li><a href="#Permissions">Bluetooth Permissions</a></li> - <li><a href="#SettingUp">Setting Up Bluetooth</a></li> - <li><a href="#FindingDevices">Finding Devices</a> - <ol> - <li><a href="#QueryingPairedDevices">Querying paired devices</a></li> - <li><a href="#DiscoveringDevices">Discovering devices</a></li> - </ol></li> - <li><a href="#ConnectingDevices">Connecting Devices</a> - <ol> - <li><a href="#ConnectingAsAServer">Connecting as a server</a></li> - <li><a href="#ConnectingAsAClient">Connecting as a client</a></li> - </ol></li> + <li><a href="#SettingUp">Setting Up Bluetooth</a></li> + <li><a href="#FindingDevices">Finding Devices</a> + <ol> + <li><a href="#QueryingPairedDevices">Querying paired devices</a></li> + <li><a href="#DiscoveringDevices">Discovering devices</a></li> + </ol></li> + <li><a href="#ConnectingDevices">Connecting Devices</a> + <ol> + <li><a href="#ConnectingAsAServer">Connecting as a server</a></li> + <li><a href="#ConnectingAsAClient">Connecting as a client</a></li> + </ol></li> <li><a href="#ManagingAConnection">Managing a Connection</a></li> - <li><a href="#Profiles">Working with Profiles</a> + <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> - - <h2>Key classes</h2> - <ol> - <li>{@link android.bluetooth.BluetoothAdapter}</li> - <li>{@link android.bluetooth.BluetoothDevice}</li> - <li>{@link android.bluetooth.BluetoothSocket}</li> - <li>{@link android.bluetooth.BluetoothServerSocket}</li> - </ol> - - <h2>Related samples</h2> - <ol> - <li><a href="{@docRoot}resources/samples/BluetoothChat/index.html">Bluetooth Chat</a></li> + </ol> + + <h2>Key classes</h2> + <ol> + <li>{@link android.bluetooth.BluetoothAdapter}</li> + <li>{@link android.bluetooth.BluetoothDevice}</li> + <li>{@link android.bluetooth.BluetoothSocket}</li> + <li>{@link android.bluetooth.BluetoothServerSocket}</li> + </ol> + + <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> -</div> - - + </ol> + +</div> +</div> + + <p>The Android platform includes support for the Bluetooth network stack, which allows a device to wirelessly exchange data with other Bluetooth devices. The application framework provides access to the Bluetooth functionality through the Android Bluetooth APIs. These APIs let applications wirelessly connect to other Bluetooth devices, enabling point-to-point and multipoint -wireless features.</p> - +wireless features.</p> + <p>Using the Bluetooth APIs, an Android application can perform the following:</p> <ul> @@ -75,14 +75,14 @@ see <a href="{@docRoot}guide/topics/connectivity/bluetooth-le.html">Bluetooth Lo <p>This document describes how to use the Android Bluetooth APIs to accomplish the four major tasks necessary to communicate using Bluetooth: setting up Bluetooth, finding devices that are either paired or available in the local -area, connecting devices, and transferring data between devices.</p> - +area, connecting devices, and transferring data between devices.</p> + <p>All of the Bluetooth APIs are available in the {@link android.bluetooth} package. Here's a summary of the classes and interfaces you will need to create Bluetooth -connections:</p> - -<dl> -<dt>{@link android.bluetooth.BluetoothAdapter}</dt> +connections:</p> + +<dl> +<dt>{@link android.bluetooth.BluetoothAdapter}</dt> <dd>Represents the local Bluetooth adapter (Bluetooth radio). The {@link android.bluetooth.BluetoothAdapter} is the entry-point for all Bluetooth interaction. Using this, @@ -90,49 +90,49 @@ you can discover other Bluetooth devices, query a list of bonded (paired) devices, instantiate a {@link android.bluetooth.BluetoothDevice} using a known MAC address, and create a {@link android.bluetooth.BluetoothServerSocket} to listen for communications -from other devices.</dd> - -<dt>{@link android.bluetooth.BluetoothDevice}</dt> +from other devices.</dd> + +<dt>{@link android.bluetooth.BluetoothDevice}</dt> <dd>Represents a remote Bluetooth device. Use this to request a connection with a remote device through a {@link android.bluetooth.BluetoothSocket} or query information about the -device such as its name, address, class, and bonding state.</dd> - -<dt>{@link android.bluetooth.BluetoothSocket}</dt> +device such as its name, address, class, and bonding state.</dd> + +<dt>{@link android.bluetooth.BluetoothSocket}</dt> <dd>Represents the interface for a Bluetooth socket (similar to a TCP {@link java.net.Socket}). This is the connection point that allows an application to exchange data with another Bluetooth device via InputStream -and OutputStream.</dd> - -<dt>{@link android.bluetooth.BluetoothServerSocket}</dt> +and OutputStream.</dd> + +<dt>{@link android.bluetooth.BluetoothServerSocket}</dt> <dd>Represents an open server socket that listens for incoming requests (similar to a TCP {@link java.net.ServerSocket}). In order to connect two Android devices, one device must open a server socket with this class. When a remote Bluetooth device makes a connection request to the this device, the {@link android.bluetooth.BluetoothServerSocket} will return a connected {@link android.bluetooth.BluetoothSocket} when the -connection is accepted.</dd> - -<dt>{@link android.bluetooth.BluetoothClass}</dt> +connection is accepted.</dd> + +<dt>{@link android.bluetooth.BluetoothClass}</dt> <dd>Describes the general characteristics and capabilities of a Bluetooth device. This is a read-only set of properties that define the device's major and minor device classes and its services. However, this does not reliably describe all Bluetooth profiles and services supported by the device, but is useful as a -hint to the device type.</dd> - +hint to the device type.</dd> + <dt>{@link android.bluetooth.BluetoothProfile}</dt> <dd>An interface that represents a Bluetooth profile. A <em>Bluetooth profile</em> is a wireless interface specification for Bluetooth-based communication between devices. An example is the Hands-Free profile. For more discussion of profiles, see <a -href="#Profiles">Working with Profiles</a></dd> +href="#Profiles">Working with Profiles</a></dd> <dt>{@link android.bluetooth.BluetoothHeadset}</dt> <dd>Provides support for Bluetooth headsets to be used with mobile phones. This includes both Bluetooth -Headset and Hands-Free (v1.5) profiles.</dd> +Headset and Hands-Free (v1.5) profiles.</dd> <dt>{@link android.bluetooth.BluetoothA2dp}</dt> <dd> Defines how high quality audio can be streamed from one device to another over a Bluetooth connection. -"A2DP" stands for Advanced Audio Distribution Profile.</dd> +"A2DP" stands for Advanced Audio Distribution Profile.</dd> <dt>{@link android.bluetooth.BluetoothHealth}</dt> <dd> Represents a Health Device Profile proxy that controls the Bluetooth service.</dd> @@ -146,23 +146,23 @@ 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 +<dd>Represents an application configuration that the Bluetooth Health third-party application registers to communicate with a remote Bluetooth health -device.</dd> +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> - -</dl> - - - - -<h2 id="Permissions">Bluetooth Permissions</h2> - + +</dl> + + + + +<h2 id="Permissions">Bluetooth Permissions</h2> + <p>In order to use Bluetooth features in your application, you must declare the Bluetooth permission {@link android.Manifest.permission#BLUETOOTH}. You need this permission to perform any Bluetooth communication, @@ -175,40 +175,40 @@ ability to discover local Bluetooth devices. The other abilities granted by this permission should not be used, unless the application is a "power manager" that will modify Bluetooth settings upon user request. <strong>Note:</strong> If you use {@link android.Manifest.permission#BLUETOOTH_ADMIN} permission, then you must -also have the {@link android.Manifest.permission#BLUETOOTH} permission.</p> - +also have the {@link android.Manifest.permission#BLUETOOTH} permission.</p> + <p>Declare the Bluetooth permission(s) in your application manifest file. For -example:</p> - -<pre> +example:</p> + +<pre> <manifest ... > <uses-permission android:name="android.permission.BLUETOOTH" /> ... </manifest> -</pre> - +</pre> + <p>See the <a -href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a> -reference for more information about declaring application permissions.</p> - - -<h2 id="SettingUp">Setting Up Bluetooth</h2> - -<div class="figure" style="width:200px"> -<img src="{@docRoot}images/bt_enable_request.png" /> +href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a> +reference for more information about declaring application permissions.</p> + + +<h2 id="SettingUp">Setting Up Bluetooth</h2> + +<div class="figure" style="width:200px"> +<img src="{@docRoot}images/bt_enable_request.png" /> <strong>Figure 1:</strong> The enabling Bluetooth dialog. -</div> - +</div> + <p>Before your application can communicate over Bluetooth, you need to verify -that Bluetooth is supported on the device, and if so, ensure that it is enabled.</p> - +that Bluetooth is supported on the device, and if so, ensure that it is enabled.</p> + <p>If Bluetooth is not supported, then you should gracefully disable any Bluetooth features. If Bluetooth is supported, but disabled, then you can request that the user enable Bluetooth without leaving your application. This setup is -accomplished in two steps, using the {@link android.bluetooth.BluetoothAdapter}.</p> - - -<ol> +accomplished in two steps, using the {@link android.bluetooth.BluetoothAdapter}.</p> + + +<ol> <li>Get the {@link android.bluetooth.BluetoothAdapter} <p>The {@link android.bluetooth.BluetoothAdapter} is required for any and all Bluetooth activity. To get the {@link android.bluetooth.BluetoothAdapter}, call the static {@link @@ -217,15 +217,15 @@ android.bluetooth.BluetoothAdapter#getDefaultAdapter()} method. This returns a Bluetooth adapter (the Bluetooth radio). There's one Bluetooth adapter for the entire system, and your application can interact with it using this object. If {@link android.bluetooth.BluetoothAdapter#getDefaultAdapter()} returns null, -then the device does not support Bluetooth and your story ends here. For example:</p> -<pre> +then the device does not support Bluetooth and your story ends here. For example:</p> +<pre> BluetoothAdapter mBluetoothAdapter = BluetoothAdapter.getDefaultAdapter(); if (mBluetoothAdapter == null) { // Device does not support Bluetooth } -</pre> -</li> - +</pre> +</li> + <li>Enable Bluetooth <p>Next, you need to ensure that Bluetooth is enabled. Call {@link android.bluetooth.BluetoothAdapter#isEnabled()} to check whether Bluetooth is @@ -234,17 +234,17 @@ request that Bluetooth be enabled, call {@link android.app.Activity#startActivityForResult(Intent,int) startActivityForResult()} with the {@link android.bluetooth.BluetoothAdapter#ACTION_REQUEST_ENABLE} action Intent. This will issue a request to enable Bluetooth through the system settings (without -stopping your application). For example:</p> -<pre> +stopping your application). For example:</p> +<pre> if (!mBluetoothAdapter.isEnabled()) { Intent enableBtIntent = new Intent(BluetoothAdapter.ACTION_REQUEST_ENABLE); startActivityForResult(enableBtIntent, REQUEST_ENABLE_BT); } -</pre> - +</pre> + <p>A dialog will appear requesting user permission to enable Bluetooth, as shown in Figure 1. If the user responds "Yes," the system will begin to enable Bluetooth -and focus will return to your application once the process completes (or fails).</p> +and focus will return to your application once the process completes (or fails).</p> <p>The {@code REQUEST_ENABLE_BT} constant passed to {@link android.app.Activity#startActivityForResult(Intent,int) startActivityForResult()} is a locally @@ -259,9 +259,9 @@ android.app.Activity#onActivityResult(int,int,Intent) onActivityResult()} callback. If Bluetooth was not enabled due to an error (or the user responded "No") then the result code is {@link android.app.Activity#RESULT_CANCELED}.</p> -</li> -</ol> - +</li> +</ol> + <p>Optionally, your application can also listen for the {@link android.bluetooth.BluetoothAdapter#ACTION_STATE_CHANGED} broadcast Intent, which the system will broadcast whenever the Bluetooth state has changed. This broadcast contains @@ -273,21 +273,21 @@ android.bluetooth.BluetoothAdapter#STATE_ON}, {@link android.bluetooth.BluetoothAdapter#STATE_TURNING_OFF}, and {@link android.bluetooth.BluetoothAdapter#STATE_OFF}. Listening for this broadcast can be useful to detect changes made to the Bluetooth state while your -app is running.</p> - +app is running.</p> + <p class="note"><strong>Tip:</strong> Enabling discoverability will automatically enable Bluetooth. If you plan to consistently enable device discoverability before performing Bluetooth activity, you can skip step 2 above. Read about <a href="#EnablingDiscoverability">enabling discoverability</a>, -below.</p> - - -<h2 id="FindingDevices">Finding Devices</h2> - +below.</p> + + +<h2 id="FindingDevices">Finding Devices</h2> + <p>Using the {@link android.bluetooth.BluetoothAdapter}, you can find remote Bluetooth devices either through device discovery or by querying the list of paired (bonded) -devices.</p> - +devices.</p> + <p>Device discovery is a scanning procedure that searches the local area for Bluetooth enabled devices and then requesting some information about each one (this is sometimes referred to as "discovering," "inquiring" or "scanning"). @@ -296,15 +296,15 @@ request only if it is currently enabled to be discoverable. If a device is discoverable, it will respond to the discovery request by sharing some information, such as the device name, class, and its unique MAC address. Using this information, the device performing discovery can then choose to initiate a -connection to the discovered device.</p> - +connection to the discovered device.</p> + <p>Once a connection is made with a remote device for the first time, a pairing request is automatically presented to the user. When a device is paired, the basic information about that device (such as the device name, class, and MAC address) is saved and can be read using the Bluetooth APIs. Using the known MAC address for a remote device, a connection can be initiated with it at -any time without performing discovery (assuming the device is within range).</p> - +any time without performing discovery (assuming the device is within range).</p> + <p>Remember there is a difference between being paired and being connected. To be paired means that two devices are aware of each other's existence, have a shared link-key that can be used for authentication, and are capable of @@ -312,28 +312,28 @@ establishing an encrypted connection with each other. To be connected means that the devices currently share an RFCOMM channel and are able to transmit data with each other. The current Android Bluetooth API's require devices to be paired before an RFCOMM connection can be established. (Pairing is automatically performed -when you initiate an encrypted connection with the Bluetooth APIs.)</p> - +when you initiate an encrypted connection with the Bluetooth APIs.)</p> + <p>The following sections describe how to find devices that have been paired, or -discover new devices using device discovery.</p> - +discover new devices using device discovery.</p> + <p class="note"><strong>Note:</strong> Android-powered devices are not discoverable by default. A user can make the device discoverable for a limited time through the system settings, or an application can request that the user enable discoverability without leaving the -application. How to <a href="#EnablingDiscoverability">enable discoverability</a> -is discussed below.</p> - - -<h3 id="QueryingPairedDevices">Querying paired devices</h3> - +application. How to <a href="#EnablingDiscoverability">enable discoverability</a> +is discussed below.</p> + + +<h3 id="QueryingPairedDevices">Querying paired devices</h3> + <p>Before performing device discovery, its worth querying the set of paired devices to see if the desired device is already known. To do so, call {@link android.bluetooth.BluetoothAdapter#getBondedDevices()}. This will return a Set of {@link android.bluetooth.BluetoothDevice}s representing paired devices. For example, you can query all paired devices and then -show the name of each device to the user, using an ArrayAdapter:</p> -<pre> +show the name of each device to the user, using an ArrayAdapter:</p> +<pre> Set<BluetoothDevice> pairedDevices = mBluetoothAdapter.getBondedDevices(); // If there are paired devices if (pairedDevices.size() > 0) { @@ -343,24 +343,24 @@ if (pairedDevices.size() > 0) { mArrayAdapter.add(device.getName() + "\n" + device.getAddress()); } } -</pre> - +</pre> + <p>All that's needed from the {@link android.bluetooth.BluetoothDevice} object in order to initiate a connection is the MAC address. In this example, it's saved as a part of an ArrayAdapter that's shown to the user. The MAC address can later be extracted in order to initiate the connection. You can learn more about creating -a connection in the section about <a href="#ConnectingDevices">Connecting Devices</a>.</p> - - -<h3 id="DiscoveringDevices">Discovering devices</h3> - +a connection in the section about <a href="#ConnectingDevices">Connecting Devices</a>.</p> + + +<h3 id="DiscoveringDevices">Discovering devices</h3> + <p>To start discovering devices, simply call {@link android.bluetooth.BluetoothAdapter#startDiscovery()}. The process is asynchronous and the method will immediately return with a boolean indicating whether discovery has successfully started. The discovery process usually involves an inquiry scan of about 12 seconds, followed by a page scan of -each found device to retrieve its Bluetooth name.</p> - +each found device to retrieve its Bluetooth name.</p> + <p>Your application must register a BroadcastReceiver for the {@link android.bluetooth.BluetoothDevice#ACTION_FOUND} Intent in order to receive information about each @@ -371,8 +371,8 @@ Intent carries the extra fields {@link android.bluetooth.BluetoothDevice#EXTRA_CLASS}, containing a {@link android.bluetooth.BluetoothDevice} and a {@link android.bluetooth.BluetoothClass}, respectively. For example, here's how you can -register to handle the broadcast when devices are discovered:</p> -<pre> +register to handle the broadcast when devices are discovered:</p> +<pre> // Create a BroadcastReceiver for ACTION_FOUND private final BroadcastReceiver mReceiver = new BroadcastReceiver() { public void onReceive(Context context, Intent intent) { @@ -389,15 +389,15 @@ private final BroadcastReceiver mReceiver = new BroadcastReceiver() { // Register the BroadcastReceiver IntentFilter filter = new IntentFilter(BluetoothDevice.ACTION_FOUND); registerReceiver(mReceiver, filter); // Don't forget to unregister during onDestroy -</pre> - +</pre> + <p>All that's needed from the {@link android.bluetooth.BluetoothDevice} object in order to initiate a connection is the MAC address. In this example, it's saved as a part of an ArrayAdapter that's shown to the user. The MAC address can later be extracted in order to initiate the connection. You can learn more about creating a connection -in the section about <a href="#ConnectingDevices">Connecting Devices</a>.</p> - +in the section about <a href="#ConnectingDevices">Connecting Devices</a>.</p> + <p class="caution"><strong>Caution:</strong> Performing device discovery is a heavy procedure for the Bluetooth adapter and will consume a lot of its resources. Once you have found a device to @@ -406,10 +406,10 @@ connect, be certain that you always stop discovery with attempting a connection. Also, if you already hold a connection with a device, then performing discovery can significantly reduce the bandwidth available for the connection, so you should -not perform discovery while connected.</p> - -<h4 id="EnablingDiscoverability">Enabling discoverability</h4> - +not perform discovery while connected.</p> + +<h4 id="EnablingDiscoverability">Enabling discoverability</h4> + <p>If you would like to make the local device discoverable to other devices, call {@link android.app.Activity#startActivityForResult(Intent,int)} with the {@link android.bluetooth.BluetoothAdapter#ACTION_REQUEST_DISCOVERABLE} action @@ -420,30 +420,30 @@ discoverable for 120 seconds. You can define a different duration by adding the extra. The maximum duration an app can set is 3600 seconds, and a value of 0 means the device is always discoverable. Any value below 0 or above 3600 is automatically set to 120 secs). For example, this snippet sets the duration to -300:</p> +300:</p> <pre>Intent discoverableIntent = new Intent(BluetoothAdapter.ACTION_REQUEST_DISCOVERABLE); discoverableIntent.putExtra(BluetoothAdapter.EXTRA_DISCOVERABLE_DURATION, 300); startActivity(discoverableIntent); -</pre> - -<div class="figure" style="width:200px"> -<img src="{@docRoot}images/bt_enable_discoverable.png" /> +</pre> + +<div class="figure" style="width:200px"> +<img src="{@docRoot}images/bt_enable_discoverable.png" /> <strong>Figure 2:</strong> The enabling discoverability dialog. -</div> - +</div> + <p>A dialog will be displayed, requesting user permission to make the device discoverable, as shown in Figure 2. If the user responds "Yes," then the device will become discoverable for the specified amount of time. Your activity will then receive a call to the {@link android.app.Activity#onActivityResult(int,int,Intent) onActivityResult())} callback, with the result code equal to the duration that the device is discoverable. If the user responded "No" or if an error occurred, the result code will -be {@link android.app.Activity#RESULT_CANCELED}.</p> - +be {@link android.app.Activity#RESULT_CANCELED}.</p> + <p class="note"><strong>Note:</strong> If Bluetooth has not been enabled on the device, -then enabling device discoverability will automatically enable Bluetooth.</p> - +then enabling device discoverability will automatically enable Bluetooth.</p> + <p>The device will silently remain in discoverable mode for the allotted time. If you would like to be notified when the discoverable mode has changed, you can register a BroadcastReceiver for the {@link @@ -457,18 +457,18 @@ new and old scan mode, respectively. Possible values for each are android.bluetooth.BluetoothAdapter#SCAN_MODE_NONE}, which indicate that the device is either in discoverable mode, not in discoverable mode but still able to receive connections, or not in discoverable -mode and unable to receive connections, respectively.</p> - +mode and unable to receive connections, respectively.</p> + <p>You do not need to enable device discoverability if you will be initiating the connection to a remote device. Enabling discoverability is only necessary when you want your application to host a server socket that will accept incoming connections, because the remote devices must be able to discover the device -before it can initiate the connection.</p> - - - -<h2 id="ConnectingDevices">Connecting Devices</h2> - +before it can initiate the connection.</p> + + + +<h2 id="ConnectingDevices">Connecting Devices</h2> + <p>In order to create a connection between your application on two devices, you must implement both the server-side and client-side mechanisms, because one device must open a server socket and the other one must initiate the connection @@ -478,36 +478,36 @@ client are considered connected to each other when they each have a connected point, each device can obtain input and output streams and data transfer can begin, which is discussed in the section about <a href="#ManagingAConnection">Managing a Connection</a>. This section describes how -to initiate the connection between two devices.</p> - +to initiate the connection between two devices.</p> + <p>The server device and the client device each obtain the required {@link android.bluetooth.BluetoothSocket} in different ways. The server will receive it when an incoming connection is accepted. The client will receive it when it -opens an RFCOMM channel to the server.</p> - -<div class="figure" style="width:200px"> -<img src="{@docRoot}images/bt_pairing_request.png" /> +opens an RFCOMM channel to the server.</p> + +<div class="figure" style="width:200px"> +<img src="{@docRoot}images/bt_pairing_request.png" /> <strong>Figure 3:</strong> The Bluetooth pairing dialog. -</div> - +</div> + <p>One implementation technique is to automatically prepare each device as a server, so that each one has a server socket open and listening for connections. Then either device can initiate a connection with the other and become the client. Alternatively, one device can explicitly "host" the connection and open a server socket on demand and the other device can simply initiate the -connection.</p> - +connection.</p> + <p class="note"><strong>Note:</strong> If the two devices have not been previously paired, then the Android framework will automatically show a pairing request notification or dialog to the user during the connection procedure, as shown in Figure 3. So when attempting to connect devices, your application does not need to be concerned about whether or not the devices are paired. Your RFCOMM connection attempt will block until the user has successfully paired, -or will fail if the user rejects pairing, or if pairing fails or times out. </p> - - -<h3 id="ConnectingAsAServer">Connecting as a server</h3> - +or will fail if the user rejects pairing, or if pairing fails or times out. </p> + + +<h3 id="ConnectingAsAServer">Connecting as a server</h3> + <p>When you want to connect two devices, one must act as a server by holding an open {@link android.bluetooth.BluetoothServerSocket}. The purpose of the server socket is to listen for incoming connection requests and when one is accepted, @@ -515,26 +515,26 @@ provide a connected {@link android.bluetooth.BluetoothSocket}. When the {@link android.bluetooth.BluetoothSocket} is acquired from the {@link android.bluetooth.BluetoothServerSocket}, the {@link android.bluetooth.BluetoothServerSocket} can (and should) be -discarded, unless you want to accept more connections.</p> - -<div class="sidebox-wrapper"> -<div class="sidebox"> -<h2>About UUID</h2> - +discarded, unless you want to accept more connections.</p> + +<div class="sidebox-wrapper"> +<div class="sidebox"> +<h2>About UUID</h2> + <p>A Universally Unique Identifier (UUID) is a standardized 128-bit format for a string ID used to uniquely identify information. The point of a UUID is that it's big enough that you can select any random and it won't clash. In this case, it's used to uniquely identify your application's Bluetooth service. To get a UUID to use with your application, you can use one of the many random UUID generators on the web, then initialize a {@link java.util.UUID} with {@link -java.util.UUID#fromString(String)}.</p> -</div> -</div> - +java.util.UUID#fromString(String)}.</p> +</div> +</div> + <p>Here's the basic procedure to set up a server socket and accept a -connection:</p> - -<ol> +connection:</p> + +<ol> <li>Get a {@link android.bluetooth.BluetoothServerSocket} by calling the {@link android.bluetooth.BluetoothAdapter#listenUsingRfcommWithServiceRecord(String, @@ -546,9 +546,9 @@ UUID is also included in the SDP entry and will be the basis for the connection agreement with the client device. That is, when the client attempts to connect with this device, it will carry a UUID that uniquely identifies the service with which it wants to connect. These UUIDs must match in order for the connection to -be accepted (in the next step).</p> -</li> - +be accepted (in the next step).</p> +</li> + <li>Start listening for connection requests by calling {@link android.bluetooth.BluetoothServerSocket#accept()}. <p>This is a blocking call. It will return when either a connection has been @@ -556,9 +556,9 @@ accepted or an exception has occurred. A connection is accepted only when a remote device has sent a connection request with a UUID matching the one registered with this listening server socket. When successful, {@link android.bluetooth.BluetoothServerSocket#accept()} will -return a connected {@link android.bluetooth.BluetoothSocket}.</p> -</li> - +return a connected {@link android.bluetooth.BluetoothSocket}.</p> +</li> + <li>Unless you want to accept additional connections, call {@link android.bluetooth.BluetoothServerSocket#close()}. <p>This releases the server socket and all its resources, but does <em>not</em> close the @@ -567,10 +567,10 @@ android.bluetooth.BluetoothServerSocket#accept()}. Unlike TCP/IP, RFCOMM only al connected client per channel at a time, so in most cases it makes sense to call {@link android.bluetooth.BluetoothServerSocket#close()} on the {@link android.bluetooth.BluetoothServerSocket} immediately after accepting a connected -socket.</p> -</li> -</ol> - +socket.</p> +</li> +</ol> + <p>The {@link android.bluetooth.BluetoothServerSocket#accept()} call should not be executed in the main activity UI thread because it is a blocking call and will prevent any other interaction with the application. It usually makes @@ -583,16 +583,16 @@ android.bluetooth.BluetoothServerSocket} (or {@link android.bluetooth.BluetoothSocket}) from another thread and the blocked call will immediately return. Note that all methods on a {@link android.bluetooth.BluetoothServerSocket} or {@link android.bluetooth.BluetoothSocket} -are thread-safe.</p> - -<h4>Example</h4> - +are thread-safe.</p> + +<h4>Example</h4> + <p>Here's a simplified thread for the server component that accepts incoming -connections:</p> -<pre> +connections:</p> +<pre> private class AcceptThread extends Thread { private final BluetoothServerSocket mmServerSocket; - + public AcceptThread() { // Use a temporary object that is later assigned to mmServerSocket, // because mmServerSocket is final @@ -603,7 +603,7 @@ private class AcceptThread extends Thread { } catch (IOException e) { } mmServerSocket = tmp; } - + public void run() { BluetoothSocket socket = null; // Keep listening until exception occurs or a socket is returned @@ -622,7 +622,7 @@ private class AcceptThread extends Thread { } } } - + /** Will cancel the listening socket, and cause the thread to finish */ public void cancel() { try { @@ -630,37 +630,37 @@ private class AcceptThread extends Thread { } catch (IOException e) { } } } -</pre> - +</pre> + <p>In this example, only one incoming connection is desired, so as soon as a connection is accepted and the {@link android.bluetooth.BluetoothSocket} is acquired, the application sends the acquired {@link android.bluetooth.BluetoothSocket} to a separate thread, closes the -{@link android.bluetooth.BluetoothServerSocket} and breaks the loop.</p> - +{@link android.bluetooth.BluetoothServerSocket} and breaks the loop.</p> + <p>Note that when {@link android.bluetooth.BluetoothServerSocket#accept()} returns the {@link android.bluetooth.BluetoothSocket}, the socket is already connected, so you should <em>not</em> call {@link android.bluetooth.BluetoothSocket#connect()} (as you do from the -client-side).</p> - +client-side).</p> + <p><code>manageConnectedSocket()</code> is a fictional method in the application that will initiate the thread for transferring data, which is discussed in the section -about <a href="#ManagingAConnection">Managing a Connection</a>.</p> - +about <a href="#ManagingAConnection">Managing a Connection</a>.</p> + <p>You should usually close your {@link android.bluetooth.BluetoothServerSocket} as soon as you are done listening for incoming connections. In this example, {@link android.bluetooth.BluetoothServerSocket#close()} is called as soon as the {@link android.bluetooth.BluetoothSocket} is acquired. You may also want to provide a public method in your thread that can close the private {@link android.bluetooth.BluetoothSocket} in the event that you need to stop listening on the -server socket.</p> - - -<h3 id="ConnectingAsAClient">Connecting as a client</h3> - +server socket.</p> + + +<h3 id="ConnectingAsAClient">Connecting as a client</h3> + <p>In order to initiate a connection with a remote device (a device holding an open server socket), you must first obtain a {@link @@ -669,11 +669,11 @@ android.bluetooth.BluetoothDevice} object that represents the remote device. section about <a href="#FindingDevices">Finding Devices</a>.) You must then use the {@link android.bluetooth.BluetoothDevice} to acquire a {@link -android.bluetooth.BluetoothSocket} and initiate the connection.</p> - -<p>Here's the basic procedure:</p> - -<ol> +android.bluetooth.BluetoothSocket} and initiate the connection.</p> + +<p>Here's the basic procedure:</p> + +<ol> <li>Using the {@link android.bluetooth.BluetoothDevice}, get a {@link android.bluetooth.BluetoothSocket} by calling {@link android.bluetooth.BluetoothDevice#createRfcommSocketToServiceRecord(UUID)}. @@ -684,9 +684,9 @@ must match the UUID used by the server device when it opened its android.bluetooth.BluetoothAdapter#listenUsingRfcommWithServiceRecord(String, UUID)}). Using the same UUID is simply a matter of hard-coding the UUID string into your application and then referencing it from both the server and client -code.</p> -</li> - +code.</p> +</li> + <li>Initiate the connection by calling {@link android.bluetooth.BluetoothSocket#connect()}. <p>Upon this call, the system will perform an SDP lookup on the remote device in @@ -697,34 +697,34 @@ android.bluetooth.BluetoothSocket#connect()} will return. This method is a blocking call. If, for any reason, the connection fails or the {@link android.bluetooth.BluetoothSocket#connect()} method times out (after about -12 seconds), then it will throw an exception.</p> +12 seconds), then it will throw an exception.</p> <p>Because {@link android.bluetooth.BluetoothSocket#connect()} is a blocking call, this connection procedure should always be performed in a thread separate from the main activity -thread.</p> +thread.</p> <p class="note">Note: You should always ensure that the device is not performing device discovery when you call {@link android.bluetooth.BluetoothSocket#connect()}. If discovery is in progress, then the -connection attempt will be significantly slowed and is more likely to fail.</p> -</li> -</ol> - -<h4>Example</h4> - +connection attempt will be significantly slowed and is more likely to fail.</p> +</li> +</ol> + +<h4>Example</h4> + <p>Here is a basic example of a thread that initiates a Bluetooth -connection:</p> -<pre> +connection:</p> +<pre> private class ConnectThread extends Thread { private final BluetoothSocket mmSocket; private final BluetoothDevice mmDevice; - + public ConnectThread(BluetoothDevice device) { // Use a temporary object that is later assigned to mmSocket, // because mmSocket is final BluetoothSocket tmp = null; mmDevice = device; - + // Get a BluetoothSocket to connect with the given BluetoothDevice try { // MY_UUID is the app's UUID string, also used by the server code @@ -732,11 +732,11 @@ private class ConnectThread extends Thread { } catch (IOException e) { } mmSocket = tmp; } - + public void run() { // Cancel discovery because it will slow down the connection mBluetoothAdapter.cancelDiscovery(); - + try { // Connect the device through the socket. This will block // until it succeeds or throws an exception @@ -748,11 +748,11 @@ private class ConnectThread extends Thread { } catch (IOException closeException) { } return; } - + // Do work to manage the connection (in a separate thread) manageConnectedSocket(mmSocket); } - + /** Will cancel an in-progress connection, and close the socket */ public void cancel() { try { @@ -760,42 +760,42 @@ private class ConnectThread extends Thread { } catch (IOException e) { } } } -</pre> - +</pre> + <p>Notice that {@link android.bluetooth.BluetoothAdapter#cancelDiscovery()} is called before the connection is made. You should always do this before connecting and it is safe to call without actually checking whether it is running or not (but if you do want to -check, call {@link android.bluetooth.BluetoothAdapter#isDiscovering()}).</p> - +check, call {@link android.bluetooth.BluetoothAdapter#isDiscovering()}).</p> + <p><code>manageConnectedSocket()</code> is a fictional method in the application that will initiate the thread for transferring data, which is discussed in the section -about <a href="#ManagingAConnection">Managing a Connection</a>.</p> - +about <a href="#ManagingAConnection">Managing a Connection</a>.</p> + <p>When you're done with your {@link android.bluetooth.BluetoothSocket}, always call {@link android.bluetooth.BluetoothSocket#close()} to clean up. Doing so will immediately close the connected socket and clean up all internal -resources.</p> - - -<h2 id="ManagingAConnection">Managing a Connection</h2> - +resources.</p> + + +<h2 id="ManagingAConnection">Managing a Connection</h2> + <p>When you have successfully connected two (or more) devices, each one will have a connected {@link android.bluetooth.BluetoothSocket}. This is where the fun begins because you can share data between devices. Using the {@link android.bluetooth.BluetoothSocket}, the general procedure to transfer arbitrary data is -simple:</p> -<ol> +simple:</p> +<ol> <li>Get the {@link java.io.InputStream} and {@link java.io.OutputStream} that handle transmissions through the socket, via {@link android.bluetooth.BluetoothSocket#getInputStream()} and -{@link android.bluetooth.BluetoothSocket#getOutputStream}, respectively.</li> - +{@link android.bluetooth.BluetoothSocket#getOutputStream}, respectively.</li> + <li>Read and write data to the streams with {@link -java.io.InputStream#read(byte[])} and {@link java.io.OutputStream#write(byte[])}.</li> -</ol> - -<p>That's it.</p> - +java.io.InputStream#read(byte[])} and {@link java.io.OutputStream#write(byte[])}.</li> +</ol> + +<p>That's it.</p> + <p>There are, of course, implementation details to consider. First and foremost, you should use a dedicated thread for all stream reading and writing. This is important because both {@link java.io.InputStream#read(byte[])} and {@link @@ -806,37 +806,37 @@ block, but can block for flow control if the remote device is not calling {@link java.io.InputStream#read(byte[])} quickly enough and the intermediate buffers are full. So, your main loop in the thread should be dedicated to reading from the {@link java.io.InputStream}. A separate public method in the thread can be used to initiate -writes to the {@link java.io.OutputStream}.</p> - -<h4>Example</h4> - -<p>Here's an example of how this might look:</p> -<pre> +writes to the {@link java.io.OutputStream}.</p> + +<h4>Example</h4> + +<p>Here's an example of how this might look:</p> +<pre> private class ConnectedThread extends Thread { private final BluetoothSocket mmSocket; private final InputStream mmInStream; private final OutputStream mmOutStream; - + public ConnectedThread(BluetoothSocket socket) { mmSocket = socket; InputStream tmpIn = null; OutputStream tmpOut = null; - + // Get the input and output streams, using temp objects because // member streams are final try { tmpIn = socket.getInputStream(); tmpOut = socket.getOutputStream(); } catch (IOException e) { } - + mmInStream = tmpIn; mmOutStream = tmpOut; } - + public void run() { byte[] buffer = new byte[1024]; // buffer store for the stream int bytes; // bytes returned from read() - + // Keep listening to the InputStream until an exception occurs while (true) { try { @@ -850,14 +850,14 @@ private class ConnectedThread extends Thread { } } } - + /* Call this from the main activity to send data to the remote device */ public void write(byte[] bytes) { try { mmOutStream.write(bytes); } catch (IOException e) { } } - + /* Call this from the main activity to shutdown the connection */ public void cancel() { try { @@ -865,44 +865,44 @@ private class ConnectedThread extends Thread { } catch (IOException e) { } } } -</pre> - +</pre> + <p>The constructor acquires the necessary streams and once executed, the thread will wait for data to come through the InputStream. When {@link java.io.InputStream#read(byte[])} returns with bytes from the stream, the data is sent to the main activity using a member Handler from the parent class. Then it goes back and waits for more bytes from -the stream.</p> - +the stream.</p> + <p>Sending outgoing data is as simple as calling the thread's <code>write()</code> method from the main activity and passing in the bytes to be sent. This method then simply calls {@link -java.io.OutputStream#write(byte[])} to send the data to the remote device.</p> - +java.io.OutputStream#write(byte[])} to send the data to the remote device.</p> + <p>The thread's <code>cancel()</code> method is important so that the connection can be terminated at any time by closing the {@link android.bluetooth.BluetoothSocket}. This should always be called when you're done using the Bluetooth -connection.</p> - -<div class="special"> +connection.</p> + +<div class="special"> <p>For a demonstration of using the Bluetooth APIs, see the <a -href="{@docRoot}resources/samples/BluetoothChat/index.html">Bluetooth Chat sample app</a>.</p> -</div> +href="{@docRoot}resources/samples/BluetoothChat/index.html">Bluetooth Chat sample app</a>.</p> +</div> -<h2 id="Profiles">Working with Profiles</h2> +<h2 id="Profiles">Working with Profiles</h2> <p>Starting in Android 3.0, the Bluetooth API includes support for working with Bluetooth profiles. A <em>Bluetooth profile</em> is a wireless interface specification for Bluetooth-based communication between devices. An example is the Hands-Free profile. For a mobile phone to connect to a wireless headset, -both devices must support the Hands-Free profile. </p> +both devices must support the Hands-Free profile. </p> <p>You can implement the interface {@link android.bluetooth.BluetoothProfile} to write your own classes to support a particular Bluetooth profile. The Android Bluetooth API provides implementations for the following Bluetooth -profiles:</p> -<ul> +profiles:</p> +<ul> <li><strong>Headset</strong>. The Headset profile provides support for Bluetooth headsets to be used with mobile phones. Android provides the {@link @@ -917,7 +917,7 @@ For more discussion of this topic, see <a href="#AT-Commands">Vendor-specific AT profile defines how high quality audio can be streamed from one device to 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> +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 @@ -928,50 +928,50 @@ 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> +HDP, see <a href="#HDP">Health Device Profile</a>.</li> -</ul> +</ul> -<p>Here are the basic steps for working with a profile:</p> -<ol> +<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/connectivity/bluetooth.html#SettingUp">Setting Up - Bluetooth</a>.</li> + Bluetooth</a>.</li> <li>Use {@link android.bluetooth.BluetoothAdapter#getProfileProxy(android.content.Context, android.bluetooth.BluetoothProfile.ServiceListener, int) getProfileProxy()} to establish a connection to the profile proxy object associated with the profile. In the example below, the profile proxy object is an instance of {@link -android.bluetooth.BluetoothHeadset}. </li> +android.bluetooth.BluetoothHeadset}. </li> <li>Set up a {@link android.bluetooth.BluetoothProfile.ServiceListener}. This listener notifies {@link android.bluetooth.BluetoothProfile} IPC clients when -they have been connected to or disconnected from the service.</li> +they have been connected to or disconnected from the service.</li> <li>In {@link android.bluetooth.BluetoothProfile.ServiceListener#onServiceConnected(int, android.bluetooth.BluetoothProfile) onServiceConnected()}, get a handle -to the profile proxy object.</li> +to the profile proxy object.</li> <li>Once you have the profile proxy object, you can use it to monitor the state of the connection and perform other operations that are relevant to that -profile.</li> -</ol> +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 -Headset profile:</p> +Headset profile:</p> <pre>BluetoothHeadset mBluetoothHeadset; - + // Get the default adapter BluetoothAdapter mBluetoothAdapter = BluetoothAdapter.getDefaultAdapter(); - + // Establish connection to the proxy. mBluetoothAdapter.getProfileProxy(context, mProfileListener, BluetoothProfile.HEADSET); - + private BluetoothProfile.ServiceListener mProfileListener = new BluetoothProfile.ServiceListener() { public void onServiceConnected(int profile, BluetoothProfile proxy) { if (profile == BluetoothProfile.HEADSET) { @@ -984,16 +984,16 @@ private BluetoothProfile.ServiceListener mProfileListener = new BluetoothProfile } } }; - + // ... call functions on mBluetoothHeadset - + // Close proxy connection after use. mBluetoothAdapter.closeProfileProxy(mBluetoothHeadset); -</pre> +</pre> -<h3 id="AT-Commands">Vendor-specific AT commands</h3> +<h3 id="AT-Commands">Vendor-specific AT commands</h3> <p>Starting in Android 3.0, applications can register to receive system broadcasts of pre-defined vendor-specific AT commands sent by headsets (such as @@ -1060,7 +1060,7 @@ 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 +application configuration ({@link android.bluetooth.BluetoothHealthAppConfiguration}) that acts as a health sink.</li> diff --git a/docs/html/guide/topics/connectivity/nfc/index.jd b/docs/html/guide/topics/connectivity/nfc/index.jd index f12facf75ecc..bc4f075c71f7 100644 --- a/docs/html/guide/topics/connectivity/nfc/index.jd +++ b/docs/html/guide/topics/connectivity/nfc/index.jd @@ -17,12 +17,12 @@ page.title=Near Field Communication <p>Android-powered devices with NFC simultaneously support three main modes of operation:</p> <ol> -<li><strong>Reader/writer mode</strong>, allowing the NFC device to read and/or write +<li><strong>Reader/writer mode</strong>, allowing the NFC device to read and/or write passive NFC tags and stickers.</li> -<li><strong>P2P mode</strong>, allowing the NFC device to exchange data with other NFC +<li><strong>P2P mode</strong>, allowing the NFC device to exchange data with other NFC peers; this operation mode is used by Android Beam.</li> -<li><strong>Card emulation mode</strong>, allowing the NFC device itself to act as an NFC -card. The emulated NFC card can then be accessed by an external NFC reader, +<li><strong>Card emulation mode</strong>, allowing the NFC device itself to act as an NFC +card. The emulated NFC card can then be accessed by an external NFC reader, such as an NFC point-of-sale terminal.</li> </ol> diff --git a/docs/html/guide/topics/connectivity/sip.jd b/docs/html/guide/topics/connectivity/sip.jd index d754894741e7..d8d6d277bbf9 100755 --- a/docs/html/guide/topics/connectivity/sip.jd +++ b/docs/html/guide/topics/connectivity/sip.jd @@ -12,10 +12,10 @@ page.tags=sipmanager,sipprofile,sipaudiocall,telephony <li><a href="#manager">Creating a SIP Manager</a></li> <li><a href="#profiles">Registering with a SIP Server</a></li> <li><a href="#audio">Making an Audio Call</a></li> - <li><a href="#receiving">Receiving Calls</a></li> + <li><a href="#receiving">Receiving Calls</a></li> <li><a href="#testing">Testing SIP Applications</a></li> </ol> - + <h2>Key classes</h2> <ol> <li>{@link android.net.sip.SipManager}</li> @@ -23,7 +23,7 @@ page.tags=sipmanager,sipprofile,sipaudiocall,telephony <li>{@link android.net.sip.SipAudioCall}</li> </ol> - + <h2>Related samples</h2> <ol> <li> <a href="{@docRoot}resources/samples/SipDemo/index.html"> SipDemo</a></li> @@ -46,9 +46,9 @@ record or playback directly.</p> <h2 id="requirements">Requirements and Limitations</h2> <p>Here are the requirements for developing a SIP application:</p> <ul> - + <li>You must have a mobile device that is running Android 2.3 or higher. </li> - + <li>SIP runs over a wireless data connection, so your device must have a data connection (with a mobile data service or Wi-Fi)</span>. This means that you can't test on AVD—you can only test on a physical device. For details, see @@ -139,7 +139,7 @@ capable of supporting SIP, add the following to your application's manifest:</p> <ul> - <li><code><uses-sdk android:minSdkVersion="9" /></code>. This + <li><code><uses-sdk android:minSdkVersion="9" /></code>. This indicates that your application requires Android 2.3 or higher. For more information, see <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#ApiLevels">API Levels</a> and the documentation for the <a @@ -162,7 +162,7 @@ may also be needed, depending on your implementation. For more information, see the documentation for the <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><uses- feature></a> element.</li> - + </ul> <p>If your application is designed to receive calls, you must also define a receiver ({@link android.content.BroadcastReceiver} subclass) in the application's manifest: </p> @@ -261,7 +261,7 @@ public void onRegistering(String localProfileUri) { public void onRegistrationDone(String localProfileUri, long expiryTime) { updateStatus("Ready"); } - + public void onRegistrationFailed(String localProfileUri, int errorCode, String errorMessage) { updateStatus("Registration failed. Please check settings."); @@ -291,8 +291,8 @@ example:</p> <li>A {@link android.net.sip.SipProfile} that is making the call (the "local profile"), and a valid SIP address to receive the call (the -"peer profile"). - +"peer profile"). + <li>A {@link android.net.sip.SipManager} object. </li> </ul> @@ -304,7 +304,7 @@ established:</p> <pre> SipAudioCall.Listener listener = new SipAudioCall.Listener() { - + @Override public void onCallEstablished(SipAudioCall call) { call.startAudio(); @@ -312,7 +312,7 @@ SipAudioCall.Listener listener = new SipAudioCall.Listener() { call.toggleMute(); ... } - + @Override public void onCallEnded(SipAudioCall call) { // Do something. @@ -326,12 +326,12 @@ make the call. The {@link android.net.sip.SipManager} method <ul> <li>A local SIP profile (the caller).</li> <li>A peer SIP profile (the user being called).</li> - + <li>A {@link android.net.sip.SipAudioCall.Listener} to listen to the call events from {@link android.net.sip.SipAudioCall}. This can be <code>null</code>, but as shown above, the listener is used to set things up once the call is established.</li> - + <li>The timeout value, in seconds.</li> </ul> <p>For example:</p> @@ -349,15 +349,15 @@ your application:</p> <code><receiver></code>. In <strong>SipDemo</strong>, this is <code><receiver android:name=".IncomingCallReceiver" android:label="Call Receiver"/></code>.</li> - + <li>Implement the receiver, which is a subclass of {@link android.content.BroadcastReceiver}. In <strong>SipDemo</strong>, this is <code>IncomingCallReceiver</code>.</li> - + <li>Initialize the local profile ({@link android.net.sip.SipProfile}) with a pending intent that fires your receiver when someone calls the local profile. </li> - + <li>Set up an intent filter that filters by the action that represents an incoming call. In <strong>SipDemo</strong>, this action is <code>android.SipDemo.INCOMING_CALL</code>. </li> @@ -427,16 +427,16 @@ action string provided by the application. In SipDemo, this action string is android.net.sip.SipProfile} object gets created with a pending intent based on the action string <code>android.SipDemo.INCOMING_CALL</code>. The <code>PendingIntent</code> object will perform a broadcast when the {@link -android.net.sip.SipProfile} receives a call:</p> +android.net.sip.SipProfile} receives a call:</p> <pre> public SipManager mSipManager = null; public SipProfile mSipProfile = null; ... -Intent intent = new Intent(); -intent.setAction("android.SipDemo.INCOMING_CALL"); -PendingIntent pendingIntent = PendingIntent.getBroadcast(this, 0, intent, Intent.FILL_IN_DATA); +Intent intent = new Intent(); +intent.setAction("android.SipDemo.INCOMING_CALL"); +PendingIntent pendingIntent = PendingIntent.getBroadcast(this, 0, intent, Intent.FILL_IN_DATA); mSipManager.open(mSipProfile, pendingIntent, null);</pre> <p>The broadcast will be intercepted by the intent filter, which will then fire @@ -485,8 +485,8 @@ href="{@docRoot}tools/device.html">Developing on a Device</a>.</li> href="{@docRoot}tools/device.html">Developing on a Device</a>.</li> <li>If you are using Android Studio, you can view the application log output by -opening the Event Log console (<strong>View > Tool Windows > Event Log</strong>). -<li>Ensure your application is configured to launch Logcat automatically when it runs: +opening the Event Log console (<strong>View > Tool Windows > Event Log</strong>). +<li>Ensure your application is configured to launch Logcat automatically when it runs: <ol TYPE=a> <li>Select <strong>Run > Edit Configurations</strong>. <li>Select the <strong>Miscellaneous</strong> tab in the <strong>Run/Debug Configurations</strong> window. diff --git a/docs/html/guide/topics/connectivity/usb/accessory.jd b/docs/html/guide/topics/connectivity/usb/accessory.jd index a2177678fc56..3942b3a951b9 100644 --- a/docs/html/guide/topics/connectivity/usb/accessory.jd +++ b/docs/html/guide/topics/connectivity/usb/accessory.jd @@ -169,7 +169,7 @@ 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 + <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> @@ -347,7 +347,7 @@ UsbAccessory[] accessoryList = manager.getAcccessoryList(); private static final String ACTION_USB_PERMISSION = "com.android.example.USB_PERMISSION"; private final BroadcastReceiver mUsbReceiver = new BroadcastReceiver() { - + public void onReceive(Context context, Intent intent) { String action = intent.getAction(); if (ACTION_USB_PERMISSION.equals(action)) { @@ -444,7 +444,7 @@ private void openAccessory() { <pre> BroadcastReceiver mUsbReceiver = new BroadcastReceiver() { public void onReceive(Context context, Intent intent) { - String action = intent.getAction(); + String action = intent.getAction(); if (UsbManager.ACTION_USB_ACCESSORY_DETACHED.equals(action)) { UsbAccessory accessory = (UsbAccessory)intent.getParcelableExtra(UsbManager.EXTRA_ACCESSORY); diff --git a/docs/html/guide/topics/connectivity/usb/host.jd b/docs/html/guide/topics/connectivity/usb/host.jd index d2194e6d6f6d..856027d09d7f 100644 --- a/docs/html/guide/topics/connectivity/usb/host.jd +++ b/docs/html/guide/topics/connectivity/usb/host.jd @@ -263,7 +263,7 @@ UsbDevice device = (UsbDevice) intent.getParcelableExtra(UsbManager.EXTRA_DEVICE obtain a device from the map.</p> <pre> UsbManager manager = (UsbManager) getSystemService(Context.USB_SERVICE); -... +... HashMap<String, UsbDevice> deviceList = manager.getDeviceList(); UsbDevice device = deviceList.get("deviceName"); </pre> @@ -317,7 +317,7 @@ private final BroadcastReceiver mUsbReceiver = new BroadcastReceiver() { if(device != null){ //call method to set up device communication } - } + } else { Log.d(TAG, "permission denied for device " + device); } @@ -396,7 +396,7 @@ private boolean forceClaim = true; UsbInterface intf = device.getInterface(0); UsbEndpoint endpoint = intf.getEndpoint(0); -UsbDeviceConnection connection = mUsbManager.openDevice(device); +UsbDeviceConnection connection = mUsbManager.openDevice(device); connection.claimInterface(intf, forceClaim); connection.bulkTransfer(endpoint, bytes, bytes.length, TIMEOUT); //do in another thread </pre> @@ -422,7 +422,7 @@ connection.bulkTransfer(endpoint, bytes, bytes.length, TIMEOUT); //do in another <pre> BroadcastReceiver mUsbReceiver = new BroadcastReceiver() { public void onReceive(Context context, Intent intent) { - String action = intent.getAction(); + String action = intent.getAction(); if (UsbManager.ACTION_USB_DEVICE_DETACHED.equals(action)) { UsbDevice device = (UsbDevice)intent.getParcelableExtra(UsbManager.EXTRA_DEVICE); diff --git a/docs/html/guide/topics/connectivity/wifip2p.jd b/docs/html/guide/topics/connectivity/wifip2p.jd index d7e1269696cf..b8eb40ea5014 100644 --- a/docs/html/guide/topics/connectivity/wifip2p.jd +++ b/docs/html/guide/topics/connectivity/wifip2p.jd @@ -66,7 +66,7 @@ a photo sharing application.</p> methods. A {@link android.net.wifi.p2p.WifiP2pManager#WIFI_P2P_PEERS_CHANGED_ACTION} intent is also broadcast if the {@link android.net.wifi.p2p.WifiP2pManager#discoverPeers discoverPeers()} method discovers that the peers list has changed.</p> - + <h2 id="api">API Overview</h2> <p>The {@link android.net.wifi.p2p.WifiP2pManager} class provides methods to allow you to interact with @@ -135,7 +135,7 @@ a photo sharing application.</p> are described in the following table:</p> <p class="table-caption"><strong>Table 2.</strong> Wi-Fi P2P Listeners</p> - + <table> <tr> <th>Listener interface</th> @@ -395,7 +395,7 @@ protected void onPause() { available peers that are in range. The call to this function is asynchronous and a success or failure is communicated to your application with {@link android.net.wifi.p2p.WifiP2pManager.ActionListener#onSuccess onSuccess()} and {@link - android.net.wifi.p2p.WifiP2pManager.ActionListener#onFailure onFailure()} if you created a + android.net.wifi.p2p.WifiP2pManager.ActionListener#onFailure onFailure()} if you created a {@link android.net.wifi.p2p.WifiP2pManager.ActionListener}. The {@link android.net.wifi.p2p.WifiP2pManager.ActionListener#onSuccess onSuccess()} method only notifies you that the discovery process succeeded and does not provide any information about the actual peers diff --git a/docs/html/guide/topics/data/index.jd b/docs/html/guide/topics/data/index.jd index 1e082b3fef95..169fc223d555 100644 --- a/docs/html/guide/topics/data/index.jd +++ b/docs/html/guide/topics/data/index.jd @@ -1,6 +1,6 @@ page.title=Data Storage page.landing=true -page.landing.intro=Store application data in databases, files, or preferences, in internal or removeable storage. You can also add a data backup service to let users store and recover application and system data. +page.landing.intro=Store application data in databases, files, or preferences, in internal or removeable storage. You can also add a data backup service to let users store and recover application and system data. page.landing.image= @jd:body @@ -10,14 +10,14 @@ page.landing.image= <div class="col-12"> <h3>Training</h3> - + <a href="http://developer.android.com/training/cloudsync/index.html"> <h4>Syncing to the Cloud</h4> <p>This class covers different strategies for cloud enabled applications. It covers syncing data with the cloud using your own back-end web application, and backing up data using the cloud so that users can restore their data when installing your application on a new device.</p> </a> - + </div> </div>
\ No newline at end of file diff --git a/docs/html/guide/topics/graphics/index.jd b/docs/html/guide/topics/graphics/index.jd index 17f630994952..a87e404503ed 100644 --- a/docs/html/guide/topics/graphics/index.jd +++ b/docs/html/guide/topics/graphics/index.jd @@ -17,7 +17,7 @@ support hardware acceleration on tablets. With this new pipeline, all drawing op by the UI toolkit are carried out using the GPU. You’ll be happy to hear that Android 4.0, Ice Cream Sandwich, brings an improved version of the hardware-accelerated 2D rendering pipeline.</p> </a> - + <a href="http://android-developers.blogspot.com/2011/05/introducing-viewpropertyanimator.html"> <h4>Introducing ViewPropertyAnimator</h4> @@ -25,7 +25,7 @@ href="http://android-developers.blogspot.com/2011/05/introducing-viewpropertyani including the new properties added to the View class in 3.0. In the 3.1 release, we added a small utility class that makes animating these properties even easier.</p> </a> - + <a href="http://android-developers.blogspot.com/2011/03/android-30-hardware-acceleration.html"> <h4>Android 3.0 Hardware Acceleration</h4> @@ -43,7 +43,7 @@ applications can benefit from an extra boost in performance.</p> that keeps your user interface (UI) components responsive and avoids exceeding your application memory limit.</p> </a> - + </div> </div>
\ No newline at end of file diff --git a/docs/html/guide/topics/graphics/overview.jd b/docs/html/guide/topics/graphics/overview.jd index 66a675dc6491..98d80a0f51bf 100644 --- a/docs/html/guide/topics/graphics/overview.jd +++ b/docs/html/guide/topics/graphics/overview.jd @@ -6,7 +6,7 @@ page.title=Animation and Graphics Overview and help you decide with approach is best for your needs.</p> <h3 id="animation">Animation</h3> - + <p>The Android framework provides two animation systems: property animation and view animation. Both animation systems are viable options, but the property animation system, in general, is the preferred method to use, because it diff --git a/docs/html/guide/topics/graphics/prop-animation.jd b/docs/html/guide/topics/graphics/prop-animation.jd index aed533de16ca..693799c5ba1e 100755 --- a/docs/html/guide/topics/graphics/prop-animation.jd +++ b/docs/html/guide/topics/graphics/prop-animation.jd @@ -165,9 +165,9 @@ page.tags=valueanimator,objectanimator,layouttransition,ViewPropertyAnimator "{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/animation/index.html">API Demos</a> sample project provides many examples on how to use the property animation system.</p> - + <h2 id="property-vs-view">How Property Animation Differs from View Animation</h2> - + <p>The view animation system provides the capability to only animate {@link android.view.View} objects, so if you wanted to animate non-{@link android.view.View} objects, you have to implement your own code to do so. The view animation system is also constrained in the fact that it only diff --git a/docs/html/guide/topics/location/strategies.jd b/docs/html/guide/topics/location/strategies.jd index 32be463e687c..2dfed2ce6e8e 100755 --- a/docs/html/guide/topics/location/strategies.jd +++ b/docs/html/guide/topics/location/strategies.jd @@ -411,12 +411,12 @@ data to work.</p> <h3 id="MockAVD">Using Android Studio</h3> <p>Select <b>Tools</b> > <b>Android</b> > <b>AVD Manager</b>. In the Android Virtual -Device Manager window, choose your AVD and launch it in the emulator by selecting the green +Device Manager window, choose your AVD and launch it in the emulator by selecting the green play arrow in the Actions column.</p> <p>Then, select <b>Tools</b> > <b>Android</b> > <b>Android Device Monitor</b>. -Select the Emulator Control tab in the Android Device Monitor window, and enter GPS coordinates -under Location Controls as individual lat/long coordinates, with a GPX file for route playback, +Select the Emulator Control tab in the Android Device Monitor window, and 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. </p> diff --git a/docs/html/guide/topics/manifest/action-element.jd b/docs/html/guide/topics/manifest/action-element.jd index fc6ce440579d..f3b340e2737a 100644 --- a/docs/html/guide/topics/manifest/action-element.jd +++ b/docs/html/guide/topics/manifest/action-element.jd @@ -13,10 +13,10 @@ parent.link=manifest-intro.html <p> <dt>description:</dt> <dd itemprop="description">Adds an action to an intent filter. -An <code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> element must contain +An <code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> element must contain one or more {@code <action>} elements. If it doesn't contain any, no -Intent objects will get through the filter. See -<a href="{@docRoot}guide/components/intents-filters.html">Intents and +Intent objects will get through the filter. See +<a href="{@docRoot}guide/components/intents-filters.html">Intents and Intent Filters</a> for details on intent filters and the role of action specifications within a filter. </dd> @@ -25,16 +25,16 @@ specifications within a filter. <dd><dl class="attr"> <dt><a name="nm"></a>{@code android:name}</dt> <dd>The name of the action. Some standard actions are defined in the -{@link android.content.Intent#ACTION_CHOOSER Intent} class as +{@link android.content.Intent#ACTION_CHOOSER Intent} class as <code>ACTION_<i>string</i></code> constants. To assign one of these actions to -this attribute, prepend "{@code android.intent.action.}" to the +this attribute, prepend "{@code android.intent.action.}" to the <code><i>string</i></code> that follows {@code ACTION_}. For example, for {@code ACTION_MAIN}, use "{@code android.intent.action.MAIN}" and for {@code ACTION_WEB_SEARCH}, use "{@code android.intent.action.WEB_SEARCH}". <p> For actions you define, it's best to use the package name as a prefix to -ensure uniqueness. For example, a {@code TRANSMOGRIFY} action might be specified +ensure uniqueness. For example, a {@code TRANSMOGRIFY} action might be specified as follows: </p> diff --git a/docs/html/guide/topics/manifest/activity-alias-element.jd b/docs/html/guide/topics/manifest/activity-alias-element.jd index 1427b55219bd..adb9937899fd 100644 --- a/docs/html/guide/topics/manifest/activity-alias-element.jd +++ b/docs/html/guide/topics/manifest/activity-alias-element.jd @@ -29,62 +29,62 @@ alias and it must be declared before the alias in the manifest. <p> The alias presents the target activity as a independent entity. -It can have its own set of intent filters, and they, rather than the -intent filters on the target activity itself, determine which intents +It can have its own set of intent filters, and they, rather than the +intent filters on the target activity itself, determine which intents can activate the target through the alias and how the system -treats the alias. For example, the intent filters on the alias may -specify the "<code>{@link android.content.Intent#ACTION_MAIN -android.intent.action.MAIN}</code>" -and "<code>{@link android.content.Intent#CATEGORY_LAUNCHER -android.intent.category.LAUNCHER}</code>" flags, causing it to be -represented in the application launcher, even though none of the +treats the alias. For example, the intent filters on the alias may +specify the "<code>{@link android.content.Intent#ACTION_MAIN +android.intent.action.MAIN}</code>" +and "<code>{@link android.content.Intent#CATEGORY_LAUNCHER +android.intent.category.LAUNCHER}</code>" flags, causing it to be +represented in the application launcher, even though none of the filters on the target activity itself set these flags. </p> <p> With the exception of {@code targetActivity}, {@code <activity-alias>} -attributes are a subset of <code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> attributes. +attributes are a subset of <code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> attributes. For attributes in the subset, none of the values set for the target carry over -to the alias. However, for attributes not in the subset, the values set for +to the alias. However, for attributes not in the subset, the values set for the target activity also apply to the alias. </p></dd> <dt>attributes:</dt> <dd><dl class="attr"> <dt><a name="enabled"></a>{@code android:enabled}</dt> -<dd>Whether or not the target activity can be instantiated by the system through -this alias — "{@code true}" if it can be, and "{@code false}" if not. +<dd>Whether or not the target activity can be instantiated by the system through +this alias — "{@code true}" if it can be, and "{@code false}" if not. The default value is "{@code true}". <p> -The <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element has its own -<code><a href="{@docRoot}guide/topics/manifest/application-element.html#enabled">enabled</a></code> attribute that applies to all -application components, including activity aliases. The +The <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element has its own +<code><a href="{@docRoot}guide/topics/manifest/application-element.html#enabled">enabled</a></code> attribute that applies to all +application components, including activity aliases. The <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> and {@code <activity-alias>} -attributes must both be "{@code true}" for the system to be able to instantiate -the target activity through the alias. If either is "{@code false}", the alias +attributes must both be "{@code true}" for the system to be able to instantiate +the target activity through the alias. If either is "{@code false}", the alias does not work. </p></dd> <dt><a name="exported"></a>{@code android:exported}</dt> -<dd>Whether or not components of other applications can launch the target activity -through this alias — "{@code true}" if they can, and "{@code false}" if not. -If "{@code false}", the target activity can be launched through the alias only by -components of the same application as the alias or applications with the same user ID. +<dd>Whether or not components of other applications can launch the target activity +through this alias — "{@code true}" if they can, and "{@code false}" if not. +If "{@code false}", the target activity can be launched through the alias only by +components of the same application as the alias or applications with the same user ID. <p> -The default value depends on whether the alias contains intent filters. The +The default value depends on whether the alias contains intent filters. The absence of any filters means that the activity can be invoked through the alias -only by specifying the exact name of the alias. This implies that the alias -is intended only for application-internal use (since others would not know its name) +only by specifying the exact name of the alias. This implies that the alias +is intended only for application-internal use (since others would not know its name) — so the default value is "{@code false}". -On the other hand, the presence of at least one filter implies that the alias +On the other hand, the presence of at least one filter implies that the alias is intended for external use — so the default value is "{@code true}". </p></dd> <dt><a name="icon"></a>{@code android:icon}</dt> -<dd>An icon for the target activity when presented to users through the alias. -See the <code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> element's +<dd>An icon for the target activity when presented to users through the alias. +See the <code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> element's <code><a href="{@docRoot}guide/topics/manifest/activity-element.html#icon">icon</a></code> attribute for more information. <dt><a name="label"></a>{@code android:label}</dt> @@ -95,31 +95,31 @@ See the <code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&l <dt><a name="nm">{@code android:name}</dt> <dd>A unique name for the alias. The name should resemble a fully -qualified class name. But, unlike the name of the target activity, -the alias name is arbitrary; it does not refer to an actual class. +qualified class name. But, unlike the name of the target activity, +the alias name is arbitrary; it does not refer to an actual class. </p></dd> <dt><a name="prmsn"></a>{@code android:permission}</dt> -<dd>The name of a permission that clients must have to launch the target activity -or get it to do something via the alias. If a caller of +<dd>The name of a permission that clients must have to launch the target activity +or get it to do something via the alias. If a caller of <code>{@link android.content.Context#startActivity startActivity()}</code> or <code>{@link android.app.Activity#startActivityForResult startActivityForResult()}</code> has not been granted the specified permission, the target activity will not be -activated. +activated. <p>This attribute supplants any permission set for the target activity itself. If it is not set, a permission is not needed to activate the target through the alias. </p> <p> -For more information on permissions, see the -<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#perms">Permissions</a> +For more information on permissions, see the +<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#perms">Permissions</a> section in the introduction. </p></dd> <dt><a name="trgt"></a>{@code android:targetActivity}</dt> <dd>The name of the activity that can be activated through the alias. -This name must match the {@code name} attribute of an +This name must match the {@code name} attribute of an <code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> element that precedes the alias in the manifest. </p></dd> diff --git a/docs/html/guide/topics/manifest/category-element.jd b/docs/html/guide/topics/manifest/category-element.jd index 0034119fe7b2..d0f0edf6dd8c 100644 --- a/docs/html/guide/topics/manifest/category-element.jd +++ b/docs/html/guide/topics/manifest/category-element.jd @@ -12,19 +12,19 @@ parent.link=manifest-intro.html <dt>description:</dt> <dd itemprop="description">Adds a category name to an intent filter. See -<a href="{@docRoot}guide/components/intents-filters.html">Intents and +<a href="{@docRoot}guide/components/intents-filters.html">Intents and Intent Filters</a> for details on intent filters and the role of category specifications within a filter.</dd> <dt>attributes:</dt> <dd><dl class="attr"> <dt><a name="nm"></a>{@code android:name}</dt> -<dd>The name of the category. Standard categories are defined in the +<dd>The name of the category. Standard categories are defined in the {@link android.content.Intent} class as <code>CATEGORY_<i>name</i></code> -constants. The name assigned here can be derived from those constants -by prefixing "{@code android.intent.category.}" to the +constants. The name assigned here can be derived from those constants +by prefixing "{@code android.intent.category.}" to the <code><i>name</i></code> that follows {@code CATEGORY_}. For example, -the string value for {@code CATEGORY_LAUNCHER} is +the string value for {@code CATEGORY_LAUNCHER} is "{@code android.intent.category.LAUNCHER}". <p class="note"><strong>Note:</strong> In order to receive implicit intents, you must include the @@ -39,7 +39,7 @@ your activity.</p> Custom categories should use the package name as a prefix, to ensure that they are unique. </p></dd> -</dl></dd> +</dl></dd> <!-- ##api level indication## --> <dt>introduced in:</dt> diff --git a/docs/html/guide/topics/manifest/grant-uri-permission-element.jd b/docs/html/guide/topics/manifest/grant-uri-permission-element.jd index b2d9bb7a104e..a464e552c47d 100644 --- a/docs/html/guide/topics/manifest/grant-uri-permission-element.jd +++ b/docs/html/guide/topics/manifest/grant-uri-permission-element.jd @@ -14,24 +14,24 @@ parent.link=manifest-intro.html <dt>description:</dt> <dd itemprop="description">Specifies which data subsets of the parent content provider permission -can be granted for. Data subsets are indicated by the path part of a +can be granted for. Data subsets are indicated by the path part of a {@code content:} URI. (The authority part of the URI identifies the -content provider.) -Granting permission is a way of enabling clients of the provider that don't -normally have permission to access its data to overcome that restriction on +content provider.) +Granting permission is a way of enabling clients of the provider that don't +normally have permission to access its data to overcome that restriction on a one-time basis. -<p> -If a content provider's <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#gprmns">grantUriPermissions</a></code> -attribute is "{@code true}", permission can be granted for any the data under -the provider's purview. However, if that attribute is "{@code false}", permission -can be granted only to data subsets that are specified by this element. +<p> +If a content provider's <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#gprmns">grantUriPermissions</a></code> +attribute is "{@code true}", permission can be granted for any the data under +the provider's purview. However, if that attribute is "{@code false}", permission +can be granted only to data subsets that are specified by this element. A provider can contain any number of {@code <grant-uri-permission>} elements. Each one can specify only one path (only one of the three possible attributes). </p> <p> -For information on how permission is granted, see the +For information on how permission is granted, see the <code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> element's <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#gprmsn">grantUriPermissions</a></code> attribute. </p></dd> @@ -41,34 +41,34 @@ For information on how permission is granted, see the <dt><a name="path"></a>{@code android:path} <br/>{@code android:pathPrefix} <br/>{@code android:pathPattern}</dt> -<dd>A path identifying the data subset or subsets that permission can be -granted for. The {@code path} attribute specifies a complete path; -permission can be granted only to the particular data subset identified -by that path. -The {@code pathPrefix} attribute specifies the initial part of a path; -permission can be granted to all data subsets with paths that share that -initial part. -The {@code pathPattern} attribute specifies a complete path, but one +<dd>A path identifying the data subset or subsets that permission can be +granted for. The {@code path} attribute specifies a complete path; +permission can be granted only to the particular data subset identified +by that path. +The {@code pathPrefix} attribute specifies the initial part of a path; +permission can be granted to all data subsets with paths that share that +initial part. +The {@code pathPattern} attribute specifies a complete path, but one that can contain the following wildcards: <ul> <li>An asterisk ('{@code *}') matches a sequence of 0 to many occurrences of the immediately preceding character.</li> -<li><p>A period followed by an asterisk ("{@code .*}") matches any sequence of +<li><p>A period followed by an asterisk ("{@code .*}") matches any sequence of 0 to many characters.</p></li> </ul> <p> -Because '{@code \}' is used as an escape character when the string is read -from XML (before it is parsed as a pattern), you will need to double-escape: -For example, a literal '{@code *}' would be written as "{@code \\*}" and a -literal '{@code \}' would be written as "{@code \\\\}". This is basically +Because '{@code \}' is used as an escape character when the string is read +from XML (before it is parsed as a pattern), you will need to double-escape: +For example, a literal '{@code *}' would be written as "{@code \\*}" and a +literal '{@code \}' would be written as "{@code \\\\}". This is basically the same as what you would need to write if constructing the string in Java code. </p> <p> -For more information on these types of patterns, see the descriptions of +For more information on these types of patterns, see the descriptions of {@link android.os.PatternMatcher#PATTERN_LITERAL}, {@link android.os.PatternMatcher#PATTERN_PREFIX}, and {@link android.os.PatternMatcher#PATTERN_SIMPLE_GLOB} in the @@ -81,10 +81,10 @@ For more information on these types of patterns, see the descriptions of <dd>API Level 1</dd> <dt>see also:</dt> -<dd>the +<dd>the <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#gprmns">grantUriPermissions</a></code> -attribute of the -<code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code> +attribute of the +<code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code> element</dd> diff --git a/docs/html/guide/topics/manifest/instrumentation-element.jd b/docs/html/guide/topics/manifest/instrumentation-element.jd index 74be559db137..a476be3b72f1 100644 --- a/docs/html/guide/topics/manifest/instrumentation-element.jd +++ b/docs/html/guide/topics/manifest/instrumentation-element.jd @@ -23,15 +23,15 @@ object is instantiated before any of the application's components.</dd> <dt>attributes:</dt> <dd><dl class="attr"> <dt><a name="ftest"></a>{@code android:functionalTest}</dt> -<dd>Whether or not the Instrumentation class should run as a functional test +<dd>Whether or not the Instrumentation class should run as a functional test — "{@code true}" if it should, and "{@code false}" if not. The default value is "{@code false}".</dd> <dt><a name="hprof"></a>{@code android:handleProfiling}</dt> -<dd>Whether or not the Instrumentation object will turn profiling on and -off — "{@code true}" if it determines when profiling starts and -stops, and "{@code false}" if profiling continues the entire time it is -running. A value of "{@code true}" enables the object to target profiling +<dd>Whether or not the Instrumentation object will turn profiling on and +off — "{@code true}" if it determines when profiling starts and +stops, and "{@code false}" if profiling continues the entire time it is +running. A value of "{@code true}" enables the object to target profiling at a specific set of operations. The default value is "{@code false}".</dd> <dt><a name="icon"></a>{@code android:icon}</dt> @@ -43,11 +43,11 @@ be set as a reference to a drawable resource.</dd> be set as a raw string or a reference to a string resource.</dd> <dt><a name="nm"></a>{@code android:name}</dt> -<dd>The name of the {@link android.app.Instrumentation} subclass. -This should be a fully qualified class name (such as, -"{@code com.example.project.StringInstrumentation}"). However, as a shorthand, -if the first character of the name is a period, it is appended to the package -name specified in the <code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> element. +<dd>The name of the {@link android.app.Instrumentation} subclass. +This should be a fully qualified class name (such as, +"{@code com.example.project.StringInstrumentation}"). However, as a shorthand, +if the first character of the name is a period, it is appended to the package +name specified in the <code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> element. <p> There is no default. The name must be specified. diff --git a/docs/html/guide/topics/manifest/intent-filter-element.jd b/docs/html/guide/topics/manifest/intent-filter-element.jd index 14b4e03b64a8..13956c9ad430 100644 --- a/docs/html/guide/topics/manifest/intent-filter-element.jd +++ b/docs/html/guide/topics/manifest/intent-filter-element.jd @@ -27,23 +27,23 @@ parent.link=manifest-intro.html <dt>description:</dt> <dd itemprop="description">Specifies the types of intents that an activity, service, or broadcast receiver can respond to. An intent filter declares the capabilities of its -parent component — what an activity or service can do and what types -of broadcasts a receiver can handle. It opens the component to receiving -intents of the advertised type, while filtering out those that are not +parent component — what an activity or service can do and what types +of broadcasts a receiver can handle. It opens the component to receiving +intents of the advertised type, while filtering out those that are not meaningful for the component. <p> -Most of the contents of the filter are described by its -<code><a href="{@docRoot}guide/topics/manifest/action-element.html"><action></a></code>, +Most of the contents of the filter are described by its +<code><a href="{@docRoot}guide/topics/manifest/action-element.html"><action></a></code>, <code><a href="{@docRoot}guide/topics/manifest/category-element.html"><category></a></code>, and <code><a href="{@docRoot}guide/topics/manifest/data-element.html"><data></a></code> subelements. </p> <p> -For a more detailed discussion of filters, see the separate -<a href="{@docRoot}guide/components/intents-filters.html">Intents -and Intent Filters</a> document, as well as the -<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#ifs">Intents Filters</a> +For a more detailed discussion of filters, see the separate +<a href="{@docRoot}guide/components/intents-filters.html">Intents +and Intent Filters</a> document, as well as the +<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#ifs">Intents Filters</a> section in the introduction. </p></dd> @@ -51,19 +51,19 @@ section in the introduction. <dd><dl class="attr"> <dt><a name="icon"></a>{@code android:icon}</dt> <dd>An icon that represents the parent activity, service, or broadcast -receiver when that component is presented to the user as having the +receiver when that component is presented to the user as having the capability described by the filter. <p> -This attribute must be set as a reference to a drawable resource -containing the image definition. The default value is the icon set -by the parent component's {@code icon} attribute. If the parent +This attribute must be set as a reference to a drawable resource +containing the image definition. The default value is the icon set +by the parent component's {@code icon} attribute. If the parent does not specify an icon, the default is the icon set by the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element. </p> <p> -For more on intent filter icons, see +For more on intent filter icons, see <a href="{@docRoot}guide/topics/manifest/manifest-intro.html#iconlabel">Icons and Labels</a> in the introduction. </p></dd> @@ -75,44 +75,44 @@ to the user as having the capability described by the filter. <p> The label should be set as a reference to a string resource, so that -it can be localized like other strings in the user interface. -However, as a convenience while you're developing the application, +it can be localized like other strings in the user interface. +However, as a convenience while you're developing the application, it can also be set as a raw string. </p> <p> -The default value is the label set by the parent component. If the +The default value is the label set by the parent component. If the parent does not specify a label, the default is the label set by the -<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's +<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's <code><a href="{@docRoot}guide/topics/manifest/application-element.html#label"> label</a></code> attribute. </p> <p> -For more on intent filter labels, see +For more on intent filter labels, see <a href="{@docRoot}guide/topics/manifest/manifest-intro.html#iconlabel">Icons and Labels</a> in the introduction. </p></dd> <dt><a name="priority"></a>{@code android:priority}</dt> <dd>The priority that should be given to the parent component with regard -to handling intents of the type described by the filter. This attribute has +to handling intents of the type described by the filter. This attribute has meaning for both activities and broadcast receivers: <ul> -<li>It provides information about how able an activity is to respond to +<li>It provides information about how able an activity is to respond to an intent that matches the filter, relative to other activities that could -also respond to the intent. When an intent could be handled by multiple +also respond to the intent. When an intent could be handled by multiple activities with different priorities, Android will consider only those with higher priority values as potential targets for the intent.</li> <li><p>It controls the order in which broadcast receivers are executed to -receive broadcast messages. Those with higher priority -values are called before those with lower values. (The order applies only +receive broadcast messages. Those with higher priority +values are called before those with lower values. (The order applies only to synchronous messages; it's ignored for asynchronous messages.)</p></li> </ul> <p> -Use this attribute only if you really need to impose a specific order in +Use this attribute only if you really need to impose a specific order in which the broadcasts are received, or want to force Android to prefer one activity over others. </p> diff --git a/docs/html/guide/topics/manifest/meta-data-element.jd b/docs/html/guide/topics/manifest/meta-data-element.jd index d3b41c391195..2d1bdfe59259 100644 --- a/docs/html/guide/topics/manifest/meta-data-element.jd +++ b/docs/html/guide/topics/manifest/meta-data-element.jd @@ -19,18 +19,18 @@ parent.link=manifest-intro.html <dt>description:</dt> <dd itemprop="description">A name-value pair for an item of additional, arbitrary data that can -be supplied to the parent component. A component element can contain any +be supplied to the parent component. A component element can contain any number of {@code <meta-data>} subelements. The values from all of -them are collected in a single {@link android.os.Bundle} object and made -available to the component as the -{@link android.content.pm.PackageItemInfo#metaData +them are collected in a single {@link android.os.Bundle} object and made +available to the component as the +{@link android.content.pm.PackageItemInfo#metaData PackageItemInfo.metaData} field. <p> -Ordinary values are specified through the <code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html#value">value</a></code> -attribute. However, to assign a resource ID as the value, use the -<code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html#resource">resource</a></code> attribute instead. For example, -the following code assigns whatever value is stored in the {@code @string/kangaroo} +Ordinary values are specified through the <code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html#value">value</a></code> +attribute. However, to assign a resource ID as the value, use the +<code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html#resource">resource</a></code> attribute instead. For example, +the following code assigns whatever value is stored in the {@code @string/kangaroo} resource to the "{@code zoo}" name: </p> @@ -44,22 +44,22 @@ the numeric ID of the resource, not the value stored in the resource: <pre><meta-data android:name="zoo" android:resource="@string/kangaroo" /></pre> <p> -It is highly recommended that you avoid supplying related data as +It is highly recommended that you avoid supplying related data as multiple separate {@code <meta-data>} entries. Instead, if you -have complex data to associate with a component, store it as a resource and +have complex data to associate with a component, store it as a resource and use the {@code resource} attribute to inform the component of its ID. </p></dd> <dt>attributes:</dt> <dd><dl class="attr"> <dt><a name="nm"></a>{@code android:name}</dt> -<dd>A unique name for the item. To ensure that the name is unique, use a -Java-style naming convention — for example, +<dd>A unique name for the item. To ensure that the name is unique, use a +Java-style naming convention — for example, "{@code com.example.project.activity.fred}".</dd> <dt><a name="rsrc"></a>{@code android:resource}</dt> -<dd>A reference to a resource. The ID of the resource is the value assigned -to the item. The ID can be retrieved from the meta-data Bundle by the +<dd>A reference to a resource. The ID of the resource is the value assigned +to the item. The ID can be retrieved from the meta-data Bundle by the {@link android.os.Bundle#getInt Bundle.getInt()} method.</dd> <dt><a name="val"></a>{@code android:value}</dt> @@ -70,7 +70,7 @@ to the item. The ID can be retrieved from the meta-data Bundle by the <th>Type</th> <th>Bundle method</th> </tr><tr> - <td>String value, using double backslashes ({@code \\}) to escape characters + <td>String value, using double backslashes ({@code \\}) to escape characters — such as "{@code \\n}" and "{@code \\uxxxxx}" for a Unicode character.</td> <td>{@link android.os.Bundle#getString(String) getString()}</td> </tr><tr> @@ -80,7 +80,7 @@ to the item. The ID can be retrieved from the meta-data Bundle by the <td>Boolean value, either "{@code true}" or "{@code false}"</td> <td>{@link android.os.Bundle#getBoolean(String) getBoolean()}</td> </tr><tr> - <td>Color value, in the form "{@code #rgb}", "{@code #argb}", + <td>Color value, in the form "{@code #rgb}", "{@code #argb}", "{@code #rrggbb}", or "{@code #aarrggbb}"</td> <td>{@link android.os.Bundle#getInt(String) getInt()}</td> </tr><tr> diff --git a/docs/html/guide/topics/manifest/path-permission-element.jd b/docs/html/guide/topics/manifest/path-permission-element.jd index cdaf82b00f29..477470733151 100644 --- a/docs/html/guide/topics/manifest/path-permission-element.jd +++ b/docs/html/guide/topics/manifest/path-permission-element.jd @@ -33,9 +33,9 @@ specified multiple times to supply multiple paths. <dd><dl class="attr"> <dt><a name="path"></a>{@code android:path}</dt> -<dd>A complete URI path for a subset of content provider data. -Permission can be granted only to the particular data identified by this path. -When used to provide search suggestion content, it must be appended +<dd>A complete URI path for a subset of content provider data. +Permission can be granted only to the particular data identified by this path. +When used to provide search suggestion content, it must be appended with "/search_suggest_query". </dd> @@ -47,24 +47,24 @@ Permission can be granted to all data subsets with paths that share this initial <dt><a name="pathPattern"></a>{@code android:pathPattern}</dt> <dd>A complete URI path for a subset of content provider data, but one that can use the following wildcards: - -<ul> + +<ul> <li>An asterisk ('<code class="Code prettyprint">*</code>'). This matches a sequence of 0 to many occurrences of -the immediately preceding character.</li> - -<li>A period followed by an asterisk ("<code class="Code prettyprint">.*</code>"). This matches any sequence of -0 or more characters.</li> -</ul> - -<p> -Because '<code class="Code prettyprint">\</code>' is used as an escape character when the string is read +the immediately preceding character.</li> + +<li>A period followed by an asterisk ("<code class="Code prettyprint">.*</code>"). This matches any sequence of +0 or more characters.</li> +</ul> + +<p> +Because '<code class="Code prettyprint">\</code>' is used as an escape character when the string is read from XML (before it is parsed as a pattern), you will need to double-escape. -For example, a literal '<code class="Code prettyprint">*</code>' would be written as "<code class="Code prettyprint">\\*</code>" and a -literal '<code class="Code prettyprint">\</code>' would be written as "<code class="Code prettyprint">\\</code>". This is basically +For example, a literal '<code class="Code prettyprint">*</code>' would be written as "<code class="Code prettyprint">\\*</code>" and a +literal '<code class="Code prettyprint">\</code>' would be written as "<code class="Code prettyprint">\\</code>". This is basically the same as what you would need to write if constructing the string in Java code. -</p> -<p> -For more information on these types of patterns, see the descriptions of +</p> +<p> +For more information on these types of patterns, see the descriptions of <a href="/reference/android/os/PatternMatcher.html#PATTERN_LITERAL">PATTERN_LITERAL</a>, <a href="/reference/android/os/PatternMatcher.html#PATTERN_PREFIX">PATTERN_PREFIX</a>, and <a href="/reference/android/os/PatternMatcher.html#PATTERN_SIMPLE_GLOB">PATTERN_SIMPLE_GLOB</a> in the @@ -74,20 +74,20 @@ For more information on these types of patterns, see the descriptions of <dt><a name="permission"></a>{@code android:permission}</dt> <dd>The name of a permission that clients must have in order to read or write the -content provider's data. This attribute is a convenient way of setting a -single permission for both reading and writing. However, the -<code>readPermission</code> and +content provider's data. This attribute is a convenient way of setting a +single permission for both reading and writing. However, the +<code>readPermission</code> and <code>writePermission</code> attributes take precedence over this one. -</dd> +</dd> <dt><a name="readPermission"></a>{@code android:readPermission}</dt> <dd>A permission that clients must have in order to query the content provider. -</dd> +</dd> <dt><a name="writePermission"></a>{@code android:writePermission}</dt> <dd>A permission that clients must have in order to make changes to the data controlled by the content provider. -</dd> +</dd> diff --git a/docs/html/guide/topics/manifest/permission-group-element.jd b/docs/html/guide/topics/manifest/permission-group-element.jd index 3221d4b68c36..85452b534fcf 100644 --- a/docs/html/guide/topics/manifest/permission-group-element.jd +++ b/docs/html/guide/topics/manifest/permission-group-element.jd @@ -20,17 +20,17 @@ permission join the group through the {@code permissionGroup} attribute of the presented together in the user interface. <p> -Note that this element does not declare a permission itself, only a category in -which permissions can be placed. See the -<code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> element for element for information +Note that this element does not declare a permission itself, only a category in +which permissions can be placed. See the +<code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> element for element for information on declaring permissions and assigning them to groups. </p></dd> <dt>attributes:</dt> <dd><dl class="attr"> <dt><a name="desc"></a>{@code android:description}</dt> -<dd>User-readable text that describes the group. The text should be -longer and more explanatory than the label. This attribute must be +<dd>User-readable text that describes the group. The text should be +longer and more explanatory than the label. This attribute must be set as a reference to a string resource. Unlike the {@code label} attribute, it cannot be a raw string.</dd> @@ -39,10 +39,10 @@ attribute, it cannot be a raw string.</dd> as a reference to a drawable resource containing the image definition.</dd> <dt><a name="label"></a>{@code android:label}</dt> -<dd>A user-readable name for the group. As a convenience, the label can -be directly set as a raw string while you're developing the application. -However, when the application is ready to be published, it should be set -as a reference to a string resource, so that it can be localized like other +<dd>A user-readable name for the group. As a convenience, the label can +be directly set as a raw string while you're developing the application. +However, when the application is ready to be published, it should be set +as a reference to a string resource, so that it can be localized like other strings in the user interface.</dd> <dt><a name="nm"></a>{@code android:name}</dt> diff --git a/docs/html/guide/topics/manifest/permission-tree-element.jd b/docs/html/guide/topics/manifest/permission-tree-element.jd index 21d7352331f3..cbfd72cd8465 100644 --- a/docs/html/guide/topics/manifest/permission-tree-element.jd +++ b/docs/html/guide/topics/manifest/permission-tree-element.jd @@ -14,7 +14,7 @@ parent.link=manifest-intro.html <dt>description:</dt> <dd itemprop="description">Declares the base name for a tree of permissions. The application takes -ownership of all names within the tree. It can dynamically add new permissions +ownership of all names within the tree. It can dynamically add new permissions to the tree by calling <code>{@link android.content.pm.PackageManager#addPermission PackageManager.addPermission()}</code>. Names within the tree are separated by periods ('{@code .}'). For example, if the base name is {@code com.example.project.taxes}, permissions like the following might be @@ -25,30 +25,30 @@ added: <br/>{@code com.example.project.taxes.deductions.EXAGGERATE}</p> <p> -Note that this element does not declare a permission itself, only a -namespace in which further permissions can be placed. See the -<code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> +Note that this element does not declare a permission itself, only a +namespace in which further permissions can be placed. See the +<code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> element for information on declaring permissions. <dt>attributes:</dt> <dd><dl class="attr"> <dt><a name="icon"></a>{@code android:icon}</dt> -<dd>An icon representing all the permissions in the tree. This attribute -must be set as a reference to a drawable resource containing the image +<dd>An icon representing all the permissions in the tree. This attribute +must be set as a reference to a drawable resource containing the image definition.</dd> <dt><a name="label"></a>{@code android:label}</dt> -<dd>A user-readable name for the group. As a convenience, the label can -be directly set as a raw string for quick and dirty programming. However, -when the application is ready to be published, it should be set as a -reference to a string resource, so that it can be localized like other +<dd>A user-readable name for the group. As a convenience, the label can +be directly set as a raw string for quick and dirty programming. However, +when the application is ready to be published, it should be set as a +reference to a string resource, so that it can be localized like other strings in the user interface.</dd> <dt><a name="nm"></a>{@code android:name}</dt> -<dd>The name that's at the base of the permission tree. It serves as -a prefix to all permission names in the tree. Java-style scoping should -be used to ensure that the name is unique. The name must have more than -two period-separated segments in its path — for example, +<dd>The name that's at the base of the permission tree. It serves as +a prefix to all permission names in the tree. Java-style scoping should +be used to ensure that the name is unique. The name must have more than +two period-separated segments in its path — for example, {@code com.example.base} is OK, but {@code com.example} is not.</dd> </dl></dd> diff --git a/docs/html/guide/topics/manifest/provider-element.jd b/docs/html/guide/topics/manifest/provider-element.jd index 4b5c0c35bc2c..1947849e56f8 100644 --- a/docs/html/guide/topics/manifest/provider-element.jd +++ b/docs/html/guide/topics/manifest/provider-element.jd @@ -37,41 +37,41 @@ parent.link=manifest-intro.html <dt>description:</dt> <dd itemprop="description"> - Declares a content provider component. A content provider is a subclass of - {@link android.content.ContentProvider} that supplies structured access to data managed by the - application. All content providers in your application must be defined in a + Declares a content provider component. A content provider is a subclass of + {@link android.content.ContentProvider} that supplies structured access to data managed by the + application. All content providers in your application must be defined in a {@code <provider>} element in the manifest file; otherwise, the system is unaware of them and doesn't run them. <p> You only declare content providers that are part of your application. Content providers in other applications that you use in your application should not be declared. - </p> + </p> <p> The Android system stores references to content providers according to an <b>authority</b> - string, part of the provider's <b>content URI</b>. For example, suppose you want to + string, part of the provider's <b>content URI</b>. For example, suppose you want to access a content provider that stores information about health care professionals. To do - this, you call the method + this, you call the method {@link android.content.ContentResolver#query ContentResolver.query()}, which among other arguments takes a URI that identifies the provider: - </p> + </p> <pre> content://com.example.project.healthcareprovider/nurses/rn </pre> <p> The <code>content:</code> <b>scheme</b> identifies the URI as a content URI pointing to - an Android content provider. The authority + an Android content provider. The authority <code>com.example.project.healthcareprovider</code> identifies the provider itself; the - Android system looks up the authority in its list of known providers and their authorities. - The substring <code>nurses/rn</code> is a <b>path</b>, which the content provider can use + Android system looks up the authority in its list of known providers and their authorities. + The substring <code>nurses/rn</code> is a <b>path</b>, which the content provider can use to identify subsets of the provider data. </p> <p> - Notice that when you define your provider in the <code><provider></code> element, you + Notice that when you define your provider in the <code><provider></code> element, you don't include the scheme or the path in the <code>android:name</code> argument, only the - authority. + authority. </p> <p> - For information on using and developing content providers, see the API Guide, + For information on using and developing content providers, see the API Guide, <a href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a>. </p> </dd> @@ -82,8 +82,8 @@ content://com.example.project.healthcareprovider/nurses/rn <dt><a name="auth"></a>{@code android:authorities}</dt> <dd> A list of one or more URI authorities that identify data offered by the content provider. - Multiple authorities are listed by separating their names with a semicolon. - To avoid conflicts, authority names should use a Java-style naming convention + Multiple authorities are listed by separating their names with a semicolon. + To avoid conflicts, authority names should use a Java-style naming convention (such as {@code com.example.provider.cartoonprovider}). Typically, it's the name of the {@link android.content.ContentProvider} subclass that implements the provider <p> @@ -92,92 +92,92 @@ content://com.example.project.healthcareprovider/nurses/rn </dd> <dt><a name="enabled"></a>{@code android:enabled}</dt> - <dd>Whether or not the content provider can be instantiated by the system — - "{@code true}" if it can be, and "{@code false}" if not. The default value + <dd>Whether or not the content provider can be instantiated by the system — + "{@code true}" if it can be, and "{@code false}" if not. The default value is "{@code true}". <p> -The <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element has its own -<code><a href="{@docRoot}guide/topics/manifest/application-element.html#enabled">enabled</a></code> attribute that applies to all -application components, including content providers. The +The <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element has its own +<code><a href="{@docRoot}guide/topics/manifest/application-element.html#enabled">enabled</a></code> attribute that applies to all +application components, including content providers. The <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> and {@code <provider>} attributes must both be "{@code true}" (as they both -are by default) for the content provider to be enabled. If either is +are by default) for the content provider to be enabled. If either is "{@code false}", the provider is disabled; it cannot be instantiated. </p></dd> <dt><a name="exported"></a>{@code android:exported}</dt> <dd> Whether the content provider is available for other applications to use: - <ul> + <ul> <li> <code>true</code>: The provider is available to other applications. Any application can use the provider's content URI to access it, subject to the permissions specified for the provider. </li> <li> - <code>false</code>: The provider is not available to other applications. Set + <code>false</code>: The provider is not available to other applications. Set <code>android:exported="false"</code> to limit access to the provider to your applications. Only applications that have the same user ID (UID) as the provider will have access to it. </li> </ul> <p> - The default value is <code>"true"</code> for applications that set either + The default value is <code>"true"</code> for applications that set either <code><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">android:minSdkVersion</a></code> - or -<code><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">android:targetSdkVersion</a></code> to + or +<code><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">android:targetSdkVersion</a></code> to <code>"16"</code> or lower. For applications that - set either of these attributes to <code>"17"</code> or higher, the default is + set either of these attributes to <code>"17"</code> or higher, the default is <code>"false"</code>. </p> <p> You can set <code>android:exported="false"</code> and still limit access to your - provider by setting permissions with the + provider by setting permissions with the <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#prmsn">permission</a></code> attribute. </p> -</dd> +</dd> <dt><a name="gprmsn"></a>{@code android:grantUriPermissions}</dt> -<dd>Whether or not those who ordinarily would not have permission to +<dd>Whether or not those who ordinarily would not have permission to access the content provider's data can be granted permission to do so, temporarily overcoming the restriction imposed by the <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#rprmsn">readPermission</a></code>, -<code><a href="{@docRoot}guide/topics/manifest/provider-element.html#wprmsn">writePermission</a></code>, and -<code><a href="{@docRoot}guide/topics/manifest/provider-element.html#prmsn">permission</a></code> attributes -— -"{@code true}" if permission can be granted, and "{@code false}" if not. -If "{@code true}", permission can be granted to any of the content -provider's data. If "{@code false}", permission can be granted only -to the data subsets listed in -<code><a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html"><grant-uri-permission></a></code> subelements, +<code><a href="{@docRoot}guide/topics/manifest/provider-element.html#wprmsn">writePermission</a></code>, and +<code><a href="{@docRoot}guide/topics/manifest/provider-element.html#prmsn">permission</a></code> attributes +— +"{@code true}" if permission can be granted, and "{@code false}" if not. +If "{@code true}", permission can be granted to any of the content +provider's data. If "{@code false}", permission can be granted only +to the data subsets listed in +<code><a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html"><grant-uri-permission></a></code> subelements, if any. The default value is "{@code false}". <p> -Granting permission is a way of giving an application component one-time -access to data protected by a permission. For example, when an e-mail -message contains an attachment, the mail application may call upon the -appropriate viewer to open it, even though the viewer doesn't have general -permission to look at all the content provider's data. +Granting permission is a way of giving an application component one-time +access to data protected by a permission. For example, when an e-mail +message contains an attachment, the mail application may call upon the +appropriate viewer to open it, even though the viewer doesn't have general +permission to look at all the content provider's data. </p> -<p> -In such cases, permission is granted by -<code>{@link android.content.Intent#FLAG_GRANT_READ_URI_PERMISSION}</code> -and <code>{@link android.content.Intent#FLAG_GRANT_WRITE_URI_PERMISSION}</code> -flags in the Intent object that activates the component. For example, the -mail application might put {@code FLAG_GRANT_READ_URI_PERMISSION} in the -Intent passed to {@code Context.startActivity()}. The permission is specific -to the URI in the Intent. +<p> +In such cases, permission is granted by +<code>{@link android.content.Intent#FLAG_GRANT_READ_URI_PERMISSION}</code> +and <code>{@link android.content.Intent#FLAG_GRANT_WRITE_URI_PERMISSION}</code> +flags in the Intent object that activates the component. For example, the +mail application might put {@code FLAG_GRANT_READ_URI_PERMISSION} in the +Intent passed to {@code Context.startActivity()}. The permission is specific +to the URI in the Intent. </p> <p> If you enable this feature, either by setting this attribute to "{@code true}" -or by defining <code><a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html"><grant-uri-permission></a></code> -subelements, you must call -<code>{@link android.content.Context#revokeUriPermission -Context.revokeUriPermission()}</code> when a covered URI is deleted from +or by defining <code><a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html"><grant-uri-permission></a></code> +subelements, you must call +<code>{@link android.content.Context#revokeUriPermission +Context.revokeUriPermission()}</code> when a covered URI is deleted from the provider. </p> @@ -187,52 +187,52 @@ element. </p></dd> <dt><a name="icon"></a>{@code android:icon}</dt> -<dd>An icon representing the content provider. -This attribute must be set as a reference to a drawable resource containing -the image definition. If it is not set, the icon specified for the application -as a whole is used instead (see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> +<dd>An icon representing the content provider. +This attribute must be set as a reference to a drawable resource containing +the image definition. If it is not set, the icon specified for the application +as a whole is used instead (see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's <code><a href="{@docRoot}guide/topics/manifest/application-element.html#icon">icon</a></code> attribute).</dd> <dt><a name="init"></a>{@code android:initOrder}</dt> -<dd>The order in which the content provider should be instantiated, -relative to other content providers hosted by the same process. -When there are dependencies among content providers, setting this -attribute for each of them ensures that they are created in the order -required by those dependencies. The value is a simple integer, +<dd>The order in which the content provider should be instantiated, +relative to other content providers hosted by the same process. +When there are dependencies among content providers, setting this +attribute for each of them ensures that they are created in the order +required by those dependencies. The value is a simple integer, with higher numbers being initialized first.</dd> <dt><a name="label"></a>{@code android:label}</dt> -<dd>A user-readable label for the content provided. -If this attribute is not set, the label set for the application as a whole is -used instead (see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's +<dd>A user-readable label for the content provided. +If this attribute is not set, the label set for the application as a whole is +used instead (see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's <code><a href="{@docRoot}guide/topics/manifest/application-element.html#label">label</a></code> attribute). <p> The label should be set as a reference to a string resource, so that -it can be localized like other strings in the user interface. -However, as a convenience while you're developing the application, +it can be localized like other strings in the user interface. +However, as a convenience while you're developing the application, it can also be set as a raw string. </p></dd> <dt><a name="multi"></a>{@code android:multiprocess}</dt> -<dd>Whether or not an instance of the content provider can be created in +<dd>Whether or not an instance of the content provider can be created in every client process — "{@code true}" if instances can run in multiple processes, and "{@code false}" if not. The default value is "{@code false}". <p> -Normally, a content provider is instantiated in the process of the -application that defined it. However, if this flag is set to "{@code true}", -the system can create an instance in every process where there's a client -that wants to interact with it, thus avoiding the overhead of interprocess +Normally, a content provider is instantiated in the process of the +application that defined it. However, if this flag is set to "{@code true}", +the system can create an instance in every process where there's a client +that wants to interact with it, thus avoiding the overhead of interprocess communication. </p></dd> <dt><a name="nm"></a>{@code android:name}</dt> -<dd>The name of the class that implements the content provider, a subclass of -{@link android.content.ContentProvider}. This should be a fully qualified -class name (such as, "{@code com.example.project.TransportationProvider}"). -However, as a shorthand, if the first character of the name is a period, -it is appended to the package name specified in the +<dd>The name of the class that implements the content provider, a subclass of +{@link android.content.ContentProvider}. This should be a fully qualified +class name (such as, "{@code com.example.project.TransportationProvider}"). +However, as a shorthand, if the first character of the name is a period, +it is appended to the package name specified in the <code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> element. <p> @@ -242,58 +242,58 @@ There is no default. The name must be specified. <dt><a name="prmsn"></a>{@code android:permission}</dt> <dd>The name of a permission that clients must have to read or write the -content provider's data. This attribute is a convenient way of setting a -single permission for both reading and writing. However, the -<code><a href="#rprmsn">readPermission</a></code> and +content provider's data. This attribute is a convenient way of setting a +single permission for both reading and writing. However, the +<code><a href="#rprmsn">readPermission</a></code> and <code><a href="#wprmsn">writePermission</a></code> attributes take precedence -over this one. If the <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#rprmsn">readPermission</a></code> +over this one. If the <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#rprmsn">readPermission</a></code> attribute is also set, it controls access for querying the content provider. And if the <code><a href="#wprmsn">writePermission</a></code> attribute is set, it controls access for modifying the provider's data. <p> -For more information on permissions, see the -<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#sectperm">Permissions</a> -section in the introduction and a separate document, +For more information on permissions, see the +<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#sectperm">Permissions</a> +section in the introduction and a separate document, <a href="{@docRoot}guide/topics/security/security.html">Security and Permissions</a>. </p></dd> <dt><a name="proc"></a>{@code android:process}</dt> -<dd>The name of the process in which the content provider should run. Normally, -all components of an application run in the default process created for the -application. It has the same name as the application package. The -<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's -<code><a href="{@docRoot}guide/topics/manifest/application-element.html#proc">process</a></code> -attribute can set a different +<dd>The name of the process in which the content provider should run. Normally, +all components of an application run in the default process created for the +application. It has the same name as the application package. The +<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's +<code><a href="{@docRoot}guide/topics/manifest/application-element.html#proc">process</a></code> +attribute can set a different default for all components. But each component can override the default -with its own {@code process} attribute, allowing you to spread your +with its own {@code process} attribute, allowing you to spread your application across multiple processes. <p> -If the name assigned to this attribute begins with a colon (':'), a new -process, private to the application, is created when it's needed and +If the name assigned to this attribute begins with a colon (':'), a new +process, private to the application, is created when it's needed and the activity runs in that process. -If the process name begins with a lowercase character, the activity will run +If the process name begins with a lowercase character, the activity will run in a global process of that name, provided that it has permission to do so. -This allows components in different applications to share a process, reducing +This allows components in different applications to share a process, reducing resource usage. </p></dd> <dt><a name="rprmsn"></a>{@code android:readPermission}</dt> -<dd>A permission that clients must have to query the content provider. -See also the <code><a href="#prmsn">permission</a></code> and +<dd>A permission that clients must have to query the content provider. +See also the <code><a href="#prmsn">permission</a></code> and <code><a href="#wprmsn">writePermission</a></code> attributes.</dd> <dt><a name="sync"></a>{@code android:syncable}</dt> -<dd>Whether or not the data under the content provider's control -is to be synchronized with data on a server — "{@code true}" +<dd>Whether or not the data under the content provider's control +is to be synchronized with data on a server — "{@code true}" if it is to be synchronized, and "{@code false}" if not.</dd> <dt><a name="wprmsn"></a>{@code android:writePermission}</dt> -<dd>A permission that clients must have to make changes to the data -controlled by the content provider. -See also the <code><a href="#prmsn">permission</a></code> and +<dd>A permission that clients must have to make changes to the data +controlled by the content provider. +See also the <code><a href="#prmsn">permission</a></code> and <code><a href="#rprmsn">readPermission</a></code> attributes.</dd> </dl></dd> diff --git a/docs/html/guide/topics/manifest/receiver-element.jd b/docs/html/guide/topics/manifest/receiver-element.jd index 081a191c38e1..800ee8a6e4c7 100644 --- a/docs/html/guide/topics/manifest/receiver-element.jd +++ b/docs/html/guide/topics/manifest/receiver-element.jd @@ -24,14 +24,14 @@ parent.link=manifest-intro.html <dt>description:</dt> <dd itemprop="description">Declares a broadcast receiver (a {@link android.content.BroadcastReceiver} -subclass) as one of the application's components. Broadcast receivers enable -applications to receive intents that are broadcast by the system or by other +subclass) as one of the application's components. Broadcast receivers enable +applications to receive intents that are broadcast by the system or by other applications, even when other components of the application are not running. <p> There are two ways to make a broadcast receiver known to the system: One is declare it in the manifest file with this element. The other is to create -the receiver dynamically in code and register it with the <code>{@link +the receiver dynamically in code and register it with the <code>{@link android.content.Context#registerReceiver Context.registerReceiver()}</code> method. See the {@link android.content.BroadcastReceiver} class description for more on dynamically created receivers. @@ -40,14 +40,14 @@ for more on dynamically created receivers. <dt>attributes:</dt> <dd><dl class="attr"> <dt><a name="enabled"></a>{@code android:enabled}</dt> -<dd>Whether or not the broadcast receiver can be instantiated by the system — -"{@code true}" if it can be, and "{@code false}" if not. The default value +<dd>Whether or not the broadcast receiver can be instantiated by the system — +"{@code true}" if it can be, and "{@code false}" if not. The default value is "{@code true}". <p> -The <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element has its own -<code><a href="{@docRoot}guide/topics/manifest/application-element.html#enabled">enabled</a></code> attribute that applies to all -application components, including broadcast receivers. The +The <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element has its own +<code><a href="{@docRoot}guide/topics/manifest/application-element.html#enabled">enabled</a></code> attribute that applies to all +application components, including broadcast receivers. The <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> and {@code <receiver>} attributes must both be "{@code true}" for the broadcast receiver to be enabled. If either is "{@code false}", it is @@ -55,72 +55,72 @@ disabled; it cannot be instantiated. </p></dd> <dt><a name="exported"></a>{@code android:exported}</dt> -<dd>Whether or not the broadcast receiver can receive messages from sources -outside its application — "{@code true}" if it can, and "{@code false}" -if not. If "{@code false}", the only messages the broadcast receiver can -receive are those sent by components of the same application or applications -with the same user ID. +<dd>Whether or not the broadcast receiver can receive messages from sources +outside its application — "{@code true}" if it can, and "{@code false}" +if not. If "{@code false}", the only messages the broadcast receiver can +receive are those sent by components of the same application or applications +with the same user ID. <p> -The default value depends on whether the broadcast receiver contains intent filters. +The default value depends on whether the broadcast receiver contains intent filters. The absence of any filters means that it can be invoked only by Intent objects that -specify its exact class name. This implies that the receiver is intended only for -application-internal use (since others would not normally know the class name). +specify its exact class name. This implies that the receiver is intended only for +application-internal use (since others would not normally know the class name). So in this case, the default value is "{@code false}". -On the other hand, the presence of at least one filter implies that the broadcast -receiver is intended to receive intents broadcast by the system or other applications, +On the other hand, the presence of at least one filter implies that the broadcast +receiver is intended to receive intents broadcast by the system or other applications, so the default value is "{@code true}". </p> <p> -This attribute is not the only way to limit a broadcast receiver's external exposure. -You can also use a permission to limit the external entities that can send it messages +This attribute is not the only way to limit a broadcast receiver's external exposure. +You can also use a permission to limit the external entities that can send it messages (see the <code><a href="{@docRoot}guide/topics/manifest/receiver-element.html#prmsn">permission</a></code> attribute). </p></dd> <dt><a name="icon"></a>{@code android:icon}</dt> -<dd>An icon representing the broadcast receiver. This attribute must be set -as a reference to a drawable resource containing the image definition. -If it is not set, the icon specified for the application as a whole is used -instead (see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> +<dd>An icon representing the broadcast receiver. This attribute must be set +as a reference to a drawable resource containing the image definition. +If it is not set, the icon specified for the application as a whole is used +instead (see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's <code><a href="{@docRoot}guide/topics/manifest/application-element.html#icon">icon</a></code> attribute). <p> -The broadcast receiver's icon — whether set here or by the -<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element — is also the -default icon for all the receiver's intent filters (see the -<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> element's -<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html#icon">icon</a></code> attribute). +The broadcast receiver's icon — whether set here or by the +<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element — is also the +default icon for all the receiver's intent filters (see the +<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> element's +<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html#icon">icon</a></code> attribute). </p></dd> <dt><a name="label"></a>{@code android:label}</dt> -<dd>A user-readable label for the broadcast receiver. If this attribute is not -set, the label set for the application as a whole is -used instead (see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's +<dd>A user-readable label for the broadcast receiver. If this attribute is not +set, the label set for the application as a whole is +used instead (see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's <code><a href="{@docRoot}guide/topics/manifest/application-element.html#label">label</a></code> attribute). <p> -The broadcast receiver's label — whether set here or by the -<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element — is also the -default label for all the receiver's intent filters (see the -<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> element's -<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html#label">label</a></code> attribute). +The broadcast receiver's label — whether set here or by the +<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element — is also the +default label for all the receiver's intent filters (see the +<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> element's +<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html#label">label</a></code> attribute). </p> <p> The label should be set as a reference to a string resource, so that -it can be localized like other strings in the user interface. -However, as a convenience while you're developing the application, +it can be localized like other strings in the user interface. +However, as a convenience while you're developing the application, it can also be set as a raw string. </p></dd> <dt><a name="nm"></a>{@code android:name}</dt> -<dd>The name of the class that implements the broadcast receiver, a subclass of -{@link android.content.BroadcastReceiver}. This should be a fully qualified -class name (such as, "{@code com.example.project.ReportReceiver}"). However, -as a shorthand, if the first character of the name is a period (for example, -"{@code . ReportReceiver}"), it is appended to the package name specified in -the <code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> element. +<dd>The name of the class that implements the broadcast receiver, a subclass of +{@link android.content.BroadcastReceiver}. This should be a fully qualified +class name (such as, "{@code com.example.project.ReportReceiver}"). However, +as a shorthand, if the first character of the name is a period (for example, +"{@code . ReportReceiver}"), it is appended to the package name specified in +the <code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> element. <p>Once you publish your application, you <a href="http://android-developers.blogspot.com/2011/06/things-that-cannot-change.html">should not @@ -132,38 +132,38 @@ There is no default. The name must be specified. </p></dd> <dt><a name="prmsn"></a>{@code android:permission}</dt> -<dd>The name of a permission that broadcasters must have to send a +<dd>The name of a permission that broadcasters must have to send a message to the broadcast receiver. -If this attribute is not set, the permission set by the +If this attribute is not set, the permission set by the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's -<code><a href="{@docRoot}guide/topics/manifest/application-element.html#prmsn">permission</a></code> attribute applies -to the broadcast receiver. If neither attribute is set, the receiver +<code><a href="{@docRoot}guide/topics/manifest/application-element.html#prmsn">permission</a></code> attribute applies +to the broadcast receiver. If neither attribute is set, the receiver is not protected by a permission. <p> -For more information on permissions, see the -<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#sectperm">Permissions</a> -section in the introduction and a separate document, +For more information on permissions, see the +<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#sectperm">Permissions</a> +section in the introduction and a separate document, <a href="{@docRoot}guide/topics/security/security.html">Security and Permissions</a>. </p></dd> <dt><a name="proc"></a>{@code android:process}</dt> -<dd>The name of the process in which the broadcast receiver should run. -Normally, all components of an application run in the default process created -for the application. It has the same name as the application package. The -<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's -<code><a href="{@docRoot}guide/topics/manifest/application-element.html#proc">process</a></code> attribute can set a different +<dd>The name of the process in which the broadcast receiver should run. +Normally, all components of an application run in the default process created +for the application. It has the same name as the application package. The +<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's +<code><a href="{@docRoot}guide/topics/manifest/application-element.html#proc">process</a></code> attribute can set a different default for all components. But each component can override the default -with its own {@code process} attribute, allowing you to spread your +with its own {@code process} attribute, allowing you to spread your application across multiple processes. <p> -If the name assigned to this attribute begins with a colon (':'), a new -process, private to the application, is created when it's needed and +If the name assigned to this attribute begins with a colon (':'), a new +process, private to the application, is created when it's needed and the broadcast receiver runs in that process. -If the process name begins with a lowercase character, the receiver will run +If the process name begins with a lowercase character, the receiver will run in a global process of that name, provided that it has permission to do so. -This allows components in different applications to share a process, reducing +This allows components in different applications to share a process, reducing resource usage. </p></dd> </dl></dd> diff --git a/docs/html/guide/topics/manifest/service-element.jd b/docs/html/guide/topics/manifest/service-element.jd index fca85f5793c8..9197a7f03435 100644 --- a/docs/html/guide/topics/manifest/service-element.jd +++ b/docs/html/guide/topics/manifest/service-element.jd @@ -25,108 +25,108 @@ parent.link=manifest-intro.html <dt>description:</dt> <dd itemprop="description">Declares a service (a {@link android.app.Service} subclass) as one -of the application's components. Unlike activities, services lack a -visual user interface. They're used to implement long-running background -operations or a rich communications API that can be called by other +of the application's components. Unlike activities, services lack a +visual user interface. They're used to implement long-running background +operations or a rich communications API that can be called by other applications. <p> All services must be represented by {@code <service>} elements in -the manifest file. Any that are not declared there will not be seen +the manifest file. Any that are not declared there will not be seen by the system and will never be run. </p></dd> <dt>attributes:</dt> <dd><dl class="attr"> <dt><a name="enabled"></a>{@code android:enabled}</dt> -<dd>Whether or not the service can be instantiated by the system — -"{@code true}" if it can be, and "{@code false}" if not. The default value +<dd>Whether or not the service can be instantiated by the system — +"{@code true}" if it can be, and "{@code false}" if not. The default value is "{@code true}". <p> -The <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element has its own -<code><a href="{@docRoot}guide/topics/manifest/application-element.html#enabled">enabled</a></code> attribute that applies to all -application components, including services. The +The <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element has its own +<code><a href="{@docRoot}guide/topics/manifest/application-element.html#enabled">enabled</a></code> attribute that applies to all +application components, including services. The <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> and {@code <service>} attributes must both be "{@code true}" (as they both -are by default) for the service to be enabled. If either is +are by default) for the service to be enabled. If either is "{@code false}", the service is disabled; it cannot be instantiated. </p></dd> <dt><a name="exported"></a>{@code android:exported}</dt> -<dd>Whether or not components of other applications can invoke -the service or interact with it — "{@code true}" if they can, and -"{@code false}" if not. When the value is "{@code false}", only -components of the same application or applications +<dd>Whether or not components of other applications can invoke +the service or interact with it — "{@code true}" if they can, and +"{@code false}" if not. When the value is "{@code false}", only +components of the same application or applications with the same user ID can start the service or bind to it. <p> -The default value depends on whether the service contains intent filters. The -absence of any filters means that it can be invoked only by specifying -its exact class name. This implies that the service is intended only for -application-internal use (since others would not know the class name). So in +The default value depends on whether the service contains intent filters. The +absence of any filters means that it can be invoked only by specifying +its exact class name. This implies that the service is intended only for +application-internal use (since others would not know the class name). So in this case, the default value is "{@code false}". -On the other hand, the presence of at least one filter implies that the service +On the other hand, the presence of at least one filter implies that the service is intended for external use, so the default value is "{@code true}". </p> <p> This attribute is not the only way to limit the exposure of a service to other -applications. You can also use a permission to limit the external entities that -can interact with the service (see the <code><a href="{@docRoot}guide/topics/manifest/service-element.html#prmsn">permission</a></code> +applications. You can also use a permission to limit the external entities that +can interact with the service (see the <code><a href="{@docRoot}guide/topics/manifest/service-element.html#prmsn">permission</a></code> attribute). </p></dd> <dt><a name="icon"></a>{@code android:icon}</dt> -<dd>An icon representing the service. This attribute must be set as a -reference to a drawable resource containing the image definition. -If it is not set, the icon specified for the application -as a whole is used instead (see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> +<dd>An icon representing the service. This attribute must be set as a +reference to a drawable resource containing the image definition. +If it is not set, the icon specified for the application +as a whole is used instead (see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's <code><a href="{@docRoot}guide/topics/manifest/application-element.html#icon">icon</a></code> attribute). </p> <p> -The service's icon — whether set here or by the -<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element — is also the -default icon for all the service's intent filters (see the -<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> element's +The service's icon — whether set here or by the +<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element — is also the +default icon for all the service's intent filters (see the +<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> element's <code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html#icon">icon</a></code> attribute). -</p></dd> +</p></dd> <dt><a name="isolated"></a>{@code android:isolatedProcess}</dt> <dd>If set to true, this service will run under a special process that is isolated from the rest of the system and has no permissions of its own. - The only communication with it is through the Service API + The only communication with it is through the Service API (binding and starting).</dd> <dt><a name="label"></a>{@code android:label}</dt> -<dd>A name for the service that can be displayed to users. -If this attribute is not set, the label set for the application as a whole is -used instead (see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's +<dd>A name for the service that can be displayed to users. +If this attribute is not set, the label set for the application as a whole is +used instead (see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's <code><a href="{@docRoot}guide/topics/manifest/application-element.html#label">label</a></code> attribute). <p> -The service's label — whether set here or by the -<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element — is also the -default label for all the service's intent filters (see the -<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> element's -<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html#label">label</a></code> attribute). +The service's label — whether set here or by the +<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element — is also the +default label for all the service's intent filters (see the +<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> element's +<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html#label">label</a></code> attribute). </p> <p> The label should be set as a reference to a string resource, so that -it can be localized like other strings in the user interface. -However, as a convenience while you're developing the application, +it can be localized like other strings in the user interface. +However, as a convenience while you're developing the application, it can also be set as a raw string. </p></dd> <dt><a name="nm"></a>{@code android:name}</dt> -<dd>The name of the {@link android.app.Service} subclass that implements -the service. This should be a fully qualified class name (such as, -"{@code com.example.project.RoomService}"). However, as a shorthand, if +<dd>The name of the {@link android.app.Service} subclass that implements +the service. This should be a fully qualified class name (such as, +"{@code com.example.project.RoomService}"). However, as a shorthand, if the first character of the name is a period (for example, "{@code .RoomService}"), -it is appended to the package name specified in the -<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> element. +it is appended to the package name specified in the +<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> element. <p>Once you publish your application, you <a href="http://android-developers.blogspot.com/2011/06/things-that-cannot-change.html">should not @@ -138,8 +138,8 @@ There is no default. The name must be specified. </p></dd> <dt><a name="prmsn"></a>{@code android:permission}</dt> -<dd>The name of a permission that an entity must have in order to -launch the service or bind to it. If a caller of +<dd>The name of a permission that an entity must have in order to +launch the service or bind to it. If a caller of <code>{@link android.content.Context#startService startService()}</code>, <code>{@link android.content.Context#bindService bindService()}</code>, or <code>{@link android.content.Context#stopService stopService()}</code>, @@ -147,38 +147,38 @@ has not been granted this permission, the method will not work and the Intent object will not be delivered to the service. <p> -If this attribute is not set, the permission set by the +If this attribute is not set, the permission set by the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's -<code><a href="{@docRoot}guide/topics/manifest/application-element.html#prmsn">permission</a></code> +<code><a href="{@docRoot}guide/topics/manifest/application-element.html#prmsn">permission</a></code> attribute applies to the service. If neither attribute is set, the service is not protected by a permission. </p> <p> -For more information on permissions, see the -<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#perms">Permissions</a> -section in the introduction and a separate document, +For more information on permissions, see the +<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#perms">Permissions</a> +section in the introduction and a separate document, <a href="{@docRoot}guide/topics/security/security.html">Security and Permissions</a>. </p></dd> <dt><a name="proc"></a>{@code android:process}</dt> -<dd>The name of the process where the service is to run. Normally, -all components of an application run in the default process created for the -application. It has the same name as the application package. The -<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's -<code><a href="{@docRoot}guide/topics/manifest/application-element.html#proc">process</a></code> -attribute can set a different +<dd>The name of the process where the service is to run. Normally, +all components of an application run in the default process created for the +application. It has the same name as the application package. The +<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's +<code><a href="{@docRoot}guide/topics/manifest/application-element.html#proc">process</a></code> +attribute can set a different default for all components. But component can override the default -with its own {@code process} attribute, allowing you to spread your +with its own {@code process} attribute, allowing you to spread your application across multiple processes. <p> -If the name assigned to this attribute begins with a colon (':'), a new -process, private to the application, is created when it's needed and +If the name assigned to this attribute begins with a colon (':'), a new +process, private to the application, is created when it's needed and the service runs in that process. -If the process name begins with a lowercase character, the service will run +If the process name begins with a lowercase character, the service will run in a global process of that name, provided that it has permission to do so. -This allows components in different applications to share a process, reducing +This allows components in different applications to share a process, reducing resource usage. </p></dd> </dl></dd> diff --git a/docs/html/guide/topics/manifest/supports-gl-texture-element.jd b/docs/html/guide/topics/manifest/supports-gl-texture-element.jd index ab751c217f05..a72fc818b74b 100644 --- a/docs/html/guide/topics/manifest/supports-gl-texture-element.jd +++ b/docs/html/guide/topics/manifest/supports-gl-texture-element.jd @@ -3,16 +3,16 @@ parent.title=The AndroidManifest.xml File parent.link=manifest-intro.html @jd:body - <div class="sidebox-wrapper"> + <div class="sidebox-wrapper"> <div class="sidebox"> - <img src="{@docRoot}assets/images/icon_play.png" style="float:left;margin:0;padding:0;"> - <p style="color:#669999;padding-top:1em;">Google Play Filtering</p> + <img src="{@docRoot}assets/images/icon_play.png" style="float:left;margin:0;padding:0;"> + <p style="color:#669999;padding-top:1em;">Google Play Filtering</p> <p style="padding-top:1em;">Google Play filters applications according to the texture compression formats that they support, to ensure that they can be installed only on devices that can handle their textures properly. You can use texture compression filtering as a way of targeting specific device types, based on GPU platform.</p> - + <p style="margin-top:1em;">For important information about how Google Play uses <code><supports-gl-texture></code> elements as the basis for filtering, please read <a href="#market-texture-filtering">Google diff --git a/docs/html/guide/topics/manifest/supports-screens-element.jd b/docs/html/guide/topics/manifest/supports-screens-element.jd index a4546fa98f12..ce2bb8d20fd0 100644 --- a/docs/html/guide/topics/manifest/supports-screens-element.jd +++ b/docs/html/guide/topics/manifest/supports-screens-element.jd @@ -74,7 +74,7 @@ screens.</p> transition from Android 1.5 to 1.6, when support for multiple screens was first introduced. You should not use it.</p> </dd> - + <dt><a name="small"></a>{@code android:smallScreens}</dt> <dd>Indicates whether the application supports smaller screen form-factors. A small screen is defined as one with a smaller aspect ratio than @@ -84,14 +84,14 @@ should not use it.</p> the platform can do to make such an application work on a smaller screen. This is {@code "true"} by default. </dd> - + <dt><a name="normal"></a>{@code android:normalScreens}</dt> <dd>Indicates whether an application supports the "normal" screen form-factors. Traditionally this is an HVGA medium density screen, but WQVGA low density and WVGA high density are also considered to be normal. This attribute is "true" by default. </dd> - + <dt><a name="large"></a>{@code android:largeScreens}</dt> <dd>Indicates whether the application supports larger screen form-factors. A large screen is defined as a screen that is significantly larger @@ -116,7 +116,7 @@ generally enable <a href="{@docRoot}guide/practices/screen-compat-mode.html">scr compatibility mode</a>.</p> <p>This attribute was introduced in API level 9.</p> </dd> - + <dt><a name="any"></a>{@code android:anyDensity}</dt> <dd>Indicates whether the application includes resources to accommodate any screen density. @@ -127,14 +127,14 @@ is if your app directly manipulates bitmaps (see the <a href="{@docRoot}guide/practices/screens_support.html#DensityConsiderations">Supporting Multiple Screens</a> document for more information).</p> </dd> - + <dt id="requiresSmallest">{@code android:requiresSmallestWidthDp}</dt> <dd>Specifies the minimum smallestWidth required. The smallestWidth is the shortest dimension of the screen space (in {@code dp} units) that must be available to your application UI—that is, the shortest of the available screen's two dimensions. So, in order for a device to be considered compatible with your application, the device's smallestWidth must be equal to or greater than this value. (Usually, the value you supply for this is the "smallest width" that your layout supports, -regardless of the screen's current orientation.) +regardless of the screen's current orientation.) <p>For example, a typical handset screen has a smallestWidth of 320dp, a 7" tablet has a smallestWidth of 600dp, and a 10" tablet has a smallestWidth of 720dp. These values are generally @@ -209,7 +209,7 @@ screens with a 320dp width, so screen compatibility mode is not applied if your android:largestWidthLimitDp} is larger than 320.</p> <p>This attribute was introduced in API level 13.</p> </dd> - + </dl></dd> diff --git a/docs/html/guide/topics/manifest/uses-library-element.jd b/docs/html/guide/topics/manifest/uses-library-element.jd index aa7ca8287eda..f8d8e62faf58 100644 --- a/docs/html/guide/topics/manifest/uses-library-element.jd +++ b/docs/html/guide/topics/manifest/uses-library-element.jd @@ -3,10 +3,10 @@ parent.title=The AndroidManifest.xml File parent.link=manifest-intro.html @jd:body -<div class="sidebox-wrapper"> +<div class="sidebox-wrapper"> <div class="sidebox"> - <img src="{@docRoot}assets/images/icon_play.png" style="float:left;margin:0;padding:0;"> - <p style="color:#669999;padding-top:1em;">Google Play Filtering</p> + <img src="{@docRoot}assets/images/icon_play.png" style="float:left;margin:0;padding:0;"> + <p style="color:#669999;padding-top:1em;">Google Play Filtering</p> <p style="padding-top:1em;">Google Play uses the <uses-library> elements declared in your app manifest to filter your app from devices that do not meet it's library requirements. For more information about filtering, see the topic diff --git a/docs/html/guide/topics/manifest/uses-permission-element.jd b/docs/html/guide/topics/manifest/uses-permission-element.jd index 32fe21eb89ea..03a0dc15d75f 100644 --- a/docs/html/guide/topics/manifest/uses-permission-element.jd +++ b/docs/html/guide/topics/manifest/uses-permission-element.jd @@ -5,10 +5,10 @@ parent.link=manifest-intro.html <dl class="xml"> -<div class="sidebox-wrapper"> +<div class="sidebox-wrapper"> <div class="sidebox"> -<img src="{@docRoot}assets/images/icon_play.png" style="float:left;margin:0;padding:0;"> -<p style="color:#669999;padding-top:1em;">Google Play Filtering</p> +<img src="{@docRoot}assets/images/icon_play.png" style="float:left;margin:0;padding:0;"> +<p style="color:#669999;padding-top:1em;">Google Play Filtering</p> <p style="clear:left;">In some cases, the permissions that you request through <code><uses-permission></code> can affect how @@ -43,24 +43,24 @@ href="{@docRoot}guide/topics/manifest/uses-feature-element.html#permissions-feat <dt>description:</dt> <dd itemprop="description">Requests a permission that the application must be granted in -order for it to operate correctly. Permissions are granted by the user when the +order for it to operate correctly. Permissions are granted by the user when the application is installed (on devices running Android 5.1 and lower) or while the app is running (on devices running Android 6.0 and higher). <p> -For more information on permissions, see the -<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#perms">Permissions</a></code> +For more information on permissions, see the +<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#perms">Permissions</a></code> section in the introduction and the separate <a href="{@docRoot}guide/topics/security/permissions.html">System Permissions</a> API guide. -A list of permissions defined by the base platform can be found at +A list of permissions defined by the base platform can be found at {@link android.Manifest.permission android.Manifest.permission}. <dt>attributes:</dt> <dd><dl class="attr"> <dt><a name="nm"></a>{@code android:name}</dt> -<dd>The name of the permission. It can be a permission defined by the -application with the <code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> -element, a permission defined by another application, or one of the +<dd>The name of the permission. It can be a permission defined by the +application with the <code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> +element, a permission defined by another application, or one of the standard system permissions (such as {@link android.Manifest.permission#CAMERA "android.permission.CAMERA"} or {@link android.Manifest.permission#READ_CONTACTS diff --git a/docs/html/guide/topics/media/index.jd b/docs/html/guide/topics/media/index.jd index a750c9a8809f..c66ab309515c 100644 --- a/docs/html/guide/topics/media/index.jd +++ b/docs/html/guide/topics/media/index.jd @@ -1,6 +1,6 @@ page.title=Media and Camera page.landing=true -page.landing.intro=Add video, audio, and photo capabilities to your app with Android's robust APIs for playing and recording media. +page.landing.intro=Add video, audio, and photo capabilities to your app with Android's robust APIs for playing and recording media. page.landing.image= @jd:body diff --git a/docs/html/guide/topics/media/jet/jetcreator_manual.jd b/docs/html/guide/topics/media/jet/jetcreator_manual.jd index 214c79eed7b3..c2df25b1a435 100644 --- a/docs/html/guide/topics/media/jet/jetcreator_manual.jd +++ b/docs/html/guide/topics/media/jet/jetcreator_manual.jd @@ -21,7 +21,7 @@ format, that respond in real-time to game play events and user interaction.</p> <p>JET works in conjunction with SONiVOX's Embedded Audio Synthesizer (EAS) which is the MIDI playback device for Android. Both the -JET and EAS engines are integrated into the Android embedded platform through the +JET and EAS engines are integrated into the Android embedded platform through the {@link android.media.JetPlayer} class, as well as inherent in the JET Creator application. As such, the JET content author can be sure that the playback will sound exactly the same in both the JET Creator @@ -387,34 +387,34 @@ JET Creator projects to other people.</p> you first launch JET Creator you are presented with an open dialog like the following.</p> - + <p><img border=0 width=450 height=285 src="{@docRoot}images/jet/jc_open_dlg.png" </p> - - + + <p> <b>Open</b> will open an existing .jtc (JET Creator file) file. Use the browser button to browse to the directory where you have saved your .jtc file.</p> - + <p> <b>New</b> will create a new .jtc file.</p> - + <p> <b>Import</b> will import a JET Archive (.zip) file.</p> - + <p> <b>Cancel</b> will cancel the dialog and exit the application.</p> - - + + <h1>5 Main Window </h1> @@ -457,16 +457,16 @@ Creator Main Window<o:p></o:p></i></p> <p>The buttons along the left side of main window do the following:</p> -<p>Add: +<p>Add: Displays the segment or event window for adding a new segment or event</p> -<p>Revise: +<p>Revise: Displays the segment or event window for updating an existing segment or event</p> -<p>Delete: +<p>Delete: Deletes the selected segment or event (will ask for confirmation)</p> -<p>Move: +<p>Move: Displays the move window which allows you to move selected segments or events in time</p> @@ -476,11 +476,11 @@ in time</p> <p>Dequeue All: Dequeues (deselects) all segments</p> -<p>Play: +<p>Play: Starts playback of all queued segments. This button changes to Stop if any segments are playing</p> -<p>Audition: +<p>Audition: Displays the Audition window (see below)</p> diff --git a/docs/html/guide/topics/media/jetplayer.jd b/docs/html/guide/topics/media/jetplayer.jd index f3d55f90f4ae..0f3212188c6f 100644 --- a/docs/html/guide/topics/media/jetplayer.jd +++ b/docs/html/guide/topics/media/jetplayer.jd @@ -1,5 +1,5 @@ page.title=JetPlayer -parent.title=Multimedia and Camera +parent.title=Multimedia and Camera parent.link=index.html @jd:body diff --git a/docs/html/guide/topics/processes/process-lifecycle.jd b/docs/html/guide/topics/processes/process-lifecycle.jd index 0380f945aef0..47ca1ec8912b 100644 --- a/docs/html/guide/topics/processes/process-lifecycle.jd +++ b/docs/html/guide/topics/processes/process-lifecycle.jd @@ -48,7 +48,7 @@ following conditions hold: at the top of the screen that the user is interacting with (its {@link android.app.Activity#onResume} method has been called).</li> <li> It has a {@link android.content.BroadcastReceiver} that is currently running - (its {@link android.content.BroadcastReceiver#onReceive + (its {@link android.content.BroadcastReceiver#onReceive BroadcastReceiver.onReceive()} method is executing).</li> <li>It has a {@link android.app.Service} that is currently executing code in one of its callbacks ({@link android.app.Service#onCreate Service.onCreate()}, diff --git a/docs/html/guide/topics/providers/calendar-provider.jd b/docs/html/guide/topics/providers/calendar-provider.jd index 3cd4511de9b0..485f3c167630 100644 --- a/docs/html/guide/topics/providers/calendar-provider.jd +++ b/docs/html/guide/topics/providers/calendar-provider.jd @@ -42,7 +42,7 @@ page.title=Calendar Provider <li><a href="#intent-view">Using intents to view calendar data</a></li> </ol> </li> - + <li><a href="#sync-adapter">Sync Adapters</a></li> </ol> @@ -63,8 +63,8 @@ operations on calendars, events, attendees, reminders, and so on.</p> <p>The Calender Provider API can be used by applications and sync adapters. The rules vary depending on what type of program is making the calls. This document -focuses primarily on using the Calendar Provider API as an application. For -a discussion of how sync adapters are different, see +focuses primarily on using the Calendar Provider API as an application. For +a discussion of how sync adapters are different, see <a href="#sync-adapter">Sync Adapters</a>.</p> @@ -79,17 +79,17 @@ nor does it need to provide a user interface to view or create events.</p> <h2 id="overview">Basics</h2> -<p><a href="{@docRoot}guide/topics/providers/content-providers.html">Content providers</a> store data and make it accessible to +<p><a href="{@docRoot}guide/topics/providers/content-providers.html">Content providers</a> store data and make it accessible to applications. The content providers offered by the Android platform (including the Calendar Provider) typically expose data as a set of tables based on a relational database model, where each row is a record and each column is data of a particular type and meaning. Through the Calendar Provider API, applications and sync adapters can get read/write access to the database tables that hold a user's calendar data.</p> -<p>Every content provider exposes a public URI (wrapped as a -{@link android.net.Uri} +<p>Every content provider exposes a public URI (wrapped as a +{@link android.net.Uri} object) that uniquely identifies its data set. A content provider that controls - multiple data sets (multiple tables) exposes a separate URI for each one. All + multiple data sets (multiple tables) exposes a separate URI for each one. All URIs for providers begin with the string "content://". This identifies the data as being controlled by a content provider. The Calendar Provider defines constants for the URIs for each of its classes (tables). These @@ -113,26 +113,26 @@ main tables and the fields that link them to each other.</p> </tr> <tr> <td><p>{@link android.provider.CalendarContract.Calendars}</p></td> - - <td>This table holds + + <td>This table holds the calendar-specific information. Each row in this table contains the details for a single calendar, such as the name, color, sync information, and so on.</td> </tr> <tr> <td>{@link android.provider.CalendarContract.Events}</td> - + <td>This table holds the event-specific information. Each row in this table has the information for a single event—for example, event title, location, start time, end time, and so on. The event can occur one-time or can recur multiple times. Attendees, -reminders, and extended properties are stored in separate tables. -They each have an {@link android.provider.CalendarContract.AttendeesColumns#EVENT_ID} +reminders, and extended properties are stored in separate tables. +They each have an {@link android.provider.CalendarContract.AttendeesColumns#EVENT_ID} that references the {@link android.provider.BaseColumns#_ID} in the Events table.</td> </tr> <tr> <td>{@link android.provider.CalendarContract.Instances}</td> - + <td>This table holds the start and end time for each occurrence of an event. Each row in this table represents a single event occurrence. For one-time events there is a 1:1 mapping @@ -141,7 +141,7 @@ of instances to events. For recurring events, multiple rows are automatically </tr> <tr> <td>{@link android.provider.CalendarContract.Attendees}</td> - + <td>This table holds the event attendee (guest) information. Each row represents a single guest of an event. It specifies the type of guest and the guest's attendance response @@ -149,17 +149,17 @@ for the event.</td> </tr> <tr> <td>{@link android.provider.CalendarContract.Reminders}</td> - + <td>This table holds the alert/notification data. Each row represents a single alert for an event. An event can have multiple reminders. The maximum number of reminders per event is -specified in -{@link android.provider.CalendarContract.CalendarColumns#MAX_REMINDERS}, +specified in +{@link android.provider.CalendarContract.CalendarColumns#MAX_REMINDERS}, which is set by the sync adapter that owns the given calendar. Reminders are specified in minutes before the event and have a method that determines how the user will be alerted.</td> </tr> - + </table> <p>The Calendar Provider API is designed to be flexible and powerful. At the @@ -178,9 +178,9 @@ Intents</a>.</p> <li><strong>Sync adapters.</strong> A sync adapter synchronizes the calendar data -on a user's device with another server or data source. In the +on a user's device with another server or data source. In the {@link android.provider.CalendarContract.Calendars} and -{@link android.provider.CalendarContract.Events} tables, +{@link android.provider.CalendarContract.Events} tables, there are columns that are reserved for the sync adapters to use. The provider and applications should not modify them. In fact, they are not visible unless they are accessed as a sync adapter. For more information about @@ -209,9 +209,9 @@ to delete, insert or update calendar data:</p> <h2 id="calendar">Calendars Table</h2> -<p>The {@link android.provider.CalendarContract.Calendars} table contains details +<p>The {@link android.provider.CalendarContract.Calendars} table contains details for individual calendars. The following -Calendars columns are writable by both an application and a <a href="#sync-adapter">sync adapter</a>. +Calendars columns are writable by both an application and a <a href="#sync-adapter">sync adapter</a>. For a full list of supported fields, see the {@link android.provider.CalendarContract.Calendars} reference.</p> <table> @@ -229,7 +229,7 @@ For a full list of supported fields, see the </tr> <tr> <td>{@link android.provider.CalendarContract.Calendars#VISIBLE}</td> - + <td>A boolean indicating whether the calendar is selected to be displayed. A value of 0 indicates that events associated with this calendar should not be shown. A value of 1 indicates that events associated with this calendar should @@ -240,7 +240,7 @@ android.provider.CalendarContract.Instances} table.</td> </tr> <tr> <td>{@link android.provider.CalendarContract.CalendarColumns#SYNC_EVENTS}</td> - + <td>A boolean indicating whether the calendar should be synced and have its events stored on the device. A value of 0 says do not sync this calendar or store its events on the device. A value of 1 says sync events for this calendar @@ -253,8 +253,8 @@ and store its events on the device.</td> <p>Here is an example that shows how to get the calendars that are owned by a particular user. For simplicity's sake, in this example the query operation is shown in the user interface thread ("main thread"). In practice, this should be done in an asynchronous -thread instead of on the main thread. For more discussion, see -<a href="{@docRoot}guide/components/loaders.html">Loaders</a>. If you are not just +thread instead of on the main thread. For more discussion, see +<a href="{@docRoot}guide/components/loaders.html">Loaders</a>. If you are not just reading data but modifying it, see {@link android.content.AsyncQueryHandler}. </p> @@ -268,18 +268,18 @@ public static final String[] EVENT_PROJECTION = new String[] { Calendars.CALENDAR_DISPLAY_NAME, // 2 Calendars.OWNER_ACCOUNT // 3 }; - + // The indices for the projection array above. private static final int PROJECTION_ID_INDEX = 0; private static final int PROJECTION_ACCOUNT_NAME_INDEX = 1; private static final int PROJECTION_DISPLAY_NAME_INDEX = 2; private static final int PROJECTION_OWNER_ACCOUNT_INDEX = 3;</pre> - + <div class="sidebox-wrapper"> <div class="sidebox"> <h3>Why must you include ACCOUNT_TYPE?</h3> <p>If you query on a {@link android.provider.CalendarContract.Calendars#ACCOUNT_NAME -Calendars.ACCOUNT_NAME}, you must also include +Calendars.ACCOUNT_NAME}, you must also include {@link android.provider.CalendarContract.Calendars#ACCOUNT_TYPE Calendars.ACCOUNT_TYPE} in the selection. That is because a given account is only considered unique given both its <code>ACCOUNT_NAME</code> and its @@ -289,7 +289,7 @@ account authenticator that was used when the account was registered with the android.provider.CalendarContract#ACCOUNT_TYPE_LOCAL} for calendars not associated with a device account. {@link android.provider.CalendarContract#ACCOUNT_TYPE_LOCAL} accounts do not get -synced.</p> </div> </div> +synced.</p> </div> </div> <p> In the next part of the example, you construct your query. The selection @@ -301,59 +301,59 @@ calendars that have the <code>ACCOUNT_NAME</code> has viewed, not just calendars the user owns, omit the <code>OWNER_ACCOUNT</code>. The query returns a {@link android.database.Cursor} object that you can use to traverse the result set returned by the database -query. For more discussion of using queries in content providers, +query. For more discussion of using queries in content providers, see <a href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a>.</p> <pre>// Run query Cursor cur = null; ContentResolver cr = getContentResolver(); -Uri uri = Calendars.CONTENT_URI; -String selection = "((" + Calendars.ACCOUNT_NAME + " = ?) AND (" +Uri uri = Calendars.CONTENT_URI; +String selection = "((" + Calendars.ACCOUNT_NAME + " = ?) AND (" + Calendars.ACCOUNT_TYPE + " = ?) AND (" + Calendars.OWNER_ACCOUNT + " = ?))"; String[] selectionArgs = new String[] {"sampleuser@gmail.com", "com.google", - "sampleuser@gmail.com"}; -// Submit the query and get a Cursor object back. + "sampleuser@gmail.com"}; +// Submit the query and get a Cursor object back. cur = cr.query(uri, EVENT_PROJECTION, selection, selectionArgs, null);</pre> <p>This next section uses the cursor to step through the result set. It uses the constants that were set up at the beginning of the example to return the values for each field.</p> - + <pre>// Use the cursor to step through the returned records while (cur.moveToNext()) { long calID = 0; String displayName = null; String accountName = null; String ownerName = null; - + // Get the field values calID = cur.getLong(PROJECTION_ID_INDEX); displayName = cur.getString(PROJECTION_DISPLAY_NAME_INDEX); accountName = cur.getString(PROJECTION_ACCOUNT_NAME_INDEX); ownerName = cur.getString(PROJECTION_OWNER_ACCOUNT_INDEX); - + // Do something with the values... ... } </pre> - + <h3 id="modify-calendar">Modifying a calendar</h3> <p>To perform an update of an calendar, you can provide the {@link android.provider.BaseColumns#_ID} of the calendar either as an appended ID to -the Uri +the Uri -({@link android.content.ContentUris#withAppendedId(android.net.Uri,long) withAppendedId()}) +({@link android.content.ContentUris#withAppendedId(android.net.Uri,long) withAppendedId()}) or as the first selection item. The selection should start with <code>"_id=?"</code>, and the first <code>selectionArg</code> should be the {@link -android.provider.BaseColumns#_ID} of the calendar. +android.provider.BaseColumns#_ID} of the calendar. You can also do updates by encoding the ID in the URI. This example changes a -calendar's display name using the -({@link android.content.ContentUris#withAppendedId(android.net.Uri,long) withAppendedId()}) +calendar's display name using the +({@link android.content.ContentUris#withAppendedId(android.net.Uri,long) withAppendedId()}) approach:</p> <pre>private static final String DEBUG_TAG = "MyActivity"; @@ -375,7 +375,7 @@ an application needs to create a local calendar, it can do this by performing the calendar insertion as a sync adapter, using an {@link android.provider.CalendarContract.SyncColumns#ACCOUNT_TYPE} of {@link android.provider.CalendarContract#ACCOUNT_TYPE_LOCAL}. -{@link android.provider.CalendarContract#ACCOUNT_TYPE_LOCAL} +{@link android.provider.CalendarContract#ACCOUNT_TYPE_LOCAL} is a special account type for calendars that are not associated with a device account. Calendars of this type are not synced to a server. For a discussion of sync adapters, see <a href="#sync-adapter">Sync Adapters</a>.</p> @@ -434,7 +434,7 @@ android.provider.CalendarContract.Events} reference.</p> </tr> <tr> <td>{@link android.provider.CalendarContract.EventsColumns#DURATION}</td> - + <td>The duration of the event in <a href="http://tools.ietf.org/html/rfc5545#section-3.8.2.5">RFC5545</a> format. For example, a value of <code>"PT1H"</code> states that the event @@ -445,41 +445,41 @@ duration of 2 weeks. </td> </tr> <tr> <td>{@link android.provider.CalendarContract.EventsColumns#ALL_DAY}</td> - + <td>A value of 1 indicates this event occupies the entire day, as defined by the local time zone. A value of 0 indicates it is a regular event that may start and end at any time during a day.</td> - + </tr> - - + + <tr> <td>{@link android.provider.CalendarContract.EventsColumns#RRULE}</td> - + <td>The recurrence rule for the event format. For example, <code>"FREQ=WEEKLY;COUNT=10;WKST=SU"</code>. You can find more examples <a href="http://tools.ietf.org/html/rfc5545#section-3.8.5.3">here</a>.</td> - + </tr> - + <tr> <td>{@link android.provider.CalendarContract.EventsColumns#RDATE}</td> - <td>The recurrence dates for the event. - You typically use {@link android.provider.CalendarContract.EventsColumns#RDATE} - in conjunction with {@link android.provider.CalendarContract.EventsColumns#RRULE} + <td>The recurrence dates for the event. + You typically use {@link android.provider.CalendarContract.EventsColumns#RDATE} + in conjunction with {@link android.provider.CalendarContract.EventsColumns#RRULE} to define an aggregate set of repeating occurrences. For more discussion, see the <a href="http://tools.ietf.org/html/rfc5545#section-3.8.5.2">RFC5545 spec</a>.</td> </tr> - + <tr> <td>{@link android.provider.CalendarContract.EventsColumns#AVAILABILITY}</td> - - <td>If this event counts as busy time or is free time that can be + + <td>If this event counts as busy time or is free time that can be scheduled over. </td> - + </tr> <tr> <td>{@link android.provider.CalendarContract.EventsColumns#GUESTS_CAN_MODIFY}</td> @@ -519,11 +519,11 @@ you're inserting an event through the {@link android.content.Intent#ACTION_INSERT INSERT} Intent, described in <a href="#intent-insert">Using an intent to insert an event</a>—in that scenario, a default time zone is supplied.</li> - + <li>For non-recurring events, you must include {@link android.provider.CalendarContract.EventsColumns#DTEND}. </li> - - + + <li>For recurring events, you must include a {@link android.provider.CalendarContract.EventsColumns#DURATION} in addition to {@link android.provider.CalendarContract.EventsColumns#RRULE} or {@link @@ -532,9 +532,9 @@ you're inserting an event through the {@link android.content.Intent#ACTION_INSERT INSERT} Intent, described in <a href="#intent-insert">Using an intent to insert an event</a>—in that scenario, you can use an {@link -android.provider.CalendarContract.EventsColumns#RRULE} in conjunction with {@link android.provider.CalendarContract.EventsColumns#DTSTART} and {@link android.provider.CalendarContract.EventsColumns#DTEND}, and the Calendar application +android.provider.CalendarContract.EventsColumns#RRULE} in conjunction with {@link android.provider.CalendarContract.EventsColumns#DTSTART} and {@link android.provider.CalendarContract.EventsColumns#DTEND}, and the Calendar application converts it to a duration automatically.</li> - + </ul> <p>Here is an example of inserting an event. This is being performed in the UI @@ -545,8 +545,8 @@ information, see {@link android.content.AsyncQueryHandler}.</p> <pre> long calID = 3; -long startMillis = 0; -long endMillis = 0; +long startMillis = 0; +long endMillis = 0; Calendar beginTime = Calendar.getInstance(); beginTime.set(2012, 9, 14, 7, 30); startMillis = beginTime.getTimeInMillis(); @@ -567,7 +567,7 @@ Uri uri = cr.insert(Events.CONTENT_URI, values); // get the event ID that is the last element in the Uri long eventID = Long.parseLong(uri.getLastPathSegment()); -// +// // ... do something with event ID // //</pre> @@ -584,14 +584,14 @@ attendees or reminders to an event.</p> that you use an {@link android.content.Intent#ACTION_EDIT EDIT} Intent, as described in <a href="#intent-edit">Using an intent to edit an event</a>. However, if you need to, you can edit events directly. To perform an update of -an Event, you can provide the <code>_ID</code> of the +an Event, you can provide the <code>_ID</code> of the event either as an appended ID to the Uri ({@link -android.content.ContentUris#withAppendedId(android.net.Uri,long) withAppendedId()}) -or as the first selection item. +android.content.ContentUris#withAppendedId(android.net.Uri,long) withAppendedId()}) +or as the first selection item. The selection should start with <code>"_id=?"</code>, and the first <code>selectionArg</code> should be the <code>_ID</code> of the event. You can also do updates using a selection with no ID. Here is an example of updating an -event. It changes the title of the event using the +event. It changes the title of the event using the {@link android.content.ContentUris#withAppendedId(android.net.Uri,long) withAppendedId()} approach:</p> @@ -604,7 +604,7 @@ ContentResolver cr = getContentResolver(); ContentValues values = new ContentValues(); Uri updateUri = null; // The new title for the event -values.put(Events.TITLE, "Kickboxing"); +values.put(Events.TITLE, "Kickboxing"); updateUri = ContentUris.withAppendedId(Events.CONTENT_URI, eventID); int rows = getContentResolver().update(updateUri, values, null, null); Log.i(DEBUG_TAG, "Rows updated: " + rows); </pre> @@ -631,22 +631,22 @@ ContentValues values = new ContentValues(); Uri deleteUri = null; deleteUri = ContentUris.withAppendedId(Events.CONTENT_URI, eventID); int rows = getContentResolver().delete(deleteUri, null, null); -Log.i(DEBUG_TAG, "Rows deleted: " + rows); +Log.i(DEBUG_TAG, "Rows deleted: " + rows); </pre> <h2 id="attendees">Attendees Table</h2> <p>Each row of the {@link android.provider.CalendarContract.Attendees} table -represents a single attendee or guest of an event. Calling -{@link android.provider.CalendarContract.Reminders#query(android.content.ContentResolver, long, java.lang.String[]) query()} +represents a single attendee or guest of an event. Calling +{@link android.provider.CalendarContract.Reminders#query(android.content.ContentResolver, long, java.lang.String[]) query()} returns a list of attendees for the -event with the given {@link android.provider.CalendarContract.AttendeesColumns#EVENT_ID}. -This {@link android.provider.CalendarContract.AttendeesColumns#EVENT_ID} +event with the given {@link android.provider.CalendarContract.AttendeesColumns#EVENT_ID}. +This {@link android.provider.CalendarContract.AttendeesColumns#EVENT_ID} must match the {@link -android.provider.BaseColumns#_ID} of a particular event.</p> +android.provider.BaseColumns#_ID} of a particular event.</p> <p>The following table lists the -writable fields. When inserting a new attendee, you must include all of them +writable fields. When inserting a new attendee, you must include all of them except <code>ATTENDEE_NAME</code>. </p> @@ -704,7 +704,7 @@ except <code>ATTENDEE_NAME</code>. <h3 id="add-attendees">Adding Attendees</h3> <p>Here is an example that adds a single attendee to an event. Note that the -{@link android.provider.CalendarContract.AttendeesColumns#EVENT_ID} +{@link android.provider.CalendarContract.AttendeesColumns#EVENT_ID} is required:</p> <pre> @@ -724,17 +724,17 @@ Uri uri = cr.insert(Attendees.CONTENT_URI, values); <h2 id="reminders">Reminders Table</h2> <p>Each row of the {@link android.provider.CalendarContract.Reminders} table -represents a single reminder for an event. Calling +represents a single reminder for an event. Calling {@link android.provider.CalendarContract.Reminders#query(android.content.ContentResolver, long, java.lang.String[]) query()} returns a list of reminders for the -event with the given +event with the given {@link android.provider.CalendarContract.AttendeesColumns#EVENT_ID}.</p> <p>The following table lists the writable fields for reminders. All of them must be included when inserting a new reminder. Note that sync adapters specify the types of reminders they support in the {@link -android.provider.CalendarContract.Calendars} table. See -{@link android.provider.CalendarContract.CalendarColumns#ALLOWED_REMINDERS} +android.provider.CalendarContract.Calendars} table. See +{@link android.provider.CalendarContract.CalendarColumns#ALLOWED_REMINDERS} for details.</p> @@ -779,16 +779,16 @@ Uri uri = cr.insert(Reminders.CONTENT_URI, values);</pre> <h2 id="instances">Instances Table</h2> -<p>The +<p>The {@link android.provider.CalendarContract.Instances} table holds the start and end time for occurrences of an event. Each row in this table represents a single event occurrence. The instances table is not writable and only provides a way to query event occurrences. </p> -<p>The following table lists some of the fields you can query on for an instance. Note -that time zone is defined by -{@link android.provider.CalendarContract.CalendarCache#KEY_TIMEZONE_TYPE} -and +<p>The following table lists some of the fields you can query on for an instance. Note +that time zone is defined by +{@link android.provider.CalendarContract.CalendarCache#KEY_TIMEZONE_TYPE} +and {@link android.provider.CalendarContract.CalendarCache#KEY_TIMEZONE_INSTANCES}.</p> @@ -807,18 +807,18 @@ and </tr> <tr> <td>{@link android.provider.CalendarContract.Instances#END_DAY}</td> - + <td>The Julian end day of the instance, relative to the Calendar's time -zone. - +zone. + </td> </tr> <tr> <td>{@link android.provider.CalendarContract.Instances#END_MINUTE}</td> - + <td>The end minute of the instance measured from midnight in the Calendar's time zone.</td> - + </tr> <tr> <td>{@link android.provider.CalendarContract.Instances#EVENT_ID}</td> @@ -826,16 +826,16 @@ Calendar's time zone.</td> </tr> <tr> <td>{@link android.provider.CalendarContract.Instances#START_DAY}</td> - <td>The Julian start day of the instance, relative to the Calendar's time zone. + <td>The Julian start day of the instance, relative to the Calendar's time zone. </td> </tr> <tr> <td>{@link android.provider.CalendarContract.Instances#START_MINUTE}</td> - + <td>The start minute of the instance measured from midnight, relative to the -Calendar's time zone. +Calendar's time zone. </td> - + </tr> </table> @@ -846,7 +846,7 @@ Calendar's time zone. in the URI. In this example, {@link android.provider.CalendarContract.Instances} gets access to the {@link android.provider.CalendarContract.EventsColumns#TITLE} field through its -implementation of the {@link android.provider.CalendarContract.EventsColumns} interface. +implementation of the {@link android.provider.CalendarContract.EventsColumns} interface. In other words, {@link android.provider.CalendarContract.EventsColumns#TITLE} is returned through a database view, not through querying the raw {@link @@ -859,7 +859,7 @@ public static final String[] INSTANCE_PROJECTION = new String[] { Instances.BEGIN, // 1 Instances.TITLE // 2 }; - + // The indices for the projection array above. private static final int PROJECTION_ID_INDEX = 0; private static final int PROJECTION_BEGIN_INDEX = 1; @@ -874,7 +874,7 @@ long startMillis = beginTime.getTimeInMillis(); Calendar endTime = Calendar.getInstance(); endTime.set(2011, 10, 24, 8, 0); long endMillis = endTime.getTimeInMillis(); - + Cursor cur = null; ContentResolver cr = getContentResolver(); @@ -889,28 +889,28 @@ ContentUris.appendId(builder, startMillis); ContentUris.appendId(builder, endMillis); // Submit the query -cur = cr.query(builder.build(), - INSTANCE_PROJECTION, - selection, - selectionArgs, +cur = cr.query(builder.build(), + INSTANCE_PROJECTION, + selection, + selectionArgs, null); - + while (cur.moveToNext()) { String title = null; long eventID = 0; - long beginVal = 0; - + long beginVal = 0; + // Get the field values eventID = cur.getLong(PROJECTION_ID_INDEX); beginVal = cur.getLong(PROJECTION_BEGIN_INDEX); title = cur.getString(PROJECTION_TITLE_INDEX); - - // Do something with the values. - Log.i(DEBUG_TAG, "Event: " + title); + + // Do something with the values. + Log.i(DEBUG_TAG, "Event: " + title); Calendar calendar = Calendar.getInstance(); - calendar.setTimeInMillis(beginVal); + calendar.setTimeInMillis(beginVal); DateFormat formatter = new SimpleDateFormat("MM/dd/yyyy"); - Log.i(DEBUG_TAG, "Date: " + formatter.format(calendar.getTime())); + Log.i(DEBUG_TAG, "Date: " + formatter.format(calendar.getTime())); } }</pre> @@ -928,9 +928,9 @@ while (cur.moveToNext()) { <td><br> {@link android.content.Intent#ACTION_VIEW VIEW} <br></td> <td><p><code>content://com.android.calendar/time/<ms_since_epoch></code></p> - You can also refer to the URI with -{@link android.provider.CalendarContract#CONTENT_URI CalendarContract.CONTENT_URI}. -For an example of using this intent, see <a href="{@docRoot}guide/topics/providers/calendar-provider.html#intent-view">Using intents to view calendar data</a>. + You can also refer to the URI with +{@link android.provider.CalendarContract#CONTENT_URI CalendarContract.CONTENT_URI}. +For an example of using this intent, see <a href="{@docRoot}guide/topics/providers/calendar-provider.html#intent-view">Using intents to view calendar data</a>. </td> <td>Open calendar to the time specified by <code><ms_since_epoch></code>.</td> @@ -941,11 +941,11 @@ For an example of using this intent, see <a href="{@docRoot}guide/topics/provide </td> <td><p><code>content://com.android.calendar/events/<event_id></code></p> - - You can also refer to the URI with -{@link android.provider.CalendarContract.Events#CONTENT_URI Events.CONTENT_URI}. + + You can also refer to the URI with +{@link android.provider.CalendarContract.Events#CONTENT_URI Events.CONTENT_URI}. For an example of using this intent, see <a href="{@docRoot}guide/topics/providers/calendar-provider.html#intent-view">Using intents to view calendar data</a>. - + </td> <td>View the event specified by <code><event_id></code>.</td> @@ -958,12 +958,12 @@ For an example of using this intent, see <a href="{@docRoot}guide/topics/provide <tr> <td>{@link android.content.Intent#ACTION_EDIT EDIT} </td> <td><p><code>content://com.android.calendar/events/<event_id></code></p> - - You can also refer to the URI with -{@link android.provider.CalendarContract.Events#CONTENT_URI Events.CONTENT_URI}. + + You can also refer to the URI with +{@link android.provider.CalendarContract.Events#CONTENT_URI Events.CONTENT_URI}. For an example of using this intent, see <a href="{@docRoot}guide/topics/providers/calendar-provider.html#intent-edit">Using an intent to edit an event</a>. - - + + </td> <td>Edit the event specified by <code><event_id></code>.</td> @@ -978,11 +978,11 @@ For an example of using this intent, see <a href="{@docRoot}guide/topics/provide <br> {@link android.content.Intent#ACTION_INSERT INSERT} </td> <td><p><code>content://com.android.calendar/events</code></p> - - You can also refer to the URI with -{@link android.provider.CalendarContract.Events#CONTENT_URI Events.CONTENT_URI}. + + You can also refer to the URI with +{@link android.provider.CalendarContract.Events#CONTENT_URI Events.CONTENT_URI}. For an example of using this intent, see <a href="{@docRoot}guide/topics/providers/calendar-provider.html#intent-insert">Using an intent to insert an event</a>. - + </td> <td>Create an event.</td> @@ -1002,7 +1002,7 @@ For an example of using this intent, see <a href="{@docRoot}guide/topics/provide <td>Name for the event.</td> </tr> <tr> - + <td>{@link android.provider.CalendarContract#EXTRA_EVENT_BEGIN_TIME CalendarContract.EXTRA_EVENT_BEGIN_TIME}</td> <td>Event begin time in milliseconds from the epoch.</td> @@ -1010,25 +1010,25 @@ CalendarContract.EXTRA_EVENT_BEGIN_TIME}</td> <tr> <td>{@link android.provider.CalendarContract#EXTRA_EVENT_END_TIME CalendarContract.EXTRA_EVENT_END_TIME}</td> - + <td>Event end time in milliseconds from the epoch.</td> </tr> <tr> <td>{@link android.provider.CalendarContract#EXTRA_EVENT_ALL_DAY CalendarContract.EXTRA_EVENT_ALL_DAY}</td> - + <td>A boolean that indicates that an event is all day. Value can be <code>true</code> or <code>false</code>.</td> </tr> <tr> <td>{@link android.provider.CalendarContract.EventsColumns#EVENT_LOCATION Events.EVENT_LOCATION}</td> - + <td>Location of the event.</td> </tr> <tr> <td>{@link android.provider.CalendarContract.EventsColumns#DESCRIPTION Events.DESCRIPTION}</td> - + <td>Event description.</td> </tr> <tr> @@ -1045,16 +1045,16 @@ Events.DESCRIPTION}</td> <td> {@link android.provider.CalendarContract.EventsColumns#ACCESS_LEVEL Events.ACCESS_LEVEL}</td> - + <td>Whether the event is private or public.</td> </tr> <tr> <td>{@link android.provider.CalendarContract.EventsColumns#AVAILABILITY Events.AVAILABILITY}</td> - + <td>If this event counts as busy time or is free time that can be scheduled over.</td> - -</table> + +</table> <p>The following sections describe how to use these intents.</p> @@ -1066,23 +1066,23 @@ With this approach, your application doesn't even need to have the {@link android.Manifest.permission#WRITE_CALENDAR} permission included in its <a href="#manifest">manifest file</a>.</p> - + <p>When users run an application that uses this approach, the application sends them to the Calendar to finish adding the event. The {@link android.content.Intent#ACTION_INSERT INSERT} Intent uses extra fields to pre-populate a form with the details of the event in the Calendar. Users can then cancel the event, edit the form as needed, or save the event to their calendars.</p> - + <p>Here is a code snippet that schedules an event on January 19, 2012, that runs from 7:30 a.m. to 8:30 a.m. Note the following about this code snippet:</p> <ul> - <li>It specifies {@link android.provider.CalendarContract.Events#CONTENT_URI Events.CONTENT_URI} + <li>It specifies {@link android.provider.CalendarContract.Events#CONTENT_URI Events.CONTENT_URI} as the Uri.</li> - + <li>It uses the {@link android.provider.CalendarContract#EXTRA_EVENT_BEGIN_TIME CalendarContract.EXTRA_EVENT_BEGIN_TIME} and {@link @@ -1090,10 +1090,10 @@ android.provider.CalendarContract#EXTRA_EVENT_END_TIME CalendarContract.EXTRA_EVENT_END_TIME} extra fields to pre-populate the form with the time of the event. The values for these times must be in UTC milliseconds from the epoch.</li> - + <li>It uses the {@link android.content.Intent#EXTRA_EMAIL Intent.EXTRA_EMAIL} extra field to provide a comma-separated list of invitees, specified by email address.</li> - + </ul> <pre> Calendar beginTime = Calendar.getInstance(); @@ -1166,18 +1166,18 @@ access the Calendar Provider:</p> <ul> <li>A sync adapter needs to specify that it's a sync adapter by setting {@link android.provider.CalendarContract#CALLER_IS_SYNCADAPTER} to <code>true</code>.</li> - - + + <li>A sync adapter needs to provide an {@link android.provider.CalendarContract.SyncColumns#ACCOUNT_NAME} and an {@link android.provider.CalendarContract.SyncColumns#ACCOUNT_TYPE} as query parameters in the URI. </li> - + <li>A sync adapter has write access to more columns than an application or widget. - For example, an application can only modify a few characteristics of a calendar, + For example, an application can only modify a few characteristics of a calendar, such as its name, display name, visibility setting, and whether the calendar is synced. By comparison, a sync adapter can access not only those columns, but many others, such as calendar color, time zone, access level, location, and so on. -However, a sync adapter is restricted to the <code>ACCOUNT_NAME</code> and +However, a sync adapter is restricted to the <code>ACCOUNT_NAME</code> and <code>ACCOUNT_TYPE</code> it specified.</li> </ul> <p>Here is a helper method you can use to return a URI for use with a sync adapter:</p> @@ -1188,5 +1188,5 @@ However, a sync adapter is restricted to the <code>ACCOUNT_NAME</code> and .appendQueryParameter(Calendars.ACCOUNT_TYPE, accountType).build(); } </pre> -<p>For a sample implementation of a sync adapter (not specifically related to Calendar), see +<p>For a sample implementation of a sync adapter (not specifically related to Calendar), see <a href="{@docRoot}resources/samples/SampleSyncAdapter/index.html">SampleSyncAdapter</a>. diff --git a/docs/html/guide/topics/providers/content-provider-basics.jd b/docs/html/guide/topics/providers/content-provider-basics.jd index b7ae3d2cb85c..37df4e92c66e 100644 --- a/docs/html/guide/topics/providers/content-provider-basics.jd +++ b/docs/html/guide/topics/providers/content-provider-basics.jd @@ -238,7 +238,7 @@ page.title=Content Provider Basics For example, to get a list of the words and their locales from the User Dictionary Provider, you call {@link android.content.ContentResolver#query ContentResolver.query()}. The {@link android.content.ContentResolver#query query()} method calls the - {@link android.content.ContentProvider#query ContentProvider.query()} method defined by the + {@link android.content.ContentProvider#query ContentProvider.query()} method defined by the User Dictionary Provider. The following lines of code show a {@link android.content.ContentResolver#query ContentResolver.query()} call: <p> @@ -253,7 +253,7 @@ mCursor = getContentResolver().query( </pre> <p> Table 2 shows how the arguments to - {@link android.content.ContentResolver#query + {@link android.content.ContentResolver#query query(Uri,projection,selection,selectionArgs,sortOrder)} match an SQL SELECT statement: </p> <p class="table-caption"> @@ -361,8 +361,8 @@ Uri singleUri = ContentUris.withAppendedId(UserDictionary.Words.CONTENT_URI,4); </p> <p class="note"> For the sake of clarity, the code snippets in this section call - {@link android.content.ContentResolver#query ContentResolver.query()} on the "UI thread"". In - actual code, however, you should do queries asynchronously on a separate thread. One way to do + {@link android.content.ContentResolver#query ContentResolver.query()} on the "UI thread"". In + actual code, however, you should do queries asynchronously on a separate thread. One way to do this is to use the {@link android.content.CursorLoader} class, which is described in more detail in the <a href="{@docRoot}guide/components/loaders.html"> Loaders</a> guide. Also, the lines of code are snippets only; they don't show a complete @@ -430,7 +430,7 @@ String[] mSelectionArgs = {""}; <p> The next snippet shows how to use {@link android.content.ContentResolver#query ContentResolver.query()}, using the User Dictionary - Provider as an example. A provider client query is similar to an SQL query, and it contains a + Provider as an example. A provider client query is similar to an SQL query, and it contains a set of columns to return, a set of selection criteria, and a sort order. </p> <p> @@ -440,8 +440,8 @@ String[] mSelectionArgs = {""}; <p> The expression that specifies the rows to retrieve is split into a selection clause and selection arguments. The selection clause is a combination of logical and Boolean expressions, - column names, and values (the variable <code>mSelectionClause</code>). If you specify the - replaceable parameter <code>?</code> instead of a value, the query method retrieves the value + column names, and values (the variable <code>mSelectionClause</code>). If you specify the + replaceable parameter <code>?</code> instead of a value, the query method retrieves the value from the selection arguments array (the variable <code>mSelectionArgs</code>). </p> <p> @@ -567,14 +567,14 @@ selectionArgs[0] = mUserInput; <!-- Displaying the results --> <h3 id="DisplayResults">Displaying query results</h3> <p> - The {@link android.content.ContentResolver#query ContentResolver.query()} client method always - returns a {@link android.database.Cursor} containing the columns specified by the query's - projection for the rows that match the query's selection criteria. A - {@link android.database.Cursor} object provides random read access to the rows and columns it - contains. Using {@link android.database.Cursor} methods, you can iterate over the rows in the + The {@link android.content.ContentResolver#query ContentResolver.query()} client method always + returns a {@link android.database.Cursor} containing the columns specified by the query's + projection for the rows that match the query's selection criteria. A + {@link android.database.Cursor} object provides random read access to the rows and columns it + contains. Using {@link android.database.Cursor} methods, you can iterate over the rows in the results, determine the data type of each column, get the data out of a column, and examine other - properties of the results. Some {@link android.database.Cursor} implementations automatically - update the object when the provider's data changes, or trigger methods in an observer object + properties of the results. Some {@link android.database.Cursor} implementations automatically + update the object when the provider's data changes, or trigger methods in an observer object when the {@link android.database.Cursor} changes, or both. </p> <p class="note"> @@ -705,14 +705,14 @@ if (mCursor != null) { <p> To get the permissions needed to access a provider, an application requests them with a <code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code> - element in its manifest file. When the Android Package Manager installs the application, a user - must approve all of the permissions the application requests. If the user approves all of them, + element in its manifest file. When the Android Package Manager installs the application, a user + must approve all of the permissions the application requests. If the user approves all of them, Package Manager continues the installation; if the user doesn't approve them, Package Manager aborts the installation. </p> <p> The following -<code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code> +<code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code> element requests read access to the User Dictionary Provider: </p> <pre> @@ -795,8 +795,8 @@ content://user_dictionary/words/<id_value> To update a row, you use a {@link android.content.ContentValues} object with the updated values just as you do with an insertion, and selection criteria just as you do with a query. The client method you use is - {@link android.content.ContentResolver#update ContentResolver.update()}. You only need to add - values to the {@link android.content.ContentValues} object for columns you're updating. If you + {@link android.content.ContentResolver#update ContentResolver.update()}. You only need to add + values to the {@link android.content.ContentValues} object for columns you're updating. If you want to clear the contents of a column, set the value to <code>null</code>. </p> <p> @@ -830,7 +830,7 @@ mRowsUpdated = getContentResolver().update( </pre> <p> You should also sanitize user input when you call - {@link android.content.ContentResolver#update ContentResolver.update()}. To learn more about + {@link android.content.ContentResolver#update ContentResolver.update()}. To learn more about this, read the section <a href="#Injection">Protecting against malicious input</a>. </p> <h3 id="Deleting">Deleting data</h3> @@ -860,7 +860,7 @@ mRowsDeleted = getContentResolver().delete( </pre> <p> You should also sanitize user input when you call - {@link android.content.ContentResolver#delete ContentResolver.delete()}. To learn more about + {@link android.content.ContentResolver#delete ContentResolver.delete()}. To learn more about this, read the section <a href="#Injection">Protecting against malicious input</a>. </p> <!-- Provider Data Types --> @@ -948,9 +948,9 @@ mRowsDeleted = getContentResolver().delete( To access a provider in "batch mode", you create an array of {@link android.content.ContentProviderOperation} objects and then dispatch them to a content provider with - {@link android.content.ContentResolver#applyBatch ContentResolver.applyBatch()}. You pass the - content provider's <em>authority</em> to this method, rather than a particular content URI. - This allows each {@link android.content.ContentProviderOperation} object in the array to work + {@link android.content.ContentResolver#applyBatch ContentResolver.applyBatch()}. You pass the + content provider's <em>authority</em> to this method, rather than a particular content URI. + This allows each {@link android.content.ContentProviderOperation} object in the array to work against a different table. A call to {@link android.content.ContentResolver#applyBatch ContentResolver.applyBatch()} returns an array of results. </p> @@ -1013,7 +1013,7 @@ mRowsDeleted = getContentResolver().delete( <p> A provider defines URI permissions for content URIs in its manifest, using the <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#gprmsn">android:grantUriPermission</a></code> - attribute of the + attribute of the <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code> element, as well as the <code><a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html"><grant-uri-permission></a></code> diff --git a/docs/html/guide/topics/providers/content-provider-creating.jd b/docs/html/guide/topics/providers/content-provider-creating.jd index baa92e131dc7..ec6909c89136 100755 --- a/docs/html/guide/topics/providers/content-provider-creating.jd +++ b/docs/html/guide/topics/providers/content-provider-creating.jd @@ -422,7 +422,7 @@ public class ExampleProvider extends ContentProvider { * in the path */ sUriMatcher.addURI("com.example.app.provider", "table3", 1); - + /* * Sets the code for a single row to 2. In this case, the "#" wildcard is * used. "content://com.example.app.provider/table3/3" matches, but @@ -881,7 +881,7 @@ vnd.android.cursor.<strong>item</strong>/vnd.com.example.provider.table1 A contract class also helps developers because it usually has mnemonic names for its constants, so developers are less likely to use incorrect values for column names or URIs. Since it's a class, it can contain Javadoc documentation. Integrated development environments such as - Android Studio can auto-complete constant names from the contract class and display Javadoc for + Android Studio can auto-complete constant names from the contract class and display Javadoc for the constants. </p> <p> diff --git a/docs/html/guide/topics/renderscript/compute.jd b/docs/html/guide/topics/renderscript/compute.jd index fc795ff6a63f..861c9258f2c2 100755 --- a/docs/html/guide/topics/renderscript/compute.jd +++ b/docs/html/guide/topics/renderscript/compute.jd @@ -167,7 +167,7 @@ precision (such as SIMD CPU instructions).</p> </ul> <p>We strongly recommend using the Support Library APIs for accessing RenderScript because they - provide a wider range of device compatibility. Developers targeting specific versions of + provide a wider range of device compatibility. Developers targeting specific versions of Android can use {@link android.renderscript} if necessary.</p> diff --git a/docs/html/guide/topics/resources/accessing-resources.jd b/docs/html/guide/topics/resources/accessing-resources.jd index b971238c1773..953b27418efc 100644 --- a/docs/html/guide/topics/resources/accessing-resources.jd +++ b/docs/html/guide/topics/resources/accessing-resources.jd @@ -264,8 +264,8 @@ reference a system resource, you would need to include the package name. For exa android:text="@string/hello" /> </pre> -<p class="note"><strong>Note:</strong> You should use string resources at -all times, so that your application can be localized for other languages. +<p class="note"><strong>Note:</strong> You should use string resources at +all times, so that your application can be localized for other languages. For information about creating alternative resources (such as localized strings), see <a href="providing-resources.html#AlternativeResources">Providing Alternative diff --git a/docs/html/guide/topics/resources/animation-resource.jd b/docs/html/guide/topics/resources/animation-resource.jd index e5cac8874afb..05582f0e366d 100644 --- a/docs/html/guide/topics/resources/animation-resource.jd +++ b/docs/html/guide/topics/resources/animation-resource.jd @@ -12,7 +12,7 @@ parent.link=available-resources.html <ol> <li><a href="#Tween">Tween animation</a></li> <li><a href="#Frame">Frame animation</a></li> - </ol> + </ol> </li> </ol> <h2>See also</h2> @@ -94,7 +94,7 @@ In XML: <code>@[<em>package</em>:]animator/<em>filename</em></code> </set> </pre> -<p>The file must have a single root element: either +<p>The file must have a single root element: either <code><set></code>, <code><objectAnimator></code>, or <code><valueAnimator></code>. You can group animation elements together inside the <code><set></code> element, including other <code><set></code> elements. @@ -109,7 +109,7 @@ group animation elements together inside the <code><set></code> element, i <code><valueAnimator></code>, or other <code><set></code> elements). Represents an {@link android.animation.AnimatorSet}. <p>You can specify nested <code><set></code> tags to further - group animations together. Each <code><set></code> can define its own + group animations together. Each <code><set></code> can define its own <code>ordering</code> attribute.</p> <p class="caps">attributes:</p> @@ -119,11 +119,11 @@ group animation elements together inside the <code><set></code> element, i </dt> <dd> <em>Keyword</em>. Specifies the play ordering of animations in this set. - <table> - <tr><th>Value</th><th>Description</th></tr> - <tr><td><code>sequentially</code></td><td>Play animations in this set sequentially</td></tr> - <tr><td><code>together</code> (default)</td><td>Play animations in this set at the same time.</td></tr> - </table> + <table> + <tr><th>Value</th><th>Description</th></tr> + <tr><td><code>sequentially</code></td><td>Play animations in this set sequentially</td></tr> + <tr><td><code>together</code> (default)</td><td>Play animations in this set at the same time.</td></tr> + </table> </dd> </dl> </dd> @@ -131,11 +131,11 @@ group animation elements together inside the <code><set></code> element, i <dt id="obj-animator-element"><code><objectAnimator></code></dt> <dd>Animates a specific property of an object over a specific amount of time. Represents an {@link android.animation.ObjectAnimator}.</p> - + <p class="caps">attributes:</p> <dl class="atn-list"> <dt> - <code>android:propertyName</code> + <code>android:propertyName</code> </dt> <dd> <em>String</em>. <strong>Required</strong>. The object's property to animate, referenced by its name. For example you can specify @@ -206,11 +206,11 @@ group animation elements together inside the <code><set></code> element, i <dd> <em>Keyword</em>. Do not specify this attribute if the value is a color. The animation framework automatically handles color values - <table> - <tr><th>Value</th><th>Description</th></tr> - <tr><td><code>intType</code></td><td>Specifies that the animated values are integers</td></tr> - <tr><td><code>floatType</code> (default)</td><td>Specifies that the animated values are floats</td></tr> - </table> + <table> + <tr><th>Value</th><th>Description</th></tr> + <tr><td><code>intType</code></td><td>Specifies that the animated values are integers</td></tr> + <tr><td><code>floatType</code> (default)</td><td>Specifies that the animated values are floats</td></tr> + </table> </dd> </dl> @@ -279,11 +279,11 @@ group animation elements together inside the <code><set></code> element, i <dd> <em>Keyword</em>. Do not specify this attribute if the value is a color. The animation framework automatically handles color values. - <table> - <tr><th>Value</th><th>Description</th></tr> - <tr><td><code>intType</code></td><td>Specifies that the animated values are integers</td></tr> - <tr><td><code>floatType</code> (default)</td><td>Specifies that the animated values are floats</td></tr> - </table> + <table> + <tr><th>Value</th><th>Description</th></tr> + <tr><td><code>intType</code></td><td>Specifies that the animated values are integers</td></tr> + <tr><td><code>floatType</code> (default)</td><td>Specifies that the animated values are floats</td></tr> + </table> </dd> </dl> @@ -320,7 +320,7 @@ group animation elements together inside the <code><set></code> element, i before starting the animation set. Calling {@link android.animation.AnimatorSet#setTarget setTarget()} sets a single target object for all children of the {@link android.animation.AnimatorSet} as a convenience. The following code shows how to do this:</p> - + <pre> AnimatorSet set = (AnimatorSet) AnimatorInflater.loadAnimator(myContext, R.anim.property_animator); diff --git a/docs/html/guide/topics/resources/more-resources.jd b/docs/html/guide/topics/resources/more-resources.jd index 1afbf70731e4..8488cdee7620 100644 --- a/docs/html/guide/topics/resources/more-resources.jd +++ b/docs/html/guide/topics/resources/more-resources.jd @@ -760,7 +760,7 @@ int color = colors.{@link android.content.res.TypedArray#getColor(int,int) getCo </dd> </dl> -</dd> +</dd> <dt>example:</dt> <dd> @@ -781,7 +781,7 @@ int color = colors.{@link android.content.res.TypedArray#getColor(int,int) getCo </dd> </dl> -</dd> +</dd> <dt>see also:</dt> diff --git a/docs/html/guide/topics/resources/providing-resources.jd b/docs/html/guide/topics/resources/providing-resources.jd index c919ed5e777d..80a989a57e28 100644 --- a/docs/html/guide/topics/resources/providing-resources.jd +++ b/docs/html/guide/topics/resources/providing-resources.jd @@ -523,7 +523,7 @@ is <em>larger</em> than the current screen, the system will <strong>not</strong> application will crash at runtime (for example, if all layout resources are tagged with the {@code xlarge} qualifier, but the device is a normal-size screen).</p> <p><em>Added in API level 4.</em></p> - + <p>See <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a> for more information.</p> <p>Also see the {@link android.content.res.Configuration#screenLayout} configuration field, @@ -608,7 +608,7 @@ which indicates the current device orientation.</p> </ul> <p><em>Added in API level 8, television added in API 13, watch added in API 20.</em></p> <p>For information about how your app can respond when the device is inserted into or - removed from a dock, read <a + removed from a dock, read <a href="{@docRoot}training/monitoring-device-state/docking-monitoring.html">Determining and Monitoring the Docking State and Type</a>.</p> <p>This can change during the life of your application if the user places the device in a @@ -659,8 +659,8 @@ application during runtime.</p> Level 8</em></li> <li>{@code xxhdpi}: Extra-extra-high-density screens; approximately 480dpi. <em>Added in API Level 16</em></li> - <li>{@code xxxhdpi}: Extra-extra-extra-high-density uses (launcher icon only, see the - <a href="{@docRoot}guide/practices/screens_support.html#xxxhdpi-note">note</a> + <li>{@code xxxhdpi}: Extra-extra-extra-high-density uses (launcher icon only, see the + <a href="{@docRoot}guide/practices/screens_support.html#xxxhdpi-note">note</a> in <em>Supporting Multiple Screens</em>); approximately 640dpi. <em>Added in API Level 18</em></li> <li>{@code nodpi}: This can be used for bitmap resources that you do not want to be scaled diff --git a/docs/html/guide/topics/resources/runtime-changes.jd b/docs/html/guide/topics/resources/runtime-changes.jd index 8781d208d6ea..2e6f9b765edf 100644 --- a/docs/html/guide/topics/resources/runtime-changes.jd +++ b/docs/html/guide/topics/resources/runtime-changes.jd @@ -84,12 +84,12 @@ your activity to preserve stateful objects.</p> <p>To retain stateful objects in a fragment during a runtime configuration change:</p> <ol> - <li>Extend the {@link android.app.Fragment} class and declare references to your stateful + <li>Extend the {@link android.app.Fragment} class and declare references to your stateful objects.</li> <li>Call {@link android.app.Fragment#setRetainInstance(boolean)} when the fragment is created. </li> <li>Add the fragment to your activity.</li> - <li>Use {@link android.app.FragmentManager} to retrieve the fragment when the activity is + <li>Use {@link android.app.FragmentManager} to retrieve the fragment when the activity is restarted.</li> </ol> @@ -127,8 +127,8 @@ leak all the views and resources of the original activity instance. (Leaking res means that your application maintains a hold on them and they cannot be garbage-collected, so lots of memory can be lost.)</p> -<p>Then use {@link android.app.FragmentManager} to add the fragment to the activity. -You can obtain the data object from the fragment when the activity starts again during runtime +<p>Then use {@link android.app.FragmentManager} to add the fragment to the activity. +You can obtain the data object from the fragment when the activity starts again during runtime configuration changes. For example, define your activity as follows:</p> <pre> @@ -170,7 +170,7 @@ public class MyActivity extends Activity { <p>In this example, {@link android.app.Activity#onCreate(Bundle) onCreate()} adds a fragment or restores a reference to it. {@link android.app.Activity#onCreate(Bundle) onCreate()} also stores the stateful object inside the fragment instance. -{@link android.app.Activity#onDestroy() onDestroy()} updates the stateful object inside the +{@link android.app.Activity#onDestroy() onDestroy()} updates the stateful object inside the retained fragment instance.</p> diff --git a/docs/html/guide/topics/sensors/index.jd b/docs/html/guide/topics/sensors/index.jd index 09d27e7a9bd5..36d3adcb48a3 100644 --- a/docs/html/guide/topics/sensors/index.jd +++ b/docs/html/guide/topics/sensors/index.jd @@ -1,7 +1,7 @@ page.title=Location and Sensors APIs page.landing=true page.tags=location,sensors -page.landing.intro=Use sensors on the device to add rich location and motion capabilities to your app, from GPS or network location to accelerometer, gyroscope, temperature, barometer, and more. +page.landing.intro=Use sensors on the device to add rich location and motion capabilities to your app, from GPS or network location to accelerometer, gyroscope, temperature, barometer, and more. page.landing.image= @jd:body @@ -10,7 +10,7 @@ page.landing.image= <div class="col-6"> <h3>Blog Articles</h3> - + <a href="http://android-developers.blogspot.com/2010/09/one-screen-turn-deserves-another.html"> <h4>One Screen Turn Deserves Another</h4> <p>However, there’s a new wrinkle: recently, a few devices have shipped (see here and here) @@ -18,7 +18,7 @@ that run Android on screens that are naturally landscape in their orientation. T the default position, the screens are wider than they are tall. This introduces a few fairly subtle issues that we’ve noticed causing problems in some apps.</p> </a> - + <a href="http://android-developers.blogspot.com/2011/06/deep-dive-into-location.html"> <h4>A Deep Dive Into Location</h4> <p>I’ve written an open-source reference app that incorporates all of the tips, tricks, and @@ -29,7 +29,7 @@ venues - as well as providing a reasonable level of offline support</p> <div class="col-6"> <h3>Training</h3> - + <a href="http://developer.android.com/training/location/index.html"> <h4>Making Your App Location Aware</h4> <p>This class teaches you how to incorporate location based services in your Android diff --git a/docs/html/guide/topics/text/index.jd b/docs/html/guide/topics/text/index.jd index 3865f25aee71..2bf46967339e 100644 --- a/docs/html/guide/topics/text/index.jd +++ b/docs/html/guide/topics/text/index.jd @@ -9,7 +9,7 @@ page.landing.image= <div class="col-12"> <h3>Blog Articles</h3> - + <a href="http://android-developers.blogspot.com/2011/12/add-voice-typing-to-your-ime.html"> <h4>Add Voice Typing To Your IME</h4> <p>A new feature available in Android 4.0 is voice typing: the difference for users is that diff --git a/docs/html/guide/topics/text/spell-checker-framework.jd b/docs/html/guide/topics/text/spell-checker-framework.jd index a5d9932b26a7..7c059ce157cb 100644 --- a/docs/html/guide/topics/text/spell-checker-framework.jd +++ b/docs/html/guide/topics/text/spell-checker-framework.jd @@ -6,7 +6,7 @@ page.tags=input,spellcheckerservice <h2>In This Document</h2> <ol> <li> - <a href="#SpellCheckLifeCycle">Spell Check Lifecycle</a> + <a href="#SpellCheckLifeCycle">Spell Check Lifecycle</a> </li> <li> <a href="#SpellCheckImplementation">Implementing a Spell Checker Service</a> @@ -30,12 +30,12 @@ page.tags=input,spellcheckerservice </div> <p> - The Android platform offers a spelling checker framework that lets you implement - and access spell checking in your application. The framework is one of the + The Android platform offers a spelling checker framework that lets you implement + and access spell checking in your application. The framework is one of the Text Service APIs offered by the Android platform. </p> <p> - To use the framework in your app, you create a special type of Android service that + To use the framework in your app, you create a special type of Android service that generates a spelling checker <strong>session</strong> object. Based on text you provide, the session object returns spelling suggestions generated by the spelling checker. </p> diff --git a/docs/html/guide/topics/ui/accessibility/apps.jd b/docs/html/guide/topics/ui/accessibility/apps.jd index eb639e37027d..26fb3cca9dc3 100644 --- a/docs/html/guide/topics/ui/accessibility/apps.jd +++ b/docs/html/guide/topics/ui/accessibility/apps.jd @@ -458,7 +458,7 @@ public boolean dispatchPopulateAccessibilityEvent(AccessibilityEvent event) { // Call the super implementation to populate its text to the event, which // calls onPopulateAccessibilityEvent() on API Level 14 and up. boolean completed = super.dispatchPopulateAccessibilityEvent(event); - + // In case this is running on a API revision earlier that 14, check // the text content of the event and add an appropriate text // description for this custom view: diff --git a/docs/html/guide/topics/ui/binding.jd b/docs/html/guide/topics/ui/binding.jd index a4fd25c2825e..48a1d409ef21 100644 --- a/docs/html/guide/topics/ui/binding.jd +++ b/docs/html/guide/topics/ui/binding.jd @@ -16,7 +16,7 @@ parent.link=index.html <pre> -// Get a Spinner and bind it to an ArrayAdapter that +// Get a Spinner and bind it to an ArrayAdapter that // references a String array. Spinner s1 = (Spinner) findViewById(R.id.spinner1); ArrayAdapter<CharSequence> adapter = ArrayAdapter.createFromResource( @@ -31,7 +31,7 @@ private static String[] PROJECTION = new String[] { Spinner s2 = (Spinner) findViewById(R.id.spinner2); Cursor cur = managedQuery(People.CONTENT_URI, PROJECTION, null, null); - + SimpleCursorAdapter adapter2 = new SimpleCursorAdapter(this, android.R.layout.simple_spinner_item, // Use a template // that displays a @@ -41,7 +41,7 @@ SimpleCursorAdapter adapter2 = new SimpleCursorAdapter(this, // people database to... new int[] {android.R.id.text1}); // The "text1" view defined in // the XML template - + adapter2.setDropDownViewResource(android.R.layout.simple_spinner_dropdown_item); s2.setAdapter(adapter2); </pre> @@ -70,7 +70,7 @@ private OnItemClickListener mMessageClickedHandler = new OnItemClickListener() { // Now hook into our object and set its onItemClickListener member // to our class handler object. mHistoryView = (ListView)findViewById(R.id.history); -mHistoryView.setOnItemClickListener(mMessageClickedHandler); +mHistoryView.setOnItemClickListener(mMessageClickedHandler); </pre> <div class="special"> diff --git a/docs/html/guide/topics/ui/controls.jd b/docs/html/guide/topics/ui/controls.jd index a58d9f9b380f..bb8c1a779588 100644 --- a/docs/html/guide/topics/ui/controls.jd +++ b/docs/html/guide/topics/ui/controls.jd @@ -71,7 +71,7 @@ href="{@docRoot}guide/topics/ui/custom-components.html">custom components</a>.</ <tr> <td><a href="controls/radiobutton.html">Radio button</a></td> <td>Similar to checkboxes, except that only one option can be selected in the group.</td> - <td>{@link android.widget.RadioGroup RadioGroup} + <td>{@link android.widget.RadioGroup RadioGroup} <br>{@link android.widget.RadioButton RadioButton} </td> </tr> <tr> diff --git a/docs/html/guide/topics/ui/controls/button.jd b/docs/html/guide/topics/ui/controls/button.jd index 295044f0b55d..a529d533de79 100644 --- a/docs/html/guide/topics/ui/controls/button.jd +++ b/docs/html/guide/topics/ui/controls/button.jd @@ -214,7 +214,7 @@ pressed (activated).</li> <li>The second <code><item></code> defines the bitmap to use when the button is focused (when the button is highlighted using the trackball or directional pad).</li> - <li>The third <code><item></code> defines the bitmap to use when the button is in the + <li>The third <code><item></code> defines the bitmap to use when the button is in the default state (it's neither pressed nor focused).</li> </ul> <p class="note"><strong>Note:</strong> The order of the <code><item></code> elements is diff --git a/docs/html/guide/topics/ui/controls/checkbox.jd b/docs/html/guide/topics/ui/controls/checkbox.jd index 2a64e38d3bf4..f5feeb106a38 100644 --- a/docs/html/guide/topics/ui/controls/checkbox.jd +++ b/docs/html/guide/topics/ui/controls/checkbox.jd @@ -65,7 +65,7 @@ click event for both checkboxes:</p> public void onCheckboxClicked(View view) { // Is the view now checked? boolean checked = ((CheckBox) view).isChecked(); - + // Check which checkbox was clicked switch(view.getId()) { case R.id.checkbox_meat: diff --git a/docs/html/guide/topics/ui/controls/pickers.jd b/docs/html/guide/topics/ui/controls/pickers.jd index c0667add65aa..9788f084022a 100644 --- a/docs/html/guide/topics/ui/controls/pickers.jd +++ b/docs/html/guide/topics/ui/controls/pickers.jd @@ -123,15 +123,15 @@ android.support.v4.app.DialogFragment#show show()}.</p> <p>For example, here's a button that, when clicked, calls a method to show the dialog:</p> <pre> -<Button - android:layout_width="wrap_content" +<Button + android:layout_width="wrap_content" android:layout_height="wrap_content" - android:text="@string/pick_time" + android:text="@string/pick_time" android:onClick="showTimePickerDialog" /> </pre> <p>When the user clicks this button, the system calls the following method:</p> - + <pre> public void showTimePickerDialog(View v) { DialogFragment newFragment = new TimePickerFragment(); @@ -224,15 +224,15 @@ android.support.v4.app.DialogFragment#show show()}.</p> <p>For example, here's a button that, when clicked, calls a method to show the dialog:</p> <pre> -<Button - android:layout_width="wrap_content" +<Button + android:layout_width="wrap_content" android:layout_height="wrap_content" - android:text="@string/pick_date" + android:text="@string/pick_date" android:onClick="showDatePickerDialog" /> </pre> <p>When the user clicks this button, the system calls the following method:</p> - + <pre> public void showDatePickerDialog(View v) { DialogFragment newFragment = new DatePickerFragment(); diff --git a/docs/html/guide/topics/ui/controls/radiobutton.jd b/docs/html/guide/topics/ui/controls/radiobutton.jd index b2556e1956ab..e1441d3f5fbf 100644 --- a/docs/html/guide/topics/ui/controls/radiobutton.jd +++ b/docs/html/guide/topics/ui/controls/radiobutton.jd @@ -72,7 +72,7 @@ click event for both radio buttons:</p> public void onRadioButtonClicked(View view) { // Is the button now checked? boolean checked = ((RadioButton) view).isChecked(); - + // Check which radio button was clicked switch(view.getId()) { case R.id.radio_pirates: diff --git a/docs/html/guide/topics/ui/controls/spinner.jd b/docs/html/guide/topics/ui/controls/spinner.jd index 3b8aaad4613c..00b0432f9f70 100644 --- a/docs/html/guide/topics/ui/controls/spinner.jd +++ b/docs/html/guide/topics/ui/controls/spinner.jd @@ -4,7 +4,7 @@ page.tags=adapterview,spinneradapter <div id="qv-wrapper"> <div id="qv"> - + <h2>In this document</h2> <ol> <li><a href="#Populate">Populate the Spinner with User Choices</a></li> @@ -113,8 +113,8 @@ For example, here's an implementation of the interface in an {@link android.app. <pre> public class SpinnerActivity extends Activity implements OnItemSelectedListener { ... - - public void onItemSelected(AdapterView<?> parent, View view, + + public void onItemSelected(AdapterView<?> parent, View view, int pos, long id) { // An item was selected. You can retrieve the selected item using // parent.getItemAtPosition(pos) diff --git a/docs/html/guide/topics/ui/controls/text.jd b/docs/html/guide/topics/ui/controls/text.jd index f4d72b2a80f6..f5c2a4251788 100644 --- a/docs/html/guide/topics/ui/controls/text.jd +++ b/docs/html/guide/topics/ui/controls/text.jd @@ -4,7 +4,7 @@ page.tags=edittext,autocompletetextview <div id="qv-wrapper"> <div id="qv"> - + <h2>In this document</h2> <ol> <li><a href="#Keyboard">Specifying the Keyboard Type</a> @@ -279,7 +279,7 @@ that provides suggestions from an array, using {@link android.widget.ArrayAdapte layout with only the text field: <pre> <?xml version="1.0" encoding="utf-8"?> -<AutoCompleteTextView xmlns:android="http://schemas.android.com/apk/res/android" +<AutoCompleteTextView xmlns:android="http://schemas.android.com/apk/res/android" android:id="@+id/autocomplete_country" android:layout_width="fill_parent" android:layout_height="wrap_content" /> @@ -313,8 +313,8 @@ code to specify the adapter that supplies the suggestions: AutoCompleteTextView textView = (AutoCompleteTextView) findViewById(R.id.autocomplete_country); // Get the string array String[] countries = getResources().getStringArray(R.array.countries_array); -// Create the adapter and set it to the AutoCompleteTextView -ArrayAdapter<String> adapter = +// Create the adapter and set it to the AutoCompleteTextView +ArrayAdapter<String> adapter = new ArrayAdapter<String>(this, android.R.layout.simple_list_item_1, countries); textView.setAdapter(adapter); </pre> diff --git a/docs/html/guide/topics/ui/custom-components.jd b/docs/html/guide/topics/ui/custom-components.jd index b7249c56ea0b..bd3de1c29a24 100755 --- a/docs/html/guide/topics/ui/custom-components.jd +++ b/docs/html/guide/topics/ui/custom-components.jd @@ -14,37 +14,37 @@ page.tags=view,widget </div> </div> -<p>Android offers a sophisticated and powerful componentized model for building your UI, -based on the fundamental layout classes: {@link android.view.View} and -{@link android.view.ViewGroup}. To start with, the platform includes a variety of prebuilt -View and ViewGroup subclasses — called widgets and layouts, respectively — +<p>Android offers a sophisticated and powerful componentized model for building your UI, +based on the fundamental layout classes: {@link android.view.View} and +{@link android.view.ViewGroup}. To start with, the platform includes a variety of prebuilt +View and ViewGroup subclasses — called widgets and layouts, respectively — that you can use to construct your UI.</p> -<p>A partial list of available widgets includes {@link android.widget.Button Button}, -{@link android.widget.TextView TextView}, -{@link android.widget.EditText EditText}, +<p>A partial list of available widgets includes {@link android.widget.Button Button}, +{@link android.widget.TextView TextView}, +{@link android.widget.EditText EditText}, {@link android.widget.ListView ListView}, -{@link android.widget.CheckBox CheckBox}, -{@link android.widget.RadioButton RadioButton}, -{@link android.widget.Gallery Gallery}, -{@link android.widget.Spinner Spinner}, and the more special-purpose -{@link android.widget.AutoCompleteTextView AutoCompleteTextView}, +{@link android.widget.CheckBox CheckBox}, +{@link android.widget.RadioButton RadioButton}, +{@link android.widget.Gallery Gallery}, +{@link android.widget.Spinner Spinner}, and the more special-purpose +{@link android.widget.AutoCompleteTextView AutoCompleteTextView}, {@link android.widget.ImageSwitcher ImageSwitcher}, and {@link android.widget.TextSwitcher TextSwitcher}. </p> -<p>Among the layouts available are {@link android.widget.LinearLayout LinearLayout}, -{@link android.widget.FrameLayout FrameLayout}, {@link android.widget.RelativeLayout RelativeLayout}, +<p>Among the layouts available are {@link android.widget.LinearLayout LinearLayout}, +{@link android.widget.FrameLayout FrameLayout}, {@link android.widget.RelativeLayout RelativeLayout}, and others. For more examples, see <a href="layout-objects.html">Common Layout Objects</a>.</p> -<p>If none of the prebuilt widgets or layouts meets your needs, you can create your own View subclass. -If you only need to make small adjustments to an existing widget or layout, you can simply subclass +<p>If none of the prebuilt widgets or layouts meets your needs, you can create your own View subclass. +If you only need to make small adjustments to an existing widget or layout, you can simply subclass the widget or layout and override its methods. </p> -<p>Creating your own View subclasses gives you precise control over the appearance and function -of a screen element. To give an idea of the control you get with custom views, here are some +<p>Creating your own View subclasses gives you precise control over the appearance and function +of a screen element. To give an idea of the control you get with custom views, here are some examples of what you could do with them:</p> - + <ul> <li> You could create a completely custom-rendered View type, for example a "volume @@ -60,7 +60,7 @@ examples of what you could do with them:</p> </li> <li> You could override the way that an EditText component is rendered on the screen - (the <a href="{@docRoot}resources/samples/NotePad/index.html">Notepad Tutorial</a> uses this to good effect, + (the <a href="{@docRoot}resources/samples/NotePad/index.html">Notepad Tutorial</a> uses this to good effect, to create a lined-notepad page). </li> <li> @@ -69,7 +69,7 @@ examples of what you could do with them:</p> </li> </ul> <p> -The sections below explain how to create custom Views and use them in your application. +The sections below explain how to create custom Views and use them in your application. For detailed reference information, see the {@link android.view.View} class. </p> @@ -77,26 +77,26 @@ For detailed reference information, see the {@link android.view.View} class. </p <p>Here is a high level overview of what you need to know to get started in creating your own View components:</p> - + <ol> <li> - Extend an existing {@link android.view.View View} class or subclass + Extend an existing {@link android.view.View View} class or subclass with your own class. </li> <li> - Override some of the methods from the superclass. The superclass methods + Override some of the methods from the superclass. The superclass methods to override start with '<code>on</code>', for - example, {@link android.view.View#onDraw onDraw()}, - {@link android.view.View#onMeasure onMeasure()}, and + example, {@link android.view.View#onDraw onDraw()}, + {@link android.view.View#onMeasure onMeasure()}, and {@link android.view.View#onKeyDown onKeyDown()}. - This is similar to the <code>on...</code> events in {@link android.app.Activity Activity} + This is similar to the <code>on...</code> events in {@link android.app.Activity Activity} or {@link android.app.ListActivity ListActivity} that you override for lifecycle and other functionality hooks. <li> - Use your new extension class. Once completed, your new extension class + Use your new extension class. Once completed, your new extension class can be used in place of the view upon which it was based. </li> -</ol> +</ol> <p class="note"><strong>Tip:</strong> Extension classes can be defined as inner classes inside the activities that use them. This is useful because it controls access to them but @@ -119,7 +119,7 @@ way you like, limited perhaps only by your imagination, the size of the screen, and the available processing power (remember that ultimately your application might have to run on something with significantly less power than your desktop workstation).</p> -<p>To create a fully customized component:</p> +<p>To create a fully customized component:</p> <ol> <li> The most generic view you can extend is, unsurprisingly, {@link @@ -170,11 +170,11 @@ slightly more complex by the requirements of limits from the parent (which are passed in to the <code>onMeasure()</code> method) and by the requirement to call the <code>setMeasuredDimension()</code> method with the measured width and height once they have been calculated. If you fail to -call this method from an overridden <code>onMeasure()</code> method, the +call this method from an overridden <code>onMeasure()</code> method, the result will be an exception at measurement time.</p> -<p>At a high level, implementing <code>onMeasure()</code> looks something +<p>At a high level, implementing <code>onMeasure()</code> looks something like this:</p> - + <ol> <li> The overridden <code>onMeasure()</code> method is called with width and @@ -193,7 +193,7 @@ result will be an exception at measurement time.</p> measurement width and height which will be required to render the component. It should try to stay within the specifications passed in, although it can choose to exceed them (in this case, the parent can - choose what to do, including clipping, scrolling, throwing an exception, + choose what to do, including clipping, scrolling, throwing an exception, or asking the <code>onMeasure()</code> to try again, perhaps with different measurement specifications). </li> @@ -212,7 +212,7 @@ Here's a summary of some of the other standard methods that the framework calls <thead> <tr><th>Category</th> <th>Methods</th> <th>Description</th></tr> </thead> - + <tbody> <tr> <td rowspan="2">Creation</td> @@ -228,7 +228,7 @@ Here's a summary of some of the other standard methods that the framework calls <td>Called after a view and all of its children has been inflated from XML.</td> </tr> - + <tr> <td rowspan="3">Layout</td> <td><code>{@link android.view.View#onMeasure}</code></td> @@ -247,14 +247,14 @@ Here's a summary of some of the other standard methods that the framework calls <td>Called when the size of this view has changed. </td> </tr> - + <tr> <td>Drawing</td> <td><code>{@link android.view.View#onDraw}</code></td> <td>Called when the view should render its content. </td> </tr> - + <tr> <td rowspan="4">Event processing</td> <td><code>{@link android.view.View#onKeyDown}</code></td> @@ -265,58 +265,58 @@ Here's a summary of some of the other standard methods that the framework calls <td><code>{@link android.view.View#onKeyUp}</code></td> <td>Called when a key up event occurs. </td> - </tr> + </tr> <tr> <td><code>{@link android.view.View#onTrackballEvent}</code></td> <td>Called when a trackball motion event occurs. </td> - </tr> + </tr> <tr> <td><code>{@link android.view.View#onTouchEvent}</code></td> <td>Called when a touch screen motion event occurs. </td> - </tr> - + </tr> + <tr> <td rowspan="2">Focus</td> <td><code>{@link android.view.View#onFocusChanged}</code></td> <td>Called when the view gains or loses focus. </td> </tr> - + <tr> <td><code>{@link android.view.View#onWindowFocusChanged}</code></td> <td>Called when the window containing the view gains or loses focus. </td> </tr> - + <tr> <td rowspan="3">Attaching</td> <td><code>{@link android.view.View#onAttachedToWindow()}</code></td> <td>Called when the view is attached to a window. </td> </tr> - + <tr> <td><code>{@link android.view.View#onDetachedFromWindow}</code></td> <td>Called when the view is detached from its window. </td> - </tr> - + </tr> + <tr> <td><code>{@link android.view.View#onWindowVisibilityChanged}</code></td> <td>Called when the visibility of the window containing the view has changed. </td> - </tr> + </tr> </tbody> - + </table> <h3 id="customexample">A Custom View Example</h3> -<p>The CustomView sample in the +<p>The CustomView sample in the <a href="{@docRoot}resources/samples/ApiDemos/index.html">API Demos</a> provides an example of a customized View. The custom View is defined in the <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/LabelView.html">LabelView</a> @@ -359,9 +359,9 @@ combination of a single line EditText field and an adjacent button with an attac something from the list, it populates the EditText field, but the user can also type something directly into the EditText if they prefer.</p> <p>In Android, there are actually two other Views readily available to do -this: {@link android.widget.Spinner Spinner} and -{@link android.widget.AutoCompleteTextView AutoCompleteTextView}, but -regardless, the concept of a Combo Box makes an easy-to-understand +this: {@link android.widget.Spinner Spinner} and +{@link android.widget.AutoCompleteTextView AutoCompleteTextView}, but +regardless, the concept of a Combo Box makes an easy-to-understand example.</p> <p>To create a compound component:</p> <ol> @@ -397,7 +397,7 @@ example.</p> <li> In the case of extending a Layout, you don't need to override the <code>onDraw()</code> and <code>onMeasure()</code> methods since the - layout will have default behavior that will likely work just fine. However, + layout will have default behavior that will likely work just fine. However, you can still override them if you need to. </li> <li> @@ -409,7 +409,7 @@ example.</p> <p> To summarize, the use of a Layout as the basis for a Custom Control has a number of advantages, including:</p> - + <ul> <li> You can specify the layout using the declarative XML files just like @@ -433,7 +433,7 @@ number of advantages, including:</p> SpeechView which extends LinearLayout to make a component for displaying Speech quotes. The corresponding classes in the sample code are <code>List4.java</code> and <code>List6.java</code>.</p> - + <h2 id="modifying">Modifying an Existing View Type</h2> @@ -450,7 +450,7 @@ samples. This demonstrates many aspects of using the Android platform, among them is extending an EditText View to make a lined notepad. This is not a perfect example, and the APIs for doing this might change from this early preview, but it does demonstrate the principles.</p> -<p>If you haven't done so already, import the +<p>If you haven't done so already, import the NotePad sample into Android Studio (or just look at the source using the link provided). In particular look at the definition of <code>MyEditText</code> in the <a @@ -462,7 +462,7 @@ file.</p> <strong>The Definition</strong> <p>The class is defined with the following line:<br/> <code>public static class MyEditText extends EditText</code></p> - + <ul> <li> It is defined as an inner class within the <code>NoteEditor</code> @@ -488,7 +488,7 @@ file.</p> </li> <li> <strong>Class Initialization</strong> - <p>As always, the super is called first. Furthermore, + <p>As always, the super is called first. Furthermore, this is not a default constructor, but a parameterized one. The EditText is created with these parameters when it is inflated from an XML layout file, thus, our constructor needs to both take them and pass them @@ -496,7 +496,7 @@ file.</p> </li> <li> <strong>Overridden Methods</strong> - <p>In this example, there is only one method to be overridden: + <p>In this example, there is only one method to be overridden: <code>onDraw()</code> — but there could easily be others needed when you create your own custom components.</p> <p>For the NotePad sample, overriding the <code>onDraw()</code> method allows @@ -513,7 +513,7 @@ file.</p> <code>res/layout</code> folder.</p> <pre> <view - class="com.android.notepad.NoteEditor$MyEditText" + class="com.android.notepad.NoteEditor$MyEditText" id="@+id/note" android:layout_width="fill_parent" android:layout_height="fill_parent" @@ -522,7 +522,7 @@ file.</p> android:scrollbars="vertical" android:fadingEdge="vertical" /> </pre> - + <ul> <li> The custom component is created as a generic view in the XML, and @@ -531,7 +531,7 @@ file.</p> <code>NoteEditor$MyEditText</code> notation which is a standard way to refer to inner classes in the Java programming language. <p>If your custom View component is not defined as an inner class, then you can, - alternatively, declare the View component + alternatively, declare the View component with the XML element name, and exclude the <code>class</code> attribute. For example:</p> <pre> <com.android.notepad.MyEditText diff --git a/docs/html/guide/topics/ui/dialogs.jd b/docs/html/guide/topics/ui/dialogs.jd index e4469eae4e29..7ab4ca552b4d 100644 --- a/docs/html/guide/topics/ui/dialogs.jd +++ b/docs/html/guide/topics/ui/dialogs.jd @@ -32,7 +32,7 @@ page.tags=alertdialog,dialogfragment <li>{@link android.app.DialogFragment}</li> <li>{@link android.app.AlertDialog}</li> </ol> - + <h2>See also</h2> <ol> <li><a href="{@docRoot}design/building-blocks/dialogs.html">Dialogs design guide</a></li> @@ -238,8 +238,8 @@ AlertDialog dialog = builder.create(); </pre> <p>The <code>set...Button()</code> methods require a title for the button (supplied -by a <a href="{@docRoot}guide/topics/resources/string-resource.html">string resource</a>) and a -{@link android.content.DialogInterface.OnClickListener} that defines the action to take +by a <a href="{@docRoot}guide/topics/resources/string-resource.html">string resource</a>) and a +{@link android.content.DialogInterface.OnClickListener} that defines the action to take when the user presses the button.</p> <p>There are three different action buttons you can add:</p> @@ -251,7 +251,7 @@ when the user presses the button.</p> <dt>Neutral</dt> <dd>You should use this when the user may not want to proceed with the action, but doesn't necessarily want to cancel. It appears between the positive and negative - buttons. For example, the action might be "Remind me later."</dd> + buttons. For example, the action might be "Remind me later."</dd> </dl> <p>You can add only one of each button type to an {@link @@ -274,7 +274,7 @@ A dialog with a title and list.</p> <li>A persistent multiple-choice list (checkboxes)</li> </ul> -<p>To create a single-choice list like the one in figure 3, +<p>To create a single-choice list like the one in figure 3, use the {@link android.app.AlertDialog.Builder#setItems setItems()} method:</p> <pre style="clear:right"> @@ -294,7 +294,7 @@ public Dialog onCreateDialog(Bundle savedInstanceState) { <p>Because the list appears in the dialog's content area, the dialog cannot show both a message and a list and you should set a title for the -dialog with {@link android.app.AlertDialog.Builder#setTitle setTitle()}. +dialog with {@link android.app.AlertDialog.Builder#setTitle setTitle()}. To specify the items for the list, call {@link android.app.AlertDialog.Builder#setItems setItems()}, passing an array. Alternatively, you can specify a list using {@link @@ -320,11 +320,11 @@ A list of multiple-choice items.</p> <h4 id="Checkboxes">Adding a persistent multiple-choice or single-choice list</h4> -<p>To add a list of multiple-choice items (checkboxes) or +<p>To add a list of multiple-choice items (checkboxes) or single-choice items (radio buttons), use the {@link android.app.AlertDialog.Builder#setMultiChoiceItems(Cursor,String,String, -DialogInterface.OnMultiChoiceClickListener) setMultiChoiceItems()} or -{@link android.app.AlertDialog.Builder#setSingleChoiceItems(int,int,DialogInterface.OnClickListener) +DialogInterface.OnMultiChoiceClickListener) setMultiChoiceItems()} or +{@link android.app.AlertDialog.Builder#setSingleChoiceItems(int,int,DialogInterface.OnClickListener) setSingleChoiceItems()} methods, respectively.</p> <p>For example, here's how you can create a multiple-choice list like the @@ -349,7 +349,7 @@ public Dialog onCreateDialog(Bundle savedInstanceState) { // If the user checked the item, add it to the selected items mSelectedItems.add(which); } else if (mSelectedItems.contains(which)) { - // Else, if the item is already in the array, remove it + // Else, if the item is already in the array, remove it mSelectedItems.remove(Integer.valueOf(which)); } } @@ -376,7 +376,7 @@ public Dialog onCreateDialog(Bundle savedInstanceState) { <p>Although both a traditional list and a list with radio buttons provide a "single choice" action, you should use {@link -android.app.AlertDialog.Builder#setSingleChoiceItems(int,int,DialogInterface.OnClickListener) +android.app.AlertDialog.Builder#setSingleChoiceItems(int,int,DialogInterface.OnClickListener) setSingleChoiceItems()} if you want to persist the user's choice. That is, if opening the dialog again later should indicate what the user's current choice is, then you create a list with radio buttons.</p> @@ -445,7 +445,7 @@ you should change its font family to {@code "sans-serif"} so that both text fiel a matching font style.</p> <p>To inflate the layout in your {@link android.support.v4.app.DialogFragment}, -get a {@link android.view.LayoutInflater} with +get a {@link android.view.LayoutInflater} with {@link android.app.Activity#getLayoutInflater()} and call {@link android.view.LayoutInflater#inflate inflate()}, where the first parameter is the layout resource ID and the second parameter is a parent view for the layout. @@ -473,7 +473,7 @@ public Dialog onCreateDialog(Bundle savedInstanceState) { public void onClick(DialogInterface dialog, int id) { LoginDialogFragment.this.getDialog().cancel(); } - }); + }); return builder.create(); } </pre> @@ -508,7 +508,7 @@ interface through which it delivers the events back to the host activity:</p> <pre> public class NoticeDialogFragment extends DialogFragment { - + /* The activity that creates an instance of this dialog fragment must * implement this interface in order to receive event callbacks. * Each method passes the DialogFragment in case the host needs to query it. */ @@ -516,10 +516,10 @@ public class NoticeDialogFragment extends DialogFragment { public void onDialogPositiveClick(DialogFragment dialog); public void onDialogNegativeClick(DialogFragment dialog); } - + // Use this instance of the interface to deliver action events NoticeDialogListener mListener; - + // Override the Fragment.onAttach() method to instantiate the NoticeDialogListener @Override public void onAttach(Activity activity) { @@ -546,7 +546,7 @@ events through an implementation of the {@code NoticeDialogListener} interface:< public class MainActivity extends FragmentActivity implements NoticeDialogFragment.NoticeDialogListener{ ... - + public void showNoticeDialog() { // Create an instance of the dialog fragment and show it DialogFragment dialog = new NoticeDialogFragment(); @@ -659,7 +659,7 @@ public class CustomDialogFragment extends DialogFragment { // Inflate the layout to use as dialog or embedded fragment return inflater.inflate(R.layout.purchase_items, container, false); } - + /** The system calls this only when creating the layout in a dialog. */ @Override public Dialog onCreateDialog(Bundle savedInstanceState) { @@ -681,7 +681,7 @@ or a fullscreen UI, based on the screen size:</p> public void showDialog() { FragmentManager fragmentManager = getSupportFragmentManager(); CustomDialogFragment newFragment = new CustomDialogFragment(); - + if (mIsLargeLayout) { // The device is using a large layout, so show the fragment as a dialog newFragment.show(fragmentManager, "dialog"); @@ -781,7 +781,7 @@ android.support.v4.app.DialogFragment#onDismiss onDismiss()} method in your {@li android.support.v4.app.DialogFragment}.</p> <p>You can also <em>cancel</em> a dialog. This is a special event that indicates the user -explicitly left the dialog without completing the task. This occurs if the user presses the +explicitly left the dialog without completing the task. This occurs if the user presses the <em>Back</em> button, touches the screen outside the dialog area, or if you explicitly call {@link android.app.Dialog#cancel()} on the {@link android.app.Dialog} (such as in response to a "Cancel" button in the dialog).</p> diff --git a/docs/html/guide/topics/ui/drag-drop.jd b/docs/html/guide/topics/ui/drag-drop.jd index 4eb54f232568..8871c87f4f25 100644 --- a/docs/html/guide/topics/ui/drag-drop.jd +++ b/docs/html/guide/topics/ui/drag-drop.jd @@ -978,7 +978,7 @@ protected class myDragEventListener implements View.OnDragListener { Log.e("DragDrop Example","Unknown action type received by OnDragListener."); break; } - + return false; } }; diff --git a/docs/html/guide/topics/ui/how-android-draws.jd b/docs/html/guide/topics/ui/how-android-draws.jd index 168f77b265cf..79563692d493 100644 --- a/docs/html/guide/topics/ui/how-android-draws.jd +++ b/docs/html/guide/topics/ui/how-android-draws.jd @@ -4,18 +4,18 @@ parent.link=index.html @jd:body -<p>When an {@link android.app.Activity} receives focus, it will be requested to +<p>When an {@link android.app.Activity} receives focus, it will be requested to draw its layout. -The Android framework will handle the procedure for drawing, but the +The Android framework will handle the procedure for drawing, but the {@link android.app.Activity} must provide the root node of its layout hierarchy.</p> -<p>Drawing begins with the root node of the layout. It is requested to measure and -draw the layout tree. Drawing is handled by walking the tree and rendering each -{@link android.view.View} that intersects the invalid region. In turn, each +<p>Drawing begins with the root node of the layout. It is requested to measure and +draw the layout tree. Drawing is handled by walking the tree and rendering each +{@link android.view.View} that intersects the invalid region. In turn, each {@link android.view.ViewGroup} is responsible for requesting -each of its children to be drawn -(with the {@link android.view.View#draw(Canvas) draw()} method) +each of its children to be drawn +(with the {@link android.view.View#draw(Canvas) draw()} method) and each {@link android.view.View} is responsible for drawing itself. Because the tree is traversed in-order, this means that parents will be drawn before (i.e., behind) their children, with @@ -24,55 +24,55 @@ and each {@link android.view.View} is responsible for drawing itself. <div class="sidebox-wrapper"> <div class="sidebox"> - <p>The framework will not draw {@link android.view.View} objects that are not -in the invalid region, and also + <p>The framework will not draw {@link android.view.View} objects that are not +in the invalid region, and also will take care of drawing the {@link android.view.View} background for you.</p> - <p>You can force a {@link android.view.View} to draw, by calling + <p>You can force a {@link android.view.View} to draw, by calling {@link android.view.View#invalidate()}. </p> </div> </div> <p> - Drawing the layout is a two pass process: a measure pass and a layout pass. -The measuring pass is implemented in {@link android.view.View#measure(int, int)} -and is a top-down traversal of the {@link android.view.View} tree. Each {@link android.view.View} + Drawing the layout is a two pass process: a measure pass and a layout pass. +The measuring pass is implemented in {@link android.view.View#measure(int, int)} +and is a top-down traversal of the {@link android.view.View} tree. Each {@link android.view.View} pushes dimension specifications down the tree - during the recursion. At the end of the measure pass, every + during the recursion. At the end of the measure pass, every {@link android.view.View} has stored its measurements. The second pass happens in {@link android.view.View#layout(int,int,int,int)} and is also top-down. During this pass each parent is responsible for positioning all of its children using the sizes computed in the measure pass. </p> - + <p> - When a {@link android.view.View} object's -{@link android.view.View#measure(int, int) measure()} method + When a {@link android.view.View} object's +{@link android.view.View#measure(int, int) measure()} method returns, its {@link android.view.View#getMeasuredWidth()} and - {@link android.view.View#getMeasuredHeight()} values must be set, along - with those for all of that {@link android.view.View} object's descendants. -A {@link android.view.View} object's measured width and -measured height values must respect the constraints imposed by the + {@link android.view.View#getMeasuredHeight()} values must be set, along + with those for all of that {@link android.view.View} object's descendants. +A {@link android.view.View} object's measured width and +measured height values must respect the constraints imposed by the {@link android.view.View} object's parents. This guarantees that at the end of the measure pass, all parents accept all of their - children's measurements. A parent {@link android.view.View} may call + children's measurements. A parent {@link android.view.View} may call {@link android.view.View#measure(int, int) measure()} more than once on its children. For example, the parent may measure each child once with unspecified dimensions to find out how big they want to be, then call - {@link android.view.View#measure(int, int) measure()} on them again with + {@link android.view.View#measure(int, int) measure()} on them again with actual numbers if the sum of all the children's - unconstrained sizes is too big or too small (that is, if the children + unconstrained sizes is too big or too small (that is, if the children don't agree among themselves - as to how much space they each get, the parent will intervene and set + as to how much space they each get, the parent will intervene and set the rules on the second pass). </p> - + <div class="sidebox-wrapper"> <div class="sidebox"><p> - To initiate a layout, call {@link android.view.View#requestLayout}. + To initiate a layout, call {@link android.view.View#requestLayout}. This method is typically - called by a {@link android.view.View} on itself + called by a {@link android.view.View} on itself when it believes that is can no longer fit within its current bounds.</p> </div> @@ -80,54 +80,54 @@ when it believes that is can no longer fit within <p> The measure pass uses two classes to communicate dimensions. The - {@link android.view.ViewGroup.LayoutParams} class is used by + {@link android.view.ViewGroup.LayoutParams} class is used by {@link android.view.View} objects to tell their parents how they - want to be measured and positioned. The base + want to be measured and positioned. The base {@link android.view.ViewGroup.LayoutParams} class just - describes how big the {@link android.view.View} wants to be for both + describes how big the {@link android.view.View} wants to be for both width and height. For each dimension, it can specify one of:</p> <ul> <li> an exact number - <li>{@link android.view.ViewGroup.LayoutParams#MATCH_PARENT MATCH_PARENT}, + <li>{@link android.view.ViewGroup.LayoutParams#MATCH_PARENT MATCH_PARENT}, which means the {@link android.view.View} wants to be as big as its parent (minus padding)</li> - <li>{@link android.view.ViewGroup.LayoutParams#WRAP_CONTENT WRAP_CONTENT}, + <li>{@link android.view.ViewGroup.LayoutParams#WRAP_CONTENT WRAP_CONTENT}, which means that the {@link android.view.View} wants to be just big enough to enclose its content (plus padding).</li> </ul> - <p>There are subclasses of {@link android.view.ViewGroup.LayoutParams} for + <p>There are subclasses of {@link android.view.ViewGroup.LayoutParams} for different subclasses of {@link android.view.ViewGroup}. - For example, {@link android.widget.RelativeLayout} has its own subclass of + For example, {@link android.widget.RelativeLayout} has its own subclass of {@link android.view.ViewGroup.LayoutParams}, which includes - the ability to center child {@link android.view.View} objects + the ability to center child {@link android.view.View} objects horizontally and vertically. </p> - + <p> - {@link android.view.View.MeasureSpec MeasureSpec} objects are used to push + {@link android.view.View.MeasureSpec MeasureSpec} objects are used to push requirements down the tree from parent to - child. A {@link android.view.View.MeasureSpec MeasureSpec} can be in one of + child. A {@link android.view.View.MeasureSpec MeasureSpec} can be in one of three modes:</p> <ul> - <li>{@link android.view.View.MeasureSpec#UNSPECIFIED UNSPECIFIED}: This is + <li>{@link android.view.View.MeasureSpec#UNSPECIFIED UNSPECIFIED}: This is used by a parent to determine the desired dimension - of a child {@link android.view.View}. For example, a -{@link android.widget.LinearLayout} may call + of a child {@link android.view.View}. For example, a +{@link android.widget.LinearLayout} may call {@link android.view.View#measure(int, int) measure()} on its child - with the height set to {@link android.view.View.MeasureSpec#UNSPECIFIED UNSPECIFIED} -and a width of {@link android.view.View.MeasureSpec#EXACTLY EXACTLY} 240 to -find out how tall the child {@link android.view.View} wants to be given a + with the height set to {@link android.view.View.MeasureSpec#UNSPECIFIED UNSPECIFIED} +and a width of {@link android.view.View.MeasureSpec#EXACTLY EXACTLY} 240 to +find out how tall the child {@link android.view.View} wants to be given a width of 240 pixels.</li> - <li>{@link android.view.View.MeasureSpec#EXACTLY EXACTLY}: This is used + <li>{@link android.view.View.MeasureSpec#EXACTLY EXACTLY}: This is used by the parent to impose an exact size on the child. The child must use this size, and guarantee that all of its descendants will fit within this size.</li> - <li>{@link android.view.View.MeasureSpec#AT_MOST AT MOST}: This is used by + <li>{@link android.view.View.MeasureSpec#AT_MOST AT MOST}: This is used by the parent to impose a maximum size on the child. The child must guarantee that it and all of its descendants will fit within this size.</li> </ul> - + diff --git a/docs/html/guide/topics/ui/index.jd b/docs/html/guide/topics/ui/index.jd index 0725eb73defc..ccdf200ecac6 100644 --- a/docs/html/guide/topics/ui/index.jd +++ b/docs/html/guide/topics/ui/index.jd @@ -1,6 +1,6 @@ page.title=User Interface page.landing=true -page.landing.intro=Your app's user interface is everything that the user can see and interact with. Android provides a variety of pre-built UI components such as structured layout objects and UI controls that allow you to build the graphical user interface for your app. Android also provides other UI modules for special interfaces such as dialogs, notifications, and menus. +page.landing.intro=Your app's user interface is everything that the user can see and interact with. Android provides a variety of pre-built UI components such as structured layout objects and UI controls that allow you to build the graphical user interface for your app. Android also provides other UI modules for special interfaces such as dialogs, notifications, and menus. page.landing.image=images/ui/ui_index.png page.landing.next=overview.html diff --git a/docs/html/guide/topics/ui/layout/grid.jd b/docs/html/guide/topics/ui/layout/grid.jd index 3474f48c9d86..31f9b9ca4ead 100644 --- a/docs/html/guide/topics/ui/layout/grid.jd +++ b/docs/html/guide/topics/ui/layout/grid.jd @@ -32,7 +32,7 @@ cells empty, but cells cannot span columns, as they can in HTML.</p> Each row has zero or more cells, each of which is defined by any kind of other View. So, the cells of a row may be composed of a variety of View objects, like ImageView or TextView objects. A cell may also be a ViewGroup object (for example, you can nest another TableLayout as a cell).</p> -<p>The following sample layout has two rows and two cells in each. The accompanying screenshot shows the +<p>The following sample layout has two rows and two cells in each. The accompanying screenshot shows the result, with cell borders displayed as dotted lines (added for visual effect). </p> <table class="columns"> @@ -71,7 +71,7 @@ result, with cell borders displayed as dotted lines (added for visual effect). < <p>Columns can be hidden, marked to stretch and fill the available screen space, or can be marked as shrinkable to force the column to shrink until the table - fits the screen. See the {@link android.widget.TableLayout TableLayout reference} + fits the screen. See the {@link android.widget.TableLayout TableLayout reference} documentation for more details. </p> diff --git a/docs/html/guide/topics/ui/layout/linear.jd b/docs/html/guide/topics/ui/layout/linear.jd index 7441782f5e6f..4224d17d07a7 100644 --- a/docs/html/guide/topics/ui/layout/linear.jd +++ b/docs/html/guide/topics/ui/layout/linear.jd @@ -59,7 +59,7 @@ href="{@docRoot}reference/android/widget/LinearLayout.LayoutParams.html#attr_and >{@code android:layout_weight}</a> attribute. This attribute assigns an "importance" value to a view in terms of how much space it should occupy on the screen. A larger weight value allows it to expand -to fill any remaining space in the parent view. +to fill any remaining space in the parent view. Child views can specify a weight value, and then any remaining space in the view group is assigned to children in the proportion of their declared weight. Default weight is zero.</p> diff --git a/docs/html/guide/topics/ui/layout/listview.jd b/docs/html/guide/topics/ui/layout/listview.jd index 3c6e32ca41cf..e6e5578e6fd8 100644 --- a/docs/html/guide/topics/ui/layout/listview.jd +++ b/docs/html/guide/topics/ui/layout/listview.jd @@ -80,7 +80,7 @@ public class ListViewLoader extends ListActivity ContactsContract.Data.DISPLAY_NAME}; // This is the select criteria - static final String SELECTION = "((" + + static final String SELECTION = "((" + ContactsContract.Data.DISPLAY_NAME + " NOTNULL) AND (" + ContactsContract.Data.DISPLAY_NAME + " != '' ))"; @@ -105,7 +105,7 @@ public class ListViewLoader extends ListActivity // Create an empty adapter we will use to display the loaded data. // We pass null for the cursor, then update it in onLoadFinished() - mAdapter = new SimpleCursorAdapter(this, + mAdapter = new SimpleCursorAdapter(this, android.R.layout.simple_list_item_1, null, fromColumns, toViews, 0); setListAdapter(mAdapter); @@ -138,7 +138,7 @@ public class ListViewLoader extends ListActivity mAdapter.swapCursor(null); } - @Override + @Override public void onListItemClick(ListView l, View v, int position, long id) { // Do something when a list item is clicked } diff --git a/docs/html/guide/topics/ui/layout/relative.jd b/docs/html/guide/topics/ui/layout/relative.jd index ca5cb4838036..92735ae808bf 100644 --- a/docs/html/guide/topics/ui/layout/relative.jd +++ b/docs/html/guide/topics/ui/layout/relative.jd @@ -38,7 +38,7 @@ make one below another, centered in the screen, centered left, and so on. By def views are drawn at the top-left of the layout, so you must define the position of each view using the various layout properties available from {@link android.widget.RelativeLayout.LayoutParams}.</p> - + <p>Some of the many layout properties available to views in a {@link android.widget.RelativeLayout} include:</p> <dl> diff --git a/docs/html/guide/topics/ui/menus.jd b/docs/html/guide/topics/ui/menus.jd index ad2aa9b8bf29..73dec2095dca 100644 --- a/docs/html/guide/topics/ui/menus.jd +++ b/docs/html/guide/topics/ui/menus.jd @@ -77,9 +77,9 @@ activity. It's where you should place actions that have a global impact on the a "Search," "Compose email," and "Settings." <p>See the section about <a href="#options-menu">Creating an Options Menu</a>.</p> </dd> - + <dt><strong>Context menu and contextual action mode</strong></dt> - + <dd>A context menu is a <a href="#FloatingContextMenu">floating menu</a> that appears when the user performs a long-click on an element. It provides actions that affect the selected content or context frame. @@ -88,7 +88,7 @@ action items that affect the selected content in a bar at the top of the screen to select multiple items.</p> <p>See the section about <a href="#context-menu">Creating Contextual Menus</a>.</p> </dd> - + <dt><strong>Popup menu</strong></dt> <dd>A popup menu displays a list of items in a vertical list that's anchored to the view that invoked the menu. It's good for providing an overflow of actions that relate to specific content or @@ -130,7 +130,7 @@ directory and build the menu with the following elements:</p> <dt><code><item></code></dt> <dd>Creates a {@link android.view.MenuItem}, which represents a single item in a menu. This element may contain a nested <code><menu></code> element in order to create a submenu.</dd> - + <dt><code><group></code></dt> <dd>An optional, invisible container for {@code <item>} elements. It allows you to categorize menu items so they share properties such as active state and visibility. For more @@ -224,7 +224,7 @@ the sixth item and the rest into the overflow menu, which the user can open by s <em>More</em>.</li> <li>If you've developed your application for <strong>Android 3.0 (API level 11) and -higher</strong>, items from the options menu are available in the +higher</strong>, items from the options menu are available in the app bar. By default, the system places all items in the action overflow, which the user can reveal with the action overflow icon on the right side of the app bar (or by pressing the device <em>Menu</em> button, if available). To @@ -343,7 +343,7 @@ again unless the menu is invalidated for some reason. However, you should use {@ android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()} only to create the initial menu state and not to make changes during the activity lifecycle.</p> -<p>If you want to modify the options menu based on +<p>If you want to modify the options menu based on events that occur during the activity lifecycle, you can do so in the {@link android.app.Activity#onPrepareOptionsMenu(Menu) onPrepareOptionsMenu()} method. This method passes you the {@link android.view.Menu} object as it currently exists so you can modify it, @@ -360,7 +360,7 @@ presented in the app bar. When an event occurs and you want to perform a menu up call {@link android.app.Activity#invalidateOptionsMenu invalidateOptionsMenu()} to request that the system call {@link android.app.Activity#onPrepareOptionsMenu(Menu) onPrepareOptionsMenu()}.</p> -<p class="note"><strong>Note:</strong> +<p class="note"><strong>Note:</strong> You should never change items in the options menu based on the {@link android.view.View} currently in focus. When in touch mode (when the user is not using a trackball or d-pad), views cannot take focus, so you should never use focus as the basis for modifying @@ -738,8 +738,8 @@ that shows a popup menu:</p> <pre> <ImageButton - android:layout_width="wrap_content" - android:layout_height="wrap_content" + android:layout_width="wrap_content" + android:layout_height="wrap_content" android:src="@drawable/ic_overflow_holo_dark" android:contentDescription="@string/descr_overflow_button" android:onClick="showPopup" /> @@ -1023,6 +1023,6 @@ category. For example:</p> <p>Read more about writing intent filters in the <a href="/guide/components/intents-filters.html">Intents and Intent Filters</a> document.</p> -<p>For a sample application using this technique, see the +<p>For a sample application using this technique, see the <a href="{@docRoot}resources/samples/NotePad/src/com/example/android/notepad/NoteEditor.html">Note Pad</a> sample code.</p> diff --git a/docs/html/guide/topics/ui/notifiers/toasts.jd b/docs/html/guide/topics/ui/notifiers/toasts.jd index e5d4a0a35651..d9627274fa3e 100644 --- a/docs/html/guide/topics/ui/notifiers/toasts.jd +++ b/docs/html/guide/topics/ui/notifiers/toasts.jd @@ -2,14 +2,14 @@ page.title=Toasts @jd:body <div id="qv-wrapper"> - <div id="qv"> + <div id="qv"> <h2>In this document</h2> <ol> <li><a href="#Basics">The Basics</a></li> <li><a href="#Positioning">Positioning your Toast</a></li> <li><a href="#CustomToastView">Creating a Custom Toast View</a></li> </ol> - + <h2>Key classes</h2> <ol> <li>{@link android.widget.Toast}</li> @@ -19,14 +19,14 @@ page.title=Toasts <p>A toast provides simple feedback about an operation in a small popup. It only fills the amount of space required for the message and the current -activity remains visible and interactive. -For example, navigating away from an email before you send it triggers a -"Draft saved" toast to let you know that you can continue editing later. +activity remains visible and interactive. +For example, navigating away from an email before you send it triggers a +"Draft saved" toast to let you know that you can continue editing later. Toasts automatically disappear after a timeout.</p> <img src="{@docRoot}images/toast.png" alt="" /> -<p>If user response to a status message is required, consider instead using a +<p>If user response to a status message is required, consider instead using a <a href="{@docRoot}guide/topics/ui/notifiers/notifications.html">Notification</a>.</p> @@ -49,8 +49,8 @@ toast.show(); </pre> <p>This example demonstrates everything you need for most toast notifications. -You should rarely need anything else. You may, however, want to position the -toast differently or even use your own layout instead of a simple text message. +You should rarely need anything else. You may, however, want to position the +toast differently or even use your own layout instead of a simple text message. The following sections describe how you can do these things.</p> <p>You can also chain your methods and avoid holding on to the Toast object, like this:</p> @@ -61,7 +61,7 @@ The following sections describe how you can do these things.</p> <p>A standard toast notification appears near the bottom of the screen, centered horizontally. You can change this position with the {@link android.widget.Toast#setGravity(int,int,int)} -method. This accepts three parameters: a {@link android.view.Gravity} constant, +method. This accepts three parameters: a {@link android.view.Gravity} constant, an x-position offset, and a y-position offset.</p> <p>For example, if you decide that the toast should appear in the top-left corner, you can set the @@ -70,7 +70,7 @@ gravity like this:</p> toast.setGravity(Gravity.TOP|Gravity.LEFT, 0, 0); </pre> -<p>If you want to nudge the position to the right, increase the value of the second parameter. +<p>If you want to nudge the position to the right, increase the value of the second parameter. To nudge it down, increase the value of the last parameter. @@ -103,7 +103,7 @@ with the following XML (saved as <em>toast_layout.xml</em>):</p> android:textColor="#FFF" /> </LinearLayout> -</pre> +</pre> <p>Notice that the ID of the LinearLayout element is "toast_layout_root". You must use this ID to inflate the layout from the XML, as shown here:</p> @@ -123,21 +123,21 @@ toast.setView(layout); toast.show(); </pre> -<p>First, retrieve the {@link android.view.LayoutInflater} with -{@link android.app.Activity#getLayoutInflater()} +<p>First, retrieve the {@link android.view.LayoutInflater} with +{@link android.app.Activity#getLayoutInflater()} (or {@link android.content.Context#getSystemService(String) getSystemService()}), -and then inflate the layout from XML using +and then inflate the layout from XML using {@link android.view.LayoutInflater#inflate(int, ViewGroup)}. The first parameter is the layout resource ID and the second is the root View. You can use -this inflated layout to find more View objects in the layout, so now capture and +this inflated layout to find more View objects in the layout, so now capture and define the content for the ImageView and TextView elements. Finally, create a new Toast with {@link android.widget.Toast#Toast(Context)} and set some properties of the toast, such as the gravity and duration. Then call {@link android.widget.Toast#setView(View)} and pass it the inflated layout. -You can now display the toast with your custom layout by calling +You can now display the toast with your custom layout by calling {@link android.widget.Toast#show()}.</p> -<p class="note"><strong>Note:</strong> Do not use the public constructor for a Toast +<p class="note"><strong>Note:</strong> Do not use the public constructor for a Toast unless you are going to define the layout with {@link android.widget.Toast#setView(View)}. If you do not have a custom layout to use, you must use {@link android.widget.Toast#makeText(Context,int,int)} to create the Toast.</p> diff --git a/docs/html/guide/topics/ui/overview.jd b/docs/html/guide/topics/ui/overview.jd index 85c5756de35c..f323d6c4926d 100644 --- a/docs/html/guide/topics/ui/overview.jd +++ b/docs/html/guide/topics/ui/overview.jd @@ -39,7 +39,7 @@ group. </p> <pre> <?xml version="1.0" encoding="utf-8"?> <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" - android:layout_width="fill_parent" + android:layout_width="fill_parent" android:layout_height="fill_parent" android:orientation="vertical" > <TextView android:id="@+id/text" @@ -60,7 +60,7 @@ layout.</p> <p>For a complete guide to creating a UI layout, see <a href="declaring-layout.html">XML Layouts</a>. - + <h2 id="UIComponents">User Interface Components</h2> <p>You don't have to build all of your UI using {@link android.view.View} and {@link diff --git a/docs/html/guide/topics/ui/settings.jd b/docs/html/guide/topics/ui/settings.jd index 243c1c340eb3..9e304a3f603c 100644 --- a/docs/html/guide/topics/ui/settings.jd +++ b/docs/html/guide/topics/ui/settings.jd @@ -84,7 +84,7 @@ href="{@docRoot}design/patterns/settings.html">Settings</a> design guide.</p> <img src="{@docRoot}images/ui/settings/settings.png" alt="" width="435" /> <p class="img-caption"><strong>Figure 1.</strong> Screenshots from the Android Messaging app's -settings. Selecting an item defined by a {@link android.preference.Preference} +settings. Selecting an item defined by a {@link android.preference.Preference} opens an interface to change the setting.</p> @@ -230,7 +230,7 @@ android.preference.ListPreference}. Both items include the following three attri <dt>{@code android:key}</dt> <dd>This attribute is required for preferences that persist a data value. It specifies the unique key (a string) the system uses when saving this setting's value in the {@link -android.content.SharedPreferences}. +android.content.SharedPreferences}. <p>The only instances in which this attribute is <em>not required</em> is when the preference is a {@link android.preference.PreferenceCategory} or {@link android.preference.PreferenceScreen}, or the preference specifies an {@link android.content.Intent} to invoke (with an <a @@ -291,7 +291,7 @@ android.preference.PreferenceCategory}.</p> <pre> <PreferenceScreen xmlns:android="http://schemas.android.com/apk/res/android"> - <PreferenceCategory + <PreferenceCategory android:title="@string/pref_sms_storage_title" android:key="pref_key_storage_settings"> <CheckBoxPreference @@ -299,12 +299,12 @@ android.preference.PreferenceCategory}.</p> android:summary="@string/pref_summary_auto_delete" android:title="@string/pref_title_auto_delete" android:defaultValue="false"... /> - <Preference + <Preference android:key="pref_key_sms_delete_limit" android:dependency="pref_key_auto_delete" android:summary="@string/pref_summary_delete_limit" android:title="@string/pref_title_sms_delete"... /> - <Preference + <Preference android:key="pref_key_mms_delete_limit" android:dependency="pref_key_auto_delete" android:summary="@string/pref_summary_delete_limit" @@ -594,11 +594,11 @@ element inside a root {@code <preference-headers>} element. For example:</p> <pre> <?xml version="1.0" encoding="utf-8"?> <preference-headers xmlns:android="http://schemas.android.com/apk/res/android"> - <header + <header android:fragment="com.example.prefs.SettingsActivity$SettingsFragmentOne" android:title="@string/prefs_category_one" android:summary="@string/prefs_summ_category_one" /> - <header + <header android:fragment="com.example.prefs.SettingsActivity$SettingsFragmentTwo" android:title="@string/prefs_category_two" android:summary="@string/prefs_summ_category_two" > @@ -678,15 +678,15 @@ the {@link android.preference.PreferenceActivity} that specifies which preferenc load.</p> <p>For example, here's an XML file for preference headers that is used on Android 3.0 -and higher ({@code res/xml/preference_headers.xml}):</p> +and higher ({@code res/xml/preference_headers.xml}):</p> <pre> <preference-headers xmlns:android="http://schemas.android.com/apk/res/android"> - <header + <header android:fragment="com.example.prefs.SettingsFragmentOne" android:title="@string/prefs_category_one" android:summary="@string/prefs_summ_category_one" /> - <header + <header android:fragment="com.example.prefs.SettingsFragmentTwo" android:title="@string/prefs_category_two" android:summary="@string/prefs_summ_category_two" /> @@ -698,18 +698,18 @@ Android 3.0 ({@code res/xml/preference_headers_legacy.xml}):</p> <pre> <PreferenceScreen xmlns:android="http://schemas.android.com/apk/res/android"> - <Preference + <Preference android:title="@string/prefs_category_one" android:summary="@string/prefs_summ_category_one" > - <intent + <intent android:targetPackage="com.example.prefs" android:targetClass="com.example.prefs.SettingsActivity" android:action="com.example.prefs.PREFS_ONE" /> </Preference> - <Preference + <Preference android:title="@string/prefs_category_two" android:summary="@string/prefs_summ_category_two" > - <intent + <intent android:targetPackage="com.example.prefs" android:targetClass="com.example.prefs.SettingsActivity" android:action="com.example.prefs.PREFS_TWO" /> @@ -982,11 +982,11 @@ default positive and negative dialog buttons:</p> public class NumberPickerPreference extends DialogPreference { public NumberPickerPreference(Context context, AttributeSet attrs) { super(context, attrs); - + setDialogLayoutResource(R.layout.numberpicker_dialog); setPositiveButtonText(android.R.string.ok); setNegativeButtonText(android.R.string.cancel); - + setDialogIcon(null); } ... @@ -1201,7 +1201,7 @@ protected void onRestoreInstanceState(Parcelable state) { // Cast state to custom BaseSavedState and pass to superclass SavedState myState = (SavedState) state; super.onRestoreInstanceState(myState.getSuperState()); - + // Set this Preference's widget to reflect the restored state mNumberPicker.setValue(myState.value); } diff --git a/docs/html/guide/topics/ui/themes.jd b/docs/html/guide/topics/ui/themes.jd index f932dbdec191..436b789ea51f 100644 --- a/docs/html/guide/topics/ui/themes.jd +++ b/docs/html/guide/topics/ui/themes.jd @@ -177,7 +177,7 @@ You're probably familiar with some already, such as {@link android.R.attr#layout <p>The best place to find properties that apply to a specific {@link android.view.View} is the corresponding class reference, which lists all of the supported XML attributes. For example, all of the attributes listed in the table of -<a href="{@docRoot}reference/android/widget/TextView.html#lattrs">TextView XML +<a href="{@docRoot}reference/android/widget/TextView.html#lattrs">TextView XML attributes</a> can be used in a style definition for a {@link android.widget.TextView} element (or one of its subclasses). One of the attributes listed in the reference is <a href="{@docRoot}reference/android/widget/TextView.html#attr_android:inputType">{@code @@ -279,14 +279,14 @@ does <em>not</em> use the <code>android:</code> namespace prefix.</p> <h3 id="ApplyATheme">Apply a theme to an Activity or application</h3> <p>To set a theme for all the activities of your application, open the {@code AndroidManifest.xml} file and -edit the <code><application></code> tag to include the <code>android:theme</code> attribute with the +edit the <code><application></code> tag to include the <code>android:theme</code> attribute with the style name. For example:</p> <pre> <application android:theme="@style/CustomTheme"> </pre> -<p>If you want a theme applied to just one Activity in your application, then add the +<p>If you want a theme applied to just one Activity in your application, then add the <code>android:theme</code> attribute to the <code><activity></code> tag instead.</p> <p>Just as Android provides other built-in resources, there are many pre-defined themes that you can use, to avoid @@ -374,9 +374,9 @@ keeps your program code focused on application functionality, rather than style. for you to change your theme programatically (perhaps based on a user preference), you can.</p> <p>To set the theme in your program code, use the {@link android.content.ContextWrapper#setTheme(int)} -method and pass it the theme resource ID. Note that, when doing so, you must be sure to set the theme <em>before</em> -instantiating any Views in the context, for example, before calling -<code>setContentView(View)</code> or <code>inflate(int, ViewGroup)</code>. This ensures that +method and pass it the theme resource ID. Note that, when doing so, you must be sure to set the theme <em>before</em> +instantiating any Views in the context, for example, before calling +<code>setContentView(View)</code> or <code>inflate(int, ViewGroup)</code>. This ensures that the system applies the same theme for all of your UI screens. Here's an example:</p> <pre> @@ -391,7 +391,7 @@ the system applies the same theme for all of your UI screens. Here's an example: <p>If you are considering loading a theme programmatically for the main screen of your application, note that the theme would not be applied in any animations the system would use to start the activity, which -would take place before your application opens. In most cases, if +would take place before your application opens. In most cases, if you want to apply a theme to your main screen, doing so in XML is a better approach. </p> diff --git a/docs/html/guide/topics/ui/ui-events.jd b/docs/html/guide/topics/ui/ui-events.jd index 6d41b15f6c17..7dd24a44fa89 100644 --- a/docs/html/guide/topics/ui/ui-events.jd +++ b/docs/html/guide/topics/ui/ui-events.jd @@ -20,8 +20,8 @@ parent.link=index.html When considering events within your user interface, the approach is to capture the events from the specific View object that the user interacts with. The View class provides the means to do so.</p> -<p>Within the various View classes that you'll use to compose your layout, you may notice several public callback -methods that look useful for UI events. These methods are called by the Android framework when the +<p>Within the various View classes that you'll use to compose your layout, you may notice several public callback +methods that look useful for UI events. These methods are called by the Android framework when the respective action occurs on that object. For instance, when a View (such as a Button) is touched, the <code>onTouchEvent()</code> method is called on that object. However, in order to intercept this, you must extend the class and override the method. However, extending every View object @@ -30,7 +30,7 @@ a collection of nested interfaces with callbacks that you can much more easily d called <a href="#EventListeners">event listeners</a>, are your ticket to capturing the user interaction with your UI.</p> <p>While you will more commonly use the event listeners to listen for user interaction, there may -come a time when you do want to extend a View class, in order to build a custom component. +come a time when you do want to extend a View class, in order to build a custom component. Perhaps you want to extend the {@link android.widget.Button} class to make something more fancy. In this case, you'll be able to define the default event behaviors for your class using the class <a href="#EventHandlers">event handlers</a>.</p> @@ -38,7 +38,7 @@ class using the class <a href="#EventHandlers">event handlers</a>.</p> <h2 id="EventListeners">Event Listeners</h2> -<p>An event listener is an interface in the {@link android.view.View} class that contains a single +<p>An event listener is an interface in the {@link android.view.View} class that contains a single callback method. These methods will be called by the Android framework when the View to which the listener has been registered is triggered by user interaction with the item in the UI.</p> @@ -46,27 +46,27 @@ been registered is triggered by user interaction with the item in the UI.</p> <dl> <dt><code>onClick()</code></dt> - <dd>From {@link android.view.View.OnClickListener}. - This is called when the user either touches the item + <dd>From {@link android.view.View.OnClickListener}. + This is called when the user either touches the item (when in touch mode), or focuses upon the item with the navigation-keys or trackball and presses the suitable "enter" key or presses down on the trackball.</dd> <dt><code>onLongClick()</code></dt> - <dd>From {@link android.view.View.OnLongClickListener}. - This is called when the user either touches and holds the item (when in touch mode), or + <dd>From {@link android.view.View.OnLongClickListener}. + This is called when the user either touches and holds the item (when in touch mode), or focuses upon the item with the navigation-keys or trackball and presses and holds the suitable "enter" key or presses and holds down on the trackball (for one second).</dd> <dt><code>onFocusChange()</code></dt> - <dd>From {@link android.view.View.OnFocusChangeListener}. + <dd>From {@link android.view.View.OnFocusChangeListener}. This is called when the user navigates onto or away from the item, using the navigation-keys or trackball.</dd> <dt><code>onKey()</code></dt> - <dd>From {@link android.view.View.OnKeyListener}. + <dd>From {@link android.view.View.OnKeyListener}. This is called when the user is focused on the item and presses or releases a hardware key on the device.</dd> <dt><code>onTouch()</code></dt> - <dd>From {@link android.view.View.OnTouchListener}. + <dd>From {@link android.view.View.OnTouchListener}. This is called when the user performs an action qualified as a touch event, including a press, a release, or any movement gesture on the screen (within the bounds of the item).</dd> <dt><code>onCreateContextMenu()</code></dt> - <dd>From {@link android.view.View.OnCreateContextMenuListener}. + <dd>From {@link android.view.View.OnCreateContextMenuListener}. This is called when a Context Menu is being built (as the result of a sustained "long click"). See the discussion on context menus in the <a href="{@docRoot}guide/topics/ui/menus.html#context-menu">Menus</a> developer guide.</dd> @@ -75,8 +75,8 @@ been registered is triggered by user interaction with the item in the UI.</p> <p>These methods are the sole inhabitants of their respective interface. To define one of these methods and handle your events, implement the nested interface in your Activity or define it as an anonymous class. Then, pass an instance of your implementation -to the respective <code>View.set...Listener()</code> method. (E.g., call -<code>{@link android.view.View#setOnClickListener(View.OnClickListener) setOnClickListener()}</code> +to the respective <code>View.set...Listener()</code> method. (E.g., call +<code>{@link android.view.View#setOnClickListener(View.OnClickListener) setOnClickListener()}</code> and pass it your implementation of the {@link android.view.View.OnClickListener OnClickListener}.)</p> <p>The example below shows how to register an on-click listener for a Button. </p> @@ -121,17 +121,17 @@ public class ExampleActivity extends Activity implements OnClickListener { no return value, but some other event listener methods must return a boolean. The reason depends on the event. For the few that do, here's why:</p> <ul> - <li><code>{@link android.view.View.OnLongClickListener#onLongClick(View) onLongClick()}</code> - - This returns a boolean to indicate whether you have consumed the event and it should not be carried further. - That is, return <em>true</em> to indicate that you have handled the event and it should stop here; + <li><code>{@link android.view.View.OnLongClickListener#onLongClick(View) onLongClick()}</code> - + This returns a boolean to indicate whether you have consumed the event and it should not be carried further. + That is, return <em>true</em> to indicate that you have handled the event and it should stop here; return <em>false</em> if you have not handled it and/or the event should continue to any other on-click listeners.</li> - <li><code>{@link android.view.View.OnKeyListener#onKey(View,int,KeyEvent) onKey()}</code> - + <li><code>{@link android.view.View.OnKeyListener#onKey(View,int,KeyEvent) onKey()}</code> - This returns a boolean to indicate whether you have consumed the event and it should not be carried further. - That is, return <em>true</em> to indicate that you have handled the event and it should stop here; + That is, return <em>true</em> to indicate that you have handled the event and it should stop here; return <em>false</em> if you have not handled it and/or the event should continue to any other on-key listeners.</li> - <li><code>{@link android.view.View.OnTouchListener#onTouch(View,MotionEvent) onTouch()}</code> - + <li><code>{@link android.view.View.OnTouchListener#onTouch(View,MotionEvent) onTouch()}</code> - This returns a boolean to indicate whether your listener consumes this event. The important thing is that this event can have multiple actions that follow each other. So, if you return <em>false</em> when the down action event is received, you indicate that you have not consumed the event and are also @@ -142,7 +142,7 @@ depends on the event. For the few that do, here's why:</p> <p>Remember that hardware key events are always delivered to the View currently in focus. They are dispatched starting from the top of the View hierarchy, and then down, until they reach the appropriate destination. If your View (or a child of your View) currently has focus, then you can see the event travel through the <code>{@link android.view.View#dispatchKeyEvent(KeyEvent) -dispatchKeyEvent()}</code> method. As an alternative to capturing key events through your View, you can also receive +dispatchKeyEvent()}</code> method. As an alternative to capturing key events through your View, you can also receive all of the events inside your Activity with <code>{@link android.app.Activity#onKeyDown(int,KeyEvent) onKeyDown()}</code> and <code>{@link android.app.Activity#onKeyUp(int,KeyEvent) onKeyUp()}</code>.</p> @@ -176,19 +176,19 @@ including:</p> <li><code>{@link android.view.View#onTouchEvent}</code> - Called when a touch screen motion event occurs.</li> <li><code>{@link android.view.View#onFocusChanged}</code> - Called when the view gains or loses focus.</li> </ul> -<p>There are some other methods that you should be aware of, which are not part of the View class, -but can directly impact the way you're able to handle events. So, when managing more complex events inside +<p>There are some other methods that you should be aware of, which are not part of the View class, +but can directly impact the way you're able to handle events. So, when managing more complex events inside a layout, consider these other methods:</p> <ul> <li><code>{@link android.app.Activity#dispatchTouchEvent(MotionEvent) - Activity.dispatchTouchEvent(MotionEvent)}</code> - This allows your {@link + Activity.dispatchTouchEvent(MotionEvent)}</code> - This allows your {@link android.app.Activity} to intercept all touch events before they are dispatched to the window.</li> <li><code>{@link android.view.ViewGroup#onInterceptTouchEvent(MotionEvent) ViewGroup.onInterceptTouchEvent(MotionEvent)}</code> - This allows a {@link android.view.ViewGroup} to watch events as they are dispatched to child Views.</li> <li><code>{@link android.view.ViewParent#requestDisallowInterceptTouchEvent(boolean) ViewParent.requestDisallowInterceptTouchEvent(boolean)}</code> - Call this - upon a parent View to indicate that it should not intercept touch events with <code>{@link + upon a parent View to indicate that it should not intercept touch events with <code>{@link android.view.ViewGroup#onInterceptTouchEvent(MotionEvent)}</code>.</li> </ul> @@ -199,7 +199,7 @@ necessary to give focus to actionable items (like buttons) so the user can see what will accept input. If the device has touch capabilities, however, and the user begins interacting with the interface by touching it, then it is no longer necessary to highlight items, or give focus to a particular View. Thus, there is a mode -for interaction named "touch mode." +for interaction named "touch mode." </p> <p> For a touch-capable device, once the user touches the screen, the device @@ -214,7 +214,7 @@ exit touch mode, and find a view to take focus. Now, the user may resume interac with the user interface without touching the screen. </p> <p> -The touch mode state is maintained throughout the entire system (all windows and activities). +The touch mode state is maintained throughout the entire system (all windows and activities). To query the current state, you can call {@link android.view.View#isInTouchMode} to see whether the device is currently in touch mode. </p> @@ -254,10 +254,10 @@ the focus is leaving. Define the value of the attribute to be the id of the View <p>Ordinarily, in this vertical layout, navigating up from the first Button would not go anywhere, nor would navigating down from the second Button. Now that the top Button has -defined the bottom one as the <var>nextFocusUp</var> (and vice versa), the navigation focus will +defined the bottom one as the <var>nextFocusUp</var> (and vice versa), the navigation focus will cycle from top-to-bottom and bottom-to-top.</p> -<p>If you'd like to declare a View as focusable in your UI (when it is traditionally not), +<p>If you'd like to declare a View as focusable in your UI (when it is traditionally not), add the <code>android:focusable</code> XML attribute to the View, in your layout declaration. Set the value <var>true</var>. You can also declare a View as focusable while in Touch Mode with <code>android:focusableInTouchMode</code>.</p> @@ -282,7 +282,7 @@ as discussed in the <a href="#EventListeners">Event Listeners</a> section, above the framework will take care of measuring, laying out, and drawing the tree as appropriate.</li> </ol> - + <p class="note"><strong>Note:</strong> The entire View tree is single threaded. You must always be on the UI thread when calling any method on any View. If you are doing work on other threads and want to update the state of a View diff --git a/docs/html/guide/webapps/debugging.jd b/docs/html/guide/webapps/debugging.jd index a74797df3bd3..9e8e11337b73 100755 --- a/docs/html/guide/webapps/debugging.jd +++ b/docs/html/guide/webapps/debugging.jd @@ -92,7 +92,7 @@ expect from other web browsers.</p> <h2 id="WebView">Using Console APIs in WebView</h2> <p>All the console APIs shown above are also -supported when debugging in {@link android.webkit.WebView}. +supported when debugging in {@link android.webkit.WebView}. If you're targeting Android 2.1 (API level 7) and higher, you must provide a {@link android.webkit.WebChromeClient} that implements the {@link android.webkit.WebChromeClient#onConsoleMessage(String,int,String) diff --git a/docs/html/guide/webapps/targeting.jd b/docs/html/guide/webapps/targeting.jd index 4a2ea1773c95..10259b115b29 100644 --- a/docs/html/guide/webapps/targeting.jd +++ b/docs/html/guide/webapps/targeting.jd @@ -108,7 +108,7 @@ should exactly match the device screen's width and that the ability to zoom shou <p>When optimizing your site for mobile devices, you should usually set the width to -{@code "device-width"} so the size fits exactly on all devices, then use CSS media queries to +{@code "device-width"} so the size fits exactly on all devices, then use CSS media queries to flexibly adapt layouts to suit different screen sizes. <p class="note"><strong>Note:</strong> You should disable user scaling only when you're certain |