TcxCustomDataController.OnCompare Event

Allows you to implement a custom sorting algorithm.

Declaration

property OnCompare: TcxDataControllerCompareEvent read; write;

Remarks

You can handle the OnCompare event to implement custom sorting algorithms. For instance, you can group Null Variant record values and then sort remaining records according to their values.

Important

If your custom sorting algorithm is not thread-safe, make sure that multi-threaded calculations are disabled for data sort operations in the data controller.

To disable multi-threading for sort operations in the data controller, set the MultiThreadedOptions.Sorting property to bFalse.

Event Occurrence

The OnCompare event occurs every time the data controller compares values from two records in the same dataset field.

Event Parameters

V1 and V2 parameters allow you to identify two compared values while ARecordIndex1 and ARecordIndex2 parameters return their positions in the target dataset field.

To determine the result of a value comparison operation, assign one of the following values to the Compare parameter within an OnCompare event handler:

-1

V1 is less than V2

0

V1 and V2 are equal

1

V1 is greater than V2

Refer to the TcxDataControllerCompareEvent procedural type description for detailed information on parameters accessible within an OnCompare event handler.

Code Example: Implement a Custom Sorting Algorithm

The code example below demonstrates an OnCompare event handler that groups records with Null Variant values at the bottom regardless of the active sort order. The DefaultCompare function compares two values when they are not Null Variant.

Delphi

uses
  dxCore;
// ...
procedure TForm1.MyCompare1(ADataController: TcxCustomDataController;
ARecordIndex1, ARecordIndex2, AItemIndex: Integer; const V1, V2: Variant; var Compare: Integer);
const
  SortValueA: array [Boolean] of Integer = (-1, 1);
begin
  if VarType(V1) = varNull then
  begin
    if VarType(V2) = varNull then
      Compare := 0
    else
      Compare := SortValueA[ADataController.GetItemSortOrder(AItemIndex) = soAscending];
  end
  else
    if VarType(V2) = varNull then
      Compare := SortValueA[ADataController.GetItemSortOrder(AItemIndex) = soDescending]
    else
      Compare := ADataController.DefaultCompare(ARecordIndex1, ARecordIndex2, AItemIndex);
end;

C++

#include "dxCore.hpp"
// ...
void __fastcall TForm1::MyCompare1(TcxCustomDataController *ADataController, int ARecordIndex1,
int ARecordIndex2, int AItemIndex, const Variant &V1, const Variant &V2, int &Compare)
{
  const int SortValueA[2] = {-1, 1};
  if (VarType(V1) == varNull) {
    if (VarType(V2) == varNull) {
      Compare = 0;
    }
    else
      Compare = SortValueA[ADataController->GetItemSortOrder(AItemIndex) == soAscending];
  }
  else
  {
    if (VarType(V2) == varNull)
      Compare = SortValueA[ADataController->GetItemSortOrder(AItemIndex) == soDescending];
    else
      Compare = ADataController->DefaultCompare(ARecordIndex1, ARecordIndex2, AItemIndex);
  }
}