skip to main content
OpenEdge Development: ADM and SmartObjects
SmartObjects : SmartFilters
 
SmartFilters
A SmartFilter is an ADM filter‑class SmartObject that comprises a frame containing data fields that are used to gather user‑specified selection criteria for filtering the data in a SmartDataObject. It follows the query‑by-fields model and is implemented as a dynamic SmartObject; that is, the selection criteria (the filter) are specified at run time rather than at design time.
Because the SmartFilter is implemented as a dynamic SmartObject, it does not have a wizard. At design time, it opens as a frame that contains only three visual objects: buttons labeled Apply, Blank, and Reset. You then use the Link Advisor specify a SmartDataObject as a data source for the SmartFilter instance. You also specify its filter fields: the data‑source fields in which the application user can specify selection criteria. You do this by modifying instance properties in its instance properties dialog box.
At run time, the user specifies selection criteria in the filter fields, using the buttons as needed:
*The Apply button applies the currently specified filter to the base query.
*The Blank button removes the currently specified filter, leaving the selection fields undefined.
*The Reset button resets the selection fields to the most recently applied filter.
Table 2–11 lists the SmartDataObject files.
 
Table 2–11: SmartFilter files 
File type
Filename / SmartLinks
Master file
(Because a SmartFilter’s fields are defined at design time and its selection criteria are defined dynamically at run time, a template is not necessary.)
src/adm2/dynfilter.w
Primary include file
src/adm2/filter.i
ADM/Progress Advisor‑supported SmartLinks
Filter-Source
Instance properties dialog box
src/adm2/support/filterd.w (source code)
gui/adm2/support/filterd.r (compiled code)
SmartFilter instance properties
The main purpose of SmartFilter instance properties is to allow you to select fields from the SmartDataObject that serves as the SmartFilter’s Filter-Target and customize how application users specify filter data.
Figure 2–11 shows the SmartFilter instance properties dialog box.
Figure 2–11: SmartFilter Properties dialog box
Instance properties in this dialog box are grouped into the following panes:
*Data pane
*Field Properties pane
*Style pane
*String Operators pane
*Operator View as pane
*Size & Position pane
A final instance property, View, is not in any group.
You use these instance properties as described in the following sections.
Data pane
You use the instance properties in the Data pane to define the SmartDataObject that will serve as the SmartFilter’s Filter-Target and specify the SmartDataObject fields that are available to the SmartFilter:
*Target, Browse — If your SmartFilter already is linked to a SmartDataObject that will serve as its Filter-Target, the Target field lists that SmartDataObject and is disabled; you cannot specify another value.
The Target field is enabled, however, if you open the instance properties dialog box without linking the SmartFilter to a Filter-Target. You might want to create a SmartFilter without a link, for example, because you placed it in a SmartContainer and intend to link it to a Filter-Target in another SmartContainer. The Browse button opens a window in which you can browse to and select a SmartDataObject.
Note: This SmartDataObject is only design‑time SmartDataObject. You must ensure it is linked at run time.
*Fields, Edit Field List — The Fields list box lists the filter fields that will appear in the SmartFilter, in the order in which they will be shown. The Edit Field List button opens a window in which you can select, deselect, and reorder these fields.
Field Properties pane
Because the fields that appear in the SmartFilter are generated dynamically, you cannot access most of their properties in the AppBuilder; however, the SmartFilter’s instance property provides access to a few field properties. Select a field in the Fields list box, and its property values appear in the Field Properties pane.
Changes entered into a control in the Field Properties pane take effect as soon as you select another field in the Fields list box. Pressing OK in the dialog box saves all field property value changes, including any that are not displayed:
*Label, Filter Target — The Label fill-in field displays the label of the selected field. By default, the AppBuilder uses the label from the data source and disables this field. To enable the Label field so you can enter your own label, uncheck Filter Target.
*Width, Default — The Width fill‑in field displays the width of the selected field. By default, the AppBuilder uses the default field width and disables this field. (The default field width is data‑type dependent and is specified in the Size & Position pane. See the “Size & Position pane” section.) To enable the Width field so you can enter your own value, uncheck Default.
*Tooltip — Enter the text of the tooltip for this field. There is no default.
*Help ID — Enter the context ID for the relevant help topic. There is no default.
*View as range fields, Explicit operator— These check boxes override the default filter style (see the “Style pane” section for details) for the field selected in the Fields fill‑in field:
*The View as range fields check box gives the selected field the same visualization as the Range style gives to all fields.
*The Explicit operator check box assigns the same operator to the selected field as the Explicit style gives to all fields.
You can check only one of these boxes. One or both might be disabled, depending on your choice of default filter style:
*If the default filter style is Inline, neither check box is enabled.
*If the style is Explicit or Implicit, only the View as range fields check box is enabled.
*If the style is Range, only the Explicit operator check box is enabled.
Style pane
You use this set of radio buttons to specify the default filter style, which defines how the AppBuilder visualizes the fields in the SmartFilter and applies the application user’s filter criteria to the query:
*Implicit — This generates a single list of fill‑in fields in which the application user can specify filter data at run time. Each field is assigned the appropriate data type, thus restricting the filter data entered by the user to the correct data type. You specify in the associated combo box the implicit operator to be used with the filter data.
In some cases, other SmartFilter properties might override the default behavior of the Implicit style:
*If you check the BEGINS property, the AppBuilder uses the BEGINS operator for character fields regardless of your choice of operator. (This is the default.)
*If you check the CONTAINS property, the AppBuilder uses the CONTAINS operator for filter fields that are mapped to word‑indexed database fields, regardless of your choice of operator. In addition, these fields are visualized as editors rather than fill‑in fields, with their height and word‑wrap capabilities regulated by the Number of Lines in Editors property.
See the “String Operators pane” section for details on the BEGINS and CONTAINS properties. For details on the Number of Lines in Editors property, see the “Size & Position pane” section.
The Implicit style supports wild cards, but only if you do not check the BEGINS property. There is one exception: a value that starts with a wild card always generates an expression with the Progress MATCHES keyword.
*Explicit — This shows, after a filter field, a list of selectable operators from which the application user can select at run time. The operator is visualized as either a combo box or a radio set, depending on how you set the properties in the Operator View as pane. For details, see the “Operator View as pane” section.
Selecting the Explicit style disables the BEGINS property. (This is because BEGINS is in the operator list for character fields.) For details, see the “String Operators pane” section.
*Range — This generates two lists of each filter field, allowing the application user to specify a range of inclusive values as filter data at run time. The left‑hand set of fields support wild cards.
Selecting the Range style disables the BEGINS property. However, the CONTAINS string operator property might override the default behavior of the Range style. If you check this property, the AppBuilder uses the CONTAINS operator for filter fields that are mapped to word‑indexed database fields, instead of a range of values. In addition, these fields are visualized as editors rather than fill‑in fields, with their height and word‑wrap capabilities regulated by the Number of Lines in Editors property.
See the “String Operators pane” section for details on the BEGINS and CONTAINS properties. For details on the Number of Lines in Editors property, see the “Size & Position pane” section.
*Inline — This generates a single list of fields for which the application user can enter the filter data and an operator at run time. All fields are represented as character fields to allow typing the operator names. The default operator, which the AppBuilder uses if the user does not enter an operator, is EQUALS.
In some cases, other SmartFilter properties might override the default behavior of the Inline style:
*If you check the BEGINS property, the AppBuilder uses the BEGINS operator as the default operator for character fields instead of EQUALS.
*If you check the CONTAINS property, the AppBuilder uses the CONTAINS operator for filter fields that are mapped to word‑indexed database fields, regardless of the user’s choice of operator (or the default operator, if relevant). In addition, these fields are visualized as editors rather than fill‑in fields, with their height and word‑wrap capabilities regulated by the Number of Lines in Editors property.
See the “String Operators pane” section for details on the BEGINS and CONTAINS properties. For details on the Number of Lines in Editors property, see the “Size & Position pane” section.
The Inline style supports wild cards, but only if you do not check the BEGINS property. There is one exception: a value that starts with a wild card always generates an expression with the Progress MATCHES keyword.
String Operators pane
You use these check boxes to specify certain overrides for the default filter styles, For details, see the “Style pane” section:
*BEGINS — If checked, this specifies the following:
*If the default filter style is Implicit, Progress uses the BEGINS operator for character fields instead of the implicit operator that you specify.
*If the default filter style is Inline, Progress uses BEGINS as the default operator for character fields. (The default operator is used when application users do not specify an operator.)
The BEGINS property is disabled for the Explicit and Range filter styles.
*CONTAINS — If this is checked, and the default filter style is Implicit, Range, or Inline, specifies that the AppBuilder uses CONTAINS as the operator for filter fields that are mapped to word‑wrapped database fields, regardless of the operator specified for that style. In addition, these fields are visualized as editors rather than fill‑in fields, with their height and word‑wrap capabilities regulated by the Number of Lines in Editors property. For details, see the “Size & Position pane” section.
Operator View as pane
You use this set of radio buttons to specify how the AppBuilder visualizes the operator selection provided when you select Explicit as the default filter style. For details, see the “Style pane” section:
*Combo-box — This visualizes the operator selection as a combo box.
*Radio-set — This visualizes the operator selection as a radio set.
These radio buttons are disabled if the default filter style is Implicit or Inline. They are enabled if the default filter style is Range, in case you choose to override the style for a specific field to Explicit with the Explicit operator property. For details, see the “Field Properties pane” section.
Size & Position pane
You use the instance properties in the Size & Position pane to define various aspects of filter fields:
*Width of Character Fields — This specifies the default width of character fields.
*Width of Other Fields — This specifies the default width of noncharacter fields.
*Column — this specifies the column position of all fields.
Note: This is the position of the actual field and not the label.
*Number of Lines in Editors — When you check the CONTAINS property (see the “String Operators pane” section), the AppBuilder visualizes certain filter fields as editors rather than fill‑in fields. This property specifies the number of lines to use for these editors. If you specify 1, the editor has the same height as fill‑in fields and word wrapping is disabled. If you specify 2, the editor shows two lines, word wrapping is enabled, and a vertical scroll bar appears.
View property
If checked (the default), the View check box makes the SmartFilter visible.
SmartFilter usage notes
This section discusses special programming considerations for using SmartFilters.
Filter link as pass‑through link
The Filter link that connects a SmartFilter and its data source can be implemented as a pass‑through link. This allows you to create a SmartFilter in a separate SmartWindow and wait to link it to the Filter‑target until you drop the SmartFilter’s SmartWindow into the Filter‑target’s SmartWindow.
You can start a SmartFilter that is in a separate SmartWindow from a SmartToolbar. Follow these general steps to do this:
1. Create a SmartFilter in a separate SmartWindow, specifying all necessary instance properties, and link it temporarily as a Filter‑source to THIS-PROCEDURE (the SmartWindow).
2. Drop this SmartWindow in a SmartWindow with a potential filter—a SmartDataObject that matches the SmartFilter—and answer Yes to the Link Advisor’s prompt about adding the Filter link to the SmartDataObject.
3. Optionally, specify HideOnInit and DisableOnInit in the SmartWindow’s instance properties dialog box and start the main SmartWindow.
4. Check the Filter check box in the SmartToolbar’s instance properties dialog box.
The SmartToolbar can now view and start the SmartFilter’s SmartWindow.