guide/components/loaders.jd

page.title=
parent.title=
parent.link=activities.html
@jd:body
<div id="qv-wrapper">
<div id="qv">
    <h2></h2>
    <ol>
    <li><a href="#summary">Loader API </a></li>
    <li><a href="#app"></a>
      <ol>
        <li><a href="#requirements"></a></li>
        <li><a href="#starting"></a></li>
        <li><a href="#restarting"></a></li>
        <li><a href="#callback">LoaderManager </a></li>
      </ol>
    </li>
    <li><a href="#example"></a>
       <ol>
         <li><a href="#more_examples"></a></li>
        </ol>
    </li>
  </ol>

  <h2></h2>
    <ol>
      <li>{@link android.app.LoaderManager}</li>
      <li>{@link android.content.Loader}</li>

    </ol>

    <h2></h2>
   <ol>
     <li> <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LoaderCursor.html">
LoaderCursor</a></li>
     <li> <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LoaderThrottle.html">
LoaderThrottle</a></li>
   </ol>
  </div>
</div>

<p>Android 3.0
 3 </p>
  <ul>
    <li> {@link android.app.Activity}  {@link
android.app.Fragment} </li>
    <li></li>
    <li>
</li>
    <li>

</li>
  </ul>

<h2 id="summary">Loader API </h2>

<p>
</p>

<table>
  <tr>
    <th>/</th>
    <th></th>
  </tr>
  <tr>
    <td>{@link android.app.LoaderManager}</td>
    <td>1  {@link
android.content.Loader} {@link android.app.Activity}  {@link android.app.Fragment}
 {@link android.app.Activity}  {@link android.app.Fragment} {@link android.content.CursorLoader}


    <br />
    <br />
    1 {@link android.app.LoaderManager}  1 {@link android.app.LoaderManager}
