DtDndDragStart(3)

     NAME
          DtDndDragStart, DtDndVaDragStart - initiate a drag

     SYNOPSIS
          #include <Dt/Dnd.h>

          Widget DtDndDragStart(Widget dragSource,
                                XEvent *event,
                                DtDndProtocol protocol,
                                Cardinal numItems,
                                unsigned char operations,
                                XtCallbackList convertCallback,
                                XtCallbackList dragFinishCallback,
                                ArgList argList,
                                Cardinal argCount);

          Widget DtDndVaDragStart(Widget dragSource,
                                  XEvent *event,
                                  DtDndProtocol protocol,
                                  Cardinal numItems,
                                  unsigned char operations,
                                  XtCallbackList convertCallback,
                                  XtCallbackList dragFinishCallback,
                                  ...);

     DESCRIPTION
          The DtDndDragStart() and DtDndVaDragStart() functions
          initiate a Motif drag, with drag visuals appropriate to the
          type of data being dragged, and updates the translation
          table of the drag context.  Either of the functions is
          called from the application's event handler, which
          interprets mouse events to determine when a drag should
          begin.

          The only difference between DtDndDragStart() and
          DtDndVaDragStart() is how the argument list is passed.  The
          argument list is passed as an ArgList to DtDndDragStart()
          and using varargs for DtDndVaDragStart().

          The dragSource argument is the widget that received the
          event that triggered the drag.

          The event argument is the button press or button motion
          event that triggered the drag.

          The protocol argument specifies the protocol used for the
          data transfer.  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 specifies the number of items being
          dragged.

          The operations argument indicates which operations the
          dragSource supports.  The operations are:

             XmDROP_COPY
                   Copy operations are valid.

             XmDROP_LINK
                   Link operations are valid.

             XmDROP_MOVE
                   Move operations are valid.

          A drag source can support any combination of these
          operations.  A combination of operations is specified by the
          bitwise inclusive OR of several operation values.  For
          example, to support the move and copy operations, the
          application can specify:

               XmDROP_MOVE | XmDROP_COPY

          The convertCallback argument is a callback function that is
          invoked when a drop has started and the drop site has
          requested data from the drag source.  The convertCallback is
          responsible for providing the data that is transferred to
          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 dragFinishCallback argument is a callback function that
          is invoked when the drag and drop transaction is complete.
          The dragFinishCallback is called after the convertCallback,
          if applicable.  (The convertCallback is called only after a
          drop has started on an eligible drop site, whereas
          dragFinishCallback is called after the drag finishes,
          whether or not a drop occurred.)  The dragFinishCallback
          should reset any drag motion handler and free any memory
          allocated by the drag source during the drag and drop
          transaction.  The arguments for the dragFinishCallback are
          the Motif Drag Context, an XtPointer to application-supplied
          client data, and an XtPointer to a
          DtDndDragFinishCallbackStruct structure.

        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.

             DtNsourceIcon (Widget)
                   Specifies the XmDragIcon used to represent the data
                   being dragged.  This icon is created using either
                   DtDndCreateSourceIcon(3) or XmCreateDragIcon(3X).
                   If DtNsourceIcon is NULL, then a default icon is
                   used, which is appropriate for the data begin
                   dragged.  The default value is NULL.

             DtNbufferIsText (Boolean)
                   Specifies whether the dragged buffer should also be
                   sourced as text, allowing the buffer to be dropped
                   onto text widgets.  This attribute is only valid if
                   protocol DtDND_BUFFER_TRANSFER and is ignored for
                   other transfers.  If DtNbufferIsText is True, the
                   buffer is sourced as text in addition to being
                   sourced as buffers; if it is False, the buffers are
                   sourced only as buffers.

             DtNdropOnRootCallback
                   Specifies the callback to be invoked when the drop
                   occurs on the desktop.  This callback is only for
                   use by specialized clients such as file managers.
                   If DtNdropOnRootCallback is NULL, then drops onto
                   the desktop background are not allowed.  The
                   default value is NULL.

        Callbacks
          Once the rendezvous with the drop site has been
          accomplished, the application-provided callback functions
          are called to perform the transfer of the dragged data.

          First, the convertCallback is called with a reason of
          DtCR_DND_CONVERT_DATA.  The application must set the
          DtDndContext fields appropriate to the transfer protocol to
          provide the data to be transferred to the drop site.

          If the drag operation is XmDROP_MOVE and the drop site
          requests that the move be completed, the convertCallback is
          called again with a reason of DtCR_DND_CONVERT_DELETE.  The
          application should delete its version of the dragged data.

          Once the data transfer is complete, the dragFinishCallback
          is called with a reason of DtCR_DND_DRAG_FINISH.  The
          application should free any memory allocated in the
          convertCallback and restore any application state.

        Callback Information
          Each of the callbacks for DtDndDragStart() and

          DtDndVaDragStart() 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
          convertCallback:

               typedef struct {
                   int reason;
                   XEvent *event;
                   DtDndContext *dragData;
                   DtDndStatus status;
               } DtDndConvertCallbackStruct, *DtDndConvertCallback;

          The reason argument indicates why the callback was invoked.
          The possible reasons for this callback are:

             DtCR_DND_CONVERT_DATA
                   The callback provides the requested data by setting
                   appropriate fields in the dragData structure.

             DtCR_DND_CONVERT_DELETE
                   The callback completes the XmDROP_MOVE operation by
                   deleting its copy of the dragged data.

          The event argument points to the XEvent that triggered the
          callback.

          The dragData argument specifies the DtDndContext that
          contains the data to be dragged.  If the reason argument is
          DtCR_DND_CONVERT_DATA, the application must provide the data
          by setting the relevant fields in the DtDndContext, as
          described in the following Structures section.  If the
          reason argument is DtCR_DND_CONVERT_DELETE, the application
          must delete the original data that completes a move
          operation.

          The status argument indicates the status of the conversion.
          The application can set this to DtDND_FAILURE to cancel the
          conversion and consequently the drag and drop operation.
          The value of status is normally DtDND_SUCCESS.

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

               typedef struct {
                   int reason;
                   XEvent *event;
                   DtDndContext *dragData;
                   Widget sourceIcon;
               } DtDndDragFinishCallbackStruct, *DtDndDragFinishCallback;

          The reason argument indicates why the callback was invoked.
          The valid reason for this callback is DtCR_DND_DRAG_FINISH.

          The event argument points to the XEvent that triggered the
          callback.

          The sourceIcon argument specifies the source icon registered
          in the call to DtDndDragStart.  This widget is provided to
          allow the application to free data associated with the
          source icon and optionally destroy the source icon.

          The dragData argument specifies the DtDndContext that
          contains the data that was dragged.  The application should
          free any data it associated with the dragData.

        Structures
          The following structures are used by the drag source in the
          convertCallback and dragFinishCallback to communicate data
          between the application and the drag and drop subsystem.
          The DtDndContext structure is passed to these callbacks as
          dragData in the callback structure appropriate to the
          callback.

          In the convertCallback, the application that is acting as
          the drag source is responsible for filling in the
          DtDndContext structure with the data being transferred.

          In the dragFinishCallback, the application acting as the
          drag source is responsible for freeing any data it allocated
          for use in the DtDndContext structure.

               typedef struct _DtDndContext {
                   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 should be
          stored and read 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 XmDragStart(3X), the DtDndDragStart() function
          sets 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 XmDragStart() call.

          The following resources are modified by DtDndDragStart() and
          DtDndVaDragStart() in the Motif Drag Context:

               XmNblendModel

               XmNclientData
               XmNconvertProc
               XmNcursorBackground
               XmNcursorForeground
               XmNdragDropFinishCallback
               XmNdragOperations
               XmNdropFinishCallback
               XmNdropStartCallback
               XmNexportTargets
               XmNnumExportTargets
               XmNsourcePixmapIcon
               XmNtopLevelEnterCallback

          The following resources are modified by DtDndDragStart() and
          DtDndVaDragStart() in the Motif Drag Icon:

               XmNattachment
               XmNdepth
               XmNheight
               XmNhotX
               XmNhotY
               XmNmask
               XmNoffsetX
               XmNoffsetY
               XmNpixmap
               XmNwidth

     RETURN VALUE
          Upon successful completion, the DtDndDragStart() function
          returns the drag context widget created when the Motif drag
          is started; otherwise, it returns NULL if the drag could not
          be started.

     SEE ALSO
          DtDnd(5), DtDtsFileToDataType(3), DtDndCreateSourceIcon(3),
          DtDndDropRegister(3), DtDndVaDropRegister(3),
          DtDndDropUnregister(3), XmCreateDragIcon(3X),
          XmDragContext(3X), XmDragIcon(3X), XmDragStart(3X).