DtDndDropRegister(3) — Subroutines

NAME

DtDndDropRegister, DtDndVaDropRegister − specify a drop site

SYNOPSIS

#include <Dt/Dnd.h>
void DtDndDropRegister(Widget dropSite,
DtDndProtocol ∗protocols,
Cardinal numProtocols,
unsigned char operations,
XtCallbackList transferCallback,
ArgList argList,
Cardinal argCount);

void DtDndVaDropRegister(Widget dropSite,
DtDndProtocol ∗protocols,
Cardinal numProtocols,
unsigned char operations,
XtCallbackList transferCallback,
...);

DESCRIPTION

The DtDndDropRegister() and DtDndVaDropRegister() functions register a Motif drop site with import targets based on the specified data transfer protocols. DtDndDropRegister() may be called to register a widget as a drop site at any time, typically soon after the widget is created.

The only difference between DtDndDropRegister() and DtDndVaDropRegister() is how the argument list is passed. The argument list is passed as an ArgList to DtDndDropRegister() and using VarArgs for DtDndVaDropRegister().

The dropSite argument specifies the widget to register as the drop site.

The protocol argument specifies the list of data transfer protocols in which the drop site is able to participate. Valid values are:

DtDND_TEXT_TRANSFER
The drop site can transfer text.

DtDND_FILENAME_TRANSFER
The drop site can transfer a list of file names.

DtDND_DATA_TRANSFER
Other types of data can be transferred. The XmNimportTargets and XmNnumImportTargets resources must also be specified in the argument list.

The numProtocols argument specifies the number of protocols in the protocol list.

The operations argument specifies the set of valid operations associated with a drop site. The operations are:

XmDROP_COPY
Copy operations are valid.

XmDROP_LINK
Link operations are valid.

XmDROP_MOVE
Move operations are valid.

A drop site can support any combination of these operations. A combination of operations is specified by the bitwise inclusive OR of several operation values.

The transferCallback argument specifies the callback to be called when the dropped data object has been received by the drop site. The transferCallback is responsible for transferring the data from the dropData to the appropriate internal data structures at the drop site. The arguments for the convertCallback are the Motif Drag Context, an XtPointer to application-supplied client data, and an XtPointer to a DtDndConvertCallbackStruct structure.

The argList argument specifies the optional argument list.

The argCount argument specifies the number of arguments in argList.

Argument Value Pairs

The DtDndDragStart() and DtDndVaDragStart() functions support the following optional argument-value pairs. Motif resources can be set via the argument list as well, provided they are not resources that are used by the drag and drop subsystem; see Motif Resources.

DtNregisterChildren
Specifies whether children of a composite drop site widget should be registered. If True, then the composite dropSite widget and its children are registered as a single drop site. If False, then only the dropSite widget itself is registered as the drop site. The default is False.

DtNacceptUntypedDrops
Specifies whether to accept drops of untyped data. If True, the drop site accepts any type of data and uses data typing to process the data appropriately. If False, the drop site accepts the types of data specified by protocols and XmNimportTargets. The default is False.

DtNdropAnimateCallback
Specifies the callback to be called when the drop is complete. This enables graphical animation upon successful completion of a drop. This callback is called after the transferCallback is called and after Motif performs the “melt” effect. The arguments for the DtNDropAnimateCallback are the Motif Drag Context, an XtPointer to application-supplied client data, and an XtPointer to a DtDndDropAnimateCallbackStruct structure. The Motif Drag Context is in the process of being destroyed at this point so the application must not use it or any of its values in the dropAnimateCallback. The default is NULL.

Callback Information

Each of the callbacks for DtDndDropRegister() and DtDndVaDropRegister() has an associated callback structure. These callbacks cannot be used with the XtAddCallback(3X) interface.

A pointer to the following structure is passed to the transferCallback:

typedef struct {
int reason;
XEvent ∗event;
Position x, y;
unsigned char operation;
DtDndContext ∗dropData;
Boolean completeMove;
DtDndStatus status;
} DtDndTransferCallbackStruct, ∗DtDndTransferCallback;

The reason argument indicates why the callback was invoked: DtCR_DND_DROP_TRANSFER.

The event argument is always set to NULL by Motif drag and drop.

The x and y arguments indicate the coordinates of the dropped item in relation to the origin of the drop site widget.

The operation argument indicates the type of drop: XmDROP_COPY, XmDROP_MOVE or XmDROP_LINK.

