/*
 * 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 ViewBinder is available, ViewBinder.setViewValue(View, 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, setViewText(TextView, String) is invoked. If the returned value is false and the view to bind is an ImageView, setViewImage(ImageView, String) is invoked. If no appropriate binding can be found, an IllegalStateException is thrown. /**
 * 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. /** 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. /** 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.
/**
     * 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. /** 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. /** 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.
/**
     * The View IDs that will display a child's data fetched from the
     * corresponding column.
     */
    private int[] mChildTo;
    
    
View binder, if supplied
/**
     * View binder, if supplied
     */
    private ViewBinder mViewBinder;

    
Constructor.
Params:
context – The context where the ExpandableListView associated with this SimpleCursorTreeAdapter is running
cursor – The database cursor
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.
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.
groupFrom – A list of column names that will be used to display the
           data for a group.
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.
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.
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.
childFrom – A list of column names that will be used to display the
           data for a child.
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./**
     * 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.
Params:
context – The context where the ExpandableListView associated with this SimpleCursorTreeAdapter is running
cursor – The database cursor
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.
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.
groupFrom – A list of column names that will be used to display the
           data for a group.
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.
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.
childFrom – A list of column names that will be used to display the
           data for a child.
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./**
     * 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.
Params:
context – The context where the ExpandableListView associated with this SimpleCursorTreeAdapter is running
cursor – The database cursor
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.
groupFrom – A list of column names that will be used to display the
           data for a group.
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.
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.
childFrom – A list of column names that will be used to display the
           data for a child.
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./**
     * 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 ViewBinder used to bind data to views. 
See Also:
setViewBinder(ViewBinder)
Returns:
a ViewBinder or null if the binder does not exist/**
     * 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.
Params:
viewBinder – the binder used to bind data to views, can be null to
       remove the existing binder
See Also:
getViewBinder()/**
     * 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.
Params:
v – ImageView to receive an image
value – the value retrieved from the cursor/**
     * 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.
Params:
v – TextView to receive text
text – the text to be set for the TextView/**
     * 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 Also:
setViewImage.setViewImage(ImageView, String)
SimpleCursorTreeAdapter.setViewText(TextView, String)/**
     * 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.
Params:
view – the view to bind the data to
cursor – the cursor to get the data from
columnIndex – the column at which the data can be found in the cursor
Returns:
true if the data was bound to the view, false otherwise/**
         * 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);
    }
}