Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
XmDragContext(3)	   Library Functions Manual	      XmDragContext(3)

NAME
       XmDragContext --	The DragContext	widget class

SYNOPSIS
       #include	<Xm/DragDrop.h>

DESCRIPTION
       DragContexts are	special	widgets	used in	drag and drop transactions.  A
       DragContext is implemented as a widget, but a client does  not  explic-
       itly  create  a	DragContext widget. Instead, a client initiates	a drag
       and drop	transaction by calling XmDragStart, and	this routine  initial-
       izes  and  returns  a DragContext widget. There is a unique DragContext
       for each	drag operation.	The toolkit frees a DragContext	when a	trans-
       action is complete; therefore, an application programmer	should not ex-
       plicitly	destroy	a DragContext.

       Initiator and receiver clients both use DragContexts to track the state
       of  a transaction. When the initiator and receiver of a transaction are
       in the same client, they	share the same DragContext instance.  If  they
       are  in different clients, there	are two	separate DragContexts. In this
       case, the initiator calls XmDragStart and the toolkit provides a	 Drag-
       Context	for  the  receiver client. The only resources pertinent	to the
       receiver	are XmNexportTargets and XmNnumExportTargets. These  can  both
       be passed as arguments to the XmDropSiteRetrieve	function to obtain in-
       formation about the current drop	site.

       In general, in order to receive data, a drop site must share  at	 least
       one  target  type and operation in common with a	drag source. The Drag-
       Context resource, XmNexportTargets, identifies  the  selection  targets
       for  the	drag source. These export targets are compared with the	XmNim-
       portTargets resource list specified by a	drop  site.   The  DragContext
       resource,  XmNdragOperations,  identifies the valid operations that can
       be applied to the source	data by	the initiator. The drop	site  counter-
       part  resource  is XmNdropSiteOperations, which indicates a drop	site's
       supported operations.

       A client	uses DragIcon widgets to define	the  drag-over	animation  ef-
       fects  associated with a	given drag and drop transaction.  An initiator
       specifies a set of drag icons, selects a	blending model,	and sets fore-
       ground and background cursor colors with	DragContext resources.

       The type	of drag-over visual used to represent a	drag operation depends
       on the drag protocol style. In preregister mode,	the server is grabbed,
       and  either  a cursor or	a pixmap may be	used as	a drag-over visual. In
       dynamic mode, drag-over visuals must be implemented with	the X  cursor.
       If  the resulting drag protocol style is	Drop Only or None and the XmN-
       dragInitiatorProtocolStyle is XmDRAG_DYNAMIC or	XmDRAG_PREFER_DYNAMIC,
       then  a dynamic visual style (cursor) is	used. Otherwise, a preregister
       visual style is used.

   Classes
       DragContext inherits behavior and resources from	Core.

       The class pointer is xmDragContextClass.

       The class name is XmDragContext.

   New Resources
       The following table defines a set of widget resources used by the  pro-
       grammer	to specify data. The programmer	can also set the resource val-
       ues for the inherited classes to	set attributes	for  this  widget.  To
       reference  a  resource by name or by class in a .Xdefaults file,	remove
       the XmN or XmC prefix and use the remaining letters. To specify one  of
       the  defined  values for	a resource in a	.Xdefaults file, remove	the Xm
       prefix and use the remaining letters (in	either lowercase or uppercase,
       but  include  any  underscores  between words). The codes in the	access
       column indicate if the given resource can be set	at creation time  (C),
       set by using XtSetValues	(S), retrieved by using	XtGetValues (G), or is
       not applicable (N/A).

       +-----------------------------------------------------------------------------------------------------------------------+
       |			    |		      XmDragContext Resource Set	  |			      |	       |
       |Name			    | Class		     | Type			  | Default		      |	Access |
       +----------------------------+------------------------+----------------------------+---------------------------+--------+
       |XmNblendModel		    | XmCBlendModel	     | unsigned	char		  | XmBLEND_ALL		      |	CG     |
       +----------------------------+------------------------+----------------------------+---------------------------+--------+
       |XmNclientData		    | XmCClientData	     | XtPointer		  | NULL		      |	CSG    |
       +----------------------------+------------------------+----------------------------+---------------------------+--------+
       |XmNconvertProc		    | XmCConvertProc	     | XtConvertSelectionIncrProc | NULL		      |	CSG    |
       +----------------------------+------------------------+----------------------------+---------------------------+--------+
       |XmNcursorBackground	    | XmCCursorBackground    | Pixel			  | dynamic		      |	CSG    |
       +----------------------------+------------------------+----------------------------+---------------------------+--------+
       |XmNcursorForeground	    | XmCCursorForeground    | Pixel			  | dynamic		      |	CSG    |
       +----------------------------+------------------------+----------------------------+---------------------------+--------+
       |XmNdragDropFinishCallback   | XmCCallback	     | XtCallbackList		  | NULL		      |	CSG    |
       +----------------------------+------------------------+----------------------------+---------------------------+--------+
       |XmNdragMotionCallback	    | XmCCallback	     | XtCallbackList		  | NULL		      |	C      |
       +----------------------------+------------------------+----------------------------+---------------------------+--------+
       |XmNdragOperations	    | XmCDragOperations	     | unsigned	char		  | XmDROP_COPY	| XmDROP_MOVE |	C      |
       +----------------------------+------------------------+----------------------------+---------------------------+--------+
       |XmNdropFinishCallback	    | XmCCallback	     | XtCallbackList		  | NULL		      |	C      |
       +----------------------------+------------------------+----------------------------+---------------------------+--------+
       |XmNdropSiteEnterCallback    | XmCCallback	     | XtCallbackList		  | NULL		      |	C      |
       +----------------------------+------------------------+----------------------------+---------------------------+--------+
       |XmNdropSiteLeaveCallback    | XmCCallback	     | XtCallbackList		  | NULL		      |	C      |
       +----------------------------+------------------------+----------------------------+---------------------------+--------+
       |XmNdropStartCallback	    | XmCCallback	     | XtCallbackList		  | NULL		      |	C      |
       +----------------------------+------------------------+----------------------------+---------------------------+--------+
       |XmNexportTargets	    | XmCExportTargets	     | Atom *			  | NULL		      |	CSG    |
       +----------------------------+------------------------+----------------------------+---------------------------+--------+
       |XmNincremental		    | XmCIncremental	     | Boolean			  | False		      |	CSG    |
       +----------------------------+------------------------+----------------------------+---------------------------+--------+
       |XmNinvalidCursorForeground  | XmCCursorForeground    | Pixel			  | dynamic		      |	CSG    |
       +----------------------------+------------------------+----------------------------+---------------------------+--------+
       |XmNnoneCursorForeground	    | XmCCursorForeground    | Pixel			  | dynamic		      |	CSG    |
       +----------------------------+------------------------+----------------------------+---------------------------+--------+
       |XmNnumExportTargets	    | XmCNumExportTargets    | Cardinal			  | 0			      |	CSG    |
       +----------------------------+------------------------+----------------------------+---------------------------+--------+
       |XmNoperationChangedCallback | XmCCallback	     | XtCallbackList		  | NULL		      |	C      |
       +----------------------------+------------------------+----------------------------+---------------------------+--------+
       |XmNoperationCursorIcon	    | XmCOperationCursorIcon | Widget			  | dynamic		      |	CSG    |
       +----------------------------+------------------------+----------------------------+---------------------------+--------+
       |XmNsourceCursorIcon	    | XmCSourceCursorIcon    | Widget			  | dynamic		      |	CSG    |
       +----------------------------+------------------------+----------------------------+---------------------------+--------+
       |XmNsourcePixmapIcon	    | XmCSourcePixmapIcon    | Widget			  | dynamic		      |	CSG    |
       +----------------------------+------------------------+----------------------------+---------------------------+--------+
       |XmNstateCursorIcon	    | XmCStateCursorIcon     | Widget			  | dynamic		      |	CSG    |
       +----------------------------+------------------------+----------------------------+---------------------------+--------+
       |XmNtopLevelEnterCallback    | XmCCallback	     | XtCallbackList		  | NULL		      |	C      |
       +----------------------------+------------------------+----------------------------+---------------------------+--------+
       |XmNtopLevelLeaveCallback    | XmCCallback	     | XtCallbackList		  | NULL		      |	C      |
       +----------------------------+------------------------+----------------------------+---------------------------+--------+
       |XmNvalidCursorForeground    | XmCCursorForeground    | Pixel			  | dynamic		      |	CSG    |
       +----------------------------+------------------------+----------------------------+---------------------------+--------+
       +----------------------------+------------------------+----------------------------+---------------------------+--------+
       XmNblendModel
		 Specifies which combination of	DragIcons are blended to  pro-
		 duce a	drag-over visual.

		 XmBLEND_ALL
			   Blends  all	three DragIcons: the source, state and
			   operation icons.  The icons are layered from	top to
			   bottom  with	 the  operation	 icon  on  top and the
			   source icon on the bottom.  The hotspot is  derived
			   from	the state icon.

		 XmBLEND_STATE_SOURCE
			   Blends the state and	source icons only. The hotspot
			   is derived from the state icon.

		 XmBLEND_JUST_SOURCE
			   Specifies that only the source icon is used,	 which
			   the initiator updates as required.

		 XmBLEND_NONE
			   Specifies  that  no	drag-over visual is generated.
			   The client tracks  the  drop	 site  status  through
			   callback routines and updates the drag-over visuals
			   as necessary.

       XmNclientData
		 Specifies the client data to be passed	to XmNconvertProc when
		 it is invoked.

       XmNconvertProc
		 If  XmNincremental  is	 True,	specifies  a procedure of type
		 XtConvertSelectionIncrProc that converts the source  data  to
		 the  format(s)	 requested by the receiver client.  The	widget
		 argument passed to this procedure is the DragContext  widget.
		 The  selection	atom passed is _MOTIF_DROP.  If	XmNincremental
		 is False, the procedure  is  an  XtConvertSelectionProc,  and
		 should	ignore the max_length, client_data, and	request_id ar-
		 guments and should handle the	conversion  atomically.	  Data
		 returned  by XmNconvertProc must be allocated using XtMalloc,
		 and will be freed automatically  by  the  toolkit  after  the
		 transfer.  For	additional information on selection conversion
		 procedures, see X Toolkit Intrinsics--C Language Interface.

       XmNcursorBackground
		 Specifies the background pixel	value of the cursor.

       XmNcursorForeground
		 Specifies the foreground pixel	value of the cursor  when  the
		 state	icon  is  not  blended.	 This resource defaults	to the
		 foreground color of the  widget  passed  to  the  XmDragStart
		 function.

       XmNdragDropFinishCallback
		 Specifies  the	 list  of  callbacks  that are called when the
		 transaction is	completed. The type of the structure whose ad-
		 dress is passed to this callback is XmDragDropFinishCallback-
		 Struct.   The	 reason	   sent	   by	 the	callback    is
		 XmCR_DRAG_DROP_FINISH.

       XmNdragMotionCallback
		 Specifies  the	 list  of  callbacks that are invoked when the
		 pointer moves.	 The type of structure whose address is	passed
		 to  this  callback  is	XmDragMotionCallbackStruct. The	reason
		 sent by the callback is XmCR_DRAG_MOTION.

       XmNdragOperations
		 Specifies the set of valid operations associated with an ini-
		 tiator	client for a drag transaction.	This resource is a bit
		 mask that is formed by	combining one or more of the following
		 values	 using	a  bitwise operation such as inclusive OR (|):
		 XmDROP_COPY, XmDROP_LINK, XmDROP_MOVE.	 The value XmDROP_NOOP
		 for  this  resource  indicates	 that no operations are	valid.
		 For Text and TextField	widgets, this resource is set  to  Xm-
		 DROP_COPY  |  XmDROP_MOVE; for	List widgets, it is set	to Xm-
		 DROP_COPY.

       XmNdropFinishCallback
		 Specifies the list of callbacks that  are  invoked  when  the
		 drop is completed. The	type of	the structure whose address is
		 passed	to this	callback  is  XmDropFinishCallbackStruct.  The
		 reason	sent by	the callback is	XmCR_DROP_FINISH.

       XmNdropSiteEnterCallback
		 Specifies  the	 list  of  callbacks that are invoked when the
		 pointer enters	a drop site. The type of the  structure	 whose
		 address  is  passed  to this callback is XmDropSiteEnterCall-
		 backStruct.   The   reason   sent   by	  the	callback    is
		 XmCR_DROP_SITE_ENTER.

       XmNdropSiteLeaveCallback
		 Specifies  the	 list  of  callbacks that are invoked when the
		 pointer leaves	a drop site. The type of the  structure	 whose
		 address  is  passed  to this callback is XmDropSiteLeaveCall-
		 backStruct.   The   reason   sent   by	  the	callback    is
		 XmCR_DROP_SITE_LEAVE.

       XmNdropStartCallback
		 Specifies  the	list of	callbacks that are invoked when	a drop
		 is initiated. The type	of  the	 structure  whose  address  is
		 passed	 to  this  callback  is	XmDropStartCallbackStruct. The
		 reason	sent by	the callback is	XmCR_DROP_START.

       XmNexportTargets
		 Specifies the list  of	 target	 atoms	associated  with  this
		 source.   This	resource identifies the	selection targets this
		 source	can be converted to.

       XmNincremental
		 Specifies a Boolean value that	indicates whether the transfer
		 on  the  initiator  side  uses	 the  Xt incremental selection
		 transfer mechanism described in X Toolkit Intrinsics--C  Lan-
		 guage	Interface.   If	 the value is True, the	initiator uses
		 incremental transfer; if the value is	False,	the  initiator
		 uses atomic transfer.

       XmNinvalidCursorForeground
		 Specifies  the	 foreground pixel value	of the cursor when the
		 state is invalid. This	resource defaults to the value of  the
		 XmNcursorForeground resource.

       XmNnoneCursorForeground
		 Specifies  the	 foreground pixel value	of the cursor when the
		 state is none.	This resource defaults to the value of the Xm-
		 NcursorForeground resource.

       XmNnumExportTargets
		 Specifies  the	 number	 of entries in the list	of export tar-
		 gets.

       XmNoperationChangedCallback
		 Specifies the list of callbacks that  are  invoked  when  the
		 drag  is  started and when the	user requests that a different
		 operation be applied to the drop.  The	type of	the  structure
		 whose	 address  is  passed  to  this	callback  is  XmOpera-
		 tionChangedCallbackStruct. The	reason sent by the callback is
		 XmCR_OPERATION_CHANGED.

       XmNoperationCursorIcon
		 Specifies the cursor icon used	to designate the type of oper-
		 ation performed by the	drag transaction.  If  NULL,  XmScreen
		 resources  provide default icons for copy, link, and move op-
		 erations.

       XmNsourceCursorIcon
		 Specifies the cursor icon used	to represent the source	when a
		 dynamic  visual style is used.	If NULL, the XmNdefaultSource-
		 CursorIcon resource of	XmScreen  provides  a  default	cursor
		 icon.

       XmNsourcePixmapIcon
		 Specifies the pixmap icon used	to represent the source	when a
		 preregister visual style is used. The icon is	used  in  con-
		 junction  with	 the  colormap	of  the	 widget	 passed	to Xm-
		 DragStart.  If	NULL, XmNsourceCursorIcon is used.

       XmNstateCursorIcon
		 Specifies the cursor icon used	to designate the  state	 of  a
		 drop site.  If	NULL, XmScreen resources provide default icons
		 for a valid, invalid, and no drop site	condition.

       XmNtopLevelEnterCallback
		 Specifies the list of callbacks  that	are  called  when  the
		 pointer  enters  a  top-level	window	or root	window (due to
		 changing screens). The	type of	the structure whose address is
		 passed	to this	callback is XmTopLevelEnterCallbackStruct. The
		 reason	sent by	the callback is	XmCR_TOP_LEVEL_ENTER.

       XmNtopLevelLeaveCallback
		 Specifies the list of callbacks  that	are  called  when  the
		 pointer  leaves a top level window or the root	window (due to
		 changing screens). The	type of	the structure whose address is
		 passed	to this	callback is XmTopLevelLeaveCallbackStruct. The
		 reason	sent by	the callback is	XmCR_TOP_LEVEL_LEAVE.

       XmNvalidCursorForeground
		 Specifies the foreground pixel	value of the cursor designated
		 as a valid cursor icon.

   Inherited Resources
       DragContext  inherits  behavior	and  resources from the	superclass de-
       scribed in the following	table.	For a complete description of each re-
       source, refer to	the Core reference page.

       +---------------------------------------------------------------------------------------------------------------+
       |			      |		      Core Resource SetName			      |	Class			      |	Type	       | Default	      |	Access |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNaccelerators		      |	XmCAccelerators		      |	XtAccelerators | dynamic	      |	CSG    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNancestorSensitive	      |	XmCSensitive		      |	Boolean	       | dynamic	      |	G      |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNbackground		      |	XmCBackground		      |	Pixel	       | dynamic	      |	CSG    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNbackgroundPixmap	      |	XmCPixmap		      |	Pixmap	       | XmUNSPECIFIED_PIXMAP |	CSG    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNborderColor		      |	XmCBorderColor		      |	Pixel	       | XtDefaultForeground  |	CSG    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNborderPixmap		      |	XmCPixmap		      |	Pixmap	       | XmUNSPECIFIED_PIXMAP |	CSG    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNborderWidth		      |	XmCBorderWidth		      |	Dimension      | 0		      |	CSG    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNcolormap		      |	XmCColormap		      |	Colormap       | dynamic	      |	CG     |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNdepth		      |	XmCDepth		      |	int	       | dynamic	      |	CG     |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNdestroyCallback	      |	XmCCallback		      |	XtCallbackList | NULL		      |	C      |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNheight		      |	XmCHeight		      |	Dimension      | dynamic	      |	CSG    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNinitialResourcesPersistent |	XmCInitialResourcesPersistent |	Boolean	       | True		      |	C      |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNmappedWhenManaged	      |	XmCMappedWhenManaged	      |	Boolean	       | True		      |	CSG    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNscreen		      |	XmCScreen		      |	Screen *       | dynamic	      |	CG     |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNsensitive		      |	XmCSensitive		      |	Boolean	       | True		      |	CSG    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNtranslations		      |	XmCTranslations		      |	XtTranslations | dynamic	      |	CSG    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNwidth		      |	XmCWidth		      |	Dimension      | dynamic	      |	CSG    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNx			      |	XmCPosition		      |	Position       | 0		      |	CSG    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       |XmNy			      |	XmCPosition		      |	Position       | 0		      |	CSG    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       +------------------------------+-------------------------------+----------------+----------------------+--------+
   Callback Information
       Each of the DragContext callbacks has an	associated callback structure.

       A  pointer  to the following structure is passed	to the XmNdragDropFin-
       ishCallback callback:

       typedef struct
       {
	       int reason;
	       XEvent  *event;
	       Time timeStamp;
       }XmDragDropFinishCallbackStruct,	*XmDragDropFinishCallback;

       reason	 Indicates why the callback was	invoked

       event	 Points	to the XEvent that triggered the callback

       timeStamp Specifies the time at which either the	drag or	the  drop  was
		 completed

       A  pointer  to  the following structure is passed to callbacks for XmN-
       dragMotionCallback:

       typedef struct
       {
	       int reason;
	       XEvent *event;
	       Time timeStamp;
	       unsigned	char operation;
	       unsigned	char operations;
	       unsigned	char dropSiteStatus;
	       Position	x;
	       Position	y;
       }XmDragMotionCallbackStruct, *XmDragMotionCallback;

       reason	 Indicates why the callback was	invoked.

       event	 Points	to the XEvent that triggered the callback.

       timeStamp Specifies the timestamp of the	logical	event.

       operation Identifies an operation.

		 If the	toolkit	has just called	a DropSite's XmNdragProc,  the
		 toolkit  initializes  operation to the	value of the operation
		 member	of the XmDragProcCallbackStruct	at the time the	 Drop-
		 Site's	XmNdragProc returns.

		 If  the toolkit has not called	an XmNdragProc and the pointer
		 is within an active drop site,	the toolkit initializes	opera-
		 tion  by  selecting  an operation from	the bitwise AND	of the
		 initial value of the operations member	and the	value  of  the
		 DropSite's   XmNdropSiteOperations   resource.	  The  toolkit
		 searches  this	 set  first  for  XmDROP_MOVE,	then  for  Xm-
		 DROP_COPY, then for XmDROP_LINK, and initializes operation to
		 the first operation it	finds in  the  set.   If  the  toolkit
		 finds none of these operations	in the set, it initializes op-
		 eration to XmDROP_NOOP.

		 If the	toolkit	has not	called an XmNdragProc and the  pointer
		 is  not  within  an active drop site, the toolkit initializes
		 operation by selecting	an operation from the initial value of
		 the  operations  member.  The toolkit searches	this set first
		 for XmDROP_MOVE, then for XmDROP_COPY,	then for  XmDROP_LINK,
		 and  initializes operation to the first operation it finds in
		 the set.  If the toolkit finds	none of	 these	operations  in
		 the set, it initializes operation to XmDROP_NOOP.

       operations
		 Indicates  the	 set  of  operations  supported	for the	source
		 data.

		 If the	toolkit	has just called	a DropSite's XmNdragProc,  the
		 toolkit  initializes  operations  to  the  bitwise AND	of the
		 DropSite's XmNdropOperations and the value of the  operations
		 member	 of the	XmDragProcCallbackStruct at the	time the Drop-
		 Site's	XmNdragProc returns.  If the resulting set  of	opera-
		 tions	is  empty,  the	 toolkit initializes operations	to Xm-
		 DROP_NOOP.

		 If the	toolkit	has not	called an  XmNdragProc	and  the  user
		 does  not  select  an operation (by pressing a	modifier key),
		 the toolkit initializes operations to the value of the	 Drag-
		 Context's XmNdragOperations resource.

		 If  the  toolkit  has	not called an XmNdragProc and the user
		 does select an	operation, the toolkit initializes  operations
		 to  the  bitwise  AND	of the corresponding operation and the
		 value of the DragContext's  XmNdragOperations	resource.   If
		 the  resulting	 set  of operations is empty, the toolkit ini-
		 tializes operations to	XmDROP_NOOP.

       dropSiteStatus
		 Indicates whether or not a drop site is valid.

		 If the	toolkit	has just called	a DropSite's XmNdragProc,  the
		 toolkit  initializes dropSiteStatus to	the value of the drop-
		 SiteStatus member of the XmDragProcCallbackStruct at the time
		 the DropSite's	XmNdragProc returns.

		 If  the toolkit has not called	an XmNdragProc,	it initializes
		 dropSiteStatus	as follows: the	toolkit	initializes dropSiteS-
		 tatus	to  XmNO_DROP_SITE  if the pointer is over an inactive
		 drop site or is not over a drop site.	The  toolkit  initial-
		 izes dropSiteStatus to	XmDROP_SITE_VALID if all the following
		 conditions are	met:

		    o  The pointer is over an active drop site.

		    o  The DragContext's XmNexportTargets and  the  DropSite's
		       XmNimportTargets	are compatible.

		    o  The  initial  value  of the operation member is not Xm-
		       DROP_NOOP.

		 Otherwise, the	 toolkit  initializes  dropSiteStatus  to  Xm-
		 DROP_SITE_INVALID.

       A  pointer  to the following structure is passed	for the	XmNdropFinish-
       Callback	callback:

       typedef struct
       {
	       int reason;
	       XEvent *event;
	       Time timeStamp;
	       unsigned	char operation;
	       unsigned	char operations;
	       unsigned	char dropSiteStatus;
	       unsigned	char dropAction;
	       unsigned	char completionStatus;
       }XmDropFinishCallbackStruct, *XmDropFinishCallback;

       reason	 Indicates why the callback was	invoked.

       event	 Points	to the XEvent that triggered the callback.

       timeStamp Specifies the time at which the drop was completed.

       operation Identifies an operation.

		 If the	pointer	is over	an active drop site when the drop  be-
		 gins,	the  toolkit initializes operation to the value	of the
		 operation member of the XmDropProcCallbackStruct at the  time
		 the DropSite's	XmNdropProc returns.

		 If  the pointer is not	over an	active drop site when the drop
		 begins, the toolkit initializes operation by selecting	an op-
		 eration from the initial value	of the operations member.  The
		 toolkit searches this set first for XmDROP_MOVE, then for Xm-
		 DROP_COPY, then for XmDROP_LINK, and initializes operation to
		 the first operation it	finds in the set.  If it finds none of
		 these	operations in the set, it initializes operation	to Xm-
		 DROP_NOOP.

       operations
		 Indicates the set of  operations  supported  for  the	source
		 data.

		 If  the pointer is over an active drop	site when the drop be-
		 gins, the toolkit initializes operations to the  bitwise  AND
		 of  the DropSite's XmNdropOperations and the value of the op-
		 erations member of the	XmDropProcCallbackStruct at  the  time
		 the  DropSite's XmNdropProc returns.  If the resulting	set of
		 operations is empty, the toolkit  initializes	operations  to
		 XmDROP_NOOP.

		 If  the pointer is not	over an	active drop site when the drop
		 begins	and if the user	 does  not  select  an	operation  (by
		 pressing  a modifier key), the	toolkit	initializes operations
		 to the	value of the DragContext's XmNdragOperations resource.

		 If the	pointer	is not over an active drop site	when the  drop
		 begins	 and if	the user does select an	operation, the toolkit
		 initializes operations	to the bitwise AND of the  correspond-
		 ing operation and the value of	the DragContext's XmNdragOper-
		 ations	resource.  If  the  resulting  set  of	operations  is
		 empty,	the toolkit initializes	operations to XmDROP_NOOP.

       dropSiteStatus
		 Indicates whether or not a drop site is valid.

		 If  the pointer is over an active drop	site when the drop be-
		 gins, the toolkit initializes dropSiteStatus to the value  of
		 the  dropSiteStatus member of the XmDropProcCallbackStruct at
		 the time the DropSite's XmNdropProc returns.

		 If the	pointer	is not over an active drop site	when the  drop
		 begins,    the	   toolkit   initializes   dropSiteStatus   to
		 XmNO_DROP_SITE.

       dropAction
		 Identifies the	 drop  action.	The  values  are  XmDROP,  Xm-
		 DROP_CANCEL,  XmDROP_HELP,  and  XmDROP_INTERRUPT.   The  Xm-
		 DROP_INTERRUPT	value is currently unsupported;	if  specified,
		 it will be interpreted	as an XmDROP_CANCEL.

       completionStatus
		 An  IN/OUT  member  that indicates the	status of the drop ac-
		 tion.	After the last callback	procedure  has	returned,  the
		 final	value of this member determines	what visual transition
		 effects will be applied.  There are two values:

		 XmDROP_SUCCESS
			   The drop was	successful.

		 XmDROP_FAILURE
			   The drop was	unsuccessful.

       A pointer to the	following structure is passed to  callbacks  for  XmN-
       dropSiteEnterCallback:

       typedef struct
       {
	       int reason;
	       XEvent *event;
	       Time timeStamp;
	       unsigned	char operation;
	       unsigned	char operations;
	       unsigned	char dropSiteStatus;
	       Position	x;
	       Position	y;
       }XmDropSiteEnterCallbackStruct, *XmDropSiteEnterCallback;

       reason	 Indicates why the callback was	invoked.

       event	 Points	to the XEvent that triggered the callback.

       timeStamp Specifies the time the	crossing event occurred.

       operation Identifies an operation.

		 If  the toolkit has just called a DropSite's XmNdragProc, the
		 toolkit initializes operation to the value of	the  operation
		 member	 of the	XmDragProcCallbackStruct at the	time the Drop-
		 Site's	XmNdragProc returns.

		 If the	toolkit	has not	called an XmNdragProc, it  initializes
		 operation  by	selecting an operation from the	bitwise	AND of
		 the initial value of the operations member and	the  value  of
		 the  DropSite's  XmNdropSiteOperations	resource.  The toolkit
		 searches  this	 set  first  for  XmDROP_MOVE,	then  for  Xm-
		 DROP_COPY, then for XmDROP_LINK, and initializes operation to
		 the first operation it	finds in  the  set.   If  the  toolkit
		 finds none of these operations	in the set, it initializes op-
		 eration to XmDROP_NOOP.

       operations
		 Indicates the set of  operations  supported  for  the	source
		 data.

		 If  the toolkit has just called a DropSite's XmNdragProc, the
		 toolkit initializes operations	to  the	 bitwise  AND  of  the
		 DropSite's  XmNdropOperations and the value of	the operations
		 member	of the XmDragProcCallbackStruct	at the time the	 Drop-
		 Site's	 XmNdragProc  returns.	If the resulting set of	opera-
		 tions is empty, the toolkit  initializes  operations  to  Xm-
		 DROP_NOOP.

		 If  the  toolkit  has	not called an XmNdragProc and the user
		 does not select an operation (by pressing  a  modifier	 key),
		 the  toolkit initializes operations to	the value of the Drag-
		 Context's XmNdragOperations resource.

		 If the	toolkit	has not	called an  XmNdragProc	and  the  user
		 does  select an operation, the	toolkit	initializes operations
		 to the	bitwise	AND of the  corresponding  operation  and  the
		 value	of  the	 DragContext's XmNdragOperations resource.  If
		 the resulting set of operations is empty,  the	 toolkit  ini-
		 tializes operations to	XmDROP_NOOP.

       dropSiteStatus
		 Indicates whether or not a drop site is valid.

		 If  the toolkit has just called a DropSite's XmNdragProc, the
		 toolkit initializes dropSiteStatus to the value of the	 drop-
		 SiteStatus member of the XmDragProcCallbackStruct at the time
		 the DropSite's	XmNdragProc returns.

		 If the	toolkit	has not	 called	 XmNdragProc,  it  initializes
		 dropSiteStatus	to XmDROP_SITE_VALID if	the DragContext's XmN-
		 exportTargets and the DropSite's XmNimportTargets are compat-
		 ible  and if the initial value	of the operation member	is not
		 XmDROP_NOOP.  Otherwise, the toolkit initializes dropSiteSta-
		 tus to	XmDROP_SITE_INVALID.

       x	 Indicates  the	x-coordinate of	the pointer in root window co-
		 ordinates.

       y	 Indicates the y-coordinate of the pointer in root window  co-
		 ordinates.

       A  pointer  to  the following structure is passed to callbacks for XmN-
       dropSiteLeaveCallback:

       typedef struct
       {
	       int reason;
	       XEvent *event;
	       Time timeStamp;
       }XmDropSiteLeaveCallbackStruct, *XmDropSiteLeaveCallback;

       reason	 Indicates why the callback was	invoked

       event	 Points	to the XEvent that triggered the callback

       timeStamp Specifies the timestamp of the	logical	event

       A pointer to the	following structure is passed  for  the	 XmNdropStart-
       Callback	callback:

       typedef struct
       {
	       int reason;
	       XEvent *event;
	       Time timeStamp;
	       unsigned	char operation;
	       unsigned	char operations;
	       unsigned	char dropSiteStatus;
	       unsigned	char dropAction;
	       Position	x;
	       Position	y;
       }XmDropStartCallbackStruct, *XmDropStartCallback;

       reason	 Indicates why the callback was	invoked.

       event	 Points	to the XEvent that triggered the callback.

       timeStamp Specifies the time at which the drag was completed.

       operation Identifies an operation.

		 If  the pointer is over an active drop	site when the drop be-
		 gins, the toolkit initializes operation to the	value  of  the
		 operation  member of the XmDropProcCallbackStruct at the time
		 the DropSite's	XmNdropProc returns.

		 If the	pointer	is not over an active drop site	when the  drop
		 begins, the toolkit initializes operation by selecting	an op-
		 eration from the initial value	of the operations member.  The
		 toolkit searches this set first for XmDROP_MOVE, then for Xm-
		 DROP_COPY, then for XmDROP_LINK, and initializes operation to
		 the first operation it	finds in the set.  If it finds none of
		 these operations in the set, it initializes operation to  Xm-
		 DROP_NOOP.

       operations
		 Indicates  the	 set  of  operations  supported	for the	source
		 data.

		 If the	pointer	is over	an active drop site when the drop  be-
		 gins,	the  toolkit initializes operations to the bitwise AND
		 of the	DropSite's XmNdropOperations and the value of the  op-
		 erations  member  of the XmDropProcCallbackStruct at the time
		 the DropSite's	XmNdropProc returns.  If the resulting set  of
		 operations  is	 empty,	 the toolkit initializes operations to
		 XmDROP_NOOP.

		 If the	pointer	is not over an active drop site	when the  drop
		 begins	 and  if  the  user  does  not select an operation (by
		 pressing a modifier key), the toolkit initializes  operations
		 to the	value of the DragContext's XmNdragOperations resource.

		 If  the pointer is not	over an	active drop site when the drop
		 begins	and if the user	does select an operation, the  toolkit
		 initializes  operations to the	bitwise	AND of the correspond-
		 ing operation and the value of	the DragContext's XmNdragOper-
		 ations	 resource.   If	 the  resulting	 set  of operations is
		 empty,	the toolkit initializes	operations to XmDROP_NOOP.

       dropSiteStatus
		 Indicates whether or not a drop site is valid.

		 If the	pointer	is over	an active drop site when the drop  be-
		 gins,	the toolkit initializes	dropSiteStatus to the value of
		 the dropSiteStatus member of the XmDropProcCallbackStruct  at
		 the time the DropSite's XmNdropProc returns.

		 If  the pointer is not	over an	active drop site when the drop
		 begins,   the	 toolkit   initializes	  dropSiteStatus    to
		 XmNO_DROP_SITE.

		 This  field  is invalid if the	dropAction field is set	to Xm-
		 DROP_CANCEL.

       dropAction
		 An IN/OUT member that identifies the drop action.  The	values
		 are XmDROP, XmDROP_CANCEL, XmDROP_HELP, and XmDROP_INTERRUPT.
		 The value of dropAction can be	modified to change the	action
		 actually  initiated.  The value XmDROP_INTERRUPT is currently
		 unsupported; if specified, it will be interpreted as  an  Xm-
		 DROP_CANCEL.

       x	 Indicates  the	x-coordinate of	the pointer in root window co-
		 ordinates.

       y	 Indicates the y-coordinate of the pointer in root window  co-
		 ordinates.

       A  pointer  to  the  following  structure  is  passed  to the XmNopera-
       tionChangedCallback callback:

       typedef struct
       {
	       int reason;
	       XEvent  *event;
	       Time timeStamp;
	       unsigned	char operation;
	       unsigned	char operations;
	       unsigned	char dropSiteStatus;
       }XmOperationChangedCallbackStruct, *XmOperationChangedCallback;

       reason	 Indicates why the callback was	invoked.

       event	 Points	to the XEvent that triggered the callback.

       timeStamp Specifies the time at which the crossing event	occurred.

       operation Identifies an operation.

		 If the	toolkit	has just called	a DropSite's XmNdragProc,  the
		 toolkit  initializes  operation to the	value of the operation
		 member	of the XmDragProcCallbackStruct	at the time the	 Drop-
		 Site's	XmNdragProc returns.

		 If the	toolkit	has not	called an XmNdragProc, and the pointer
		 is within an active drop site,	the toolkit initializes	opera-
		 tion  by  selecting  an operation from	the bitwise AND	of the
		 initial value of the operations member	and the	value  of  the
		 DropSite's   XmNdropSiteOperations   resource.	  The  toolkit
		 searches  this	 set  first  for  XmDROP_MOVE,	then  for  Xm-
		 DROP_COPY, then for XmDROP_LINK, and initializes operation to
		 the first operation it	finds in  the  set.   If  the  toolkit
		 finds none of these operations	in the set, it initializes op-
		 eration to XmDROP_NOOP.

		 If the	toolkit	has not	called an XmNdragProc, and the pointer
		 is  not  within  an active drop site, the toolkit initializes
		 operation by selecting	an operation from the initial value of
		 the  operations  member.  The toolkit searches	this set first
		 for XmDROP_MOVE, then for XmDROP_COPY,	then for  XmDROP_LINK,
		 and  initializes operation to the first operation it finds in
		 the set.  If the toolkit finds	none of	 these	operations  in
		 the set, it initializes operation to XmDROP_NOOP.

       operations
		 Indicates  the	 set  of  operations  supported	for the	source
		 data.

		 If the	toolkit	has just called	a DropSite's XmNdragProc,  the
		 toolkit  initializes  operations  to  the  bitwise AND	of the
		 DropSite's XmNdropOperations and the value of the  operations
		 member	 of the	XmDragProcCallbackStruct at the	time the Drop-
		 Site's	XmNdragProc returns.  If the resulting set  of	opera-
		 tions	is  empty,  the	 toolkit initializes operations	to Xm-
		 DROP_NOOP.

		 If the	toolkit	has not	called an XmNdragProc,	and  the  user
		 does  not  select  an operation (by pressing a	modifier key),
		 the toolkit initializes operations to the value of the	 Drag-
		 Context's XmNdragOperations resource.

		 If  the  toolkit  has not called an XmNdragProc, and the user
		 does select an	operation, the toolkit initializes  operations
		 to  the  bitwise  AND	of the corresponding operation and the
		 value of the DragContext's  XmNdragOperations	resource.   If
		 the  resulting	 set  of operations is empty, the toolkit ini-
		 tializes operations to	XmDROP_NOOP.

       dropSiteStatus
		 Indicates whether or not a drop site is valid.

		 If the	toolkit	has just called	a DropSite's XmNdragProc,  the
		 toolkit  initializes dropSiteStatus to	the value of the drop-
		 SiteStatus member of the XmDragProcCallbackStruct at the time
		 the DropSite's	XmNdragProc returns.

		 If  the  toolkit has not called an XmNdragProc	it initializes
		 dropSiteStatus	to XmNO_DROP_SITE if the pointer  is  over  an
		 inactive  drop	 site or is not	over a drop site.  The toolkit
		 initializes dropSiteStatus to XmDROP_SITE_VALID  if  all  the
		 following conditions are met:

		    o  The pointer is over an active drop site

		    o  The  DragContext's  XmNexportTargets and	the DropSite's
		       XmNimportTargets	are compatible

		    o  The initial value of the	operation member  is  not  Xm-
		       DROP_NOOP

		 Otherwise,  the  toolkit  initializes	dropSiteStatus	to Xm-
		 DROP_SITE_INVALID.

       A pointer to the	following structure is passed to callbacks for	XmNto-
       pLevelEnterCallback:

       typedef struct
       {
	       int reason;
	       XEvent *event;
	       Time timeStamp;
	       Screen screen;
	       Window window;
	       Position	x;
	       Position	y;
	       unsigned	char dragProtocolStyle;
       }XmTopLevelEnterCallbackStruct, *XmTopLevelEnterCallback;

       reason	 Indicates why the callback was	invoked.

       event	 Points	to the XEvent that triggered the callback.

       timeStamp Specifies the timestamp of the	logical	event.

       screen	 Specifies  the	screen associated with the top-level window or
		 root window being entered.

       window	 Specifies the ID of the top-level window or root window being
		 entered.

       x	 Indicates  the	x-coordinate of	the pointer in root window co-
		 ordinates.

       y	 Indicates the y-coordinate of the pointer in root window  co-
		 ordinates.

       dragProtocolStyle
		 Specifies  the	 protocol  style adopted by the	initiator. The
		 values	are XmDRAG_DROP_ONLY, XmDRAG_DYNAMIC, XmDRAG_NONE, and
		 XmDRAG_PREREGISTER.

       A  pointer to the following structure is	passed to callbacks for	XmNto-
       pLevelLeaveCallback:

       typedef struct
       {
	       int reason;
	       XEvent  *event;
	       Time timeStamp;
	       Screen screen;
	       Window window;
       }XmTopLevelLeaveCallbackStruct, *XmTopLevelLeaveCallback;

       reason	 Indicates why the callback was	invoked

       event	 Points	to the XEvent that triggered the callback

       timeStamp Specifies the timestamp of the	logical	event

       screen	 Specifies a screen associated with the	 top-level  window  or
		 root window being left

       window	 Specifies the ID of the top-level window or root window being
		 left

   Translations
       The XmDragContext translations are described  in	 the  following	 list.
       The following key names are listed in the X standard key	event transla-
       tion table syntax.  This	format is the one used by Motif	to specify the
       widget  actions	corresponding to a given key.  A brief overview	of the
       format is provided under	VirtualBindings(3).  For a  complete  descrip-
       tion  of	the format, please refer to the	X Toolkit Instrinsics Documen-
       tation.

       Button1<Enter>:
		 DragMotion()

       Button1<Leave>:
		 DragMotion()

       Button1<Motion>:
		 DragMotion()

       Button2<Enter>:
		 DragMotion()

       Button2<Leave>:
		 DragMotion()

       Button2<Motion>:
		 DragMotion()

       <Btn2Up>: FinishDrag()

       <Btn1Up>: FinishDrag()

       <Key>Return:
		 FinishDrag()

       <Key><osfActivate>:
		 FinishDrag()

       <BtnDown>:
		 IgnoreButtons()

       <BtnUp>:	 IgnoreButtons()

       :<Key><osfCancel>:
		 CancelDrag()

       :<Key><osfHelp>:
		 HelpDrag()

       :<Key><osfUp>:
		 DragKey(Up)

       :<Key><osfDown>:
		 DragKey(Down)

       :<Key><osfLeft>:
		 DragKey(Left)

       :<Key><osfRight>:
		 DragKey(Right)

       :<KeyUp>: DragKey(Update)

       :<KeyDown>:
		 DragKey(Update)

   Action Routines
       The XmDragContext action	routines are

       CancelDrag():
		 Cancels the drag operation and	frees the associated  DragCon-
		 text.

       DragKey(String)
		 If  the value of String is Left, Right, Up, or	Down, this ac-
		 tion moves the	dragged	object in the corresponding  location.
		 Any other values of String are	ignored.

       DragMotion():
		 Drags the selected data as the	pointer	is moved.

       FinishDrag():
		 Finishes the drag operation and starts	the drop operation.

       HelpDrag():
		 Initiates  a  conditional  drop  that enables the receiver to
		 provide help information to the user. The user	can cancel  or
		 continue the drop operation in	response to this information.

   Virtual Bindings
       The  bindings  for  virtual  keys are vendor specific.  For information
       about bindings for virtual buttons and keys, see	VirtualBindings(3).

RELATED	INFORMATION
       Core(3),	XmDisplay(3), XmDragCancel(3), XmDragIcon(3),  XmDragStart(3),
       XmDropSite(3), XmDropTransfer(3), and XmScreen(3).

							      XmDragContext(3)

NAME | SYNOPSIS | DESCRIPTION | RELATED INFORMATION

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=XmDragContext&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help