This chapter contains the following topics:
Tree controls display data in a hierarchical format. You can have multiple controls on a single form if you need more than one tree.
The tree itself is assembled from data that you have placed into cache. The data structure you create for this purpose must load at least three columns into cache:
Node Value
This value is used primarily for placing the row as a node in the tree. Every node in the tree requires a value which corresponds to its position in the tree, based on parent node value. The secondary purpose of node value is for identification.
Node Description
This value is used to label each node in the tree for the benefit of the users.
Parent Value
This value is used to indicate which row is its parent. The value corresponds to Node Value. Runtime adds this row as a child node of its parent in the tree.
Based on this data, and given which node value is to be used as the parent, runtime can construct a tree. For example, consider this table of data:
| Node Value | Node Description | Parent Value |
|---|---|---|
| 1 | Alpha Manufacturing | 0 |
| 2 | Branch A | 1 |
| 3 | Branch B | 1 |
| 4 | Plant x | 2 |
| 5 | Plant y | 2 |
| 6 | Plant z | 3 |
Given that the root node value is 1, runtime could assemble a tree with this structure:
Alpha Manufacturing
Branch A
Plant x
Plant y
Branch B
Plant z
Consequently, you must ensure that the data in the node value and parent value columns correspond such that runtime can derive the hierarchy. Additionally, many of the system functions that you can use to manipulate the tree rely on node value as an identifier. Therefore, you might want to ensure that those values are unique.
You can also use table I/O to provide node data by associating a given node with a particular table handle using the Set Tree Node Handle system function.
Tree controls have no control-specific properties in Form Design Aid (FDA). Additionally, no automatic runtime processing occurs for the control. Tree controls are manipulated by system functions exclusively.
These events can fire on the tree control during runtime:
Set Focus On Tree
Fires when the tree control acquires focus.
Tree Node Selected
Fires when the user clicks a tree node.
Tree Node Is Expanding
Fires when the user or engine expands a node. This event fires only on the first expand incident for a particular node in a session.
Tree Node Is Collapsing
Fires when the user or engine collapses a node.
Double Click on Leaf Node
Fires when the user double-clicks a leaf node.
Get Custom Tree Node
Fires when the user or engine expands a node for the first time in the session. It also fires if page-at-a-time processing is enabled and the user loads a new page.
Tree Node Is Deleted
Fires when the user or engine deletes a tree node.
Kill Focus On Tree
Fires when the tree control loses focus.
This chapter discusses the system functions unique to the tree control.
Use this system function to load the entire contents of the tree control from cache.
Input, required. The tree control form control (FC) to affect.
Input, required. The name of the cache from which to acquire data for the contents of the tree. Set the parameter to an applicable object from the object list.
Input, required. The name of the data structure used to organize the cache. Double-click <Get Structure Name> to select the structure to use.
Input, required. The data to use for identification. This value is not a true ID in the traditional sense; in this system function, it is used primarily for matching with values in the Parent Value Column to determine parent/child relationships. If you want to use node value as a true identifier, ensure that each row will have a unique value in this column (many tree control system functions use node value as an ID). Set the parameter to an applicable object from the object list.
Input, required. The label to display for each node. Set the parameter to an applicable object from the object list.
Input, required. The data to use to determine parent/child relationships. This value indicates which row is the parent of the current row. When runtime constructs the tree, it will place the current row as a child of the row with the corresponding value in Node Value Column. Set the parameter to an applicable object from the object list.
Input, required. The value that indicates the root node. Ultimately, the uppermost node of the tree, the root node, has no parent. Runtime compares this value with the values in the Node Column Value parameter. The row with the matching value becomes the root node.
Use this system function to collapse a given node.
Input, required. The tree control FC to affect.
Input, required. The node to collapse. Set the parameter to: <Currently Selected Node>, <Last Inserted Node>, or <Currently Expanding/Collapsing Node>.Expand Tree Node
Use this system function to delete a node (and its children) from the tree. You can also delete just the children of a node or all of the nodes in the tree.
Input, required. The tree control FC to affect.
Input, required. The node to delete. Set the parameter to: <Currently Selected Node>, <Last Inserted Node>, <All Child Nodes Under the Current Node>, <All Nodes>, <With Specified Node Value>. Use the last option in conjunction with the Node Value parameter.
Input, optional. The node to delete. This parameter is required only if you set Node to <With Specified Node Value>. Set the parameter to an applicable object from the object list.
Use this system function to expand a node (provided that the node is expandable).
Input, required. The tree control FC to affect.
Input, required. The node to expand. Set the parameter to: <Currently Selected Node>, or <Last Inserted Node>.Contract Tree Node
Use this system function to acquire the display text of a node and its associated node value
Input, required. The tree control FC to affect.
Input, required. The node about which to acquire information. Set the parameter to: <Currently Selected Node>, <Last Inserted Node>, or <Currently Expanding/Collapsing Node>.
Output, required. The object to which to return the text displayed with the node. The data type of this parameter should be the same as that is displayed by the node. For example, if the node is displaying a numeric value, this parameter should be a numeric value. Set the parameter to an applicable object from the object list.
Output, required. The object to which to return the value of the node. The data type of this parameter should be the same as that of the value currently stored in the node. For example, if the node currently has a numeric value, this parameter should be a numeric value. Set the parameter to an applicable object from the object list.
Store the node value while inserting the node or by using the Set Node Information system function. A typical use is to store a key value associated with the tree node. Data of any type can be stored in the node value as long as you maintain consistency in storing and retrieving the value.
Use this system function to determine the vertical level of a node in the tree. The root node is 0, so its first child is at a level of 1, its second at 2, and so on.
Input, required. The tree control FC to affect.
Input, required. The node about which to acquire information. Set the parameter to: <Currently Selected Node>, <Currently Expanding/Collapsing Node>, or <Currently Deleted Node>.
Output (numeric), required. The object to which to return the node level. Set the parameter to an applicable object from the object list.
Use this system function to acquire the table handle associated with a particular tree node.
Input, required. The tree control FC to affect.
Input, required. The node for which to acquire the handle. Set the parameter to: <Currently Selected Node>, <Last Inserted Node>, <Root Node>, <Currently Expanding/Collapsing Node>, or <Currently Deleted Node>.
Input, required. The index of the handle. Applications can associate more than one handle to one tree node. Use this parameter to differentiate multiple handles for the same node. Set the parameter to an alphanumeric constant (<Literal>), <Blank>, <Zero>, or an applicable object from the object list.
Output, required. The object to which to return the handle associated with the node. Set the parameter to an applicable object from the object list.
Use this system function to insert a node into the tree.
Input, required. The tree control FC to affect.
Input, required. The position in the tree where you want to insert the node, relative to this node. Set the parameter to insert the node as a child of the current node (<Under Currently Selected Node>), to insert the node as a sibling of the current node (<After Currently Selected Node>), <After Last Inserted Node>, <Under Root Node>, <Under Currently Expanding Node>, or <Under Specified Parent Value>. Use the last option in conjunction with the Parent Value parameter.
Input, required. The object to which to return the text displayed with the node. The data type of this parameter should be the same as that is displayed by the node. For example, if the node is displaying a numeric value, this parameter should be a numeric value. Set the parameter to an applicable object from the object list.
Input, required. The object to which to return the value of the node. The data type of this parameter should be the same as that of the value currently stored in the node. For example, if the node currently has a numeric value, this parameter should be a numeric value. Set the parameter to an applicable object from the object list.
Input, required. An indicator of whether the user can expand and collapse the node. Set the parameter to <Yes> or <No>.
Input, optional. The ID of the node you want to become the parent of the node you are inserting. Use this parameter if you set Node to <Under Specified Parent Value>. Set the parameter to an applicable object from the object list.
Use this system function to set the default bitmap schema that will be used by the tree nodes in the tree control.
Input, required. The tree control FC to affect.
Input, required. The bitmap to display for a node when it has been expanded. Set the parameter to a particular bitmap (double-click <Choose Tree Bitmap> to browse for one) or the standard bitmap (<Default>).
Input, required. The bitmap to display for a node when it has been collapsed. Set the parameter to a particular bitmap (double-click <Choose Tree Bitmap> to browse for one) or the standard bitmap (<Default>).
Input, required. The bitmap to display for a leaf node with no children. Set the parameter to a particular bitmap (double-click <Choose Tree Bitmap> to browse for one) or the standard bitmap (<Default>).
The bitmaps must be of size 16 x 16 and should reside in the treebmps subdirectory of the resource directory (for example: d:\b7\appl_pgf\res\treebmps). If a bitmap fails to load, the application uses the corresponding standard bitmap. The ideal place for using this system function is during on event, Dialog Is Initialized.
Use this system function to set a bitmap for a particular node, no matter its state.
Input, required. The tree control FC to affect.
Input, required. The node for which to set the bitmap. Set the parameter to: <Currently Selected Node>, <Last Inserted Node>, or <Currently Expanding/Collapsing Node>.
Input, required. The bitmap to display for the node. Set the parameter to a particular bitmap (double-click <Choose Tree Bitmap> to browse for one) or the standard bitmap (<Default>).
After the bitmap for a tree node is set using this system function, the default scheme changes for that node. The system does not apply the expanded and collapsed bitmaps to the node.
The bitmaps must be of size 16 x 16 and should reside in the treebmps subdirectory of the resource directory (for example: d:\b7\appl_pgf\res\treebmps). If a bitmap fails to load, the application uses the corresponding standard bitmap. The ideal place for using this system function is on the event Dialog Is Initialized.
Use this system function to change the node value and the text displayed for the node.
Input, required. The tree control FC to affect.
Input, required. The node to affect. Set the parameter to: <Currently Selected Node>, <Last Inserted Node>, or <Currently Expanding/Collapsing Node>.
Input, required. The text to display for the node. Set the parameter to an applicable object from the object list.
Input, required. The value to apply to the node. This value is often used for identification purposes, so you might want to ensure that it is unique. Set the parameter to an applicable object from the object list.
Use this system function to apply or change the text associated with a given node. This is the text that users can see.
Input, required. The tree control FC to affect.
Input, required. The text to apply to the node for display. Set the parameter to an applicable object from the object list.
Input, required. The value of the node to affect. Set the parameter to <Root Node> or an applicable object from the object list.
Use this system function to associate a handle with a particular tree node.
Input, required. The tree control FC to affect.
Input, required. The node to which to associate the handle. Set the parameter to: <Currently Selected Node>, <Last Inserted Node>, <Root Node>, or <Currently Expanding/Collapsing Node>.
Input, required. The index of the handle. Applications can associate more than one handle to one tree node. Use this parameter to differentiate multiple handles for the same node. Set the parameter to an alphanumeric constant (<Literal>), <Blank>, <Zero>, or an applicable object from the object list.
Input, required. The object to which to return the handle associated with the node. Set the parameter to an applicable object from the object list.