Handling the Results

As shown in the previous lesson, you should begin loading your data with a CursorLoader in your implementation of onCreateLoader(). The loader then provides the query results to your Activity or FragmentActivity in your implementation of LoaderCallbacks.onLoadFinished(). One of the incoming arguments to this method is a Cursor containing the query results. You can use this object to update your data display or do further processing.

Besides onCreateLoader() and onLoadFinished(), you also have to implement onLoaderReset(). This method is invoked when CursorLoader detects that data associated with the Cursor has changed. When the data changes, the framework also re-runs the current query.

Handle Query Results

To display Cursor data returned by CursorLoader, use a View class that implements AdapterView and provide the view with an adapter that implements CursorAdapter. The system then automatically moves data from the Cursor to the view.

You can set up the linkage between the view and adapter before you have any data to display, and then move a Cursor into the adapter in the onLoadFinished() method. As soon as you move the Cursor into the adapter, the system automatically updates the view. This also happens if you change the contents of the Cursor.

For example:

public String[] mFromColumns = {
    DataProviderContract.IMAGE_PICTURENAME_COLUMN
};
public int[] mToFields = {
    R.id.PictureName
};
// Gets a handle to a List View
ListView mListView = (ListView) findViewById(R.id.dataList);
/*
 * Defines a SimpleCursorAdapter for the ListView
 *
 */
SimpleCursorAdapter mAdapter =
    new SimpleCursorAdapter(
            this,                // Current context
            R.layout.list_item,  // Layout for a single row
            null,                // No Cursor yet
            mFromColumns,        // Cursor columns to use
            mToFields,           // Layout fields to use
            0                    // No flags
    );
// Sets the adapter for the view
mListView.setAdapter(mAdapter);
...
/*
 * Defines the callback that CursorLoader calls
 * when it's finished its query
 */
@Override
public void onLoadFinished(Loader<Cursor> loader, Cursor cursor) {
    ...
    /*
     * Moves the query results into the adapter, causing the
     * ListView fronting this adapter to re-display
     */
    mAdapter.changeCursor(cursor);
}

Delete Old Cursor References

The CursorLoader is reset whenever its Cursor becomes invalid. This usually occurs because the data associated with the Cursor has changed. Before re-running the query, the framework calls your implementation of onLoaderReset(). In this callback, you should delete all references to the current Cursor in order to prevent memory leaks. Once onLoaderReset() finishes, CursorLoader re-runs its query.

For example:

/*
 * Invoked when the CursorLoader is being reset. For example, this is
 * called if the data in the provider changes and the Cursor becomes stale.
 */
@Override
public void onLoaderReset(Loader<Cursor> loader) {
    
    /*
     * Clears out the adapter's reference to the Cursor.
     * This prevents memory leaks.
     */
    mAdapter.changeCursor(null);
}