Android APIs
public abstract class

Filter

extends Object
java.lang.Object
   ↳ android.widget.Filter

Class Overview

A filter constrains data with a filtering pattern.

Filters are usually created by Filterable classes.

Filtering operations performed by calling filter(CharSequence) or filter(CharSequence, android.widget.Filter.FilterListener) are performed asynchronously. When these methods are called, a filtering request is posted in a request queue and processed later. Any call to one of these methods will cancel any previous non-executed filtering request.

See also:

Summary

Nested Classes
interface Filter.FilterListener

Listener used to receive a notification upon completion of a filtering operation. 

class Filter.FilterResults

Holds the results of a filtering operation. 

Public Constructors
Filter()

Creates a new asynchronous filter.

Public Methods
CharSequence convertResultToString(Object resultValue)

Converts a value from the filtered set into a CharSequence.

final void filter(CharSequence constraint, Filter.FilterListener listener)

Starts an asynchronous filtering operation.

final void filter(CharSequence constraint)

Starts an asynchronous filtering operation.

Protected Methods
abstract Filter.FilterResults performFiltering(CharSequence constraint)

Invoked in a worker thread to filter the data according to the constraint.

abstract void publishResults(CharSequence constraint, Filter.FilterResults results)

Invoked in the UI thread to publish the filtering results in the user interface.

[Expand]
Inherited Methods
From class java.lang.Object

Public Constructors

public Filter ()

Added in API level 1

Creates a new asynchronous filter.

Public Methods

public CharSequence convertResultToString (Object resultValue)

Added in API level 1

Converts a value from the filtered set into a CharSequence. Subclasses should override this method to convert their results. The default implementation returns an empty String for null values or the default String representation of the value.

Parameters
resultValue Object: the value to convert to a CharSequence
Returns
CharSequence a CharSequence representing the value

public final void filter (CharSequence constraint, Filter.FilterListener listener)

Added in API level 1

Starts an asynchronous filtering operation. Calling this method cancels all previous non-executed filtering requests and posts a new filtering request that will be executed later.

Upon completion, the listener is notified.

Parameters
constraint CharSequence: the constraint used to filter the data
listener Filter.FilterListener: a listener notified upon completion of the operation

public final void filter (CharSequence constraint)

Added in API level 1

Starts an asynchronous filtering operation. Calling this method cancels all previous non-executed filtering requests and posts a new filtering request that will be executed later.

Parameters
constraint CharSequence: the constraint used to filter the data

Protected Methods

protected abstract Filter.FilterResults performFiltering (CharSequence constraint)

Added in API level 1

Invoked in a worker thread to filter the data according to the constraint. Subclasses must implement this method to perform the filtering operation. Results computed by the filtering operation must be returned as a Filter.FilterResults that will then be published in the UI thread through publishResults(CharSequence, android.widget.Filter.FilterResults).

Contract: When the constraint is null, the original data must be restored.

Parameters
constraint CharSequence: the constraint used to filter the data
Returns
Filter.FilterResults the results of the filtering operation

protected abstract void publishResults (CharSequence constraint, Filter.FilterResults results)

Added in API level 1

Invoked in the UI thread to publish the filtering results in the user interface. Subclasses must implement this method to display the results computed in performFiltering(CharSequence).

Parameters
constraint CharSequence: the constraint used to filter the data
results Filter.FilterResults: the results of the filtering operation