1 /*
2  * Copyright (C) 2007 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package android.widget;
18 
19 import android.database.DataSetObserver;
20 import android.view.View;
21 import android.view.ViewGroup;
22 
23 /**
24  * An adapter that links a {@link ExpandableListView} with the underlying
25  * data. The implementation of this interface will provide access
26  * to the data of the children (categorized by groups), and also instantiate
27  * {@link View}s for children and groups.
28  */
29 public interface ExpandableListAdapter {
30     /**
31      * @see Adapter#registerDataSetObserver(DataSetObserver)
32      */
registerDataSetObserver(DataSetObserver observer)33     void registerDataSetObserver(DataSetObserver observer);
34 
35     /**
36      * @see Adapter#unregisterDataSetObserver(DataSetObserver)
37      */
unregisterDataSetObserver(DataSetObserver observer)38     void unregisterDataSetObserver(DataSetObserver observer);
39 
40     /**
41      * Gets the number of groups.
42      *
43      * @return the number of groups
44      */
getGroupCount()45     int getGroupCount();
46 
47     /**
48      * Gets the number of children in a specified group.
49      *
50      * @param groupPosition the position of the group for which the children
51      *            count should be returned
52      * @return the children count in the specified group
53      */
getChildrenCount(int groupPosition)54     int getChildrenCount(int groupPosition);
55 
56     /**
57      * Gets the data associated with the given group.
58      *
59      * @param groupPosition the position of the group
60      * @return the data child for the specified group
61      */
getGroup(int groupPosition)62     Object getGroup(int groupPosition);
63 
64     /**
65      * Gets the data associated with the given child within the given group.
66      *
67      * @param groupPosition the position of the group that the child resides in
68      * @param childPosition the position of the child with respect to other
69      *            children in the group
70      * @return the data of the child
71      */
getChild(int groupPosition, int childPosition)72     Object getChild(int groupPosition, int childPosition);
73 
74     /**
75      * Gets the ID for the group at the given position. This group ID must be
76      * unique across groups. The combined ID (see
77      * {@link #getCombinedGroupId(long)}) must be unique across ALL items
78      * (groups and all children).
79      *
80      * @param groupPosition the position of the group for which the ID is wanted
81      * @return the ID associated with the group
82      */
getGroupId(int groupPosition)83     long getGroupId(int groupPosition);
84 
85     /**
86      * Gets the ID for the given child within the given group. This ID must be
87      * unique across all children within the group. The combined ID (see
88      * {@link #getCombinedChildId(long, long)}) must be unique across ALL items
89      * (groups and all children).
90      *
91      * @param groupPosition the position of the group that contains the child
92      * @param childPosition the position of the child within the group for which
93      *            the ID is wanted
94      * @return the ID associated with the child
95      */
getChildId(int groupPosition, int childPosition)96     long getChildId(int groupPosition, int childPosition);
97 
98     /**
99      * Indicates whether the child and group IDs are stable across changes to the
100      * underlying data.
101      *
102      * @return whether or not the same ID always refers to the same object
103      * @see Adapter#hasStableIds()
104      */
hasStableIds()105     boolean hasStableIds();
106 
107     /**
108      * Gets a View that displays the given group. This View is only for the
109      * group--the Views for the group's children will be fetched using
110      * {@link #getChildView(int, int, boolean, View, ViewGroup)}.
111      *
112      * @param groupPosition the position of the group for which the View is
113      *            returned
114      * @param isExpanded whether the group is expanded or collapsed
115      * @param convertView the old view to reuse, if possible. You should check
116      *            that this view is non-null and of an appropriate type before
117      *            using. If it is not possible to convert this view to display
118      *            the correct data, this method can create a new view. It is not
119      *            guaranteed that the convertView will have been previously
120      *            created by
121      *            {@link #getGroupView(int, boolean, View, ViewGroup)}.
122      * @param parent the parent that this view will eventually be attached to
123      * @return the View corresponding to the group at the specified position
124      */
getGroupView(int groupPosition, boolean isExpanded, View convertView, ViewGroup parent)125     View getGroupView(int groupPosition, boolean isExpanded, View convertView, ViewGroup parent);
126 
127     /**
128      * Gets a View that displays the data for the given child within the given
129      * group.
130      *
131      * @param groupPosition the position of the group that contains the child
132      * @param childPosition the position of the child (for which the View is
133      *            returned) within the group
134      * @param isLastChild Whether the child is the last child within the group
135      * @param convertView the old view to reuse, if possible. You should check
136      *            that this view is non-null and of an appropriate type before
137      *            using. If it is not possible to convert this view to display
138      *            the correct data, this method can create a new view. It is not
139      *            guaranteed that the convertView will have been previously
140      *            created by
141      *            {@link #getChildView(int, int, boolean, View, ViewGroup)}.
142      * @param parent the parent that this view will eventually be attached to
143      * @return the View corresponding to the child at the specified position
144      */
getChildView(int groupPosition, int childPosition, boolean isLastChild, View convertView, ViewGroup parent)145     View getChildView(int groupPosition, int childPosition, boolean isLastChild,
146             View convertView, ViewGroup parent);
147 
148     /**
149      * Whether the child at the specified position is selectable.
150      *
151      * @param groupPosition the position of the group that contains the child
152      * @param childPosition the position of the child within the group
153      * @return whether the child is selectable.
154      */
isChildSelectable(int groupPosition, int childPosition)155     boolean isChildSelectable(int groupPosition, int childPosition);
156 
157     /**
158      * @see ListAdapter#areAllItemsEnabled()
159      */
areAllItemsEnabled()160     boolean areAllItemsEnabled();
161 
162     /**
163      * @see ListAdapter#isEmpty()
164      */
isEmpty()165     boolean isEmpty();
166 
167     /**
168      * Called when a group is expanded.
169      *
170      * @param groupPosition The group being expanded.
171      */
onGroupExpanded(int groupPosition)172     void onGroupExpanded(int groupPosition);
173 
174     /**
175      * Called when a group is collapsed.
176      *
177      * @param groupPosition The group being collapsed.
178      */
onGroupCollapsed(int groupPosition)179     void onGroupCollapsed(int groupPosition);
180 
181     /**
182      * Gets an ID for a child that is unique across any item (either group or
183      * child) that is in this list. Expandable lists require each item (group or
184      * child) to have a unique ID among all children and groups in the list.
185      * This method is responsible for returning that unique ID given a child's
186      * ID and its group's ID. Furthermore, if {@link #hasStableIds()} is true, the
187      * returned ID must be stable as well.
188      *
189      * @param groupId The ID of the group that contains this child.
190      * @param childId The ID of the child.
191      * @return The unique (and possibly stable) ID of the child across all
192      *         groups and children in this list.
193      */
getCombinedChildId(long groupId, long childId)194     long getCombinedChildId(long groupId, long childId);
195 
196     /**
197      * Gets an ID for a group that is unique across any item (either group or
198      * child) that is in this list. Expandable lists require each item (group or
199      * child) to have a unique ID among all children and groups in the list.
200      * This method is responsible for returning that unique ID given a group's
201      * ID. Furthermore, if {@link #hasStableIds()} is true, the returned ID must be
202      * stable as well.
203      *
204      * @param groupId The ID of the group
205      * @return The unique (and possibly stable) ID of the group across all
206      *         groups and children in this list.
207      */
getCombinedGroupId(long groupId)208     long getCombinedGroupId(long groupId);
209 }
210