Java tutorial
/* * Copyright (C) 2007 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package android.widget; import android.annotation.UnsupportedAppUsage; import android.os.Handler; import android.os.HandlerThread; import android.os.Looper; import android.os.Message; import android.util.Log; /** * <p>A filter constrains data with a filtering pattern.</p> * * <p>Filters are usually created by {@link android.widget.Filterable} * classes.</p> * * <p>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.</p> * * @see android.widget.Filterable */ public abstract class Filter { private static final String LOG_TAG = "Filter"; private static final String THREAD_NAME = "Filter"; private static final int FILTER_TOKEN = 0xD0D0F00D; private static final int FINISH_TOKEN = 0xDEADBEEF; private Handler mThreadHandler; private Handler mResultHandler; private Delayer mDelayer; private final Object mLock = new Object(); /** * <p>Creates a new asynchronous filter.</p> */ public Filter() { mResultHandler = new ResultsHandler(); } /** * 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 */ @UnsupportedAppUsage public void setDelayer(Delayer delayer) { synchronized (mLock) { mDelayer = delayer; } } /** * <p>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.</p> * * @param constraint the constraint used to filter the data * * @see #filter(CharSequence, android.widget.Filter.FilterListener) */ public final void filter(CharSequence constraint) { filter(constraint, null); } /** * <p>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.</p> * * <p>Upon completion, the listener is notified.</p> * * @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) */ public final void filter(CharSequence constraint, FilterListener listener) { 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); } } /** * <p>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)}.</p> * * <p><strong>Contract:</strong> When the constraint is null, the original * data must be restored.</p> * * @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 FilterResults performFiltering(CharSequence constraint); /** * <p>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}.</p> * * @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 */ protected abstract void publishResults(CharSequence constraint, FilterResults results); /** * <p>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.</p> * * @param resultValue the value to convert to a CharSequence * @return a CharSequence representing the value */ public CharSequence convertResultToString(Object resultValue) { return resultValue == null ? "" : resultValue.toString(); } /** * <p>Holds the results of a filtering operation. The results are the values * computed by the filtering operation and the number of these values.</p> */ protected static class FilterResults { public FilterResults() { // nothing to see here } /** * <p>Contains all the values computed by the filtering operation.</p> */ public Object values; /** * <p>Contains the number of values computed by the filtering * operation.</p> */ public int count; } /** * <p>Listener used to receive a notification upon completion of a filtering * operation.</p> */ public static interface FilterListener { /** * <p>Notifies the end of a filtering operation.</p> * * @param count the number of values computed by the filter */ public void onFilterComplete(int count); } /** * <p>Worker thread handler. When a new filtering request is posted from * {@link android.widget.Filter#filter(CharSequence, android.widget.Filter.FilterListener)}, * it is sent to this handler.</p> */ private class RequestHandler extends Handler { public RequestHandler(Looper looper) { super(looper); } /** * <p>Handles filtering requests by calling * {@link Filter#performFiltering} and then sending a message * with the results to the results handler.</p> * * @param msg the filtering request */ public void handleMessage(Message msg) { int what = msg.what; Message message; switch (what) { case FILTER_TOKEN: RequestArguments args = (RequestArguments) msg.obj; try { args.results = performFiltering(args.constraint); } catch (Exception e) { args.results = new FilterResults(); Log.w(LOG_TAG, "An exception occured during performFiltering()!", e); } finally { message = mResultHandler.obtainMessage(what); message.obj = args; message.sendToTarget(); } synchronized (mLock) { if (mThreadHandler != null) { Message finishMessage = mThreadHandler.obtainMessage(FINISH_TOKEN); mThreadHandler.sendMessageDelayed(finishMessage, 3000); } } break; case FINISH_TOKEN: synchronized (mLock) { if (mThreadHandler != null) { mThreadHandler.getLooper().quit(); mThreadHandler = null; } } break; } } } /** * <p>Handles the results of a filtering operation. The results are * handled in the UI thread.</p> */ private class ResultsHandler extends Handler { /** * <p>Messages received from the request handler are processed in the * UI thread. The processing involves calling * {@link Filter#publishResults(CharSequence, * android.widget.Filter.FilterResults)} * to post the results back in the UI and then notifying the listener, * if any.</p> * * @param msg the filtering results */ @Override public void handleMessage(Message msg) { RequestArguments args = (RequestArguments) msg.obj; publishResults(args.constraint, args.results); if (args.listener != null) { int count = args.results != null ? args.results.count : -1; args.listener.onFilterComplete(count); } } } /** * <p>Holds the arguments of a filtering request as well as the results * of the request.</p> */ private static class RequestArguments { /** * <p>The constraint used to filter the data.</p> */ CharSequence constraint; /** * <p>The listener to notify upon completion. Can be null.</p> */ FilterListener listener; /** * <p>The results of the filtering operation.</p> */ FilterResults results; } /** * @hide */ public interface Delayer { /** * @param constraint The constraint passed to {@link Filter#filter(CharSequence)} * @return The delay that should be used for * {@link Handler#sendMessageDelayed(android.os.Message, long)} */ long getPostingDelay(CharSequence constraint); } }