VB Declaration
Declare Function sx_FilterDlg Lib "Apollo9.dll"
(ByVal hWnd As Integer,
ByVal cpExpr As Any,
ByVal cpCaption As Any,
ByVal iIsIndexList As Integer)
As String
C Declaration
LONG FAR PASCAL sx_FilterDlg
(HWND hwnd,
BYTEP cpExpr
BYTEP cpCaption,
SHORT iHasIndexList);
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.
Parameters
hWnd: The hWnd property of an existing form that will be used as the parent window of the dialog box.
cpExpr: 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 (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.
cpCaption: A caption string to be used as a title for the filter dialog. If passed as a NULL string (0&), the title defaults to 'Filter Builder' + dbf file name.
iIsIndexList: 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 the index box is shown below. The dialog without the index list is displayed on the next page.
The behavior of the operations buttons also changes.
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.
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 iIsIndexList 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 sx_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 iIsIndexList 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.
GoButton. Only displayed if the iIsIndexList parameter is False. The filter string constructed by the user is returned. Note: When iIsIndexList 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.
CountButton. Only displayed if the iIsIndexList 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 Error message box
VB Example
Sub bFilter_Click ()
Dim lRecNum As Long
Dim cString As String
Dim iRet As Integer
If Not FilterOn Then
' set up alias names
iRet = sx_FilterAlias("LastName", "last")
iRet = sx_FilterAlias("FirstName", "first")
iRet = sx_FilterAlias("Address", "a1")
iRet = sx_FilterAlias("City", "a2")
iRet = sx_FilterAlias("State", "a3")
' allow User to set the query by passing
' iIsIndexList as TRUE
cString = sx_FilterDlg(sxtest.hWnd, 0&, "My App Name", True
If Len(cString) > 0 Then
FilterOn = True
End If
If FilterOn Then
bFilter.Caption = "&Reset"
End If
Else
' clear query
FilterOn = False
bFilter.Caption = "&Filter"
lRecNum = sx_Query(0&)
End If
End Sub
C Example
void CNamesForm::OnButtonFilter()
{
sx_FilterDlg(GetParent(), NULL, NULL, TRUE));
// test if user set filter
if (lstrlen(sx_DBFilter()))
bFilterOn = TRUE;
...
...
}