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:
- setEditable: defines whether the user can enter free text, or choose one of the available, prepopulated, options.
- setAutoOptions: instructs the editor to extract the options from the table's content. This is a dynamic process, if new content is added to the table, new options will be presented to the user.
- setOptions: defines the set of options that the user can choose. If the editor is defined as non editable, the user can only choose one of these options.
- setMaxHistory: if there are options available, the max history defines the number of historic elements to present. The history can therefore be disabled by setting the max history to 0.
-
setListCellRenderer:
defines (or unsets) the renderer used to display the filter's content. Setting a renderer has a major
implication: editor becomes non editable.
There is an alternative method to setup the filter's renderer: setting a TableCellRenderer, using the TableFilterHeader' setTableCellRenderer method.
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:
-
Comparison operators. The comparison is done on the parsed object, not on the string
representation, unless no
Format
orComparator
is defined for the given type. For example, specifying the text ">= 4" implies, for a column with integer types, that a direct comparison between integers will be performed. These operators are:- >=
- >
- <
- <=
- <>
-
Equal operators. The comparison is done on the parsed object, not on the string
representation, unless no
Format
is defined for the given type. The comparison is performed using the equals method. These operators are:- !=: note that, in most cases, it will behave as the operator <>
- ! : equivalent to !=
- <
- =
- ==: equivalent to =
-
Basic wildcard operators. These operators work using the string representation of the
types (using, when possible, the defined
Format
instance). Only two wildcard characters are defined: * and ?- ~: for example ~ *vadis* will filter in all expressions including the substring vadis
- !~: negates the previous operator
- Regular expression operator. There is only one such operator: ~~, accepting a java regular expression.
There are 3 specific methods in the parser that greatly affect its behaviour:
- setIgnoreCase: defines if the filter matching is case sensitive or not. It also affects how the options in the filter editor are located, ignoring case or not.
- setDefaultOperator: if the user does not provide specifically an operator, the default operator -which is ~ by default- is used.
- setFormat: this and the setComparator method are normally required to use custom types, as detailed below.
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:
- autoOptions, false by default, defines whether the editors should automatically extract the options from the associated table models.
- autoSelection, true by default, defines whether the filter will automatically select a row when that row is the only one remaining in the table after a filter operation.
- dateFormat, used by the parser, as detailed above
- defaultOperator, used by the parser, as detailed above
- headerBackground
- headerForeground
- headerPosition, whether to locate the filter header just above or below the table's header, or wheter the placement will be done manually by the programmer.
- ignoreCase
- maxPopupHistory, used by all the filter editors.
- maxVisiblePopupRows , used to limit the size of the popup menus in the filter editors.
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.