TcxCustomDataController.FindRecordIndexByText(Integer,Integer,string,Boolean,Boolean,Boolean) Method

Returns the record index of the record matching the supplied text within a particular field.

Declaration

function FindRecordIndexByText(AStartRecordIndex: Integer; AItemIndex: Integer; const AText: string; APartialCompare: Boolean; ACircular: Boolean; AForward: Boolean): Integer; overload; virtual;

Parameters

Name	Type
AStartRecordIndex	Integer
AItemIndex	Integer
AText	string
APartialCompare	Boolean
ACircular	Boolean
AForward	Boolean

Returns

Type
Integer

Remarks

This function returns the record index of the first record that contains a field value matching the specified AText. This can be used to implement incremental search functionality, i.e. to locate specific records by text they contain. The record index retrieved by the function can be used, for instance, to focus a record by the FocusedRecordIndex property.

If a record containing specified text couldn’t be found, the function returns -1.

FindRecordIndexByText iterates records matching the current filter criteria. The search starts from the record addressed by the AStartRecordIndex parameter, which specifies the record index (the record’s position in the data source).

The search is performed against the item specified by the AItemIndex parameter. In the ExpressQuantumGrid control, you can use the TcxCustomGridTableItem.Index property value for this parameter.

The AForward parameter determines the search direction. It specifies whether to search forwards or backwards.

Setting the ACircular parameter to True ensures that the search will cycle when reaching the first record (if AForward is False) and the last record (if AForward is True). If ACircular is False, the search stops once it reaches these records.

The function compares strings without case sensitivity. The APartialCompare parameter allows you to specify whether the text being searched must match the display text of a field partially or entirely. If APartialCompare is True, the function is successful if the search text matches the starting characters of the field text. If APartialCompare is False, strings to compare must be identical.

In the ExpressQuantumGrid, you can use the View’s Controller.IncSearchingText property to start the incremental search.

Note

Do not call the FindRecordIndexByText method within the BeginUpdate/EndUpdate and BeginFullUpdate/EndFullUpdate blocks.