TcxCustomGridTableView.OnCustomDrawCell Event

Allows you to override or complement built-in cell draw routines.

Declaration

property OnCustomDrawCell: TcxGridTableDataCellCustomDrawEvent read; write;

Remarks

You can handle the OnCustomDrawCell event to change the appearance of individual cells depending on specific conditions in your application.

Event Occurrence

The OnCustomDrawCell event occurs every time the grid View is about to draw a cell.

Important

Since the OnCustomDrawCell event may occur very often, its handler must not include time-consuming calculations. Otherwise, the resource-intensive custom draw routine may render the application UI slow and unresponsive.

If you need to rely on data-dependent conditions in an OnCustomDrawCell event handler, we recommend that you use only cached or pre-calculated values instead of complex calculations at the data controller or dataset level.

Event Parameters

The following parameters are available within an OnCustomDrawCell event handler:

Sender

Provides access to the grid Table View that raised the cell draw event.

ACanvas

Provides access to the processed cell’s canvas. You can call canvas draw routines accessible through this parameter to display custom cell content.

ViewInfo

Returns information required to draw the processed cell. For example, you can use the ViewInfo.Bounds field to identify the boundaries of the cell’s canvas.

ADone

Specifies if built-in cell draw routines are disabled. Assign True to this parameter within an OnCustomDrawCell event handler to implement the draw routine for the processed cell from scratch.

Refer to the TcxGridTableDataCellCustomDrawEvent procedural type description for detailed information on all available options.

Code Example

Built-in draw routines display a cell according to its content, active look & feel settings, and other grid View options that affect cell appearance and layout:

The code example in this topic section demonstrates an OnCustomDrawCell event handler that implements a custom draw routine for the Names grid column. This handler defines custom display text and changes cell background color depending on values in the Groups column.

How to Test this Code Example

Follow the steps below to test this code example in your RAD Studio IDE:

1. Copy the DFM code snippet below.
2. Create a new project in the IDE and focus an empty form.
3. Press Ctrl+V to populate the form with preconfigured components.
4. Select cxGrid1DBTableView1 in the TcxGrid on the form.
5. Create an empty OnCustomDrawCell event handler, paste the code example, and run the project.

DFM

object cxGrid1: TcxGrid
   Left = 72
   Top = 80
   Width = 545
   Height = 200
   TabOrder = 0
   object cxGrid1DBTableView1: TcxGridDBTableView
     Navigator.Buttons.CustomButtons = <>
     ScrollbarAnnotations.CustomAnnotations = <>
     OnCustomDrawCell = cxGrid1TableView1CustomDrawCell
     DataController.DataSource = DataSource1
     DataController.Summary.DefaultGroupSummaryItems = <>
     DataController.Summary.FooterSummaryItems = <>
     DataController.Summary.SummaryGroups = <>
     object cxGrid1DBTableView1RecId: TcxGridDBColumn
       DataBinding.FieldName = 'RecId'
       Visible = False
     end
     object cxGrid1DBTableView1Groups: TcxGridDBColumn
       DataBinding.FieldName = 'Groups'
     end
     object cxGrid1DBTableView1Names: TcxGridDBColumn
       DataBinding.FieldName = 'Names'
     end
     object cxGrid1DBTableView1Values: TcxGridDBColumn
       DataBinding.FieldName = 'Values'
       Width = 54
     end
   end
   object cxGrid1Level1: TcxGridLevel
     GridView = cxGrid1DBTableView1
   end
 end
 object dxMemData1: TdxMemData
   Active = True
   Indexes = <>
   Persistent.Data = {
     5665728FC2F5285C8FFE3F04000000140000000100070047726F757073001400
     0000010006004E616D657300040000000300070056616C756573000400000009
     000600446174657300010600000047726F75703101050000004E616D6531010A
     000000017B000B00010600000047726F75703101050000004E616D6532011400
     000001CF0E0B00010600000047726F75703201050000004E616D6533011E0000
     00017A210B00010600000047726F75703201050000004E616D65340128000000
     01892B0B00}
   SortOptions = []
   Left = 520
   Top = 88
   object dxMemData1Groups: TStringField
     FieldName = 'Groups'
   end
   object dxMemData1Names: TStringField
     FieldName = 'Names'
   end
   object dxMemData1Values: TIntegerField
     FieldName = 'Values'
   end
   object dxMemData1Dates: TDateField
     FieldName = 'Dates'
   end
 end
 object DataSource1: TDataSource
   DataSet = dxMemData1
   Left = 472
   Top = 176
 end

Delphi

procedure TMyForm.cxGrid1TableView1CustomDrawCell(Sender: TcxCustomGridTableView;
  ACanvas: TcxCanvas; AViewInfo: TcxGridTableDataCellViewInfo;
  var ADone: Boolean);
var
  AString: string;
  ARect: TRect;
begin
  if AViewInfo.Item.Caption = 'Names' then
  begin
    AString := AViewInfo.Item.Caption + ', Row ' + IntToStr(AViewInfo.GridRecord.Index);
    ARect := AViewInfo.Bounds;
    ARect.Left := ARect.Left + 5;
    ARect.Right := ARect.Left + ACanvas.TextWidth(AString);
    if AViewInfo.GridRecord.Values[cxGrid1DBTableView1Groups.Index] = 'Group1' then
      ACanvas.FillRect(AViewInfo.Bounds, clRed)
    else
      ACanvas.FillRect(AViewInfo.Bounds, clGreen);
    ACanvas.DrawTexT(AString, ARect, 0, True);
    ADone := True;  // Disables built-in cell draw routines
  end;
end;

C++

void __fastcall TMyForm::cxGrid1TableView1CustomDrawCell(TcxCustomGridTableView *Sender,
  TcxCanvas *ACanvas, TcxGridTableDataCellViewInfo *AViewInfo, bool &ADone)
{
  UnicodeString AString;
  TRect ARect;

  if(AViewInfo->Item->Caption == "Names")
  {
    AString = AViewInfo->Item->Caption + " Row " + IntToStr(AViewInfo->GridRecord->Index);
    ARect = AViewInfo->Bounds;
    ARect.Left = ARect.Left + 5;
    ARect.Right = ARect.Left + ACanvas->TextWidth(AString);
    if(AViewInfo->GridRecord->Values[cxGrid1DBTableView1Groups->Index] == "Group1")
      ACanvas->FillRect(AViewInfo->Bounds, clRed);
    else
      ACanvas->FillRect(AViewInfo->Bounds, clGreen);
    ACanvas->DrawTexT(AString, ARect, 0, true);
    ADone = true; // Disables built-in cell draw routines
  }
}

Important Limitations

Do not perform any operations at the dataset level within an OnCustomDrawCell event handler. These operations may move focus and send other notifications that can trigger an infinite loop.