| Control Name | Unit | Class |
| RX Database Filters | DBFilter | TRxDBFilter |
Description:
This component
implements a BDE-level filter, based on a callback into your
form's/unit's code. The TRxDBFilter component allows you to
specify one or more record selection criteria to be used when
displaying data from a table or query (TTable, TQuery, TQBEQuery or TRxQuery components). Filter criteria can be specified for
any number of fields in a table, giving you more flexibility than
Delphi's built-in Range operators and some advantages over
performing a single-table query.
You can specify one or more lines of filter criteria in Filter property to be used when displaying data from the associated table or query. The default value is blank - no filter defined. Applications can also specify a filter using the OnFiltering event handler. The Filter property supplements the OnFiltering event handler. Be sure that the interactions between the Filter property and the OnFiltering event handler do not result in an empty filter set when they are used simultaneously in an application.
Delphi 2.0 and 3.0 TTable and TQuery components has a similar property named Filter, which has similar functionality. However Delphi 2.0 is for 32 bit applications only. We recommend you use Delphi’s filtering if you are developing 32-bit only applications, but use TRxDBFilter if you need to simultaneously support both 16 and 32 bit. You can also use same data-aware controls (i.e. TDBEdit, TDBCheckBox etc) to display and edit dataset's records and to enter filter's selection criteria. Use SetCapture, ReleaseCapture and ReadCaptureControls methods to enable users to enter selection criteria into data-aware controls at runtime.
Property
Active
Declaration:
Active: Boolean;
Specifies whether filtering is active for a dataset. Check Active to determine whether or not dataset filtering is in effect. If Active is True, then filtering is active. Otherwise Active is False. To apply filter conditions specified in the Filter property or the OnFiltering event handler, set Active to True (or call Activate method). When filtering is enabled, user edits to a record may mean that the record no longer meets a filter’s test condition. The next time the record is retrieved from the dataset while the filter is in effect, the record may seem to disappear. If that happens, the next record that passes the filter condition becomes the current record.
Property
Captured
Declaration:
Captured: Boolean;
Captured (runtime and read-only) indicates whether the filter has 'captured' data-aware controls assosiated with filtered dataset (specified by DataSource property).
A data-aware controls becomes the "captured controls" when the TRxDBFilter calls SetCapture method.
To release captured controls application must call the ReleaseCapture method. When data-aware controls are captured by the filter, the dataset's Post method calls the ReadCaptureControls; ReleaseCapture; Activate; methods and sets the filter by using the entered values; the dataset's Cancel method releases controls by calling ReleaseCapture; method.
Property
ExprFilter
Declaration:
ExprFilter: hDBIFilter;
Specifies the Borland Database Engine (BDE) filter handle for the filter, which use the Filter property.
Property
Filter
Declaration:
Filter: TStringList;
Specifies the text of the current filter for a dataset. Use Filter to specify a dataset filter. When filtering is applied to a dataset (by setting the Active property to True or calling Activate method), only those records that meet a filter’s conditions are available to an application. Filter contains the string that describes the filter condition. For example, the following filter condition displays only those records where the customer number greather then 1000 and customer name starts with 'A' character: (( Cust_No > 1000) OR ([Customer Name] < 'B')) The following conditions are also available: State = 'CA' or Pay = NULL or [Date] > '12/01/1995'. To filter strings bases on partial comparisons, use an asterisk as a wildcard. For example: State = 'M*' The following unary operations available in a filter expressions: = NULL <> NULL
The following binary operations
available in a filter expressions:
__<> (not equal)
__>= (great or equal)
__<= (less or equal)
__= (equal)
__> (great)
__< (less)
Applications can set Filter at runtime to change the filtering
condition for a dataset at (for example, in response to user
input).
Property Filter example
with rxDBFilter1.Filter do
begin
__BeginUpdate;
__try
____Clear;
____Add('((Cust_No > 1000) OR');
____Add('([Customer Name] <= ''B'')) AND
(State = ''CA'')');
__finally
____EndUpdate;
__end;
end;
rxDBFilter1.Active := True;
Property
FuncFilter
Declaration:
FuncFilter: hDBIFilter;
Specifies the Borland Database Engine (BDE) filter handle for the filter, which use the OnFiltering event handler.
Property
LogicCond
Declaration:
LogicCond: TFilterLogicCond;
The LogicCond property specifies a logical operator which used to create selection criteria with the ReadCaptureControls method. The valid values for LogicCond are flAND or flOR. If LogicCond is flAND, all simple filter conditions which has been read from data-aware controls, combines with "AND" logical operator. If LogicCond is flOR, the "OR" logical operator used to combine filter conditions into selection criteria (Filter property).
Property
Options
Declaration:
Options: TDBFilterOptions;
Options lets you fine-tune the filtering provided by the Filter property. The TFilterOptions type defines the possible values for the Options property, as described below:
- foCaseInsensitive - The filter is processed without regard to case in the dataset's data.
- foNoPartialCompare - String matches must be exact over the length of the data in the dataset; partial matches aren't allowed.
Property
Priority
Declaration:
Priority: Word;
Priority determines the filter's priority relative to other filters on the same dataset.
Event
OnActivate
Declaration:
OnActivate: TNotifyEvent;
The OnActivate event is activated after a filter is activated, either by calling the Activate method or by setting the Active property to True. By assigning a method to this property, you can take any special actions required by the event.
Event
OnDeactivate
Declaration:
OnDeactivate: TNotifyEvent;
The OnDeactivate event is activated after a filter is deactivated, either by calling the Deactivate method or by setting the Active property to False.
By assigning a method to this property, you can take any special actions required by the event.
Event
OnFiltering
Declaration:
OnFiltering: TFilterEvent;
OnFiltering occurs each time a different record in the dataset becomes the current record and filtering is enabled. Write an OnFiltering event handler to test each record in a dataset for against a test condition that determines whether or not the record is visible to the application. To indicate whether or not a record passes the filter condition, a filter handler must return True to include a record, or False to exclude it.
Applications can also specify a filter using the Filter property. The Filter property supplements the OnFiltering event handler. Be sure that the interactions between the Filter property and the OnFiltering event handler do not result in an empty filter set when they are used simultaneously in an application.
Event OnFiltering example
procedure TForm1.RxFilterOnFiltering(Sender: TObject;
DataSet: TDataSet): Boolean;
begin
__if
(AnsiUpperCase(DataSet.FieldByName('Cust_Name')) = 'Smith') or
__ _((DataSet.FieldByName('Rate') > 0.5) and
(DataSet.FieldByName('Rate') < 0.95)) __then
____Result := True
__else
____Result := False;
end;
Event
OnReleaseCapture
Declaration:
OnReleaseCapture: TNotifyEvent;
The OnReleaseCapture event is activated when a data-aware controls, previously captured by the filter, is released by calling the ReleaseCapture method. By assigning a method to this property, you can take any special actions required by the event.
Event
OnSetCapture
Declaration:
OnSetCapture: TNotifyEvent;
The OnSetCapture event is activated when a filter captures the data-aware controls assosiated with filtered dataset, by calling the SetCapture method. By assigning a method to this property, you can take any special actions required by the event.
Method
Activate
Declaration:
procedure Activate;
Activate filter for a dataset. It is equivalent to setting the Active property to True.
Method
Deactivate
Declaration:
procedure Deactivate;
Deactivate filter for a dataset. It is equivalent to setting the Active property to False.
Method ReadCaptureControls
Declaration:
procedure ReadCaptureControls;
You can use same data-aware controls (i.e. TDBEdit, TDBCheckBox etc) to display and edit dataset's records and to enter filter's selection criteria. Use SetCapture, ReleaseCapture and ReadCaptureControls methods to enable end-users to enter selection criteria into data-aware controls at run-time.
SetCapture method "captures" data-aware controls linked to a same datasource as TRxDBFilter component and allows user to enter data into these controls as selection criteria (without change the state of a dataset). You can read entered data by calling ReadCaptureControls method. This method reads selection criteria from data-aware controls captured by the filter component and fills the its Filter property by values readed. The single ctiteries combines into Filter property by using AND or OR logic operation according to LogicCond property value. After entering and reading selection criteria you MUST return data-aware controls to its normal state by calling ReleaseCapture method.
Method
ReleaseCapture
Declaration:
procedure ReleaseCapture;
You can use same data-aware controls (i.e. TDBEdit, TDBCheckBox etc) to display and edit dataset's records and to enter filter's selection criteria. Use SetCapture, ReleaseCapture and ReadCaptureControls methods to enable end-users to enter selection criteria into data-aware controls at run-time.
After using SetCapture method to entering selection criteria into data-ware controls and reading this criteria by ReadCaptureControls method you MUST return data-aware controls into its normal state by calling ReleaseCapture method.
Calling ReleaseCapture triggers the OnReleaseCapture event handler if one is defined for the TRxDBFilter component.
Method
SetCapture
Declaration:
procedure SetCapture;
You can use same data-aware controls (i.e. TDBEdit, TDBCheckBox etc) to display and edit dataset's records and to enter filter's selection criteria. Use SetCapture, ReleaseCapture and ReadCaptureControls methods to enable end-users to enter selection criteria into data-aware controls at run-time. SetCapture method "captures" data-aware controls linked to a same datasource as TRxDBFilter component and allows user to enter data into these controls as selection criteria (without change the state of a dataset). You can use entered data by calling ReadCaptureControls method. After entering and reading selection criteria you must return data-aware controls to its normal state by calling ReleaseCapture method. Calling SetCapture triggers the OnSetCapture event handler if one is defined for the TRxDBFilter component.
Method
Update
Declaration:
procedure Update;
The Update method reset the filter on the filtered dataset.
Method
UpdateFuncFilter
Declaration:
procedure UpdateFuncFilter;
Update resets the callback-filter on the filtered dataset. This method must be called when you change the conditions in OnFiltering event handler at runtime.
Type
EFilterError
Declaration:
EFilterError = class(Exception);
The EFilterError type is the exception type raised when an error is detected by the TRxDBFilter component.
Type
TDBFilterOption
Declaration:
TDBFilterOption = (foCaseInsensitive, foNoPartialCompare);
The TFilterOptions type defines the possible values for the Options property of the TRxDBFilter component.
Type
TDBFilterOptions
Declaration:
TDBFilterOptions = set of TDBFilterOption;
The TFilterOptions type defines the possible values for the Options property of the TRxDBFilter component.
Type
TFilterEvent
Declaration:
TFilterEvent = function (Sender: TObject; DataSet: TDataSet) :
Boolean of object;
The TFilterEvent type points to a method that responds to an OnFiltering event of the TRxDBFilter component, for including or excluding records from being visible in a dataset.
Type
TFilterLogicCond
Declaration:
TFilterLogicCond = (flAnd, flOr);
The TFilterLogicCond type defines the possible values for the LogicCond property of the TRxDBFilter component.
Routine
DropAllFilters
Declaration:
procedure DropAllFilters(DataSet: TDataSet);
DropAllFilter drops the all filters on the specified DataSet and frees all resources associated with the filters.
DropAllFilters example:
begin
__...
__DropAllFilters(Query1);
end;
Index Page | About | Download
Creation Date: 4 Feb 1998 | Last Update: 16 Mar 2000