android.support.v4.widget
Class CursorAdapter

java.lang.Object
  android.widget.BaseAdapter
      android.support.v4.widget.CursorAdapter

All Implemented Interfaces:

android.widget.Adapter, android.widget.Filterable, android.widget.ListAdapter, android.widget.SpinnerAdapter

Direct Known Subclasses:

ResourceCursorAdapter

public abstract class CursorAdapter
extends android.widget.BaseAdapter
implements android.widget.Filterable

Static library support version of the framework's 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.

Field Summary

static int	FLAG_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 LoaderManager with a CursorLoader.
static 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.
protected boolean	mAutoRequery This field should be made private, so it is hidden from the SDK.
protected android.support.v4.widget.CursorAdapter.ChangeObserver	mChangeObserver This field should be made private, so it is hidden from the SDK.
protected android.content.Context	mContext This field should be made private, so it is hidden from the SDK.
protected android.database.Cursor	mCursor This field should be made private, so it is hidden from the SDK.
protected android.support.v4.widget.CursorFilter	mCursorFilter This field should be made private, so it is hidden from the SDK.
protected android.database.DataSetObserver	mDataSetObserver This field should be made private, so it is hidden from the SDK.
protected boolean	mDataValid This field should be made private, so it is hidden from the SDK.
protected android.widget.FilterQueryProvider	mFilterQueryProvider This field should be made private, so it is hidden from the SDK.
protected int	mRowIDColumn This field should be made private, so it is hidden from the SDK.

Fields inherited from interface android.widget.Adapter

IGNORE_ITEM_VIEW_TYPE, NO_SELECTION

Constructor Summary

CursorAdapter(android.content.Context context, android.database.Cursor c)
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 LoaderManager with a CursorLoader.

CursorAdapter(android.content.Context context, android.database.Cursor c, boolean autoRequery)
Constructor that allows control over auto-requery.

CursorAdapter(android.content.Context context, android.database.Cursor c, int flags)
Recommended constructor.

Method Summary

