TableFilter tutorial

Filter Header

TableFilterHeader is the main Gui component in the TableFilter library; the following line of code:

TableFilterHeader filterHeader = new TableFilterHeader(table);

is enough to setup a filter in a table, looking like:

A different constructor can be used to place the header just atop the table:

TableFilterHeader filterHeader = new TableFilterHeader(table, Position.TOP);

This header places together a set of filter editors, one per table's column, and is responsible to resize / move them as the table's columns change their layout. Please note that the colors, fonts, are fully customizable, and will mimic by default the table header. The default look and feel, on Windows Vista, looks like:

It is also possible to place manually the header, for example as a footer below the table:

Filter Editor

Each column in a table with a TableFilterHeader has an associated filter editor, that looks like:

In this case, the content is text based, and a pop down menu will show any list of prepopulated options, as well as a historic of the last provided inputs. The editor provides autocompletion, and, if defined as non editable, will restrict the input to one of the available options.

It is possible to provide a renderer, as it is done on generic swing tables and lists, supporting implementations such as:

An editor has the type FilterEditor, and can be obtained from the TableFilterHeader as:

FilterEditor editor = filterHeader.getFilterEditor(modelColumn);

Its API includes methods such as:

It is possible to affect the look and feel and the behaviour of all the editors by using directly the API of the filter header. For example, the following line of code changes the background color:

filterHeader.setBackground(Color.lightGray);

Filter expressions

The library is delivered with a single expression parser, which supports a comprehensive set of operators to define simple filtering expressions. Each filter editor can have a separate parser, and it is possible to define new parsers by implementing the IFilterTextParser interface.

The supported operators include:

There are 3 specific methods in the parser that greatly affect its behaviour:

Custom types

The type associated to each table's column is defined by its table model. Primitive types are directly supported, but the user must provide specific format instances to define how to parse or format other objects.

If the user fails to define the format for any non primitive, the library will use the default string representation. If the table includes some renderer to format an object, the default string representation will normally be not enough, and the filtering will look wrong. In addition, all the filtering operations will be string based, which can affect to the performance and, worse, to the operation logic.

For example, a date can be renderer as DD/MM/YYYY; if this format is not provided, an expression such as > 01/02/2020 can give faux positives for dates like 11/12/2019.

Dates are, in fact, the only non primitive type directly supported by the library, although the user should still provide the right used format. The default format is predefined in FilterSettings.dateFormat, or can be specified on each parser separately, using the setFormat method.

Settings

The FilterSettings singleton collects all default settings that will be used when new FilterHeaders are created. As in previous versions, it is also possible defining theses settings using system properties; it includes:

Examples

The source distribution includes a test program -whose screenshots are used in this document-. The program makes use of most of the features built in the library, so its code can be used to study how to use the library. It is also useful to check the effect of the settings on the filters.

The example is located in the package net.coderazzi.filters.examples, under the examples folder.

It can be also directly tested using this link.