Added in API level 1

CursorAdapter

---

Kotlin |Java

abstract class CursorAdapter : BaseAdapter, Filterable, ThemedSpinnerAdapter

kotlin.Any
↳	android.widget.BaseAdapter
	↳	android.widget.CursorAdapter

Known Direct Subclasses ResourceCursorAdapter ResourceCursorAdapter An easy adapter that creates views defined in an XML file.

Known Indirect Subclasses SimpleCursorAdapter SimpleCursorAdapter An easy adapter to map columns from a cursor to TextViews or ImageViews defined in an XML file.

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 android.database.MergeCursor with this class will not work if the merged Cursors have overlapping values in their "_id" columns.

Summary

Constants
static Int	FLAG_AUTO_REQUERY If set the adapter will call requery() on the cursor whenever a content change notification is delivered.
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.

Public constructors
CursorAdapter(context: Context!, c: Cursor!) Constructor that always enables auto-requery.
CursorAdapter(context: Context!, c: Cursor!, autoRequery: Boolean) Constructor that allows control over auto-requery.
CursorAdapter(context: Context!, c: Cursor!, flags: Int) Recommended constructor.

Public methods
abstract Unit	bindView(view: View!, context: Context!, cursor: Cursor!) Bind an existing view to the data pointed to by cursor
open Unit	changeCursor(cursor: Cursor!) Change the underlying cursor to a new cursor.
open CharSequence!	convertToString(cursor: Cursor!) Converts the cursor into a CharSequence.
open Int	getCount()
open Cursor!	getCursor() Returns the cursor.
open View!	getDropDownView(position: Int, convertView: View!, parent: ViewGroup!)
open Resources.Theme?	getDropDownViewTheme()
open Filter!	getFilter()
open FilterQueryProvider!	getFilterQueryProvider() Returns the query filter provider used for filtering.
open Any!	getItem(position: Int)
open Long	getItemId(position: Int)
open View!	getView(position: Int, convertView: View!, parent: ViewGroup!)
open Boolean	hasStableIds()
open View!	newDropDownView(context: Context!, cursor: Cursor!, parent: ViewGroup!) Makes a new drop down view to hold the data pointed to by cursor.
abstract View!	newView(context: Context!, cursor: Cursor!, parent: ViewGroup!) Makes a new view to hold the data pointed to by cursor.
open Cursor!	runQueryOnBackgroundThread(constraint: CharSequence!) Runs a query with the specified constraint.
open Unit	setDropDownViewTheme(theme: Resources.Theme?) Sets the Resources.Theme against which drop-down views are inflated.
open Unit	setFilterQueryProvider(filterQueryProvider: FilterQueryProvider!) Sets the query filter provider used to filter the current Cursor.
open Cursor!	swapCursor(newCursor: Cursor!) Swap in a new Cursor, returning the old Cursor.

Protected methods
open Unit	init(context: Context!, c: Cursor!, autoRequery: Boolean)
open Unit	onContentChanged() Called when the ContentObserver on the cursor receives a change notification.

Inherited functions

From class BaseAdapter Boolean areAllItemsEnabled() Array<CharSequence!>? getAutofillOptions() Int getItemViewType(position: Int) Int getViewTypeCount() Boolean isEmpty() Boolean isEnabled(position: Int) Unit notifyDataSetChanged() Notifies the attached observers that the underlying data has been changed and any View reflecting the data set should refresh itself. Unit notifyDataSetInvalidated() Notifies the attached observers that the underlying data is no longer valid or available. Once invoked this adapter is no longer valid and should not report further data set changes. Unit registerDataSetObserver(observer: DataSetObserver!) Unit setAutofillOptions(vararg options: CharSequence!) Sets the value returned by getAutofillOptions() Unit unregisterDataSetObserver(observer: DataSetObserver!)

Constants

FLAG_AUTO_REQUERY

Added in API level 11
Deprecated in API level 15

static val FLAG_AUTO_REQUERY: Int

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.

Value: 1

FLAG_REGISTER_CONTENT_OBSERVER

Added in API level 11

static val FLAG_REGISTER_CONTENT_OBSERVER: Int

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.

Value: 2

Public constructors

CursorAdapter

Added in API level 1

CursorAdapter(
    context: Context!, 
    c: Cursor!)

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

CursorAdapter

Added in API level 1

CursorAdapter(
    context: Context!, 
    c: Cursor!, 
    autoRequery: Boolean)

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

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

