Java tutorial
/* * 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.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. If there is an existing cursor * it will be closed. */ public void setGroupCursor(Cursor cursor) { mGroupCursorHelper.changeCursor(cursor, false); } /** * Sets the children Cursor for a particular group. If there is an existing cursor * it will be closed. * <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.close(); 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 && !mCursor.isClosed()) { if (false) 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(); } } } }