Android Training: Loading Data in the Background

Change-Id: Ibb469cd068068b37ea95371afb7e4dca4535ba94

1 files changed, 142 insertions, 0 deletions

diff --git a/docs/html/training/load-data-background/setup-loader.jd b/docs/html/training/load-data-background/setup-loader.jd
new file mode 100644
index 0000000..17fe7b0
--- /dev/null
+++ b/docs/html/training/load-data-background/setup-loader.jd
@@ -0,0 +1,142 @@
+page.title=Running a Query with a CursorLoader
+trainingnavtop=true
+startpage=true
+
+@jd:body
+
+<!-- This is the training bar -->
+<div id="tb-wrapper">
+  <div id="tb">
+<h2>This lesson teaches you to</h2>
+<ol>
+    <li>
+        <a href="#Extend">Define an Activity That Uses CursorLoader</a>
+    </li>
+    <li>
+        <a href="#InitializeLoader">Initialize the Query</a>
+    </li>
+    <li>
+        <a href="#DefineLaunch">Start the Query</a>
+    </li>
+</ol>
+
+<h2>Try it out</h2>
+<div class="download-box">
+    <a href="{@docRoot}shareables/training/ThreadSample.zip" class="button">Download the sample</a>
+    <p class="filename">ThreadSample.zip</p>
+</div>
+
+  </div>
+</div>
+<p>
+    A {@link android.support.v4.content.CursorLoader} runs an asynchronous query in the background
+    against a {@link android.content.ContentProvider}, and returns the results to the
+    {@link android.app.Activity} or {@link android.support.v4.app.FragmentActivity} from which it
+    was called. This allows the {@link android.app.Activity} or
+    {@link android.support.v4.app.FragmentActivity} to continue to interact with the user while the
+    query is ongoing.
+</p>
+<h2 id="Extend">Define an Activity That Uses CursorLoader</h2>
+<p>
+    To use a {@link android.support.v4.content.CursorLoader} with an
+    {@link android.app.Activity} or {@link android.support.v4.app.FragmentActivity}, use the
+    {@link android.support.v4.app.LoaderManager.LoaderCallbacks LoaderCallbacks&lt;Cursor&gt;}
+    interface. A {@link android.support.v4.content.CursorLoader} invokes callbacks defined
+    in this interface to communicate with the class; this lesson and the next one
+    describe each callback in detail.
+</p>
+<p>
+    For example, this is how you should define a {@link android.support.v4.app.FragmentActivity}
+    that uses the support library version of {@link android.support.v4.content.CursorLoader}. By
+    extending {@link android.support.v4.app.FragmentActivity}, you get support for
+    {@link android.support.v4.content.CursorLoader} as well as
+    {@link android.support.v4.app.Fragment}:
+</p>
+<pre>
+public class PhotoThumbnailFragment extends FragmentActivity implements
+        LoaderManager.LoaderCallbacks&lt;Cursor&gt; {
+...
+}
+</pre>
+<h2 id="InitializeLoader">Initialize the Query</h2>
+<p>
+    To initialize a query, call
+    {@link android.support.v4.app.LoaderManager#initLoader LoaderManager.initLoader()}. This
+    initializes the background framework. You can do this after the user has entered data that's
+    used in the query, or, if you don't need any user data, you can do it in
+    {@link android.support.v4.app.FragmentActivity#onCreate onCreate()} or
+    {@link android.support.v4.app.Fragment#onCreateView onCreateView()}. For example:
+</p>
+<pre>
+    // Identifies a particular Loader being used in this component
+    private static final int URL_LOADER = 0;
+    ...
+    /* When the system is ready for the Fragment to appear, this displays
+     * the Fragment's View
+     */
+    public View onCreateView(
+            LayoutInflater inflater,
+            ViewGroup viewGroup,
+            Bundle bundle) {
+        ...
+        /*
+         * Initializes the CursorLoader. The URL_LOADER value is eventually passed
+         * to onCreateLoader().
+         */
+        getLoaderManager().initLoader(URL_LOADER, null, this);
+        ...
+    }
+</pre>
+<p class="note">
+    <strong>Note:</strong> The method {@link android.support.v4.app.Fragment#getLoaderManager
+    getLoaderManager()} is only available in the {@link android.support.v4.app.Fragment} class. To
+    get a {@link android.support.v4.app.LoaderManager} in a
+    {@link android.support.v4.app.FragmentActivity}, call
+    {@link android.support.v4.app.FragmentActivity#getSupportLoaderManager
+    getSupportLoaderManager()}.
+</p>
+<h2 id="DefineLaunch">Start the Query</h2>
+<p>
+    As soon as the background framework is initialized, it calls your implementation of
+    {@link android.support.v4.app.LoaderManager.LoaderCallbacks#onCreateLoader onCreateLoader()}.
+    To start the query, return a {@link android.support.v4.content.CursorLoader} from this method.
+    You can instantiate an empty {@link android.support.v4.content.CursorLoader} and then use its
+    methods to define your query, or you can instantiate the object and define the query at the
+    same time:
+</p>
+<pre>
+/*
+* Callback that's invoked when the system has initialized the Loader and
+* is ready to start the query. This usually happens when initLoader() is
+* called. The loaderID argument contains the ID value passed to the
+* initLoader() call.
+*/
+&#64;Override
+public Loader&lt;Cursor&gt; onCreateLoader(int loaderID, Bundle bundle)
+{
+    /*
+     * Takes action based on the ID of the Loader that's being created
+     */
+    switch (loaderID) {
+        case URL_LOADER:
+            // Returns a new CursorLoader
+            return new CursorLoader(
+                        getActivity(),   // Parent activity context
+                        mDataUrl,        // Table to query
+                        mProjection,     // Projection to return
+                        null,            // No selection clause
+                        null,            // No selection arguments
+                        null             // Default sort order
+        );
+        default:
+            // An invalid id was passed in
+            return null;
+    }
+}
+</pre>
+<p>
+    Once the background framework has the object, it starts the query in the background. When the
+    query is done, the background framework calls
+    {@link android.support.v4.app.LoaderManager.LoaderCallbacks#onLoadFinished onLoadFinished()},
+    which is described in the next lesson.
+</p>