diff options
Diffstat (limited to 'docs/html/guide')
| -rw-r--r-- | docs/html/guide/appendix/market-filters.jd | 94 | ||||
| -rw-r--r-- | docs/html/guide/developing/testing/index.jd | 4 | ||||
| -rw-r--r-- | docs/html/guide/developing/tools/monkeyrunner_concepts.jd | 13 | ||||
| -rw-r--r-- | docs/html/guide/guide_toc.cs | 22 | ||||
| -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 |
10 files changed, 807 insertions, 86 deletions
diff --git a/docs/html/guide/appendix/market-filters.jd b/docs/html/guide/appendix/market-filters.jd index 6ca8acc..f826f43 100644 --- a/docs/html/guide/appendix/market-filters.jd +++ b/docs/html/guide/appendix/market-filters.jd @@ -5,23 +5,25 @@ page.title=Market Filters <div id="qv"> <h2>Quickview</h2> -<ul> <li>Android Market applies filters to that let you control whether your app is shown to a -user who is browing or searching for apps.</li> -<li>Filtering is determined by elements in an app's manifest file, -aspects of the device being used, and other factors.</li> </ul> +<ul> +<li>Android Market applies filters that control which Android-powered devices can access your +application on Market.</li> +<li>Filtering is determined by comparing device configurations that you declare in you app's +manifest file to the configurations defined by the device, as well as other factors.</li> </ul> <h2>In this document</h2> <ol> <li><a href="#how-filters-work">How Filters Work in Android Market</a></li> <li><a href="#manifest-filters">Filtering based on Manifest File Elements</a></li> <li><a href="#other-filters">Other Filters</a></li> +<li><a href="#advanced-filters">Advanced Manifest Filters</a></li> </ol> <h2>See also</h2> <ol> <li><a -href="{@docRoot}guide/practices/compatibility.html">Compatibility</a></li> -<li style="margin-top:2px;"><code><a +href="{@docRoot}guide/practices/compatibility.html">Android Compatibility</a></li> +<li><code><a href="{@docRoot}guide/topics/manifest/supports-screens-element.html"><supports-screens></a></code></li> <li><code><a href="{@docRoot}guide/topics/manifest/uses-configuration-element.html"><uses-configuration></a></code></li> @@ -42,36 +44,40 @@ publishing your app on Android Market?</p> <a id="publish-link" href="http://market.android.com/publish">Go to Android Market »</a> </div> </div> -</div> </div> +</div> +</div> + -<p>When a user searches or browses in Android Market, the results are filtered, and -some applications might not be visible. For example, if an application requires a +<p>When a user searches or browses in Android Market, the results are filtered based on which +applications are compatible with the user's device. For example, if an application requires a trackball (as specified in the manifest file), then Android Market will not show -the app on any device that does not have a trackball.</p> <p>The manifest file and -the device's hardware and features are only part of how applications are filtered -— filtering also depends on the country and carrier, the presence or absence -of a SIM card, and other factors. </p> +the app on any device that does not have a trackball.</p> + +<p>The manifest file and the device's hardware and features are only part of how applications are +filtered—filtering might also depend on the country and carrier, the presence or absence of a +SIM card, and other factors. </p> <p>Changes to the Android Market filters are independent of changes to the Android platform itself. This document will be updated periodically to reflect -any changes that occur. </p> +any changes that affect the way Android Market filters applications.</p> + <h2 id="how-filters-work">How Filters Work in Android Market</h2> <p>Android Market uses the filter restrictions described below to determine whether to show your application to a user who is browsing or searching for -applications on a given device. When determining whether to display your app, +applications on an Android-powered device. When determining whether to display your app, Market checks the device's hardware and software capabilities, as well as it's carrier, location, and other characteristics. It then compares those against the restrictions and dependencies expressed by the application itself, in its -manifest, <code>.apk</code>, and publishing details. If the application is +manifest file and publishing details. If the application is compatible with the device according to the filter rules, Market displays the application to the user. Otherwise, Market hides your application from search results and category browsing. </p> -<p> You can use the filters described below to control whether Market shows or -hides your application to users. You can request any combination of the -available filters for your app — for example, you could set a +<p>You can use the filters described below to control whether Market shows or +hides your application to users. You can use any combination of the +available filters for your app—for example, you can set a <code>minSdkVersion</code> requirement of <code>"4"</code> and set <code>smallScreens="false"</code> in the app, then when uploading the app to Market you could target European countries (carriers) only. Android Market's @@ -92,16 +98,18 @@ makes the app invisible to the user, the user will not see that an upgrade is available. </li> </ul> + + <h2 id="manifest-filters">Filtering based on Manifest Elements</h2> <p>Most Market filters are triggered by elements within an application's manifest file, <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a>, -although not everything in the manifest file can trigger filtering. The -table below lists the manifest elements that you can use to trigger Android -Market filtering, and explains how the filtering works.</p> +although not everything in the manifest file can trigger filtering. +Table 1 lists the manifest elements that you should use to trigger Android +Market filtering, and explains how the filtering for each element works.</p> -<p class="table-caption"><strong>Table 1.</strong> Manifest elements that +<p id="table1" class="table-caption"><strong>Table 1.</strong> Manifest elements that trigger filtering on Market.</p> <table> <tr> @@ -313,10 +321,13 @@ href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#max"><code>android:m </tr> </table> + <h2 id="other-filters">Other Filters</h2> + <p>Android Market uses other application characteristics to determine whether to show or hide an application for a particular user on a given device, as described in the table below. </p> -<p class="table-caption"><strong>Table 2.</strong> Application and publishing characteristics that affect filtering on Market.</p> +<p id="table2" class="table-caption"><strong>Table 2.</strong> Application and publishing +characteristics that affect filtering on Market.</p> <table> <tr> <th>Filter Name</th> <th>How It Works</th> </tr> @@ -351,3 +362,38 @@ country (as determined by SIM carrier) in which paid apps are available.</p></td developer devices or unreleased devices.</p></td> </tr> </table> + + +<h2 id="advanced-filters">Advanced Manifest Filters</h2> + +<p>In addition to the manifest elements in <a href="#table1">table 1</a>, Android Market can also +filter applications based on the advanced manifest elements in table 3.</p> + +<p>These manifest elements and the filtering they trigger are for exceptional use-cases +only. They are designed for some types of high-performance games and similar applications that +require strict controls on application distribution. <strong>Most applications should never use +these filters</strong>.</p> + +<p id="table3" class="table-caption"><strong>Table 3.</strong> Advanced manifest elements for +Android Market filtering.</p> +<table> + <tr><th>Manifest Element</th><th>Summary</th></tr> + <tr> + <td><nobr><a href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">{@code +<compatible-screens>}</a></nobr></td> + <td> + <p>Android Market filters the application if the device screen size and density does not match +any of the screen configurations (declared by a {@code <screen>} element) in the {@code +<compatible-screens>} element.</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 excluding all combinations of screen size +and density that you have not listed. You should instead use the <a +href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code +<supports-screens>}</a> manifest element (described above in <a href="#table1">table +1</a>) to enable screen compatibility mode for screen configurations you have not accounted for +with alternative resources.</p> + </td> + </tr> +</table> + diff --git a/docs/html/guide/developing/testing/index.jd b/docs/html/guide/developing/testing/index.jd index 8ffaf58..8a08959 100644 --- a/docs/html/guide/developing/testing/index.jd +++ b/docs/html/guide/developing/testing/index.jd @@ -18,14 +18,14 @@ page.title=Testing which guides you through a more complex testing scenario. </p> <dl> - <dt><a href="testing_eclipse.html">Testing in Eclipse, with ADT</a></dt> + <dt><a href="testing_eclipse.html">Testing from Eclipse, with ADT</a></dt> <dd> The ADT plugin lets you quickly set up and manage test projects directly in the Eclipse UI. Once you have written your tests, you can build and run them and then see the results in the Eclipse JUnit view. You can also use the SDK command-line tools to execute your tests if needed. </dd> - <dt><a href="testing_otheride.html">Testing in Other IDEs</a></dt> + <dt><a href="testing_otheride.html">Testing from Other IDEs</a></dt> <dd> The SDK command-line tools provide the same capabilities as the ADT plugin. You can use them to set up and manage test projects, build your test application, diff --git a/docs/html/guide/developing/tools/monkeyrunner_concepts.jd b/docs/html/guide/developing/tools/monkeyrunner_concepts.jd index d648b93..658ff75 100644 --- a/docs/html/guide/developing/tools/monkeyrunner_concepts.jd +++ b/docs/html/guide/developing/tools/monkeyrunner_concepts.jd @@ -110,8 +110,17 @@ device = MonkeyRunner.waitForConnection() # to see if the installation worked. device.installPackage('myproject/bin/MyApplication.apk') -# Runs an activity in the application -device.startActivity(component='com.example.android.myapplication.MainActivity') +# sets a variable with the package's internal name +package = 'com.example.android.myapplication' + +# sets a variable with the name of an Activity in the package +activity = 'com.example.android.myapplication.MainActivity' + +# sets the name of the component to start +runComponent = package + '/' + activity + +# Runs the component +device.startActivity(component=runComponent) # Presses the Menu button device.press('KEYCODE_MENU','DOWN_AND_UP') diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs index 0ea4b83..24ccfdb 100644 --- a/docs/html/guide/guide_toc.cs +++ b/docs/html/guide/guide_toc.cs @@ -65,6 +65,9 @@ <li><a href="<?cs var:toroot ?>guide/topics/fundamentals/fragments.html"> <span class="en">Fragments</span> </a> <span class="new">new!</span></li> + <li><a href="<?cs var:toroot ?>guide/topics/providers/loaders.html"> + <span class="en">Loaders</span> + </a><span class="new">new!</span></li> <li><a href="<?cs var:toroot ?>guide/topics/fundamentals/tasks-and-back-stack.html"> <span class="en">Tasks and Back Stack</span> </a></li> @@ -95,8 +98,9 @@ <ul> <li class="toggle-list"> <div><a href="<?cs var:toroot ?>guide/topics/ui/index.html"> - <span class="en">User Interface</span> - </a></div> + <span class="en">User Interface</span> + </a> + <span class="new">more!</span></div> <ul> <li><a href="<?cs var:toroot ?>guide/topics/ui/declaring-layout.html"> <span class="en">Declaring Layout</span> @@ -207,6 +211,7 @@ <li><a href="<?cs var:toroot ?>guide/topics/manifest/activity-alias-element.html"><activity-alias></a></li> <li><a href="<?cs var:toroot ?>guide/topics/manifest/application-element.html"><application></a></li> <li><a href="<?cs var:toroot ?>guide/topics/manifest/category-element.html"><category></a></li> + <li><a href="<?cs var:toroot ?>guide/topics/manifest/compatible-screens-element.html"><compatible-screens></a></li> <li><a href="<?cs var:toroot ?>guide/topics/manifest/data-element.html"><data></a></li> <li><a href="<?cs var:toroot ?>guide/topics/manifest/grant-uri-permission-element.html"><grant-uri-permission></a></li> <li><a href="<?cs var:toroot ?>guide/topics/manifest/instrumentation-element.html"><instrumentation></a></li> @@ -233,8 +238,9 @@ <ul> <li class="toggle-list"> <div><a href="<?cs var:toroot ?>guide/topics/graphics/index.html"> - <span class="en">Graphics</span> - </a></div> + <span class="en">Graphics</span> + </a> + <span class="new">more!</span></div> <ul> <li><a href="<?cs var:toroot ?>guide/topics/graphics/2d-graphics.html"> <span class="en">2D Graphics</span> @@ -253,15 +259,15 @@ </a></li> </ul> </li> + <li><a href="<?cs var:toroot ?>guide/topics/media/index.html"> + <span class="en">Audio and Video</span> + </a></li> <li> <a href="<?cs var:toroot ?>guide/topics/clipboard/copy-paste.html"> - <span class="en">Copying and Pasting</span> + <span class="en">Copy and Paste</span> </a> <span class="new">new!</span> </li> - <li><a href="<?cs var:toroot ?>guide/topics/media/index.html"> - <span class="en">Audio and Video</span> - </a></li> <!--<li class="toggle-list"> <div><a style="color:gray;">Sensors</a></div> <ul> 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"> |