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
17package 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 */
33public 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     */
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     */
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     */
77    int getSectionForPosition(int position);
78}
79