TcxCustomDataSource Class

A custom data source for a grid control.

Declaration

TcxCustomDataSource = class(
    TObject
)

Remarks

This class provides the base functionality to implement a user-defined data source. You can inherit your data source from TcxCustomDataSource to force your grid to display arbitrary data. To do so, several methods must be overridden. As a rule, you have to implement your custom data source when it is necessary to display information from an aggregate data structure within a grid control (for instance, a tree structure, a cluster of linked objects, a list, etc.). To set a custom data source for a grid control, use the CustomDataSource property. When a data controller retrieves data from a custom data source it is operating in provider mode.

The main methods that you should override are GetRecordCount, GetValue, SetValue, InsertRecord, AppendRecord and DeleteRecord.

The GetRecordCount method returns the number of records the grid control should display. The GetValue and SetValue methods enable the retrieving and setting of the values for the specified record and item (column). Other methods are called by the data controller, when a user inserts, appends, and deletes a specific record.

Read the following notes carefully to understand the most important issues when implementing a custom data source.

Let’s consider a structure of objects, each of which contains several fields (for instance, ID and Name) to be displayed in a grid control.

Every field is displayed in a separate column. The first issue is that you have to uniquely identify these columns. The item index (the visible index of a column) can be used as an item handle (a value that uniquely identifies a column) only if a user does not change column order. By default the TcxCustomDataSource class does not solve the problem of changing column order: the GetItemHandle method simply returns the passed item index as an item handle. To solve this problem in a derived class you have to override the GetItemHandle method.

You can use the column’s DataBinding.Data property to recognize a column. For instance, you can use this property as you wish to set a unique value (integer, pointer or some other).

Delphi

with AGridTableView do
  begin
    with CreateColumn as TcxGridColumn do
      begin
        //...
        Caption := 'ID';
        DataBinding.Data := Pointer(0);
      end;
    with CreateColumn as TcxGridColumn do
      begin
        //...
        Caption := 'Name';
        DataBinding.Data := Pointer(1);
      end;
    //...
  end;

C++

TcxGridColumn *AColumn = (TcxGridColumn *)(AGridTableView -> CreateColumn());
AColumn -> Caption = "ID";
AColumn -> DataBinding -> Data = Pointer(0);
//...
AColumn = (TcxGridColumn *)(AGridTableView -> CreateColumn());
AColumn -> Caption = "Name";
AColumn -> DataBinding -> Data = Pointer(1);
//...

You can retrieve an item handle by reading a value of the TcxGridColumn.DataBinding, or TcxGridColumn.DataBinding.Data property in the GetItemHandle method.

Delphi

function TUserDataSource.GetItemHandle(AItemIndex: Integer): TcxDataItemHandle;
var GridColumn: TcxCustomGridTableItem;
begin
  GridColumn := TcxCustomGridTableItem(DataController.GetItem(AItemIndex));
  Result := TcxDataItemHandle(GridColumn.DataBinding);
end;

C++

void* __fastcall TUserDataSource::GetItemHandle(int AItemIndex) {
  TcxCustomGridTableItem *GridColumn = (TcxCustomGridTableItem*) DataController->GetItem(AItemIndex);
  return GridColumn->DataBinding;
}

An item handle retrieved by GetItemHandle is passed to the GetValue, GetInfoForCompare and GetDisplayText methods. It identifies the actual column required for data returned from the corresponding field of an object.

The second issue relates to record manipulations: they must also be uniquely identified. The record index is the visible position of a record. Since sorting records can change their record indexes they cannot be used as identifiers, but every record in a grid control has a record handle which is used as a unique identifier. Before data is obtained from a custom data source for the first time, the data controller invokes the GetRecordHandle method for each record in the custom data source and stores the record handle retrieved. By default, GetRecordHandle simply returns the passed record index as a record handle.

The following image displays record indexes and record handles before and after sorting in descending order.

You can override the default behavior of the GetRecordHandle method and provide, for instance, pointers to specific objects as record handles.

Inheritance

TObject

TcxCustomDataSource