Treelist Methods & Properties

This section covers various methods and properties of the treelist object (the actual field). Tips, sample code, and demos let you see how to make use of the methods and properties when working with the treelist object.

You can view all of the methods and properties when you select the treelist object in a window class and the press F9 to open the Property Manager window. You can also find information in the F1 Help on treelist methods and properties.

Some of the methods listed in this section pertain to both the treelist object and a node of the treelist. In those situations sample code is given for both the treelist object and the tree node.

There is an option with the treelist object to display columns of additional data for each node. See the Treelist Columns topic for methods pertaining to the display columns option.

Be sure to review the Treelist Naming Conventions topic if you haven't already done so.

A Run Demo button will appear at the bottom of the StudioTips Browser window if a demo is available for a particular tip. Clicking the Run Demo button will open up a demo window.

For most of the demos in this section, you can play around clicking on different nodes in the treelist and then clicking the pushbutton to test the method on different nodes.

Holding down the shift key while clicking the button in the demo window will take you to a breakpoint in the method code allowing you to step through the actual code so you can see what is happening behind the scenes.

You do not need to issue a $redraw after using a treelist method. Each treelist method automatically redraws the treelist object when applicable.

$add

$add(cName[,iIdent,lRowForColumns])

Adds a node with the specified iIdent, and returns an item reference to the new node. If the treelist has multiple columns, you can supply the data for columns 2 and greater in the row variable lRowForColumns.

Add a new root level node to the treelist.

; Add a root node to the treelist.
Do irTreeObj.$add(NodeName) Returns rNode

; Add a root node to the treelist, specifying the node ident.
Do irTreeObj.$add(NodeName,Ident) Returns rNode

; Add a root node to the treelist, specifying the node ident, and the columns row data.
Do irTreeObj.$add(NodeName,Ident,ColumnsRowData) Returns rNode

; Note: In all of the above cases, the ident and rowdata can be assigned after.
Do irTreeObj.$add(NodeName) Returns rNode
Do rNode.$ident.$assign(Ident)
Do rNode.$rowdata.$assign(ColumnsRowData)

Add a new child node to a parent node.

; Add a child node to a parent node.
Do rParentNode.$add(NodeName) Returns rNode

; Add a child node, specifying the node ident.
Do rParentNode.$add(NodeName,Ident) Returns rNode

; Add a child node , specifying the node ident, and the columns row data.
Do rParentNode.$add(NodeName,Ident,ColumnsRowData) Returns rNode

; Note: In all of the above cases, the ident and rowdata can be assigned after.
Do rParentNode.$add(NodeName) Returns rNode
Do rNode.$ident.$assign(Ident)
Do rNode.$rowdata.$assign(ColumnsRowData)

$addafter

$addafter(rItem,cName[,iIdent,lRowForColumns])

Adds a node with the specified iIdent, after the node rItem, and returns a tree node item reference to the new node.

; Add a root node to the treelist after the specified existing root node.
Do irTreeObj.$addafter(rRootNode,NodeName) Returns rNode

; Add a child node to a parent node after the specified existing child node.
Do rParentNode.$addafter(rChildNode,NodeName) Returns rNode

; Note: The $ident and $rowdata can be included as parameters.

$addbefore

$addbefore(rItem,cName[,iIdent,lRowForColumns])

Adds a node with the specified iIdent, before the node rItem, and returns a tree node item reference to the new node.

; Add a root node to the treelist before the specified existing root node.
Do irTreeObj.$addbefore(rRootNode,NodeName) Returns rNode

; Add a child node to a parent node before the specified existing child node.
Do rParentNode.$addbefore(rChildNode,NodeName) Returns rNode

; Note: The $ident and $rowdata can be included as parameters.

$clearallnodes

$clearallnodes()

Clears all nodes in the entire treelist or the child nodes of a specific parent node.

; Clear all the nodes in the treelist.
Do irTreeObj.$clearallnodes()

; Clear all the child nodes of a specific parent node.
Do rParentNode.$clearallnodes()

$collapse

$collapse()

Closes all nodes of the entire treelist or a specified parent node.

; Close all the nodes in the treelist.
Do irTreeObj.$collapse()

; Close all the child nodes of a specific parent node.
Do rParentNode.$collapse()

$count

$count()

Return the number of child nodes.

; Count all the root nodes in the treelist.
Do irTreeObj.$count() Returns NodesCount

; Count all the child nodes of a specific parent node.
Do rParentNode.$count() Returns NodesCount

$countall

$countall()

Returns the total number of nodes in the tree. This method only works for the treelist object.

