@@PaintCycles.htm Similar to the system tree view Virtual Treeview defines so called <B>paint cycles</B>. 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. <TABLE> Stage \Description Comments ----------------- ----------------------------- ------------------------------------------------------------------------------------------ before paint This stage is entered only This stage is typically used to do any further setup of the target canvas of the paint \once per paint cycle. After \operation (e.g. the window or a printer canvas), like changing the mapping mode or setting the vsPainting state setting another clipping region. Since the passed canvas is not directly used to do the it is the very first actual painting setting its font or colors has no effect. Basically only properties which instruction in a cycle. affect blitting a bitmap to the target canvas have an effect at all. before item This stage is entered once In the event for this stage you can tell the tree whether you want to paint the node paint per node to be drawn and entirely on your own or let the tree paint it. As this happens on a per node basis it is allows directly to control the perfect place to maintain a special layout without doing everything in the paint the path which is the taken cycle. Note: setting the CustomDraw parameter in the event to True will skip the node to paint 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.<P> <P> 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 This stage is also entered This stage and its associated event is usually used to give the node a different erase \only once per node and background color or erase the background with a special pattern which is different to allows to customize the what the tree would draw. node's background. after item erase This stage is also entered This stage and its associated event is used to do additional drawings after the \only once per node. background has been erased. before cell This paint stage is the While internally a full setup for this node happened before the stage is entered (if it paint first of the cell specific is the first run) the only noticeable effect for the application which has changed stages used to customize a compared to <B>after item erase</B> is that the painting is limited to the current single cell of a node and is column. There are still no lines or images painted yet. called several times per node, depending on the number of columns. If no columns are used then it is called once. \on paint text After default stuff like Because Virtual Treeview does not know how to draw the content of a node it delegates lines and images has been this drawing to a virtual method called DoPaintNode. Descendants override this method and painted the paint node/paint do whatever is appropriate. For instance TVirtualDrawTree simply triggers its OnDrawNode text stage is entered. 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.<P> <B>Note: </B>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 This stage can be used to add whatever you like to a single cell after everything has immediately after the cell been painted there and is triggered once per column. is drawn. after item paint This stage is entered after The after item paint stage is used to add node specific stuff like frames and the like all cells of an item are which concern all columns of that node and is called once per node. drawn. after paint The after paint stage is the In this stage everything of the tree (related to the current update area) has been drawn, last stage in the long chain including the selection rectangle. \of paint stages and is entered after when paint cycle is complete. </TABLE> Summary 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.