FileDocCategorySizeDatePackage
Filter.javaAPI DocAndroid 5.1 API11723Thu Mar 12 22:22:10 GMT 2015android.widget

Filter

public abstract class Filter extends Object

A filter constrains data with a filtering pattern.

Filters are usually created by {@link android.widget.Filterable} classes.

Filtering operations performed by calling {@link #filter(CharSequence)} or {@link #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
android.widget.Filterable

Fields Summary
private static final String
LOG_TAG
private static final String
THREAD_NAME
private static final int
FILTER_TOKEN
private static final int
FINISH_TOKEN
private android.os.Handler
mThreadHandler
private android.os.Handler
mResultHandler
private Delayer
mDelayer
private final Object
mLock
Constructors Summary
public Filter()

Creates a new asynchronous filter.


              
      
        mResultHandler = new ResultsHandler();
    
Methods Summary
public java.lang.CharSequenceconvertResultToString(java.lang.Object resultValue)

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.

param
resultValue the value to convert to a CharSequence
return
a CharSequence representing the value

        return resultValue == null ? "" : resultValue.toString();
    
public final voidfilter(java.lang.CharSequence constraint)

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.

param
constraint the constraint used to filter the data
see
#filter(CharSequence, android.widget.Filter.FilterListener)

        filter(constraint, null);
    
public final voidfilter(java.lang.CharSequence constraint, android.widget.Filter$FilterListener listener)

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.

param
constraint the constraint used to filter the data
param
listener a listener notified upon completion of the operation
see
#filter(CharSequence)
see
#performFiltering(CharSequence)
see
#publishResults(CharSequence, android.widget.Filter.FilterResults)

        synchronized (mLock) {
            if (mThreadHandler == null) {
                HandlerThread thread = new HandlerThread(
                        THREAD_NAME, android.os.Process.THREAD_PRIORITY_BACKGROUND);
                thread.start();
                mThreadHandler = new RequestHandler(thread.getLooper());
            }

            final long delay = (mDelayer == null) ? 0 : mDelayer.getPostingDelay(constraint);
            
            Message message = mThreadHandler.obtainMessage(FILTER_TOKEN);
    
            RequestArguments args = new RequestArguments();
            // make sure we use an immutable copy of the constraint, so that
            // it doesn't change while the filter operation is in progress
            args.constraint = constraint != null ? constraint.toString() : null;
            args.listener = listener;
            message.obj = args;
    
            mThreadHandler.removeMessages(FILTER_TOKEN);
            mThreadHandler.removeMessages(FINISH_TOKEN);
            mThreadHandler.sendMessageDelayed(message, delay);
        }
    
protected abstract android.widget.Filter$FilterResultsperformFiltering(java.lang.CharSequence constraint)

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 {@link android.widget.Filter.FilterResults} that will then be published in the UI thread through {@link #publishResults(CharSequence, android.widget.Filter.FilterResults)}.

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

param
constraint the constraint used to filter the data
return
the results of the filtering operation
see
#filter(CharSequence, android.widget.Filter.FilterListener)
see
#publishResults(CharSequence, android.widget.Filter.FilterResults)
see
android.widget.Filter.FilterResults

protected abstract voidpublishResults(java.lang.CharSequence constraint, android.widget.Filter$FilterResults results)

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 {@link #performFiltering}.

param
constraint the constraint used to filter the data
param
results the results of the filtering operation
see
#filter(CharSequence, android.widget.Filter.FilterListener)
see
#performFiltering(CharSequence)
see
android.widget.Filter.FilterResults

public voidsetDelayer(android.widget.Filter$Delayer delayer)
Provide an interface that decides how long to delay the message for a given query. Useful for heuristics such as posting a delay for the delete key to avoid doing any work while the user holds down the delete key.

param
delayer The delayer.
hide

        synchronized (mLock) {
            mDelayer = delayer;
        }