Android APIs
public abstract class

CursorAdapter

extends BaseAdapter
implements Filterable ThemedSpinnerAdapter
java.lang.Object
   ↳ android.widget.BaseAdapter
     ↳ android.widget.CursorAdapter
Known Direct Subclasses
Known Indirect Subclasses

Class Overview

Adapter that exposes data from a Cursor to a ListView widget.

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

Summary

Constants
int FLAG_AUTO_REQUERY This constant was deprecated in API level 11. 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 LoaderManager with a CursorLoader.
int FLAG_REGISTER_CONTENT_OBSERVER If set the adapter will register a content observer on the cursor and will call onContentChanged() when a notification comes in.
[Expand]
Inherited Constants
From interface android.widget.Adapter
Public Constructors
CursorAdapter(Context context, Cursor c)
This constructor was deprecated in API level 11. 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 LoaderManager with a CursorLoader.
CursorAdapter(Context context, Cursor c, boolean autoRequery)
Constructor that allows control over auto-requery.
CursorAdapter(Context context, Cursor c, int flags)
Recommended constructor.
Public Methods
abstract void bindView(View view, Context context, Cursor cursor)
Bind an existing view to the data pointed to by cursor
void changeCursor(Cursor cursor)
Change the underlying cursor to a new cursor.
CharSequence convertToString(Cursor cursor)

Converts the cursor into a CharSequence.

int getCount()
How many items are in the data set represented by this Adapter.
Cursor getCursor()
Returns the cursor.
View getDropDownView(int position, View convertView, ViewGroup parent)
Gets a View that displays in the drop down popup the data at the specified position in the data set.
Resources.Theme getDropDownViewTheme()
Returns the value previously set by a call to setDropDownViewTheme(Theme).
Filter getFilter()

Returns a filter that can be used to constrain data with a filtering pattern.

FilterQueryProvider getFilterQueryProvider()
Returns the query filter provider used for filtering.
Object getItem(int position)
Get the data item associated with the specified position in the data set.
long getItemId(int position)
Get the row id associated with the specified position in the list.
View getView(int position, View convertView, ViewGroup parent)
Get a View that displays the data at the specified position in the data set.
boolean hasStableIds()
Indicates whether the item ids are stable across changes to the underlying data.
View newDropDownView(Context context, Cursor cursor, ViewGroup parent)
Makes a new drop down view to hold the data pointed to by cursor.
abstract View newView(Context context, Cursor cursor, ViewGroup parent)
Makes a new view to hold the data pointed to by cursor.
Cursor runQueryOnBackgroundThread(CharSequence constraint)
Runs a query with the specified constraint.
void setDropDownViewTheme(Resources.Theme theme)
Sets the Resources.Theme against which drop-down views are inflated.
void setFilterQueryProvider(FilterQueryProvider filterQueryProvider)
Sets the query filter provider used to filter the current Cursor.
Cursor swapCursor(Cursor newCursor)
Swap in a new Cursor, returning the old Cursor.
Protected Methods
void init(Context context, Cursor c, boolean autoRequery)
This method was deprecated in API level 11. Don't use this, use the normal constructor. This will be removed in the future.
void onContentChanged()
Called when the ContentObserver on the cursor receives a change notification.
[Expand]
Inherited Methods
From class android.widget.BaseAdapter
From class java.lang.Object
From interface android.widget.ListAdapter
From interface android.widget.SpinnerAdapter
From interface android.widget.Filterable
From interface android.widget.ThemedSpinnerAdapter
From interface android.widget.Adapter

Constants

public static final int FLAG_AUTO_REQUERY

Added in API level 11

This constant was deprecated in API level 11.
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 LoaderManager with a CursorLoader.

If set the adapter will call requery() on the cursor whenever a content change notification is delivered. Implies FLAG_REGISTER_CONTENT_OBSERVER.

Constant Value: 1 (0x00000001)

public static final int FLAG_REGISTER_CONTENT_OBSERVER

Added in API level 11

If set the adapter will register a content observer on the cursor and will call 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 CursorLoader.

Constant Value: 2 (0x00000002)

Public Constructors

public CursorAdapter (Context context, Cursor c)

Added in API level 1

This constructor was deprecated in API level 11.
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 LoaderManager with a CursorLoader.

Constructor that always enables auto-requery.

Parameters
context Context: The context
c Cursor: The cursor from which to get the data.

public CursorAdapter (Context context, Cursor c, boolean autoRequery)

Added in API level 1

Constructor that allows control over auto-requery. It is recommended you not use this, but instead CursorAdapter(Context, Cursor, int). When using this constructor, FLAG_REGISTER_CONTENT_OBSERVER will always be set.

Parameters
context Context: The context
c Cursor: The cursor from which to get the data.
autoRequery boolean: 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.

public CursorAdapter (Context context, Cursor c, int flags)

Added in API level 11

Recommended constructor.

Parameters
context Context: The context
c Cursor: The cursor from which to get the data.
flags int: Flags used to determine the behavior of the adapter; may be any combination of FLAG_AUTO_REQUERY and FLAG_REGISTER_CONTENT_OBSERVER.

Public Methods

public abstract void bindView (View view, Context context, Cursor cursor)

Added in API level 1

Bind an existing view to the data pointed to by cursor

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

public void changeCursor (Cursor cursor)

Added in API level 1

Change the underlying cursor to a new cursor. If there is an existing cursor it will be closed.

Parameters
cursor Cursor: The new cursor to be used

public CharSequence convertToString (Cursor cursor)

Added in API level 1

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.

