StudioTips - GUI - Treelists (All Contents)

Tips_gui > Treelists > Treelists (All Contents)

Treelists

Treelist

: a hierachical list with expandable and collapsable nodes.

Picture a tree in the forest, this is the picture you need to have in your mind when you think and talk about treelist objects in the computer world. Every branch of a tree is connected to a parent branch, which is connected to another parent branch, and eventually the branches connect all the way back to the root of the tree. There is only one root for each tree.

Treelists are among the last hold outs in my Omnis Studio learning experience. I remember attending a class on treelists at my first Omnis conference. After that session my thoughts were "Treelists are too much work, I'll stick with lists, they are a lot easier".

Treelists might be more work for the programmer, but in the right situation they are the best GUI.

Imagine trying to navigate the StudioTips Browser without treelists! Treelists are great for presenting lots of information in a format that allows the user to explore the layers on their own.

Treelist Naming Conventions

When dealing with treelists, it is important to clearly understand the some of the different terms used:

Treelist Object - The actual window field object that is used to display the treelist to the user.
Root Node - Any node at the first level of the treelist.
Parent Node - The node one level above a child nodes as viewed by the child node.
Child Node - Any node which is attached to a parent node as viewed by the parent node.

Think of the treelist object itself as the level zero (0) parent node. The treelist object is the parent node of all the level one (1) root nodes. Each of the level one (1) parent nodes can have level two (2) child nodes, etc.

The naming conventions used in the sample code in this section are as follows:

irTreeObj - Item reference to the treelist object. (instance variable)
rParentNode - Item reference to a node in the treelist. (local variable)
rNode - Item reference to a node in the treelist. (local variable) This variable is usually used for the return value from any method which returns a reference to a node.

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.

Populating a Treelist

You can populate a treelist object from a list variable using the $setnodelist method. See $setnodelist and $getnodelist in the Treelist Methods & Properties topic for more information.

There are 3 types of lists which you can use in the $setnodelist method.

kRelationalList - simplest form.
kFlatList - lets you specify the node properties.
kTreeColList - lets you specify the node properties and display columns.

When I was first learning to use treelists I prepared the appropriate list and then used the $setnodelist method to populate the treelist. Preparing the list was a lot of work and one of the reason I steered clear of using treelists.

Later I learned how to populate the treelist object on-the-fly using notation.

Typically I build the root level nodes with the expand node icons. When the user clicks to expand a node I trap the evTreeExpand event and using pNodeItem to find out which node is being expanded, clear the child nodes and add the child nodes one at a time in a loop. As each node is added you use the node reference to set the node properties.

Populating treelists on-the-fly is fast, flexible, and in my opinion much less work than populating them from lists.

The following sample code shows how to build the root nodes of a treelist object.

; Treelist Method: buildTreelist

; Call this method from the $construct method of the treelist object.

; Build a treelist which displays all object classes in the current library.

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

; Make a list of all the object classes in the current library.
Do $clib.$objects.$makelist($ref().$name,$ref) Returns ClassesList
Do ClassesList.$cols.1.$name.$assign('name')
Do ClassesList.$cols.2.$name.$assign('ref')
Do ClassesList.$sort(upp($ref.name))

; Loop through the classes list, building the treelist root nodes.
For ClassesList.$line from 1 to ClassesList.$linecount step 1

   ; Add the root node and set the $tag to reference the class.
   Do irTreeObj.$add(ClassesList.name) Returns rNode
   Do rNode.$showexpandalways.$assign(kTrue)
   Do rNode.$tag.$assign(ClassesList.ref)

End For

Quit method kTrue

The following sample code shows how to add child nodes on-the-fly.

; Treelist Method: addChildNodes (prParentNode, prClass)

; Build a list of the methods for the specified class.
Do prClass.$methods.$makelist($ref().$name,$ref) Returns MethodsList
Do MethodsList.$cols.1.$name.$assign('name')
Do MethodsList.$cols.2.$name.$assign('ref')
Do MethodsList.$sort(upp($ref.name))