The dropData argument contains the data that has been dropped.

The dragContext argument specifies the ID of the Motif Drag Context widget associated with this drag and drop transaction.

The completeMove argument indicates whether a move operation needs to be completed. If the operation is XmDROP_MOVE and completeMove is set to False in the transferCallback, a delete does not occur. By default, completeMove is True and a delete occurs to complete the move operation.

The status argument indicates the success or failure of the data transfer. If the data could not be appropriately moved, copied or linked, the status field must be set to DtDND_FAILURE. By default, the status field is set to DtDND_SUCCESS.

A pointer to the following structure is passed to the dropAnimateCallback:

typedef struct {
int reason;
XEvent ∗event;
Position x, y;
unsigned char operation;
DtDndContext ∗dropData;
} DtDndDropAnimateCallbackStruct, ∗DtDndDropAnimateCallback;

The reason argument indicates why the callback was invoked. The valid reason is DtCR_DND_DROP_ANIMATE.

The event argument is always set to NULL by Motif drag and drop.

The x and y arguments indicate the coordinates of the dropped item in relation to the origin of the drop site widget.

The operation argument indicates the type of drop: XmDROP_COPY, XmDROP_MOVE or XmDROP_LINK.

The dropData argument contains the data that has been dropped.

Structures

The following structures are used by the drop site in the transferCallback to get the transferred data from the drag and drop subsystem. The DtDndContext structure is passed as dropData in the DtDndTransferCallbackStruct structure.

typedef struct {
DtDndProtocol protocol;
union {
DtDndFile file;
DtDndText text;
DtDndData data;
} u;
} DtDndContext;

The protocol argument indicates the data transfer protocol under which the data in the DtDndContext is being transferred. Valid values are:

DtDND_TEXT_TRANSFER
Text is being transferred.

DtDND_FILENAME_TRANSFER
A list of file names is being transferred.

DtDND_DATA_TRANSFER
Another type of data is being transferred.

The u argument is a union containing data that the drop site should access in the format corresponding to the specified protocol. The data structures corresponding to the transfer protocols are as follows.

The following structure is used with the DtDND_FILENAME_TRANSFER protocol.

typedef struct {
char ∗hostName;
char ∗∗fileNames;
char ∗∗fileFormats;
Cardinal numItems;
} DtDndFile;

The hostName argument points to the name of the host machine on which the drag source resides.

The fileNames argument is an array of pointers to the names of the files being transferred.

The fileFormats argument is an array of pointers optionally containing the file formats of the files being transferred, as specified in the data typing database.

The numItems argument indicates the number of files in the list of fileNames and the number of formats in fileFormats.

The following structure is used with the DtDND_TEXT_TRANSFER protocol:

typedef struct {
XmString ∗strings;
Cardinal numItems;
} DtDndText;

The strings argument contains pointers to the strings being transferred.

The numItems argument indicates the number of strings in the list of strings.

The following structure is used with the DtDND_DATA_TRANSFER protocol:

typedef struct {
Atom target;
Atom type;
void ∗buf;
int format;
int length;
} DtDndData;

The target argument specifies what the application-defined data is.

The type argument specifies the type of the data, such as XA_STRING, XA_INTEGER or an application-defined type.

The buf argument points to the data being transferred.

The format argument indicates the format of the data by specifying the character width in bits. Valid values are 8, 16 and 32.

The length argument indicates the number of pieces of data in the buffer. Thus, the length of the buffer in bytes is format / 8 × length.

Motif Resources

When it calls XmDropSite()Register3X, the DtDndDropRegister() and DtDndVaDropRegister() functions set Motif resources; the application must not modify the values of any of these resources. Resources other than those listed here can be used and are passed through to the underlying XmDropRegister(). call.

The following resources are modified by DtDndDropRegister() and DtDndVaDropRegister() in the Motif Drag Context.

XmNdestroyCallback
XmNdropTransfers
XmNnumDropTransfers
XmNtransferProc
XmNtransferStatus

The following resources are modified by DtDndDropRegister() and DtDndVaDropRegister() in the Motif Drop Site.

XmNdropProc
XmNdropSiteOperations
XmNdropSiteType
XmNimportTargets
XmNnumImportTargets

RETURN VALUE

The DtDndDropRegister() and DtDndVaDropRegister() functions return no value.

Museum

Related Articles