3. Filtering

Filtering, by definition and usage in this context, is displaying a subset of data into the TableView based on a given filter globally. on a specified column or combination.

Steps to implement filtering functionality into TableView

1. Implement the IFilterableModel interface to your Cell Item Model. This interface would require you to implement the method getFilterableKeyword().
2. The getFilterableKeyword() requires a String value to be returned. Make sure that this item is unique for a specific filter and without conflict to other filter Strings.
3. Create a Filter instance passing the created TableView:

    ...
    private TableView   tableView;
    private Filter      tableViewFilter;
    ...    
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        ...
        tableView = setUpTableView();
        tableViewFilter = new Filter(tableView);
        ...
    }
    ...

4. Filtering can be done for the whole table (global), for a specified column or combination. The filtering call is very easy to use once the Filter object is created:

    ...
    public void filterWholeTable(String filterKeyword) {
        tableViewFilter.set(filterKeyword);
    }
    
    // assuming that Gender column is the 4th column in the TableView
    public void filterTableForGender(String genderFilterKeyword) {
        tableViewFilter.set(3, genderFilterKeyword);
    }
    
    public void filterTableColumnForKeyword(int column, String keyword) {
        tableViewFilter.set(column, keyword);
    }
    ...

Filtering notes

1. For clearing a filter, just pass an empty String ("" AND NOT null) to the set method.

    ...
    public void clearWholeTableFilter() {
        tableViewFilter.set("");
    }
    
    // assuming that Gender column is the 4th column in the TableView
    public void clearFilterForGender() {
        tableViewFilter.set(3, "");
    }
    ...

2. Multiple filtering combinations are supported such as COLUMN + WHOLE TABLE filter or MULTIPLE COLUMNS filter: e.g. "Happy" + "Boy" + all strings with a '-' character.
3. Based on step 2 of the implementation steps above, FilterableKeyword for different types of filters must be unique Strings AND no common substring. For instance, "male" and "female" should not be used together as filter keywords, since the method for processing filters uses String.contains(CharSequence s), the filtering process will return all data with male keyword, thus, female is also included in the filtered data set. Better use "boy" and "girl" or the hashed values of your keyword Strings.
4. Advanced usage: FilterChangedListener is also available and can be implemented if you want to do something whenever the TableView is filtered. Public listener methods include:

    // FilterChangedListener implementation:
    ...
    tableView.getFilterHandler().addFilterChangedListener(filterChangedListener);
    ...
    
    // The filterChangedListener variable:
    private FilterChangedListener filterChangedListener =
            new FilterChangedListener() {
                /**
                 * Called when a filter has been changed.
                 *
                 * @param filteredCellItems      The list of filtered cell items.
                 * @param filteredRowHeaderItems The list of filtered row items.
                 */
                @Override
                public void onFilterChanged(List<List<T>> filteredCellItems, List<T> filteredRowHeaderItems) {
                    // do something here...
                }
                
                /**
                 * Called when the TableView filters are cleared.
                 *
                 * @param originalCellItems      The unfiltered cell item list.
                 * @param originalRowHeaderItems The unfiltered row header list.
                 */
                @Override
                public void onFilterCleared(List<List<T>> originalCellItems, List<T> originalRowHeaderItems) {
                    // do something here...
                }
    };