XmDropSite - The DropSite Registry
#include <Xm/DragDrop.h>
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 [Toc] [Back]
XmDropSite does not inherit from any widget class.
New Resources [Toc] [Back]
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 [Toc] [Back]
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 XmNanimationPixmap when the animation style is
XmDRAG_UNDER_PIXMAP. Specifies a pixmap for dragunder
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 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.
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 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: The widget 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 [Toc] [Back]
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 char dropSiteStatus;
unsigned char operation;
unsigned char operations;
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 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_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. 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 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 char dropSiteStatus;
unsigned char operation;
unsigned char operations;
unsigned char dropAction; }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 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 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).
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). 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 XmDropStartCallbackStruct
passed to the initiator'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 initiator's drop
start callbacks (the DragContext's XmNdropStartCallback
callbacks).
XmDragContext(3X), XmDragIcon(3X), XmDropSiteConfigureStackingOrder(3X), XmDropSiteEndUpdate(3X), XmDropSiteQueryStackingOrder(3X), XmDropSiteRegister(3X), XmDropSiteStartUpdate(3X), XmDropSiteUpdate(3X), XmDropSiteUnregister(3X), XmDropTransfer(3X), XmTargetsAreCompatible(3X)
XmDropSite(3X)
[ Back ] |
