1page.title=Running a Query with a CursorLoader
2trainingnavtop=true
3startpage=true
4
5@jd:body
6
7<!-- This is the training bar -->
8<div id="tb-wrapper">
9  <div id="tb">
10<h2>This lesson teaches you to</h2>
11<ol>
12    <li>
13        <a href="#Extend">Define an Activity That Uses CursorLoader</a>
14    </li>
15    <li>
16        <a href="#InitializeLoader">Initialize the Query</a>
17    </li>
18    <li>
19        <a href="#DefineLaunch">Start the Query</a>
20    </li>
21</ol>
22
23<h2>Try it out</h2>
24<div class="download-box">
25    <a href="{@docRoot}shareables/training/ThreadSample.zip" class="button">Download the sample</a>
26    <p class="filename">ThreadSample.zip</p>
27</div>
28
29  </div>
30</div>
31<p>
32    A {@link android.support.v4.content.CursorLoader} runs an asynchronous query in the background
33    against a {@link android.content.ContentProvider}, and returns the results to the
34    {@link android.app.Activity} or {@link android.support.v4.app.FragmentActivity} from which it
35    was called. This allows the {@link android.app.Activity} or
36    {@link android.support.v4.app.FragmentActivity} to continue to interact with the user while the
37    query is ongoing.
38</p>
39<h2 id="Extend">Define an Activity That Uses CursorLoader</h2>
40<p>
41    To use a {@link android.support.v4.content.CursorLoader} with an
42    {@link android.app.Activity} or {@link android.support.v4.app.FragmentActivity}, use the
43    {@link android.support.v4.app.LoaderManager.LoaderCallbacks LoaderCallbacks&lt;Cursor&gt;}
44    interface. A {@link android.support.v4.content.CursorLoader} invokes callbacks defined
45    in this interface to communicate with the class; this lesson and the next one
46    describe each callback in detail.
47</p>
48<p>
49    For example, this is how you should define a {@link android.support.v4.app.FragmentActivity}
50    that uses the support library version of {@link android.support.v4.content.CursorLoader}. By
51    extending {@link android.support.v4.app.FragmentActivity}, you get support for
52    {@link android.support.v4.content.CursorLoader} as well as
53    {@link android.support.v4.app.Fragment}:
54</p>
55<pre>
56public class PhotoThumbnailFragment extends FragmentActivity implements
57        LoaderManager.LoaderCallbacks&lt;Cursor&gt; {
58...
59}
60</pre>
61<h2 id="InitializeLoader">Initialize the Query</h2>
62<p>
63    To initialize a query, call
64    {@link android.support.v4.app.LoaderManager#initLoader LoaderManager.initLoader()}. This
65    initializes the background framework. You can do this after the user has entered data that's
66    used in the query, or, if you don't need any user data, you can do it in
67    {@link android.support.v4.app.FragmentActivity#onCreate onCreate()} or
68    {@link android.support.v4.app.Fragment#onCreateView onCreateView()}. For example:
69</p>
70<pre>
71    // Identifies a particular Loader being used in this component
72    private static final int URL_LOADER = 0;
73    ...
74    /* When the system is ready for the Fragment to appear, this displays
75     * the Fragment's View
76     */
77    public View onCreateView(
78            LayoutInflater inflater,
79            ViewGroup viewGroup,
80            Bundle bundle) {
81        ...
82        /*
83         * Initializes the CursorLoader. The URL_LOADER value is eventually passed
84         * to onCreateLoader().
85         */
86        getLoaderManager().initLoader(URL_LOADER, null, this);
87        ...
88    }
89</pre>
90<p class="note">
91    <strong>Note:</strong> The method {@link android.support.v4.app.Fragment#getLoaderManager
92    getLoaderManager()} is only available in the {@link android.support.v4.app.Fragment} class. To
93    get a {@link android.support.v4.app.LoaderManager} in a
94    {@link android.support.v4.app.FragmentActivity}, call
95    {@link android.support.v4.app.FragmentActivity#getSupportLoaderManager
96    getSupportLoaderManager()}.
97</p>
98<h2 id="DefineLaunch">Start the Query</h2>
99<p>
100    As soon as the background framework is initialized, it calls your implementation of
101    {@link android.support.v4.app.LoaderManager.LoaderCallbacks#onCreateLoader onCreateLoader()}.
102    To start the query, return a {@link android.support.v4.content.CursorLoader} from this method.
103    You can instantiate an empty {@link android.support.v4.content.CursorLoader} and then use its
104    methods to define your query, or you can instantiate the object and define the query at the
105    same time:
106</p>
107<pre>
108/*
109* Callback that's invoked when the system has initialized the Loader and
110* is ready to start the query. This usually happens when initLoader() is
111* called. The loaderID argument contains the ID value passed to the
112* initLoader() call.
113*/
114&#64;Override
115public Loader&lt;Cursor&gt; onCreateLoader(int loaderID, Bundle bundle)
116{
117    /*
118     * Takes action based on the ID of the Loader that's being created
119     */
120    switch (loaderID) {
121        case URL_LOADER:
122            // Returns a new CursorLoader
123            return new CursorLoader(
124                        getActivity(),   // Parent activity context
125                        mDataUrl,        // Table to query
126                        mProjection,     // Projection to return
127                        null,            // No selection clause
128                        null,            // No selection arguments
129                        null             // Default sort order
130        );
131        default:
132            // An invalid id was passed in
133            return null;
134    }
135}
136</pre>
137<p>
138    Once the background framework has the object, it starts the query in the background. When the
139    query is done, the background framework calls
140    {@link android.support.v4.app.LoaderManager.LoaderCallbacks#onLoadFinished onLoadFinished()},
141    which is described in the next lesson.
142</p>
143