Custom Draw
- 4 minutes to read
The Custom Draw feature provides unlimited customization facilities for the grid control’s look and feel. As this feature is event-based, you have to handle events and implement some code. You may use Styles instead for simplicity and to avoid coding, but this obviously reduces flexibility.
How a Custom Draw Event Works
Each custom draw event provides a set of parameters which supply the information needed for drawing each type of grid View element.
The Sender parameter specifies the grid element to be repainted. Usually it is the grid element that owns this event. The following table lists all available custom draw events and their owners:
Event | Description |
|---|---|
Allows a band header of the Banded Table View to be custom drawn. Applies to: | |
OnCustomDrawFooterCell (TcxGridColumn.OnCustomDrawFooterCell and TcxGridTableView.OnCustomDrawFooterCell) | Allows a footer cell of the Table View to be custom drawn. Applies to: |
Allows a column header of the Table View to be custom drawn. Applies to: | |
Allows a column header of the Table View to be custom drawn. Applies to: | |
Allows View elements such as footers, group footers, filter panels and the Group By box to be custom drawn. Applies to: | |
OnCustomDrawCell (TcxCustomGridTableItem.OnCustomDrawCell and TcxCustomGridTableView.OnCustomDrawCell) | Allows a grid View cell to be custom drawn. Applies to: |
Allows a group row to be custom drawn. Applies to: | |
OnCustomDrawGroupSummaryCell (TcxGridColumn.OnCustomDrawGroupSummaryCell and TcxGridTableView.OnCustomDrawGroupSummaryCell) | Allows a group summary to be custom drawn. Applies to: |
Allows a row indicator to be custom drawn. Applies to: | |
OnCustomDrawLegend (TcxGridChartDiagram.OnCustomDrawLegend and TcxGridChartView.OnCustomDrawLegend) | Allows a chart legend to be custom drawn. Applies to: |
OnCustomDrawLegendItem (TcxGridChartDiagram.OnCustomDrawLegendItem and TcxGridChartView.OnCustomDrawLegendItem) | Allows a legend item to be custom drawn. Applies to: |
Allows a chart’s plot area to be custom drawn. Applies to: | |
OnCustomDrawValue (TcxGridChartDiagram.OnCustomDrawValue and TcxGridChartSeries.OnCustomDrawValue) | Allows a chart value (also called a data marker) to be custom drawn. Applies to: |
Allows a chart’s value area (a constituent part of the data markers in area diagrams) to be custom drawn. Applies to: | |
Allows a series site‘s area to be custom drawn. Applies to: | |
Allows a series site‘s caption area to be custom drawn. Applies to: |
The ViewInfo object, which contains all the information required for painting each element, is passed via the ViewInfo parameter. Many ViewInfo properties are only needed by the grid’s internal structure, so you can ignore them. The most useful ViewInfo properties are:
Bounds property. Determines the bounding rectangle of the repainted grid element. Each custom draw event provides a grid control canvas represented by the ACanvas parameter. As the ACanvas parameter refers to the whole grid control canvas, you should use the AViewInfo.Bounds property to determine the position and size of the current grid element. The rectangle contained within this property determines the top-left and bottom-right corners of the element within the grid control via the Bounds.Top, Bounds.Left, Bounds.Bottom, and Bounds.Right fields correspondingly.
Params property. Contains a set of fields that determine the painted element style. With the Params.Color, Params.TextColor, and Params.Font fields, you can specify the background color, text color (if any), and the font (a TFont object) applied to the grid element.
DisplayValue property (ReadOnly) – Specifies the value that is displayed by the element.
The ACanvas parameter provides the canvas where the element is painted. Remember that the ACanvas property provides the whole canvas of the grid control. So you should use the AViewInfo.Bounds property to determine the bounding rectangle for the repainted element. Although ACanvas is of the TcxCanvas type, it publishes all the most useful canvas methods. If you want to access the standard VCL canvas, you should use the ACanvas.Canvas property.
The ADone parameter determines whether an event handler completely draws an appropriate element. If ADone is True, the default draw procedure is not called.