TreeControl Module

The tree control is a system level tool in VTS. The TreeControl module implements a tree control similar to that employed by the Microsoft Windows Explorer folder panel.

The format for the TreeControl module is:

TreeControl(&Tree)

where &Tree is a reference to the tree to be displayed.

The caller (not the parent) can provide the following subroutine modules that will be called by TreeControl in response to specific events:

OnLeftClick(Node, X, Y) 

Called when the left mouse button is released over a tree node. Node is the tree node, while X and Y are the coordinates of the mouse.

OnRightClick(Node, X, Y) 

Called when the right mouse button is released over a tree node. Node is the tree node, while X and Y are the coordinates of the mouse.

OnDoubleClick(Node, X, Y) 

Called when the left mouse button is double-clicked over a tree node. Node is the tree node, while X and Y are the coordinates of the mouse. This callback is always proceeded by OnLeftClick() and any node expansion is done prior to calling OnDoubleClick(), but after OnLeftClick().

CreateSubtree(Node) 

Called when a tree node has its TIF_CANEXPAND flag set, but the TI_SUBTREE member of the node has not yet been constructed. The callee is expected to construct an array of nodes and store them in the node supplied to CreateSubtree.

ExpandTreeToNode(Key) 

A sort of superset of CreateSubtree. It is called in response to a call to SetSelected() to command the caller of TreeControl to make all the tree nodes necessary to allow the node containing the Key to be expanded. The caller of TreeControl should call ExpandNode as needed for each node. When this callback returns, the tree will be positioned at the node that contains Key.

 The (rough) logic of ExpandTreeToNode is:

 Recursively walk up the tree by recursing this subroutine until we get to the tree root. The reverse recursion path is the shortest route from the root back to the node. Unwind the recursion, creating subtrees as necessary and calling ExpandNode() for any that are not expanded.

 Clicking on the junction is handled internally, and no callback is made.

 

The array that is passed in describes the tree structure. The array must be a 2-dimensional array, with each row (first subscript) describing a node at the same level in the tree. Each field in the row describes the node further:

[n][TI_KEY] 

The Key value is user-defined, and must be a value for which the == operator is meaningful. The Key value is used to identify which node the caller is talking about when calling helper subroutines.

[n][TI_TEXT] 

This is the text value displayed. It can be any VTS value that has a valid textual representation.

[n][TI_SUBTREE] 

This is a reference to an array of subordinate nodes that are of the same format as this node.

[n][TI_FLAGS] 

Flag values are used internally.

[n][TI_ICON] 

ICON graphic for the node (a folder graphic by default).

[n][TI_TOOLTIP] 

Additional tooltip for the node (none by default).

You can have each row with as many elements as you wish, but the above indices are reserved and must be present in all nodes. The "structured" Tree array provided can be modified at any time, and the TreeControl will faithfully follow it. You can call Refresh() at any time to invoke a full rebuild of the tree.