XmDropSite(3X) UNIX System V XmDropSite(3X)
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
1 (printed 6/8/92)
XmDropSite(3X) UNIX System V XmDropSite(3X)
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
XmDRAGUNDERPIXMAP.
XmNanimationPixmap
Specifies a pixmap for drag-under animation when
the animation style is XmDRAGUNDERPIXMAP. 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
2 (printed 6/8/92)
XmDropSite(3X) UNIX System V XmDropSite(3X)
current colormap.
XmNanimationStyle
Specifies the drag-under animation style used when
a drag enters a valid drop site. The possible
values are
XmDRAGUNDERHIGHLIGHT
The drop site uses highlighting effects.
XmDRAGUNDERSHADOWOUT
The drop site uses an outset shadow.
XmDRAGUNDERSHADOWIN
The drop site uses an inset shadow.
XmDRAGUNDERPIXMAP
The drop site uses the pixmap specified by
XmNanimationPixmap to indicate that it can
receive the drop.
XmDRAGUNDERNONE
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:
XmCRDROPSITEENTERMESSAGE
XmCRDROPSITELEAVEMESSAGE
XmCRDRAGMOTIONMESSAGE
XmCROPERATIONCHANGEDMESSAGE
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
3 (printed 6/8/92)
XmDropSite(3X) UNIX System V XmDropSite(3X)
callbacks of the initiator (the DragContext's
XmNdropSiteEnterCallback,
XmNdropSiteLeaveCallback, XmNdragMotionCallback,
or XmNoperationChangedCallback callbacks).
XmNdropProc
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 XmCRDROPMESSAGE.
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).
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
XmDROPSITECOMPOSITE, this resource cannot be
specified by the application.
XmNdropSiteActivity
Indicates whether a drop site is active or
inactive. The values are XmDROPSITEACTIVE and
XmDROPSITEINACTIVE. 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.
XmNdropSiteOperations
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 (|): XmDROPCOPY, XmDROPLINK, and
XmDROPMOVE. The value XmDROPNOOP for this
resource indicates that no operations are valid.
4 (printed 6/8/92)
XmDropSite(3X) UNIX System V XmDropSite(3X)
XmNdropSiteType
Specifies the type of the drop site. The possible
values are
XmDROPSITESIMPLE
The widget does not have any additional children
that are registered as drop sites.
XmDROPSITECOMPOSITE
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
XmDROPSITECOMPOSITE, 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 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
5 (printed 6/8/92)
XmDropSite(3X) UNIX System V XmDropSite(3X)
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 XmCRDROPSITEENTERMESSAGE
or XmCROPERATIONCHANGEDMESSAGE, or when the
reason is XmCRDRAGMOTIONMESSAGE or
XmCRDROPSITELEAVEMESSAGE 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
XmDROPSITEVALID if the DragContext's
XmNexportTargets and the DropSite's
XmNimportTargets are compatible and if the
initial value of the operation member is not
XmDROPNOOP. Otherwise, the toolkit initializes
dropSiteStatus to XmDROPSITEINVALID.
When the reason is XmCRDRAGMOTIONMESSAGE or
XmCRDROPSITELEAVEMESSAGE 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
6 (printed 6/8/92)
XmDropSite(3X) UNIX System V XmDropSite(3X)
the DropSite's XmNdropSiteOperations resource.
The toolkit searches this set first for
XmDROPMOVE, then for XmDROPCOPY, then for
XmDROPLINK, 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 XmDROPNOOP.
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 XmDROPNOOP.
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;
7 (printed 6/8/92)
XmDropSite(3X) UNIX System V XmDropSite(3X)
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
XmDROPSITEVALID if the DragContext's
XmNexportTargets and the DropSite's
XmNimportTargets are compatible and if the
initial value of the operation member is not
XmDROPNOOP. Otherwise, the toolkit initializes
dropSiteStatus to XmDROPSITEINVALID.
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.
8 (printed 6/8/92)
XmDropSite(3X) UNIX System V XmDropSite(3X)
The toolkit searches this set first for
XmDROPMOVE, then for XmDROPCOPY, then for
XmDROPLINK, 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 XmDROPNOOP.
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.
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 XmDROPNOOP.
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.
XmDROPHELP
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
9 (printed 6/8/92)
XmDropSite(3X) UNIX System V XmDropSite(3X)
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).
10 (printed 6/8/92)