 |
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.
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:
- before paint (OnBeforePaint)
- before item paint (OnBeforeItemPaint)
- before item erase (OnBeforeItemErase)
- after item erase (OnAfterItemErase)
- before cell draw (OnBeforeCellPaint)
- on paint text (string trees only, OnPaintText)
- after cell draw (OnAfterCellPaint)
after item paint (OnAfterItemPaint) after paint (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.
|
Stage |
Description |
Comments |
|
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. |
|
What do you think about this topic? Send feedback!
|