}
/**
- * 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);
+ int getSectionForPosition(int position);
}
OSDN Git Service
