Package icyllis.modernui.widget

# Class Filter

java.lang.Object
icyllis.modernui.widget.Filter

public abstract class Filter extends Object

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, 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:
  - `Filterable`

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static interface`
  `Filter.Delayer`
  `static interface`
  `Filter.FilterListener`
  Listener used to receive a notification upon completion of a filtering operation.
  `protected static class`
  `Filter.FilterResults`
  Holds the results of a filtering operation.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Filter()`
  Creates a new asynchronous filter.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `CharSequence`
  `convertResultToString(Object resultValue)`
  Converts a value from the filtered set into a CharSequence.
  `final void`
  `filter(CharSequence constraint)`
  Starts an asynchronous filtering operation.
  `final void`
  `filter(CharSequence constraint, Filter.FilterListener listener)`
  Starts an asynchronous filtering operation.
  `protected abstract Filter.FilterResults`
  `performFiltering(CharSequence constraint)`
  Invoked in a worker thread to filter the data according to the constraint.
  `protected abstract void`
  `publishResults(CharSequence constraint, Filter.FilterResults results)`
  Invoked in the UI thread to publish the filtering results in the user interface.
  `void`
  `setDelayer(Filter.Delayer delayer)`
  Provide an interface that decides how long to delay the message for a given query.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### Filter

    public Filter()

    Creates a new asynchronous filter.

- ## Method Details

  - ### setDelayer

    public void setDelayer(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.
    Parameters:
      `delayer` - The delayer.

  - ### filter

    public final void filter(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.

    Parameters:
      `constraint` - the constraint used to filter the data
    See Also:
      - `filter(CharSequence, FilterListener)`

  - ### filter

    public final void filter(CharSequence constraint, 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.

    Parameters:
      `constraint` - the constraint used to filter the data
      `listener` - a listener notified upon completion of the operation
    See Also:
      - `filter(CharSequence)`
      - `performFiltering(CharSequence)`
      - `publishResults(CharSequence, FilterResults)`

  - ### performFiltering

    protected abstract Filter.FilterResults performFiltering(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 `Filter.FilterResults` that will then be published in the UI thread through `publishResults(CharSequence, FilterResults)`.

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

    Parameters:
      `constraint` - the constraint used to filter the data
    Returns:
      the results of the filtering operation
    See Also:
      - `filter(CharSequence, FilterListener)`
      - `publishResults(CharSequence, FilterResults)`
      - `Filter.FilterResults`

  - ### publishResults

    protected abstract void publishResults(CharSequence constraint, 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 `performFiltering(java.lang.CharSequence)`.

    Parameters:
      `constraint` - the constraint used to filter the data
      `results` - the results of the filtering operation
    See Also:
      - `filter(CharSequence, FilterListener)`
      - `performFiltering(CharSequence)`
      - `Filter.FilterResults`

  - ### convertResultToString

    public CharSequence convertResultToString(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.

    Parameters:
      `resultValue` - the value to convert to a CharSequence
    Returns:
      a CharSequence representing the value