DtDndDropRegister(3)

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

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