DtDndDragStart man page on IRIX

Man page or keyword search:  
man Server   31559 pages
apropos Keyword Search (all sections)
Output format
IRIX logo
[printable version]



     DtDndDragStart(3) UNIX System V (1 August 1995) 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.

     Page 1					      (printed 9/3/04)

     DtDndDragStart(3) UNIX System V (1 August 1995) DtDndDragStart(3)

	     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

     Page 2					      (printed 9/3/04)

     DtDndDragStart(3) UNIX System V (1 August 1995) DtDndDragStart(3)

	  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

     Page 3					      (printed 9/3/04)

     DtDndDragStart(3) UNIX System V (1 August 1995) DtDndDragStart(3)

	  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;

     Page 4					      (printed 9/3/04)

     DtDndDragStart(3) UNIX System V (1 August 1995) DtDndDragStart(3)

	  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

     Page 5					      (printed 9/3/04)

     DtDndDragStart(3) UNIX System V (1 August 1995) DtDndDragStart(3)

		   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

     Page 6					      (printed 9/3/04)

     DtDndDragStart(3) UNIX System V (1 August 1995) DtDndDragStart(3)

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

     Page 7					      (printed 9/3/04)

[top]

List of man pages available for IRIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net