The Treeview ActiveX control - the basics

Youve decided that you need to use the Treeview and now you need to learn how. But man, the documentation leaves
you in more doubt, leaving far too many questions unanswered. Youve also searched the UT and referenced the few
articles available, and while they hel to fill in many gas, they more hand you a fish rather than teach you to fish, and
youre the !ind of erson who needs to !now the "whys of things. # feel your ain, because # $ust went through the e%act
same thing last month.
The following is intended to describe the basic factors relating to imlementing the &ctive' Treeview comonent
sulied with (isual )o%*ro. #n this case the information is alicable to ()*+ ,*-.
This document does not include the #mage.ist control that can be used to add images to nodes, nor does it include the
.istview control often seen used in con$unction with the Treeview control /0indows 1%lorer, for e%amle, as the right
side dislay ane2.
&dding the control to a form
This is started in the same way as any other control is added. #n this case the &ctive' 3ontrol /4.13ontrol2 icon is
clic!ed on the /standard2 )orm 3ontrols toolbar. Then the mouse is moved to the area of the form where the to left
corner of the control is to be ositioned, downclic!ed, then dragged to where the bottom right corner of the control is to be.
5eleasing the mouse at the aroriate oint leads to a small delay and then resentation of the #nsert 4b$ect dialogue
/)igure - below2. & listbo% in the dialogue, titled 3ontrol Tye, shows the available controls installed in the system.
6itting the m !ey ositions the listbo% to the first one with the name starting with m. #n my case this was the
7acromedia )lash )actory 4b$ect. 3lic!ing on the scroll bar /downward2 of the listbo% eventually revealed the 7icrosoft
Treeview 3ontrol 8 two in my case9 7icrosoft Treeview 3ontrol :.; /,*<2 and 7icrosoft Treeview 3ontrol, version =.;
/,*>2.
Figure 1
# initially selected the latest version /:.; ,*<2 but found that later use of the )- !ey to obtain its hel roduced nothing.
Trying the other control instead /version =.; ,*>2 did result in a dislay of its hel when # ressed the )- !ey. 7y guess is
that the :.; ,*< version came with the ()*? ublic beta that # had downloaded and installed on the same machine. The
)- !ey does resent hel for the control but it is very oorly organi@ed and there are missing roerties and methods. #
recommend the use, in addition to )-, of the 4b$ect Browser sulied with ()*+ and later versions.
AoubleBclic!ing on the
7icrosoft Treeview 3ontrol
version =.; ,*> results in
the designated form area
being filled as shown in figure
> to the left and the roerty
sheet as shown in figure C at
the right here. The roerty
sheet effectively lists a
merged set of roerties 8
those alicable to ()*s
control and those secific to
the Treeview control. The
latter are shown in blue font
in the values side of the
roerty sheet.
0or!ing with the Treeview control roerties
4nce the Treeview control is shown on the form design surface, clic!ing anywhere on it to ma!e it the selected control
and then hitting the )- !ey will resent a 6el file for it. #n addition, rightBclic!ing on the /selected2 Treeview control
resents a ou menu with the selection Tree3trl *roerties as the last one. 3lic!ing on that item resents the
Tree3trl *roerties dialogue as shown in figure <. &n e%amle of its use is shown below /figure =2, obtained by clic!ing
on the 3hec!bo%es chec!bo% in the dialogue and then clic!ing &ly and then clic!ing 4D. Eotice too that the
dialogue has three tabs.
Figure 2
Figure 3
Figure 5
0hen you wish to maniulate the Treeview roerties /above2 programmatically you must use the 4b$ect roerty name
within the name structure. Based on the figures here, and assuming the Treeview control has been laced on the form
named )orm-, the control would be /rogrammatically2 disabled by coding9
)orm-.4lecontrol-.4b$ect.1nabled F .).
# could not find this roerty of the ()* 4.13ontrol mentioned in the roerty sheet or anywhere one might regularly
refer to during develoment. 6owever, it is mentioned in the section titled 7aniulation of 4b$ects with &utomation under
the toic Using &ctive' 3ontrols, under the toic &dding 4.1 4b$ects to &lications, under the toic ,haring
#nformation and &dding 4.1, under the toic #nteroerability and the #nternet, under the toic 1%tending &lications
in the Using (isual )o%*ro art of the online 6el. *hewwwG The only way # found it was by using the ,earch otion.
Hoing through the 3ontent # stoed clic!ing deeer in the toic tree once # came uon the toic #nteroerability and
the #nternet because it seemed unrelated to the ob$ect /un2 of my need. #t is noteworthy that the ()* documentation
content itself is resented in a Treeview control.
*rogramming the Treeview control
#n essence, the Treeview can be used to resent any data that is hierarchical in nature. #t can also be rogrammed to
ermit the user to ma!e changes to the data resented, though of course if you do so you must also rogram to change
the actual data in addition to acceting the userBtyed revisions. )or e%amle, 0indows 1%lorer allows you to rename a
directory name resented in its left ane and in the bac!ground it also erforms an actual rename of the directory.
7uch of the data in our ()* alications is hierarchical. The Treeview can be used to give a user access to a list of toB
level entities with the ability to IdrillBdownI to obtain details ertinent to a secific item. &n e%amle might be a root level
list of JassemblyJ art numbers, with comonent art numbers available on e%anding the node. ,ubBassemblies listed in
that e%ansion could also be made e%andable to show their comonent arts.
The Treeview control itself is $ust an emty bo%. To use it you must first fill it with the information you wish to resent.
4nce youve done that, you li!ely want to react to actions that the user erforms on the content. You may even want to
store ertinent information after the user indicates that they have finished their wor! with the form or the record/s2
dislayed on the form.
#nherent in the Treeview control are two additional controls. The Nodes collection ob$ect is used to create and maintain
the content of the Treeview while the Node ob$ect can be used to maniulate the dislay andKor content of a secific node
within the Treeview content. The Nodes ob$ect can also be used to maniulate a secific node using its Item roerty.
The first thing that you need to do is to fill the Treeview with userBviewable content. To do this you will use the &dd/2
method of the Eodes collection ob$ect. The synta% of the &dd/2 method is /mostly from the 6el file29
4EewEode F tvw5ef.Eodes.&dd/LrelativeM,LrelationshiM,L!eyM,te%t,LimageM,LselectedimageM2
This method adds a node to the sub$ect Treeview control, ositioned based on the relative and relationship argument
content. The first node added is given the /imlied2 inde% value of - and nodes added subsequently each have their inde%
value incremented by -. ,ince nodes can be added in any order, and can also be Remove!d, the inde% cannot be used
reliably to ste sequentially through the tree as it is dislayed to the user. This is also the case when the "orted roerty
is set to T5U1. The !ey roerty may be a better way to directly access some secific node. #t is ossible, though, that
your use will not even need to access a secific node, in which case neither the index nor the key roerty is relevant.
7any consider the Treeview to be a slow control, articularly deending on the data source and its record count. #n such
cases it may be aroriate to dynamically add nodes to the /ne%t2 child level only as the user e%ands the node.
The arguments for the &dd/2 method are defined below /it returns a reference to the added node29
Figure #
Argument $%&lanation
relative
4tional and, when secified, identifies a pre-existing node by either its inde% value or its !ey. The
relationshi of the node referenced in this arameter and the new node being added by this statement is
defined in the ne%t arameter. 0hen this argument is omitted, the node added is laced in the last osition
of the to node. Eote that relative is used here in the sense of "family /child, arent, etc.2.
relationship
4tional and, when secified, states the lacement of the node being added in relation to the relative
identified above. The ermissible values are9
'alue (escri&tion )onstant
;
First. Node is laced before all other nodes at the same level of the node named
in relative.
tvwFirst
-
*ast. Node is laced after all other nodes at the same level of the node named
in relative. &ny Eode added subsequently may be laced after the one added as
*ast.
tvw*ast
>
/default2
Ne%t. Node is laced after the node named in relative. tvwNe%t
C +revious. Node is laced before the node named in relative. tvw+revious
< )hild. Node becomes a child node of the node named in relative. tvw)hild
key
4tional and, when secified, is a unique string e%ression that can be used to access this secific node
later. ,afest to ensure at least one alhabetic in the string as one that is all numbers may be interreted as
numeric, causing an error. Eote that a node can be accessed directly in the Nodes collection by index or
by key value. Using the !ey value may be the most ractical.
text 5equired. The string that is dislayed in the Treeview control for the node being added.
image
4tional. &n integer value to set the icon from the /otional2 associated Image*ist control that is identified
in the #mage.ist roerty of the Treeview control.
selectedimag
e
4tional. &n integer value to set the icon from the /otional2 associated Image*ist control, to be dislayed
when the node is selected.
,hown below is some samle code used to fill a very simle Treeview on a form. #t is ta!en from the subBclassed
Treeview, coded in a method named *oulateTheTree/2 invo!ed in the forms #nit/2. The inut is a table of two field
records where TyeEame will constitute a to /root2 node and ,ubTye will be a child of that TyeEame. The
records are sourced from a local view which secifies A#,T#E3T and sorts the records ascending by TyeEame and
,ubTye. The record format in this case assures that every to /root2 node will have at least one child.
,3&E
#) 17*TY/,ubTye2 45 17*TY/TyeEame2 NN guard against an invalid record
1.,1 NN we have content that is valid
O 0hen the ITyeEameI changes, we need to create a new JrootJ /arent2 item
#) TyeEame PQ m..astTye
m..astTye F TyeEame
m..ast5ootEumber F m..ast5ootEumber R -
m..ast5ootDey F &..T5#7/TyeEame2 S
R *&A./&..T5#7/,T5/m..ast5ootEumber, <, ;22, <, I;I2
This.Eodes.&dd/ , S NN e%isting !ey string or inde% number
tvwEe%t, S NN relationshi to above
m..ast5ootDey, S NN !ey /string2
TyeEame, S NN te%t to be dislayed
, S NN imageT in #mage.ist
2 NN ,elected#mageT in #mage.ist
1EA#)
O Eow we add the I,ubTyeI as a child node of the current arent
This.Eodes.&dd/ m..ast5ootDey, S NN e%isting !ey string or inde% number
tvw3hild, S NN relationshi to above
, S NN !ey /string2
,ubTye, S NN te%t to be dislayed
, S NN imageT in #mage.ist
2 NN ,elected#mageT in #mage.ist
1EA#) L17*TY/,ubTye2 45 17*TY/TyeEame2M
1EA,3&E
4ther roerties and methods of the Eodes collection are9
+ro&erties
)ount returns the total number of items in the collection.
Item
returns a secific node /reference2, by osition /inde%2 or by !ey.
1%amles9
oEode5ef F tvw5ef.Eodes.#tem/inde%2
oEode5ef F tvw5ef.Eodes.#tem/!eyBvalue2
,ethods
)lear removes all node ob$ects from the Treeview.
Remove
removes a secific node /reference2, by osition /inde%2 or by !ey.
1%amles9
Ftvw5ef.Eodes.5emove/inde%2
Ftvw5ef.Eodes.5emove/!eyBvalue2
The )ount roerty is useful if you have the need to ste through the entire Nodes collection because it always reflects
the e%act count of nodes in the entire tree.
The Remove! method will remove a secific node, and if you have chosen to dynamically add child nodes as a arent
node is e%anded then this method can be used to remove those same nodes once the user has collased the arent
node. 1very node you Remove! decrements the )ount roerty by one.
4nce the Treeview has been oulated /all nodes or $ust the to node level2 the users can access and maniulate things
in it. ,o the ne%t thing you will do is to react to the users actions. 0hile there are more /all Treeview *17s are
summari@ed, listed alhabetically at the end of this article2, the most common events of the Treeview control that you will
code for are9
Action $%&lanation
)olla&se! occurs when a Node ob$ect is collased. By definition the node has children.
$%&and! occurs when a Node ob$ect is e%anded, e%osing its children to user view.
Node)hec-!
occurs only when the )hec-.o%es roerty is T5U1, when a chec!bo% is
clic!ed.
Node)lic-! occurs when a Node ob$ect is clic!ed, but not when a /node2 chec!bo% is clic!ed.
#n all cases above a node ob$ect /reference2 is assed as the .43&. arameter, named node.
The Node ob$ect has several roerties and a single method. # have bro!en the roerties down into two categories 8
regular and ob$ect /references2. The roerties are9
Regular
)hec-edO, - Logical
&lies when )hec-.o%es is T5U1. .). means
UEchec!ed.
)hildren
Numeri
c
5eturns the number of children for the node. ; means none.
$%&andedO Logical .T. means the node is e%anded, .). that it is collased.
$%&andedImageO Integer ,ecifies an image in an Image*ist control.
Full+ath String 5eturns the fully qualified ath /to node to this node2.
ImageO Integer ,ecifies an image in an Image*ist control.
Inde%
Numeri
c
5eturns the unique inde% of this node in the collection.
/e0O String Unique value to identify this secific node of the collection.
"electedO Logical T5U1 indicates the node is selected, )&.,1 that it is not.
"electedImageO Integer ,ecifies an image in an Image*ist control.
"ortedO Logical ,ecifies if nodes at level of assed node are sorted or not.
Te%tO String The string value that aears in the treeview for this node.
OThese roerties can be set as well as interrogated.
-The 3hec!ed roerty was not in the 6el, but rather found using the 4b$ect Browser.
1b2ect
)hild To obtain an ob$ect reference to the first child of this /assed2 node.
First"ibling To obtain an ob$ect reference to the first node at same level as this node.
*ast"ibling To obtain an ob$ect reference to the last node at same level as this node.
Ne%t To obtain an ob$ect reference to the ne%t node at same level as this node.
+arent To obtain /or setU2 an ob$. ref. that is /or to be setU2 arent of this node.
+revious To obtain an ob$ect reference to the revious node at same level as this.
Root To obtain an ob$ect reference to the root node of the Treeview.
The sole method is $nsure'isible! and ta!es a node ob$ect reference as its arameter. #t will e%and Treeview node/s2
andKor scroll the Treeview as necessary to ensure that the assed node is made visible to the user.
The documentation for the "elected roerty mentions another roerty named 7ulti,elect /of the TreeviewU2 but #
could find nothing to confirm that it e%ists as a real roerty of the Treeview control and Treeviews observed oeration
suggests that it is not an alicable roerty.
Using the 4b$ect Browser /()*+ and later2 to review )omctl*ib /which is the 7icrosoft 0indows 3ommon 3ontrols =.;
/,*>22 and ,")omctl*ib /which is the 7icrosoft 0indows 3ommon 3ontrols :.; /,*<22, the following differences were
noted between the roerties enumerated in the 6el versus those listed. # dont !now that any of the named roerties
below can actually be used in a rogram /save 3hec!ed, which can for sure2.
)ound in both classes using the ob$ect browser9
+ro&ert0 (i33erence
Tag ,tores any e%tra data needed for your rogram.
'isible 5eturnsKsets logical controlling if ob$ect is visible or hidden.
)ound only in ,")omctl*ib /:.; /,*<229
+ro&ert0 (i33erence
.ac-)olor 5eturnsKsets the bac!ground color used for dislayed te%t of a Node ob$ect.
.old 5eturnsKsets logical controlling if te%t of Node is dislayed in bold font.
)hec-ed 5eturnsKsets logical controlling if the Node ob$ect is chec!ed or not.
Fore)olor 5eturnsKsets the foreground color used for dislayed te%t of a Node ob$ect.
&s noted earlier, all four of the most used events of the Treeview control have a node ob$ect reference assed as the
single arameter. This fact leads to some interesting caabilities as far as coding to refer directly to other related nodes is
concerned. ,ome e%amles are shown below. Dee in mind that node is the .43&. arameter name assed to the
event.
#) node.3hildren Q ; NN node has children
O )or illustrative uroses we will go bac!wards chec!mar!ing each child
*rior3hild5ef F node.3hild..ast,ibling NN P BBBBBBBB T-
)45 ' F - T4 node.3hildren
*rior3hild5ef.3hec!ed F .T. NN chec!mar! this child
*rior3hild5ef F *rior3hild5ef.*revious NN P BBBBBBBB T>
E1'T '
1EA#)
The line commented T- above shows how an ob$ect reference to the last child node can be obtained directly using the
/ob$ect reference2 roerties of the passed node. This wor!s because each roerty is actually a Eode ob$ect /reference2
itself, so each has all of the roerties of a node ob$ect. This line of code is actually "saying give me an ob$ect reference
to the last sibling /last node at level /..ast,ibling22 node of the child node /.3hild2 of the node in rocess /assed in
arameter /node22. The same line might alternately have been coded as follows9
3hild4f*assed F node.3hild
*rior3hild5ef F 3hild4f*assed..ast,ibling
The line commented T> above simly shows how the /memvar2 ob$ect reference created by the line annotated T- can
itself be used to reference the rior /child2 node. Because the Nodes collection ob$ects Item roerty returns a Node
ob$ect reference, all of the Node *17s can be addressed in a VEodes.#temV statement. 1%amles /unrelated to above2
are9
3hild3ount F This)orm.tvw5ef.Eodes.#tem/-2.3hildren
)irst4fAaddys F This)orm.tvw5ef.Eodes.#tem/D1Y;;+2.*arent.)irst,ibling
7iscellaneous notes about the Treeview control
0hile # could find nothing definitive on the matter, there li!ely are limits inherent in the control itself.
4ne source ut the limit of nodes in a Treeview at C>,;;;. #f this is in fact the case, # assume that dynamically adding
nodes as the user e%ands a arent node and removing those /added2 children once the user collases that arent can
still ma!e the control ractical for most uses. 4f course this would also be deendent on the users collasing some of
those e%anded nodes from time to time.
# imagine, too that there is a limit regarding the length of any !ey value /string2 that you can use. 3ant say if there might
be a limit on the cumulative length of all !ey string values.
# could not find any limit stated for the te%t /label2 roerty of a node but again # susect that there is one.
# couldnt locate anything definingKdescribing errors that might occur when using the Treeview control, nor do # !now if
such errors are traable within ()*.
The Treeview is the control used in the 0indows 1%lorer alications left ane to dislay the volumes, directories and
secial files of the system /the right ane is resented using the .istview control2. The Treeview is also used in the
*ro$ect 7anager window in ()*.
The Treeview control is often used by software installation routines to resent selectable otions for inclusion. #n this case
the 3hec!Bo%es roerty is often T5U1.
)inally, it is worth !eeing in mind that while the functionality of the Treeview control is well understood by systems
eole, the same cannot be said for your average clerical user. ,o you will be wise to e%lain its use in some detail in
your alication documentation andKor send significant time going over its usage in user training sessions.
# hoe that this article has heled you to imlement your own Treeview controls with a little more ease than # e%erienced.
There are more comle% and owerful methods and events available in the control and # e%ect that you will be able to
lay with them once you have succeeded in imlementing your first one.
,ummary of all *17s for the Treeview control
This summary does not include the Nodes collection ob$ect or the Node ob$ect because their *17s are all documented in
the body of the article.
The Treeview control itself has several roerties, events and methods available. Their names and a summary of their
functionality are listed below.
A3ter*abel$dit $vent
4ccurs after a user edits the labelO of the currently selected Eode or .ist#tem ob$ect. # susect that this event only occurs
when the .abel1dit roerty is set .T. O# believe this refers to the te%t roerty of the node /refer to Eodes.&dd/22.
.e3ore*abel$dit $vent
4ccurs when a user attemts to edit the labelO of the currently selected .ist#tem or Eode ob$ect. O# believe this refers to
the te%t roerty of the node /refer to Eodes.&dd/22.# susect that this event only occurs when the .abel1dit roerty is
set .T.
)hec-bo%es +ro&ert0
5eturns or sets a value that determines if chec!bo%es aear left of each dislayed nodes te%t.
)olla&se $vent
Henerated when any Eode ob$ect in a Tree(iew control is collased.
(ro&4ighlight +ro&ert0
5eturns or sets a reference to a Eode or .ist#tem ob$ect that is highlighted with the system highlight color when the cursor
moves over it. Lgiven this descrition, # have no idea what the Aro word is doing in its nameM
$%&and $vent
4ccurs when a Eode ob$ect in a Tree(iew control is e%anded. That is, when its child nodes become visible.
FullRow"elect +ro&ert0
5eturns or sets a value that secifies if the entire row is selected. # susect that this refers secifically to the selected
highlight colour and that a .T. value causes the chec!bo% andKor image, when either is resent, to also be highlighted.
5et'isible)ount ,ethod
5eturns the number of Eode ob$ects that fit in the internal area of a Tree(iew control.
4itTest ,ethod
5eturns a reference to the .ist#tem ob$ect or Eode ob$ect located at the coordinates of % and y. 7ost often used with dragB
andBdro oerations to determine if a dro target item is available at the resent location.
4otTrac-ing +ro&ert0
5eturns a value that determines whether mouseBsensitive highlighting is enabled. Lnot sure what this means, actually,
because when # have the roerty Unchec!ed in the Tree3trl *roerties dialogue the "toolti still is dislayed when #
mouse over node te%t that e%tends near or beyond the right edge of the dislayM
Image*ist +ro&ert0
,ecifies the name /ob$ect reference2 of a searately instantiated /and filled2 #mage.ist control. This roerty is not
described in the documentation, other than aearing in the Tree3trl *roerties dialogue.
Indentation +ro&ert0
5eturns or sets the width of the indentation of ob$ects in a control.
*abel$dit +ro&ert0
5eturns or sets a value that determines if a user can edit labels of .ist#tem or Eode ob$ects.
*ine"t0le +ro&ert0
5eturns or sets the style of lines dislayed between Eode ob$ects.
Node)hec- $vent
4ccurs when the 3hec!Bo%es roerty equals True and a Eode ob$ect is chec!ed or unchec!ed. The chec!bo% will have
the stateas set by the oerator uon entry to this event. Lthis event does not occur when a node is chec!ed or unchec!ed
rogrammaticallyM Lthere seems to be a bug that the node assed in the arameter cannot have its chec!bo% toggled to
the oosite state /from its state on entry2M
Node)lic- $vent
4ccurs when a Eode ob$ect is clic!ed. Lthe nodes chec!bo% does not aear to be accessible through this event, at least
as far as the node assed as the arameter is concernedM
Nodes +ro&ert0
5eturns a reference to a collection of Tree(iew control Eode ob$ects. +ath"e&arator +ro&ert0
5eturns or sets the delimiter character used for the ath returned by the )ull*ath roerty.
"croll +ro&ert0
5eturns or sets a value that secifies if scrollbars are dislayed.
"electedItem +ro&ert0
5eturns a reference to a selected .ist#tem or Eode.
"ingle"el +ro&ert0
5eturns or sets a value that secifies if an item is e%anded when selected. Lanother case where the roerty name
doesnt seem to reflect its functionalityM
"orted +ro&ert0
5eturns or sets a value that determines whether the child nodes of a Eode ob$ect are sorted alhabetically.
5eturns or sets a value that determines whether the root level nodes of a Tree(iew control are sorted
alhabetically.
0hen set to T5U1, nodes are li!ely not accessible in sequential inde% order.
"tart*abel$dit ,ethod
1nables a user to edit a label. Lnot sure e%actly how this fits inM
"t0le +ro&ert0
5eturns or sets the tye of grahics /images, te%t, lusKminus, and lines2 and te%t that aear for each Eode ob$ect in a
Tree(iew control.