Virtual Treeview - Paint cycles and stages

The most complex process in Virtual Treeview is without doubts its painting.

Read here what stages Virtual Treeview enters during paint and how you can customize this process.

Description

Similar to the system tree view Virtual Treeview defines so called paint cycles.

A paint cycle is one run of the paint code which draws a part or the entire window.

In Virtual Treeview this task is accomplished by the method PaintTree

which centralizes the paint management into one place and is called

for various tasks like window painting, drag image painting, WM_PRINTCLIENT handling and so on.

This paint method is able to draw the entire tree regardless of its window to the target canvas

and optimizes painting by considering the update/clipping rectangle,

which is passed in via the Window parameter (see also PaintTree).

Usually the following paint stages are executed during a paint cycle:

--> (OnBeforePaint)
    --> (OnBeforeItemPaint)
      --> (OnBeforeItemErase)
      --> (OnAfterItemErase)
      --> (OnBeforeCellPaint)
        --> (OnPaintText)
      --> (OnAfterCellPaint)
    --> (OnAfterItemPaint)
--> (OnAfterPaint) 

The cell and node events are of course not executed if there is no node to be drawn.

A special flag (tsPainting) in TreeStates indicates when a paint cycle is in progress.

Using this flag an application can for instance determine whether a node is initialized

because it is about to be drawn or for other reasons.

Every of the stages above is accompanied by a specific event

which allows the application to customize a particular aspect in the painting.

The following list discusses tasks which can be done during the various stages.

before paint

This stage is entered only once per paint cycle.
After setting the vsPainting state it is the very first instruction in a cycle.

This stage is typically used to do any further setup of the target canvas of the paint operation
(e.g. the window or a printer canvas), like changing the mapping mode or setting another clipping region.
Since the passed canvas is not directly used to do the actual painting setting its font or colors has no effect.
Basically only properties which affect blitting a bitmap to the target canvas have an effect at all.

before item paint

This stage is entered once per node to be drawn and allows directly
to control the path which is the taken to paint the node.

In the event for this stage you can tell the tree whether you want
to paint the node entirely on your own or let the tree paint it.
As this happens on a per node basis it is the perfect place
to maintain a special layout without doing everything in the paint cycle.
Note:
setting the CustomDraw parameter in the event to True will skip the node entirely,
without painting anything of the standard things like tree lines, button,
images or erasing the background.
Hence to display any useful information for the node do it in the OnBeforeItemPaint event.

This is the first stage which gets the double buffer canvas which is used to draw a node
so if you want to set special properties this is a good opportunity.
Keep in mind though that in particular the colors are
set by the tree according to specific rules (focus, selection etc.).

before item erase

This stage is also entered only once per node and allows to customize the node's background.

This stage and its associated event is usually used to give the node a different background color
or erase the background with a special pattern which is different to what the tree would draw.

after item erase

This stage is also entered only once per node.

This stage and its associated event is used
to do additional drawings after the background has been erased.

before cell paint

This paint stage is the first of the cell specific stages used to customize a single cell of a node and
is called several times per node, depending on the number of columns.

If no columns are used then it is called once.

While internally a full setup for this node happened
before the stage is entered (if it is the first run) the only noticeable effect
for the application which has changed compared to after item erase is that
the painting is limited to the current column.
There are still no lines or images painted yet.

on paint text

After default stuff like lines and images has been painted the paint node/paint text stage is entered.

Because Virtual Treeview does not know how to draw the content of a node
it delegates this drawing to a virtual method called DoPaintNode.
Descendants override this method and do whatever is appropriate.
For instance TVirtualDrawTree simply triggers its OnDrawNode event
while the TVirtualStringTree prepares the target canvas and
allows the application to override some or all canvas settings (font etc.)
by triggering OnPaintText.

After this event returned the text/caption of the node is drawn.
Changed font properties are taken into account when aligning and painting the text.

Note: The string tree triggers the OnGetText event two times
if toShowStaticText is enabled in the TVirtualStringTree.TreeOptions.StringOptions property.
Once for the normal text and once for the static text.
Use the event's parameter to find out what is required.

after cell paint

This stage is entered immediately after the cell is drawn.

This stage can be used to add whatever you like to a single cell
after everything has been painted there and is triggered once per column.

after item paint

This stage is entered after all cells of an item are drawn.

The after item paint stage is used to add node specific stuff like frames
and the like which concern all columns of that node and is called once per node.

after paint

The after paint stage is the last stage in the long chain of paint stages
and is entered after when paint cycle is complete.

In this stage everything of the tree (related to the current update area) has been drawn,
including the selection rectangle.