FileDocCategorySizeDatePackage
CursorAdapter.javaAPI DocAndroid 5.1 API16645Thu Mar 12 22:22:10 GMT 2015android.widget

CursorAdapter

public abstract class CursorAdapter extends BaseAdapter implements Filterable, CursorFilter.CursorFilterClient
Adapter that exposes data from a {@link android.database.Cursor Cursor} to a {@link android.widget.ListView ListView} widget.

The Cursor must include a column named "_id" or this class will not work. Additionally, using {@link android.database.MergeCursor} with this class will not work if the merged Cursors have overlapping values in their "_id" columns.

Fields Summary
protected boolean
mDataValid
This field should be made private, so it is hidden from the SDK. {@hide}
protected boolean
mAutoRequery
This field should be made private, so it is hidden from the SDK. {@hide}
protected android.database.Cursor
mCursor
This field should be made private, so it is hidden from the SDK. {@hide}
protected android.content.Context
mContext
This field should be made private, so it is hidden from the SDK. {@hide}
protected int
mRowIDColumn
This field should be made private, so it is hidden from the SDK. {@hide}
protected ChangeObserver
mChangeObserver
This field should be made private, so it is hidden from the SDK. {@hide}
protected android.database.DataSetObserver
mDataSetObserver
This field should be made private, so it is hidden from the SDK. {@hide}
protected CursorFilter
mCursorFilter
This field should be made private, so it is hidden from the SDK. {@hide}
protected FilterQueryProvider
mFilterQueryProvider
This field should be made private, so it is hidden from the SDK. {@hide}
public static final int
FLAG_AUTO_REQUERY
If set the adapter will call requery() on the cursor whenever a content change notification is delivered. Implies {@link #FLAG_REGISTER_CONTENT_OBSERVER}.
public static final int
FLAG_REGISTER_CONTENT_OBSERVER
If set the adapter will register a content observer on the cursor and will call {@link #onContentChanged()} when a notification comes in. Be careful when using this flag: you will need to unset the current Cursor from the adapter to avoid leaks due to its registered observers. This flag is not needed when using a CursorAdapter with a {@link android.content.CursorLoader}.
Constructors Summary
public CursorAdapter(android.content.Context context, android.database.Cursor c)
Constructor that always enables auto-requery.

deprecated
This option is discouraged, as it results in Cursor queries being performed on the application's UI thread and thus can cause poor responsiveness or even Application Not Responding errors. As an alternative, use {@link android.app.LoaderManager} with a {@link android.content.CursorLoader}.
param
c The cursor from which to get the data.
param
context The context


                                                                     
    
         
        init(context, c, FLAG_AUTO_REQUERY);
public CursorAdapter(android.content.Context context, android.database.Cursor c, boolean autoRequery)
Constructor that allows control over auto-requery. It is recommended you not use this, but instead {@link #CursorAdapter(Context, Cursor, int)}. When using this constructor, {@link #FLAG_REGISTER_CONTENT_OBSERVER} will always be set.

param
c The cursor from which to get the data.
param
context The context
param
autoRequery If true the adapter will call requery() on the cursor whenever it changes so the most recent data is always displayed. Using true here is discouraged.

        init(context, c, autoRequery ? FLAG_AUTO_REQUERY : FLAG_REGISTER_CONTENT_OBSERVER);
public CursorAdapter(android.content.Context context, android.database.Cursor c, int flags)
Recommended constructor.

param
c The cursor from which to get the data.
param
context The context
param
flags Flags used to determine the behavior of the adapter; may be any combination of {@link #FLAG_AUTO_REQUERY} and {@link #FLAG_REGISTER_CONTENT_OBSERVER}.

        init(context, c, flags);
Methods Summary
public abstract voidbindView(android.view.View view, android.content.Context context, android.database.Cursor cursor)
Bind an existing view to the data pointed to by cursor

param
view Existing view, returned earlier by newView
param
context Interface to application's global information
param
cursor The cursor from which to get the data. The cursor is already moved to the correct position.

public voidchangeCursor(android.database.Cursor cursor)
Change the underlying cursor to a new cursor. If there is an existing cursor it will be
closed.
param
cursor The new cursor to be used
        Cursor old = swapCursor(cursor);
        if (old != null) {
            old.close();
        }
    
public java.lang.CharSequenceconvertToString(android.database.Cursor cursor)
Converts the cursor into a CharSequence. Subclasses should override this
method to convert their results. The default implementation returns an
empty String for null values or the default String representation of
the value.
param
cursor the cursor to convert to a CharSequence
return
a CharSequence representing the value
        return cursor == null ? "" : cursor.toString();
    
public intgetCount()
see
android.widget.ListAdapter#getCount()
        if (mDataValid && mCursor != null) {
            return mCursor.getCount();
        } else {
            return 0;
        }
    
public android.database.CursorgetCursor()
Returns the cursor.
return
the cursor.
        return mCursor;
    
public android.view.ViewgetDropDownView(int position, android.view.View convertView, android.view.ViewGroup parent)
        if (mDataValid) {
            mCursor.moveToPosition(position);
            View v;
            if (convertView == null) {
                v = newDropDownView(mContext, mCursor, parent);
            } else {
                v = convertView;
            }
            bindView(v, mContext, mCursor);
            return v;
        } else {
            return null;
        }
    
public FiltergetFilter()
        if (mCursorFilter == null) {
            mCursorFilter = new CursorFilter(this);
        }
        return mCursorFilter;
    
public FilterQueryProvidergetFilterQueryProvider()
Returns the query filter provider used for filtering. When the
provider is null, no filtering occurs.
return
the current filter query provider or null if it does not exist
see
#setFilterQueryProvider(android.widget.FilterQueryProvider)
see
#runQueryOnBackgroundThread(CharSequence)
        return mFilterQueryProvider;
    
public java.lang.ObjectgetItem(int position)
see
android.widget.ListAdapter#getItem(int)
        if (mDataValid && mCursor != null) {
            mCursor.moveToPosition(position);
            return mCursor;
        } else {
            return null;
        }
    
public longgetItemId(int position)
see
android.widget.ListAdapter#getItemId(int)
        if (mDataValid && mCursor != null) {
            if (mCursor.moveToPosition(position)) {
                return mCursor.getLong(mRowIDColumn);
            } else {
                return 0;
            }
        } else {
            return 0;
        }
    
public android.view.ViewgetView(int position, android.view.View convertView, android.view.ViewGroup parent)
see
android.widget.ListAdapter#getView(int, View, ViewGroup)
        if (!mDataValid) {
            throw new IllegalStateException("this should only be called when the cursor is valid");
        }
        if (!mCursor.moveToPosition(position)) {
            throw new IllegalStateException("couldn't move cursor to position " + position);
        }
        View v;
        if (convertView == null) {
            v = newView(mContext, mCursor, parent);
        } else {
            v = convertView;
        }
        bindView(v, mContext, mCursor);
        return v;
    
public booleanhasStableIds()
        return true;
    
protected voidinit(android.content.Context context, android.database.Cursor c, boolean autoRequery)
deprecated
Don't use this, use the normal constructor. This will
be removed in the future.
        init(context, c, autoRequery ? FLAG_AUTO_REQUERY : FLAG_REGISTER_CONTENT_OBSERVER);
    
voidinit(android.content.Context context, android.database.Cursor c, int flags)
        if ((flags & FLAG_AUTO_REQUERY) == FLAG_AUTO_REQUERY) {
            flags |= FLAG_REGISTER_CONTENT_OBSERVER;
            mAutoRequery = true;
        } else {
            mAutoRequery = false;
        }
        boolean cursorPresent = c != null;
        mCursor = c;
        mDataValid = cursorPresent;
        mContext = context;
        mRowIDColumn = cursorPresent ? c.getColumnIndexOrThrow("_id") : -1;
        if ((flags & FLAG_REGISTER_CONTENT_OBSERVER) == FLAG_REGISTER_CONTENT_OBSERVER) {
            mChangeObserver = new ChangeObserver();
            mDataSetObserver = new MyDataSetObserver();
        } else {
            mChangeObserver = null;
            mDataSetObserver = null;
        }

        if (cursorPresent) {
            if (mChangeObserver != null) c.registerContentObserver(mChangeObserver);
            if (mDataSetObserver != null) c.registerDataSetObserver(mDataSetObserver);
        }
    
public android.view.ViewnewDropDownView(android.content.Context context, android.database.Cursor cursor, android.view.ViewGroup parent)
Makes a new drop down view to hold the data pointed to by cursor.
param
context Interface to application's global information
param
cursor The cursor from which to get the data. The cursor is already
moved to the correct position.
param
parent The parent to which the new view is attached to
return
the newly created view.
        return newView(context, cursor, parent);
    
public abstract android.view.ViewnewView(android.content.Context context, android.database.Cursor cursor, android.view.ViewGroup parent)
Makes a new view to hold the data pointed to by cursor.
param
context Interface to application's global information
param
cursor The cursor from which to get the data. The cursor is already
moved to the correct position.
param
parent The parent to which the new view is attached to
return
the newly created view.
protected voidonContentChanged()
Called when the {@link ContentObserver} on the cursor receives a change notification.
The default implementation provides the auto-requery logic, but may be overridden by
sub classes.
see
ContentObserver#onChange(boolean)
        if (mAutoRequery && mCursor != null && !mCursor.isClosed()) {
            if (false) Log.v("Cursor", "Auto requerying " + mCursor + " due to update");
            mDataValid = mCursor.requery();
        }
    
public android.database.CursorrunQueryOnBackgroundThread(java.lang.CharSequence constraint)
Runs a query with the specified constraint. This query is requested
by the filter attached to this adapter.

The query is provided by a
{@link android.widget.FilterQueryProvider}.
If no provider is specified, the current cursor is not filtered and returned.

After this method returns the resulting cursor is passed to {@link #changeCursor(Cursor)}
and the previous cursor is closed.

This method is always executed on a background thread, not on the
application's main thread (or UI thread.)

Contract: when constraint is null or empty, the original results,
prior to any filtering, must be returned.
param
constraint the constraint with which the query must be filtered
return
a Cursor representing the results of the new query
see
#getFilter()
see
#getFilterQueryProvider()
see
#setFilterQueryProvider(android.widget.FilterQueryProvider)
        if (mFilterQueryProvider != null) {
            return mFilterQueryProvider.runQuery(constraint);
        }

        return mCursor;
    
public voidsetFilterQueryProvider(FilterQueryProvider filterQueryProvider)
Sets the query filter provider used to filter the current Cursor.
The provider's
{@link android.widget.FilterQueryProvider#runQuery(CharSequence)}
method is invoked when filtering is requested by a client of
this adapter.
param
filterQueryProvider the filter query provider or null to remove it
see
#getFilterQueryProvider()
see
#runQueryOnBackgroundThread(CharSequence)
        mFilterQueryProvider = filterQueryProvider;
    
public android.database.CursorswapCursor(android.database.Cursor newCursor)
Swap in a new Cursor, returning the old Cursor. Unlike
{@link #changeCursor(Cursor)}, the returned old Cursor is not
closed.
param
newCursor The new cursor to be used.
return
Returns the previously set Cursor, or null if there wasa not one.
If the given new Cursor is the same instance is the previously set
Cursor, null is also returned.
        if (newCursor == mCursor) {
            return null;
        }
        Cursor oldCursor = mCursor;
        if (oldCursor != null) {
            if (mChangeObserver != null) oldCursor.unregisterContentObserver(mChangeObserver);
            if (mDataSetObserver != null) oldCursor.unregisterDataSetObserver(mDataSetObserver);
        }
        mCursor = newCursor;
        if (newCursor != null) {
            if (mChangeObserver != null) newCursor.registerContentObserver(mChangeObserver);
            if (mDataSetObserver != null) newCursor.registerDataSetObserver(mDataSetObserver);
            mRowIDColumn = newCursor.getColumnIndexOrThrow("_id");
            mDataValid = true;
            // notify the observers about the new cursor
            notifyDataSetChanged();
        } else {
            mRowIDColumn = -1;
            mDataValid = false;
            // notify the observers about the lack of a data set
            notifyDataSetInvalidated();
        }
        return oldCursor;