TcxDBDataFilterCriteria.OnBeforeChange Event

Occurs after changing filter criteria, but before updating data in the corresponding data controller.

Declaration

property OnBeforeChange: TcxDBDataFilterBeforeChangeEvent read; write;

Remarks

In default loading mode (the grid mode is disabled), a data controller loads all records into memory from the linked dataset. Whenever filter criteria are changed, the data controller filters records by itself.

If you handle the OnBeforeChange event, the data controller does not filter records. It is assumed that your OnBeforeChange event handler applies new filter conditions to the underlying dataset. The Sender parameter specifies the FilterCriteria object whose filter conditions have been changed. The ADataSet parameter represents the TDataSet object to which filter criteria should be applied. New filter conditions are provided by the AFilterText parameter.

There is another way to delegate filter operations to the underlying dataset. Set the AutoDataSetFilter property to True to make the dataset, rather than the data controller, filter records. In this case, the FilterText property value is assigned to the dataset’s Filter every time filter criteria are changed.

Compared with automatic dataset filtering, the OnBeforeChange event is more flexible as it allows you to completely control the filter text and the manner in which it is applied to the dataset.

Note that AutoDataSetFilter and OnBeforeChange work independently. When filter criteria are changed, the OnBeforeChange event is fired first. Then, if the AutoDataSetFilter property is set to True, new filter conditions are automatically applied to the dataset as described above, thus discarding your dataset filter set in the OnBeforeChange event handler. So, if you want to filter data yourself via the OnBeforeChange event, you usually have to set AutoDataSetFilter to False.

In grid mode, filtering by the data controller is disabled. You must filter data either by enabling the automatic filtering via the AutoDataSetFilter property or by handling the OnBeforeChange event.