abstract void	bindView(android.view.View view, android.content.Context context, android.database.Cursor cursor) Bind an existing view to the data pointed to by cursor
void	changeCursor(android.database.Cursor cursor) Change the underlying cursor to a new cursor.
CharSequence	convertToString(android.database.Cursor cursor) Converts the cursor into a CharSequence.
int	getCount()
android.database.Cursor	getCursor() Returns the cursor.
android.view.View	getDropDownView(int position, android.view.View convertView, android.view.ViewGroup parent)
android.widget.Filter	getFilter()
android.widget.FilterQueryProvider	getFilterQueryProvider() Returns the query filter provider used for filtering.
Object	getItem(int position)
long	getItemId(int position)
android.view.View	getView(int position, android.view.View convertView, android.view.ViewGroup parent)
boolean	hasStableIds()
protected void	init(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.
android.view.View	newDropDownView(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.
abstract android.view.View	newView(android.content.Context context, android.database.Cursor cursor, android.view.ViewGroup parent) Makes a new view to hold the data pointed to by cursor.
protected void	onContentChanged() Called when the ContentObserver on the cursor receives a change notification.
android.database.Cursor	runQueryOnBackgroundThread(CharSequence constraint) Runs a query with the specified constraint.
void	setFilterQueryProvider(android.widget.FilterQueryProvider filterQueryProvider) Sets the query filter provider used to filter the current Cursor.
android.database.Cursor	swapCursor(android.database.Cursor newCursor) Swap in a new Cursor, returning the old Cursor.

Methods inherited from class android.widget.BaseAdapter

areAllItemsEnabled, getItemViewType, getViewTypeCount, isEmpty, isEnabled, notifyDataSetChanged, notifyDataSetInvalidated, registerDataSetObserver, unregisterDataSetObserver

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

mDataValid

protected boolean mDataValid

This field should be made private, so it is hidden from the SDK.

mAutoRequery

protected boolean mAutoRequery

This field should be made private, so it is hidden from the SDK.

mCursor

protected android.database.Cursor mCursor

This field should be made private, so it is hidden from the SDK.

mContext

protected android.content.Context mContext

This field should be made private, so it is hidden from the SDK.

mRowIDColumn

protected int mRowIDColumn

This field should be made private, so it is hidden from the SDK.

mChangeObserver

protected android.support.v4.widget.CursorAdapter.ChangeObserver mChangeObserver

This field should be made private, so it is hidden from the SDK.

mDataSetObserver

protected android.database.DataSetObserver mDataSetObserver

This field should be made private, so it is hidden from the SDK.

mCursorFilter

protected android.support.v4.widget.CursorFilter mCursorFilter

This field should be made private, so it is hidden from the SDK.

mFilterQueryProvider

protected android.widget.FilterQueryProvider mFilterQueryProvider

This field should be made private, so it is hidden from the SDK.

FLAG_AUTO_REQUERY

@Deprecated
public static final int FLAG_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 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.

See Also:

Constant Field Values

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

See Also:

Constant Field Values

Constructor Detail

CursorAdapter

@Deprecated
public CursorAdapter(android.content.Context context,
                                android.database.Cursor c)

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 LoaderManager with a CursorLoader.

Constructor that always enables auto-requery.

Parameters:

c - The cursor from which to get the data.

context - The context

CursorAdapter

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 CursorAdapter(Context, Cursor, int). When using this constructor, FLAG_REGISTER_CONTENT_OBSERVER will always be set.

Parameters:

c - The cursor from which to get the data.

context - The context

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

public CursorAdapter(android.content.Context context,
                     android.database.Cursor c,
                     int flags)

Recommended constructor.

Parameters:

c - The cursor from which to get the data.

context - The context

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

Method Detail

init

@Deprecated
protected void init(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.

getCursor

public android.database.Cursor getCursor()

Returns the cursor.

Returns:

the cursor.

getCount

public int getCount()

Specified by:

getCount in interface android.widget.Adapter

See Also:

Adapter.getCount()

getItem

public Object getItem(int position)

Specified by:

getItem in interface android.widget.Adapter

See Also:

Adapter.getItem(int)

getItemId

public long getItemId(int position)

Specified by:

getItemId in interface android.widget.Adapter

See Also:

Adapter.getItemId(int)

hasStableIds

public boolean hasStableIds()

Specified by:

hasStableIds in interface android.widget.Adapter

Overrides:

hasStableIds in class android.widget.BaseAdapter

getView

public android.view.View getView(int position,
                                 android.view.View convertView,
                                 android.view.ViewGroup parent)

Specified by:

getView in interface android.widget.Adapter

See Also:

Adapter.getView(int, View, ViewGroup)

getDropDownView

public android.view.View getDropDownView(int position,
                                         android.view.View convertView,
                                         android.view.ViewGroup parent)

Specified by:

getDropDownView in interface android.widget.SpinnerAdapter

Overrides:

getDropDownView in class android.widget.BaseAdapter

newView

public abstract android.view.View newView(android.content.Context context,
                                          android.database.Cursor cursor,
                                          android.view.ViewGroup parent)

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

Parameters:

context - Interface to application's global information

cursor - The cursor from which to get the data. The cursor is already moved to the correct position.

parent - The parent to which the new view is attached to

Returns:

the newly created view.

newDropDownView

public android.view.View newDropDownView(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.

Parameters:

context - Interface to application's global information

cursor - The cursor from which to get the data. The cursor is already moved to the correct position.

parent - The parent to which the new view is attached to

Returns:

the newly created view.

bindView

public abstract void bindView(android.view.View view,
                              android.content.Context context,
                              android.database.Cursor cursor)

Bind an existing view to the data pointed to by cursor

Parameters:

view - Existing view, returned earlier by newView

context - Interface to application's global information

cursor - The cursor from which to get the data. The cursor is already moved to the correct position.

changeCursor

public void changeCursor(android.database.Cursor cursor)

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

Parameters:

cursor - The new cursor to be used

swapCursor

public android.database.Cursor swapCursor(android.database.Cursor newCursor)

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

Parameters:

newCursor - The new cursor to be used.

Returns:

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.

convertToString

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

Parameters:

cursor - the cursor to convert to a CharSequence

Returns:

a CharSequence representing the value

runQueryOnBackgroundThread

public android.database.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 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 - the constraint with which the query must be filtered

Returns:

a Cursor representing the results of the new query

See Also:

getFilter(), getFilterQueryProvider(), setFilterQueryProvider(android.widget.FilterQueryProvider)

getFilter

public android.widget.Filter getFilter()

Specified by:

getFilter in interface android.widget.Filterable

getFilterQueryProvider

public android.widget.FilterQueryProvider getFilterQueryProvider()

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

Returns:

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

See Also:

setFilterQueryProvider(android.widget.FilterQueryProvider), runQueryOnBackgroundThread(CharSequence)

setFilterQueryProvider

public void setFilterQueryProvider(android.widget.FilterQueryProvider filterQueryProvider)

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

Parameters:

filterQueryProvider - the filter query provider or null to remove it

See Also:

getFilterQueryProvider(), runQueryOnBackgroundThread(CharSequence)

onContentChanged

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:

ContentObserver.onChange(boolean)