This document covers the following topics:
Both clipboard and drag/drop data transfer make use of a logical
clipboard at the Natural language level, allowing a single set of methods to
handle both requirements. The
PROCESS
GUI actions for handling the logical clipboard are as
follows: OPEN-CLIPBOARD,
SET-CLIPBOARD-DATA,
CLOSE-CLIPBOARD,
GET-CLIPBOARD-DATA and
INQ-FORMAT-AVAILABLE. Each Natural
process has exactly one logical clipboard, which is why it is referred to in
the product documentation as the "local" clipboard.
OPEN-CLIPBOARD is the first step in
building up the logical clipboard data. It takes an optional parameter (owner
window), which is typically the handle of the control sourcing the data. If
anything was previously on the logical clipboard, this action empties it. Note
that you don't need to call this for drag and drop, because Natural does this
implicitly before raising the
BEGIN-DRAG event (see below).
SET-CLIPBOARD-DATA puts the actual data
on the logical clipboard. The first parameter is the clipboard format,
specified as a string. There are two pre-defined formats (defined in NGULKEY1
as CF-TEXT and CF-FILELIST), which are used for standard text transfer, and
lists of files (suitable for data exchange with the Windows Explorer and many
other applications) respectively. In addition, an arbitrary string (which
should not begin with a dgit) should be used to indicate a private clipboard
format that only Natural applications can understand (they just need to know
the format string so they can pass it to
GET-CLIPBOARD-DATA to retrieve the data).
The second and subsequent arguments are an arbitrary number of data operands.
These can be any combination of arrays (incl. index ranges) or scalars (incl.
dynamic and large alpha variables). Arrays are internally expanded into their
individual elements, which are then handled individually as for scalars.
For example, the following code:
DEFINE DATA LOCAL
1 #ARR(A1/2,3) INIT (1,1)<'A'> (1,2)<'B'> (1,3)<'C'>
(2,1)<'X'> (2,2)<'Y'> (2,3)<'Z'>
END-DEFINE
PROCESS GUI ACTION SET-CLIPBOARD-DATA WITH CF-TEXT #ARR(*,*)
is equivalent to:
PROCESS GUI ACTION SET-CLIPBOARD-DATA WITH CF-TEXT 'A' 'B' 'C' 'X' 'Y' 'Z'
For the pre-defined formats, the operands must be alphanumeric
(format A). For private formats, the data arguments can be of almost any type.
Exception: handle variables (incl. HANDLE OF OBJECT) are not
supported, because they are process-specific. The data for private formats is
stored "as-is" (i.e., no conversion).
Note that multiple data formats can be placed on the clipboard by
performing a SET-CLIPBOARD-DATA action for each
required format. However, any call to
SET-CLIPBOARD-DATA for a particular
format replaces any data that may already exist in that format.
Note also that the data is not placed on the Windows clipboard. This is done when the logical clipboard is closed (see below).
CLOSE-CLIPBOARD closes the logical
clipboard, and places the data on the Windows clipboard, so that it becomes
available for pasting into other applications. The data cannot be modified by
SET-CLIPBOARD-DATA after this call. Note
that this call is not necessary for drag and drop because you usually don't
need to also make the dragged data available for pasting. Drag and drop can
work directly with the logical clipboard.
GET-CLIPBOARD-DATA is used by the
application performing the paste or acting as the drop target to retrieves the
data from the drag-drop clipboard (if a drag and drop operation is in progress)
or from the Windows clipboard otherwise. The drag-drop clipboard is a synonym
for the logical clipboard belonging to the source Natural process.
SET-CLIPBOARD-DATA, a clipboard format is
specified, followed by an arbitrary list of data operands (with the same format
type restrictions). For private formats, the operands need not have the same
format type as used in the
GET-CLIPBOARD-DATA action. For example,
you can place an integer on the clipboard and read it back into a packed
numeric (P) variable. Internally, a MOVE conversion is done.
Therefore, if different format types are used for setting and getting the data,
they must be MOVE-compatible.
For pre-defined formats, where the individual data items are either
delimited by CR/LF (for CF-TEXT format) or by null-terminators (for CF-FILELIST
format), only one item is usually read into each receiving field. Exception: If
the last receiving field is a dynamic alpha variable, it receives all remaining
data items, including the delimiters. This exception allows the application to
use (for example) a single dynamic alpha variable to set and get multiple lines
of data or multiple file/directory names. Regardless of the format used, if too
many receiving operands are specified, the excess fields are reset (see the
RESET statement). Note
that individual data fields may be skipped by using the
nX notation. For example,
5x skips 5 data items (where a "data item" is a
single line for CF-TEXT format).
INQ-FORMAT-AVAILABLE is used for querying
whether data is available in a given format (see specification for syntax). It
is typically used to determine whether to enable or disable the
command, or whether to display the "no
drop" cursor for drag/drop operations.
The actual clipboard data transfer has been covered above. However,
Natural allows you to define signals, menu items and toolbar items of the
special types , ,
, and
, which (unlike normal commands) do not raise
CLICK events. For input fields, edit
areas, selection boxes and table controls, it's obvious what Natural should do,
and Natural does this implicitly. For Natural, these commands now support list
boxes and ActiveX controls. However, the mechanism is different in this case,
because it is ambiguous as to how Natural should respond to these commands.
Therefore, Natural needs some assistance from the application. This assistance
comes in the form of six new events:
CUT,
COPY,
PASTE,
DELETE,
UNDO and
CLIPBOARD-STATUS, all of which are
suppressible (via the new
SUPPRESS-CUT-EVENT,
SUPPRESS-COPY-EVENT,
SUPPRESS-PASTE-EVENT,
SUPPRESS-DELETE-EVENT,
SUPPRESS-UNDO-EVENT and
SUPPRESS-CLIPBOARD-STATUS-EVENT
attributes). All six events are suppressed by default. The
CUT,
COPY,
PASTE,
DELETE and
UNDO events are raised whenever the
respective command is triggered. The corresponding event suppression flags are
used by Natural to decide whether to enable or disable the corresponding
command(s) in the user interface.
The
CLIPBOARD-STATUS event is sent to the
focus control during idle processing to give the application a chance to set
these event suppression flags dynamically according to the context (e.g.,
whether or not there is an active selection). Natural raises this event before
it queries the event suppression flags for the purpose of clipboard command
status updating). Note that these new events are (currently) only sent to list
boxes and ActiveX controls (and, of course, only if they currently have the
focus). Input fields, selection boxes, etc., are still handled implicitly.
The
CLIPBOARD-STATUS event is only raised if
there is at least one clipboard command in the user interface that needs to be
updated.
The following example shows a typical
CLIPBOARD-STATUS event for a list box
control:
DEFINE DATA LOCAL 1 #CONTROL HANDLE OF GUI 1 #FMT (A10) CONST<'MYDATAFMT'> 1 #AVAIL (L) END-DEFINE ... #CONTROL := *CONTROL /* /* Cut, Copy & Delete are enabled if an item is selected, /*or disabled otherwise /* IF #CONTROL.SELECTED-SUCCESSOR <> NULL-HANDLE #CONTROL.SUPPRESS-CUT-EVENT := NOT-SUPPRESSED #CONTROL.SUPPRESS-COPY-EVENT := NOT-SUPPRESSED #CONTROL.SUPPRESS-DELETE-EVENT := NOT-SUPPRESSEDELSE #CONTROL.SUPPRESS-CUT-EVENT := SUPPRESSED #CONTROL.SUPPRESS-COPY-EVENT := SUPPRESSED #CONTROL.SUPPRESS-DELETE-EVENT := SUPPRESSED END-IF /* /* Paste command is enabled if data is available in a /* recognized format, or disabled otherwise /* PROCESS GUI ACTION INQ-FORMAT-AVAILABLE WITH #FMT #AVAIL GIVING *ERROR /* IF #BOOL #CONTROL.SUPPRESS-PASTE-EVENT := NOT-SUPPRESSED ELSE #CONTROL.SUPPRESS-PASTE-EVENT := SUPPRESSED END-IF
Drag and drop operations can be triggered automatically (for list
boxes and bitmap controls) or manually, via the new
PERFORM-DRAG-DROP action (typically for
ActiveX controls in response to control-specific mouse click or drag start
events). For automatic drag/drop, the mouse cursor must be over the active
selection (if any). For manual drag/drop, the parameters for
PERFORM-DRAG-DROP include the handle of
the control that should receive the drag/drop events (the drag source), and an
optional flag indicating whether drag and drop should begin immediately, or
only after the user moves the mouse a system-defined minimum number of pixels.
Both automatic and manual drag/drop use the same code internally, so the same
events are received in both cases.
Drag/drop is controlled by two new I4 attributes,
DRAG-MODE (for drag
sources) and DROP-MODE (for drop
targets). These attributes can be set to one of 8 values (defined in NGULKEY1):
DM-NONE (no drag/drop allowed), DM-COPY (copy
allowed), DM-MOVE (move allowed), DM-COPYMOVE (copy
and move allowed), DM-LINK (link allowed),
DM-COPYLINK (copy and link allowed), DM-MOVELINK
(move and link allowed), DM-COPYMOVELINK (copy, move and link
allowed). Link operations imply that the drop target should create a link to
the source data, rather than creating a copy of it. For file operations,
desktop shortcuts are typically used (not currently explicitly supported by
Natural). Drag operations are only initiated if the source's
DRAG-MODE attribute is
set to something other that the default DM-NONE value. In
addition, the application must respond to the
BEGIN-DRAG event (see below).
Control types capable of acting as drop targets are: ActiveX
controls, bitmap controls, list boxes, control boxes, edit areas, and dialogs
(tab controls and table controls are planned for the future but are not
currently supported). These windows are, however, only registered with OLE as
drop targets if their DROP-MODE attribute is
set to something other that the default DM-NONE value. During a
drag/drop operation, OLE automatically searches up through the window
hierarchy, starting with the window immediately under the cursor, until it
finds a window that has been registered as a drop target. This is the window
that gets the OLE drop notifications and therefore is the window that receives
the Natural drag/drop events (see below).
The new drag/drop related events are:
BEGIN-DRAG,
END-DRAG,
DRAG-ENTER,
DRAG-OVER and
DRAG-LEAVE. In addition, the existing
DRAG-DROP event (for the Mickey Mouse
non-OLE drag/drop support for bitmap controls) is also used. All events are
suppressible via the appropriate event suppression attributes (SUPPRESS-BEGIN-DRAG-EVENT
etc.), all of which are SUPPRESSED by default.
The
BEGIN-DRAG event (if not suppressed) is
sent to the drag source on initiation of a drag operation. The application
must use the
SET-CLIPBOARD-DATA action to place some
data on the drag/drop clipboard before returning from this event, otherwise the
drag/drop operation is implicitly cancelled without the mouse cursor having
changed. Note that there is no need to call either of the
OPEN-CLIPBOARD or
CLOSE-CLIPBOARD actions.
The
END-DRAG event (if not suppressed) is
sent to the drag source after a drag/drop operation has completed (even if the
drag operation was cancelled). The main use of this event is to delete the
source data if a Move operation occurred. The application can find out whether
a Move operation has occurred by calling the existing
INQ-DRAG-DROP action, which has been
extended with two new optional integer output parameters. The first of these
new parameters indicates which mouse buttons are currently pressed (1 = Left
button, 2 = Right button, 4 = Middle button, or a combination thereof). The
second new parameter is the one we need here, and contains the drop effect
resulting from a drag/drop operation (DM-NONE if no drop or if the
operation was cancelled, DM-COPY if a Copy operation was
performed, DM-MOVE if a Move operation was performed, and
DM-LINK if a link operation was performed.
The
DRAG-ENTER event (if not suppressed) is
sent to the drop target when the drag cursor (re-)enters the region occupied by
the drop target. The application typically responds to this event by calling
the INQ-FORMAT-AVAILABLE action to find out
if a compatible data format is available on the clipboard, and then setting the
SUPPRESS-DRAG-DROP-EVENT
attribute accordingly. The
SUPPRESS-DRAG-DROP-EVENT
is important because it not only determines whether the
DRAG-DROP event should be raised, but
also informs Natural as to whether a drop should be allowed. After raising the
DRAG-ENTER and
DRAG-OVER events, Natural inspects the
SUPPRESS-DRAG-DROP-EVENT
attribute and displays a "no drop" symbol. Otherwise, the drop
effect is determined by the combination of the drag source's
DRAG-MODE value, the drop target's
DROP-MODE value, and the augmentation
keys (SHIFT and CTRL) that are currently being
pressed.
The
DRAG-OVER event (if not suppressed) is
frequently sent to the drop target as the drag cursor moves over the drop
target. It can be used, for example, to update the drop emphasis (if any) as
the user traverses the items within the control and/or to update the
SUPPRESS-DRAG-DROP-EVENT
attribute if the feasibility of a drop operation depends on the position within
the drop target.
The
DRAG-LEAVE event (if not suppressed) is
sent to the drop target when the drag cursor leaves the region occupied by the
drop target without a drop having occurred. This is mainly used (if at all) to
remove the drop emphasis (if any) applied in the
DRAG-OVER event.
The
DRAG-DROP event (if not suppressed) is
sent to the drop target when the user performs a drop. drag cursor leaves the
region occupied by the drop target without a drop having occurred. The
application should respond to this by effectively performing a Paste operation,
using the current relative position within the control, if necessary. Both the
relative position and the type of operation can be retrieved via the
INQ-DRAG-DROP action. The latter is
returned in the new (optional) "drop effect" parameter (see the
description of the
END-DRAG event above for more
information).
For list boxes, a new "insertion mark
(i)" style can be used to indicate that a dashed horizontal line
be used to indicate the current insert position when the drag cursor is moved
over the control (assuming it is a drop target). The application cannot query
the insertion mark position directly, but can find out where to insert the data
by querying the relative position within the control via the
INQ-DRAG-DROP action, then passing these
coordinates to the
INQ-ITEM-BY-POSITION action, as in the
following example:
DEFINE DATA LOCAL 1 #Y (I4) 1 #CONTROL HANDLE OF GUI 1 #ITEM HANDLE OF GUIEND-DEFINE ... /* DRAG-DROP event: PROCESS GUI ACTION INQ-DRAG-DROP WITH 4X #Y GIVING *ERROR * IF #Y < 0 #Y := 0 END-IF #CONTROL := *CONTROL PROCESS GUI ACTION INQ-ITEM-BY-POSITION WITH #CONTROL 0 #Y #ITEM GIVING *ERROR
After the above code has executed, the variable #ITEM
contains the handle of the item immediately following the insertion point. You
can then dynamically insert one or more list box items at this position by
calling the ADD action with the WITH
PARAMETERS clause, setting the
SUCCESSOR attribute to
#ITEM.
Note that the correction for negative y-coordinate in the above
example is necessary to cover the situation where the drop position is on the
list boxes top border. If no correction would be made here, #ITEM
would be set to NULL-HANDLE and the new list box item(s) would be
added undesirably at the end of the list instead of at the beginning if we were
to directly use #ITEM as the
SUCCESSOR attribute, as
described above.
For convenience, here is a brief overview of the steps involved in implementing drag-drop in Natural applications:
Set the DRAG-MODE for each drag source. If the
drag source is a bitmap control, its
DRAGGABLE attribute
must also be set to TRUE.
Set
SET-CLIPBOARD-DATA in the
BEGIN-DRAG event for each drag source to
provide the transfer data.
Set the DROP-MODE for each drop target.
In the
DRAG-ENTER event, use the
INQ-FORMAT-AVAILABLE action to set the
SUPPRESS-DRAG-DROP-EVENT
attribute to NOT-SUPPRESSED (0) if a supported clipboard format is
available, or SUPPRESSED (1) otherwise. If the control can also
act as a drag source and you need to prohibit drag-drop operations within the
control, call INQ-DRAG-DROP to get the source control
handle and compare it to the current control
(*CONTROL), suppressing the drag-drop event if
both are identical.
If the effect of the drop is position-sensitive within the
target control, use the
INQ-DRAG-DROP action within the
DRAG-OVER event to get the current
position, determine the item under the drag cursor (e.g. via the
INQ-ITEM-BY-POSITION action) and set the
SUPPRESS-DRAG-DROP-EVENT
attribute appropriately. Highlight the current item if desired.
If the current item was highlighted in step 5 above, unhighlight
it (if necessary) in the
DRAG-LEAVE and (potentially)
DRAG-DROP events.
Use
GET-CLIPBOARD-DATA in the
DRAG-DROP event to retrieve the transfer
data and process it accordingly.
In the
END-DRAG event for the drag source,
delete the source data if the drop effect returned by
INQ-DRAG-DROP is set to
DM-MOVE.
If the drag source is an ActiveX control, call the
PERFORM-DRAG-DROP action to initiate the
drag-drop operation in response to a "MouseDown"
event (for example) if a location within the current selection is clicked.
One of the problems in setting or retrieving data that may need to be placed or already have been placed on the Windows or drag-drop clipboard in response to a user interaction is being able to cope with an arbitrary amount of data at run-time. For example, the user may select a single, a few, or possibly even hundreds or thousands of list box items before performing a clipboard or drag-drop operation on them. With fixed-size arrays, one would have to define huge arrays to cope with the worst-case scenario, even though typically only a small percentage would be used most of the time.
There are two possible solutions to this problem available in
Natural. The first way is to use a single dynamic alpha variable to contain all
items to be set or retrieved. The application is then responsible for building
up the items (including delimiters) in the dynamic variable before calling
SET-CLIPBOARD-DATA, and for extracting
the items from the dynamic variable after calling
GET-CLIPBOARD-DATA. This approach is not
possible for private formats, because these are not delimited.
The second approach is to make use of X-Arrays. For setting clipboard data, these behave similarly to fixed-size arrays, except that their size can be modified to contain exactly the number of elements needed in a specific situation. For example, if there are 17 items that need to be written to the clipboard, then you can use:
DEFINE DATA LOCAL 1 #X-ARR(A80/1:*) 1 #UPB (I4) INIT <17> END-DEFINE RESIZE ARRAY #X-ARR TO (1:#UPB) PROCESS GUI ACTION SET-CLIPBOARD-DATA WITH CF-TEXT #X-ARR(*)
instead of having to use a wastefully large fixed array, of which only a small range is used:
DEFINE DATA LOCAL 1 #ARR(A80/10000) 1 #UPB (I4) INIT <17> END-DEFINE PROCESS GUI ACTION SET-CLIPBOARD-DATA WITH CF-TEXT ARR(1:#UPB)
When retrieving clipboard data, X-Arrays are even more useful, because the application does not know in advance how many items are on the clipboard. Passing all array elements (10,000 in the above example) would be relatively slow, because all unused elements need to be reset.
However, if an X-Array is used instead, Natural automatically
resizes the array to (1:N), where N is the minimum of the number of items
(remaining) on the clipboard and the array's maximum upper bound (as defined in
DEFINE-DATA, where
* indicates the maximum possible value). Note that there are three
restrictions on the use of X-Arrays in conjunction with
GET-CLIPBOARD-DATA:
The X-Array must be the last (or only) parameter.
Only 1-dimensional X-Arrays are supported.
The X-Arrays defined range must include the element 1.
Here is an example program illustrating the use of a dynamic X-Array for retrieving clipboard data, including the use of a second X-Array to store and display the data lengths:
DEFINE DATA LOCAL 1 #FMT (A10) CONST<'MYDATAFMT'> 1 #X-ARR (A/1:*) DYNAMIC 1 #X-LEN (I4/1:*) 1 #UPB (I4) 1 #I (I4) END-DEFINE PROCESS GUI ACTION OPEN-CLIPBOARD GIVING *ERROR PROCESS GUI ACTION SET-CLIPBOARD-DATA WITH #FMT 'MIKE' 'FRED' 'JIM' 'LULU' 'FRANK' 'JANA' 'ELIZABETH' 'TONY' GIVING *ERROR PROCESS GUI ACTION CLOSE-CLIPBOARD GIVING *ERROR PROCESS GUI ACTION GET-CLIPBOARD-DATA WITH #FMT #X-ARR(*) GIVING *ERROR #UPB := *UBOUND(#X-ARR) RESIZE ARRAY #X-LEN TO (1:#UPB) FOR #I 1 #UPB #X-LEN(#I) := *LENGTH(#X-ARR(#I)) END-FOR DISPLAY #X-ARR(*) (AL=10) #X-LEN(*) / '*** END OF DATA ***' END