This document covers the following topics:
A list view control can be used to display data in icon or column-based form. It is a very powerful control. Nevertheless, if you wish to display your data in tabular form and support direct in-place editing of any column value, you should consider using the table control instead.
List view controls in Natural can display their data in one of four view modes: icon, small icon, list or report.
In icon view mode, the data is displayed in large icon form:
In small icon view mode, the item labels are displayed alongside the icons. As for the icon view, the items can optionally be displayed in arbitrary positions:
In list view mode, the items are displayed similarly to the small icon view, but cannot be freely positioned. Instead, they are displayed in columns:
In report view mode, each item occupies one row, and other data relating
to the items may be displayed alongside the item in separate columns. A column
header is also usually shown, as in the example below (although this can
optionally be hidden by setting the list view control's "No header
(x)" STYLE
flag):
In the report view, the columns can be resized by the user by dragging the column dividers. Alternatively, by double-clicking on the trailing column divider in the column header, the column's width is adjusted to fit the longest text within the column.
Note that the above example consists of eleven dialog elements: The
list view
control itself, four
list view items
and six list view
columns. Both the list view items and the list view columns have the
list view control as their PARENT,
and are thus stored in the same SUCCESSOR
chain. Although they can be interspersed, it is a good idea from both an
organization and performance point-of-view to ensure that all list view columns
precede all list view items. For example, if you are dynamically inserting a
new column into a non-empty list view control as the last column, explicitly
set its SUCCESSOR
attribute to the handle of the first list view item, rather than not specifying
it at all or setting it to NULL-HANDLE, which would cause the new
column to be placed at the end of the chain, after all list view items.
The first list view column created for a list view control has a special
significance, and is referred to (here) as the primary column. The
primary column always displays the list view item labels (i.e., their
STRING
attribute values). The other columns display what is known as sub-item
data. For example, the phrase "Currency sub-item" refers to the
data stored in the "Currency" column (see above
example). To refer to a particular value within the column, we would have to be
more precise. For example, the value "1277.18" above
could be referred to as the "Currency sub-item" for
the "Second item" item. Sub-items are not
dialog element types in Natural, and will be discussed in more detail
below.
If no list view columns have been created, no information will be
displayed in the list view control when it is in report view mode! However, it
should be noted that the only way to switch between the view modes is
programmatically by explicitly changing the list view control's
VIEW-MODE
attribute value. Therefore, if the application wishes to support multiple view
modes, it must provide a mechanism (e.g., a context menu) for switching between
them. So, in practice, the user should never see a list view control in report
view mode that has no columns, since the application would normally not allow
switching to this view mode in this case.
Images for the list view items may be defined by creating and associating an image list control with the list 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 you should set the image list control's "Large images (L)" and "Small images (S)" styles according to the view modes that are to be supported. The icon view mode requires the availability of large images, whereas the other view modes require the availability of small images.
In the icon and small icon view modes, the list view items may be
(re-)positioned by setting their RECTANGLE-X
and/or RECTANGLE-Y
attribute values. If no position is explicitly set on item creation, the items
are laid out on an imaginary grid, with a default grid spacing that can be
overridden by setting the list view control's
SPACING-X
and SPACING-Y
attribute values. The ARRANGE
action can be used at any time to either re-arrange the items to occupy
consecutive locations based on this logical grid, or to snap the items to their
nearest aligned logical grid position.
Note that in either of the two icon view modes, the list view item
positions are interpreted as being in view coordinates, rather than
being relative to the control's client area (as is the case in the other view
modes). Unlike the client coordinates, the view coordinates of the items do not
change when the icon view is scrolled. Conversion between view coordinates and
client coordinates requires the use of the list view control's
OFFSET-X
and OFFSET-Y
attributes, which return the origin of the client area in view coordinates.
Note that two list view control STYLE
flags can override an explicit postion specified by the program. Firstly, if
the control's "Auto-arrange (a)" style flag is
specified, the items are automatically re-arranged on the imaginary grid each
time an item is added or moved. In this case, an explicitly specified position
merely indirectly determines the item's position in the arranged icon list.
Secondly, if the control's "Snap to grid (r)" style
flag is set, any item position explicitly specified by the program will be
adjusted to the nearest aligned position on the imaginary grid. Note that this
style is superfluous if the "auto-arrange" style is
set.
Since users are often familiar with being able to modify list view item positions via drag and drop, it may be expected that the control automatically provides this capability. However, this is not the case. If the application wishes to support drag and drop, it must explicitly cater for it, as described in the next section.
In the list view mode, the items are always displayed in columns (as
already mentioned above) and are not re-positionable. However, the spacing
between adjacent columns may be set via the
SPACING
attribute.
Note that the list view control does not remember item positions when switching between view modes. For example, if you switch away from one of the icon view modes and then back to it again, the icons are always arranged. This behavior can be circumvented by providing explicit program code for saving and restoring item positions, as shown in the following example:
DEFINE SUBROUTINE SAVE-ITEM-POSITIONS
#ITEM := #CONTROL.FIRST-CHILD
REPEAT WHILE #ITEM <> NULL-HANDLE
IF #ITEM.TYPE = LISTVIEWITEM
#ITEM.CLIENT-KEY := 'RECTANGLE-X'
#ITEM.CLIENT-VALUE := #ITEM.RECTANGLE-X
#ITEM.CLIENT-KEY := 'RECTANGLE-Y'
#ITEM.CLIENT-VALUE := #ITEM.RECTANGLE-Y
END-IF
#ITEM := #ITEM.SUCCESSOR
END-REPEAT
END-SUBROUTINE
*
DEFINE SUBROUTINE RESTORE-ITEM-POSITIONS
#ITEM := #CONTROL.FIRST-CHILD
REPEAT WHILE #ITEM <> NULL-HANDLE
IF #ITEM.TYPE = LISTVIEWITEM
#ITEM.CLIENT-KEY := 'RECTANGLE-X'
IF #ITEM.CLIENT-VALUE <> ' '
#ITEM.RECTANGLE-X := VAL(#ITEM.CLIENT-VALUE)
END-IF
#ITEM.CLIENT-KEY := 'RECTANGLE-Y'
IF #ITEM.CLIENT-VALUE <> ' '
#ITEM.RECTANGLE-Y := VAL(#ITEM.CLIENT-VALUE)
END-IF
END-IF
#ITEM := #ITEM.SUCCESSOR
END-REPEAT
END-SUBROUTINE
*
DEFINE SUBROUTINE SWITCH-VIEW-MODE
IF #VIEW-MODE <> #CONTROL.VIEW-MODE
IF #CONTROL.VIEW-MODE = VM-ICON OR
#CONTROL.VIEW-MODE = VM-SMALLICON
PERFORM SAVE-ITEM-POSITIONS
END-IF
#CONTROL.VIEW-MODE := #VIEW-MODE
IF #VIEW-MODE = VM-ICON OR
#VIEW-MODE = VM-SMALLICON
PERFORM RESTORE-ITEM-POSITIONS
END-IF
END-IF
END-SUBROUTINE
where the following local data definitions are assumed:
01 #CONTROL HANDLE OF GUI 01 #ITEM HANDLE OF GUI 01 #VIEW-MODE (I4)
The actual view mode switch can then be made by setting
#VIEW-MODE to the desired view mode (one of the VM-*
constants defined in the local data area NGULKEY1), setting
#CONTROL to the handle of the list view control, and then calling
the SWITCH-VIEW-MODE subroutine.
Items may be selected by the user either by clicking on them (optionally
whilst holding down the CTRL key to perform an extended selection),
or by defining a selection region by clicking within the list view control,
holding down the primary mouse button, and dragging. The latter technique is
known as marquee selection, and is only allowed if the control's
"Marquee select (m)"
STYLE flag
is set (the default setting). Note that, if the control's
"Hot-track select (t)" style flag is set, it is not
necessary to click an item to select it. Instead, it is sufficient to simply
let the mouse cursor hover over it briefly.
Alternatively, items may be selected or deselected programmatically by
setting or clearing their SELECTED
attribute.
In either case, extended selection is only available if the control's
MULTI-SELECTION
attribute is set to TRUE. Extended selection is the process of
selecting new items, or deselecting old ones, without the existing selection
being cleared first, and thus allows multiple (or no) items to be selected. In
the case of single selection list views, it is only possible for the user to
implicitly deselect an item by selecting a new one. Marquee selection is also
not available in this case.
The first (or only) selected item, if any, may be determined by querying
the list view control's SELECTED-SUCCESSOR
attribute, which returns NULL-HANDLE if there is no selection. The
next selected item, if any, may be determined by querying a selected item's
SELECTED-SUCCESSOR
attribute. Iterative application of this technique allows complete enumeration
of all selected items, as shown in the section below on drag and drop.
For each item that is selected or deselected, 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. Because many items may be selected in quick succession (e.g., via
marquee selection), this event should not perform any lengthy processing. For
example, it may be better to simply set a logical variable to TRUE
in the CLICK
event handler, indicating that more involved processing is required,
and do the actual processing in the dialog's
IDLE
event handler in response to this flag being set. Don't forget to
clear the flag after doing the work!
If the list view control's "Check boxes (c)"
style flag is set, check boxes are displayed alongside each item. The item's
CHECKED
attribute may be used to retrieve or set an item's checked status
programmatically. The first checked item, if any, may be determined by querying
the list view control's CHECKED-SUCCESSOR
attribute, and querying this attribute for a checked item returns the handle of
the next checked item, if any, thus allowing complete enumeration of all
checked items, as shown in the following example, which simply counts the
number of checked items:
RESET #COUNT #ITEM := #LV-1.CHECKED-SUCCESSOR REPEAT WHILE #ITEM <> NULL-HANDLE ADD 1 TO #COUNT #ITEM := #ITEM.CHECKED-SUCCESSOR END-REPEAT
where the following local data definitions are assumed:
01 #LV-1 HANDLE OF LISTVIEW 01 #ITEM HANDLE OF LISTVIEWITEM 01 #COUNT (I4)
Whenever an item is checked or unchecked, a
CHECK
event is raised for the list view control, if not suppressed via the
SUPPRESS-CHECK-EVENT
attribute, 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 list view
control. The application, if it decides to handle this event, normally performs
a default action on each selected control. The default action is user-defined
and can be different for each item. For example, activating an item
representing a text file might cause the file to be opened in an editor,
whereas activating an item representing an audio file might cause the file to
be played. Note that there may be other, non-default, actions applicable to one
or more of the selected items, 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 multiple selection is allowed (see above) and the CTRL key
is held down whilst double-clicking an item, the selection state of the item is
toggled before the ACTIVATE
event is raised.
If either of the control's "Underline hot
(u)" or "Underline cold (U)"
STYLE flags are set, it is only necessary to
single-click on an item in order to activate 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 list view
control's ACCELERATOR
attribute. The control need not currently have the focus.
By pressing the ENTER key, if the list 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 items are currently selected.
Each column in a list view (as displayed when the list view control is in report view mode) can contain (at most) one item of data per list view item, which is then (if present) displayed for the item in that column. As already mentioned above, this data is known as sub-item data.
In order to be able to support sorting correctly (see next section), the
sub-item 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 column by setting
its EDIT-MASK
attribute. The values seen in the report view column by the user for a column
are the alphanumeric representations of the sub-item for that column, using the
associated edit mask (if any). The conversion between the sub-item 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.
The first column defined for a list view control (the primary
column) has a special significance: It always displays the item's label.
Therefore, any changes to an item's sub-item data for the first coumn
automatically update the item's label, and vice-versa. Otherwise, and for all
other columns, the only means of updating the sub-item data is via the
SET-SUBITEM-DATA
action. When calling this action, the sub-item data must be supplied in a
format compatible with the internal data type, as specified by the
column's FORMAT
attribute value (alphanumeric by default).
For example, suppose we add a column to a list view control as shown below:
PROCESS GUI ACTION ADD WITH PARAMETERS HANDLE-VARIABLE = #LVCOL-DATE TYPE = LISTVIEWCOLUMN STRING = 'Date' PARENT = #LV-1 RECTANGLE-W = 83 STYLE = 'l' FORMAT = FT-DATE EDIT-MASK = 'YYYY/MM/DD' END-PARAMETERS GIVING *ERROR
The sub-item data for this column for a particular list view item,
#LVITEM-1 (say), can then be set to the current date as
follows:
PROCESS GUI ACTION SET-SUBITEM-DATA WITH #LVITEM-1 #LVCOL-DATE *DATX GIVING *ERROR
Note that we could also have used *TIMX
instead of *DATX, because time values in Natural
are automatically convertible to date values. In either case, the value is then
displayed as the current date in YYYY/MM/DD format. For the primary column, the
display string is the item label, which means that the effects of the
modification will be visible even if the list view control is not currently in
report view mode.
Note also that the data is not supplied in display format. For example, the following will not work:
PROCESS GUI ACTION SET-SUBITEM-DATA WITH #LVITEM-1 #LVCOL-DATE '2004/11/03' GIVING *ERROR /* Does NOT work!
However, if the column happens to be the primary column, then it is alternatively possible to update the column data indirectly, by setting the item's label. For example:
#LVITEM-1.STRING := '2004/11/03'
Retrieval of the sub-item data may be achieved by calling the
GET-SUBITEM-DATA
action, which takes the same parameters as the
SET-SUBITEM-DATA
action. For example:
PROCESS GUI ACTION GET-SUBITEM-DATA WITH #LVITEM-1 #LVCOL-DATE #DATE GIVING *ERROR
where #DATE is defined as follows:
01 #DATE (D)
One fact to bear in mind, however, is that there may be no sub-item data
to be retrieved. For example, the sub-item data may not have been created, or
may have been deleted (see below). Natural, however, does not support null
values. Therefore, by default, Natural resets the receiving fields when a null
value is returned (see the RESET statement). However, if a
default value has been set for a list view column, this default value is
returned instead. Setting a default value for a column is done by calling
SET-SUBITEM-DATA,
specifying NULL-HANDLE in place of a list box item handle. For
example, for a numeric column, #LVCOL-NUM, where only positive
values are allowed, we might choose to set the default value to -1, as shown
below:
#NUM := -1 PROCESS GUI ACTION SET-SUBITEM-DATA WITH NULL-HANDLE #LVCOL-NUM #NUM GIVING *ERROR
where #NUM can be a field of any signed numeric format
(e.g. I2).
The use of default values allows a value to be chosen by the programmer that does not match any explicit value that can be used in the program. If necessary, the program should be changed to prevent the default value being entered as explicit data.
For both the SET-SUBITEM-DATA
and GET-SUBITEM-DATA
actions, it is possible to set or get (respectively) the sub-item data (for a
specific item) for multiple columns in a single statement. For example:
PROCESS GUI ACTION SET-SUBITEM-DATA WITH #LVITEM-1 #LVCOL-NUM #NUM #LVCOL-DATE #DATE GIVING *ERROR
In other words, multiple [column handle, receiving field] operand pairs may be specified.
To delete the subitem data (causing null values to be stored internally,
as if no data had been set), use the
DELETE-SUBITEM-DATA
action. For example:
PROCESS GUI ACTION DELETE-SUBITEM-DATA WITH #LVITEM-1 #LVCOL-DATE GIVING *ERROR
Again, multiple sub-items may be deleted for a specific item in a single statement, by specifying multiple column handles:
PROCESS GUI ACTION DELETE-SUBITEM-DATA WITH #LVITEM-1 #LVCOL-DATE #LVCOL-NUM GIVING *ERROR
When list view items are deleted, their associated sub-item data (if
any) is deleted with them. Note that if you wish to delete all items in a list
view control, but leave the list view columns intact, use the
CLEAR
action:
PROCESS GUI ACTION CLEAR WITH #LV-1 GIVING *ERROR
where #LV-1 is the list view control handle.
Sorting of the subitem data for a list view column may be achieved
either by the user (if the list view control's "No header
(x)" and "No sort header (y)"
STYLE
flags are not set), by clicking on a column header, or by the program, by
calling the SORT-ITEMS
action. In the latter case, items may be sorted even if no columns are
available, by passing the handle of the list view control itself rather than
the list view column. See the documentation for the
SORT-ITEMS
action for more information.
The sorting on clicking on a column in the column header of a list view
control is normally implicitly performed by Natural. However, before performing
the sort, Natural raises a CLICK event (if
not suppressed) for the list view column. On returning from this event, Natural
checks whether the column is already sorted in the required direction, and
performs no further action if this is the case. This means that the application
can perform the sort itself instead of Natural, as long as it obeys the rules
for the sort direction (i.e., specifies descending sequence if the column is
currently sorted in ascending sequence, or ascending sequence otherwise). This
can be useful if the sort options (e.g. case-sensitivity) need to be dynamic,
or if it is required to perform application-specific code after the sort. An
example of a column CLICK event
handler performing an explicit sort follows:
#CONTROL := *CONTROL
T1. SETTIME
IF #CONTROL.SORTED AND NOT #CONTROL.DESCENDING
PROCESS GUI ACTION SORT-ITEMS WITH #CONTROL TRUE
GIVING *ERROR
ELSE
PROCESS GUI ACTION SORT-ITEMS WITH #CONTROL
GIVING *ERROR
END-IF
COMPRESS 'Sort took' *TIMD(T1.) 'tenths of a second'
INTO #DLG$WINDOW.STATUS-TEXT
However, in most cases, it will probably be sufficient to let Natural perform the sort implicitly.
For alphanumeric data, the sort column's "Case insensitive
(i)" and "word compare (w)"
STYLE flags
determine the default way in which the values are compared. If the sort is done
explicitly, the corresponding optional parameters to the
SORT-ITEMS
action, if specified, override these defaults. See the documentation for this
action for more details on these options.
Missing ("null") values compare low. That is, they appear at the bottom of the column when the column is sorted in descending sequence, or at the top of the column when the column is sorted in ascending sequence. Furthermore, if two column entries are identical, the existing relative position of the two items concerned is preserved.
Note that, if the list view control is in one of the icon view modes, sorting the items causes them to be re-arranged. Therefore, if you are using explicit item positions in either of the icon view modes, it is probably a good idea to disable any sort commands.
List view controls also possess a SORTED
attribute, implying that new items are inserted in their ascending or
descending sort position, depending on the value of the control's
DESCENDING
attribute, rather than being inserted at the end of the item list. For this to
work as expected, the items must already be sorted in the required direction.
For example, if an item's label (i.e., its
STRING
attribute) is modified, the application itself should, if required, ensure that
the list is maintained in sorted sequence. An example of how to do this is
provided in the next section.
Note that the SORTED
attribute does not influence the position of the items displayed in either of
the icon views. However, if an explicit sort is performed via the
SORT-ITEMS
action, the items are re-arranged in the sorted sequence. If you cannot avoid
doing a sort, and you are using explicit item positions in the icon view(s),
then you must explicitly save the icon positions prior to the sort and restore
them afterwards. For example:
PERFORM SAVE-ITEM-POSITIONS PROCESS GUI ACTION SORT-ITEMS WITH #CONTROL GIVING *ERROR IF #CONTROL.VIEW-MODE = VM-ICON OR #CONTROL.VIEW-MODE = VM-SMALLICON PERFORM RESTORE-ITEM-POSITIONS END-IF
where #CONTROL is the handle of the list view control, and
where the subroutines defined above for saving and restoring the item positions
are used. Note that the icons are re-drawn (at their old positions), causing
some flicker. Therefore, if possible, try to avoid performing a sort whilst the
list view control is in one of the icon view modes. See the section below on
label editing for an example of how this may be done.
The process of label editing for list view controls is the same as for tree 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 #SORTOBJ HANDLE OF GUI 01 #SORT (L) 01 #AUTO-ARRANGE (I4)
In addition, it is assumed that the list view control is named
#LV-1.
In the list 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
#SORT flag to indicate that the re-sequencing should occur at a
later time, after the editing process has been completed:
#SORT := TRUE
In order to decide whether to perform a re-sequencing of the items, we
will need to check whether the items are already sorted. We will do this by
querying the SORTED
and DESCENDING
attributes of the primary column if the list view has columns, or those of the
list view control itself otherwise. The relevant object handle is set in the
dialog's AFTER-OPEN
event:
IF #LV-1.COLUMN-COUNT <> 0 #SORTOBJ := #LV-1.FIRST-CHILD ELSE #SORTOBJ := #LV-1 END-IF * EXAMINE #LV-1.STYLE FOR 'a' GIVING NUMBER #AUTO-ARRANGE IF #LV-1.SORTED AND #AUTO-ARRANGE <> 0 AND (#LV-1.VIEW-MODE = VM-ICON OR #LV-1.VIEW-MODE = VM-SMALLICON) #SORT := TRUE END-IF
In addition, we obtain the status of the list view control's
"Auto-arrange (a)"
STYLE
flag. If this is set, we can sort the items even if the control is in an icon
mode, as we don't require the icon positions to be fixed. Furthermore, if the
control is sorted, we indicate that we require the items to be initially
re-sequenced. This is due to the fact (mentioned earlier) that the item
positions are not updated on item insertion in the icon modes if the control's
SORTED
flag is set. The application thus needs to perform an initial sort itself in
this case.
The actual work of re-sequencing the items is done asynchronously in the
dialog's IDLE event:
IF #SORT
IF #AUTO-ARRANGE <> 0 OR
(#LV-1.VIEW-MODE <> VM-ICON AND
#LV-1.VIEW-MODE <> VM-SMALLICON)
IF #SORTOBJ.SORTED
PROCESS GUI ACTION SORT-ITEMS WITH
#SORTOBJ #SORTOBJ.DESCENDING GIVING *ERROR
END-IF
RESET #SORT
END-IF
END-IF
Note that the sort is only done for the icon view modes for the list
view control if it is auto-arranged. Otherwise, the #SORT flag is
not reset, causing the re-sequencing to be deferred until the first
IDLE
event after the control is switched to a non-icon view mode.
If you wish to support just a single context menu for a 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 a particular control, 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 for a list view control),
#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).
Drag and drop may be used for re-positioning items within a list view control, as well as for data transfer to and from other windows. There is no difference between the two cases. The re-positioning scenario is merely a special case where the drop is made in the same list view control in which the drag was initiated.
The basic technique for providing drag and drop support is described in the section Using the Clipboard and Drag and Drop. In particular, it should be noted that it is still necessary to place some data on the drag and drop clipboard even if it is only required to support re-positioning of the items within the control, in order to inform Natural that drag and drop should be initiated. Secondly, there is a caveat specific to list view controls, in that the re-positioning of items can change the origin of the list view control, so that the top near corner of the list view control's display area may no longer begin at the default origin of (0, 0).
The following example provides some code for demonstrating the use of drag and drop with the list view control, in order to support the following operations:
Re-positioning of list view items.
Dragging and dropping text from another application (e.g. WordPad) onto a list view item in order to change its label.
The first step is to ensure that the drag and drop modes are set
correctly for the list view control. In the List View
Control Attributes window in the dialog editor, set the
Drag mode selection box to
"Move" and the Drop mode
selection box to "Copy+Move". This causes the
control's DRAG-MODE
and DROP-MODE
attributes to be set to DM-MOVE and DM-COPYMOVE,
respectively, 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 (L) 01 #AVAIL (L) 01 #X (I4) 01 #Y (I4) 01 #ORIG-X (I4) 01 #ORIG-Y (I4)
Having done this, we can write the necessary event handlers. The logical
place to start is with the
BEGIN-DRAG
event:
#CONTROL := *CONTROL * PROCESS GUI ACTION INQ-CLICKPOSITION WITH #CONTROL #ORIG-X #ORIG-Y GIVING *ERROR * ADD #CONTROL.OFFSET-X TO #ORIG-X ADD #CONTROL.OFFSET-Y TO #ORIG-Y * PROCESS GUI ACTION SET-CLIPBOARD-DATA WITH 'DUMMYPRIVFMT' 0 GIVING *ERROR
This code consists of three parts:
Getting the click position in client coordinates.
Converting the click position to view coordinates (as mentioned above, the origin of the list view window is not always "(0, 0)").
Putting some dummy data on the drag and drop clipboard, otherwise Natural will not initiate the drag and drop operation. We choose a private clipboard format because, being only dummy data, we deliberately don't want other applications to recognize it.
Next, we provide a handler for the
DRAG-ENTER
event:
PROCESS GUI ACTION INQ-DRAG-DROP WITH
1x #CONTROL GIVING *ERROR
*
IF #CONTROL = *CONTROL
IF #CONTROL.VIEW-MODE = VM-ICON OR
#CONTROL.VIEW-MODE = VM-SMALLICON
#CONTROL.SUPPRESS-DRAG-DROP-EVENT := NOT-SUPPRESSED
ELSE
#CONTROL.SUPPRESS-DRAG-DROP-EVENT := SUPPRESSED
END-IF
ELSE
#CONTROL := *CONTROL
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
END-IF
The above code consists of three parts:
The INQ-DRAG-DROP
action is called to determine the handle of the drag source control.
If the drag source is the current control, then drag source and drop
target are identical. In other words, this is the item re-positioning case.
Because item re-positioning is only allowed in one of the icon views, we
unsuppress the DRAG-DROP
event to allow the drop in this case. Otherwise, we suppress this
event in order to prohibit a drop such that the "no drop" drag
cursor appears. Note that we could have also prevented a drag from occuring at
all by not putting the data on the drag and drop clipboard in this case.
However, although not demonstrated in this example, it is often desired to drag
one or more items from a list view control to another window, even if the
source control is in list or report view mode, for which the above code
provides a better basis.
If the drag source and drop target are different, an attempt is being made to transfer data from another window. In this case, we check to see if data is available in the required format, CF-TEXT, and allow the drop if so. Otherwise the drop is prohibited.
To provide drop emphasis during the dragging of external data across the
list view control, a DRAG-OVER
event handler is supplied:
PROCESS GUI ACTION INQ-DRAG-DROP WITH
1X #CONTROL 1X #X #Y GIVING *ERROR
*
IF #CONTROL <> *CONTROL
#CONTROL := *CONTROL
IF #CONTROL.SUPPRESS-DRAG-DROP-EVENT = NOT-SUPPRESSED
PROCESS GUI ACTION INQ-ITEM-BY-POSITION WITH
#CONTROL #X #Y #ITEM GIVING *ERROR
IF #ITEM <> #DROP-ITEM
IF #DROP-ITEM <> NULL-HANDLE
#DROP-ITEM.SELECTED := #SELECTED
END-IF
#DROP-ITEM := #ITEM
IF #DROP-ITEM <> NULL-HANDLE
#SELECTED := #DROP-ITEM.SELECTED
#DROP-ITEM.SELECTED := TRUE
END-IF
END-IF
END-IF
END-IF
The above code performs the following:
The INQ-DRAG-DROP
action is called to determine the handle of the drag source control and the
current drop position.
If the drag source and drag target are identical (item
re-positioning), no further action is taken, as no drop emphasis is required in
this case. Otherwise the INQ-ITEM-BY-POSITION
action is used to find the list view item (if any) at the current drop
position.
The current target item ("drop item") is tracked in
#DROP-ITEM. Every time this changes, the current selection state
of the new drop item is first checkpointed in #SELECTED, and then
the item is selected to provide the drop emphasis by setting its
SELECTED
attribute to TRUE. In addition the selection state of the old drop
item (if any) is restored to its previously checkpointed value.
Note that the drop emphasis is not applied if a drop is not possible
(i.e., if the SUPPRESS-DRAG-DROP-EVENT
attribute is set to SUPPRESSED).
To perform the actual drop, a
DRAG-DROP
event handler is supplied:
PROCESS GUI ACTION INQ-DRAG-DROP WITH
1x #CONTROL 1x #X #Y GIVING *ERROR
*
IF #CONTROL = *CONTROL
ADD #CONTROL.OFFSET-X TO #X
ADD #CONTROL.OFFSET-Y TO #Y
SUBTRACT #ORIG-X FROM #X
SUBTRACT #ORIG-Y FROM #Y
#ITEM := #CONTROL.SELECTED-SUCCESSOR
REPEAT WHILE #ITEM <> NULL-HANDLE
ADD #X TO #ITEM.RECTANGLE-X
ADD #Y TO #ITEM.RECTANGLE-Y
#ITEM := #ITEM.SELECTED-SUCCESSOR
END-REPEAT
ELSE
IF #DROP-ITEM <> NULL-HANDLE
PROCESS GUI ACTION GET-CLIPBOARD-DATA WITH CF-TEXT #DROP-ITEM.STRING
GIVING *ERROR
#DROP-ITEM.SELECTED := #SELECTED
RESET #DROP-ITEM
END-IF
END-IF
The above code performs the following:
The INQ-DRAG-DROP
action is called to determine the handle of the drag source control and the
current drop position.
The event handler differentiates between the case where the drag source and drop target controls are identical (item re-positioning) and the case where they are distinct (drag from external source).
In the item re-positioning case, the drop position is converted to view coordinates to obtain the "(x, y)"-displacement from the original position, which is then applied to each selected item to perform the move.
In the external source case, the text data is retrieved from the
clipboard directly into the STRING
attribute of the current drop item (if any) to update its label. It is not
necessary to first check whether text is available on the drag and drop
clipboard, as we did that in the
DRAG-ENTER
event, prohibiting a drop and associated
DRAG-DROP
event from taking place at all if this is not the case. After updating the
label, the drop item's previous selection state (prior to the drag) is restored
and #DROP-ITEM reset ready for the next drag operation (if
any).
Lastly, in the case that the user cancels the drag operation, or exits
the bounds of the list view control without having performed a drop, a
DRAG-LEAVE
event handler is supplied:
IF #DROP-ITEM <> NULL-HANDLE #DROP-ITEM.SELECTED := #SELECTED RESET #DROP-ITEM END-IF
The above code simply clears the drop emphasis (if any), by restoring
the old drop item selection state. To satisfy the logic provided for the other
event handlers, #DROP-ITEM is reset, indicating the absence of a
drop item. This is essentially the same code as performed at the end of the
DRAG-DROP
event, since the DRAG-LEAVE
event is not called in the case of a drop. Therefore, any drop emhasis
resetting needs to be done in both places.