DtDndDropRegister(library call) DtDndDropRegister(library call)
NAME [Toc] [Back]
DtDndDropRegister, DtDndVaDropRegister - specify a drop site
SYNOPSIS [Toc] [Back]
#include <Dt/Dnd.h>
void DtDndDropRegister(
Widget dropSite,
DtDndProtocol protocols,
unsigned char operations,
XtCallbackList transferCallback,
ArgList argList,
Cardinal argCount);
void DtDndVaDropRegister(
Widget dropSite,
DtDndProtocol protocols,
unsigned char operations,
XtCallbackList transferCallback,
...);
DESCRIPTION [Toc] [Back]
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 set of data transfer protocols in
which the drop site is able to participate. Valid values are:
DtDND_TEXT_TRANSFER
The drop site can transfer a list of text.
DtDND_FILENAME_TRANSFER
The drop site can transfer a list of file names.
DtDND_BUFFER_TRANSFER
The drop site can transfer a list of memory buffers.
A drop site can support any combination of these protocols. A
combination of protocols is specified by the bitwise inclusive OR of
several protocol values.
- 1 - Formatted: January 24, 2005
DtDndDropRegister(library call) DtDndDropRegister(library call)
The operations argument specifies the set of valid operations
associated with a drop site. The operations are:
XmDROP_COPY
Copy operations are valid. The data will be copied from the
drag source.
XmDROP_LINK
Link operations are valid. The data will be linked using an
alternative method.
XmDROP_MOVE
Move operations are valid. The data will be copied, and
optionally deleted, from the drag source.
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 [Toc] [Back]
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 (Boolean)
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.
DtNtextIsBuffer (Boolean)
Specifies whether the drops of text selections should be
treated as buffer drops. This attribute is only valid if
protocols includes DtDND_BUFFER_TRANSFER. If DtNtextIsBuffer
is True, text drops are accepted as unnamed buffers; if it
is False, only drops of the specified protocols are
accepted. The default is False.
- 2 - Formatted: January 24, 2005
DtDndDropRegister(library call) DtDndDropRegister(library call)
DtNpreserveRegistration (Boolean)
Specifies whether to preserve any existing drop site
registration for the dropSite widget. The application can
disable preserving the drop site registration if the
dropSite widget is known not to be registered as a drop site
or that registration is not desired. This may improve drop
site registration performance. If DtNpreserveRegistration
is True, existing drop site registration is preserved; if it
is False, the existing drop site registration is replaced.
The default is True.
DtNdropAnimateCallback (XtCallbackList)
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 applicationsupplied
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.
Callbacks [Toc] [Back]
Once the rendezvous with the drag source has been accomplished, the
application-provided callback functions are called to perform the data
transfer.
First, the transferCallback is called with a reason of
DtCR_DND_TRANSFER_DATA. The application should access the DtDndContext
fields appropriate for the transfer protocol. The application should
parse or type the dropped data to determine whether it is acceptable.
If the dropped data is not acceptable, the status field of the
DtDndTransferCallbackStruct should be set to DtDND_FAILURE.
If the DtNdropAnimateCallback attribute has been specified, the
dropAnimateCallback is then called with a reason of
DtCR_DND_DROP_ANIMATE. The application should perform any
application-provided animations for the drop.
When the transferCallback (or the dropAnimateCallback, if specified)
returns, all memory associated with the drop transfer is freed. Any
data in the callback structures that will be used after the drop
transfer is complete must be copied by the application.
Callback Information [Toc] [Back]
Each of the callbacks for DtDndDropRegister and DtDndVaDropRegister
has an associated callback structure. These callbacks cannot be used
with the XtAddCallback(3) interface.
- 3 - Formatted: January 24, 2005
DtDndDropRegister(library call) DtDndDropRegister(library call)
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;
Widget dragContext;
Boolean completeMove;
DtDndStatus status;
} DtDndTransferCallbackStruct, *DtDndTransferCallback;
The reason argument indicates why the callback was invoked:
DtCR_DND_TRANSFER_DATA.
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 completeMove field should be set to False if an
alternative method will be used to complete the move.
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;
- 4 - Formatted: January 24, 2005
DtDndDropRegister(library call) DtDndDropRegister(library call)
} 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 [Toc] [Back]
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;
int numItems;
union {
XmString *strings;
String *files;
DtDndBuffer *buffers;
} data;
} 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
A list of text is being transferred.
DtDND_FILENAME_TRANSFER
A list of file names is being transferred.
DtDND_BUFFER_TRANSFER
A list of memory buffers is being transferred.
The numItems argument indicates the number of items being transferred.
The data 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 strings argument is valid if the protocol is DtDND_TEXT_TRANSFER.
The strings argument is an array of pointers to Motif strings
- 5 - Formatted: January 24, 2005
DtDndDropRegister(library call) DtDndDropRegister(library call)
containing the text being transferred.
The files argument is valid if the protocol is
DtDND_FILENAME_TRANSFER. It is an array of pointers to the names of
the files being transferred. The file names have been converted to
local host file names where possible.
The buffers argument is valid if the protocol is
DtDND_BUFFER_TRANSFER. It is an array of pointers to DtDndBuffer
structures containing the meory buffers being transferred.
The following structure is used with DtDND_FILENAME_TRANSFER:
typedef struct _DtDndBuffer {
void *bp;
int size;
string name;
} DtDndBuffer;
The bp argument points to the buffer data being transferred.
The size argument indicates the number of bytes in the buffer.
The name argument points to the name of the buffer.
Motif Resources [Toc] [Back]
When it calls XmDropSiteRegister(3), 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
- 6 - Formatted: January 24, 2005
DtDndDropRegister(library call) DtDndDropRegister(library call)
+ XmNdropSiteOperations
+ XmNdropSiteType
+ XmNimportTargets
+ XmNnumImportTargets
RETURN VALUE [Toc] [Back]
The DtDndDropRegister and DtDndVaDropRegister functions return no
value.
SEE ALSO [Toc] [Back]
Dt/Dnd.h - DtDnd(5), DtDtsDataTypeToAttributeValue(3),
DtDndDragStart(3), DtDndDragStart(3), DtDndDropUnregister(3),
XmDragContext(3), XmDropSite(3), XmDropSiteRegister(3),
XmDropSiteUpdate(3), XmDropTransfer(3), XmDropTransferStart(3).
- 7 - Formatted: January 24, 2005 [ Back ] |