; Count all the nodes in the treelist.
Do irTreeObj.$countall() Returns NodesCount

$currentnode

$currentnode()

Returns a node item reference to the currently selected node in the treelist object.

; Get a reference to the currently selected node.
Do irTreeObj.$currentnode() Returns rNode

$expand

$expand()

Open all nodes in the entire treelist or the child node of a specific parent node.

; Expand all the nodes in the treelist.
Do irTreeObj.$expand()

; Expand all the child nodes of a specific parent node.
Do rParentNode.$expand()

$findnodeident

$findnodeident(rNodeRef,iIdent[,bRecursive=kFalse])

Searches the tree for a node which has the $ident matching iIdent. If it finds such a node, it returns a tree node item reference to the node. Otherwise, it returns null. You can use the isnull() function to test the returned item reference.

If you pass a tree node item reference in rNodeRef, then the method searches the nodes beneath the referenced node. To search the root nodes, pass zero (0) as the rNodeRef parameter.

If you pass bRecursive as kTrue, then the search is recursive, which means it will drill down searching all the branches extending from rNodeRef.

; Search the root nodes only.
Do irTreeObj.$findnodeident(0,Ident) Returns rNode

; Search the root nodes and the children.
Do irTreeObj.$findnodeident(0,Ident,kTrue) Returns rNode

; Search the child nodes only of the specified parent node.
Do irTreeObj.$findnodeident(rParentNode,Ident) Returns rNode

; Search all the child nodes (drill down) of the specified parent node.
Do irTreeObj.$findnodeident(rParentNode,Ident,kTrue) Returns rNode

There is no demo for this treelist method because I did not assign node idents to the demo treelist.

$findnodename

$findnodename(rNodeRef,cName[,bRecursive=kFalse,bIgnoreCase=kFalse])

Searches the tree for a node which has the name cName. If it finds such a node, it returns a tree node item reference to the node. Otherwise, it returns null. You can use the isnull() function to test the returned item reference.

If you pass a tree node item reference in rNodeRef, then the method searches the nodes beneath the referenced node. To search the root nodes, pass zero (0) as the rNodeRef parameter.

If you pass bRecursive as kTrue, then the search is recursive, which means it will drill down searching all the branches extending from rNodeRef.

The boolean bIgnoreCase determines whether the search is case-sensitive.

; Search the root nodes only.
Do irTreeObj.$findnodename(0,NodeName) Returns rNode

; Search the root nodes and the children.
Calculate bIgnoreCase as kTrue ;; Case-insensitive search.
Do irTreeObj.$findnodename(0,NodeName,kTrue,bIgnoreCase) Returns rNode

; Search the child nodes only of the specified parent node.
Do irTreeObj.$findnodename(rParentNode,NodeName) Returns rNode

; Search all the child nodes (drill down) of the specified parent node.
Do irTreeObj.$findnodename(rParentNode,NodeName,kTrue) Returns rNode

$findnodetag

$findnodetag(rNoderef,cTag[,bRecursive=kFalse])

Returns a node reference if $tag matches the value of cTag.

Searches the tree for a node which has the $tag property value matching cTag. If it finds such a node, it returns a reference to the node. Otherwise, it returns null. You can use the isnull() function to test the returned item reference.

If you pass a tree node item reference in rNodeRef, then the method searches the nodes beneath the referenced node. To search the root nodes, pass zero (0) as the rNodeRef parameter.

If you pass bRecursive as kTrue, then the search is recursive, which means it will drill down searching all the branches extending from rNodeRef.

See the $tag treelist topic for more information about this handy developer assignable node property. The $tag can be of any datatype. For the $findnodetag method to work, the $tag property datatype must be a searchable datatype. (e.g. row, list, picture, binary would not work)

There is no demo for this treelist method because I did not assign the $tag node properties in the demo treelist.

$first

$first()

Return an item reference to the first child node of the specified parent.

; First root node in the treelist.
Do irTreeObj.$first() Returns rNode

; First child node of the specified parent node.
Do rParentNode.$first() Returns rNode

$getnodelist

$getnodelist(iListmode,rNodeRef,lListname)

Returns the list data under the specified node or for the entire tree.

1. iListmode can be kRelationalList, kFlatList or kTreeColList
2. rNodeRef can be a tree node item reference or zero (0) to retrieve the entire tree
3. lListname is the list variable to receive the list data.

; Get node list for the entire treelist object.
Do irTreeObj.$getnodelist(kRelationalList,0,SelectedNodesList)
Do irTreeObj.$getnodelist(kFlatList,0,SelectedNodesList)
Do irTreeObj.$getnodelist(kTreeColList,0,SelectedNodesList)