CursorAdapter

Added in API level 11

CursorAdapter(
    context: Context!, 
    c: Cursor!, 
    flags: Int)

Recommended constructor.

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

bindView

Added in API level 1

abstract fun bindView(
    view: View!, 
    context: Context!, 
    cursor: Cursor!
): Unit

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 API level 1

open fun changeCursor(cursor: Cursor!): Unit

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 API level 1

open fun convertToString(cursor: Cursor!): CharSequence!

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

Return
CharSequence!	a CharSequence representing the value

getCount

Added in API level 1

open fun getCount(): Int

Return
Int	Count of items.

See Also

• android.widget.ListAdapter#getCount()

getCursor

Added in API level 1

open fun getCursor(): Cursor!

Returns the cursor.

Return
Cursor!	the cursor.

getDropDownView

Added in API level 1

open fun getDropDownView(
    position: Int, 
    convertView: View!, 
    parent: ViewGroup!
): View!

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

Return
View!	a android.view.View corresponding to the data at the specified position.

getDropDownViewTheme

Added in API level 23

open fun getDropDownViewTheme(): Resources.Theme?

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

getFilter

Added in API level 1

open fun getFilter(): Filter!

Return
Filter!	a filter used to constrain data

getFilterQueryProvider

Added in API level 1

open fun getFilterQueryProvider(): FilterQueryProvider!

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

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

See Also

• #setFilterQueryProvider(android.widget.FilterQueryProvider)
• #runQueryOnBackgroundThread(CharSequence)

getItem

Added in API level 1

open fun getItem(position: Int): Any!

Parameters
position	Int: Position of the item whose data we want within the adapter's data set.

Return
Any!	The data at the specified position.

See Also

• android.widget.ListAdapter#getItem(int)

getItemId

Added in API level 1

open fun getItemId(position: Int): Long

Parameters
position	Int: The position of the item within the adapter's data set whose row id we want.

Return
Long	The id of the item at the specified position.

See Also

• android.widget.ListAdapter#getItemId(int)

getView

Added in API level 1

open fun getView(
    position: Int, 
    convertView: View!, 
    parent: ViewGroup!
): View!

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

Return
View!	A View corresponding to the data at the specified position.

See Also

• android.widget.ListAdapter#getView(int, View, ViewGroup)

hasStableIds

Added in API level 1

open fun hasStableIds(): Boolean

Return
Boolean	True if the same id always refers to the same object.

newDropDownView

Added in API level 1

open fun newDropDownView(
    context: Context!, 
    cursor: Cursor!, 
    parent: ViewGroup!
): View!

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

Return
View!	the newly created view.

newView

Added in API level 1

abstract fun newView(
    context: Context!, 
    cursor: Cursor!, 
    parent: ViewGroup!
): View!

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

Return
View!	the newly created view.

runQueryOnBackgroundThread

Added in API level 1

open fun runQueryOnBackgroundThread(constraint: CharSequence!): Cursor!

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(android.database.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.
This method may take several seconds to complete, so it should only be called from a worker thread.

Parameters
constraint	CharSequence!: the constraint with which the query must be filtered

Return
Cursor!	a Cursor representing the results of the new query

See Also

• #getFilter()
• #getFilterQueryProvider()
• #setFilterQueryProvider(android.widget.FilterQueryProvider)

setDropDownViewTheme

Added in API level 23

open fun setDropDownViewTheme(theme: Resources.Theme?): Unit

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

See Also

• #newDropDownView(Context, Cursor, ViewGroup)

setFilterQueryProvider

Added in API level 1

open fun setFilterQueryProvider(filterQueryProvider: FilterQueryProvider!): Unit

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	FilterQueryProvider!: the filter query provider or null to remove it

See Also

• #getFilterQueryProvider()
• #runQueryOnBackgroundThread(CharSequence)

swapCursor

Added in API level 11

open fun swapCursor(newCursor: Cursor!): Cursor!

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

Parameters
newCursor	Cursor!: The new cursor to be used.

Return
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 API level 1
Deprecated in API level 15

protected open fun init(
    context: Context!, 
    c: Cursor!, 
    autoRequery: Boolean
): Unit

Deprecated: Don't use this, use the normal constructor. This will be removed in the future.

onContentChanged

Added in API level 3

protected open fun onContentChanged(): Unit

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

• android.database.ContentObserver#onChange(boolean)