diff options
Diffstat (limited to 'docs/html/guide/topics')
| -rw-r--r-- | docs/html/guide/topics/clipboard/copy-paste.jd | 2 | ||||
| -rw-r--r-- | docs/html/guide/topics/manifest/compatible-screens-element.jd | 108 | ||||
| -rw-r--r-- | docs/html/guide/topics/manifest/supports-screens-element.jd | 123 | ||||
| -rw-r--r-- | docs/html/guide/topics/manifest/uses-feature-element.jd | 31 | ||||
| -rw-r--r-- | docs/html/guide/topics/providers/loaders.jd | 492 | ||||
| -rw-r--r-- | docs/html/guide/topics/ui/drag-drop.jd | 4 |
6 files changed, 710 insertions, 50 deletions
diff --git a/docs/html/guide/topics/clipboard/copy-paste.jd b/docs/html/guide/topics/clipboard/copy-paste.jd index 9a50a35..6c86f47 100644 --- a/docs/html/guide/topics/clipboard/copy-paste.jd +++ b/docs/html/guide/topics/clipboard/copy-paste.jd @@ -1,4 +1,4 @@ -page.title=Copying and Pasting +page.title=Copy and Paste @jd:body <div id="qv-wrapper"> <div id="qv"> diff --git a/docs/html/guide/topics/manifest/compatible-screens-element.jd b/docs/html/guide/topics/manifest/compatible-screens-element.jd new file mode 100644 index 0000000..9fb0fd2 --- /dev/null +++ b/docs/html/guide/topics/manifest/compatible-screens-element.jd @@ -0,0 +1,108 @@ +page.title=<compatible-screens> +@jd:body + +<dl class="xml"> +<dt>syntax:</dt> +<dd> +<pre> +<<a href="#compatible-screens">compatible-screens</a>> + <<a href="#screen">screen</a> android:<a href="#screenSize">screenSize</a>=["small" | "normal" | "large" | "xlarge"] + android:<a href="#screenDensity">screenDensity</a>=["ldpi" | "mdpi" | "hdpi" | "xhdpi"] /> + ... +</compatible-screens> +</pre> +</dd> + +<dt>contained in:</dt> +<dd><code><a +href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code></dd> + +<dt>description:</dt> +<dd>Specifies each screen configuration with which the application is compatible. Only one instance +of the {@code <compatible-screens>} element is allowed in the manifest, but it can +contain multiple <code><screen></code> elements. Each <code><screen></code> element +specifies a specific screen size-density combination with which the application is compatible. + + <p>The Android system <em>does not</em> read the {@code <compatible-screens>} manifest +element (neither at install-time nor at runtime). This element is informational only and may be used +by external services (such as Android Market) to better understand the application's compatibility +with specific screen configurations and enable filtering for users. Any screen configuration that is +<em>not</em> declared in this element is a screen with which the application is <em>not</em> +compatible. Thus, external services (such as Android Market) should not provide the application to +devices with such screens.</p> + + <p class="caution"><strong>Caution:</strong> Normally, <strong>you should not use this manifest +element</strong>. Using this element can dramatically reduce the potential user base for your +application, by not allowing users to install your application if they have a device with a screen +configuration that you have not listed. You should use it only as a last resort, when the +application absolutely does not work with all screen configurations. Instead of using this element, +you should follow the guide to <a href="{@docRoot}guide/practices/screens_support.html">Supporting +Multiple Screens</a>, in order to provide complete support for multiple screens, by adding +alternative resources for different screen sizes and densities.</p> + + <p>If you want to set only a minimum screen <em>size</em> for your your application, then you +should use the <a href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code +<supports-screens>}</a> element. For example, if you want your application to be available +only for <em>large</em> and <em>xlarge</em> screen devices, the <a +href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code +<supports-screens>}</a> element allows you to declare that your application does not +support <em>small</em> and <em>normal</em> screen sizes. External services (such as Android +Market) will filter your application accordingly. You can also use the <a +href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code +<supports-screens>}</a> element to declare whether the system should resize your +application for different screen sizes.</p> + + <p>Also see the <a href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a> +document for more information about how Android Market filters applications using this and +other manifest elements.</p> + +</dd> + +<dt>child elements:</dt> +<dd> + <dl class="tag-list"> + + <dt id="screen">{@code <screen>}</dt> + <dd>Specifies a single screen configuration with which the application is compatible. + <p>At least one instance of this element must be placed inside the {@code +<compatible-screens>} element. This element <em>must include both</em> the {@code +android:screenSize} and {@code android:screenDensity} attributes (if you do not declare both +attributes, then the element is ignored).</p> + + <p class="caps">attributes:</p> + <dl class="atn-list"> + <dt id="screenSize"><code>android:screenSize</code></dt> + <dd><b>Required.</b> Specifies the screen size for this screen configuration. + <p>Accepted values:</p> + <ul> + <li>{@code small}</li> + <li>{@code normal}</li> + <li>{@code large}</li> + <li>{@code xlarge}</li> + </ul> + <p>For information about the different screen sizes, see <a +href="{@docRoot}guide/practices/screens_support.html#range">Supporting Multiple Screens</a>.</p> + </dd> + <dt id="screenDensity"><code>android:screenDensity</code></dt> + <dd><b>Required.</b> Specifies the screen density for this screen configuration. + <p>Accepted values:</p> + <ul> + <li>{@code ldpi}</li> + <li>{@code mdpi}</li> + <li>{@code hdpi}</li> + <li>{@code xhdpi}</li> + </ul> + <p>For information about the different screen densities, see <a +href="{@docRoot}guide/practices/screens_support.html#range">Supporting Multiple Screens</a>.</p> + </dd> + </dl> + </dd> + </dl> +</dd> +<dt>introduced in:</dt> +<dd>API Level 9</dd> +<dt>see also:</dt> +<dd><a +href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a></dd> +<dd><a href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a></dd> +</dl> diff --git a/docs/html/guide/topics/manifest/supports-screens-element.jd b/docs/html/guide/topics/manifest/supports-screens-element.jd index 64a7a58..92c769e 100644 --- a/docs/html/guide/topics/manifest/supports-screens-element.jd +++ b/docs/html/guide/topics/manifest/supports-screens-element.jd @@ -6,7 +6,8 @@ page.title=<supports-screens> <dt>syntax:</dt> <dd> <pre class="stx"> -<supports-screens android:<a href="#small">smallScreens</a>=["true" | "false"] +<supports-screens android:<a href="#resizeable">resizeable</a>=["true" | "false"] + android:<a href="#small">smallScreens</a>=["true" | "false"] android:<a href="#normal">normalScreens</a>=["true" | "false"] android:<a href="#large">largeScreens</a>=["true" | "false"] android:<a href="#xlarge">xlargeScreens</a>=["true" | "false"] @@ -19,17 +20,33 @@ page.title=<supports-screens> <dt>description:</dt> <dd>Lets you specify the screen dimensions the -application supports. By default a modern application (using API Level 4 or higher) supports all -screen sizes and must explicitly disable certain screen sizes here; -older applications are assumed to support only the "normal" -screen size. Note that screen size is a separate axis from -density. Screen size is determined as the available pixels to an application -after density scaling has been applied. - -<p>Based on the target device screen density, the Android -framework will scale down assets by a factor of 0.75 (low dpi screens) -or scale them up by a factor of 1.5 (high dpi screens). -The screen density is expressed as dots-per-inch (dpi).</p> +application supports. By default, a modern application (using API Level 4 or higher) supports all +screen sizes; older applications are assumed to support only the "normal" screen size. Screen +size is determined as the available pixels to an application after density scaling has been +applied. (Note that screen size is a separate axis from screen density.) + +<p>An application "supports" a given screen size if it fills the entire screen and works as +expected. By default, the system will resize your application to fill the screen, if you have set +either <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code +minSdkVersion}</a> or <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code +targetSdkVersion}</a> to {@code "4"} or higher. Resizing works well for most applications and +you don't have to do any extra work to make your application work on larger screens.</p> + +<p>In addition to allowing the system to resize your application, you can add additional support +for different screen sizes by providing <a +href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">alternative +layout resources</a> for different sizes. For instance, you might want to modify the layout +of an activity when it is on a tablet or similar device that has an <em>xlarge</em> screen.</p> + +<p>If your application does not support <em>large</em> or <em>xlarge</em> screens, then you should +declare that it is not resizeable by setting <a href="#resizeable">{@code android:resizeable}</a> to +{@code "false"}, so that the system will not resize your application on larger screens.</p> + +<p>If your application does not support <em>small</em> screens, then +there isn't much the system can do to make the application work well on a smaller screen, so +external services (such as Android Market) should not allow users to install the application on such +screens.</p> + <p>For more information, see <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a>.</p> @@ -38,16 +55,40 @@ The screen density is expressed as dots-per-inch (dpi).</p> <dt>attributes:</dt> <dd> -<dl class="attr"><dt><a name="small"></a>{@code android:smallScreens}</dt> +<dl class="attr"> + + <dt><a name="resizeable"></a>{@code android:resizeable}</dt> + <dd>Indicates whether the application is resizeable for different screen sizes. This attribute is +true, by default, if you have set either <a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> or <a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> to +{@code "4"} or higher. Otherwise, it is false by default. If set false, the system will not resize +your application when run on <em>large</em> or <em>xlarge</em> screens. Instead, the +application appears in a "postage stamp" that equals the <em>normal</em> screen size that your +application does support. This is less than an ideal experience for users, because the +application appears smaller than the available screen, but it might help your application run +normally if it were designed only for the <em>normal</em> screen size and some behaviors do not work +when resized.</p> + <p>To provide the best experience on all screen sizes, you should allow resizing and, if your +application does not work well on larger screens, follow the guide to <a +href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a> to enable +additional screen support.</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 the "normal" (traditional HVGA) screen. An application that does not support small screens <em>will not be available</em> for - small screen devices, because there is little the platform can do - to make such an application work on a smaller screen. If the application has set the <a -href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code <uses-sdk>}</a> element's -{@code android:minSdkVersion} or {@code android:targetSdkVersion} attribute to "4" or higher, -the default value for this is "true", any value less than "4" results in this set to "false". + small screen devices from external services (such as Android Market), because there is little +the platform can do + to make such an application work on a smaller screen. If the application has set either <a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> or <a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> to +{@code "4"} or higher, +the default value for this is {@code "true"}, any value less than {@code "4"} results in this set to +{@code "false"}. </dd> <dt><a name="normal"></a>{@code android:normalScreens}</dt> @@ -61,38 +102,44 @@ the default value for this is "true", any value less than "4" results in this se <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 - than a "normal" phone screen, and thus may require some special care - on the application's part to make good use of it. An application that - does not support large screens (declares this "false")—but does support "normal" or -"small" screens—will be placed as a "postage stamp" on - a large screen, so that it retains the dimensions it was originally - designed for. If the application has set the <a -href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code <uses-sdk>}</a> element's -{@code android:minSdkVersion} or {@code android:targetSdkVersion} attribute to "4" or higher, -the default value for this is "true", any value less than "4" results in this set to "false". + than a "normal" phone screen, and thus might require some special care + on the application's part to make good use of it, though it may rely on resizing by the +system to fill the screen. If the application has set either <a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> or <a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> to +{@code "4"} or higher, +the default value for this is {@code "true"}, any value less than {@code "4"} results in this set to +{@code "false"}. </dd> - + <dt><a name="xlarge"></a>{@code android:xlargeScreens}</dt> <dd>Indicates whether the application supports extra large screen form-factors. An xlarge screen is defined as a screen that is significantly larger than a "large" screen, such as a tablet (or something larger) and may require special care - on the application's part to make good use of it. An application that - does not support xlarge screens (declares this "false")—but does support "large", -"normal", or "small" screens—will be placed as a "postage stamp" on - an xlarge screen, so that it retains the dimensions it was originally - designed for. If the application has set the <a -href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code <uses-sdk>}</a> element's -{@code android:minSdkVersion} or {@code android:targetSdkVersion} attribute to "4" or higher, -the default value for this is "true", any value less than "4" results in this set to "false". + on the application's part to make good use of it, though it may rely on resizing by the +system to fill the screen. If the application has set either <a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> or <a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> to +{@code "4"} or higher, +the default value for this is {@code "true"}, any value less than {@code "4"} results in this set to +{@code "false"}. <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. Older applications (before API Level 4) are assumed unable to - accomodate all densities and this is "false" by default. Applications using - API Level 4 or higher are assumed able to and this is "true" by default. + accomodate all densities and this is {@code "false"} by default. If the application has set +either <a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> or <a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> to +{@code "4"} or higher, +the default value for this is {@code "true"}. Otherwise, it is {@code "false"}. You can explicitly supply your abilities here. + <p>Based on the "standard" device screen density (medium dpi), the Android framework will scale +down application assets by a factor of 0.75 (low dpi screens) or scale them up by a factor of 1.5 +(high dpi screens), when you don't provide alternative resources for a specifc screen density. The +screen density is expressed as dots-per-inch (dpi).</p> </dd> diff --git a/docs/html/guide/topics/manifest/uses-feature-element.jd b/docs/html/guide/topics/manifest/uses-feature-element.jd index 5242126..0828e8b 100644 --- a/docs/html/guide/topics/manifest/uses-feature-element.jd +++ b/docs/html/guide/topics/manifest/uses-feature-element.jd @@ -644,33 +644,46 @@ device.</td> </tr> <tr> - <td rowspan="4">Touchscreen</td> + <td rowspan="5">Touchscreen</td> + <td><code>android.hardware.faketouch</code></td> + <td>The application uses basic touch interaction events, such as "click down", "click +up", and drag.</td> + <td>When declared, this indicates that the application is compatible with a device that offers an +emulated touchscreen (or better). A device that offers an emulated touchscreen provides a user input +system that can emulate a subset of touchscreen capabilities. An example of such an input system is +a mouse or remote control that drives an on-screen cursor. If your application does not require +complicated gestures and you want your application available to devices with an emulated +touchscreen, you should declare this feature.</td> +</tr> +<tr> <td><code>android.hardware.touchscreen</code></td> - <td>The application uses touchscreen capabilities on the device.</td> + <td>The application uses touchscreen capabilities, for gestures more interactive +than basic touches, such as a fling. This is a superset of the faketouch features.</td> <td></td> </tr> <tr> <td><code>android.hardware.touchscreen.multitouch</code></td> - <td>Subfeature. The application uses basic two-point multitouch capabilities on the device -screen.</td> + <td>The application uses basic two-point multitouch capabilities on the device +screen, such as for pinch gestures, but does not need to track touches independently. This +is a superset of touchscreen features.</td> <td>If declared with the <code>"android:required="true"</code> attribute, this -subfeature implicitly declares the <code>android.hardware.touchscreen</code> +implicitly declares the <code>android.hardware.touchscreen</code> parent feature. </td> </tr> <tr> <td><code>android.hardware.touchscreen.multitouch.distinct</code></td> <td>Subfeature. The application uses advanced multipoint multitouch capabilities on the device screen, such as for tracking two or more points fully -independently.</td> +independently. This is a superset of multitouch features.</td> <td rowspan="2">If declared with the <code>"android:required="true"</code> attribute, this -subfeature implicitly declares the +implicitly declares the <code>android.hardware.touchscreen.multitouch</code> parent feature. </td> </tr> <tr> <td><code>android.hardware.touchscreen.multitouch.jazzhand</code></td> - <td>Subfeature. The application uses advanced multipoint multitouch + <td>The application uses advanced multipoint multitouch capabilities on the device screen, for tracking up to five points fully -independently.</td> +independently. This is a superset of distinct multitouch features.</td> </tr> <tr> diff --git a/docs/html/guide/topics/providers/loaders.jd b/docs/html/guide/topics/providers/loaders.jd new file mode 100644 index 0000000..c54656c --- /dev/null +++ b/docs/html/guide/topics/providers/loaders.jd @@ -0,0 +1,492 @@ +page.title=Using Loaders +@jd:body +<div id="qv-wrapper"> +<div id="qv"> + <h2>In this document</h2> + <ol> + <li><a href="#summary">Loader API Summary</a></li> + <li><a href="#app">Using Loaders in an Application</a> + <ol> + <li><a href="#requirements"></a></li> + <li><a href="#starting">Starting a Loader</a></li> + <li><a href="#restarting">Restarting a Loader</a></li> + <li><a href="#callback">Using the LoaderManager Callbacks</a></li> + </ol> + </li> + <li><a href="#example">Example</a> + <ol> + <li><a href="#more_examples">More Examples</a></li> + </ol> + </li> + </ol> + + <h2>Key classes</h2> + <ol> + <li>{@link android.app.LoaderManager}</li> + <li>{@link android.content.Loader}</li> + + </ol> + + <h2>Related samples</h2> + <ol> + <li> <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/FragmentCursorLoader.html"> FragmentCursorLoader</a></li> + <li> <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LoaderThrottle.html"> LoaderThrottle</a></li> + </ol> + </div> +</div> + +<p>Introduced in Android 3.0, loaders make it easy to asynchronously load data +in an activity or fragment. Loaders have these characteristics:</p> + <ul> + <li>They are available to every {@link android.app.Activity} and {@link +android.app.Fragment}.</li> + <li>They provide asynchronous loading of data.</li> + <li>They monitor the source of their data and deliver new results when the +content changes.</li> + <li>They automatically reconnect to the last loader's cursor when being +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 +loaders in an application. They are summarized in this table:</p> + +<table> + <tr> + <th>Class/Interface</th> + <th>Description</th> + </tr> + <tr> + <td>{@link android.app.LoaderManager}</td> + <td>An abstract class associated with an {@link android.app.Activity} or +{@link android.app.Fragment} for managing one or more {@link +android.content.Loader} instances. This helps an application manage +longer-running operations in conjunction with the {@link android.app.Activity} +or {@link android.app.Fragment} lifecycle; the most common use of this is with a +{@link android.content.CursorLoader}, however applications are free to write +their own loaders for loading other types of data. + <br /> + <br /> + There is only one {@link android.app.LoaderManager} per activity or fragment. But a {@link android.app.LoaderManager} can have +multiple loaders.</td> + </tr> + <tr> + <td>{@link android.app.LoaderManager.LoaderCallbacks}</td> + <td>A callback interface for a client to interact with the {@link +android.app.LoaderManager}. For example, you use the {@link +android.app.LoaderManager.LoaderCallbacks#onCreateLoader onCreateLoader()} +callback method to create a new loader.</td> + </tr> + <tr> + <td>{@link android.content.Loader}</td> + <td>An abstract class that performs asynchronous loading of data. This is +the base class for a loader. You would typically use {@link +android.content.CursorLoader}, but you can implement your own subclass. While +loaders are active they should monitor the source of their data and deliver new +results when the contents change. </td> + </tr> + <tr> + <td>{@link android.content.AsyncTaskLoader}</td> + <td>Abstract loader that provides an {@link android.os.AsyncTask} to do the work.</td> + </tr> + <tr> + <td>{@link android.content.CursorLoader}</td> + <td>A subclass of {@link android.content.AsyncTaskLoader} that queries the +{@link android.content.ContentResolver} and returns a {@link +android.database.Cursor}. This class implements the {@link +android.content.Loader} protocol in a standard way for querying cursors, +building on {@link android.content.AsyncTaskLoader} to perform the cursor query +on a background thread so that it does not block the application's UI. Using +this loader is the best way to asynchronously load data from a {@link +android.content.ContentProvider}, instead of performing a managed query through +the fragment or activity's APIs.</td> + </tr> +</table> + +<p>The classes and interfaces in the above table are the essential components +you'll use to implement a loader in your application. You won't need all of them +for each loader you create, but you'll always need a reference to the {@link +android.app.LoaderManager} in order to initialize a loader and an implementation +of a {@link android.content.Loader} class such as {@link +android.content.CursorLoader}. The following sections show you how to use these +classes and interfaces in an application.</p> + +<h2 id ="app">Using Loaders in an Application</h2> +<p>This section describes how to use loaders in an Android application. An +application that uses loaders typically includes the following:</p> +<ul> + <li>An {@link android.app.Activity} or {@link android.app.Fragment}.</li> + <li>An instance of the {@link android.app.LoaderManager}.</li> + <li>A {@link android.content.CursorLoader} to load data backed by a {@link +android.content.ContentProvider}. Alternatively, you can implement your own subclass +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> +<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 +{@link android.content.CursorLoader}.</li> +</ul> +<h3 id="starting">Starting a Loader</h3> + +<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> + +<p>You typically +initialize a {@link android.content.Loader} within the activity's {@link +android.app.Activity#onCreate onCreate()} method, or within the fragment's +{@link android.app.Fragment#onActivityCreated onActivityCreated()} method. You +do this as follows:</p> + +<pre>// Prepare the loader. Either re-connect with an existing one, +// or start a new one. +getLoaderManager().initLoader(0, null, this);</pre> + +<p>The {@link android.app.LoaderManager#initLoader initLoader()} method takes +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> + +<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> +</ul> +<p>The {@link android.app.LoaderManager#initLoader initLoader()} call ensures that a loader +is initialized and active. It has two possible outcomes:</p> +<ul> + <li>If the loader specified by the ID already exists, the last created loader +is reused.</li> + <li>If the loader specified by the ID does <em>not</em> exist, +{@link android.app.LoaderManager#initLoader initLoader()} triggers the +{@link android.app.LoaderManager.LoaderCallbacks} method {@link android.app.LoaderManager.LoaderCallbacks#onCreateLoader onCreateLoader()}. +This is where you implement the code to instantiate and return a new loader. +For more discussion, see the section <a +href="#onCreateLoader">onCreateLoader</a>.</li> +</ul> +<p>In either case, the given {@link android.app.LoaderManager.LoaderCallbacks} +implementation is associated with the loader, and will be called when the +loader state changes. If at the point of this call the caller is in its +started state, and the requested loader already exists and has generated its +data, then the system calls {@link +android.app.LoaderManager.LoaderCallbacks#onLoadFinished onLoadFinished()} +immediately (during {@link android.app.LoaderManager#initLoader initLoader()}), +so you must be prepared for this to happen. See <a href="#onLoadFinished"> +onLoadFinished</a> for more discussion of this callback</p> + +<p>Note that the {@link android.app.LoaderManager#initLoader initLoader()} +method returns the {@link android.content.Loader} that is created, but you don't +need to capture a reference to it. The {@link android.app.LoaderManager} manages +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). +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 +href="#callback">Using the LoaderManager Callbacks</a>.</p> + +<h3 id="restarting">Restarting a Loader</h3> + +<p>When you use {@link android.app.LoaderManager#initLoader initLoader()}, as +shown above, it uses an existing loader with the specified ID if there is one. +If there isn't, it creates one. But sometimes you want to discard your old data +and start over.</p> + +<p>To discard your old data, you use {@link +android.app.LoaderManager#restartLoader restartLoader()}. For example, this +implementation of {@link android.widget.SearchView.OnQueryTextListener} restarts +the loader when the user's query changes. The loader needs to be restarted so +that it can use the revised search filter to do a new query:</p> + +<pre> +public boolean onQueryTextChanged(String newText) { + // Called when the action bar search text has changed. Update + // the search filter, and restart the loader to do a new query + // with this filter. + mCurFilter = !TextUtils.isEmpty(newText) ? newText : null; + getLoaderManager().restartLoader(0, null, this); + return true; +}</pre> + +<h3 id="callback">Using the LoaderManager Callbacks</h3> + +<p>{@link android.app.LoaderManager.LoaderCallbacks} is a callback interface +that lets a client interact with the {@link android.app.LoaderManager}. </p> +<p>Loaders, in particular {@link android.content.CursorLoader}, are expected to +retain their data after being stopped. This allows applications to keep their +data across the activity or fragment's {@link android.app.Activity#onStop +onStop()} and {@link android.app.Activity#onStart onStart()} methods, so that +when users return to an application, they don't have to wait for the data to +reload. You use the {@link android.app.LoaderManager.LoaderCallbacks} methods +when to know when to create a new loader, and to tell the application when it is + time to stop using a loader's data.</p> + +<p>{@link android.app.LoaderManager.LoaderCallbacks} includes these +methods:</p> +<ul> + <li>{@link android.app.LoaderManager.LoaderCallbacks#onCreateLoader onCreateLoader()} — +Instantiate and return a new {@link android.content.Loader} for the given ID. +</li></ul> +<ul> + <li> {@link android.app.LoaderManager.LoaderCallbacks#onLoadFinished onLoadFinished()} +— Called when a previously created loader has finished its load. +</li></ul> +<ul> + <li>{@link android.app.LoaderManager.LoaderCallbacks#onLoaderReset onLoaderReset()} + — Called when a previously created loader is being reset, thus making its +data unavailable. +</li> +</ul> +<p>These methods are described in more detail in the following sections.</p> + +<h4 id ="onCreateLoader">onCreateLoader</h4> + +<p>When you attempt to access a loader (for example, through {@link +android.app.LoaderManager#initLoader initLoader()}), it checks to see whether +the loader specified by the ID exists. If it doesn't, it triggers the {@link +android.app.LoaderManager.LoaderCallbacks} method {@link +android.app.LoaderManager.LoaderCallbacks#onCreateLoader onCreateLoader()}. This +is where you create a new loader. Typically this will be a {@link +android.content.CursorLoader}, but you can implement your own {@link +android.content.Loader} subclass. </p> + +<p>In this example, the {@link +android.app.LoaderManager.LoaderCallbacks#onCreateLoader onCreateLoader()} +callback method creates a {@link android.content.CursorLoader}. You must build +the {@link android.content.CursorLoader} using its constructor method, which +requires the complete set of information needed to perform a query to the {@link +android.content.ContentProvider}. Specifically, it needs:</p> +<ul> + <li><em>uri</em> — The URI for the content to retrieve. </li> + <li><em>projection</em> — A list of which columns to return. Passing +<code>null</code> will return all columns, which is inefficient. </li> + <li><em>selection</em> — A filter declaring which rows to return, +formatted as an SQL WHERE clause (excluding the WHERE itself). Passing +<code>null</code> will return all rows for the given URI. </li> + <li><em>selectionArgs</em> — You may include ?s in the selection, which will +be replaced by the values from <em>selectionArgs</em>, in the order that they appear in +the selection. The values will be bound as Strings. </li> + <li><em>sortOrder</em> — How to order the rows, formatted as an SQL +ORDER BY clause (excluding the ORDER BY itself). Passing <code>null</code> will +use the default sort order, which may be unordered.</li> +</ul> +<p>For example:</p> +<pre> + // If non-null, this is the current filter the user has provided. +String mCurFilter; +... +public Loader<Cursor> onCreateLoader(int id, Bundle args) { + // This is called when a new Loader needs to be created. This + // sample only has one Loader, so we don't care about the ID. + // First, pick the base URI to use depending on whether we are + // currently filtering. + Uri baseUri; + if (mCurFilter != null) { + baseUri = Uri.withAppendedPath(Contacts.CONTENT_FILTER_URI, + Uri.encode(mCurFilter)); + } else { + baseUri = Contacts.CONTENT_URI; + } + + // Now create and return a CursorLoader that will take care of + // creating a Cursor for the data being displayed. + String select = "((" + Contacts.DISPLAY_NAME + " NOTNULL) AND (" + + Contacts.HAS_PHONE_NUMBER + "=1) AND (" + + Contacts.DISPLAY_NAME + " != '' ))"; + return new CursorLoader(getActivity(), baseUri, + CONTACTS_SUMMARY_PROJECTION, select, null, + Contacts.DISPLAY_NAME + " COLLATE LOCALIZED ASC"); +}</pre> +<h4 id="onLoadFinished">onLoadFinished</h4> + +<p>This method is called when a previously created loader has finished its load. +This method is guaranteed to be called prior to the release of the last data +that was supplied for this loader. At this point you should remove all use of +the old data (since it will be released soon), but should not do your own +release of the data since its loader owns it and will take care of that.</p> + + +<p>The loader will release the data once it knows the application is no longer +using it. For example, if the data is a cursor from a {@link +android.content.CursorLoader}, you should not call {@link +android.database.Cursor#close close()} on it yourself. If the cursor is being +placed in a {@link android.widget.CursorAdapter}, you should use the {@link +android.widget.SimpleCursorAdapter#swapCursor swapCursor()} method so that the +old {@link android.database.Cursor} is not closed. For example:</p> + +<pre> +// This is the Adapter being used to display the list's data.<br +/>SimpleCursorAdapter mAdapter; +... + +public void onLoadFinished(Loader<Cursor> loader, Cursor data) { + // Swap the new cursor in. (The framework will take care of closing the + // old cursor once we return.) + mAdapter.swapCursor(data); +}</pre> + +<h4 id="onLoaderReset">onLoaderReset</h4> + +<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()} +with a value of <code>null</code>:</p> + +<pre> +// This is the Adapter being used to display the list's data. +SimpleCursorAdapter mAdapter; +... + +public void onLoaderReset(Loader<Cursor> loader) { + // This is called when the last Cursor provided to onLoadFinished() + // above is about to be closed. We need to make sure we are no + // longer using it. + mAdapter.swapCursor(null); +}</pre> + + +<h2 id="example">Example</h2> + +<p>As an example, here is the full implementation of a {@link +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> + +<pre> +public static class CursorLoaderListFragment extends ListFragment + implements OnQueryTextListener, LoaderManager.LoaderCallbacks<Cursor> { + + // This is the Adapter being used to display the list's data. + SimpleCursorAdapter mAdapter; + + // If non-null, this is the current filter the user has provided. + String mCurFilter; + + @Override public void onActivityCreated(Bundle savedInstanceState) { + super.onActivityCreated(savedInstanceState); + + // Give some text to display if there is no data. In a real + // application this would come from a resource. + setEmptyText("No phone numbers"); + + // We have a menu item to show in action bar. + setHasOptionsMenu(true); + + // Create an empty adapter we will use to display the loaded data. + mAdapter = new SimpleCursorAdapter(getActivity(), + android.R.layout.simple_list_item_2, null, + new String[] { Contacts.DISPLAY_NAME, Contacts.CONTACT_STATUS }, + new int[] { android.R.id.text1, android.R.id.text2 }, 0); + setListAdapter(mAdapter); + + // Prepare the loader. Either re-connect with an existing one, + // or start a new one. + getLoaderManager().initLoader(0, null, this); + } + + @Override public void onCreateOptionsMenu(Menu menu, MenuInflater inflater) { + // Place an action bar item for searching. + MenuItem item = menu.add("Search"); + item.setIcon(android.R.drawable.ic_menu_search); + item.setShowAsAction(MenuItem.SHOW_AS_ACTION_IF_ROOM); + SearchView sv = new SearchView(getActivity()); + sv.setOnQueryTextListener(this); + item.setActionView(sv); + } + + public boolean onQueryTextChange(String newText) { + // Called when the action bar search text has changed. Update + // the search filter, and restart the loader to do a new query + // with this filter. + mCurFilter = !TextUtils.isEmpty(newText) ? newText : null; + getLoaderManager().restartLoader(0, null, this); + return true; + } + + @Override public boolean onQueryTextSubmit(String query) { + // Don't care about this. + return true; + } + + @Override public void onListItemClick(ListView l, View v, int position, long id) { + // Insert desired behavior here. + Log.i("FragmentComplexList", "Item clicked: " + id); + } + + // These are the Contacts rows that we will retrieve. + static final String[] CONTACTS_SUMMARY_PROJECTION = new String[] { + Contacts._ID, + Contacts.DISPLAY_NAME, + Contacts.CONTACT_STATUS, + Contacts.CONTACT_PRESENCE, + Contacts.PHOTO_ID, + Contacts.LOOKUP_KEY, + }; + public Loader<Cursor> onCreateLoader(int id, Bundle args) { + // This is called when a new Loader needs to be created. This + // sample only has one Loader, so we don't care about the ID. + // First, pick the base URI to use depending on whether we are + // currently filtering. + Uri baseUri; + if (mCurFilter != null) { + baseUri = Uri.withAppendedPath(Contacts.CONTENT_FILTER_URI, + Uri.encode(mCurFilter)); + } else { + baseUri = Contacts.CONTENT_URI; + } + + // Now create and return a CursorLoader that will take care of + // creating a Cursor for the data being displayed. + String select = "((" + Contacts.DISPLAY_NAME + " NOTNULL) AND (" + + Contacts.HAS_PHONE_NUMBER + "=1) AND (" + + Contacts.DISPLAY_NAME + " != '' ))"; + return new CursorLoader(getActivity(), baseUri, + CONTACTS_SUMMARY_PROJECTION, select, null, + Contacts.DISPLAY_NAME + " COLLATE LOCALIZED ASC"); + } + + public void onLoadFinished(Loader<Cursor> loader, Cursor data) { + // Swap the new cursor in. (The framework will take care of closing the + // old cursor once we return.) + mAdapter.swapCursor(data); + } + + public void onLoaderReset(Loader<Cursor> loader) { + // This is called when the last Cursor provided to onLoadFinished() + // above is about to be closed. We need to make sure we are no + // longer using it. + mAdapter.swapCursor(null); + } +}</pre> +<h3 id="more_examples">More Examples</h3> + +<p>There are a few different samples in <strong>ApiDemos</strong> that +illustrate how to use loaders:</p> +<ul> + <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/FragmentCursorLoader.html"> FragmentCursorLoader</a> — A complete version of the +snippet shown above.</li> + <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LoaderThrottle.html"> LoaderThrottle</a> — An example of how to use throttling to +reduce the number of queries a content provider does then its data changes.</li> +</ul> + +<p>For information on downloading and installing the SDK samples, see <a +href="http://developer.android.com/resources/samples/get.html"> Getting the +Samples</a>. </p> + diff --git a/docs/html/guide/topics/ui/drag-drop.jd b/docs/html/guide/topics/ui/drag-drop.jd index 588b05b..46ccdf8 100644 --- a/docs/html/guide/topics/ui/drag-drop.jd +++ b/docs/html/guide/topics/ui/drag-drop.jd @@ -88,8 +88,8 @@ page.title=Dragging and Dropping <h2>Related Samples</h2> <ol> <li> - <a href="{@docRoot}resources/samples/Honeycomb-Gallery/index.html"> - Honeycomb-Gallery</a> sample application. + <a href="{@docRoot}resources/samples/HoneycombGallery/index.html"> + Honeycomb Gallery</a>. </li> <li> <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/DragAndDropDemo.html"> |