TreeControl

(System Library)

Description	Implements a tree control similar to that used by the Microsoft Windows Explorer folder panel.
Returns	Reference to self(). Tree control is ready when return value is valid.
Usage	Steady State only.
Function Groups	Graphics
Related to:	DropTree | GridList | ImportAPI
Format	System.TreeControl(Tree[, GrayOutTextParm, EnableKeyboardControl, NodeCallBackScope, NodeCallBackName, LeftParm, BottomParm, RightParm, TopParm, BackColorParm, TextColorParm, RowHeight)
Parameters

Tree

Required. Pointer to a structure defining the tree to be displayed. See comments for the structure definition.

GrayOutTextParm

Optional Boolean. True to gray-out text. Default:FALSE

EnableKeyboardControl

Optional Boolean. True to enable keyboard control. Default:FALSE

NodeCallBackScope

Optional object reference. The scope in which to find the callback module. See comments.

NodeCallBackName

Optional text. Name of the callback module for drawing.

LeftParm

Optional numeric. Will default to window dimensions

BottomParm

Optional numeric. Will default to window dimensions

RightParm

Optional numeric. Will default to window dimensions

TopParm

Optional numeric. Will default to window dimensions

BackColorParm

Optional background color.

TextColorParm

Optional text color.

RowHeight

Optional numeric to override the row height.

Comments:

The first parameter describes the tree structure. The structure 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.

Structure definition:

    NodeStruct Struct [
      Key             { The Key value is user-defined, and must be a value for 
                         which the == operator is meaningful. It identifies 
                         which node the caller refers to when calling helper 
                         subroutines.                                           };
      Label           { Text value displayed. It can be any VTScada value that 
                         has a valid textual representation.                    };
      SubTree         { This is a reference to an array of subordinate nodes 
                         that are of the same format as this node.              };
      MapIdx          { MapArray entry index.                                   };
      Flags           { Various flags... definitions follow                     };
      Icon            { ICON graphic for the node. Defaults to Folder icon.     };
      Tooltip         { Tooltip text. Defaults to blank.                        };
      Data            { Custom data managed by caller                           };
    ];

For legacy applications, you may continue to use the constants shown in the following table for the tree array. Used this way, the array must be two dimensional, with each row (first subscript) describing a node at the same level in the tree. Each field in the row describes the node further. The first six fields must be the following. Additional fields may be added as needed. In the following table, [n] refers to the row number and #TI_xxx refers to a defined constant within the TreeControl module. These constants are:

• [n][#TI_KEY] 
• [n][#TI_TEXT] 
• [n][#TI_SUBTREE] 
• [n][#TI_FLAGS]
• [n][#TI_ICON] 
• [n][#TI_TOOLTIP]

 

Node attributes to assign to Flags

• Constant #TIF_EXPANDED = 1       { Flag - true if expanded };
• Constant #TIF_CANEXPAND = 2     { Flag - true if able to expand };
• Constant #TIF_NOFOLDER = 4      { Flag - true if not display folder bmp };
• Constant #TIF_GREYTEXT = 8          { Flag - true if grey this option };
• Constant #TIF_HIDDENROOT = 16 { Flag - true if root is a hidden root };
• Constant #TIF_TITLEDTIP = 32         { Flag - true to use titled tooltips };
• Constant #TIF_POPUPTIP = 64        { Flag - true to NOT use in-place tooltips };

To use the control, the caller (not the parent) can provide the following subroutine modules, which will be called by TreeControl in response to specific events:

OnLeftClick(Node, X, Y, RelX, RelY)

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. RelX and RelY are the coordinates of the mouse relative to the Line.

OnRightClick(Node, X, Y, RelX, RelY)

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. RelX and RelY are the coordinates of the mouse relative to the Line.

OnDoubleClick(Node, X, Y, RelX, RelY)

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. RelX and RelY are the coordinates of the mouse relative to the Line. 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 you get to the tree root. The reverse recursion path is the shortest route from the root back to the node. Unwind the recursion, creating sub-trees as necessary and calling ExpandNode() for any that are not expanded.

OnJunctionSelect(Node)

Called when a node is collapsed only if the currently selected node existed in Node's subtree. When this happens the collapsed node will take the selection. Node is the newly selected (now collapsed) node. Click events on the junction are handled internally, and no callback is made.

When using callbacks on the selected node, the click detection is still done by the tree itself. You can use ExpandNode or SetSelected if you might prefer a different behavior. The selected node highlight is not done by the Tree Control and needs to be done in a callback, which is defined as follows:

CallBackScope\CallBackName(
                 Left   { }, 
                 Bottom { },
                 Right  { },
                 Top    { Drawing coordinates (not transformed) },
                 Node   { Array for this Node },
                 Offset { Pixel offset from left coordinate where the text or image will be drawn. });

Public API

TreeControl makes the following API available to any module that calls the ImportAPI function. To do so use:

Init [
  If 1 Main;
  [
    System.ImportAPI(System.TreeControl);
  ]

 

{***** Indices into the Tree array nodes *****}
  [ (API)
    {***** Modern node structure to use instead of legacy arrays *****}
    NodeStruct Struct [
      Key                          { "Key" value...see heading comment      };
      Label                        { Text value to be displayed             };
      SubTree                      { Subordinate tree below this node       };
      MapIdx                       { MapArray entry index                   };
      Flags                        { Various flags...see definitions        };
      Icon                         { Icon for node. Default to Folder icon. };
      Tooltip                      { Tooltip text. Default to Label.        };
      Data                         { Custom data managed by caller          };
    ];

    {***** Legacy indicies for a tree node array ***** }
    Constant #TI_KEY           = 0 { "Key" value...see heading comment      };
    Constant #TI_TEXT          = 1 { Text value to be displayed             };
    Constant #TI_SUBTREE       = 2 { Subordinate tree below this node       };
    Constant #TI_MAPARRAYIDX   = 3 { MapArray entry index                   };
    Constant #TI_FLAGS         = 4 { Various flags...see definitions        };
    Constant #TI_ICON          = 5 { ICON graphic for node..folder is default };
    Constant #TI_TOOLTIP       = 6 { In-place tooltip text - #TI_TEXT default };
    Constant #TREE_MINNODESIZE = 7 { Minimum compulsory node size           };

    {***** Node attributes to assign to Flags *****}
    Constant #TIF_EXPANDED   = 1   { Flag - true if expanded                };
    Constant #TIF_CANEXPAND  = 2   { Flag - true if able to expand          };
    Constant #TIF_NOFOLDER   = 4   { Flag - true if not display folder bmp  };
    Constant #TIF_GREYTEXT   = 8   { Flag - true if grey this option        };
    Constant #TIF_HIDDENROOT = 16  { Flag - true if root is a hidden root   };
    Constant #TIF_TITLEDTIP  = 32  { Flag - true to use titled tooltips     };
    Constant #TIF_POPUPTIP   = 64  { Flag - true to NOT use in-place tooltips };
  ]

Public Variables

TreeControl makes the following variables available for you to examine:

[
  Height            { Total number of NODES high.                 };
  Width             { Total number of PIXELS wide.                };
  LineHt            { Height of one line of text in PIXELS        };
  Started  = 0      { Flag - True when internal TreeWin is valid  };
]

Public Subroutines

Refresh

No parameters. Should be called upon building the tree and upon change.

CollapseNodes(Node)

Differs from CollapseNode. Collapse the entire sub-tree below the specified node. This can be done at any time and will not destroy the expanded state of subordinate tree nodes, allowing a subsequent expand to restore the state of the tree as it was before the collapse. This must be called if you want to delete the nodes below a specific point and rebuild them. Failure to call this before deleting nodes will have unpredictable results.

CollapseNode(ItemIndex)

Differs from CollapseNodes. Collapses a MappingArray entry if not already collapsed. This operation recursively destroys any MappingArray entries for each child of the identified item. Does not affect the expanded or contracted indication in the node tree. This allows a subsequent expansion of this node to display itself in it's previous expansion state.

DeleteNode(Node)

Deletes the specified node and its subtree.

ExpandNode(Node)

Expand the indicated node if there are child nodes and if not already expanded.

FindNode(Key, CurrentNode)

Given the "Key" value, returns the node containing that (unique) key. Returns Invalid if none found. WARNING: This subroutine may require significant system resources or time.

InsertNodes(Node, StartIndex, NumNewNodes)

Node { Tree node having its subtree expanded } StartIndex { Start index in its subtree-inserts after this } NumNewNodes { Number of new nodes added } Note that Node must already be expanded. Also, you cannot add a node to an empty Node. Build the node data and call ExpandNode instead.

SetSelected(TreeObject)

Provide the "Key" value to programmatically select a tree item. The tree will be positioned at the new selected item, expanding if needed.