Platform Android Studio Google Play Jetpack Kotlin Docs News
Overview Guides Reference Samples Design & Quality
Register now for Android Dev Summit 2019!

CursorAdapter

abstract class CursorAdapter : BaseAdapter, Filterable, CursorFilterClient
kotlin.Any
   ↳ android.widget.BaseAdapter
   ↳ androidx.cursoradapter.widget.CursorAdapter

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 Int

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

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

Public constructors
<init>(context: Context!, c: Cursor!)

Constructor that always enables auto-requery.
<init>(context: Context!, c: Cursor!, autoRequery: Boolean)

Constructor that allows control over auto-requery.
<init>(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!

Converts the cursor into a CharSequence.
open Int

open Cursor!

Returns the cursor.
open View!
getDropDownView(position: Int, convertView: View!, parent: ViewGroup!)
open Filter!

open FilterQueryProvider!

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

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!

Runs a query with the specified constraint.
open Unit

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

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

Constants

FLAG_AUTO_REQUERY

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: 0x01

FLAG_REGISTER_CONTENT_OBSERVER

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: 0x02

Public constructors

<init>

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

<init>

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

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

<init>

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

Recommended constructor.

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

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 View!: Interface to application's global information
cursor View!: The cursor from which to get the data. The cursor is already moved to the correct position.

changeCursor

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

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

open fun getCount(): Int

getCursor

open fun getCursor(): Cursor!

Returns the cursor.

Return
Cursor!: the cursor.

getDropDownView

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

getFilter

open fun getFilter(): Filter!

getFilterQueryProvider

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

getItem

open fun getItem(position: Int): Any!

getItemId

open fun getItemId(position: Int): Long

getView

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

hasStableIds

open fun hasStableIds(): Boolean

newDropDownView

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 Context!: The cursor from which to get the data. The cursor is already moved to the correct position.
parent Context!: The parent to which the new view is attached to
Return
View!: the newly created view.

newView

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 Context!: The cursor from which to get the data. The cursor is already moved to the correct position.
parent Context!: The parent to which the new view is attached to
Return
View!: the newly created view.

runQueryOnBackgroundThread

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(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
Return
Cursor!: a Cursor representing the results of the new query

setFilterQueryProvider

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

swapCursor

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

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

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

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.