1 page.title=Running a Query with a CursorLoader 2 trainingnavtop=true 3 startpage=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<Cursor>} 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> 56 public class PhotoThumbnailFragment extends FragmentActivity implements 57 LoaderManager.LoaderCallbacks<Cursor> { 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 @Override 115 public Loader<Cursor> 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
