Omnis Technical Note TNNO0002

Expanding And Collapsing A Tree

For Omnis Studio version 1.2
By Peter Kelly

What should I do when a tree expands or collapses ?

Contents

Writing Code to Handle Expand or Collapse
Node Basics
evTreeExpand
evTreeCollapse
Building Nodes Only Once

Writing Code to Handle Expand or Collapse

The Omnis tree control will by default handle the expanding and collapsing of nodes within your
tree for you.
If you have a fully populated tree and your trees content is fixed i.e. the nodes at all levels
will not change, then you can sit back and let the user expand and collapse the tree without
having to write any code.

If however you are writing a control that is for example displaying the files on your hard drive and
each node in the tree represents a directory on your drive, then the contents of each node should
probably be reloaded each time the node is expanded. Omnis allows you to hook into the expanding
and collapsing of nodes using two message, evTreeExpand and evTreeCollapse.


Node Basics

Here are three basic points to remember about nodes before we start explaining about the expand and collapse message system:

Every node has a expanded boolean state Every node has a list of child nodes. Even if a node is collapsed visually, the node may still have child nodes When a node message is sent to the tree control a message parameter is always passed indicating what node the message is for. e.g. for evTreeExpand pNodeItem is the node being expanded.


evTreeExpand

Normally when a node expands, Omnis first sends a message to the tree control informing the developer that a node is about to be expanded. After the message has been processed by $event, if the node being expanded has child nodes, then the node is expanded and the child nodes are made visible.


This message gives the developer a chance to populate the node before Omnis expands it, thus contents ofthe node would always be up to date. The danger about always populating the node on the
evTreeExpand message is that unless you remove the child nodes on the evTreeCollapse message, the
next time you get aevTreeExpand message you will add another set of child nodes to the expanding node. There are ways around this ( see Building Nodes Only Once later ). The main point to remember about
the expand and collapse messages is that Omnis will only visually add or remove the nodes from the tree. They still exist in
the node itself.

Here is an exampe of a tree being expanded and having 3 child nodes added to each expanding node.

##### Method '$event' #####
No. Local Variable Type Subtype Init.Val/Calc
1 oop Short integer (0 to 255)

No. Method text
1 On evTreeExpand ;; Event Parameters - pNodeItem( Itemreference )
2
3   ; Add 3 default child nodes to the expanding node
4   ; For loop from 1 to 3 step 1
5      Do pNodeItem.$add(con("NewChild ",loop))
6   End For

evTreeCollapse

This message is sent to the control when a tree node is about to be collapsed. Depending on what
you aredoing with your tree, you may want to respond to this message. In the example above for
evTreeExpand, we are always adding nodes to our expanding node. If we do remove the child
nodes on collapse, we will
end up with yet more nodes every time we expand it.

Here is an example using the evTreeCollapse message where we always clean up the nodes added
on the evTreeExpand message

##### Method '$event' #####
No. Local Variable Type Subtype Init.Val/Calc
1 loop Short integer (0 to 255)

No. Method text
1 On evTreeCollapse ;; Event Parameters - pNodeItem(Itemreference)
2
3 ; Node is closing, so clear all child nodes now
4 Do pNodeItem.$clearallnodes()

Building Nodes

Only Once If your tree has fixed nodes, in other words the contents of the nodes will never change,
you can save time by only populating expanding nodes once. To do this we need to keep a state of
what nodes have been expanded. There are many ways in which a list of what nodes have been
expanded can be kept, but for this example we will use the $count() method of a node to see of the
node already has child nodes.

Here is an example of a tree control that adds nodes on expand only if the node is empty, and as a
result the evTreeCollapse message does not need to do anything.

##### Method '$event' #####
No. Local Variable Type Subtype Init.Val/Calc
1 loop Short integer (0 to 255)

No. Method text
1 On evTreeExpand ;; Event Parameters - pNodeItem(Itemreference)
2
3    ; Add 3 default nodes to each expanding node only if it does not
     have child nodes
4    If pNodeItem.$count()=0
5     For loop from 1 to 3 step 1
6      Do pNodeItem.$add(con("NewChild ",loop))
7     End For
8
    End If
9
10  On evTreeCollapse ;;Event Parameters - pNodeItem(Itemreference)
11
12    ; Node is closing, but we do not need to do anything


Download RTF document