Tree-view - %N.Mtv[options]
In this section:
- Bar format - %Nbr[options]
- Horizontal and vertical scroll bars %hx and %vx
- List box format - %n.mls[options]
- Multiple selection box - %n.mms
- List-view - %lv[options]
- Tree-view - %N.Mtv[options]
- Branch-view - %bv[options]
- Colour palette - %cl[options]
%bv (Branch View) has superseded %tv. Consider using that control instead.
The %tv (Tree Control) format is used to construct a hierarchical list box that is analogous to the type of control sometimes used to display a directory structure. %bv (Branch View) is a newer format that is similar to %tv but has more options (see below). %tv takes a CHARACTER array followed by an INTEGER argument giving the size of the array. The final argument is an INTEGER argument (call it sel) that is used to receive the index of the chosen item. The format modifiers N and M set the width and depth of the tree-view in 'average characters'. The control operates in a manner that is similar to a listbox except that the first two characters of each string have a special meaning. The first character must be a capital letter ('A' - 'Z') indicating the level of the item within the hierarchy. The second letter should be a 'C' if the item is to be displayed compactly (i.e. not displaying any children) and 'E' if the item is to be displayed expanded. Consider the following list of things:
AEFood
BEFruit
CCApples
CCPears
BCNuts
CCHazel nuts
CCBrazil nuts
AEDrink
BCAlcoholic
BCNon-alcoholic
The children of a node (together with any of their children, etc.) are placed immediately beneath the parent node. In the example shown the types of nuts would not immediately be shown because of the 'C' in 'BCNuts'. Any node is expanded and contracted by simply by clicking on it. Usually you would code 'C' for the second character of each string. This would produce an initial display showing only the top level. As nodes are expanded and contracted, the information is stored in the strings. This means that, if the strings are used to display the hierarchy a second time, the display will start from where it left off. You could even store the strings in a file so that the expanded state would be the same from one run to another.
Items with a lower case letter or a blank in the first position are ignored and never displayed. This provides a means to hide elements, or to provide space for the display to grow dynamically. If a node has no children you can use 'E' or 'C' - there is no difference.
Notice that it makes no sense for a level 2 item (say) to be followed immediately by a level 4 item. An item may not be followed immediately by its 'grandchildren'. This condition will be detected as an error. Conversely, a level may decrease by any amount.
%tv (Tree Control) can take a call-back function. The call-back function may use the index of the chosen item (i.e. the argument sel) and can also get the value of CLEARWIN_INFO@(TREEVIEW_ITEM_SELECTED'). This value will be equal to 1 if the call-back is responding to a double click mouse event.
By default, the tree-view displays bullet marks to the left of the nodes. By using a grave accent with %tv, the bullet marks are replaced by icons. When the grave accent is used, the third character in each string is interpreted as an index ('A' - 'Z') into a list of icons. This icon list is supplied as an extra argument that consists of icon resources separated by commas (e.g. 'ICON1,ICON2,ICON3'). You should construct the icons in such a way that the image is confined to the top left 16 x 16 corner. The remainder of the icon should be filled with the transparent colour.
By providing a call-back that examines the expansion indicator (character two of each string) it is possible to change the icon index to reflect whether or not the icon is expanded. If you perform a change of this sort you should pass the main array to window_update@ to force the control to be updated.
The following example illustrates the use of tree-view controls:
WINAPP
BLOCK DATA
CHARACTER*30 contents(56)
INTEGER item
COMMON/C/contents
COMMON/I/item
DATA contents/
+ 'ACABook', 'BCAChapter 1', 'CCASection 1.1',
+ 'CCASection 1.2', 'CCASection 1.3', 'CCASection 1.4',
+ 'BCAChapter 2', 'CCASection 2.1', 'CCASection 2.2',
+ 'CCASection 2.3', 'CCASection 2.4', 'BCAChapter 3',
+ 'CCASection 3.1', 'CCASection 3.2', 'CCASection 3.3',
+ 'CCASection 3.4', 'BCAChapter 4', 'CCASection 4.1',
+ 'CCASection 4.2', 'CCASection 4.3', 'CCASection 4.4',
+ 'BCAChapter 5', 'CCASection 5.1', 'CCASection 5.2',
+ 'CCASection 5.3', 'CCASection 5.4', 'BCAChapter 6',
+ 'CCASection 6.1', 'CCASection 6.2', 'CCASection 6.3',
+ 'CCASection 6.4', 'BCAChapter 7', 'CCASection 7.1',
+ 'CCASection 7.2', 'CCASection 7.3', 'CCASection 7.4',
+ 'BCAChapter 8', 'CCASection 8.1', 'CCASection 8.2',
+ 'CCASection 8.3', 'CCASection 8.4', 'BCAChapter 9',
+ 'CCASection 9.1', 'CCASection 9.2', 'CCASection 9.3',
+ 'CCASection 9.4', 'BCAChapter 10', 'CCASection 10.1',
+ 'CCASection 10.2', 'CCASection 10.3', 'CCASection 10.4',
+ 'BCAChapter 11', 'CCASection 11.1', 'CCASection 11.2',
+ 'CCASection 11.3', 'CCASection 11.4'/
END
INTEGER FUNCTION test()
c--------------------------------------------------------------
c Call-back function sets the icon for
c each object according to whether it is expanded or not
c--------------------------------------------------------------
CHARACTER*30 contents(56)
INTEGER item
COMMON/C/contents
COMMON/I/item
CHARACTER*30 string
string=contents(item)
IF(string(2:2).EQ.'E')THEN
string(3:3)='B'
ELSE
string(3:3)='A'
ENDIF
CALL window_update@(contents)
test=2
END
c------------------------------------
c Main program - just call WINIO@
c------------------------------------
INCLUDE <windows.ins>
EXTERNAL test
CHARACTER*30 contents(56)
INTEGER item
COMMON/C/contents
COMMON/I/item
INTEGER a
a=winio@('%ww%ob%pv&')
a=winio@('%^`20.15tv&',
+ contents,56,item,'CLOSED_BOOK,OPEN_BOOK',test)
a=winio@('%cb%ff%nl%cn%`bt[OK]')
END
Link this with a resource file containing the following:
CLOSED_BOOK ICON BOOK1.ICO
OPEN_BOOK ICON BOOK2.ICO