; Loop through the methods list.
For MethodsList.$line from 1 to MethodsList.$linecount step 1

   ; Add a child node.
   Do prParentNode.$add(MethodsList.name) Returns rNode
   Do rNode.$tag.$assign(MethodsList.ref)
   ; Note: You can set any additional node properties here.

End For

Quit method kTrue

The following code traps evTreeExpand in the $event method of the treelist object and calls the addChildNodes method.

; Treelist Method: $event

On evTreeExpand

; Clear the child nodes.
Do pNodeItem.$clearallnodes()

; Add the child nodes.
Do method addChildNodes (pNodeItem,pNodeItem.$tag)

The following sample code shows how $constuct method of the treelist object points the instance variable irTreeObj to itself and then calls the buildTreelist method.

; Treelist Method: $construct

; Point the irTreeObj ivar to this treelist object.
Set reference irTreeObj to $cfield

; Build the treelist.
Do method buildTreelist Returns FlagOK

Quit method FlagOK

Click the Run Demo button in the StudioTips Browser window to view a demo window which use the above code.

Store and Restore Treelist

In the StudioTips Browser I needed to be able to store and restore the exact state of each treelist which you look at in the StudioTips Browser. That way if you close the StudioTips Browser window, when you reopen the window each treelist will be reopened in the same state that you last looked at them.

Tech Support gave me the solution. You simply use the parameter #NULL in the $getnodelist and $setnodelist methods.

The following sample code saves the current state and current node.

; Save the current treelist 'state' and selected node.

