The Tree-View control presents hierarchical data in a list. This list is indented to show the relationships among the data items. Users can "expand" or "collapse" items in the list to view or hide subsidiary items. One example of a tree-view control is the "Contents" page of the ACUCOBOL-GT on-line manual.
In a Tree-View control, each item in the hierarchical list is identified by an ID that is assigned at the time the element is added to the control. This provides a unique way to identify each item and thus allows for duplicate items at different points in the hierarchy without any confusion. Tree-View ID's are declared in COBOL as USAGE POINTER data items.
Tree-View controls have a variety of special properties, including the ability to store hidden data with any item and to display bitmaps adjacent to the items. The special property called ITEM is used to identify which item in the hierarchy is to be affected by the property values you provide. Typically, you set the value of the ITEM property to the ID of the item to be acted on, and then you set another property (such as ITEM-TEXT or ENSURE-VISIBLE or HAS-CHILDREN or BITMAP-NUMBER) to assign a value or setting to that item. Note that you must set the value of ITEM before you set the other property value in order to get the desired results. ITEM is the "index" for the Tree-View control (see the MODIFY and INQUIRE statements for a description of indexes).
Items in a Tree-View control are placed within the hierarchical list according to "parent" and "child" relationships that you specify. The special property PARENT allows you to specify whether an item is at the top level of the hierarchy (PARENT = 0, the default) or is the child of another item in the hierarchy (PARENT value set to the ID of the parent item).
Another special property of the Tree-View control, HAS-CHILDREN, enables you to specify whether new child items can be added underneath a specific item in the list. When HAS-CHILDREN = 0 (the default), an item has children only if they are already physically present in the control. This means that no additional child items can be added to that item by the user.
If HAS-CHILDREN is set to a non-zero value (such as HAS-CHILDREN = 1), this indicates that the item identified by the ITEM property is entitled to have child items added. This setting is useful when it is impractical to place all of a tree's items in the control at once (see examples immediately following). In this situation, you populate the highest level of the tree and then use this property to identify which of the top-level items are entitled to have children. Then, when the user expands a particular item, you have the program respond to the MSG-TV-EXPANDING event by adding the appropriate child items to the control. The HAS-CHILDREN property tells the control which items can be expanded.
In order to do this, you have to tell the Tree-View whether an item is entitled to have children when you add the item to the control. If you did not do this, the control would not allow the user to expand that item. You establish the ability to add children to an item by setting the property HAS-CHILDREN to "1" when you add the parent item. For example:
MODIFY TV-1, ITEM-TO-ADD = "Parent Item" GIVING PARENT-1, HAS-CHILDREN = 1
This informs the control that the item has children, even though the children are not physically present in the control.
There are two approaches you can take when managing the children of a particular item. You can add them the first time the parent item expands, and then leave them in the control, or you can add them as the parent expands and delete them when the parent collapses.
The first approach is to add child items the first time the parent is expanded, and them leave them in the control. To code this, respond to the MSG-TV-EXPANDING message by seeing if there are any children of the parent item. If not, then add them at this point. A typical event procedure for this would look like this:
TREE-VIEW-EVENT-1. EVALUATE EVENT-TYPE WHEN MSG-TV-EXPANDING IF EVENT-DATA-1 = TVFLAG-EXPAND |Item expanding MODIFY TV-1( EVENT-DATA-2 ), NEXT-ITEM = TVNI-CHILD GIVING ITEM-1 IF ITEM-1 = NULL |No children PERFORM ADD-CHILDREN END-IF END-IF END-EVALUATE
The paragraph ADD-CHILDREN would do the work needed to add the child items. In this example, EVENT-DATA-1 contains a flag that describes whether the parent item is being expanded or collapsed, and EVENT-DATA-2 contains the ID of the parent item. See the description of the event MSG-TV-EXPANDING for details.
The second approach is to add child items each time the parent expands, and then remove them when the parent collapses. The code for adding the items is slightly easier because you do not have to guard against adding multiple times. However, you have additional code to handle the removal of the child items. A typical event procedure for this approach looks like this:
TREE-VIEW-EVENT-1. EVALUATE EVENT-TYPE WHEN MSG-TV-EXPANDING IF EVENT-DATA-1 = TVFLAG-EXPAND PERFORM ADD-CHILDREN END-IF WHEN MSG-TV-EXPANDED IF EVENT-DATA-1 = TVFLAG-COLLAPSE MODIFY TV-1, ITEM-TO-EMPTY = EVENT-DATA-2 END-IF
TITLE
Tree-View controls do not have titles.
VALUE
A Tree-View's value is the ID of the currently selected item. When you set the VALUE, the corresponding item is selected (or the selection is removed if there is no corresponding item). When you retrieve the VALUE, the result is the ID of the current selection, or NULL if nothing is selected.
SIZE
SIZE and LINES describe the area occupied by the Tree-View control, using the control's font to determine the dimensions of a row and column. Additional space is added for the scroll bar (which is hidden when it is not needed). The default height of a Tree-View is 5 lines; the default width is 12 columns. TREE-ROOT-SPACE and TREE-TAB-SIZE are two configuration variables that affect the size and appearance of the character-based Tree-View control.
COLOR
Tree-Views use any specified foreground or background color. If either color is omitted, then that color uses a system-dependent default value. Under Microsoft Windows, the default values are determined by the user's choices in the Control Panel (usually black on bright white). These system-dependent default colors are not transformed or mapped by the runtime's color-handling configuration options.
3-D - Adds 3-D decoration around the border of the control. Effective only on boxed Tree-Views. (create, modify)
BOXED - Indicates that a box should be placed around a list box. This is the default. (create)
BUTTONS - Places small buttons to the left of each item that the user can click to expand or collapse the item in addition to double-clicking the item. The buttons show a "+" if the item can be expanded, or a "-" if it can be collapsed. Items with no subsidiary items do not get a button. Also, buttons are placed on the top level items only if you also specify the SHOW-LINES and LINES-AT-ROOT styles. (Note: some versions of Windows are known to have a bug that prevents the buttons from displaying correctly if you do not also specify the SHOW-LINES style.) (create, modify)
LINES-AT-ROOT - Allows the SHOW-LINES and BUTTONS styles to apply to top level items. (create, modify)
NO-BOX - This style removes the box that normally displays around the control. (create) SHOW-LINES Causes faint lines to be drawn between the items to help clarify their nesting relationship. Lines are not drawn between top level items unless you also specify the LINES-AT-ROOT style. (create, modify)
SHOW-SEL-ALWAYS - When this style is applied, the control always shows the current selection, even when it does not have the focus. The default is to hide the selection when the control does not have the focus. (create, modify)
BITMAP-HANDLE - (numeric) Identifies the handle of a loaded bitmap, so that images from that bitmap can be shown in items in the Tree-View. You obtain the bitmap handle by calling the library routine W$BITMAP with the WBITMAP-LOAD option. The bitmap is treated as a bitmap strip - a series of fixed-width images laid out side-by-side in a single bitmap. The images are numbered sequentially, starting at "1". Note that you have only one bitmap strip for the entire control, although you can select individual images out of this strip for each item. See BITMAP-NUMBER. (create, modify, inquire)
BITMAP-NUMBER - (numeric) Identifies the bitmap image that will be displayed for the item identified by ITEM. If you do not specify a bitmap number for a particular item, that item will use bitmap number "1". Note that you can show different bitmaps for expanded or collapsed items by changing an item's BITMAP-NUMBER in response to the MSG-TV-EXPANDING event. (create, modify, inquire)
BITMAP-WIDTH - (numeric) Sets the width of the images in the bitmap strip described by BITMAP-HANDLE. If not set, then the images default to 16-pixels wide. You should set this to match the actual width of the images that make up the bitmap strip. (create, modify, inquire)
ENSURE-VISIBLE - (numeric) When set to a valid item ID, ensures that that item is visible in the control. This may expand collapsed items and may cause scrolling. (create, modify)
EXPAND - (numeric) Programmatically expands or collapses the item identified by the ITEM property. If you set EXPAND to TVFLAG-EXPAND, the item is expanded. To collapse the item, set EXPAND to TVFLAG-COLLAPSE. These constants are defined in "acugui.def". Set to zero when you want no action to occur. (create, modify)
HIDDEN-DATA - (alphanumeric) Allows the program to store data that is not displayed in an item. Hidden data is limited to 255 bytes per item. Hidden data may be any format, including non-printing characters. This property acts on the item identified by the ITEM property. (create, modify, inquire)
HAS-CHILDREN - (numeric) When set to a non-zero value, indicates that the item identified by ITEM has child items even if there are no child items in the control. When set to zero (the default), an item has children only if they are physically present in the control. This property is useful when it is impractical to place all of a tree's items in the control all at once. In this approach, you do not place child items in the tree, but you mark which items have children via this property. Then, when the user expands a particular item, you have the program respond to the MSG-TV-EXPANDING event by adding the appropriate child items to the control. The HAS-CHILDREN property informs the control which items can be expanded. (create, modify)
ITEM - (numeric) This property is used in conjunction with other properties to identify which item to affect. Typically, you set ITEM to the ID of the item to act on and then set another property to perform the action. Note that you must set ITEM before the other property to get the desired results. ITEM is the "index" for the Tree-View control (see the MODIFY and INQUIRE statements for a description of indexes).
ITEM-TEXT - (alphanumeric) When set, changes the text of the item identified by ITEM to match the value assigned. When queried, returns the text of the item identified by ITEM. (create, modify, inquire)
ITEM-TO-ADD - (alphanumeric) Places a new item in the Tree-View control. The text assigned to ITEM-TO-ADD is placed as a new item in the control. Its position in the hierarchy is determined by the PARENT and PLACEMENT special properties. The return value from this property is the ID of the new item. If the new item is successfully added, the ITEM property is set to point to this item (this makes attaching a bitmap or hidden data to the item easier - see BITMAP-NUMBER and HIDDEN-DATA). (create, modify)
ITEM-TO-DELETE - (numeric) When set, deletes the item whose ID matches the assigned value. If you place this in the Screen Section, then set this value to NULL to ensure that you do not accidentally delete items. (create, modify)
ITEM-TO-EMPTY - (numeric) Deletes all child items of the item whose ID is assigned to this property. When set to NULL, has no effect. (create, modify)
NEXT-ITEM - (numeric) Setting this property returns a specific item ID. The new item found depends on the value used:
Value Item Found TVNI-CHILD First child of the current ITEM TVNI-FIRST-VISIBLE First item currently visible in control TVNI-NEXT Next sibling of the current ITEM TVNI-NEXT-VISIBLE Next visible item after ITEM TVNI-PARENT Parent item of the current ITEM TVNI-PREVIOUS Previous sibling of ITEM TVNI-PREVIOUS-VISIBLE Previous visible item before ITEM TVNI-ROOT Topmost item in the entire control
These values are defined in "acugui.def". Note that ITEM must refer to a visible item when you are using TVNI-NEXT-VISIBLE or TVNI-PREVIOUS-VISIBLE. The return value from setting this property is the item ID if successful, or zero if the specified item does not exist. Set NEXT-ITEM to zero when no action is wanted. (create, modify)
PARENT - (numeric) Helps to determine the placement of a new item in the control. When this is set to an ID of an item already in the control, the newly added item will be a child of the PARENT item. If PARENT is set to zero, then newly added items are placed at the top level. PARENT is set to zero when the control is created. (create, modify, inquire)
In the following example, four items are added to a Tree-View control. The first item is a parent to the next two items, and the last item is on the top level like the first:
77 ID-1 USAGE POINTER. MODIFY TREE-VIEW-1, ITEM-TO-ADD = "Item 1", GIVING ID-1, PARENT = ID-1, ITEM-TO-ADD = "Item 1-A", ITEM-TO-ADD = "Item 1-B", PARENT = 0, ITEM-TO-ADD = "Item 2"
The resulting tree looks like this:
Item 1 Item 1-A Item 1-B Item 2
PLACEMENT (numeric) Works in conjunction with PARENT to determine where new items are located in the hierarchy. The PLACEMENT value affects the location within a given sub-level (i.e., the list of items which have the same parent). If PLACEMENT is set to a valid item ID (whose parent is PARENT), then the new item is placed immediately after this item. Alternatively, you can use any one of the following special values (defined in "acugui.def"):
TVPLACE-FIRST Item placed first in the list TVPLACE-LAST Item placed last in the list TVPLACE-SORT Item sorted alphabetically in the list
The default setting is TVPLACE-LAST.
In the following example, items are sorted alphabetically except at the top level:
77 ID-1 USAGE POINTER. 77 ID-2 USAGE POINTER. MODIFY TREE-VIEW-1, ITEM-TO-ADD = "Ordinals", GIVING ID-1 PARENT = ID-1, PLACEMENT = TVPLACE-SORT, ITEM-TO-ADD = ( "First", "Second", "Third", "Fourth" ) PARENT = 0, PLACEMENT = TVPLACE-LAST, ITEM-TO-ADD = "Cardinals", GIVING ID-2, PARENT = ID-2, PLACEMENT = TVPLACE-SORT, ITEM-TO-ADD = ( "One", "Two", "Three", "Four" ).
The resulting tree looks like this:
Ordinals First Fourth Second Third Cardinals Four One Three Two
Notice that the "Ordinals" and "Cardinals" appear in the order added (TVPLACE-LAST), although the items under each are sorted alphabetically (TVPLACE-SORT). (create, modify, inquire)
RESET-LIST - (numeric) When set to a non-zero value, this removes all items from the control. Has no effect when set to zero. (create, modify)
The Tree-View control generates the following events:
CMD-GOTO
CMD-HELP
MSG-TV-DBLCLICK
MSG-TV-EXPANDED
MSG-TV-EXPANDING
MSG-TV-SELCHANGE
MSG-TV-SELCHANGING
MSG-VALIDATE