content: /*
   * Copyright (C) 2008 The Android Open Source Project
   *
   * Licensed under the Apache License, Version 2.0 (the "License");
   * you may not use this file except in compliance with the License.
   * You may obtain a copy of the License at
   *
   *      http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  
  package android.widget;
  
  /**
   * Interface that may implemented on {@link Adapter}s to enable fast scrolling
   * between sections of an {@link AbsListView}.
   * <p>
   * A section is a group of list items that have something in common. For
   * example, they may begin with the same letter or they may be songs from the
   * same artist.
   * <p>
   * {@link ExpandableListAdapter}s that consider groups and sections as
   * synonymous should account for collapsed groups and return an appropriate
   * section/position.
   *
   * @see AbsListView#setFastScrollEnabled(boolean)
   */
  public interface SectionIndexer {
      /**
       * Returns an array of objects representing sections of the list. The
       * returned array and its contents should be non-null.
       * <p>
       * The list view will call toString() on the objects to get the preview text
       * to display while scrolling. For example, an adapter may return an array
       * of Strings representing letters of the alphabet. Or, it may return an
       * array of objects whose toString() methods return their section titles.
       *
       * @return the array of section objects
       */
      Object[] getSections();
  
      /**
       * Given the index of a section within the array of section objects, returns
       * the starting position of that section within the adapter.
       * <p>
       * If the section's starting position is outside of the adapter bounds, the
       * position must be clipped to fall within the size of the adapter.
       *
       * @param sectionIndex the index of the section within the array of section
       *            objects
       * @return the starting position of that section within the adapter,
       *         constrained to fall within the adapter bounds
       */
      int getPositionForSection(int sectionIndex);
  
      /**
       * Given a position within the adapter, returns the index of the
       * corresponding section within the array of section objects.
       * <p>
       * If the section index is outside of the section array bounds, the index
       * must be clipped to fall within the size of the section array.
       * <p>
       * For example, consider an indexer where the section at array index 0
       * starts at adapter position 100. Calling this method with position 10,
       * which is before the first section, must return index 0.
       *
       * @param position the position within the adapter for which to return the
       *            corresponding section index
       * @return the index of the corresponding section within the array of
       *         section objects, constrained to fall within the array bounds
       */
      int getSectionForPosition(int position);
  }
  