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 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
