Skip to main content

DevExpress v24.2 Update — Your Feedback Matters

Our What's New in v24.2 webpage includes product-specific surveys. Your response to our survey questions will help us measure product satisfaction for features released in this major update and help us refine our plans for our next major release.

Take the survey Not interested

TcxGridTableDataCellCustomDrawEvent Type

The procedural type for grid cell draw events.

#Declaration

Delphi
TcxGridTableDataCellCustomDrawEvent = procedure(Sender: TcxCustomGridTableView; ACanvas: TcxCanvas; AViewInfo: TcxGridTableDataCellViewInfo; var ADone: Boolean) of object;

#Parameters

Name Type Description
Sender TcxCustomGridTableView

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

To access all public API members, cast the Sender parameter value to the corresponding terminal TcxCustomGridTableView class descendant.

Tip

You can call the Sender.ClassType function to identify the actual grid View type.

ACanvas TcxCanvas

Provides access to the canvas of the target grid cell.

You can call draw methods accessible through the ACanvas parameter to display custom content in the processed cell. Use the ViewInfo parameter to obtain additional information required to draw cell content, such as cell boundaries.

AViewInfo TcxGridTableDataCellViewInfo

Returns information required to identify and draw the processed cell.

Use AViewInfo.Item and AViewInfo.GridRecord properties to identify the position of the processed cell in the parent grid View. To obtain calculated cell boundaries, use the AViewInfo.Bounds field.

ADone Boolean
False
Default. Built-in draw routines display the processed cell according to active skin and appearance settings.
True
Built-in draw routines are disabled for the processed cell. Use this option if you need to draw a cell from scratch.

#Remarks

A cell custom draw event occurs every time the grid View is about to draw a cell. You can handle this event to change the appearance of individual cells depending on specific conditions in your application.

Important

Since custom draw events can be frequent, their handlers should avoid time-consuming calculations to prevent slowing down the application’s UI.

If you need to rely on data-dependent conditions in a custom draw event handler, we strongly recommend that you use only cached or pre-calculated values rather than time-consuming calculations at the data controller or dataset level.

#Code Example: Change Cell Appearance Depending on Values

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:

VCL Data Grid: A Grid Table View with Built-In Draw Routines

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.
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
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;

VCL Data Grid: A Custom-Drawn

#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.

#Direct TcxGridTableDataCellCustomDrawEvent Type References

The following events reference the TcxGridTableDataCellCustomDrawEvent procedural type:

TcxCustomGridTableItem.OnCustomDrawCell
Occurs every time a table or card cell is about to be drawn.
TcxCustomGridTableView.OnCustomDrawCell
Allows you to override or complement built-in cell draw routines.
See Also