5.x | Search Filter

In this page

• Introduction
• Configuration
• Special behaviors on action
• Performance result
• Example: Setup the SearchView
• 3rd libraries and floating SearchView

---

Introduction

To collect items based on the searchText, the item must implement the interface IFilterable or it will be simply skipped. The searchText will be propagated to the custom implementation of the filter() method.

Important note: PASS ALWAYS A COPY OF THE ORIGINAL LIST: due to internal mechanism, items are removed and/or added in order to animate items in the final list.

Items that implement IExpandable interface with a non-empty sub list of children items, will be automatically scanned by the Adapter and sub items picked up if searchText has a match.

If you don't want to implement the IFilterable interface on the items, then, you can override the method filterObject(item, constraint) to have another filter logic!

Configuration

setSearchText methods

• hasSearchText(): Checks if the current searchText is not empty nor null.
• hasNewSearchText(): Checks if the searchText is changed with a new text.
• getSearchText(): The current search text
• setSearchText(): Sets the new search text

filterItems with or without delay?

• filterItems(unfilteredItems): The method filters immediately the provided list with the search text previously set with setSearchText(). This gives a prompt responsiveness but more work and battery will be consumed.
• filterItems(unfilteredItems, delay): The execution of the filter will be delayed of few milliseconds (a value of 200-400ms is good value), useful to grab more characters from user before starting the filter.

In general items are always animated according to the limit below here.

setAnimateToLimit (from 5.0.0-b8)

Tunes the limit after the which the synchronization animations, occurred during updateDataSet and filter operations, are skipped and notifyDataSetChanged() will be called instead. Default value is 600 items, number of new items.

setNotifyChangeOfUnfilteredItems

Sometimes it is necessary, while filtering or after the data set has been updated, to rebound the items that remain unfiltered.
If the items have highlighted text, those items must be refreshed in order to change the text back to normal. This happens systematically when searchText is reduced in length by the user.
The notification (notifyItemChanged()) is triggered when items are not added nor deleted. Default value is false.

setNotifyMoveOfFilteredItems (from 5.0.0-b8)

This method performs a further step to nicely animate the moved items. The process is very slow on big list of the order of 3000-5000 items and higher, due to the calculation of the correct position for each item to be shifted. Use with caution!
The slowness is more visible when the searchText is cleared out after filtering or update data set. Default value is false.

highlightText

From class Utils, sets a spannable text with the accent color (if available) into the provided TextView. Accent color is automatically fetched.

Under the hood

A queue of notifications are executed in onPostExecute().
Also using the LinkedHashSet instead of List made a big improvement itself.

Special behaviors on action

• From beta8, the filter is 100% asynchronous, it uses the internal AsyncTask supporting a very high-volume of items.
• Sticky Header is disabled during the filter operation and restored when searchText returns empty.
• If search text is empty or null, the provided list is the current list.
• When sub items are collected, headers/parents are displayed too.
• You should disable the refresh and the addition of the items.
• If search text is empty or null, the provided list is the current list.
• Restoring deleted items with Undo functionality enabled:
  • Deleting items before the filter starts, restoring them while the filter is active, it makes the restored items to be displayed if part of the current filtered collection and at the correct position.
  • Starting the filter and removing items, then restoring them with no filter active, it makes the restored items to be displayed at the correct position too.
• Expandable item will collapse/expand only the filtered sub items.
• Screen rotation is also supported but, the search will be performed again.

Performance result (when animations are active)

Tested with 💯000 items in the emulator:

10:58:02.225 5003-5003/D/MainActivity: onQueryTextChange newText: 7
10:58:02.435 5003-5098/I/FilterAsyncTask: doInBackground - started Filter
10:58:02.435 5003-5098/V/FlexibleAdapter: FilterItems with searchText=7
10:58:03.535 5003-5098/V/FlexibleAdapter: Animate changes! oldSize=100001 newSize=40951
10:58:04.917 5003-5098/V/FlexibleAdapter: calculateRemovals total out=59050
10:58:04.940 5003-5098/V/FlexibleAdapter: calculateAdditions total new=0
10:58:04.940 5003-5098/I/FilterAsyncTask: doInBackground - ended Filter
10:58:04.946 5003-5003/V/FlexibleAdapter: Performing 100001 notifications
10:58:05.401 5003-5003/D/MainActivity: onUpdateEmptyView size=40951

From the moment the background process starts it takes ~2.5s + ~0.5s to perform remove/insert notifications.

You can play with the FragmentAsyncFilter to familiarize with the options for the filter.

Example: Setup the SearchView (code snipped from the demoApp)

To be continued

3rd libraries and floating SearchView

List of libraries that can work with FlexibleAdapter.
To be continued