XmDropSite(3X)

XmDropSite - The DropSite Registry

As shipped in IRIX 6.5.30. Added in IRIX 6.5.19.

NAME
XmDropSite - The DropSite Registry

SYNOPSIS
#include <Xm/DragDrop.h>

DESCRIPTION
A client registers a widget or gadget as a drop site using
the XmDropSiteRegister 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 XmNanimationStyle
resource. Otherwise, if the XmNdragProc routine is
specified, 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 overlaps another drop site,
the drag-under effects of the drop site underneath are
clipped by the obscuring drop site(s).

The XmDropSiteUpdate routine sets resources for a widget
that is registered 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 programmer 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 .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 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
XmNanimationPixmap when the animation style is
XmDRAG_UNDER_PIXMAP.

XmNanimationPixmap
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.

XmNanimationPixmapDepth
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 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
XmNanimationPixmap 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. 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:

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 callbacks of the initiator (the
DragContext's XmNdropSiteEnterCallback,
XmNdropSiteLeaveCallback, XmNdragMotionCallback, or
XmNoperationChangedCallback 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 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
initializing some members of the XmDropStartCallbackStruct
passed to the initiator's drop start callbacks (the
DragContext's XmNdropStartCallback 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 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 application. Indicates whether a drop site is active or
inactive. The values 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 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

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. 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 routine 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;

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 the reason is XmCR_DROP_SITE_ENTER_MESSAGE or
XmCR_OPERATION_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 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
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.

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 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.

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 animation effects.

A pointer to the following structure is passed to the XmNdropProc
routine 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;

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
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 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 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
XmDropStartCallbackStruct passed to the initiator's drop start
callbacks (the DragContext's XmNdropStartCallback callbacks).

operations
An IN/OUT member that indicates the set of operations supported for the
source data.

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 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
XmDropStartCallbackStruct passed to the initiator's drop start
callbacks (the DragContext's XmNdropStartCallback callbacks).

RELATED INFORMATION
XmDragContext(3X), XmDragIcon(3X),
XmDropSiteConfigureStackingOrder(3X),
XmDropSiteEndUpdate(3X), XmDropSiteQueryStackingOrder(3),
XmDropSiteRegister(3X), XmDropSiteStartUpdate(3X),
XmDropSiteUpdate(3X), XmDropSiteUnregister(3X),
XmDropTransfer(3X), and XmTargetsAreCompatible(3X).