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