Index Index for
Section 3
Index Alphabetical
listing for D
Index Bottom of
page		 

DtDndDropRegister(3)


CDE




NAME

  DtDndDropRegister, DtDndVaDropRegister - specify a drop site


SYNOPSIS

  #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

  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.

  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


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

  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.

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

  Callbacks


  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


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


  When it calls XmDropSiteRegister(3X), 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.





SEE ALSO

  DtDnd(5), DtDtsDataTypeToAttributeValue(3), DtDndDragStart(3),
  DtDndVaDragStart(3), DtDndDropUnregister(3), XmDragContext(3X),
  XmDropSite(3X), XmDropSiteRegister(3X), XmDropSiteUpdate(3X),
  XmDropTransfer(3X), XmDropTransferStart(3X).	DtDndDropUnregister(3);
  XmDragContext, XmDropSite, XmDropSiteRegister, XmDropSiteUpdate,
  XmDropTransfer, XmDropTransferStart in the X/Open CAE Specification, X/Open
  Motif Toolkit API.

Index Index for
Section 3
Index Alphabetical
listing for D
Index Top of
page