/*
|
* Copyright (C) 2006 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 android.widget;
|
|
import android.content.Context;
|
import android.database.Cursor;
|
import android.net.Uri;
|
import android.view.View;
|
|
/**
|
* An easy adapter to map columns from a cursor to TextViews or ImageViews
|
* defined in an XML file. You can specify which columns you want, which views
|
* you want to display the columns, and the XML file that defines the appearance
|
* of these views. Separate XML files for child and groups are possible.
|
*
|
* Binding occurs in two phases. First, if a
|
* {@link android.widget.SimpleCursorTreeAdapter.ViewBinder} is available,
|
* {@link ViewBinder#setViewValue(android.view.View, android.database.Cursor, int)}
|
* is invoked. If the returned value is true, binding has occurred. 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.
|
*/
|
public abstract class SimpleCursorTreeAdapter extends ResourceCursorTreeAdapter {
|
|
/** The name of the columns that contain the data to display for a group. */
|
private String[] mGroupFromNames;
|
|
/** The indices of columns that contain data to display for a group. */
|
private int[] mGroupFrom;
|
/**
|
* The View IDs that will display a group's data fetched from the
|
* corresponding column.
|
*/
|
private int[] mGroupTo;
|
|
/** The name of the columns that contain the data to display for a child. */
|
private String[] mChildFromNames;
|
|
/** The indices of columns that contain data to display for a child. */
|
private int[] mChildFrom;
|
/**
|
* The View IDs that will display a child's data fetched from the
|
* corresponding column.
|
*/
|
private int[] mChildTo;
|
|
/**
|
* View binder, if supplied
|
*/
|
private ViewBinder mViewBinder;
|
|
/**
|
* Constructor.
|
*
|
* @param context The context where the {@link ExpandableListView}
|
* associated with this {@link SimpleCursorTreeAdapter} is
|
* running
|
* @param cursor The database cursor
|
* @param collapsedGroupLayout The resource identifier of a layout file that
|
* defines the views for a collapsed group. The layout file
|
* should include at least those named views defined in groupTo.
|
* @param expandedGroupLayout The resource identifier of a layout file that
|
* defines the views for an expanded group. The layout file
|
* should include at least those named views defined in groupTo.
|
* @param groupFrom A list of column names that will be used to display the
|
* data for a group.
|
* @param groupTo The group views (from the group layouts) that should
|
* display column in the "from" parameter. These should all be
|
* TextViews or ImageViews. The first N views in this list are
|
* given the values of the first N columns in the from parameter.
|
* @param childLayout The resource identifier of a layout file that defines
|
* the views for a child (except the last). The layout file
|
* should include at least those named views defined in childTo.
|
* @param lastChildLayout The resource identifier of a layout file that
|
* defines the views for the last child within a group. The
|
* layout file should include at least those named views defined
|
* in childTo.
|
* @param childFrom A list of column names that will be used to display the
|
* data for a child.
|
* @param childTo The child views (from the child layouts) that should
|
* display column in the "from" parameter. These should all be
|
* TextViews or ImageViews. The first N views in this list are
|
* given the values of the first N columns in the from parameter.
|
*/
|
public SimpleCursorTreeAdapter(Context context, Cursor cursor, int collapsedGroupLayout,
|
int expandedGroupLayout, String[] groupFrom, int[] groupTo, int childLayout,
|
int lastChildLayout, String[] childFrom, int[] childTo) {
|
super(context, cursor, collapsedGroupLayout, expandedGroupLayout, childLayout,
|
lastChildLayout);
|
init(groupFrom, groupTo, childFrom, childTo);
|
}
|
|
/**
|
* Constructor.
|
*
|
* @param context The context where the {@link ExpandableListView}
|
* associated with this {@link SimpleCursorTreeAdapter} is
|
* running
|
* @param cursor The database cursor
|
* @param collapsedGroupLayout The resource identifier of a layout file that
|
* defines the views for a collapsed group. The layout file
|
* should include at least those named views defined in groupTo.
|
* @param expandedGroupLayout The resource identifier of a layout file that
|
* defines the views for an expanded group. The layout file
|
* should include at least those named views defined in groupTo.
|
* @param groupFrom A list of column names that will be used to display the
|
* data for a group.
|
* @param groupTo The group views (from the group layouts) that should
|
* display column in the "from" parameter. These should all be
|
* TextViews or ImageViews. The first N views in this list are
|
* given the values of the first N columns in the from parameter.
|
* @param childLayout The resource identifier of a layout file that defines
|
* the views for a child. The layout file
|
* should include at least those named views defined in childTo.
|
* @param childFrom A list of column names that will be used to display the
|
* data for a child.
|
* @param childTo The child views (from the child layouts) that should
|
* display column in the "from" parameter. These should all be
|
* TextViews or ImageViews. The first N views in this list are
|
* given the values of the first N columns in the from parameter.
|
*/
|
public SimpleCursorTreeAdapter(Context context, Cursor cursor, int collapsedGroupLayout,
|
int expandedGroupLayout, String[] groupFrom, int[] groupTo,
|
int childLayout, String[] childFrom, int[] childTo) {
|
super(context, cursor, collapsedGroupLayout, expandedGroupLayout, childLayout);
|
init(groupFrom, groupTo, childFrom, childTo);
|
}
|
|
/**
|
* Constructor.
|
*
|
* @param context The context where the {@link ExpandableListView}
|
* associated with this {@link SimpleCursorTreeAdapter} is
|
* running
|
* @param cursor The database cursor
|
* @param groupLayout The resource identifier of a layout file that defines
|
* the views for a group. The layout file should include at least
|
* those named views defined in groupTo.
|
* @param groupFrom A list of column names that will be used to display the
|
* data for a group.
|
* @param groupTo The group views (from the group layouts) that should
|
* display column in the "from" parameter. These should all be
|
* TextViews or ImageViews. The first N views in this list are
|
* given the values of the first N columns in the from parameter.
|
* @param childLayout The resource identifier of a layout file that defines
|
* the views for a child. The layout file should include at least
|
* those named views defined in childTo.
|
* @param childFrom A list of column names that will be used to display the
|
* data for a child.
|
* @param childTo The child views (from the child layouts) that should
|
* display column in the "from" parameter. These should all be
|
* TextViews or ImageViews. The first N views in this list are
|
* given the values of the first N columns in the from parameter.
|
*/
|
public SimpleCursorTreeAdapter(Context context, Cursor cursor, int groupLayout,
|
String[] groupFrom, int[] groupTo, int childLayout, String[] childFrom,
|
int[] childTo) {
|
super(context, cursor, groupLayout, childLayout);
|
init(groupFrom, groupTo, childFrom, childTo);
|
}
|
|
private void init(String[] groupFromNames, int[] groupTo, String[] childFromNames,
|
int[] childTo) {
|
|
mGroupFromNames = groupFromNames;
|
mGroupTo = groupTo;
|
|
mChildFromNames = childFromNames;
|
mChildTo = childTo;
|
}
|
|
/**
|
* Returns the {@link ViewBinder} used to bind data to views.
|
*
|
* @return a ViewBinder or null if the binder does not exist
|
*
|
* @see #setViewBinder(android.widget.SimpleCursorTreeAdapter.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 #getViewBinder()
|
*/
|
public void setViewBinder(ViewBinder viewBinder) {
|
mViewBinder = viewBinder;
|
}
|
|
private void bindView(View view, Context context, Cursor cursor, int[] from, int[] to) {
|
final ViewBinder binder = mViewBinder;
|
|
for (int i = 0; i < to.length; i++) {
|
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("SimpleCursorTreeAdapter can bind values" +
|
" only to TextView and ImageView!");
|
}
|
}
|
}
|
}
|
}
|
|
private void initFromColumns(Cursor cursor, String[] fromColumnNames, int[] fromColumns) {
|
for (int i = fromColumnNames.length - 1; i >= 0; i--) {
|
fromColumns[i] = cursor.getColumnIndexOrThrow(fromColumnNames[i]);
|
}
|
}
|
|
@Override
|
protected void bindChildView(View view, Context context, Cursor cursor, boolean isLastChild) {
|
if (mChildFrom == null) {
|
mChildFrom = new int[mChildFromNames.length];
|
initFromColumns(cursor, mChildFromNames, mChildFrom);
|
}
|
|
bindView(view, context, cursor, mChildFrom, mChildTo);
|
}
|
|
@Override
|
protected void bindGroupView(View view, Context context, Cursor cursor, boolean isExpanded) {
|
if (mGroupFrom == null) {
|
mGroupFrom = new int[mGroupFromNames.length];
|
initFromColumns(cursor, mGroupFromNames, mGroupFrom);
|
}
|
|
bindView(view, context, cursor, mGroupFrom, mGroupTo);
|
}
|
|
/**
|
* Called by bindView() to set the image for an ImageView. By default, the
|
* value will be treated as a 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
|
*/
|
protected 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);
|
}
|
|
/**
|
* This class can be used by external clients of SimpleCursorTreeAdapter
|
* to bind values from the Cursor to views.
|
*
|
* You should use this class to bind values from the Cursor to views
|
* that are not directly supported by SimpleCursorTreeAdapter or to
|
* change the way binding occurs for views supported by
|
* SimpleCursorTreeAdapter.
|
*
|
* @see SimpleCursorTreeAdapter#setViewImage(ImageView, String)
|
* @see SimpleCursorTreeAdapter#setViewText(TextView, String)
|
*/
|
public static 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, SimpleCursorTreeAdapter 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);
|
}
|
}
|
