TcxCustomListView.OnAdvancedCustomDraw Event

Enables you to paint the list view control (or a part of it) before or after default painting takes place.

Declaration

property OnAdvancedCustomDraw: TLVAdvancedCustomDrawEvent read; write;

Remarks

The OnAdvancedCustomDraw event fires at different stages of control painting. First it fires before any default painting is performed. Then it fires after all painting is finished. Use the Stage parameter to determine the stage of painting. It returns the cdPrePaint value if the event fires before any other painting. If the cdPostPaint value is returned, all painting procedures have already been finished. Note that the Stage parameter cannot return any other values listed by the TCustomDrawState enumeration.

The DefaultDraw parameter specifies whether default painting must proceed after the OnAdvancedCustomDraw event is executed. If handling the event when the Stage parameter is cdPrePaint, setting the DefaultDraw parameter to True prohibits all further painting. This means that items of the control will not be painted. You cannot paint them manually also in this case, since the OnCustomDrawItem and OnAdvancedCustomDrawItem events will not fire. Thus, you need to set the DefaultDraw parameter to True only when all the desired painting is performed in the OnAdvancedCustomDraw event and no further painting is needed.

When the Stage parameter returns the cdPostPaint value, the DefaultDraw parameter should not be used. No painting will take place afterwards anyway.

Note

If you need to perform only background painting (when the Stage parameter value is cdPrePaint), handle the OnCustomDraw event. This event fires twice as little times as the OnAdvancedCustomDraw event, which gives you a performance benefit.

The Sender parameter of the event provides access to the underlying list view control. Use the Canvas property of the object representing this parameter to obtain the canvas used to paint. The bounding rectangle of the control can be obtained using the ARect parameter.

The following sample code shows how to perform painting when all default painting routines are finished. The code handles the OnAdvancedCustomDraw event to paint a red cross over the control’s client area.

procedure TForm1.cxListView1AdvancedCustomDraw(Sender: TCustomListView; const ARect: TRect; Stage: TCustomDrawStage; var DefaultDraw: Boolean);
begin
  if Stage = cdPostPaint then
  begin
    with Sender.Canvas do
    begin
Pen.Color := clRed;
Pen.Style := psSolid;
Pen.Width := 3;
MoveTo(ARect.Left, ARect.Top);
LineTo(ARect.Right, ARect.Bottom);
MoveTo(ARect.Left, ARect.Bottom);
LineTo(ARect.Right, ARect.Top);
    end;
  end;
end;

The result of the code execution is demonstrated below: