This document covers the following topics:
A tree view control is used to display data in hierarchical form. Each node in the hierarchy is represented internally as a tree view item. The following shows a simple tree view (with optional check boxes) displaying a 3-level hierarchy containing seven tree view items:
The tree view control shown above is specified with the
"+/- buttons (b)", "Lines
(l)", "Lines at root (r)" and
"Check boxes (c)"
STYLE flags.
The height of each item and the indentation between levels can be set
via the ITEM-H and
SPACING attributes,
respectively. If either of these are zero, the default setting is used.
Images for the tree view items may be defined by creating and associating an image list control with the tree view control, then (for each item) selecting the required image from the image list via its index and/or image handle, as described in the section Working with Image List Controls.
Please note that it is not necessary to set the image list control's "Large images (L)" style, unless you are additionally using the same image list for a list view control, because the tree view control only uses small images.
Unlike the list view control, the tree view control only supports one
selected item. The current selection (if any) may be retrieved by querying the
tree view control's (read-only)
SELECTED-SUCCESSOR
attribute.
In addition to being selected by the user, items may be selected or
deselected programmatically by setting or clearing their
SELECTED attribute.
When an item is selected, a
CLICK event is raised for the list view
control (if not suppressed), with the handle of the corresponding item
being set in the control's ITEM attribute.
When a user double-clicks on an item, an
ACTIVATE event is raised (unless
suppressed) for the tree view control. The
application, if it decides to handle this event, normally performs a
user-defined default action on the selected item, the handle to which may be
obtained via either the ITEM or
SELECTED-SUCCESSOR
attributes of the tree view control. Note that there may be other, non-default,
actions applicable to the selected item, but these are typically accessed via
other mechanisms. For example, they may be listed (typically along with the
default action) in a context menu displayed by the application.
If the "Dbl. click expand (d)"
STYLE flag is set,
double clicking a tree view item that has child items expands the item in
addition to activating it.
The ACTIVATE event can also be triggered via
the keyboard. This can be done in either of two ways:
By pressing the key or key combination defined for the tree view
control's ACCELERATOR attribute.
The control need not currently have the focus.
By pressing the ENTER key, if the tree view control
currently has the focus. This method only works if the dialog neither contains
a default
pushbutton, nor a pushbutton with the "OK Button
(O)" STYLE flag set.
In either case, no
ACTIVATE event is raised if no item is
currently selected.
In order to be able to support sorting correctly (see next section), a
tree view item's data does not need to be alphanumeric, as it is per default,
but can be one of any of the pre-defined types supported by the column's
FORMAT attribute. In
addition, an edit mask can be applied to the item by setting its
EDIT-MASK attribute.
The item's label, as seen by the user for the item, is the alphanumeric
representation of the item's internal data, using the associated edit mask (if
any). The conversion between the item's internal data and the displayed data is
compatible with the MOVE
EDITED statement if an edit mask is supplied. Otherwise, the
conversion between the internal and displayed data, and vice-versa, is
compatible with the conversion involved in copying the data to and from the
Natural stack (see the STACK TOP
DATA and INPUT statements). For example,
numeric values are displayed using the current decimal character (as defined by
the DC
parameter) if necessary, with a leading minus character if negative, date
values are displayed in the format defined by the
DTFORM
parameter setting, logical values are displayed as an
"X" if true and as a blank if false, and so on.
An example of use of a non-alpha tree view item is shown below:
PROCESS GUI ACTION ADD WITH PARAMETERS HANDLE-VARIABLE = #TVITEM-DATE TYPE = TREEVIEWITEM PARENT = #TV-1 STRING = '+123.456' FORMAT = FT-DECIMAL EDIT-MASK = '+ZZZ,ZZ9.999' END-PARAMETERS GIVING *ERROR
In this case, the specified item label (STRING attribute value)
must of course be a valid number of a form compatible with the specified edit
mask (+ZZZ,ZZ9.999). Internally, the label is converted to the data type and
length corresponding to the specified format, FT-DECIMAL (= P10.5).
Note that it is not possible to access the underlying data for a tree view item directly. The item's data can only be set or retrieved via the item's label.
Tree view items can either be inserted in sorted sequence or explicitly
sorted after insertion, by calling the
SORT-ITEMS action. Items are inserted in
ascending alphabetical sequence if either the tree view control or the tree
view item being inserted have their
SORTED attribute set to
TRUE. In the latter case, the items are optionally sorted in
ascending or descending sequence according to their internal data (see last
section). See the documentation for the
SORT-ITEMS action for more information.
Note that it is the responsibility of the programmer to ensure that the
underlying item formats of the items concerned (as defined by the
FORMAT attribute) are
of comparable types. For example, it is possible to mix integers and floating
point values, but not integers and dates.
The process of label editing for tree view controls is the same as for list view controls. Therefore, for more information on this subject, please refer to the section Label Editing in Tree View and List View Controls.
Note that even if the
SORTED attribute is
set, the items are not automatically re-sequenced after a label editing
operation has been completed. If this is required, this can be done as shown in
the example below. Firstly, we define some variables for later use:
01 #CONTROL HANDLE OF GUI 01 #ITEM HANDLE OF TREEVIEWITEM 01 #SORTITEM HANDLE OF TREEVIEWITEM
In addition, it is assumed that the tree view control is named
#TV-1.
In the tree view control's
AFTER-EDIT event, we cannot do the
re-sequencing asynchronously, as this would interfere with the (as yet
incomplete) editing process. Instead, we simply set the #SORTITEM
variable to indicate that the re-sequencing should occur at a later time, after
the editing process has been completed. This only needs to be done if the tree
view items are sorted:
#CONTROL := *CONTROL #ITEM := #CONTROL.ITEM IF #CONTROL.SORTED OR #ITEM.SORTED #SORTITEM := #ITEM ELSE #SORTITEM := NULL-HANDLE END-IF
Note that this examples assumes the use of the default (ascending alphabetical) sorting provided by the tree view control itself.
The actual work of re-sequencing the items is done asynchronously in the
dialog's IDLE event:
IF #SORTITEM <> NULL-HANDLE PROCESS GUI ACTION SORT-ITEMS WITH #SORTITEM.PARENT GIVING *ERROR RESET #SORTITEM END-IF
If you wish to support just a single context menu for the control, you
can simply set the control's
CONTEXT-MENU attribute
to the handle of the context menu you wish to display, and leave it set to this
value. However, it is often required to be able to display more than one
context menu for list view controls, whereby this approach is too
inflexible.
To address the above problem, the
CONTEXT-MENU event was introduced (not to
be confused with the attribute of the same name as mentioned above!). This
event (if not suppressed) is raised for the target control immediately before
its CONTEXT-MENU attribute
is evaluated, allowing the application to dynamically set this attribute to the
handle of the appropriate context menu first.
As an example, assume that we have defined two context menus in the
dialog editor: one containing item-related commands,
#CTXMENU-ITEMS, and one containing generic commands (e.g., for
switching the view mode), #CTXMENU-DEFAULT. In this case, the
following
CONTEXT-MENU event could be used:
#CONTROL := *CONTROL IF #CONTROL.SELECTED-SUCCESSOR <> NULL-HANDLE #CONTROL.CONTEXT-MENU := #CTXMENU-ITEMS ELSE #CONTROL.CONTEXT-MENU := #CTXMENU-DEFAULT END-IF
where the following local data definition is assumed:
01 #CONTROL HANDLE OF GUI
In this example, the context menu #CTXMENU-ITEMS will be
displayed if the user right clicks at a position occupied by an item, or
#CTXMENU-DEFAULT otherwise.
Of course, this technique can be refined further to display context menus specific to the type(s) of the selected item(s).
When a tree view item is expanded or collapsed, an
EXPAND event or
COLLAPSE event (respectively) is raised
for the control, if the event is not suppressed. Amongst other things, these
events allow tree-view items to be dynamically created and deleted on
demand.
For example, the following code demonstrates the dynamic creation of
three items in response to the
EXPAND event. It assumes that a dummy
placeholder item with an empty
STRING attribute value
is already in place at the position where the items should be inserted. The
placeholder can either have been statically defined in the dialog editor, or
dynamically-defined during the initial tree view item creation. The purpose of
the placeholder is to ensure that a "+" button (if
button display enabled via the "+/- buttons (b)"
STYLE) appears next to
the parent node.
The following
EXPAND event code assumes that the
variable #TGT-ITEM contains the handle of the tree view item under
which the dynamic tree view items are to be created:
#CONTROL := *CONTROL
#ITEM := #CONTROL.ITEM
IF #ITEM = #TGT-ITEM
#TVITEM-DYN := #ITEM.FIRST-CHILD
IF #TVITEM-DYN <> NULL-HANDLE AND
#TVITEM-DYN.STRING = ' '
PROCESS GUI ACTION DELETE WITH #TVITEM-DYN GIVING *ERROR
FOR #I 1 3
COMPRESS 'Dynamic Item' #I INTO #A
PROCESS GUI ACTION ADD WITH PARAMETERS
HANDLE-VARIABLE = #TVITEM-DYN
TYPE = TREEVIEWITEM
PARENT = #ITEM
STRING = #A
END-PARAMETERS GIVING *ERROR
END-FOR
END-IF
END-IF
where the following local data definitions are assumed:
01 #CONTROL HANDLE OF GUI 01 #ITEM HANDLE OF TREEVIEWITEM 01 #TVITEM-DYN HANDLE OF TREEVIEWITEM 01 #TGT-ITEM HANDLE OF TREEVIEWITEM 01 #I (I4) 01 #A (A) DYNAMIC
The above code first looks to see whether the item being expanded is the
target item. If so, it queries the
STRING attribute of the
first child, to find out whether a placeholder is present. If this is the case,
the placeholder is deleted, and three dynamic tree view items are created. The
STRING attribute value
for the inserted items is specified on creation, rather than modified
afterwards, to ensure that the code also works correctly for
SORTED tree views.
To save resources, the dynamically-created items could optionally be
deleted again in the
COLLAPSE event handler, being replaced by
a placeholder item:
#CONTROL := *CONTROL
#ITEM := #CONTROL.ITEM
IF #ITEM = #TGT-ITEM
PROCESS GUI ACTION DELETE-CHILDREN WITH #ITEM GIVING *ERROR
PROCESS GUI ACTION ADD WITH PARAMETERS /* placeholder
TYPE = TREEVIEWITEM
PARENT = #ITEM
END-PARAMETERS GIVING *ERROR
END-IF
The basic technique for providing drag and drop support is described in the section Using the Clipboard and Drag and Drop.
Note that it is the responsibility of the programmer to (if required)
highlight the item (if any) under the mouse cursor by setting its
SELECTED attribute, and
to restore the original selection (if any) afterwards.
The following example provides some code for demonstrating a tree view control acting as a drop target, in order to support dragging and dropping text from another application (e.g. WordPad) onto a tree view item in order to change its label.
The first step is to ensure that the drop mode is set correctly for the
tree view control. In the Tree View Control
Attributes window in the dialog editor, set the Drop
mode selection box to Copy+Move. This
causes the control's DROP-MODE attribute to
be set to DM-COPYMOVE in the generated source code for the
dialog.
Next, the required local variables that are going to be used below must be defined:
01 #CONTROL HANDLE OF GUI 01 #DROP-ITEM HANDLE OF GUI 01 #ITEM HANDLE OF GUI 01 #SELECTED HANDLE OF GUI 01 #AVAIL (L) 01 #X (I4) 01 #Y (I4)
Having done this, we can write the necessary event handlers. The logical
place to start is with the
DRAG-ENTER event:
#CONTROL := *CONTROL #CONTROL.CLIENT-HANDLE := #CONTROL.SELECTED-SUCCESSOR PROCESS GUI ACTION INQ-FORMAT-AVAILABLE WITH CF-TEXT #AVAIL GIVING *ERROR IF #AVAIL #CONTROL.SUPPRESS-DRAG-DROP-EVENT := NOT-SUPPRESSED ELSE #CONTROL.SUPPRESS-DRAG-DROP-EVENT := SUPPRESSED END-IF
The above code first saves the handle of the currently selected item in
the control's CLIENT-HANDLE attribute for the
purposes of restoring the selection to this item later. The event handler then
checks whether text data is available on the drag-drop clipboard. If it is, the
DRAG-DROP event is unsuppressed in order
to allow a drop. Otherwise, we suppress this event in order to prohibit a drop
such that the "no drop" drag cursor appears.
To provide drop emphasis during the dragging of external data across the
tree view control, a
DRAG-OVER event handler is supplied:
#CONTROL := *CONTROL
IF #CONTROL.SUPPRESS-DRAG-DROP-EVENT = NOT-SUPPRESSED
PROCESS GUI ACTION INQ-DRAG-DROP WITH
3X #X #Y GIVING *ERROR
PROCESS GUI ACTION INQ-ITEM-BY-POSITION WITH
#CONTROL #X #Y #ITEM GIVING *ERROR
IF #ITEM <> #DROP-ITEM
#DROP-ITEM := #ITEM
IF #DROP-ITEM <> NULL-HANDLE
#DROP-ITEM.SELECTED := TRUE
END-IF
END-IF
END-IF
The above code performs the following:
If a drop was disallowed in the
DRAG-ENTER event, the event is ignored,
as no drag emphasis is required in this case.
Otherwise, the
INQ-DRAG-DROP action is called to
determine the current drop position.
The INQ-ITEM-BY-POSITION action is used to
find the tree view item (if any) at the current drop position. This item is
tracked in #DROP-ITEM.
The tree view item (if any) under the cursor is selected to provide
the drop emphasis by setting its
SELECTED attribute to
TRUE.
To perform the actual drop, a
DRAG-DROP event handler is supplied:
IF #DROP-ITEM <> NULL-HANDLE
PROCESS GUI ACTION GET-CLIPBOARD-DATA WITH CF-TEXT #DROP-ITEM.STRING
GIVING *ERROR
END-IF
#CONTROL := CONTROL /* "parameter" for subroutine below
PERFORM RESET-SELECTION
If there is a tree view item representing the drop target, the above
code retrieves the text from the drag-drop clipboard directly into the item's
caption. Afterwards, the original selection state of the tree view control is
restored. The RESET-SELECTION subroutine used for this purpose can
be written as follows:
#ITEM := #CONTROL.CLIENT-HANDLE IF #ITEM <> NULL-HANDLE /* Restore original selection: #ITEM.SELECTED := TRUE ELSE /* Nothing was originally selected, /* so clear any existing selection: #ITEM := #CONTROL.SELECTED-SUCCESSOR #ITEM.SELECTED := FALSE END-IF RESET #DROP-ITEM
To satisfy the logic provided for the other event handlers,
#DROP-ITEM is also reset, indicating the absence of a drop
item.
Lastly, in the case that the user cancels the drag operation, or exits
the bounds of the tree view control without having performed a drop, a
DRAG-LEAVE event handler is supplied:
#CONTROL := CONTROL /* "parameter" for subroutine below PERFORM RESET-SELECTION
The above code simply invokes the inline subroutine listed above in order to clear the drop emphasis (if any), and to restore the original selection state.