Merge "Update documentation for FastScroller and SectionIndexer" into klp-dev

    }

    /**

     * Enables fast scrolling by letting the user quickly scroll through lists by

     * dragging the fast scroll thumb. The adapter attached to the list may want

     * to implement {@link SectionIndexer} if it wishes to display alphabet preview and

     * jump between sections of the list.

     * Specifies whether fast scrolling is enabled or disabled.

     * <p>

     * When fast scrolling is enabled, the user can quickly scroll through lists

     * by dragging the fast scroll thumb.

     * <p>

     * If the adapter backing this list implements {@link SectionIndexer}, the

     * fast scroller will display section header previews as the user scrolls.

     * Additionally, the user will be able to quickly jump between sections by

     * tapping along the length of the scroll bar.

     *

     * @see SectionIndexer

     * @see #isFastScrollEnabled()

     * @param enabled whether or not to enable fast scrolling

     * @param enabled true to enable fast scrolling, false otherwise

     */

    public void setFastScrollEnabled(final boolean enabled) {

        if (mFastScrollEnabled != enabled) {

    }

    /**

     * Set whether or not the fast scroller should always be shown in place of the

     * standard scrollbars. Fast scrollers shown in this way will not fade out and will

     * be a permanent fixture within the list. Best combined with an inset scroll bar style

     * that will ensure enough padding. This will enable fast scrolling if it is not

     * Set whether or not the fast scroller should always be shown in place of

     * the standard scroll bars. This will enable fast scrolling if it is not

     * already enabled.

     * <p>

     * Fast scrollers shown in this way will not fade out and will be a

     * permanent fixture within the list. This is best combined with an inset

     * scroll bar style to ensure the scroll bar does not overlap content.

     *

     * @param alwaysShow true if the fast scroller should always be displayed.

     * @param alwaysShow true if the fast scroller should always be displayed,

     *            false otherwise

     * @see #setScrollBarStyle(int)

     * @see #setFastScrollEnabled(boolean)

     */

    }

    /**

     * Returns true if the fast scroller is set to always show on this view rather than

     * fade out when not in use.

     * Returns true if the fast scroller is set to always show on this view.

     *

     * @return true if the fast scroller will always show.

     * @return true if the fast scroller will always show

     * @see #setFastScrollAlwaysVisible(boolean)

     */

    public boolean isFastScrollAlwaysVisible() {

    }

    /**

     * Returns the current state of the fast scroll feature.

     * Returns true if the fast scroller is enabled.

     *

     * @see #setFastScrollEnabled(boolean)

     * @return true if fast scroll is enabled, false otherwise

     */

package android.widget;

/**

 * Interface that should be implemented on Adapters to enable fast scrolling 

 * in an {@link AbsListView} between sections of the list. A section is a group of list items

 * to jump to that have something in common. For example, they may begin with the

 * same letter or they may be songs from the same artist. ExpandableListAdapters that

 * consider groups and sections as synonymous should account for collapsed groups and return

 * an appropriate section/position.

 * 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 {

    /**

     * This provides the list view with an array of section objects. In the simplest

     * case these are Strings, each containing one letter of the alphabet.

     * They could be more complex objects that indicate the grouping for the adapter's

     * consumption. The list view will call toString() on the objects to get the

     * preview letter to display while scrolling.

     * @return the array of objects that indicate the different sections of the list.

     * 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();

    /**

     * Provides the starting index in the list for a given section.

     * @param section the index of the section to jump to.

     * @return the starting position of that section. If the section is out of bounds, the

     * position must be clipped to fall within the size of the list.

     * 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 section);

    int getPositionForSection(int sectionIndex);

    /**

     * This is a reverse mapping to fetch the section index for a given position

     * in the list.

     * @param position the position for which to return the section

     * @return the section index. If the position is out of bounds, the section index

     * 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);

}