Dataset Filtering
TTMSFNCDataSetFilterDialog builds filter expressions for a Delphi dataset. Assign DataSet before showing the dialog so the available fields can be discovered and the generated FilterText can be applied.
Show the Dialog
Assign an active dataset to DataSet, then call Execute. When the user applies the dialog, the component updates the dataset filter text and toggles filtering when needed.
TMSFNCDataSetFilterDialog1.DataSet := ClientDataSet1;
TMSFNCDataSetFilterDialog1.FilterText := ClientDataSet1.Filter;
TMSFNCDataSetFilterDialog1.Execute;
Seed or Read Filter Text
Use FilterText when the dialog should open with an existing filter or when the application needs to inspect the generated expression after execution.
TMSFNCDataSetFilterDialog1.DataSet := ClientDataSet1;
TMSFNCDataSetFilterDialog1.FilterText := 'Status = ''Open''';
TMSFNCDataSetFilterDialog1.Execute;
Caption := TMSFNCDataSetFilterDialog1.FilterText;
Customize Dialog Events
Handle button events when the application needs to control whether the dialog closes, clear the filter in a custom way, or log generated filter expressions. Handle OnGetFormatSettings when date, time, or number formatting must match a specific locale.
procedure TForm1.TMSFNCDataSetFilterDialog1ApplyButtonClicked(Sender: TObject;
AFilterBuilder: TTMSFNCFilterBuilder; var AClose: Boolean);
begin
Caption := AFilterBuilder.FilterText;
AClose := True;
end;
procedure TForm1.TMSFNCDataSetFilterDialog1GetFormatSettings(Sender: TObject;
var AFormatSettings: TFormatSettings);
begin
AFormatSettings.ShortDateFormat := 'yyyy-mm-dd';
end;
Show User-Friendly Column Names
Dataset field names are often short, technical identifiers (CUST_NO, STATUS_CD) that are not meaningful to end users. Use DisplayNames when the filter dialog should present a friendlier label for a column instead of the raw field name.
DisplayNames is a TTMSFNCFilterDialogDisplayNames collection of TTMSFNCFilterDialogFieldNameMap items, each mapping one FieldName to one DisplayName. Add mappings explicitly with AddMap, or leave a field unmapped: the dialog auto-populates a mapping from the dataset field's DisplayLabel the first time it reads the dataset's fields, but only when no mapping for that field already exists. The generated FilterText still references the underlying field names — only the dialog UI substitutes the friendly label.
procedure TForm1.FormCreate(Sender: TObject);
begin
TMSFNCDataSetFilterDialog1.DataSet := ClientDataSet1;
// Explicitly map a field name to a friendly label.
TMSFNCDataSetFilterDialog1.DisplayNames.AddMap('CUST_NO', 'Customer Number');
TMSFNCDataSetFilterDialog1.DisplayNames.AddMap('STATUS_CD', 'Status');
// Any field left unmapped here is auto-populated from the dataset field's
// DisplayLabel the first time the dialog reads the dataset's fields
// (Execute, or any call that rebuilds the filter columns).
end;
procedure TForm1.btnFilterClick(Sender: TObject);
begin
if TMSFNCDataSetFilterDialog1.Execute then
begin
// The generated FilterText still references the underlying field names;
// only the dialog UI shows the mapped display names to the user.
ClientDataSet1.Filter := TMSFNCDataSetFilterDialog1.FilterText;
ClientDataSet1.Filtered := TMSFNCDataSetFilterDialog1.FilterText <> '';
end;
end;
Combining dialog execution, seeded filter text, and result handling
The following example seeds the dialog with a previously saved filter expression, applies the result to the dataset, and logs the generated text:
procedure TForm1.btnFilterClick(Sender: TObject);
begin
TMSFNCDataSetFilterDialog1.DataSet := ClientDataSet1;
TMSFNCDataSetFilterDialog1.FilterText := FLastFilter; // restore previous
if TMSFNCDataSetFilterDialog1.Execute then
begin
FLastFilter := TMSFNCDataSetFilterDialog1.FilterText;
ClientDataSet1.Filter := FLastFilter;
ClientDataSet1.Filtered := FLastFilter <> '';
Memo1.Lines.Add('Filter applied: ' + FLastFilter);
end;
end;
procedure TForm1.TMSFNCDataSetFilterDialog1ApplyButtonClick(Sender: TObject;
var ACanClose: Boolean);
begin
// Prevent closing if the filter text is empty
ACanClose := TMSFNCDataSetFilterDialog1.FilterText <> '';
if not ACanClose then
ShowMessage('Please define at least one filter condition.');
end;