XTREE enhancement: auto-filtering. This is a mechanism, similar to that available in Windows Explorer or Excel, by which the user can click on a special button in the column header to access an automatically-generated dialog of filtering options, which can then be used to temporarily remove (hide) some of the items from the tree.
The feature is enabled by setting the XTF2_AUTOFILTER (&h00800000) bit in the FLAGS2 member of the FLAGS structure/parameter. Currently it is limited to array-based trees.
At the simplest level, the filtering is entirely a client-side affair, auto-configured by XTREE and controlled by the user, invisible to the application, and lasting only for the life of the tree. Items remaining in the tree retain their original physical record/row numbers so that selecting or editing a specific item appears the same the application regardless how many other items had been filtered out.
Filter Types
There are four different types of filters, including none, which are automatically selected based on the column attributes, or which can be manually select by means of these Advance Coldef Options:
| • | Filter=CB |
| • | Filter=RANGE |
| • | Filter=PATTERN |
| • | Filter=NONE |
The CB (checkbox) filter is the most automatic of the filter types. Each time you bring it up, it analyzes the data currently in the column and reduces it down to a set of up to 10 checkbox options which are either complete values (e.g. Red, Green, Blue), starting characters (e.g. R, G, B), or ranges of starting characters (e.g. A-D, E-G, H-Q, R-). The user can select one or more of the options to filter out all the others. There is also a "select all" option to bring the previously filtered items back.
The RANGE filter prompts for from/to values and works for numbers and dates/times. In the case of dates/times, the from/to values can be in any of the formats supported by the sort logic.
The PATTERN filter is essentially just a string character match, case insensitive, and position independent. The pattern "oo" will match "Oolong Tea", "COOKIES", "foo", etc. Currently the emphasis is on simplicity; wildcards or regex expressions are not supported but may be added later depending on feedback.
The NONE option prevents any filter from being assigned. Otherwise, if no Filter type is specified, XTREE will choose one—or none—based on the column attributes.
Comments
| • | Columns with a filter option other than NONE will have a check-mark button at the right edge of the column header. So filtering requires that the headers be visible. Columns with active filter criteria applied will display a strange symbol to the left of the column title meant to represent filtering. This symbol takes the place of the old up/down sort indicators, which have been moved to the top edge of the column header. |
| • | When multiple columns have filter specifications, they are combined with the "AND" operation. For example, if you filter the name column to include just the names starting with A and F, and also the price column to include just the range from $9.99 to $39.99, then only those rows which meet both criteria will remain visible. You can remove the filter from one column: for a checkbox filter, click "Select All"; for the other types, enter an empty pattern or range. Or you can remove the filters from all the columns by clicking on the "clear" button in any column's filter dialog. |
| • | On multi-level trees, filtering only applies to the top level, and all the dependents are filtered along with the top-level parent. |
Application Filtering
The application can participate in the filtering operation by defining a "filter status" column (1 character wide), using cformat code "0" (zero). Typically you would want to hide such a column by also specifying the "H" code. Once defined, the application can pre-filter (i.e. hide) rows, prior to call XTREE to load them into the tree, by setting the column to "1". A space or "0" is treated as visible.
Note that this is similar to the LoadOptions=NoRowIf# capability—see 6.5.1627.0—except that rows filtered by a "0" column can be unfiltered by the user, whereas rows filtered out by the NoRowIf# cannot.
The application can also be notified of the visibility state of each row on exit from the tree, by adding the cformat code "U" to the column. In this case the field must also appear in the answer array and will be set by XTREE to "0" for visible and "1" for filtered out (invisible). On re-entry into the tree in XTROP_RESELECT mode, any changes made by the application to the filter state column in the answer array will be applied to the tree (i.e. hiding or unhiding rows). Note that except in the XTF2_ANSEQDATA case—where the answer and data arrays have the same format, or are actually the same—the filter state column is positioned with the checkboxes, i.e. after the drag-drop and multi-select fields, but before any editable text fields.
For the XTROP_REPLACE operation, rows are first loaded from the data array and are then updated based on the answer array. In the case where there is an updatable filter status col (0U) and rows had been filtered out during the previous editing session, this will result in all of the rows being first added—because the data array is not updated by the filtering operation—and then the filtered-out rows will be removed during the answer array load. There is nothing wrong with this two-step approach other than inefficiency; if you have very large trees, it would be more efficient to transfer the updated filter status indicators from the answer array back to the data array before reloading the tree with XTROP_REPLACE.
The sample program XTRA5.BP in EXLIB:[908,21] has been updated to illustrate various auto-filter features. You need to enter '1' to the auto-filter prompt when running it.
