Working with Trees

IN THIS CHAPTER

• Creating a Tree Item
• Operations on a Tree Item
• Planting and Growing Trees ”Dynamically Adding Nodes Along with Data to an Existing Base Tree
• Shrinking Trees
• Summary

This chapter discusses the various techniques involving tree items in Forms 6.0. It begins by explaining what a tree item is and goes on to present the technique for creating a tree item. Next, the techniques for the various operations on a tree item are highlighted. Specifically, operations like dynamically populating a tree item, selection using single-click of a node, node activation using double-click of a node, expansion and collapsing of nodes including expanding and collapsing all nodes, searching for a particular node and dynamically adding and deleting nodes are discussed.

A tree item is used to represent hierarchical data and is query only. It is populated by means of a query and the query populating it uses CONNECT BY and START WITH clauses. A common example is the Object Navigator in the Forms Designer. Another example is the typical recursive relationship between Manager and Employee discussed in Chapter 1, "GUI Development," under the section "Simulating a Drill-Down and Drill-Up LOV Using T-Lists." The same LOV can be presented in a tree structure as shown in Figure 9.1.

Figure 9.1. A hierarchical list of employees .

The same list when represented as a native hierarchical tree structure appears in Figure 9.2.

The main operations of a tree are

• Creating and initializing with a data query
• Specifying an ORDER BY
• Populating the tree
• Altering tree properties
• Node operations: selection of a node (single-click), activation of a node (double-click), expanding and collapsing nodes, and searching for a particular node
• Growing trees: adding sub-trees dynamically, adding singular nodes dynamically, deleting sub-trees dynamically, and deleting singular nodes dynamically

Figure 9.2. A native tree structure of employees.

Forms provides built-ins to implement the above operations. These are listed in Table 9.1.

Table 9.1. Built-ins to Implement Tree Operations

Operation	Built-in
Tree creation	At design time
Tree initialization	At design time by specifying a query for the Data Query property
Tree population	FTREE.POPULATE_TREE(item, rg_id) or FTREE.POPULATE_TREE(item, query_string)
Altering tree properties	FTREE.GET_TREE_PROPERTY(item, property)
	property can be any of the following:
	1. DataSource: FTREE.DATASOURCE. Valid values are Record Group ( FTREE.RECORD_GROUP ) and query text ( FTREE.QUERY_TEXT ). Also we can obtain the actual Record Group ( FTREE.RECORD_GROUP ), which returns the record group ID or name (can be set dynamically). Query Text ( FTREE.QUERY_TEXT ) returns the query text as a character string by using the above constants (can be set dynamically).
	2. Allow_empty_branches: FTREE.ALLOW_EMPTY_BRANCHES. Valid values are TRUE and FALSE as character strings.
	3. Node Count: FTREE.NODE_COUNT.
	4. Selection Count: FTREE.SELECTION_COUNT.
	5. Allow Multi-Select: FTREE.ALLOW_MULTI-SELECT. Valid values are TRUE and FALSE as character strings. Can be set dynamically.
	FTREE.SET_TREE_NODE_PROPERTY(item, property, value)
	Only properties 1 and 5 can be set dynamically.
Node properties	FTREE.GET_TREE_NODE_PROPERTY(item, property)
	property can be any of the following:
	1. Node State: FTREE.NODE_STATE. Returns one of FTREE.EXPANDED_NODE, FTREE.COLLAPSED_NODE, or FTREE.LEAF_NODE.
	2. Node Depth: FTREE.NODE_DEPTH
	3. Node Label: FTREE.NODE_LABEL
	4. Node Icon: FTREE.NODE_ICON
	5. Node Value: FTREE.NODE_VALUE
	FTREE.SET_TREE_NODE_PROPERTY(item, property, value)
	All of these properties except Node Depth can be set dynamically.
Node selection	FTREE.GET_TREE_SELECTION(item). Returns the selected node of data type FTREE.NODE starting from the top and numbered from 1 onwards. A node is considered selected if it is single-clicked.
	FTREE.SELECTION_COUNT : Returns the total number of selected nodes.
	The right trigger for performing an action based on node selection is WHEN-TREE-NODE-SELECTED. Use :SYSTEM.TRIGGER_NODE to get the node single-clicked.
Node Activation	WHEN-TREE-NODE-ACTIVATED trigger can be used to perform an action whenever the user double-clicks a node. Use :SYSTEM.TRIGGER_NODE to get the node double-clicked.
Searching a particular node	FTREE.FIND_TREE_NODE(item, search_string, search_type, search_by, search_root, start_point)
	search_type : FTREE.FIND_NEXT or FTREE.FIND_NEXT_CHILD
	search_by : FTREE.NODE_VALUE or FTREE.NODE_LABEL
	search_root : A valid node of data type FTREE.NODE or FTREE.ROOT_NODE.
	start_point : same as search_root.
Expanding and collapsing nodes	Use FTREE.GET_NODE_PROPERTY and FTREE.SET_TREE_NODE_PROPERTY to get the node state and set them accordingly depending on the current state of a node.
	To perform an action while expanding or collapsing, use WHEN-TREE-NODE-EXPANDED trigger.
Adding sub-trees	FTREE.ADD_TREE_DATA(item, node, offset_type, offset, data_source, data).
	offset_type : Either FTREE.PARENT_OFFSET or FTREE.SIBLING_OFFSET.
	offset : If offset_type is FTREE.PARENT_OFFSET, either (1-n) or FTREE.LAST_CHILD. If offset_type is FTREE.SIBLING_OFFSET, either FTREE.NEXT_NODE or FTREE.PREVIOUS_NODE.
	data source : FTREE.RECORD_GROUP or FTREE.QUERY_TEXT.
	data : Depending on the data source, a record group ID, name, or a query text string.
Adding singular nodes	FTREE.ADD_TREE_NODE(item, node, offset_type, offset, state, label, icon, value).
	offset_type and offset are as described above.
	state is FTREE.EXPANDED_NODE, FTREE.COLLAPSED_NODE or FTREE.LEAF_NODE.
Populating a record group from an existing tree	FTREE.POPULATE_GROUP_FROM_TREE(recordgroup, item, node) starting from a given node.
	In this case, node is the start point of the tree from where data should be extracted.
Deleting sub-trees and singular nodes	FTREE.DELETE_TREE_NODE(item, node) Deleting a node that has children will automatically delete all of its children.
Finding the parent of a given node	FTREE.GET_TREE_NODE_PARENT(item, node).