public class

AlphabetIndexer

extends DataSetObserver
implements SectionIndexer
java.lang.Object
   ↳ android.database.DataSetObserver
     ↳ android.widget.AlphabetIndexer

Class Overview

A helper class for adapters that implement the SectionIndexer interface. If the items in the adapter are sorted by simple alphabet-based sorting, then this class provides a way to do fast indexing of large lists using binary search. It caches the indices that have been determined through the binary search and also invalidates the cache if changes occur in the cursor.

Your adapter is responsible for updating the cursor by calling setCursor(Cursor) if the cursor changes. getPositionForSection(int) method does the binary search for the starting index of a given section (alphabet).

Summary

Fields
protected CharSequence mAlphabet The string of characters that make up the indexing sections.
protected int mColumnIndex The index of the cursor column that this list is sorted on.
protected Cursor mDataCursor Cursor that is used by the adapter of the list view.
Public Constructors
AlphabetIndexer(Cursor cursor, int sortedColumnIndex, CharSequence alphabet)
Constructs the indexer.
Public Methods
int getPositionForSection(int sectionIndex)
Performs a binary search or cache lookup to find the first row that matches a given section's starting letter.
int getSectionForPosition(int position)
Returns the section index for a given position in the list by querying the item and comparing it with all items in the section array.
Object[] getSections()
Returns the section array constructed from the alphabet provided in the constructor.
void onChanged()
This method is called when the entire data set has changed, most likely through a call to requery() on a Cursor.
void onInvalidated()
This method is called when the entire data becomes invalid, most likely through a call to deactivate() or close() on a Cursor.
void setCursor(Cursor cursor)
Sets a new cursor as the data set and resets the cache of indices.
Protected Methods
int compare(String word, String letter)
Default implementation compares the first character of word with letter.
[Expand]
Inherited Methods
From class android.database.DataSetObserver
From class java.lang.Object
From interface android.widget.SectionIndexer

Fields

protected CharSequence mAlphabet

Since: API Level 3

The string of characters that make up the indexing sections.

protected int mColumnIndex

Since: API Level 3

The index of the cursor column that this list is sorted on.

protected Cursor mDataCursor

Since: API Level 3

Cursor that is used by the adapter of the list view.

Public Constructors

public AlphabetIndexer (Cursor cursor, int sortedColumnIndex, CharSequence alphabet)

Since: API Level 3

Constructs the indexer.

Parameters
cursor the cursor containing the data set
sortedColumnIndex the column number in the cursor that is sorted alphabetically
alphabet string containing the alphabet, with space as the first character. For example, use the string " ABCDEFGHIJKLMNOPQRSTUVWXYZ" for English indexing. The characters must be uppercase and be sorted in ascii/unicode order. Basically characters in the alphabet will show up as preview letters.

Public Methods

public int getPositionForSection (int sectionIndex)

Since: API Level 3

Performs a binary search or cache lookup to find the first row that matches a given section's starting letter.

Parameters
sectionIndex the section to search for
Returns
  • the row index of the first occurrence, or the nearest next letter. For instance, if searching for "T" and no "T" is found, then the first row starting with "U" or any higher letter is returned. If there is no data following "T" at all, then the list size is returned.

public int getSectionForPosition (int position)

Since: API Level 3

Returns the section index for a given position in the list by querying the item and comparing it with all items in the section array.

Parameters
position the position for which to return the section
Returns
  • the section index. If the position is out of bounds, the section index must be clipped to fall within the size of the section array.

public Object[] getSections ()

Since: API Level 3

Returns the section array constructed from the alphabet provided in the constructor.

Returns
  • the section array

public void onChanged ()

Since: API Level 3

This method is called when the entire data set has changed, most likely through a call to requery() on a Cursor.

public void onInvalidated ()

Since: API Level 3

This method is called when the entire data becomes invalid, most likely through a call to deactivate() or close() on a Cursor.

public void setCursor (Cursor cursor)

Since: API Level 3

Sets a new cursor as the data set and resets the cache of indices.

Parameters
cursor the new cursor to use as the data set

Protected Methods

protected int compare (String word, String letter)

Since: API Level 3

Default implementation compares the first character of word with letter.