XmDropSite(3X) OSF/Motif 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
───────────────────────────────────────────────────────────────────
Name Default Access
Class Type
───────────────────────────────────────────────────────────────────
───────────────────────────────────────────────────────────────────
XmNanimationMask XmUNSPECIFIED_PIXMAP CSG
XmCAnimationMask Pixmap
───────────────────────────────────────────────────────────────────
XmNanimationPixmap XmUNSPECIFIED_PIXMAP CSG
XmCAnimationPixmap Pixmap
───────────────────────────────────────────────────────────────────
XmNanimationPixmapDepth 0 CSG
XmCAnimationPixmapDepth int
───────────────────────────────────────────────────────────────────
XmNanimationStyle XmDRAG_UNDER_HIGHLIGHT CSG
XmCAnimationStyle unsigned char
───────────────────────────────────────────────────────────────────
XmNdragProc NULL CSG
XmCDragProc XtCallbackProc
───────────────────────────────────────────────────────────────────
XmNdropProc NULL CSG
XmCDropProc XtCallbackProc
───────────────────────────────────────────────────────────────────
XmNdropRectangles dynamic CSG
XmCDropRectangles XRectangle *
───────────────────────────────────────────────────────────────────
XmNdropSiteActivity XmDROP_SITE_ACTIVE CSG
XmCDropSiteActivity unsigned char
───────────────────────────────────────────────────────────────────
XmNdropSiteOperations XmDROP_MOVE XmDROP_COPY CSG
XmCDropSiteOperations unsigned char
───────────────────────────────────────────────────────────────────
XmNdropSiteType XmDROP_SITE_SIMPLE CG
XmCDropSiteType unsigned char
───────────────────────────────────────────────────────────────────
XmNimportTargets NULL CSG
XmCImportTargets Atom *
───────────────────────────────────────────────────────────────────
XmNnumDropRectangles 1 CSG
XmCNumDropRectangles Cardinal
───────────────────────────────────────────────────────────────────
XmNnumImportTargets 0 CSG
XmCNumImportTargets Cardinal
───────────────────────────────────────────────────────────────────
Specifies a mask to use with the pixmap specified by XmNanimationPixmap
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 origin 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 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. 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 speci‐
fied 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 XmNdragProc routine.
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:
The drag procedure may change the values of some members of the XmDrag‐
ProcCallbackStruct passed to it. After the drag procedure returns, the
toolkit uses the final values in initializing some members of the call‐
back struct passed to the appropriate callbacks of the initiator (the
DragContext's XmNdropSiteEnterCallback, XmNdropSiteLeaveCallback, XmN‐
dragMotionCallback, or XmNoperationChangedCallback callbacks). Speci‐
fies 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
procedure 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 XmDrop‐
ProcCallbackStruct passed to it. After the drop procedure returns, the
toolkit uses the final values in initializing some members of the
XmDropStartCallbackStruct passed to the initiator's drop start call‐
backs (the DragContext's XmNdropStartCallback callbacks). Specifies a
list of rectangles that describe the shape of a drop site. The loca‐
tions 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_COMPOSITE, this resource cannot be specified by the appli‐
cation. Indicates whether a drop site is active or inactive. The val‐
ues are XmDROP_SITE_ACTIVE and XmDROP_SITE_INACTIVE. 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. 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 inclu‐
sive 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 wid‐
get does not have any additional children that are registered as drop
sites. The widget will have children that are registered as drop
sites. Specifies 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 chardropSiteStatus; unsigned charoperation; unsigned
charoperations; Boolean animate; } XmDragProcCallbackStruct,
*XmDragProcCallback; 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 transaction. Indicates the x-coordinate of the pointer rela‐
tive to the drop site. Indicates the y-coordinate of the pointer rela‐
tive 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 invocation of the drag procedure, the toolkit
initializes dropSiteStatus as follows: the toolkit initializes drop‐
SiteStatus 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 tool‐
kit 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 dropSiteStatus at the time
the previous invocation of the drag procedure 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 opera‐
tion.
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 call‐
backs 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 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 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 chardropSiteStatus; unsigned charoperation; unsigned
charoperations; unsigned chardropAction; } XmDropProcCallbackStruct,
*XmDropProcCallback; 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 transaction. Indicates the x-coordinate of the pointer rela‐
tive to the drop site. Indicates the y-coordinate of the pointer rela‐
tive 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 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.
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 XmDropStartCallbackStruct passed to the
initiator's drop start callbacks (the DragContext's XmNdropStartCall‐
back 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 ini‐
tializes 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 XmDropStartCallbackStruct passed to the initia‐
tor's drop start callbacks (the DragContext's XmNdropStartCallback
callbacks). 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 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 XmDropStartCallbackStruct passed to the ini‐
tiator's drop start callbacks (the DragContext's XmNdropStartCallback
callbacks). An IN/OUT member that identifies the action associated
with the drop. The possible 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).
RELATED INFORMATIONXmDragContext(3X), XmDragIcon(3X), XmDropSiteConfig‐
ureStackingOrder(3X), XmDropSiteEndUpdate(3X), XmDropSiteQueryS‐
tackingOrder(3X), XmDropSiteRegister(3X), XmDropSiteStartUpdate(3X),
XmDropSiteUpdate(3X), XmDropSiteUnregister(3X), XmDropTransfer(3X), and
XmTargetsAreCompatible(3X).
XmDropSite(3X)
