 |
Index for
Section 3X |
|
 |
Alphabetical
listing for X |
|
 |
Bottom of
page |
|
XmDropSite(3X)
OSF/Motif
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
XmNanimationMask
Class: XmCAnimationMask
Default: XmUNSPECIFIED_PIXMAP
Type: Pixmap
Access: CSG
XmNanimationPixmap
Class: XmCAnimationPixmap
Default: XmUNSPECIFIED_PIXMAP
Type: Pixmap
Access: CSG
XmNanimationPixmapDepth
Class: XmCAnimationPixmapDepth
Default: 0
Type: int
Access: CSG
XmNanimationStyle
Class: XmCAnimationStyle
Default: XmDRAG_UNDER_HIGHLIGHT
Type: unsigned char
Access: CSG
XmNdragProc
Class: XmCDragProc
Default: NULL
Type: XtCallbackProc
Access: CSG
XmNdropProc
Class: XmCDropProc
Default: NULL
Type: XtCallbackProc
Access: CSG
XmNdropRectangles
Class: XmCDropRectangles
Default: dynamic
Type: XRectangle *
Access: CSG
XmNdropSiteActivity
Class: XmCDropSiteActivity
Default: XmDROP_SITE_ACTIVE
Type: unsigned char
Access: CSG
XmNdropSiteOperations
Class: XmCDropSiteOperations
Default: XmDROP_MOVE XmDROP_COPY
Type: unsigned char
Access: CSG
XmNdropSiteType
Class: XmCDropSiteType
Default: XmDROP_SITE_SIMPLE
Type: unsigned char
Access: CG
XmNimportTargets
Class: XmCImportTargets
Default: NULL
Type: Atom *
Access: CSG
XmNnumDropRectangles
Class: XmCNumDropRectangles
Default: 1
Type: Cardinal
Access: CSG
XmNnumImportTargets
Class: XmCNumImportTargets
Default: 0
Type: Cardinal
Access: 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.
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:
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).
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 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).
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_COMPOSITE, this resource cannot be
specified by the application.
XmNdropSiteActivity
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.
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 (|):
XmDROP_COPY, XmDROP_LINK, and XmDROP_MOVE. The value XmDROP_NOOP for
this resource indicates 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 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;
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 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 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.
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).
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).
SEE ALSO
XmDragContext(3X), XmDragIcon(3X), XmDropSiteConfigureStackingOrder(3X),
XmDropSiteEndUpdate(3X), XmDropSiteQueryStackingOrder(3X),
XmDropSiteRegister(3X), XmDropSiteStartUpdate(3X), XmDropSiteUpdate(3X),
XmDropSiteUnregister(3X), XmDropTransfer(3X), XmTargetsAreCompatible(3X)
|
Index for
Section 3X |
|
|
Alphabetical
listing for X |
|
 |
Top of
page |
|