Declaration
function FilterDlg( winHandle: HWnd; sExpr, sCaption: String; bHasIndexList: WordBool ): String;
Description
Displays a modal dialog box that allows the user to create a custom filter expression by selecting information and elements displayed on the Filter Builder form.
This method is not supported under remote tables using Apollo Database Server.
Parameters
winHandle: The hWnd property of an existing form that will be used as the parent window of the dialog box.
sExpr: A filter string default that will occupy the work area text box that receives the new filter expression. If no default is to be displayed, pass this parameter as a NULL string ('' or #0). If a current filter exists, and this parameter is passed as a NULL string, the current filter will be passed to the dialog as default.
sCaption: A caption string to be used as a title for the filter dialog. If passed as a NULL string ('' or #0), the title defaults to 'Filter Builder' + dbf file name.
bHasIndexList: True or False depending on whether or not the index list box is to be displayed. The value of this parameter drastically changes the behavior of the dialog.
If True, the dialog is best suited for power users that are able to use the index list and key expressions to advantage. The dialog with index box is shown in Figure 1 (See Delphi Example #1). The dialog less the index list is displayed in Figure 2 (See Delphi Example #2).
The behavior of the operations buttons also changes. See below.
Return Value
The filter string created by the user. If the filter was canceled by the user, the length of the string returned is 0.
Figure 1
Form Description
All form elements are described in the status bar below the work area whenever the mouse cursor is positioned over the dialog box item. If the function list box is selected, the highlighted function has its syntax displayed in the status bar.
The dialog box contains the following elements:
Field name list box. Selecting a field name from the box inserts that name at the current caret position in the work area.
Function list box. Selected functions are also inserted at the current caret position.
Index list box. Only displayed if the iHasIndexList parameter is True. The current index tags and the expressions used to build them are displayed in this list box. If one of these items is selected, QKEYVAL("tagname") is inserted in the work area for character type indexes (see Query). If the index is not of type CHAR, the index expression is inserted in the work area. Using the index expression ensures query optimization.
Relational operations buttons insert the corresponding symbol in the work area.
Logical operations buttons insert the corresponding logical operator in the work area.
Execute Button. Only displayed if the iHasIndexList parameter is True. This button actually executes the filter and then exits. If the filter expression is invalid, a message is displayed and the exit is not taken. If a filter was set, the filter string constructed by the user is returned.
Go Button. Only displayed if the iHasIndexList parameter is False. The filter string constructed by the user is returned. When iHasIndexList is False, the query is NEVER actually executed. The disposition of the filter string is entirely in the hands of the applications programmer.
Cancel Button. Cancels the dialog box and returns a zero length string.
Count Button. Only displayed if the iHasIndexList parameter is True. Executes the query and displays the number of records found in the status box. The filter is removed after the count. To actually execute, the Execute button must be pressed.
Test/Test Syntax Button. Tests the expression for optimization level and syntax. If the expression can be parsed, the optimization level (NONE, PART, or FULL) is reported in the status box. If a syntax error occurs, the user is informed via a standard Apollo Error message box.
Figure 2
Delphi Examples
// EXAMPLE #1: Displays Filter Dialog box with Index List
procedure TForm1.Button1Click(Sender: TObject);
const
bFilterOn: WordBool = False;
begin
with ApTbl do
begin
if not bFilterOn then
begin
// Display filter dialog box for user to construct expression
FilterDlg( self.Handle,'STATE = "CA"','With Index Box',True );
// Filter set? If so, reset static bFilterOn flag
if Length( DBFilter ) > 0 then
begin
bFilterOn := True;
Button1.Caption := '&Reset';
GoTop;
end;
end
else
begin
// Otherwise, clear query & change caption back
bFilterOn := False;
Button1.Caption := '&Filter';
Query( '' );
GoTop;
end;
end;
end;
// EXAMPLE #2: Displays Filter Dialog box w/o Index List
procedure TForm1.Button1Click(Sender: TObject);
const
bFilterOn: WordBool = False;
var
sFilt : String;
begin
with ApTbl do
begin
if not bFilterOn then
begin
// Display filter dialog box for user to construct expression
sFilt := FilterDlg( self.Handle, 'STATE = "CA"', 'Without Index Box', False );
// Filter set? If so, reset static bFilterOn flag
if Length( sFilt ) > 0 then
begin
bFilterOn := True;
Button1.Caption := '&Reset';
Query( sFilt );
GoTop;
end;
end
else
begin
// Otherwise, clear query & change caption back
bFilterOn := False;
Button1.Caption := '&Filter';
Query( '' );
GoTop;
end;
end;
end;
C++Builder Example
// EXAMPLE #1: Displays Filter Dialog box with Index List
void __fastcall TForm1::Button1Click(TObject *Sender)
{
static bool bFilterOn = false;
if (!bFilterOn)
{
// Display filter dialog box for user to construct expression
ApTbl->FilterDlg( Form1->Handle, "STATE = 'CA'", "With Index Box", true );
// Filter set? If so, reset static bFilterOn flag
if (ApTbl->DBFilter() > "")
{
bFilterOn = true;
Button1->Caption = "&Reset";
ApTbl->GoTop();
}
}
else
{
// Otherwise, clear query & change caption back
bFilterOn = false;
Button1->Caption = "&Filter";
ApTbl->Query( "" );
ApTbl->GoTop();
}
}
See Also