; Get the current state of the treelist. Tip from Tech Support.
Do rTree.$getnodelist(kTreeColList,#NULL,List)

; Get the current node of the treelist
Do rTree.$currentnode() Returns rNode
Do rTree.$getvisibleline(rNode) Returns VisLineNum

; Save the list and visible line number.
Do method saveTreelistState (rTree,List,VisLineNum) Returns FlagOK

Quit method FlagOK

The following sample code restores the last state and last current node.

; Restore the last treelist 'state' and selected node.

; Get the last state list and visble line number for this treelist.
Do method getTreelistState (rTree,List,VisLineNum) Returns FlagOK
If FlagOK

   ; Clear all the nodes
   Do rTree.$clearallnodes()

   ; Set the treelist
   Do rTree.$setnodelist(kTreeColList,#NULL,List)

   ; Get a reference to the last selected visible node
   Do rTree.$getvisiblenode(VisLineNum) Returns rNode

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

End If
Quit method FlagOK

The $tag property can not be saved back to any of the nodes lists (kFlatList,kRelationalList,kTreeColsList). If you need to save the $tag value to a nodes list considering adding/using a column in the $rowdata property instead.

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.

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.

iListmode can be kRelationalList, kFlatList or kTreeColList
rNodeRef can be a tree node item reference or zero (0) to retrieve the entire tree
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.

The $movenode method had some problems in Omnis Studio v4.2, these have been fixed in v4.3.

$multipleselect

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

If the $multipleselect treelist object property has been set to kTrue, the $selected property of any selected node will be kTrue.

$nextnode

$nextnode(rItem,bRecursive)

Returns the node in the tree after the node identified by tree node item reference rItem; if bRecursive is kTrue the method steps into any child nodes.

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

Tree Node Methods & Properties

This section covers various methods and propeties of the treelist nodes. 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 find information in the F1 Help on treelist nodes by searching for tree node.

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.

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

$checked

If true, the line is checked.

If rNode.$checked
; Do something.
Else
; Do something else.
End If

$drawinactive

If true, the text for the node is drawn to indicate that the node is not active, and the expand/collapse box is hidden.

$enterable

If true, the grid is enterable.

$iconid

The numeric icon identifier used to reference the icon in the icon file or #ICONS.

; Set the icon ID for the node.
Do rNode.$iconid.$assign(1704)
; or
Calculate rNode.$iconid as 1704

$isexpanded

If true, the node is already expanded.

If rNode.$isexpanded
; Do something
Else
; Do something else.
End If

$level

The node indent level within the tree.

; Find out the indent level of the specified node.
Do rNode.$level() Returns LevelNum
; or
Calculate LevelNum as rNode.$level()

; Decide what to do based on the indent level of the node.
Switch rNode.$level
   Case 1
      ; Do something
   Case 2
      ; Do something else
End Switch

$nodeparent

Returns a tree node item reference to the parent node of the current node. If the return value is empty, then the current node is a root node.

; Get a reference to the node's parent.
Do rNode.$nodeparent() Returns rParentNode

$rowdata

The row variable containing the column data for the node, used when the tree list has more than one column. Column N of the row variable contains the data of column (N + 1) of the tree list. Each column is a character string of up to 255 characters.

; Set the row data.
Do rNode.$rowdata.$assign(Row)

; Get the row data.
Do rNode.$rowdata Returns Row

$seedid

A unique number assigned to a node within a tree. This is a read-only property.

Calculate ID as rNode.$seedid

$selected

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

If the $selected treelist object property has been set to kTrue node is selected. You can $assign the $selected property of any node.

If rNode.$selected
; The node is selected.
End If

$showexpandalways

If true, the node is to always show the expand/collapse box.

Do rNode.$showexpandalways.$assign(kTrue)

$tag

Omnis introduced a $tag treelist node property which can be assigned by the developer. The $tag property is a binary, so you can assign any datatype to the $tag node property.

I have found the $tag node property great for building treelists on-the-fly. For example if I build a treelist of all the classes in a library, as the list is built, I assign a class item reference to each node's $tag property. When the user clicks to expand a class node, I simply use $tag property to get the item reference to the class. With the class reference in hand, a list of methods for that class can be very quickly built and the method name nodes added. As each method node is added, the method item reference is assigned to the node's $tag property.

; Build a treelist which displays all the menu classes in the current library.

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

; Make a list of all the menu classes in the current library.
Do $clib.$menus.$makelist($ref().$name,$ref) Returns ClassesList
Do ClassesList.$cols.1.$name.$assign('name')
Do ClassesList.$cols.2.$name.$assign('ref')

; Loop through the classes list, building the treelist root nodes.
For ClassesList.$line from 1 to ClassesList.$linecount step 1

   ; Add the root node and set the $tag to reference the class.
   Do irTreeObj.$add(ClassesList.name) Returns rNode
   Do rNode.$showexpandalways.$assign(kTrue)
   Do rNode.$tag.$assign(ClassesList.ref)

End For

Quit method kTrue

; The following code would be used in the $event method of the treelist object.
On evTreeExpand
Switch pNodeItem.$level
   Case 1 ;; Class

      ; Clear the existing child nodes.
      Do pNodeItem.$clearallnodes()

      Set reference rClass to pNodeItem.$tag().$ref

      ; Make a list of the methods and add them as child nodes.
      Do rClass.$methods.$makelist($ref().$name,$ref) Returns MethodsList
      Do MethodsList.$cols.1.$name.$assign('name')
      Do MethodsList.$cols.1.$name.$assign('ref')
      For MethodsList.$line from 1 to MethodsList.$linecount step 1

         Do pNodeItem.$add(MethodsList.name) Returns rNode
         Do rNode.$tag.$assign(MethodsList.ref)

      End For

   Case 2 ;; Method.


End Switch

Use your imagination. The $tag property can help with building treelists on-the-fly and save a lot of code.

The $tag property can not be saved back to any of the nodes lists (kFlatList,kTreeColsList,kTreeRelationalList). If you need to save the $tag value to a nodes list considering adding/using a column in the $rowdata property instead.

Treelist Events

There are a number of events related to treelists. You can trap them in the $event method of the Treelist.

evTreeCollapse - Sent to a tree list when a node collapses.
evTreeExpand - Sent to a tree list when a node expands.
evTreeExpandCollapseFinished - Sent to a tree list after expanding or collapsing is finished.
evTreeListEditStarting - Sent to a Tree list when the column text is about to be edited
evTreeListEditFinishing - Sent to a Tree list when new text is ready to be stored in the list
evTreeListEditFinished - Sent to a Tree list when the edit field has been closed
evTreeNodeNameFinished - Sent to a tree list when the node icon has been clicked.
evTreeNodeNameFinishing - Sent to a tree list when the node name has been changed.
evTreeNodeIconClicked - Sent to a tree list when the node icon has been clicked.

Every one of the evTree... events has the parameter pNoteItem which is an item reference to the node.

The evTreeListEdit... events also have the parameter pColumnNumber indiciating the column number where the event is taking place.

The evTreeNodeNameFinishing and evTreeNodeName... events have also have the parameter pNewText which is the text which the user has entered.

Treelist Drag and Drop

You can allow drag and drop nodes between treelists or within the same treelist. There are several treelist object properties you need to set in order to be able to do drag and drop operations. Set the treelist object F6 Properties Manager > Action tab properties are as follows:

$multipleselect = kTrue - if you want to allow multiple nodes to be dragged and dropped.
$mouseevents = kTrue - so that you can find out the line number where the drop occurred.
$dropbetweenlines = kTrue - so the user can see where the dragged nodes will be added.
$dragmode = kDragData - if you want to allow the user to drag nodes.
$dragrange = kRangeWindow - if you want to limit dragging nodes to the same window
$dropmode = kAcceptAll - if you want the list to accept drops
$hiliteline = kTrue - so that the object hilites during drag and drop.

There is a demo included with this tip. Click the Run Demo button in the StudioTips Browser to open the demo window. The sample code below is used in the demo window.

The $event method of the treelist object is as follows:

; $event method of a treelist object,.

On evDrop

; Get the visible node where the user dropped onto, and the previous node.
Calculate VisLineNum as mouseover(kMLine)
Do $cobj.$getvisiblenode(VisLineNum) Returns rDropNode
Do $cobj.$getvisiblenode(VisLineNum-1) Returns rPrevVisNode

; Get the selected nodes.
Do pDragField.$getselectednodes(List)

If pDragField.$objtype=kTreeList

   ; Add the selected nodes to the treelist.
   Do method addSelectedNodes (List,rDropNode,rPrevVisNode) Returns AddedNodesList

   ; If the drag is coming from the same treelist remove the selected nodes.
   If pDragField=$cobj

      ; Remove the old nodes.
      For List.$line from 1 to List.$linecount step 1
         Do $cobj.$remove(List.C1)
      End For

   End If

   ; Reset the current node to be the first added node.
   Do $cobj.$setcurrentnode(AddedNodesList.1.C1)

   ; Get the list of nodes selected in the target list.
   Do $cobj.$getselectednodes(List)

   ; Deselect any selected nodes in the target list.
   For List.$line from 1 to List.$linecount step 1
      Do List.C1.$multipleselect.$assign(kFalse)
   End For

   ; Select the added nodes.
   For AddedNodesList.$line from 1 to AddedNodesList.$linecount step 1
      Do AddedNodesList.C1.$multipleselect.$assign(kTrue)
   End For

End If

The addSelectedNodes method which is called by the $event method is as follows:

; Method: addSelectedNodes(pSelectedNodesList,prDropNode,prPrevVisNode)

; Define the NewNodesList
Do NewNodesList.$cols.$add('noderef',kItemref)

If prDropNode.$level=prPrevVisNode.$level-1

   ; The drop took place just after the last child node of the previous parent.

   ; Set the parent node to be the previous node's parent.
   Do prPrevVisNode.$nodeparent() Returns rParentNode

   ; Add the dropped nodes after the previous node.
   For pSelectedNodesList.$line from pSelectedNodesList.$linecount to 1 step -1

      Set reference rNode to pSelectedNodesList.C1
      Do rParentNode.$addafter(prPrevVisNode,rNode().$name) Returns rAddNode
      Do NewNodesList.$add(rAddNode)

   End For

Else

   If prDropNode.$level=1 ;; Root node drop.

      ; Set the treelist object as the parent node.
      Set reference rParentNode to $cobj

   Else

      ; Set the parent node.
      Do prDropNode.$nodeparent() Returns rParentNode

   End If

   ; Loop through the list backwards, adding nodes before the drop node.
   For pSelectedNodesList.$line from 1 to pSelectedNodesList.$linecount step 1

      Set reference rNode to pSelectedNodesList.C1
      Do rParentNode.$addbefore(prDropNode,rNode().$name) Returns rAddNode
      Do NewNodesList.$add(rAddNode)

   End For

End If
Quit method NewNodesList

Treelist Columns

The treelist object supports displaying columns of data for each node in the treelist. If you are unsure of what that looks like, click the Run Demo button in the StudioTips Browser window to view a columns list style treelist.

To set up a treelist with additional columns you need to do the following:

Select the treelist object > press F9 to open the Properties Manager > select the Appearance tab.
Set the following properties in order to display additional columns of data for each node.

$designcols - to the number of columns of data you wish to display. Column one is the treelist nodes column.
$hideheader - to kFalse so that the columns header will be displayed.
$columnnames - to a CSV string of names you want to use for the column headers.

To display data in the treelist columns you have to set the $rowdata node property with a row variable that has the data you want to display in the correct order. Column 1 of the $rowdata will be displayed in column 2 of the treelist object columns, column 2 of the $rowdata in column 3 of the treelist object columns, etc.

There are two ways you can load the $rowdata into the treelist object:

Adding a Rowdata column to the list variable which you use to $setnodelist and preloading that column for each line in the list with the $rowdata you want displayed. Once the list variable is prepared you use $setnodelist to load the treelist object.
Assigning the $rowdata property using notation. (This is the technique I prefer.) See the $rowdata topic in this section for more information.

$edittext

$edittext(iColumnNumber)

Lets the user edit the text for a column in the currently selected line, when the tree is the current field. The node (column 1) can only be entered if its $enterable property is kTrue. You can control whether other columns can be entered using the evTreeListEditStarting event.

To stop columns from being editable add this to the $event method of the treelist object:

; Prevent text editing of columns.
On evTreeListEditStarting
Quit event handler (Discard event)

You only need to worry about the $edittext method if you want to initiate setting the user to edit a specific column in the treelist object. By deafult the user can click on any column in the treelist object and Omnis Studio will let the user edit the column value if you didn't discard the evTreeListEditStarting event.

$getcolumnalign

$getcolumnalign()

Returns the alignment of the specified column. This only applies to trees with multiple columns.

; Get the column alignment for the 2nd column.
; kAlign will be: kCenterJst, kLeftJst, or kRightJst
Do irTree.$getcolumnalign(2) Returns kAlign

$rowdata

Each node in a treelist has a $rowdata property. You can set any row variable to the $rowdata property at any time. Once the $rowdata property has been set you can get the $rowdata from the node.

The data in the columns of the $rowdata property is displayed in the columns of a treelist object which has the $designcols property set to a value greater than zero.

; Set the row data for the specified node.
Do rNode.$rowdata.$assign(Row)
; or
Calculate rNode.$rowdata as Row

; Get the row data from the specified node.
Calculate Row as rNode.$rowdata

The following sample code demonstrates how you can get the value for a column in the row data which the user has just edited.

On evTreeListEditFinished

; Get the $rowdata for the current node.
Calculate Row as pNodeItem.$rowdata

; Get the value of the clicked column.
; The $rowdata column number is one less than the treelist column number.
Calculate Value as Row.[pColumnNumber-1]

$setcolumnalign

$setcolumnalign(iColumnNumber,kAlign)

Sets the alignment of the specified column. You can specify kAlign as kLeftJst, kRightJst, or kCenterJst. The property $columnalignmode controls how $setcolumnalign affects the field. This only applies to trees with multiple columns.

; Set the column alignment for the 2nd column.
Do irTreeObj.$setcolumnalign(2,kCenterJst)