Gradle dependencies
compile group: 'androidx.cursoradapter', name: 'cursoradapter', version: '1.0.0'
- groupId: androidx.cursoradapter
- artifactId: cursoradapter
- version: 1.0.0
Artifact androidx.cursoradapter:cursoradapter:1.0.0 it located at Google repository (https://maven.google.com/)
Androidx artifact mapping:
androidx.cursoradapter:cursoradapter com.android.support:cursoradapter
Androidx class mapping:
androidx.cursoradapter.widget.SimpleCursorAdapter android.support.v4.widget.SimpleCursorAdapter
Overview
Static library support version of the framework's .
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
Fields |
---|
protected int[] | mFrom A list of columns containing the data to bind to the UI. |
protected int[] | mTo A list of View ids representing the views to which the data must be bound. |
from CursorAdapter | FLAG_AUTO_REQUERY, FLAG_REGISTER_CONTENT_OBSERVER, mAutoRequery, mChangeObserver, mContext, mCursor, mCursorFilter, mDataSetObserver, mDataValid, mFilterQueryProvider, mRowIDColumn |
Constructors |
---|
public | SimpleCursorAdapter(Context context, int layout, Cursor c, java.lang.String from[], int[] to[])
Constructor the enables auto-requery. |
public | SimpleCursorAdapter(Context context, int layout, Cursor c, java.lang.String from[], int[] to[], int flags)
Standard constructor. |
Methods |
---|
public void | bindView(View view, Context context, Cursor cursor)
Binds all of the field names passed into the "to" parameter of the
constructor with their corresponding cursor columns as specified in the
"from" parameter. |
public void | changeCursorAndColumns(Cursor c, java.lang.String from[], int[] to[])
Change the cursor and change the column-to-view mappings at the same time. |
public java.lang.CharSequence | convertToString(Cursor cursor)
Returns a CharSequence representation of the specified Cursor as defined
by the current CursorToStringConverter. |
public SimpleCursorAdapter.CursorToStringConverter | getCursorToStringConverter()
Returns the converter used to convert the filtering Cursor
into a String. |
public int | getStringConversionColumn()
Return the index of the column used to get a String representation
of the Cursor. |
public SimpleCursorAdapter.ViewBinder | getViewBinder()
Returns the SimpleCursorAdapter.ViewBinder used to bind data to views. |
public void | setCursorToStringConverter(SimpleCursorAdapter.CursorToStringConverter cursorToStringConverter)
Sets the converter used to convert the filtering Cursor
into a String. |
public void | setStringConversionColumn(int stringConversionColumn)
Defines the index of the column in the Cursor used to get a String
representation of that Cursor. |
public void | setViewBinder(SimpleCursorAdapter.ViewBinder viewBinder)
Sets the binder used to bind data to views. |
public void | setViewImage(ImageView v, java.lang.String value)
Called by bindView() to set the image for an ImageView but only if
there is no existing ViewBinder or if the existing ViewBinder cannot
handle binding to an ImageView. |
public void | setViewText(TextView v, java.lang.String text)
Called by bindView() to set the text for a TextView but only if
there is no existing ViewBinder or if the existing ViewBinder cannot
handle binding to a TextView. |
public Cursor | swapCursor(Cursor newCursor)
Swap in a new Cursor, returning the old Cursor. |
from ResourceCursorAdapter | newDropDownView, newView, setDropDownViewResource, setViewResource |
from CursorAdapter | changeCursor, getCount, getCursor, getDropDownView, getFilter, getFilterQueryProvider, getItem, getItemId, getView, hasStableIds, init, onContentChanged, runQueryOnBackgroundThread, setFilterQueryProvider |
from java.lang.Object | clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Fields
A list of columns containing the data to bind to the UI.
This field should be made private, so it is hidden from the SDK.
A list of View ids representing the views to which the data must be bound.
This field should be made private, so it is hidden from the SDK.
Constructors
public
SimpleCursorAdapter(Context context, int layout, Cursor c, java.lang.String from[], int[] to[])
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 .
Constructor the enables auto-requery.
public
SimpleCursorAdapter(Context context, int layout, Cursor c, java.lang.String from[], int[] to[], int flags)
Standard constructor.
Parameters:
context: The context where the ListView associated with this
SimpleListItemFactory is running
layout: resource identifier of a layout file that defines the views
for this list item. The layout file should include at least
those named views defined in "to"
c: The database cursor. Can be null if the cursor is not available yet.
from: A list of column names representing the data to bind to the UI. Can be null
if the cursor is not available yet.
to: The views that should display column in the "from" parameter.
These should all be TextViews. The first N views in this list
are given the values of the first N columns in the from
parameter. Can be null if the cursor is not available yet.
flags: Flags used to determine the behavior of the adapter,
as per CursorAdapter.CursorAdapter(Context, Cursor, int).
Methods
public void
bindView(View view, Context context, Cursor cursor)
Binds all of the field names passed into the "to" parameter of the
constructor with their corresponding cursor columns as specified in the
"from" parameter.
Binding occurs in two phases. First, if a
is available,
SimpleCursorAdapter.ViewBinder
is invoked. If the returned value is true, binding has occured. If the
returned value is false and the view to bind is a TextView,
SimpleCursorAdapter.setViewText(TextView, String) is invoked. If the returned value is
false and the view to bind is an ImageView,
SimpleCursorAdapter.setViewImage(ImageView, String) is invoked. If no appropriate
binding can be found, an java.lang.IllegalStateException
is thrown.
See also: , SimpleCursorAdapter.getViewBinder(), SimpleCursorAdapter.setViewBinder(SimpleCursorAdapter.ViewBinder), SimpleCursorAdapter.setViewImage(ImageView, String), SimpleCursorAdapter.setViewText(TextView, String)
Returns the SimpleCursorAdapter.ViewBinder used to bind data to views.
Returns:
a ViewBinder or null if the binder does not exist
See also: SimpleCursorAdapter, SimpleCursorAdapter.setViewBinder(SimpleCursorAdapter.ViewBinder)
Sets the binder used to bind data to views.
Parameters:
viewBinder: the binder used to bind data to views, can be null to
remove the existing binder
See also: SimpleCursorAdapter, SimpleCursorAdapter.getViewBinder()
public void
setViewImage(ImageView v, java.lang.String value)
Called by bindView() to set the image for an ImageView but only if
there is no existing ViewBinder or if the existing ViewBinder cannot
handle binding to an ImageView.
By default, the value will be treated as an image resource. If the
value cannot be used as an image resource, the value is used as an
image Uri.
Intended to be overridden by Adapters that need to filter strings
retrieved from the database.
Parameters:
v: ImageView to receive an image
value: the value retrieved from the cursor
public void
setViewText(TextView v, java.lang.String text)
Called by bindView() to set the text for a TextView but only if
there is no existing ViewBinder or if the existing ViewBinder cannot
handle binding to a TextView.
Intended to be overridden by Adapters that need to filter strings
retrieved from the database.
Parameters:
v: TextView to receive text
text: the text to be set for the TextView
public int
getStringConversionColumn()
Return the index of the column used to get a String representation
of the Cursor.
Returns:
a valid index in the current Cursor or -1
See also: , SimpleCursorAdapter.setStringConversionColumn(int), SimpleCursorAdapter.setCursorToStringConverter(SimpleCursorAdapter.CursorToStringConverter), SimpleCursorAdapter.getCursorToStringConverter()
public void
setStringConversionColumn(int stringConversionColumn)
Defines the index of the column in the Cursor used to get a String
representation of that Cursor. The column is used to convert the
Cursor to a String only when the current CursorToStringConverter
is null.
Parameters:
stringConversionColumn: a valid index in the current Cursor or -1 to use the default
conversion mechanism
See also: , SimpleCursorAdapter.getStringConversionColumn(), SimpleCursorAdapter.setCursorToStringConverter(SimpleCursorAdapter.CursorToStringConverter), SimpleCursorAdapter.getCursorToStringConverter()
Returns the converter used to convert the filtering Cursor
into a String.
Returns:
null if the converter does not exist or an instance of
See also: SimpleCursorAdapter.setCursorToStringConverter(SimpleCursorAdapter.CursorToStringConverter), SimpleCursorAdapter.getStringConversionColumn(), SimpleCursorAdapter.setStringConversionColumn(int)
Sets the converter used to convert the filtering Cursor
into a String.
Parameters:
cursorToStringConverter: the Cursor to String converter, or
null to remove the converter
See also: SimpleCursorAdapter.setCursorToStringConverter(SimpleCursorAdapter.CursorToStringConverter), SimpleCursorAdapter.getStringConversionColumn(), SimpleCursorAdapter.setStringConversionColumn(int)
public java.lang.CharSequence
convertToString(Cursor cursor)
Returns a CharSequence representation of the specified Cursor as defined
by the current CursorToStringConverter. If no CursorToStringConverter
has been set, the String conversion column is used instead. If the
conversion column is -1, the returned String is empty if the cursor
is null or Cursor.toString().
Parameters:
cursor: the Cursor to convert to a CharSequence
Returns:
a non-null CharSequence representing the cursor
public Cursor
swapCursor(Cursor newCursor)
Swap in a new Cursor, returning the old Cursor. Unlike
CursorAdapter.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 was not one.
If the given new Cursor is the same instance is the previously set
Cursor, null is also returned.
public void
changeCursorAndColumns(Cursor c, java.lang.String from[], int[] to[])
Change the cursor and change the column-to-view mappings at the same time.
Parameters:
c: The database cursor. Can be null if the cursor is not available yet.
from: A list of column names representing the data to bind to the UI. Can be null
if the cursor is not available yet.
to: The views that should display column in the "from" parameter.
These should all be TextViews. The first N views in this list
are given the values of the first N columns in the from
parameter. Can be null if the cursor is not available yet.
Source
/*
* Copyright 2018 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package androidx.cursoradapter.widget;
import static androidx.annotation.RestrictTo.Scope.LIBRARY_GROUP;
import android.content.Context;
import android.database.Cursor;
import android.net.Uri;
import android.view.View;
import android.widget.ImageView;
import android.widget.TextView;
import androidx.annotation.RestrictTo;
/**
* Static library support version of the framework's {@link android.widget.SimpleCursorAdapter}.
* 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.
*/
public class SimpleCursorAdapter extends ResourceCursorAdapter {
/**
* A list of columns containing the data to bind to the UI.
* This field should be made private, so it is hidden from the SDK.
* @hide
*/
@RestrictTo(LIBRARY_GROUP)
protected int[] mFrom;
/**
* A list of View ids representing the views to which the data must be bound.
* This field should be made private, so it is hidden from the SDK.
* @hide
*/
@RestrictTo(LIBRARY_GROUP)
protected int[] mTo;
private int mStringConversionColumn = -1;
private CursorToStringConverter mCursorToStringConverter;
private ViewBinder mViewBinder;
String[] mOriginalFrom;
/**
* Constructor the enables 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 {@link android.app.LoaderManager} with a {@link android.content.CursorLoader}.
*/
@Deprecated
public SimpleCursorAdapter(Context context, int layout, Cursor c, String[] from, int[] to) {
super(context, layout, c);
mTo = to;
mOriginalFrom = from;
findColumns(c, from);
}
/**
* Standard constructor.
*
* @param context The context where the ListView associated with this
* SimpleListItemFactory is running
* @param layout resource identifier of a layout file that defines the views
* for this list item. The layout file should include at least
* those named views defined in "to"
* @param c The database cursor. Can be null if the cursor is not available yet.
* @param from A list of column names representing the data to bind to the UI. Can be null
* if the cursor is not available yet.
* @param to The views that should display column in the "from" parameter.
* These should all be TextViews. The first N views in this list
* are given the values of the first N columns in the from
* parameter. Can be null if the cursor is not available yet.
* @param flags Flags used to determine the behavior of the adapter,
* as per {@link CursorAdapter#CursorAdapter(Context, Cursor, int)}.
*/
public SimpleCursorAdapter(Context context, int layout, Cursor c, String[] from,
int[] to, int flags) {
super(context, layout, c, flags);
mTo = to;
mOriginalFrom = from;
findColumns(c, from);
}
/**
* Binds all of the field names passed into the "to" parameter of the
* constructor with their corresponding cursor columns as specified in the
* "from" parameter.
*
* Binding occurs in two phases. First, if a
* {@link android.widget.SimpleCursorAdapter.ViewBinder} is available,
* {@link ViewBinder#setViewValue(android.view.View, android.database.Cursor, int)}
* is invoked. If the returned value is true, binding has occured. If the
* returned value is false and the view to bind is a TextView,
* {@link #setViewText(TextView, String)} is invoked. If the returned value is
* false and the view to bind is an ImageView,
* {@link #setViewImage(ImageView, String)} is invoked. If no appropriate
* binding can be found, an {@link IllegalStateException} is thrown.
*
* @throws IllegalStateException if binding cannot occur
*
* @see android.widget.CursorAdapter#bindView(View, Context, Cursor)
* @see #getViewBinder()
* @see #setViewBinder(ViewBinder)
* @see #setViewImage(ImageView, String)
* @see #setViewText(TextView, String)
*/
@Override
public void bindView(View view, Context context, Cursor cursor) {
final ViewBinder binder = mViewBinder;
final int count = mTo.length;
final int[] from = mFrom;
final int[] to = mTo;
for (int i = 0; i < count; i++) {
final View v = view.findViewById(to[i]);
if (v != null) {
boolean bound = false;
if (binder != null) {
bound = binder.setViewValue(v, cursor, from[i]);
}
if (!bound) {
String text = cursor.getString(from[i]);
if (text == null) {
text = "";
}
if (v instanceof TextView) {
setViewText((TextView) v, text);
} else if (v instanceof ImageView) {
setViewImage((ImageView) v, text);
} else {
throw new IllegalStateException(v.getClass().getName() + " is not a "
+ " view that can be bounds by this SimpleCursorAdapter");
}
}
}
}
}
/**
* Returns the {@link ViewBinder} used to bind data to views.
*
* @return a ViewBinder or null if the binder does not exist
*
* @see #bindView(android.view.View, android.content.Context, android.database.Cursor)
* @see #setViewBinder(ViewBinder)
*/
public ViewBinder getViewBinder() {
return mViewBinder;
}
/**
* Sets the binder used to bind data to views.
*
* @param viewBinder the binder used to bind data to views, can be null to
* remove the existing binder
*
* @see #bindView(android.view.View, android.content.Context, android.database.Cursor)
* @see #getViewBinder()
*/
public void setViewBinder(ViewBinder viewBinder) {
mViewBinder = viewBinder;
}
/**
* Called by bindView() to set the image for an ImageView but only if
* there is no existing ViewBinder or if the existing ViewBinder cannot
* handle binding to an ImageView.
*
* By default, the value will be treated as an image resource. If the
* value cannot be used as an image resource, the value is used as an
* image Uri.
*
* Intended to be overridden by Adapters that need to filter strings
* retrieved from the database.
*
* @param v ImageView to receive an image
* @param value the value retrieved from the cursor
*/
public void setViewImage(ImageView v, String value) {
try {
v.setImageResource(Integer.parseInt(value));
} catch (NumberFormatException nfe) {
v.setImageURI(Uri.parse(value));
}
}
/**
* Called by bindView() to set the text for a TextView but only if
* there is no existing ViewBinder or if the existing ViewBinder cannot
* handle binding to a TextView.
*
* Intended to be overridden by Adapters that need to filter strings
* retrieved from the database.
*
* @param v TextView to receive text
* @param text the text to be set for the TextView
*/
public void setViewText(TextView v, String text) {
v.setText(text);
}
/**
* Return the index of the column used to get a String representation
* of the Cursor.
*
* @return a valid index in the current Cursor or -1
*
* @see android.widget.CursorAdapter#convertToString(android.database.Cursor)
* @see #setStringConversionColumn(int)
* @see #setCursorToStringConverter(CursorToStringConverter)
* @see #getCursorToStringConverter()
*/
public int getStringConversionColumn() {
return mStringConversionColumn;
}
/**
* Defines the index of the column in the Cursor used to get a String
* representation of that Cursor. The column is used to convert the
* Cursor to a String only when the current CursorToStringConverter
* is null.
*
* @param stringConversionColumn a valid index in the current Cursor or -1 to use the default
* conversion mechanism
*
* @see android.widget.CursorAdapter#convertToString(android.database.Cursor)
* @see #getStringConversionColumn()
* @see #setCursorToStringConverter(CursorToStringConverter)
* @see #getCursorToStringConverter()
*/
public void setStringConversionColumn(int stringConversionColumn) {
mStringConversionColumn = stringConversionColumn;
}
/**
* Returns the converter used to convert the filtering Cursor
* into a String.
*
* @return null if the converter does not exist or an instance of
* {@link android.widget.SimpleCursorAdapter.CursorToStringConverter}
*
* @see #setCursorToStringConverter(CursorToStringConverter)
* @see #getStringConversionColumn()
* @see #setStringConversionColumn(int)
* @see android.widget.CursorAdapter#convertToString(android.database.Cursor)
*/
public CursorToStringConverter getCursorToStringConverter() {
return mCursorToStringConverter;
}
/**
* Sets the converter used to convert the filtering Cursor
* into a String.
*
* @param cursorToStringConverter the Cursor to String converter, or
* null to remove the converter
*
* @see #setCursorToStringConverter(CursorToStringConverter)
* @see #getStringConversionColumn()
* @see #setStringConversionColumn(int)
* @see android.widget.CursorAdapter#convertToString(android.database.Cursor)
*/
public void setCursorToStringConverter(CursorToStringConverter cursorToStringConverter) {
mCursorToStringConverter = cursorToStringConverter;
}
/**
* Returns a CharSequence representation of the specified Cursor as defined
* by the current CursorToStringConverter. If no CursorToStringConverter
* has been set, the String conversion column is used instead. If the
* conversion column is -1, the returned String is empty if the cursor
* is null or Cursor.toString().
*
* @param cursor the Cursor to convert to a CharSequence
*
* @return a non-null CharSequence representing the cursor
*/
@Override
public CharSequence convertToString(Cursor cursor) {
if (mCursorToStringConverter != null) {
return mCursorToStringConverter.convertToString(cursor);
} else if (mStringConversionColumn > -1) {
return cursor.getString(mStringConversionColumn);
}
return super.convertToString(cursor);
}
/**
* Create a map from an array of strings to an array of column-id integers in cursor c.
* If c is null, the array will be discarded.
*
* @param c the cursor to find the columns from
* @param from the Strings naming the columns of interest
*/
private void findColumns(Cursor c, String[] from) {
if (c != null) {
int i;
int count = from.length;
if (mFrom == null || mFrom.length != count) {
mFrom = new int[count];
}
for (i = 0; i < count; i++) {
mFrom[i] = c.getColumnIndexOrThrow(from[i]);
}
} else {
mFrom = null;
}
}
@Override
public Cursor swapCursor(Cursor c) {
// super.swapCursor() will notify observers before we have
// a valid mapping, make sure we have a mapping before this
// happens
findColumns(c, mOriginalFrom);
return super.swapCursor(c);
}
/**
* Change the cursor and change the column-to-view mappings at the same time.
*
* @param c The database cursor. Can be null if the cursor is not available yet.
* @param from A list of column names representing the data to bind to the UI. Can be null
* if the cursor is not available yet.
* @param to The views that should display column in the "from" parameter.
* These should all be TextViews. The first N views in this list
* are given the values of the first N columns in the from
* parameter. Can be null if the cursor is not available yet.
*/
public void changeCursorAndColumns(Cursor c, String[] from, int[] to) {
mOriginalFrom = from;
mTo = to;
// super.changeCursor() will notify observers before we have
// a valid mapping, make sure we have a mapping before this
// happens
findColumns(c, mOriginalFrom);
super.changeCursor(c);
}
/**
* This class can be used by external clients of SimpleCursorAdapter
* to bind values fom the Cursor to views.
*
* You should use this class to bind values from the Cursor to views
* that are not directly supported by SimpleCursorAdapter or to
* change the way binding occurs for views supported by
* SimpleCursorAdapter.
*
* @see SimpleCursorAdapter#bindView(View, Context, Cursor)
* @see SimpleCursorAdapter#setViewImage(ImageView, String)
* @see SimpleCursorAdapter#setViewText(TextView, String)
*/
public interface ViewBinder {
/**
* Binds the Cursor column defined by the specified index to the specified view.
*
* When binding is handled by this ViewBinder, this method must return true.
* If this method returns false, SimpleCursorAdapter will attempts to handle
* the binding on its own.
*
* @param view the view to bind the data to
* @param cursor the cursor to get the data from
* @param columnIndex the column at which the data can be found in the cursor
*
* @return true if the data was bound to the view, false otherwise
*/
boolean setViewValue(View view, Cursor cursor, int columnIndex);
}
/**
* This class can be used by external clients of SimpleCursorAdapter
* to define how the Cursor should be converted to a String.
*
* @see android.widget.CursorAdapter#convertToString(android.database.Cursor)
*/
public interface CursorToStringConverter {
/**
* Returns a CharSequence representing the specified Cursor.
*
* @param cursor the cursor for which a CharSequence representation
* is requested
*
* @return a non-null CharSequence representing the cursor
*/
CharSequence convertToString(Cursor cursor);
}
}