XmDragContext(library call) XmDragContext(library call)
NAME
XmDragContext -- The DragContext widget class
SYNOPSIS
#include <Xm/DragDrop.h>
DESCRIPTION
DragContexts are special widgets used in drag and drop transactions. A
DragContext is implemented as a widget, but a client does not explic-
itly create a DragContext widget. Instead, a client initiates a drag
and drop transaction by calling XmDragStart, and this routine initial-
izes and returns a DragContext widget. There is a unique DragContext
for each drag operation. The toolkit frees a DragContext when a trans-
action is complete; therefore, an application programmer should not
explicitly destroy a DragContext.
Initiator and receiver clients both use DragContexts to track the state
of a transaction. When the initiator and receiver of a transaction are
in the same client, they share the same DragContext instance. If they
are in different clients, there are two separate DragContexts. In this
case, the initiator calls XmDragStart and the toolkit provides a Drag-
Context for the receiver client. The only resources pertinent to the
receiver are XmNexportTargets and XmNnumExportTargets. These can both
be passed as arguments to the XmDropSiteRetrieve function to obtain
information about the current drop site.
In general, in order to receive data, a drop site must share at least
one target type and operation in common with a drag source. The Drag-
Context resource, XmNexportTargets, identifies the selection targets
for the drag source. These export targets are compared with the XmNim-
portTargets resource list specified by a drop site. The DragContext
resource, XmNdragOperations, identifies the valid operations that can
be applied to the source data by the initiator. The drop site counter-
part resource is XmNdropSiteOperations, which indicates a drop site's
supported operations.
A client uses DragIcon widgets to define the drag-over animation
effects associated with a given drag and drop transaction. An initia-
tor specifies a set of drag icons, selects a blending model, and sets
foreground and background cursor colors with DragContext resources.
The type of drag-over visual used to represent a drag operation depends
on the drag protocol style. In preregister mode, the server is grabbed,
and either a cursor or a pixmap may be used as a drag-over visual. In
dynamic mode, drag-over visuals must be implemented with the X cursor.
If the resulting drag protocol style is Drop Only or None and the XmN-
dragInitiatorProtocolStyle is XmDRAG_DYNAMIC or XmDRAG_PREFER_DYNAMIC,
then a dynamic visual style (cursor) is used. Otherwise, a preregister
visual style is used.
Classes
DragContext inherits behavior and resources from Core.
The class pointer is xmDragContextClass.
The class name is XmDragContext.
New Resources
The following table defines a set of widget resources used by the pro-
grammer to specify data. The programmer can also set the resource val-
ues for the inherited classes to set attributes for this widget. 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 XtSetValues (S), retrieved by using XtGetValues (G), or is
not applicable (N/A).
+-----------------------------------------------------------------------------------------------------------------------+
| | XmDragContext Resource Set | | |
|Name | Class | Type | Default | Access |
+----------------------------+------------------------+----------------------------+---------------------------+--------+
|XmNblendModel | XmCBlendModel | unsigned char | XmBLEND_ALL | CG |
+----------------------------+------------------------+----------------------------+---------------------------+--------+
|XmNclientData | XmCClientData | XtPointer | NULL | CSG |
+----------------------------+------------------------+----------------------------+---------------------------+--------+
|XmNconvertProc | XmCConvertProc | XtConvertSelectionIncrProc | NULL | CSG |
+----------------------------+------------------------+----------------------------+---------------------------+--------+
|XmNcursorBackground | XmCCursorBackground | Pixel | dynamic | CSG |
+----------------------------+------------------------+----------------------------+---------------------------+--------+
|XmNcursorForeground | XmCCursorForeground | Pixel | dynamic | CSG |
+----------------------------+------------------------+----------------------------+---------------------------+--------+
|XmNdragDropFinishCallback | XmCCallback | XtCallbackList | NULL | CSG |
+----------------------------+------------------------+----------------------------+---------------------------+--------+
|XmNdragMotionCallback | XmCCallback | XtCallbackList | NULL | C |
+----------------------------+------------------------+----------------------------+---------------------------+--------+
|XmNdragOperations | XmCDragOperations | unsigned char | XmDROP_COPY | XmDROP_MOVE | C |
+----------------------------+------------------------+----------------------------+---------------------------+--------+
|XmNdropFinishCallback | XmCCallback | XtCallbackList | NULL | C |
+----------------------------+------------------------+----------------------------+---------------------------+--------+
|XmNdropSiteEnterCallback | XmCCallback | XtCallbackList | NULL | C |
+----------------------------+------------------------+----------------------------+---------------------------+--------+
|XmNdropSiteLeaveCallback | XmCCallback | XtCallbackList | NULL | C |
+----------------------------+------------------------+----------------------------+---------------------------+--------+
|XmNdropStartCallback | XmCCallback | XtCallbackList | NULL | C |
+----------------------------+------------------------+----------------------------+---------------------------+--------+
|XmNexportTargets | XmCExportTargets | Atom * | NULL | CSG |
+----------------------------+------------------------+----------------------------+---------------------------+--------+
|XmNincremental | XmCIncremental | Boolean | False | CSG |
+----------------------------+------------------------+----------------------------+---------------------------+--------+
|XmNinvalidCursorForeground | XmCCursorForeground | Pixel | dynamic | CSG |
+----------------------------+------------------------+----------------------------+---------------------------+--------+
|XmNnoneCursorForeground | XmCCursorForeground | Pixel | dynamic | CSG |
+----------------------------+------------------------+----------------------------+---------------------------+--------+
|XmNnumExportTargets | XmCNumExportTargets | Cardinal | 0 | CSG |
+----------------------------+------------------------+----------------------------+---------------------------+--------+
|XmNoperationChangedCallback | XmCCallback | XtCallbackList | NULL | C |
+----------------------------+------------------------+----------------------------+---------------------------+--------+
|XmNoperationCursorIcon | XmCOperationCursorIcon | Widget | dynamic | CSG |
+----------------------------+------------------------+----------------------------+---------------------------+--------+
|XmNsourceCursorIcon | XmCSourceCursorIcon | Widget | dynamic | CSG |
+----------------------------+------------------------+----------------------------+---------------------------+--------+
|XmNsourcePixmapIcon | XmCSourcePixmapIcon | Widget | dynamic | CSG |
+----------------------------+------------------------+----------------------------+---------------------------+--------+
|XmNstateCursorIcon | XmCStateCursorIcon | Widget | dynamic | CSG |
+----------------------------+------------------------+----------------------------+---------------------------+--------+
|XmNtopLevelEnterCallback | XmCCallback | XtCallbackList | NULL | C |
+----------------------------+------------------------+----------------------------+---------------------------+--------+
|XmNtopLevelLeaveCallback | XmCCallback | XtCallbackList | NULL | C |
+----------------------------+------------------------+----------------------------+---------------------------+--------+
|XmNvalidCursorForeground | XmCCursorForeground | Pixel | dynamic | CSG |
+----------------------------+------------------------+----------------------------+---------------------------+--------+
+----------------------------+------------------------+----------------------------+---------------------------+--------+
XmNblendModel
Specifies which combination of DragIcons are blended to pro-
duce a drag-over visual.
XmBLEND_ALL
Blends all three DragIcons: the source, state and
operation icons. The icons are layered from top to
bottom with the operation icon on top and the
source icon on the bottom. The hotspot is derived
from the state icon.
XmBLEND_STATE_SOURCE
Blends the state and source icons only. The hotspot
is derived from the state icon.
XmBLEND_JUST_SOURCE
Specifies that only the source icon is used, which
the initiator updates as required.
XmBLEND_NONE
Specifies that no drag-over visual is generated.
The client tracks the drop site status through
callback routines and updates the drag-over visuals
as necessary.
XmNclientData
Specifies the client data to be passed to XmNconvertProc when
it is invoked.
XmNconvertProc
If XmNincremental is True, specifies a procedure of type
XtConvertSelectionIncrProc that converts the source data to
the format(s) requested by the receiver client. The widget
argument passed to this procedure is the DragContext widget.
The selection atom passed is _MOTIF_DROP. If XmNincremental
is False, the procedure is an XtConvertSelectionProc, and
should ignore the max_length, client_data, and request_id
arguments and should handle the conversion atomically. Data
returned by XmNconvertProc must be allocated using XtMalloc,
and will be freed automatically by the toolkit after the
transfer. For additional information on selection conversion
procedures, see X Toolkit Intrinsics--C Language Interface.
XmNcursorBackground
Specifies the background pixel value of the cursor.
XmNcursorForeground
Specifies the foreground pixel value of the cursor when the
state icon is not blended. This resource defaults to the
foreground color of the widget passed to the XmDragStart
function.
XmNdragDropFinishCallback
Specifies the list of callbacks that are called when the
transaction is completed. The type of the structure whose
address is passed to this callback is XmDragDropFinishCall-
backStruct. The reason sent by the callback is
XmCR_DRAG_DROP_FINISH.
XmNdragMotionCallback
Specifies the list of callbacks that are invoked when the
pointer moves. The type of structure whose address is passed
to this callback is XmDragMotionCallbackStruct. The reason
sent by the callback is XmCR_DRAG_MOTION.
XmNdragOperations
Specifies the set of valid operations associated with an ini-
tiator client for a drag transaction. 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, XmDROP_MOVE. The value XmDROP_NOOP
for this resource indicates that no operations are valid.
For Text and TextField widgets, this resource is set to
XmDROP_COPY | XmDROP_MOVE; for List widgets, it is set to
XmDROP_COPY.
XmNdropFinishCallback
Specifies the list of callbacks that are invoked when the
drop is completed. The type of the structure whose address is
passed to this callback is XmDropFinishCallbackStruct. The
reason sent by the callback is XmCR_DROP_FINISH.
XmNdropSiteEnterCallback
Specifies the list of callbacks that are invoked when the
pointer enters a drop site. The type of the structure whose
address is passed to this callback is XmDropSiteEnterCall-
backStruct. The reason sent by the callback is
XmCR_DROP_SITE_ENTER.
XmNdropSiteLeaveCallback
Specifies the list of callbacks that are invoked when the
pointer leaves a drop site. The type of the structure whose
address is passed to this callback is XmDropSiteLeaveCall-
backStruct. The reason sent by the callback is
XmCR_DROP_SITE_LEAVE.
XmNdropStartCallback
Specifies the list of callbacks that are invoked when a drop
is initiated. The type of the structure whose address is
passed to this callback is XmDropStartCallbackStruct. The
reason sent by the callback is XmCR_DROP_START.
XmNexportTargets
Specifies the list of target atoms associated with this
source. This resource identifies the selection targets this
source can be converted to.
XmNincremental
Specifies a Boolean value that indicates whether the transfer
on the initiator side uses the Xt incremental selection
transfer mechanism described in X Toolkit Intrinsics--C Lan-
guage Interface. If the value is True, the initiator uses
incremental transfer; if the value is False, the initiator
uses atomic transfer.
XmNinvalidCursorForeground
Specifies the foreground pixel value of the cursor when the
state is invalid. This resource defaults to the value of the
XmNcursorForeground resource.
XmNnoneCursorForeground
Specifies the foreground pixel value of the cursor when the
state is none. This resource defaults to the value of the
XmNcursorForeground resource.
XmNnumExportTargets
Specifies the number of entries in the list of export tar-
gets.
XmNoperationChangedCallback
Specifies the list of callbacks that are invoked when the
drag is started and when the user requests that a different
operation be applied to the drop. The type of the structure
whose address is passed to this callback is XmOpera-
tionChangedCallbackStruct. The reason sent by the callback is
XmCR_OPERATION_CHANGED.
XmNoperationCursorIcon
Specifies the cursor icon used to designate the type of oper-
ation performed by the drag transaction. If NULL, XmScreen
resources provide default icons for copy, link, and move
operations.
XmNsourceCursorIcon
Specifies the cursor icon used to represent the source when a
dynamic visual style is used. If NULL, the XmNdefaultSource-
CursorIcon resource of XmScreen provides a default cursor
icon.
XmNsourcePixmapIcon
Specifies the pixmap icon used to represent the source when a
preregister visual style is used. The icon is used in con-
junction with the colormap of the widget passed to
XmDragStart. If NULL, XmNsourceCursorIcon is used.
XmNstateCursorIcon
Specifies the cursor icon used to designate the state of a
drop site. If NULL, XmScreen resources provide default icons
for a valid, invalid, and no drop site condition.
XmNtopLevelEnterCallback
Specifies the list of callbacks that are called when the
pointer enters a top-level window or root window (due to
changing screens). The type of the structure whose address is
passed to this callback is XmTopLevelEnterCallbackStruct. The
reason sent by the callback is XmCR_TOP_LEVEL_ENTER.
XmNtopLevelLeaveCallback
Specifies the list of callbacks that are called when the
pointer leaves a top level window or the root window (due to
changing screens). The type of the structure whose address is
passed to this callback is XmTopLevelLeaveCallbackStruct. The
reason sent by the callback is XmCR_TOP_LEVEL_LEAVE.
XmNvalidCursorForeground
Specifies the foreground pixel value of the cursor designated
as a valid cursor icon.
Inherited Resources
DragContext inherits behavior and resources from the superclass
described in the following table. For a complete description of each
resource, refer to the Core reference page.
+---------------------------------------------------------------------------------------------------------------+
| | Core Resource Set | | |
|Name | Class | Type | Default | Access |
+------------------------------+-------------------------------+----------------+----------------------+--------+
|XmNaccelerators | XmCAccelerators | XtAccelerators | dynamic | CSG |
+------------------------------+-------------------------------+----------------+----------------------+--------+
|XmNancestorSensitive | XmCSensitive | Boolean | dynamic | G |
+------------------------------+-------------------------------+----------------+----------------------+--------+
|XmNbackground | XmCBackground | Pixel | dynamic | CSG |
+------------------------------+-------------------------------+----------------+----------------------+--------+
|XmNbackgroundPixmap | XmCPixmap | Pixmap | XmUNSPECIFIED_PIXMAP | CSG |
+------------------------------+-------------------------------+----------------+----------------------+--------+
|XmNborderColor | XmCBorderColor | Pixel | XtDefaultForeground | CSG |
+------------------------------+-------------------------------+----------------+----------------------+--------+
|XmNborderPixmap | XmCPixmap | Pixmap | XmUNSPECIFIED_PIXMAP | CSG |
+------------------------------+-------------------------------+----------------+----------------------+--------+
|XmNborderWidth | XmCBorderWidth | Dimension | 0 | CSG |
+------------------------------+-------------------------------+----------------+----------------------+--------+
|XmNcolormap | XmCColormap | Colormap | dynamic | CG |
+------------------------------+-------------------------------+----------------+----------------------+--------+
|XmNdepth | XmCDepth | int | dynamic | CG |
+------------------------------+-------------------------------+----------------+----------------------+--------+
|XmNdestroyCallback | XmCCallback | XtCallbackList | NULL | C |
+------------------------------+-------------------------------+----------------+----------------------+--------+
|XmNheight | XmCHeight | Dimension | dynamic | CSG |
+------------------------------+-------------------------------+----------------+----------------------+--------+
|XmNinitialResourcesPersistent | XmCInitialResourcesPersistent | Boolean | True | C |
+------------------------------+-------------------------------+----------------+----------------------+--------+
|XmNmappedWhenManaged | XmCMappedWhenManaged | Boolean | True | CSG |
+------------------------------+-------------------------------+----------------+----------------------+--------+
|XmNscreen | XmCScreen | Screen * | dynamic | CG |
+------------------------------+-------------------------------+----------------+----------------------+--------+
|XmNsensitive | XmCSensitive | Boolean | True | CSG |
+------------------------------+-------------------------------+----------------+----------------------+--------+
|XmNtranslations | XmCTranslations | XtTranslations | dynamic | CSG |
+------------------------------+-------------------------------+----------------+----------------------+--------+
|XmNwidth | XmCWidth | Dimension | dynamic | CSG |
+------------------------------+-------------------------------+----------------+----------------------+--------+
|XmNx | XmCPosition | Position | 0 | CSG |
+------------------------------+-------------------------------+----------------+----------------------+--------+
|XmNy | XmCPosition | Position | 0 | CSG |
+------------------------------+-------------------------------+----------------+----------------------+--------+
+------------------------------+-------------------------------+----------------+----------------------+--------+
Callback Information
Each of the DragContext callbacks has an associated callback structure.
A pointer to the following structure is passed to the XmNdragDropFin-
ishCallback callback:
typedef struct
{
int reason;
XEvent *event;
Time timeStamp;
}XmDragDropFinishCallbackStruct, *XmDragDropFinishCallback;
reason Indicates why the callback was invoked
event Points to the XEvent that triggered the callback
timeStamp Specifies the time at which either the drag or the drop was
completed
A pointer to the following structure is passed to callbacks for XmN-
dragMotionCallback:
typedef struct
{
int reason;
XEvent *event;
Time timeStamp;
unsigned char operation;
unsigned char operations;
unsigned char dropSiteStatus;
Position x;
Position y;
}XmDragMotionCallbackStruct, *XmDragMotionCallback;
reason Indicates why the callback was invoked.
event Points to the XEvent that triggered the callback.
timeStamp Specifies the timestamp of the logical event.
operation Identifies an operation.
If the toolkit has just called a DropSite's XmNdragProc, the
toolkit initializes operation to the value of the operation
member of the XmDragProcCallbackStruct at the time the Drop-
Site's XmNdragProc returns.
If the toolkit has not called an XmNdragProc and the pointer
is within an active drop site, the toolkit initializes opera-
tion 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.
If the toolkit has not called an XmNdragProc and the pointer
is not within an active drop site, the toolkit initializes
operation by selecting an operation from the initial value of
the operations member. 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.
operations
Indicates the set of operations supported for the source
data.
If the toolkit has just called a DropSite's XmNdragProc, the
toolkit initializes operations to the bitwise AND of the
DropSite's XmNdropOperations and the value of the operations
member of the XmDragProcCallbackStruct at the time the Drop-
Site's XmNdragProc returns. If the resulting set of opera-
tions is empty, the toolkit initializes operations to
XmDROP_NOOP.
If the toolkit has not called an XmNdragProc and the user
does not select an operation (by pressing a modifier key),
the toolkit initializes operations to the value of the Drag-
Context's XmNdragOperations resource.
If the toolkit has not called an XmNdragProc and 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.
dropSiteStatus
Indicates whether or not a drop site is valid.
If the toolkit has just called a DropSite's XmNdragProc, the
toolkit initializes dropSiteStatus to the value of the drop-
SiteStatus member of the XmDragProcCallbackStruct at the time
the DropSite's XmNdragProc returns.
If the toolkit has not called an XmNdragProc, it initializes
dropSiteStatus as follows: the toolkit initializes dropSiteS-
tatus to XmNO_DROP_SITE if the pointer is over an inactive
drop site or is not over a drop site. The toolkit initial-
izes dropSiteStatus to XmDROP_SITE_VALID if all the following
conditions are met:
o The pointer is over an active drop site.
o The DragContext's XmNexportTargets and the DropSite's
XmNimportTargets are compatible.
o The initial value of the operation member is not
XmDROP_NOOP.
Otherwise, the toolkit initializes dropSiteStatus to
XmDROP_SITE_INVALID.
A pointer to the following structure is passed for the XmNdropFinish-
Callback callback:
typedef struct
{
int reason;
XEvent *event;
Time timeStamp;
unsigned char operation;
unsigned char operations;
unsigned char dropSiteStatus;
unsigned char dropAction;
unsigned char completionStatus;
}XmDropFinishCallbackStruct, *XmDropFinishCallback;
reason Indicates why the callback was invoked.
event Points to the XEvent that triggered the callback.
timeStamp Specifies the time at which the drop was completed.
operation Identifies an operation.
If the pointer is over an active drop site when the drop
begins, the toolkit initializes operation to the value of the
operation member of the XmDropProcCallbackStruct at the time
the DropSite's XmNdropProc returns.
If the pointer is not over an active drop site when the drop
begins, the toolkit initializes operation by selecting an
operation from the initial value of the operations member.
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.
operations
Indicates the set of operations supported for the source
data.
If the pointer is over an active drop site when the drop
begins, the toolkit initializes operations to the bitwise AND
of the DropSite's XmNdropOperations and the value of the
operations member of the XmDropProcCallbackStruct at the time
the DropSite's XmNdropProc returns. If the resulting set of
operations is empty, the toolkit initializes operations to
XmDROP_NOOP.
If the pointer is not over an active drop site when the drop
begins and 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 pointer is not over an active drop site when the drop
begins and if the user does select an operation, the toolkit
initializes operations to the bitwise AND of the correspond-
ing operation and the value of the DragContext's XmNdragOper-
ations resource. If the resulting set of operations is
empty, the toolkit initializes operations to XmDROP_NOOP.
dropSiteStatus
Indicates whether or not a drop site is valid.
If the pointer is over an active drop site when the drop
begins, the toolkit initializes dropSiteStatus to the value
of the dropSiteStatus member of the XmDropProcCallbackStruct
at the time the DropSite's XmNdropProc returns.
If the pointer is not over an active drop site when the drop
begins, the toolkit initializes dropSiteStatus to
XmNO_DROP_SITE.
dropAction
Identifies the drop action. The values are XmDROP,
XmDROP_CANCEL, XmDROP_HELP, and XmDROP_INTERRUPT. The
XmDROP_INTERRUPT value is currently unsupported; if speci-
fied, it will be interpreted as an XmDROP_CANCEL.
completionStatus
An IN/OUT member that indicates the status of the drop
action. After the last callback procedure has returned, the
final value of this member determines what visual transition
effects will be applied. There are two values:
XmDROP_SUCCESS
The drop was successful.
XmDROP_FAILURE
The drop was unsuccessful.
A pointer to the following structure is passed to callbacks for XmN-
dropSiteEnterCallback:
typedef struct
{
int reason;
XEvent *event;
Time timeStamp;
unsigned char operation;
unsigned char operations;
unsigned char dropSiteStatus;
Position x;
Position y;
}XmDropSiteEnterCallbackStruct, *XmDropSiteEnterCallback;
reason Indicates why the callback was invoked.
event Points to the XEvent that triggered the callback.
timeStamp Specifies the time the crossing event occurred.
operation Identifies an operation.
If the toolkit has just called a DropSite's XmNdragProc, the
toolkit initializes operation to the value of the operation
member of the XmDragProcCallbackStruct at the time the Drop-
Site's XmNdragProc returns.
If the toolkit has not called an XmNdragProc, it 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.
operations
Indicates the set of operations supported for the source
data.
If the toolkit has just called a DropSite's XmNdragProc, the
toolkit initializes operations to the bitwise AND of the
DropSite's XmNdropOperations and the value of the operations
member of the XmDragProcCallbackStruct at the time the Drop-
Site's XmNdragProc returns. If the resulting set of opera-
tions is empty, the toolkit initializes operations to
XmDROP_NOOP.
If the toolkit has not called an XmNdragProc and the user
does not select an operation (by pressing a modifier key),
the toolkit initializes operations to the value of the Drag-
Context's XmNdragOperations resource.
If the toolkit has not called an XmNdragProc and 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.
dropSiteStatus
Indicates whether or not a drop site is valid.
If the toolkit has just called a DropSite's XmNdragProc, the
toolkit initializes dropSiteStatus to the value of the drop-
SiteStatus member of the XmDragProcCallbackStruct at the time
the DropSite's XmNdragProc returns.
If the toolkit has not called XmNdragProc, it initializes
dropSiteStatus to XmDROP_SITE_VALID if the DragContext's XmN-
exportTargets and the DropSite's XmNimportTargets are compat-
ible and if the initial value of the operation member is not
XmDROP_NOOP. Otherwise, the toolkit initializes dropSiteSta-
tus to XmDROP_SITE_INVALID.
x Indicates the x-coordinate of the pointer in root window
coordinates.
y Indicates the y-coordinate of the pointer in root window
coordinates.
A pointer to the following structure is passed to callbacks for XmN-
dropSiteLeaveCallback:
typedef struct
{
int reason;
XEvent *event;
Time timeStamp;
}XmDropSiteLeaveCallbackStruct, *XmDropSiteLeaveCallback;
reason Indicates why the callback was invoked
event Points to the XEvent that triggered the callback
timeStamp Specifies the timestamp of the logical event
A pointer to the following structure is passed for the XmNdropStart-
Callback callback:
typedef struct
{
int reason;
XEvent *event;
Time timeStamp;
unsigned char operation;
unsigned char operations;
unsigned char dropSiteStatus;
unsigned char dropAction;
Position x;
Position y;
}XmDropStartCallbackStruct, *XmDropStartCallback;
reason Indicates why the callback was invoked.
event Points to the XEvent that triggered the callback.
timeStamp Specifies the time at which the drag was completed.
operation Identifies an operation.
If the pointer is over an active drop site when the drop
begins, the toolkit initializes operation to the value of the
operation member of the XmDropProcCallbackStruct at the time
the DropSite's XmNdropProc returns.
If the pointer is not over an active drop site when the drop
begins, the toolkit initializes operation by selecting an
operation from the initial value of the operations member.
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.
operations
Indicates the set of operations supported for the source
data.
If the pointer is over an active drop site when the drop
begins, the toolkit initializes operations to the bitwise AND
of the DropSite's XmNdropOperations and the value of the
operations member of the XmDropProcCallbackStruct at the time
the DropSite's XmNdropProc returns. If the resulting set of
operations is empty, the toolkit initializes operations to
XmDROP_NOOP.
If the pointer is not over an active drop site when the drop
begins and 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 pointer is not over an active drop site when the drop
begins and if the user does select an operation, the toolkit
initializes operations to the bitwise AND of the correspond-
ing operation and the value of the DragContext's XmNdragOper-
ations resource. If the resulting set of operations is
empty, the toolkit initializes operations to XmDROP_NOOP.
dropSiteStatus
Indicates whether or not a drop site is valid.
If the pointer is over an active drop site when the drop
begins, the toolkit initializes dropSiteStatus to the value
of the dropSiteStatus member of the XmDropProcCallbackStruct
at the time the DropSite's XmNdropProc returns.
If the pointer is not over an active drop site when the drop
begins, the toolkit initializes dropSiteStatus to
XmNO_DROP_SITE.
This field is invalid if the dropAction field is set to
XmDROP_CANCEL.
dropAction
An IN/OUT member that identifies the drop action. The values
are XmDROP, XmDROP_CANCEL, XmDROP_HELP, and XmDROP_INTERRUPT.
The value of dropAction can be modified to change the action
actually initiated. The value XmDROP_INTERRUPT is currently
unsupported; if specified, it will be interpreted as an
XmDROP_CANCEL.
x Indicates the x-coordinate of the pointer in root window
coordinates.
y Indicates the y-coordinate of the pointer in root window
coordinates.
A pointer to the following structure is passed to the XmNopera-
tionChangedCallback callback:
typedef struct
{
int reason;
XEvent *event;
Time timeStamp;
unsigned char operation;
unsigned char operations;
unsigned char dropSiteStatus;
}XmOperationChangedCallbackStruct, *XmOperationChangedCallback;
reason Indicates why the callback was invoked.
event Points to the XEvent that triggered the callback.
timeStamp Specifies the time at which the crossing event occurred.
operation Identifies an operation.
If the toolkit has just called a DropSite's XmNdragProc, the
toolkit initializes operation to the value of the operation
member of the XmDragProcCallbackStruct at the time the Drop-
Site's XmNdragProc returns.
If the toolkit has not called an XmNdragProc, and the pointer
is within an active drop site, the toolkit initializes opera-
tion 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.
If the toolkit has not called an XmNdragProc, and the pointer
is not within an active drop site, the toolkit initializes
operation by selecting an operation from the initial value of
the operations member. 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.
operations
Indicates the set of operations supported for the source
data.
If the toolkit has just called a DropSite's XmNdragProc, the
toolkit initializes operations to the bitwise AND of the
DropSite's XmNdropOperations and the value of the operations
member of the XmDragProcCallbackStruct at the time the Drop-
Site's XmNdragProc returns. If the resulting set of opera-
tions is empty, the toolkit initializes operations to
XmDROP_NOOP.
If the toolkit has not called an XmNdragProc, and the user
does not select an operation (by pressing a modifier key),
the toolkit initializes operations to the value of the Drag-
Context's XmNdragOperations resource.
If the toolkit has not called an XmNdragProc, and 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.
dropSiteStatus
Indicates whether or not a drop site is valid.
If the toolkit has just called a DropSite's XmNdragProc, the
toolkit initializes dropSiteStatus to the value of the drop-
SiteStatus member of the XmDragProcCallbackStruct at the time
the DropSite's XmNdragProc returns.
If the toolkit has not called an XmNdragProc it initializes
dropSiteStatus to XmNO_DROP_SITE if the pointer is over an
inactive drop site or is not over a drop site. The toolkit
initializes dropSiteStatus to XmDROP_SITE_VALID if all the
following conditions are met:
o The pointer is over an active drop site
o The DragContext's XmNexportTargets and the DropSite's
XmNimportTargets are compatible
o The initial value of the operation member is not
XmDROP_NOOP
Otherwise, the toolkit initializes dropSiteStatus to
XmDROP_SITE_INVALID.
A pointer to the following structure is passed to callbacks for XmNto-
pLevelEnterCallback:
typedef struct
{
int reason;
XEvent *event;
Time timeStamp;
Screen screen;
Window window;
Position x;
Position y;
unsigned char dragProtocolStyle;
}XmTopLevelEnterCallbackStruct, *XmTopLevelEnterCallback;
reason Indicates why the callback was invoked.
event Points to the XEvent that triggered the callback.
timeStamp Specifies the timestamp of the logical event.
screen Specifies the screen associated with the top-level window or
root window being entered.
window Specifies the ID of the top-level window or root window being
entered.
x Indicates the x-coordinate of the pointer in root window
coordinates.
y Indicates the y-coordinate of the pointer in root window
coordinates.
dragProtocolStyle
Specifies the protocol style adopted by the initiator. The
values are XmDRAG_DROP_ONLY, XmDRAG_DYNAMIC, XmDRAG_NONE, and
XmDRAG_PREREGISTER.
A pointer to the following structure is passed to callbacks for XmNto-
pLevelLeaveCallback:
typedef struct
{
int reason;
XEvent *event;
Time timeStamp;
Screen screen;
Window window;
}XmTopLevelLeaveCallbackStruct, *XmTopLevelLeaveCallback;
reason Indicates why the callback was invoked
event Points to the XEvent that triggered the callback
timeStamp Specifies the timestamp of the logical event
screen Specifies a screen associated with the top-level window or
root window being left
window Specifies the ID of the top-level window or root window being
left
Translations
The XmDragContext translations are described in the following list.
The following key names are listed in the X standard key event transla-
tion table syntax. This format is the one used by Motif to specify the
widget actions corresponding to a given key. A brief overview of the
format is provided under VirtualBindings(3). For a complete descrip-
tion of the format, please refer to the X Toolkit Instrinsics Documen-
tation.
Button1<Enter>:
DragMotion()
Button1<Leave>:
DragMotion()
Button1<Motion>:
DragMotion()
Button2<Enter>:
DragMotion()
Button2<Leave>:
DragMotion()
Button2<Motion>:
DragMotion()
<Btn2Up>: FinishDrag()
<Btn1Up>: FinishDrag()
<Key>Return:
FinishDrag()
<Key><osfActivate>:
FinishDrag()
<BtnDown>:
IgnoreButtons()
<BtnUp>: IgnoreButtons()
:<Key><osfCancel>:
CancelDrag()
:<Key><osfHelp>:
HelpDrag()
:<Key><osfUp>:
DragKey(Up)
:<Key><osfDown>:
DragKey(Down)
:<Key><osfLeft>:
DragKey(Left)
:<Key><osfRight>:
DragKey(Right)
:<KeyUp>: DragKey(Update)
:<KeyDown>:
DragKey(Update)
Action Routines
The XmDragContext action routines are
CancelDrag():
Cancels the drag operation and frees the associated DragCon-
text.
DragKey(String)
If the value of String is Left, Right, Up, or Down, this
action moves the dragged object in the corresponding loca-
tion. Any other values of String are ignored.
DragMotion():
Drags the selected data as the pointer is moved.
FinishDrag():
Finishes the drag operation and starts the drop operation.
HelpDrag():
Initiates a conditional drop that enables the receiver to
provide help information to the user. The user can cancel or
continue the drop operation in response to this information.
Virtual Bindings
The bindings for virtual keys are vendor specific. For information
about bindings for virtual buttons and keys, see VirtualBindings(3).
RELATED INFORMATION
Core(3), XmDisplay(3), XmDragCancel(3), XmDragIcon(3), XmDragStart(3),
XmDropSite(3), XmDropTransfer(3), and XmScreen(3).
XmDragContext(library call)
openMotif 2.3.1 - Generated Sun Nov 30 12:09:47 CST 2008