DtDndVaDragStart man page on HP-UX

Printed from http://www.polarhome.com/service/man/?qf=DtDndVaDragStart&af=0&tf=2&of=HP-UX

DtDndDragStart(library call)			  DtDndDragStart(library call)

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	inter‐
       prets 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 trans‐
       fer.  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  sup‐
       ports.  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 com‐
       bination of operations is specified by the bitwise inclusive OR of sev‐
       eral operation values.  For example, to support the move and copy oper‐
       ations, 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 convert‐
       Callback are the Motif Drag Context, an XtPointer  to  application-sup‐
       plied  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  convertCall‐
       back  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 dragFinishCall‐
       back are the Motif Drag Context, an XtPointer  to  application-supplied
       client data, and an XtPointer to a DtDndDragFinishCallbackStruct struc‐
       ture.

   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  DtDndCreateSour‐
		 ceIcon(3)  or	XmCreateDragIcon(3). 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_TRANS‐
		 FER 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_CON‐
       VERT_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 rea‐
       son of DtCR_DND_CONVERT_DELETE. The application should delete its  ver‐
       sion 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(3) 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 possi‐
       ble reasons for this callback are:

       DtCR_DND_CONVERT_DATA
		 The callback provides the requested data by setting appropri‐
		 ate 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 appli‐
       cation  can set this to DtDND_FAILURE to cancel the conversion and con‐
       sequently the drag and drop operation.  The value of status is normally
       DtDND_SUCCESS.

       A  pointer  to the following structure is passed to the dragFinishCall‐
       back:

       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  applica‐
       tion  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  convert‐
       Callback	 and dragFinishCallback to communicate data between the appli‐
       cation and the drag and drop subsystem.	The DtDndContext structure  is
       passed  to these callbacks as dragData in the callback structure appro‐
       priate 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 DtDndCon‐
       text 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  contain‐
       ing 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 pos‐
       sible.

       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(3), 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 DtDnd‐
       VaDragStart 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	DtDnd‐
       VaDragStart 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
       Dt/Dnd.h	 - DtDnd(5), DtDtsFileToDataType(3), DtDndCreateSourceIcon(3),
       DtDndDropRegister(3),   DtDndDropRegister(3),   DtDndDropUnregister(3),
       XmCreateDragIcon(3), XmDragContext(3), XmDragIcon(3), XmDragStart(3).

						  DtDndDragStart(library call)
[top]

List of man pages available for HP-UX

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