XmDropSite(3X)XmDropSite(3X)NAMEXmDropSite - 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
entering 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
effects (through the XmNdragProc routine) or rely on the toolkit to
provide animation.
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 val‐
ues 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 remain‐
ing 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 XmDropSiteUpdate (S),
retrieved by using XmDropSiteRetrieve (G), or is not applicable (N/A).
XmDropSite Resource Set
Class: XmCAnimationMask
Default: XmUNSPECIFIED_PIXMAP
Type: Pixmap
Access: CSG
Class: XmCAnimationPixmap
Default: XmUNSPECIFIED_PIXMAP
Type: Pixmap
Access: CSG
Class: XmCAnimationPixmapDepth
Default: 0
Type: int
Access: CSG
Class: XmCAnimationStyle
Default: XmDRAG_UNDER_HIGHLIGHT
Type: unsigned char
Access: CSG
Class: XmCDragProc
Default: NULL
Type: XtCallbackProc
Access: CSG
Class: XmCDropProc
Default: NULL
Type: XtCallbackProc
Access: CSG
Class: XmCDropRectangles
Default: dynamic
Type: XRectangle *
Access: CSG
Class: XmCDropSiteActivity
Default: XmDROP_SITE_ACTIVE
Type: unsigned char
Access: CSG
Class: XmCDropSiteOperations
Default: XmDROP_MOVE XmDROP_COPY
Type: unsigned char
Access: CSG
Class: XmCDropSiteType
Default: XmDROP_SITE_SIMPLE
Type: unsigned char
Access: CG
Class: XmCImportTargets
Default: NULL
Type: Atom *
Access: CSG
Class: XmCNumDropRectangles
Default: 1
Type: Cardinal
Access: CSG
Class: XmCNumImportTargets
Default: 0
Type: Cardinal
Access: CSG
Specifies a mask to use with the pixmap specified by XmNanima‐
tionPixmap when the animation style is XmDRAG_UNDER_PIXMAP.
Specifies a pixmap for drag-under animation when the animation
style is XmDRAG_UNDER_PIXMAP. The pixmap is drawn with its ori‐
gin at the upper left corner of the bounding box of the drop
site. If the drop site window is larger than the animation
pixmap, the portion of the window not covered by the pixmap will
be tiled with the window's background color. Specifies the
depth of the pixmap specified by the XmNanimationPixmap
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 XmNanima‐
tionPixmapDepth matches the depth of the drop site window. Col‐
ors are derived from the current colormap. Specifies the drag-
under animation style used when a drag enters a valid drop site.
The possible values are: The drop site uses highlighting
effects. The drop site uses an outset shadow. The drop site
uses an inset shadow. The drop site uses the pixmap specified
by XmNanimationPixmap to indicate that it can receive the drop.
The drop site does not use animation effects. A client using a
dynamic protocol, may provide drag-under effects in its XmNdrag‐
Proc routine. Specifies the procedure that is invoked when the
drop site receives a crossing, motion, or operation changed mes‐
sage. This procedure is called only when a dynamic protocol is
used. The type of structure whose address is passed to this pro‐
cedure is XmDragProcCallbackStruct. The reason sent to the pro‐
cedure is one of the following:
XmCR_DROP_SITE_ENTER_MESSAGE
XmCR_DROP_SITE_LEAVE_MESSAGE
XmCR_DRAG_MOTION_MESSAGE
XmCR_OPERATION_CHANGED_MESSAGE
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 initializing some
members of the callback struct passed to the appropriate call‐
backs of the initiator (the DragContext's XmNdropSiteEnterCall‐
back, XmNdropSiteLeaveCallback, XmNdragMotionCallback, or XmNop‐
erationChangedCallback callbacks). Specifies the procedure that
is invoked when a drop (excluding a cancel or interrupt action)
occurs on a drop site regardless of the status of the drop site.
The type of the structure whose address is passed to this proce‐
dure is XmDropProcCallbackStruct. The reason sent to the proce‐
dure 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 initializing some
members of the XmDropStartCallbackStruct passed to the initia‐
tor's drop start callbacks (the DragContext's XmNdropStartCall‐
back callbacks). 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 XmN‐
dropRectangles is NULL, the drop site is assumed to be the sen‐
sitive area of the enclosing widget. If XmNdropSiteType is
XmDROP_SITE_COMPOSITE, this resource cannot be specified by the
application. Indicates whether a drop site is active or inac‐
tive. The values are XmDROP_SITE_ACTIVE and XmDROP_SITE_INAC‐
TIVE. An active drop site can receive a drop, whereas an inac‐
tive 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.
Specifies the set of valid operations associated with a drop
site. 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, and
XmDROP_MOVE. The value XmDROP_NOOP for this resource indicates
that no operations are valid. Specifies the type of the drop
site. The possible values are: The widget does not have any
additional children that are registered as drop sites. The wid‐
get will have children that are registered as drop sites. Spec‐
ifies the list of target atoms that this drop site accepts.
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. 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, *XmDragProcCall‐
back;
Indicates why the callback was invoked. Points to the XEvent that
triggered the callback. Specifies the timestamp of the logical event.
Specifies the ID of the DragContext widget associated with the transac‐
tion. Indicates the x-coordinate of the pointer relative to the drop
site. Indicates the y-coordinate of the pointer relative to the drop
site. An IN/OUT member that indicates whether or not a drop site is
valid.
When the reason is XmCR_DROP_SITE_ENTER_MESSAGE or XmCR_OPERA‐
TION_CHANGED_MESSAGE, or when the reason is
XmCR_DRAG_MOTION_MESSAGE or XmCR_DROP_SITE_LEAVE_MESSAGE and the
pointer is not in the same drop site as on the previous invoca‐
tion of the drag procedure, the toolkit initializes dropSiteSta‐
tus as follows: the toolkit initializes dropSiteStatus to
XmDROP_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_INVALID.
When the reason is XmCR_DRAG_MOTION_MESSAGE or
XmCR_DROP_SITE_LEAVE_MESSAGE and the pointer is within the same
drop site as on the previous invocation of the drag procedure,
the toolkit initializes dropSiteStatus to the value of drop‐
SiteStatus at the time the previous invocation of the drag pro‐
cedure returns.
The drag procedure may change the value of this member. After
the drag procedure returns, the toolkit uses the final value in
initializing the dropSiteStatus member of the callback struct
passed to the appropriate callbacks of the initiator. 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 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.
The drag procedure may change the value of this member. After
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. An IN/OUT member
that indicates the set of operations supported for the source
data.
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 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 initializes operations to
XmDROP_NOOP.
The drag procedure may change the value of this member. After
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. An OUT member
that indicates whether the toolkit or the receiver client pro‐
vides 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 animation 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, *XmDropProcCall‐
back;
Indicates why the callback was invoked. Specifies the XEvent that
triggered the callback. Specifies the timestamp of the logical event.
Specifies the ID of the DragContext widget associated with the transac‐
tion. Indicates the x-coordinate of the pointer relative to the drop
site. Indicates the y-coordinate of the pointer relative to the drop
site. 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 XmNimport‐
Targets 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. After
the drop procedure returns, the toolkit uses the final value in
initializing the dropSiteStatus member of the XmDropStartCall‐
backStruct passed to the initiator's drop start callbacks (the
DragContext's XmNdropStartCallback callbacks). 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 XmDROP_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. After
the drop procedure returns, the toolkit uses the final value in
initializing the operation member of the XmDropStartCallback‐
Struct passed to the initiator's drop start callbacks (the Drag‐
Context's XmNdropStartCallback callbacks). An IN/OUT member
that indicates the set of operations supported for the source
data.
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 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 initializes operations to
XmDROP_NOOP.
The drop procedure may change the value of this member. After
the drop procedure returns, the toolkit uses the final value in
initializing the operations member of the XmDropStartCallback‐
Struct passed to the initiator's drop start callbacks (the Drag‐
Context's XmNdropStartCallback callbacks). An IN/OUT member
that identifies the action associated with the drop. The possi‐
ble values are: A drop was attempted. If the drop site is
valid, drop transfer handling proceeds. The user has requested
help on the drop site.
The drop procedure may change the value of this member. After the drop
procedure returns, the toolkit uses the final value in initializing the
dropAction member of the XmDropStartCallbackStruct passed to the ini‐
tiator's drop start callbacks (the DragContext's XmNdropStartCallback
callbacks).
SEE ALSOXmDragContext(3X), XmDragIcon(3X), XmDropSiteConfig‐
ureStackingOrder(3X), XmDropSiteEndUpdate(3X), XmDropSiteQueryS‐
tackingOrder(3X), XmDropSiteRegister(3X), XmDropSiteStartUpdate(3X),
XmDropSiteUpdate(3X), XmDropSiteUnregister(3X), XmDropTransfer(3X),
XmTargetsAreCompatible(3X)XmDropSite(3X)