; Get node list for a specified parent node.
Do irTreeObj.$getnodelist(kRelationalList,rParentNode,SelectedNodesList)
Do irTreeObj.$getnodelist(kFlatList,rParentNode,SelectedNodesList)
Do irTreeObj.$getnodelist(kTreeColList,rParentNode,SelectedNodesList)

$getselectednodes

$getselectednodes(List)

Gets a list of item references to the selected nodes in the treelist object. The first and only column in the list is an item reference datatype column.

; Get a list of the selected nodes.
Do irTreeObj.$getselectednodes(List)

Prior to v4.1 you need to loop through all the nodes and check the $multipleselect node property of each node. If the node is selected, the $multipleselect property value will be kTrue. The following sample code can be used to build a list of selected nodes versions of Omnis Studio prior to v4.1.

; Build a list of the selected nodes list. (Pre-version 4.1)

; Define the nodes list.
Do SelectedNodesList.$cols.$add('nodeitem',kItemref)

; Only visible nodes can be selected. Just loop through the visible nodes.
Calculate %L as 1
Do irTreeObj.$getvisiblenode(%L) Returns rNode
While rNode
   
   ; If the node is selected add it to the list.
   If rNode.$multipleselect
      Do SelectedNodesList.$add(rNode)
   End If
   
   ; Go to the next visible line.
   Calculate %L as %L+1
   Do irTreeObj.$getvisiblenode(%L) Returns rNode
   
End While

$getvisibleline

$getvisibleline(rItem)

Returns the line number of the node identified by the tree node item reference rItem, if the node is visible. If the node is not visible, it returns zero.

; Return the visible line number for the specified node.
Do irTreeObj.$getvisibleline(rNode) Returns LineNum

$getvisiblenode

$getvisiblenode(iVisLine)

Returns a tree node item reference to the node for the visible line iVisLine.

; Return a reference to the specified visible line number.
Do irTreeObj.$getvisiblenode(LineNum) Returns rNode

$movenode

$movenode(rItem,rItemMoveAfter[,cChildModeConst])

moves rItem. rItem is moved according to kMoveNodexxx constants. Returns kTrue if successful.

$multipleselect

$multipleselect

Setting the treelist property $multipleselect property to kTrue allows the user to select multiple nodes in the treelist.

$nextnode

$nextnode(rItem,bRecursive)

$prevnode

$prevnode(rItem,bRecursive)

Returns the node in the tree before the node identified by tree node item reference rItem; if bRecursive is kTrue, the method steps back into node parents.

; Previous node
Do irTreeObj.$prevnode(rCurrNode) Returns rNode

; Previous node. Step in to parent nodes.
Do irTreeObj.$prevnode(rCurrNode,kTrue) Returns rNode

$remove

$remove()

Delete the child node identified by tree node item reference rItem.

; Remove the specifed node
Do irTreeObj.$remove(rNode)

$setcurrentnode

$setcurrentnode(rItem)

Sets the currently selected node to the node identified by tree node item reference rItem. Note that this will only work for visible nodes, and that it will generate a click event on the node after making it current.

; Set the current node.
Do irTreeObj.$setcurrentnode(rNode)

; Unset the current node.
Do irTreeObj.$setcurrentnode()

$setnodelist

$setnodelist(iListmode,rNodeRef,lListname)

Lets you populate a specified node or the entire tree with the data in lListname;

iListmode can be kRelationalList, kFlatList or kTreeColList;

rNoderef can be a tree node item reference or zero to populate the entire tree.

; Set the entire treelist using a list.
Do irTreeObj.$setnodelist(kRelationalList,0,List)
Do irTreeObj.$setnodelist(kFlatList,0,List)
Do irTreeObj.$setnodelist(kTreeColList,0,List)

; Set the child nodes of a parent node using a list.
Do irTreeObj.$setnodelist(kRelationalList,rParentNode,List)
Do irTreeObj.$setnodelist(kFlatList,rParentNode,List)
Do irTreeObj.$setnodelist(kTreeColList,rParentNode,List)

$setnodelist is simply the reverse of $getnodelist. Study the various lists in the $getnodelist demo. You need to build the applicable list and then use $setnodelist with the appropriate parameters. You can either use $setnodelist to set the entire treelist, or to set the nodes on a branch of the treelist.

I find it much easier to build treelists on-the-fly using notation than dealing with making a list and then using the $setnodelist method. See the topic on Populating a Treelist.

StudioTips Documentation - Copyright 2006 Vencor Software