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
17package android.widget;
18
19import android.database.DataSetObserver;
20import android.view.View;
21import 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 */
29public interface ExpandableListAdapter {
30    /**
31     * @see Adapter#registerDataSetObserver(DataSetObserver)
32     */
33    void registerDataSetObserver(DataSetObserver observer);
34
35    /**
36     * @see Adapter#unregisterDataSetObserver(DataSetObserver)
37     */
38    void unregisterDataSetObserver(DataSetObserver observer);
39
40    /**
41     * Gets the number of groups.
42     *
43     * @return the number of groups
44     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
155    boolean isChildSelectable(int groupPosition, int childPosition);
156
157    /**
158     * @see ListAdapter#areAllItemsEnabled()
159     */
160    boolean areAllItemsEnabled();
161
162    /**
163     * @see ListAdapter#isEmpty()
164     */
165    boolean isEmpty();
166
167    /**
168     * Called when a group is expanded.
169     *
170     * @param groupPosition The group being expanded.
171     */
172    void onGroupExpanded(int groupPosition);
173
174    /**
175     * Called when a group is collapsed.
176     *
177     * @param groupPosition The group being collapsed.
178     */
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     */
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     */
208    long getCombinedGroupId(long groupId);
209}
210