Selecting Records
- 4 minutes to read
This section relates to selecting records programmatically. Focused and selected records are discussed in the Focused/Selected Records topic.
If the View’s OptionsSelection.MultiSelect property is set to False, only one record (row in a (Banded) Table View or card in a Card View) can be selected at a time. This record is said to be focused. Focusing a record automatically selects it.
You can use the following code to focus and select the first record within the tvFilms View at the same time:
If the View’s OptionsSelection.MultiSelect property is set to True, you are able to select multiple records at once. When this option is enabled and an end-user clicks any record, it becomes focused and selected at the same time. The focused record can be deselected by clicking it while holding down the Ctrl key. Furthermore, when the View’s OptionsBehavior.PullFocusing property is set to True an end-user can select records by holding down the left mouse button whilst dragging the mouse pointer over the records to be selected. This automatically focuses the records under the cursor and adds them to the selection.
To select/deselect multiple records, you can use one of the following methods:
- the Selected property of a record object.
The following code navigates the Orders dataset displayed by the tvOrders View and selects records which have a payment amount greater than 100000. To navigate the dataset, we use a TDataSet object’s First and Next methods, which move focus through the records in the dataset. The currently focused record is accessed via the View’s Controller.FocusedRecord property.
Note that this code works correctly in the following cases:
When grid mode is applied (the View’s DataController.DataModeController.GridMode property is set to True)
When synchronization between a grid control and a TDataSet object is enabled (the View’s DataController.DataModeController.SyncMode property is set to True) and grouping is not used.
var
AView: TcxGridDBTableView;
//...
AView := tvOrders;
AView.OptionsSelection.MultiSelect := True;
AView.Controller.ClearSelection;
with AView.DataController.DataSet do
begin
First;
while not EOF do
begin
if FieldValues['PaymentAmount'] > 100000 then
AView.Controller.FocusedRecord.Selected := True;
Next;
end;
end;
- the ChangeRowSelection method of the View’s data controller
This method changes the selection state of a given row. The row is addressed by the method’s ARowIndex parameter which specifies the row index (visual position of a row within a View). Using row indexes you can access both group and data rows. Rows hidden under collapsed groups are not indexed.
The following code selects the records within the tvCustomers View based on the Customer field’s value. The Customer field is a string field and it is displayed by the tvCustomersCustomer column. We need to select the records which have their Customer field’s value set to ‘Y’.
To get the row index for a given record index, we use the GetRowIndexByRecordIndex method of the View’s data controller. Its first parameter specifies a record index and the second parameter specifies whether the record should be made visible if it is hidden under a collapsed group row. We need to set the second parameter to True to ensure that the required record is visible thus enabling its selection.
You should use this code only when grid mode is not applied (the View’s DataController.DataModeController.GridMode property is set to False). In grid mode, you will not be able to process all the records using the following code. To navigate records in grid mode, use the members of your TDataSet object (First, Last, Next, Prior and MoveBy).
var
I: Integer;
//...
tvCustomers.OptionsSelection.MultiSelect := True;
with tvCustomers.DataController do
begin
ClearSelection();
for I := 0 to RecordCount - 1 do
begin
if Values[I, tvCustomersCustomer.Index] = 'Y' then
ChangeRowSelection(GetRowIndexByRecordIndex(I, True), True);
end;
end;
- the SelectRows method of the View’s data controller
This method allows a continuous range of records to be selected. Two parameters specify the starting and ending row indexes of the required range.
The next code selects rows 0-5 within the tvOrders View:
- the SelectAll method of the View’s data controller
This method selects all the records, which are visible or potentially visible by scrolling, within a View. Records hidden within collapsed group rows are not selected.