</td>
  </tr>
  <tr>
    <td>{@link android.app.LoaderManager.LoaderCallbacks}</td>
    <td> {@link
android.app.LoaderManager}  {@link
android.app.LoaderManager.LoaderCallbacks#onCreateLoader onCreateLoader()}
</td>
  </tr>
  <tr>
    <td>{@link android.content.Loader}</td>
    <td>
 {@link
android.content.CursorLoader}

 </td>
  </tr>
  <tr>
    <td>{@link android.content.AsyncTaskLoader}</td>
    <td> {@link android.os.AsyncTask} </td>
  </tr>
  <tr>
    <td>{@link android.content.CursorLoader}</td>
    <td>{@link android.content.ContentResolver}  {@link
android.database.Cursor} {@link android.content.AsyncTaskLoader}
 {@link
android.content.Loader}  UI {@link android.content.AsyncTaskLoader} {@link
android.content.ContentProvider}  API  API


</td>
  </tr>
</table>

<p>
{@link
android.app.LoaderManager}  {@link
android.content.CursorLoader}  {@link android.content.Loader}  {@link
android.app.LoaderManager}

</p>

<h2 id ="app"></h2>
<p>Android
</p>
<ul>
  <li>{@link android.app.Activity}  {@link android.app.Fragment}</li>
  <li>{@link android.app.LoaderManager} </li>
  <li>{@link
android.content.ContentProvider}  {@link android.content.CursorLoader}{@link android.content.Loader} {@link android.content.AsyncTaskLoader}

</li>
  <li>{@link android.app.LoaderManager.LoaderCallbacks}

</li>
<li>{@link
android.widget.SimpleCursorAdapter} </li>
  <li>{@link android.content.CursorLoader} {@link android.content.ContentProvider}
</li>
</ul>
<h3 id="starting"></h3>

<p>{@link android.app.LoaderManager}  1  {@link
android.content.Loader}  {@link android.app.Activity}  {@link android.app.Fragment}
1 {@link
android.app.LoaderManager}  1 </p>

<p> {@link
android.app.Activity#onCreate onCreate()}  {@link android.app.Fragment#onActivityCreated onActivityCreated()}  {@link android.content.Loader}


</p>

<pre>// Prepare the loader.  Either re-connect with an existing one,
// or start a new one.
getLoaderManager().initLoader(0, null, this);</pre>

<p>{@link android.app.LoaderManager#initLoader initLoader()}
</p>
<ul>
  <li> IDID  0 </li>
<li> <code>null</code>
</li>

<li>{@link android.app.LoaderManager}  {@link android.app.LoaderManager.LoaderCallbacks}
 {@link
android.app.LoaderManager.LoaderCallbacks}  {@code this}

</li>
</ul>
<p>{@link android.app.LoaderManager#initLoader initLoader()}
 2 </p>
<ul>
  <li>ID
</li>
  <li>ID <em></em>{@link android.app.LoaderManager#initLoader initLoader()}  {@link android.app.LoaderManager.LoaderCallbacks}  {@link android.app.LoaderManager.LoaderCallbacks#onCreateLoader onCreateLoader()} <a href="#onCreateLoader">onCreateLoader</a>


</li>
</ul>
<p> {@link android.app.LoaderManager.LoaderCallbacks}

 {@link
android.app.LoaderManager.LoaderCallbacks#onLoadFinished onLoadFinished()} {@link android.app.LoaderManager#initLoader initLoader()}


<a href="#onLoadFinished">
onLoadFinished</a> </p>

<p>{@link android.app.LoaderManager#initLoader initLoader()}  {@link android.content.Loader}

{@link android.app.LoaderManager}
{@link android.app.LoaderManager}

 <a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LoaderThrottle.html"> LoaderThrottle</a>

{@link
android.app.LoaderManager.LoaderCallbacks}

<a href="#callback">LoadManager </a></p>

<h3 id="restarting"></h3>

<p> {@link android.app.LoaderManager#initLoader initLoader()}  ID


</p>

<p>{@link
android.app.LoaderManager#restartLoader restartLoader()}  {@link android.widget.SearchView.OnQueryTextListener}


</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">LoaderManager </h3>

<p>{@link android.app.LoaderManager.LoaderCallbacks}  {@link android.app.LoaderManager}
 </p>
<p>{@link android.content.CursorLoader}
 {@link android.app.Activity#onStop
onStop()}  {@link android.app.Activity#onStart onStart()}


{@link android.app.LoaderManager.LoaderCallbacks}

</p>

<p>{@link android.app.LoaderManager.LoaderCallbacks}
</p>
<ul>
  <li>{@link android.app.LoaderManager.LoaderCallbacks#onCreateLoader onCreateLoader()}   ID  {@link android.content.Loader}

</li></ul>
<ul>
  <li> {@link android.app.LoaderManager.LoaderCallbacks#onLoadFinished onLoadFinished()}

</li></ul>
<ul>
  <li>{@link android.app.LoaderManager.LoaderCallbacks#onLoaderReset onLoaderReset()}


</li>
</ul>
<p></p>

<h4 id ="onCreateLoader">onCreateLoader</h4>

<p>{@link
android.app.LoaderManager#initLoader initLoader()} ID
{@link
android.app.LoaderManager.LoaderCallbacks}  {@link
android.app.LoaderManager.LoaderCallbacks#onCreateLoader onCreateLoader()}
{@link
android.content.CursorLoader}  {@link
android.content.Loader}  </p>

<p>{@link
android.app.LoaderManager.LoaderCallbacks#onCreateLoader onCreateLoader()}
  {@link android.content.CursorLoader} {@link android.content.CursorLoader} {@link
android.content.ContentProvider}

</p>
<ul>
  <li><em>uri</em>   URI </li>
  <li><em>projection</em>  <code>null</code>
 </li>
  <li><em>selection</em>  SQL WHERE WHERE
<code>null</code>  URI
 </li>
  <li><em>selectionArgs</em>  selection  ? selection  <em>selectionArgs</em>

Strings  </li>
  <li><em>sortOrder</em>  SQL
ORDER BY ORDER <code>null</code>
</li>
</ul>
<p></p>
<pre>
 // If non-null, this is the current filter the user has provided.
String mCurFilter;
...
public Loader&lt;Cursor&gt; 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 = &quot;((&quot; + Contacts.DISPLAY_NAME + &quot; NOTNULL) AND (&quot;
      + Contacts.HAS_PHONE_NUMBER + &quot;=1) AND (&quot;
      + Contacts.DISPLAY_NAME + &quot; != '' ))&quot;;
  return new CursorLoader(getActivity(), baseUri,
      CONTACTS_SUMMARY_PROJECTION, select, null,
      Contacts.DISPLAY_NAME + &quot; COLLATE LOCALIZED ASC&quot;);
}</pre>
<h4 id="onLoadFinished">onLoadFinished</h4>

<p>


</p>


<p>
 {@link
android.content.CursorLoader}  {@link
android.database.Cursor#close close()}  {@link android.widget.CursorAdapter}  {@link android.database.Cursor}  {@link
android.widget.SimpleCursorAdapter#swapCursor swapCursor()}

</p>

<pre>
// This is the Adapter being used to display the list's data.<br
/>SimpleCursorAdapter mAdapter;
...

public void onLoadFinished(Loader&lt;Cursor&gt; 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>

 </p>
<p><code>null</code>  {@link android.widget.SimpleCursorAdapter#swapCursor swapCursor()}

</p>

<pre>
// This is the Adapter being used to display the list's data.
SimpleCursorAdapter mAdapter;
...

public void onLoaderReset(Loader&lt;Cursor&gt; 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"></h2>

<p>  {@link android.widget.ListView}  {@link
android.app.Fragment}
{@link
android.content.CursorLoader} </p>

<p> {@link android.Manifest.permission#READ_CONTACTS READ_CONTACTS}

</p>

<pre>
public static class CursorLoaderListFragment extends ListFragment
    implements OnQueryTextListener, LoaderManager.LoaderCallbacks&lt;Cursor&gt; {

    // 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(&quot;No phone numbers&quot;);

    // 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(&quot;Search&quot;);
    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(&quot;FragmentComplexList&quot;, &quot;Item clicked: &quot; + 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&lt;Cursor&gt; 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 = &quot;((&quot; + Contacts.DISPLAY_NAME + &quot; NOTNULL) AND (&quot;
        + Contacts.HAS_PHONE_NUMBER + &quot;=1) AND (&quot;
        + Contacts.DISPLAY_NAME + &quot; != '' ))&quot;;
    return new CursorLoader(getActivity(), baseUri,
        CONTACTS_SUMMARY_PROJECTION, select, null,
        Contacts.DISPLAY_NAME + &quot; COLLATE LOCALIZED ASC&quot;);
  }

  public void onLoadFinished(Loader&lt;Cursor&gt; 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&lt;Cursor&gt; 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"></h3>

<p><strong>ApiDemos</strong>
</p>
<ul>
  <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LoaderCursor.html">
LoaderCursor</a>
</li>
  <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LoaderThrottle.html"> LoaderThrottle</a>
</li>
</ul>

<p>SDK <a href="http://developer.android.com/resources/samples/get.html">Getting the Samples</a>
 </p>