35 Understanding Tree Controls

35.1 Tree Controls

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.

35.2 Tree Control Events

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.

35.3 Tree Control System Functions

This chapter discusses the system functions unique to the tree control.

Bulk Tree Load

Use this system function to load the entire contents of the tree control from cache.

Parameters

Tree Control

Input, required. The tree control form control (FC) to affect.

Cache Name

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.

Data Structure

Input, required. The name of the data structure used to organize the cache. Double-click <Get Structure Name> to select the structure to use.

Node Value Column

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.

Node Description Column

Input, required. The label to display for each node. Set the parameter to an applicable object from the object list.

Parent Value Column

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.

Root Node Value

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.

Delete 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.

Parameters

Tree Control

Input, required. The tree control FC to affect.

Node

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.

Node Value

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.

Expand Tree Node

Use this system function to expand a node (provided that the node is expandable).

Get Node Information

Use this system function to acquire the display text of a node and its associated node value

Parameters

Tree Control

Input, required. The tree control FC to affect.

Node

Input, required. The node about which to acquire information. Set the parameter to: <Currently Selected Node>, <Last Inserted Node>, or <Currently Expanding/Collapsing Node>.

Node Text

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.

Node Value

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.

Additional Notes

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.

Returns

This system function returns the text associated with the node to the object indicated by Node Text, and the node value to the object indicated by Node Value.

Get Node Level

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.

Parameters

Tree Control

Input, required. The tree control FC to affect.

Node

Input, required. The node about which to acquire information. Set the parameter to: <Currently Selected Node>, <Currently Expanding/Collapsing Node>, or <Currently Deleted Node>.

Return To

Output (numeric), required. The object to which to return the node level. Set the parameter to an applicable object from the object list.

Returns

This system function returns the level of the node to the object indicated by Return To.

Get Tree Node Handle

Use this system function to acquire the table handle associated with a particular tree 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.

Handle

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.

Returns

This system function returns the handle associated with the identified tree node to the object specified by Handle.

Insert Tree Node

Use this system function to insert a node into the tree.

Parameters

Tree Control

Input, required. The tree control FC to affect.

Node

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.

Node Text

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.

Node Value

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.

Expandable?

Input, required. An indicator of whether the user can expand and collapse the node. Set the parameter to <Yes> or <No>.

Parent Value

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.

Set Bitmap Scheme

Use this system function to set the default bitmap schema that will be used by the tree nodes in the tree control.

Parameters

Tree Control

Input, required. The tree control FC to affect.

Open Bitmap

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>).

Closed Bitmap

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>).

Leaf Bitmap

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>).

Additional Notes

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.

Set Node Bitmap

Use this system function to set a bitmap for a particular node, no matter its state.

Parameters

Tree Control

Input, required. The tree control FC to affect.

Node

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>.

Bitmap

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>).

Additional Notes

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.

Set Node Information

Use this system function to change the node value and the text displayed for the node.

Input, required. The text to display for the node. Set the parameter to an applicable object from the object list.

Node Value

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.

Additional Notes

A typical use of a node value 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.

Set Node Text

Use this system function to apply or change the text associated with a given node. This is the text that users can see.

Parameters

Tree Control

Input, required. The tree control FC to affect.

Node Text

Input, required. The text to apply to the node for display. Set the parameter to an applicable object from the object list.

Node Value

Input, required. The value of the node to affect. Set the parameter to <Root Node> or an applicable object from the object list.

Set Tree Node Handle

Use this system function to associate a handle with a particular tree node.

Parameters

Tree Control

Input, required. The tree control FC to affect.

Node

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>.

Index

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.

Handle

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.

Scripting on this page enhances content navigation, but does not change the content in any way.