CursorAdapter

public abstract class CursorAdapter extends BaseAdapter implements Filterable

Known direct subclasses
ResourceCursorAdapter

Static library support version of the framework's android.widget.ResourceCursorAdapter.

Known indirect subclasses
SimpleCursorAdapter

Static library support version of the framework's android.widget.SimpleCursorAdapter.


Static library support version of the framework's android.widget.CursorAdapter. Used to write apps that run on platforms prior to Android 3.0. When running on Android 3.0 or above, this implementation is still used; it does not try to switch to the framework's implementation. See the framework SDK documentation for a class overview.

Summary

Constants

static final int

This field is 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.

static final int

If set the adapter will register a content observer on the cursor and will call onContentChanged when a notification comes in.

Public constructors

This method is 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.

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

Change the underlying cursor to a new cursor.

CharSequence

Converts the cursor into a CharSequence.

int
Cursor

Returns the cursor.

View
getDropDownView(int position, View convertView, ViewGroup parent)
Filter
FilterQueryProvider

Returns the query filter provider used for filtering.

Object
getItem(int position)
long
getItemId(int position)
View
getView(int position, View convertView, ViewGroup parent)
boolean
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

Runs a query with the specified constraint.

void

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 is deprecated.

Don't use this, use the normal constructor.

void

Called when the ContentObserver on the cursor receives a change notification.

Inherited Constants

From android.widget.Adapter
static final int
static final int
NO_SELECTION = -2147483648

Inherited methods

From android.widget.BaseAdapter
boolean
CharSequence[]
int
getItemViewType(int position)
int
boolean
boolean
isEnabled(int position)
void
void
void
void
setAutofillOptions(CharSequence[] options)
void

Constants

FLAG_AUTO_REQUERY

Added in 1.0.0
Deprecated in 1.0.0
public static final int FLAG_AUTO_REQUERY = 1

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

FLAG_REGISTER_CONTENT_OBSERVER

Added in 1.0.0
public static final int FLAG_REGISTER_CONTENT_OBSERVER = 2

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 android.content.CursorLoader.

Public constructors

CursorAdapter

Added in 1.0.0
Deprecated in 1.0.0
public CursorAdapter(Context context, Cursor c)

Constructor that always enables auto-requery.

Parameters
Context context

The context

Cursor c

The cursor from which to get the data.

CursorAdapter

Added in 1.0.0
public CursorAdapter(Context context, Cursor c, boolean autoRequery)

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

Parameters
Context context

The context

Cursor c

The cursor from which to get the data.

boolean 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.

CursorAdapter

Added in 1.0.0
public CursorAdapter(Context context, Cursor c, int flags)

Recommended constructor.

Parameters
Context context

The context

Cursor c

The cursor from which to get the data.

int flags

Flags used to determine the behavior of the adapter; may be any combination of FLAG_AUTO_REQUERY and FLAG_REGISTER_CONTENT_OBSERVER.

Public methods

bindView

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

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.

changeCursor

Added in 1.0.0
public void changeCursor(Cursor cursor)

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

convertToString

Added in 1.0.0
public CharSequence convertToString(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.

Parameters
Cursor cursor

the cursor to convert to a CharSequence

Returns
CharSequence

a CharSequence representing the value

getCount

Added in 1.0.0
public int getCount()
See also
getCount

getCursor

Added in 1.0.0
public Cursor getCursor()

Returns the cursor.

Returns
Cursor

the cursor.

getDropDownView

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

getFilter

Added in 1.0.0
public Filter getFilter()

getFilterQueryProvider

Added in 1.0.0
public FilterQueryProvider getFilterQueryProvider()

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

getItem

Added in 1.0.0
public Object getItem(int position)
See also
getItem

getItemId

Added in 1.0.0
public long getItemId(int position)
See also
getItemId

getView

Added in 1.0.0
public View getView(int position, View convertView, ViewGroup parent)
See also
getView

hasStableIds

public boolean hasStableIds()

newDropDownView

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

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.

ViewGroup parent

The parent to which the new view is attached to

Returns
View

the newly created view.

newView

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

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.

ViewGroup parent

The parent to which the new view is attached to

Returns
View

the newly created view.

runQueryOnBackgroundThread

Added in 1.0.0
public Cursor runQueryOnBackgroundThread(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 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 changeCursor 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
CharSequence constraint

the constraint with which the query must be filtered

Returns
Cursor

a Cursor representing the results of the new query

setFilterQueryProvider

Added in 1.0.0
public void setFilterQueryProvider(FilterQueryProvider filterQueryProvider)

Sets the query filter provider used to filter the current Cursor. The provider's runQuery 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

swapCursor

Added in 1.0.0
public Cursor swapCursor(Cursor newCursor)

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

Parameters
Cursor newCursor

The new cursor to be used.

Returns
Cursor

Returns the previously set Cursor, or null if there was not one. If the given new Cursor is the same instance is the previously set Cursor, null is also returned.

Protected methods

init

Added in 1.0.0
Deprecated in 1.0.0
protected void init(Context context, Cursor c, boolean autoRequery)

onContentChanged

Added in 1.0.0
protected void onContentChanged()

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
onChange