Parameters
cursor Cursor: the cursor to convert to a CharSequence
Returns
CharSequence a CharSequence representing the value

public int getCount ()

Added in API level 1

How many items are in the data set represented by this Adapter.

Returns
int Count of items.

See also:

public Cursor getCursor ()

Added in API level 1

Returns the cursor.

Returns
Cursor the cursor.

public View getDropDownView (int position, View convertView, ViewGroup parent)

Added in API level 1

Gets a View that displays in the drop down popup the data at the specified position in the data set.

Parameters
position int: index of the item whose view we want.
convertView View: the old view to reuse, if possible. Note: You should check that this view is non-null and of an appropriate type before using. If it is not possible to convert this view to display the correct data, this method can create a new view.
parent ViewGroup: the parent that this view will eventually be attached to
Returns
View a View corresponding to the data at the specified position.

public Resources.Theme getDropDownViewTheme ()

Added in API level 23

Returns the value previously set by a call to setDropDownViewTheme(Theme).

Returns
Resources.Theme the Resources.Theme against which drop-down views are inflated, or null if one has not been explicitly set

public Filter getFilter ()

Added in API level 1

Returns a filter that can be used to constrain data with a filtering pattern.

This method is usually implemented by Adapter classes.

Returns
Filter a filter used to constrain data

public FilterQueryProvider getFilterQueryProvider ()

Added in API level 1

Returns the query filter provider used for filtering. When the provider is null, no filtering occurs.

Returns
FilterQueryProvider the current filter query provider or null if it does not exist

public Object getItem (int position)

Added in API level 1

Get the data item associated with the specified position in the data set.

Parameters
position int: Position of the item whose data we want within the adapter's data set.
Returns
Object The data at the specified position.

See also:

public long getItemId (int position)

Added in API level 1

Get the row id associated with the specified position in the list.

Parameters
position int: The position of the item within the adapter's data set whose row id we want.
Returns
long The id of the item at the specified position.

See also:

public View getView (int position, View convertView, ViewGroup parent)

Added in API level 1

Get a View that displays the data at the specified position in the data set. You can either create a View manually or inflate it from an XML layout file. When the View is inflated, the parent View (GridView, ListView...) will apply default layout parameters unless you use inflate(int, android.view.ViewGroup, boolean) to specify a root view and to prevent attachment to the root.

Parameters
position int: The position of the item within the adapter's data set of the item whose view we want.
convertView View: The old view to reuse, if possible. Note: You should check that this view is non-null and of an appropriate type before using. If it is not possible to convert this view to display the correct data, this method can create a new view. Heterogeneous lists can specify their number of view types, so that this View is always of the right type (see getViewTypeCount() and getItemViewType(int)).
parent ViewGroup: The parent that this view will eventually be attached to
Returns
View A View corresponding to the data at the specified position.

public boolean hasStableIds ()

Added in API level 1

Indicates whether the item ids are stable across changes to the underlying data.

Returns
boolean True if the same id always refers to the same object.

public View newDropDownView (Context context, Cursor cursor, ViewGroup parent)

Added in API level 1

Makes a new drop down view to hold the data pointed to by cursor.

Parameters
context Context: Interface to application's global information
cursor Cursor: The cursor from which to get the data. The cursor is already moved to the correct position.
parent ViewGroup: The parent to which the new view is attached to
Returns
View the newly created view.

public abstract View newView (Context context, Cursor cursor, ViewGroup parent)

Added in API level 1

Makes a new view to hold the data pointed to by cursor.

Parameters
context Context: Interface to application's global information
cursor Cursor: The cursor from which to get the data. The cursor is already moved to the correct position.
parent ViewGroup: The parent to which the new view is attached to
Returns
View the newly created view.

public Cursor runQueryOnBackgroundThread (CharSequence constraint)

Added in API level 1

Runs a query with the specified constraint. This query is requested by the filter attached to this adapter. The query is provided by a FilterQueryProvider. If no provider is specified, the current cursor is not filtered and returned. After this method returns the resulting cursor is passed to 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.

Parameters
constraint CharSequence: the constraint with which the query must be filtered
Returns
Cursor a Cursor representing the results of the new query

public void setDropDownViewTheme (Resources.Theme theme)

Added in API level 23

Sets the Resources.Theme against which drop-down views are inflated.

By default, drop-down views are inflated against the theme of the Context passed to the adapter's constructor.

Parameters
theme Resources.Theme: the theme against which to inflate drop-down views or null to use the theme from the adapter's context

public void setFilterQueryProvider (FilterQueryProvider filterQueryProvider)

Added in API level 1

Sets the query filter provider used to filter the current Cursor. The provider's runQuery(CharSequence) method is invoked when filtering is requested by a client of this adapter.

Parameters
filterQueryProvider FilterQueryProvider: the filter query provider or null to remove it

public Cursor swapCursor (Cursor newCursor)

Added in API level 11

Swap in a new Cursor, returning the old Cursor. Unlike changeCursor(Cursor), the returned old Cursor is not closed.

Parameters
newCursor Cursor: The new cursor to be used.
Returns
Cursor 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.

Protected Methods

protected void init (Context context, Cursor c, boolean autoRequery)

Added in API level 1

This method was deprecated in API level 11.
Don't use this, use the normal constructor. This will be removed in the future.

Parameters
context Context
c Cursor
autoRequery boolean

protected void onContentChanged ()

Added in API level 3

Called when the ContentObserver on the cursor receives a change notification. The default implementation provides the auto-requery logic, but may be overridden by sub classes.

See also: