TcxCustomTreeView.OnAdvancedCustomDraw Event

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

Declaration

property OnAdvancedCustomDraw: TTVAdvancedCustomDrawEvent 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 cdPrePaint 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 value 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 control items will not be painted. You cannot paint them manually either, 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 cdPostPaint, the DefaultDraw parameter should not be used. No painting will take place.

Note

Handle the OnCustomDraw event to perform only background painting (when the Stage parameter value is cdPrePaint).

The Sender parameter of the event provides access to the underlying tree 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 X over the control’s client area.

procedure TForm1.cxTreeView1AdvancedCustomDraw(Sender: TCustomTreeView;
  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 code execution is as follows:

Important

Use the OnAdvancedCustomDraw event to paint the foreground of the control very carefully. When performing scrolling, the tree view control simply copies its canvas content and moves it up or down. After movement, the OnAdvancedCustomDraw event is raised again. If considering the example above, this can result in several red X’s painted one under another. Note that the same effect takes place if collapsing or expanding nodes. Other nodes can be moved as the result of the operation. Node movement is implemented in a similar manner – the portion of the canvas’ content is copied and moved to another position. Thus, if performing foreground painting, you need to be sure that end-users are not allowed to scroll the control and expand/collapse items.