android.support.v4.widget
Class CursorAdapter

java.lang.Object
  extended by BaseAdapter
      extended by android.support.v4.widget.CursorAdapter
Direct Known Subclasses:
ResourceCursorAdapter

public abstract class CursorAdapter
extends BaseAdapter

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.


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 android.app.LoaderManager with a android.content.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  Context mContext
          This field should be made private, so it is hidden from the SDK.
protected  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  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  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.
 
Constructor Summary
CursorAdapter(Context context, 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 android.app.LoaderManager with a android.content.CursorLoader.
CursorAdapter(Context context, Cursor c, boolean autoRequery)
          Constructor that allows control over auto-requery.
CursorAdapter(Context context, Cursor c, int flags)
          Recommended constructor.
 
Method Summary
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.
 java.lang.CharSequence convertToString(Cursor cursor)
          Converts the cursor into a CharSequence.
 int getCount()
           
 Cursor getCursor()
          Returns the cursor.
 View getDropDownView(int position, View convertView, ViewGroup parent)
           
 Filter getFilter()
           
 FilterQueryProvider getFilterQueryProvider()
          Returns the query filter provider used for filtering.
 java.lang.Object getItem(int position)
           
 long getItemId(int position)
           
 View getView(int position, View convertView, ViewGroup parent)
           
 boolean hasStableIds()
           
protected  void init(Context context, Cursor c, boolean autoRequery)
          Deprecated. Don't use this, use the normal constructor. This will be removed in the future.
 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.
protected  void onContentChanged()
          Called when the ContentObserver on the cursor receives a change notification.
 Cursor runQueryOnBackgroundThread(java.lang.CharSequence constraint)
          Runs a query with the specified constraint.
 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.
 
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 Cursor mCursor
This field should be made private, so it is hidden from the SDK.


mContext

protected 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 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 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 android.app.LoaderManager with a android.content.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 android.content.CursorLoader.

See Also:
Constant Field Values
Constructor Detail

CursorAdapter

@Deprecated
public CursorAdapter(Context context,
                                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 android.app.LoaderManager with a android.content.CursorLoader.

Constructor that always enables auto-requery.

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

CursorAdapter

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(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(Context context,
                     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(Context context,
                               Cursor c,
                               boolean autoRequery)
Deprecated. Don't use this, use the normal constructor. This will be removed in the future.


getCursor

public Cursor getCursor()
Returns the cursor.

Returns:
the cursor.

getCount

public int getCount()
See Also:
android.widget.ListAdapter#getCount()

getItem

public java.lang.Object getItem(int position)
See Also:
android.widget.ListAdapter#getItem(int)

getItemId

public long getItemId(int position)
See Also:
android.widget.ListAdapter#getItemId(int)

hasStableIds

public boolean hasStableIds()

getView

public View getView(int position,
                    View convertView,
                    ViewGroup parent)
See Also:
android.widget.ListAdapter#getView(int, View, ViewGroup)

getDropDownView

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

newView

public abstract View newView(Context context,
                             Cursor cursor,
                             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 View newDropDownView(Context context,
                            Cursor cursor,
                            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(View view,
                              Context context,
                              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(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 Cursor swapCursor(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 java.lang.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 - the cursor to convert to a CharSequence
Returns:
a CharSequence representing the value

runQueryOnBackgroundThread

public Cursor runQueryOnBackgroundThread(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 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(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 Filter getFilter()

getFilterQueryProvider

public 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(FilterQueryProvider filterQueryProvider)
Sets the query filter provider used to filter the current Cursor. The provider's android.widget.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)