/*
* Copyright (C) 2007 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.app.Activity;
import android.content.Context;
import android.database.ContentObserver;
import android.database.Cursor;
import android.database.DataSetObserver;
import android.os.Handler;
import android.util.Config;
import android.util.Log;
import android.util.SparseArray;
import android.view.View;
import android.view.ViewGroup;
/**
* An adapter that exposes data from a series of {@link Cursor}s to an
* {@link ExpandableListView} widget. The top-level {@link Cursor} (that is
* given in the constructor) exposes the groups, while subsequent {@link Cursor}s
* returned from {@link #getChildrenCursor(Cursor)} expose children within a
* particular group. The Cursors must include a column named "_id" or this class
* will not work.
*/
public abstract class CursorTreeAdapter extends BaseExpandableListAdapter implements Filterable,
CursorFilter.CursorFilterClient {
private Context mContext;
private Handler mHandler;
private boolean mAutoRequery;
/** The cursor helper that is used to get the groups */
MyCursorHelper mGroupCursorHelper;
/**
* The map of a group position to the group's children cursor helper (the
* cursor helper that is used to get the children for that group)
*/
SparseArray<MyCursorHelper> mChildrenCursorHelpers;
// Filter related
CursorFilter mCursorFilter;
FilterQueryProvider mFilterQueryProvider;
/**
* Constructor. The adapter will call {@link Cursor#requery()} on the cursor whenever
* it changes so that the most recent data is always displayed.
*
* @param cursor The cursor from which to get the data for the groups.
*/
public CursorTreeAdapter(Cursor cursor, Context context) {
init(cursor, context, true);
}
/**
* Constructor.
*
* @param cursor The cursor from which to get the data for the groups.
* @param context The context
* @param autoRequery If true the adapter will call {@link Cursor#requery()}
* on the cursor whenever it changes so the most recent data is
* always displayed.
*/
public CursorTreeAdapter(Cursor cursor, Context context, boolean autoRequery) {
init(cursor, context, autoRequery);
}
private void init(Cursor cursor, Context context, boolean autoRequery) {
mContext = context;
mHandler = new Handler();
mAutoRequery = autoRequery;
mGroupCursorHelper = new MyCursorHelper(cursor);
mChildrenCursorHelpers = new SparseArray<MyCursorHelper>();
}
/**
* Gets the cursor helper for the children in the given group.
*
* @param groupPosition The group whose children will be returned
* @param requestCursor Whether to request a Cursor via
* {@link #getChildrenCursor(Cursor)} (true), or to assume a call
* to {@link #setChildrenCursor(int, Cursor)} will happen shortly
* (false).
* @return The cursor helper for the children of the given group
*/
synchronized MyCursorHelper getChildrenCursorHelper(int groupPosition, boolean requestCursor) {
MyCursorHelper cursorHelper = mChildrenCursorHelpers.get(groupPosition);
if (cursorHelper == null) {
if (mGroupCursorHelper.moveTo(groupPosition) == null) return null;
final Cursor cursor = getChildrenCursor(mGroupCursorHelper.getCursor());
cursorHelper = new MyCursorHelper(cursor);
mChildrenCursorHelpers.put(groupPosition, cursorHelper);
}
return cursorHelper;
}
/**
* Gets the Cursor for the children at the given group. Subclasses must
* implement this method to return the children data for a particular group.
* <p>
* If you want to asynchronously query a provider to prevent blocking the
* UI, it is possible to return null and at a later time call
* {@link #setChildrenCursor(int, Cursor)}.
* <p>
* It is your responsibility to manage this Cursor through the Activity
* lifecycle. It is a good idea to use {@link Activity#managedQuery} which
* will handle this for you. In some situations, the adapter will deactivate
* the Cursor on its own, but this will not always be the case, so please
* ensure the Cursor is properly managed.
*
* @param groupCursor The cursor pointing to the group whose children cursor
* should be returned
* @return The cursor for the children of a particular group, or null.
*/
abstract protected Cursor getChildrenCursor(Cursor groupCursor);
/**
* Sets the group Cursor.
*
* @param cursor The Cursor to set for the group.
*/
public void setGroupCursor(Cursor cursor) {
mGroupCursorHelper.changeCursor(cursor, false);
}
/**
* Sets the children Cursor for a particular group.
* <p>
* This is useful when asynchronously querying to prevent blocking the UI.
*
* @param groupPosition The group whose children are being set via this Cursor.
* @param childrenCursor The Cursor that contains the children of the group.
*/
public void setChildrenCursor(int groupPosition, Cursor childrenCursor) {
/*
* Don't request a cursor from the subclass, instead we will be setting
* the cursor ourselves.
*/
MyCursorHelper childrenCursorHelper = getChildrenCursorHelper(groupPosition, false);
/*
* Don't release any cursor since we know exactly what data is changing
* (this cursor, which is still valid).
*/
childrenCursorHelper.changeCursor(childrenCursor, false);
}
public Cursor getChild(int groupPosition, int childPosition) {
// Return this group's children Cursor pointing to the particular child
return getChildrenCursorHelper(groupPosition, true).moveTo(childPosition);
}
public long getChildId(int groupPosition, int childPosition) {
return getChildrenCursorHelper(groupPosition, true).getId(childPosition);
}
public int getChildrenCount(int groupPosition) {
MyCursorHelper helper = getChildrenCursorHelper(groupPosition, true);
return (mGroupCursorHelper.isValid() && helper != null) ? helper.getCount() : 0;
}
public Cursor getGroup(int groupPosition) {
// Return the group Cursor pointing to the given group
return mGroupCursorHelper.moveTo(groupPosition);
}
public int getGroupCount() {
return mGroupCursorHelper.getCount();
}
public long getGroupId(int groupPosition) {
return mGroupCursorHelper.getId(groupPosition);
}
public View getGroupView(int groupPosition, boolean isExpanded, View convertView,
ViewGroup parent) {
Cursor cursor = mGroupCursorHelper.moveTo(groupPosition);
if (cursor == null) {
throw new IllegalStateException("this should only be called when the cursor is valid");
}
View v;
if (convertView == null) {
v = newGroupView(mContext, cursor, isExpanded, parent);
} else {
v = convertView;
}
bindGroupView(v, mContext, cursor, isExpanded);
return v;
}
/**
* Makes a new group view to hold the group data pointed to by cursor.
*
* @param context Interface to application's global information
* @param cursor The group cursor from which to get the data. The cursor is
* already moved to the correct position.
* @param isExpanded Whether the group is expanded.
* @param parent The parent to which the new view is attached to
* @return The newly created view.
*/
protected abstract View newGroupView(Context context, Cursor cursor, boolean isExpanded,
ViewGroup parent);
/**
* Bind an existing view to the group data pointed to by cursor.
*
* @param view Existing view, returned earlier by newGroupView.
* @param context Interface to application's global information
* @param cursor The cursor from which to get the data. The cursor is
* already moved to the correct position.
* @param isExpanded Whether the group is expanded.
*/
protected abstract void bindGroupView(View view, Context context, Cursor cursor,
boolean isExpanded);
public View getChildView(int groupPosition, int childPosition, boolean isLastChild,
View convertView, ViewGroup parent) {
MyCursorHelper cursorHelper = getChildrenCursorHelper(groupPosition, true);
Cursor cursor = cursorHelper.moveTo(childPosition);
if (cursor == null) {
throw new IllegalStateException("this should only be called when the cursor is valid");
}
View v;
if (convertView == null) {
v = newChildView(mContext, cursor, isLastChild, parent);
} else {
v = convertView;
}
bindChildView(v, mContext, cursor, isLastChild);
return v;
}
/**
* Makes a new child view to hold the data pointed to by cursor.
*
* @param context Interface to application's global information
* @param cursor The cursor from which to get the data. The cursor is
* already moved to the correct position.
* @param isLastChild Whether the child is the last child within its group.
* @param parent The parent to which the new view is attached to
* @return the newly created view.
*/
protected abstract View newChildView(Context context, Cursor cursor, boolean isLastChild,
ViewGroup parent);
/**
* Bind an existing view to the child data pointed to by cursor
*
* @param view Existing view, returned earlier by newChildView
* @param context Interface to application's global information
* @param cursor The cursor from which to get the data. The cursor is
* already moved to the correct position.
* @param isLastChild Whether the child is the last child within its group.
*/
protected abstract void bindChildView(View view, Context context, Cursor cursor,
boolean isLastChild);
public boolean isChildSelectable(int groupPosition, int childPosition) {
return true;
}
public boolean hasStableIds() {
return true;
}
private synchronized void releaseCursorHelpers() {
for (int pos = mChildrenCursorHelpers.size() - 1; pos >= 0; pos--) {
mChildrenCursorHelpers.valueAt(pos).deactivate();
}
mChildrenCursorHelpers.clear();
}
@Override
public void notifyDataSetChanged() {
notifyDataSetChanged(true);
}
/**
* Notifies a data set change, but with the option of not releasing any
* cached cursors.
*
* @param releaseCursors Whether to release and deactivate any cached
* cursors.
*/
public void notifyDataSetChanged(boolean releaseCursors) {
if (releaseCursors) {
releaseCursorHelpers();
}
super.notifyDataSetChanged();
}
@Override
public void notifyDataSetInvalidated() {
releaseCursorHelpers();
super.notifyDataSetInvalidated();
}
@Override
public void onGroupCollapsed(int groupPosition) {
deactivateChildrenCursorHelper(groupPosition);
}
/**
* Deactivates the Cursor and removes the helper from cache.
*
* @param groupPosition The group whose children Cursor and helper should be
* deactivated.
*/
synchronized void deactivateChildrenCursorHelper(int groupPosition) {
MyCursorHelper cursorHelper = getChildrenCursorHelper(groupPosition, true);
mChildrenCursorHelpers.remove(groupPosition);
cursorHelper.deactivate();
}
/**
* @see CursorAdapter#convertToString(Cursor)
*/
public String convertToString(Cursor cursor) {
return cursor == null ? "" : cursor.toString();
}
/**
* @see CursorAdapter#runQueryOnBackgroundThread(CharSequence)
*/
public Cursor runQueryOnBackgroundThread(CharSequence constraint) {
if (mFilterQueryProvider != null) {
return mFilterQueryProvider.runQuery(constraint);
}
return mGroupCursorHelper.getCursor();
}
public Filter getFilter() {
if (mCursorFilter == null) {
mCursorFilter = new CursorFilter(this);
}
return mCursorFilter;
}
/**
* @see CursorAdapter#getFilterQueryProvider()
*/
public FilterQueryProvider getFilterQueryProvider() {
return mFilterQueryProvider;
}
/**
* @see CursorAdapter#setFilterQueryProvider(FilterQueryProvider)
*/
public void setFilterQueryProvider(FilterQueryProvider filterQueryProvider) {
mFilterQueryProvider = filterQueryProvider;
}
/**
* @see CursorAdapter#changeCursor(Cursor)
*/
public void changeCursor(Cursor cursor) {
mGroupCursorHelper.changeCursor(cursor, true);
}
/**
* @see CursorAdapter#getCursor()
*/
public Cursor getCursor() {
return mGroupCursorHelper.getCursor();
}
/**
* Helper class for Cursor management:
* <li> Data validity
* <li> Funneling the content and data set observers from a Cursor to a
* single data set observer for widgets
* <li> ID from the Cursor for use in adapter IDs
* <li> Swapping cursors but maintaining other metadata
*/
class MyCursorHelper {
private Cursor mCursor;
private boolean mDataValid;
private int mRowIDColumn;
private MyContentObserver mContentObserver;
private MyDataSetObserver mDataSetObserver;
MyCursorHelper(Cursor cursor) {
final boolean cursorPresent = cursor != null;
mCursor = cursor;
mDataValid = cursorPresent;
mRowIDColumn = cursorPresent ? cursor.getColumnIndex("_id") : -1;
mContentObserver = new MyContentObserver();
mDataSetObserver = new MyDataSetObserver();
if (cursorPresent) {
cursor.registerContentObserver(mContentObserver);
cursor.registerDataSetObserver(mDataSetObserver);
}
}
Cursor getCursor() {
return mCursor;
}
int getCount() {
if (mDataValid && mCursor != null) {
return mCursor.getCount();
} else {
return 0;
}
}
long getId(int position) {
if (mDataValid && mCursor != null) {
if (mCursor.moveToPosition(position)) {
return mCursor.getLong(mRowIDColumn);
} else {
return 0;
}
} else {
return 0;
}
}
Cursor moveTo(int position) {
if (mDataValid && (mCursor != null) && mCursor.moveToPosition(position)) {
return mCursor;
} else {
return null;
}
}
void changeCursor(Cursor cursor, boolean releaseCursors) {
if (cursor == mCursor) return;
deactivate();
mCursor = cursor;
if (cursor != null) {
cursor.registerContentObserver(mContentObserver);
cursor.registerDataSetObserver(mDataSetObserver);
mRowIDColumn = cursor.getColumnIndex("_id");
mDataValid = true;
// notify the observers about the new cursor
notifyDataSetChanged(releaseCursors);
} else {
mRowIDColumn = -1;
mDataValid = false;
// notify the observers about the lack of a data set
notifyDataSetInvalidated();
}
}
void deactivate() {
if (mCursor == null) {
return;
}
mCursor.unregisterContentObserver(mContentObserver);
mCursor.unregisterDataSetObserver(mDataSetObserver);
mCursor.deactivate();
mCursor = null;
}
boolean isValid() {
return mDataValid && mCursor != null;
}
private class MyContentObserver extends ContentObserver {
public MyContentObserver() {
super(mHandler);
}
@Override
public boolean deliverSelfNotifications() {
return true;
}
@Override
public void onChange(boolean selfChange) {
if (mAutoRequery && mCursor != null) {
if (Config.LOGV) Log.v("Cursor", "Auto requerying " + mCursor +
" due to update");
mDataValid = mCursor.requery();
}
}
}
private class MyDataSetObserver extends DataSetObserver {
@Override
public void onChanged() {
mDataValid = true;
notifyDataSetChanged();
}
@Override
public void onInvalidated() {
mDataValid = false;
notifyDataSetInvalidated();
}
}
}
}
|
