XmDropSite(library call) XmDropSite(library call)
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
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. 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
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 | 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
animation 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
enters 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
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 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
XmDROP_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
accepts.
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
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 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.
After 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
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.
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.
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.
animate 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 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.
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 XmNdropStartCallback call-
backs).
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
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 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.
After 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.
After 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(library call)
openMotif 2.3.1 - Generated Sun Nov 30 12:12:56 CST 2008