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

FreeBSD Manual Pages

  
 
  

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

NAME
       XmDropSite -- The DropSite Registry

SYNOPSIS
       #include	<Xm/DragDrop.h>

DESCRIPTION
       A  client registers a widget or gadget as a drop	site using the XmDrop-
       SiteRegister function. In addition, this	routine	defines	 the  behavior
       and  capabilities  of  a	drop site by specifying	appropriate resources.
       For example, the	 XmNimportTargets  and	XmNnumImportTargets  resources
       identify	 respectively  the  selection target types and number of types
       supported by a drop site. The visual animation effects associated  with
       a drop site are also described with DropSite resources.

       Drop  site  animation effects that occur	in response to the pointer en-
       tering a	valid drop site	are called drag-under effects. A receiver  can
       select  from  several  animation	 styles	supplied by the	toolkit	or can
       provide customized animation effects. Drag-under	 effects  supplied  by
       the  toolkit  include  border  highlighting, shadow in/out drawing, and
       pixmap representation.

       When a preregister drag protocol	style is used, the  toolkit  generates
       drag-under  visual  effects based on the	value of the XmNanimationStyle
       resource. In dynamic mode, if the drop  site  XmNdragProc  resource  is
       NULL,  the toolkit also provides	animation effects based	on the XmNani-
       mationStyle resource. Otherwise,	if the XmNdragProc routine  is	speci-
       fied,  the  receiver can	either assume responsibility for animation ef-
       fects (through the XmNdragProc routine) or rely on the toolkit to  pro-
       vide  animation.	  An  application can either handle all	or none	of the
       animation effects for a particular drop site.  That is, an  application
       should never do a partial job of	animation on a particular drop site.

       Drop  sites  may	overlap. The initial stacking order corresponds	to the
       order in	which the drop sites were registered. When a drop  site	 over-
       laps  another drop site,	the drag-under effects of the drop site	under-
       neath are clipped by the	obscuring drop site(s).

       The XmDropSiteUpdate routine sets resources for a widget	that is	regis-
       tered as	a drop site. XmDropSiteRetrieve	gets drop site resource	values
       previously specified for	a registered widget. These routines  are  used
       instead of XtSetValues and XtGetValues.

   Classes
       XmDropSite does not inherit from	any widget class.

   New Resources
       The  following table defines a set of widget resources used by the pro-
       grammer to specify data.	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 .Xde-
       faults file, remove the Xm prefix and use the remaining letters (in ei-
       ther 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 XmDropSiteUpdate (S), re-
       trieved by using	XmDropSiteRetrieve (G),	or is not applicable (N/A).

       +--------------------------------------------------------------------------------------------------------+
       |			|		XmDropSite|Resource Set	   |			       |	|
       |Name			| Class			  | Type	   | Default		       | Access	|
       +------------------------+-------------------------+----------------+---------------------------+--------+
       |XmNanimationMask	| XmCAnimationMask	  | Pixmap	   | XmUNSPECIFIED_PIXMAP      | CSG	|
       +------------------------+-------------------------+----------------+---------------------------+--------+
       |XmNanimationPixmap	| XmCAnimationPixmap	  | Pixmap	   | XmUNSPECIFIED_PIXMAP      | CSG	|
       +------------------------+-------------------------+----------------+---------------------------+--------+
       |XmNanimationPixmapDepth	| XmCAnimationPixmapDepth | int		   | 0			       | CSG	|
       +------------------------+-------------------------+----------------+---------------------------+--------+
       |XmNanimationStyle	| XmCAnimationStyle	  | unsigned char  | XmDRAG_UNDER_HIGHLIGHT    | CSG	|
       +------------------------+-------------------------+----------------+---------------------------+--------+
       |XmNdragProc		| XmCDragProc		  | XtCallbackProc | NULL		       | CSG	|
       +------------------------+-------------------------+----------------+---------------------------+--------+
       |XmNdropProc		| XmCDropProc		  | XtCallbackProc | NULL		       | CSG	|
       +------------------------+-------------------------+----------------+---------------------------+--------+
       |XmNdropRectangles	| XmCDropRectangles	  | XRectangle *   | dynamic		       | CSG	|
       +------------------------+-------------------------+----------------+---------------------------+--------+
       |XmNdropSiteActivity	| XmCDropSiteActivity	  | unsigned char  | XmDROP_SITE_ACTIVE	       | CSG	|
       +------------------------+-------------------------+----------------+---------------------------+--------+
       |XmNdropSiteOperations	| XmCDropSiteOperations	  | unsigned char  | XmDROP_MOVE | XmDROP_COPY | CSG	|
       +------------------------+-------------------------+----------------+---------------------------+--------+
       |XmNdropSiteType		| XmCDropSiteType	  | unsigned char  | XmDROP_SITE_SIMPLE	       | CG	|
       +------------------------+-------------------------+----------------+---------------------------+--------+
       |XmNimportTargets	| XmCImportTargets	  | Atom *	   | NULL		       | CSG	|
       +------------------------+-------------------------+----------------+---------------------------+--------+
       |XmNnumDropRectangles	| XmCNumDropRectangles	  | Cardinal	   | 1			       | CSG	|
       +------------------------+-------------------------+----------------+---------------------------+--------+
       |XmNnumImportTargets	| XmCNumImportTargets	  | Cardinal	   | 0			       | CSG	|
       +------------------------+-------------------------+----------------+---------------------------+--------+
       +------------------------+-------------------------+----------------+---------------------------+--------+
       XmNanimationMask
		 Specifies  a mask to use with the pixmap specified by XmNani-
		 mationPixmap when the animation style is XmDRAG_UNDER_PIXMAP.

       XmNanimationPixmap
		 Specifies a pixmap for	drag-under animation when  the	anima-
		 tion  style  is XmDRAG_UNDER_PIXMAP. The pixmap is drawn with
		 its origin at the upper left corner of	the  bounding  box  of
		 the drop site.	If the drop site window	is larger than the an-
		 imation pixmap, the portion of	the window not covered by  the
		 pixmap	will be	tiled with the window's	background color.

       XmNanimationPixmapDepth
		 Specifies  the	depth of the pixmap specified by the XmNanima-
		 tionPixmap resource. When the depth  is  1,  the  colors  are
		 taken	from  the  foreground  and background of the drop site
		 widget. For any other value, drop site	animation occurs  only
		 if  the XmNanimationPixmapDepth matches the depth of the drop
		 site window. Colors are derived from the current colormap.

       XmNanimationStyle
		 Specifies the drag-under animation style used when a drag en-
		 ters a	valid drop site. The possible values are

		 XmDRAG_UNDER_HIGHLIGHT
			   The drop site uses highlighting effects.

		 XmDRAG_UNDER_SHADOW_OUT
			   The drop site uses an outset	shadow.

		 XmDRAG_UNDER_SHADOW_IN
			   The drop site uses an inset shadow.

		 XmDRAG_UNDER_PIXMAP
			   The	drop site uses the pixmap specified by XmNani-
			   mationPixmap	to indicate that it  can  receive  the
			   drop.

		 XmDRAG_UNDER_NONE
			   The	drop  site  does  not use animation effects. A
			   client using	a dynamic protocol, may	provide	 drag-
			   under effects in its	XmNdragProc routine.

       XmNdragProc
		 Specifies  the	 procedure  that is invoked when the drop site
		 receives a crossing, motion, or  operation  changed  message.
		 This  procedure  is  called  only  when a dynamic protocol is
		 used.	The type of structure whose address is passed to  this
		 procedure  is	XmDragProcCallbackStruct.   The	reason sent to
		 the procedure is one of the following:

		    o  XmCR_DROP_SITE_ENTER_MESSAGE

		    o  XmCR_DROP_SITE_LEAVE_MESSAGE

		    o  XmCR_DRAG_MOTION

		    o  XmCR_OPERATION_CHANGED

		 The drag procedure may	change the values of some  members  of
		 the  XmDragProcCallbackStruct	passed	to it.	After the drag
		 procedure returns, the	toolkit	uses the final values in  ini-
		 tializing  some  members  of the callback structure passed to
		 the appropriate callbacks of the initiator (the DragContext's
		 XmNdropSiteEnterCallback,  XmNdropSiteLeaveCallback, XmNdrag-
		 MotionCallback, or XmNoperationChangedCallback	callbacks).

       XmNdropProc
		 Specifies the procedure that is invoked when a	drop  (exclud-
		 ing  a	 cancel	or interrupt action) occurs on a drop site re-
		 gardless of the status	of the drop  site.  The	 type  of  the
		 structure  whose  address  is passed to this procedure	is Xm-
		 DropProcCallbackStruct. The reason sent to the	 procedure  is
		 XmCR_DROP_MESSAGE.

		 The  drop  procedure may change the values of some members of
		 the XmDropProcCallbackStruct passed to	it.   After  the  drop
		 procedure  returns, the toolkit uses the final	values in ini-
		 tializing  some  members  of  the   XmDropStartCallbackStruct
		 passed	 to the	initiator's drop start callbacks (the DragCon-
		 text's	XmNdropStartCallback callbacks).

       XmNdropRectangles
		 Specifies a list of rectangles	that describe the shape	 of  a
		 drop  site.  The  locations of	the rectangles are relative to
		 the origin of the enclosing object. When XmNdropRectangles is
		 NULL,	the  drop  site	is assumed to be the sensitive area of
		 the enclosing widget. If XmNdropSiteType is  XmDROP_SITE_COM-
		 POSITE, this resource cannot be specified by the application.

		 Retrieving  this resource returns allocated memory that needs
		 to be freed with the XtFree function.

       XmNdropSiteActivity
		 Indicates whether a drop site is active or inactive. The val-
		 ues  are  XmDROP_SITE_ACTIVE,	XmDROP_SITE_INACTIVE,  and Xm-
		 DROP_SITE_IGNORE.  An active drop site	can  receive  a	 drop,
		 whereas  an  inactive	drop site is dormant. An inactive drop
		 site is treated as if it was not a registered drop  site  and
		 any  drag-under  visuals  associated with entering or leaving
		 the drop site do not occur. However, it  is  still  used  for
		 clipping  drag-under  effects.	 A value of XmDROP_SITE_IGNORE
		 indicates that	a drop site should be  ignored	for  all  pur-
		 poses.

       XmNdropSiteOperations
		 Specifies  the	set of valid operations	associated with	a drop
		 site.	This resource is a bit mask that is formed by  combin-
		 ing one or more of the	following values using a bitwise oper-
		 ation such as inclusive OR (|): XmDROP_COPY, XmDROP_LINK, and
		 XmDROP_MOVE.	The  value XmDROP_NOOP for this	resource indi-
		 cates that no operations are valid.

       XmNdropSiteType
		 Specifies the type of the drop	site. The possible values are

		 XmDROP_SITE_SIMPLE
			   The widget does not have  any  additional  children
			   that	are registered as drop sites.

		 XmDROP_SITE_COMPOSITE
			   The	widget	will have children that	are registered
			   as drop sites.

       XmNimportTargets
		 Specifies the list of target atoms that this  drop  site  ac-
		 cepts.

       XmNnumDropRectangles
		 Specifies  the	 number	of rectangles in the XmNdropRectangles
		 list. If the drop site	type  is  XmDROP_SITE_COMPOSITE,  this
		 resource can not be specified by the application.

       XmNnumImportTargets
		 Specifies the number of atoms in the target atom list.

   Callback Information
       A  pointer to the following structure is	passed to the XmNdragProc rou-
       tine when the drop site receives	crossing, motion, or operation changed
       messages:

       typedef struct
       {
	       int reason;
	       XEvent *event;
	       Time timeStamp;
	       Widget dragContext;
	       Position	x;
	       Position	y;
	       unsigned	char dropSiteStatus;
	       unsigned	char operation;
	       unsigned	char operations;
	       Boolean animate;
       } XmDragProcCallbackStruct, *XmDragProcCallback;

       reason	 Indicates why the callback was	invoked.

       event	 Points	to the XEvent that triggered the callback.

       timeStamp Specifies the timestamp of the	logical	event.

       dragContext
		 Specifies  the	 ID  of	the DragContext	widget associated with
		 the transaction.

       x	 Indicates the x-coordinate of the  pointer  relative  to  the
		 drop site.

       y	 Indicates  the	 y-coordinate  of  the pointer relative	to the
		 drop site.

       dropSiteStatus
		 An IN/OUT member that indicates whether or not	a drop site is
		 valid.

		 When  reason  is  XmCR_DROP_SITE_ENTER_MESSAGE	or XmCR_OPERA-
		 TION_CHANGED,	  or	reason	  is	XmCR_DRAG_MOTION    or
		 XmCR_DROP_SITE_LEAVE_MESSAGE  and  the	 pointer is not	in the
		 same drop site	as on the previous invocation of the drag pro-
		 cedure,   the	 toolkit  initializes  dropSiteStatus  to  Xm-
		 DROP_SITE_VALID if the	DragContext's XmNexportTargets and the
		 DropSite's XmNimportTargets are compatible and	if the initial
		 value of the operation	member is not XmDROP_NOOP.  Otherwise,
		 the  toolkit  initializes  dropSiteStatus  to XmDROP_SITE_IN-
		 VALID.

		 When	  the	  reason      is      XmCR_DRAG_MOTION	    or
		 XmCR_DROP_SITE_LEAVE_MESSAGE  and  the	 pointer is within the
		 same drop site	as on the previous invocation of the drag pro-
		 cedure,  the  toolkit initializes dropSiteStatus to the value
		 of dropSiteStatus at the time the previous invocation of  the
		 drag procedure	returns.

		 The  drag procedure may change	the value of this member.  Af-
		 ter the drag procedure	returns, the toolkit  uses  the	 final
		 value	in initializing	the dropSiteStatus member of the call-
		 back struct passed to the appropriate callbacks of  the  ini-
		 tiator.

       operation An IN/OUT member that identifies an operation.

		 The  toolkit  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  Xm-
		 DROP_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.

		 The drag procedure may	change the value of this member.   Af-
		 ter  the  drag	 procedure returns, the	toolkit	uses the final
		 value in initializing the operation member  of	 the  callback
		 struct	passed to the appropriate callbacks of the initiator.

       operations
		 An  IN/OUT  member  that indicates the	set of operations sup-
		 ported	for the	source data.

		 If the	user does not select an	operation (by pressing a modi-
		 fier key), the	toolkit	initializes operations to the value of
		 the DragContext's XmNdragOperations resource.	 If  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.

		 The  drag procedure may change	the value of this member.  Af-
		 ter the drag procedure	returns, the toolkit  uses  the	 final
		 value	in  initializing the operations	member of the callback
		 struct	passed to the appropriate callbacks of the initiator.

       animate	 An OUT	member that indicates whether the toolkit or  the  re-
		 ceiver	 client	 provides  drag-under effects for a valid drop
		 site. If animate is set to True, the  toolkit	provides  drop
		 site  animation  per the XmNanimationStyle resource value; if
		 it is set to False, the receiver generates drag-under	anima-
		 tion effects.

       A  pointer to the following structure is	passed to the XmNdropProc rou-
       tine when the drop site receives	a drop message:

       typedef struct
       {
	       int reason;
	       XEvent *event;
	       Time timeStamp;
	       Widget dragContext;
	       Position	x;
	       Position	y;
	       unsigned	char dropSiteStatus;
	       unsigned	char operation;
	       unsigned	char operations;
	       unsigned	char dropAction;
       } XmDropProcCallbackStruct, *XmDropProcCallback;

       reason	 Indicates why the callback was	invoked.

       event	 Specifies the XEvent that triggered the callback.

       timeStamp Specifies the timestamp of the	logical	event.

       dragContext
		 Specifies the ID of the DragContext  widget  associated  with
		 the transaction.

       x	 Indicates  the	 x-coordinate  of  the pointer relative	to the
		 drop site.

       y	 Indicates the y-coordinate of the  pointer  relative  to  the
		 drop site.

       dropSiteStatus
		 An IN/OUT member that indicates whether or not	a drop site is
		 valid.

		 The toolkit initializes dropSiteStatus	 to  XmDROP_SITE_VALID
		 if the	DragContext's XmNexportTargets and the DropSite's XmN-
		 importTargets are compatible and if the initial value of  the
		 operation  member is not XmDROP_NOOP.	Otherwise, the toolkit
		 initializes dropSiteStatus to XmDROP_SITE_INVALID.

		 The drop procedure may	change the value of this member.   Af-
		 ter  the  drop	 procedure returns, the	toolkit	uses the final
		 value in initializing the dropSiteStatus member  of  the  Xm-
		 DropStartCallbackStruct  passed to the	initiator's drop start
		 callbacks (the	DragContext's XmNdropStartCallback callbacks).

       operation An IN/OUT member that identifies an operation.

		 The toolkit 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 Xm-
		 DROP_MOVE, then for XmDROP_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 XmDROP_NOOP.

		 The  drop procedure may change	the value of this member.  Af-
		 ter the drop procedure	returns, the toolkit  uses  the	 final
		 value	in  initializing  the  operation member	of the XmDrop-
		 StartCallbackStruct passed  to	 the  initiator's  drop	 start
		 callbacks (the	DragContext's XmNdropStartCallback callbacks).

       operations
		 An  IN/OUT  member  that indicates the	set of operations sup-
		 ported	for the	source data.

		 If the	user does not select an	operation (by pressing a modi-
		 fier key), the	toolkit	initializes operations to the value of
		 the DragContext's XmNdragOperations resource.	 If  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.

		 The  drop procedure may change	the value of this member.  Af-
		 ter the drop procedure	returns, the toolkit  uses  the	 final
		 value	in  initializing  the operations member	of the XmDrop-
		 StartCallbackStruct passed  to	 the  initiator's  drop	 start
		 callbacks (the	DragContext's XmNdropStartCallback callbacks).

       dropAction
		 An  IN/OUT  member that identifies the	action associated with
		 the drop.  The	possible values	are

		 XmDROP	   A drop was attempted. If the	drop  site  is	valid,
			   drop	transfer handling proceeds.

		 XmDROP_HELP
			   The user has	requested help on the drop site.

		 The  drop procedure may change	the value of this member.  Af-
		 ter the drop procedure	returns, the toolkit  uses  the	 final
		 value	in  initializing  the dropAction member	of the XmDrop-
		 StartCallbackStruct passed  to	 the  initiator's  drop	 start
		 callbacks (the	DragContext's XmNdropStartCallback callbacks).

RELATED	INFORMATION
       XmDragContext(3),  XmDragIcon(3),  XmDropSiteConfigureStackingOrder(3),
       XmDropSiteEndUpdate(3), XmDropSiteQueryStackingOrder(3),	XmDropSiteReg-
       ister(3),  XmDropSiteStartUpdate(3), XmDropSiteUpdate(3), XmDropSiteUn-
       register(3), XmDropTransfer(3), and XmTargetsAreCompatible(3).

								 XmDropSite(3)

NAME | SYNOPSIS | DESCRIPTION | RELATED INFORMATION

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

home | help