1 /*
2  * Copyright (C) 2008 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 /**
20  * Interface that may implemented on {@link Adapter}s to enable fast scrolling
21  * between sections of an {@link AbsListView}.
22  * <p>
23  * A section is a group of list items that have something in common. For
24  * example, they may begin with the same letter or they may be songs from the
25  * same artist.
26  * <p>
27  * {@link ExpandableListAdapter}s that consider groups and sections as
28  * synonymous should account for collapsed groups and return an appropriate
29  * section/position.
30  *
31  * @see AbsListView#setFastScrollEnabled(boolean)
32  */
33 public interface SectionIndexer {
34     /**
35      * Returns an array of objects representing sections of the list. The
36      * returned array and its contents should be non-null.
37      * <p>
38      * The list view will call toString() on the objects to get the preview text
39      * to display while scrolling. For example, an adapter may return an array
40      * of Strings representing letters of the alphabet. Or, it may return an
41      * array of objects whose toString() methods return their section titles.
42      *
43      * @return the array of section objects
44      */
getSections()45     Object[] getSections();
46 
47     /**
48      * Given the index of a section within the array of section objects, returns
49      * the starting position of that section within the adapter.
50      * <p>
51      * If the section's starting position is outside of the adapter bounds, the
52      * position must be clipped to fall within the size of the adapter.
53      *
54      * @param sectionIndex the index of the section within the array of section
55      *            objects
56      * @return the starting position of that section within the adapter,
57      *         constrained to fall within the adapter bounds
58      */
getPositionForSection(int sectionIndex)59     int getPositionForSection(int sectionIndex);
60 
61     /**
62      * Given a position within the adapter, returns the index of the
63      * corresponding section within the array of section objects.
64      * <p>
65      * If the section index is outside of the section array bounds, the index
66      * must be clipped to fall within the size of the section array.
67      * <p>
68      * For example, consider an indexer where the section at array index 0
69      * starts at adapter position 100. Calling this method with position 10,
70      * which is before the first section, must return index 0.
71      *
72      * @param position the position within the adapter for which to return the
73      *            corresponding section index
74      * @return the index of the corresponding section within the array of
75      *         section objects, constrained to fall within the array bounds
76      */
getSectionForPosition(int position)77     int getSectionForPosition(int position);
78 }
79