XmDragContext(3X) UNIX System V XmDragContext(3X)
NAME
XmDragContext - The DragContext widget class
SYNOPSIS
#include <Xm/DragDrop.h>
VERSION
This page documents version 1.2 of the Motif library.
DESCRIPTION
DragContexts are special widgets used in drag and drop
transactions. A DragContext is implemented as a widget, but
a client does not explicitly create a DragContext widget.
Instead, a client initiates a drag and drop transaction by
calling XmDragStart, and this routine initializes and
returns a DragContext widget. There is a unique DragContext
for each drag operation. The toolkit frees a DragContext
when a transaction 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
DragContext 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 DragContext resource, XmNexportTargets,
identifies the selection targets for the drag source. These
export targets are compared with the XmNimportTargets
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 counterpart 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 initiator 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
Page 1 (printed 4/30/98)
XmDragContext(3X) UNIX System V XmDragContext(3X)
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 XmNdragInitiatorProtocolStyle is
XmDRAGDYNAMIC or XmDRAGPREFERDYNAMIC, 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 programmer to specify data. The programmer can also
set the resource values 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
Page 2 (printed 4/30/98)
XmDragContext(3X) UNIX System V XmDragContext(3X)
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 produce a drag-over visual.
XmBLENDALL
Blends all three DragIcons - the source,
state and operation icon. 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.
XmBLENDSTATESOURCE
Blends the state and source icons only.
The hotspot is derived from the state
icon.
XmBLENDJUSTSOURCE
Specifies that only the source icon is
used, which the initiator updates as
required.
XmBLENDNONE
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 the
XmNconvertProc when it is invoked.
XmNconvertProc
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
Page 3 (printed 4/30/98)
XmDragContext(3X) UNIX System V XmDragContext(3X)
XmNincremental is False, the procedure 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 XmDragDropFinishCallbackStruct. The
reason sent by the callback is
XmCRDRAGDROPFINISH.
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 XmCRDRAGMOTION.
XmNdragOperations
Specifies the set of valid operations associated
with an initiator 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
(|): XmDROPCOPY, XmDROPLINK, XmDROPMOVE. The
value XmDROPNOOP for this resource indicates that
no operations are valid. For Text and TextField
widgets, this resource is set to XmDROPCOPY |
XmDROPMOVE; for List widgets, it is set to
XmDROPCOPY.
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
Page 4 (printed 4/30/98)
XmDragContext(3X) UNIX System V XmDragContext(3X)
is XmDropFinishCallbackStruct. The reason sent
by the callback is XmCRDROPFINISH.
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 XmDropSiteEnterCallbackStruct. The
reason sent by the callback is
XmCRDROPSITEENTER.
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 XmDropSiteLeaveCallbackStruct. The
reason sent by the callback is
XmCRDROPSITELEAVE.
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 XmCRDROPSTART.
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 Language 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
Page 5 (printed 4/30/98)
XmDragContext(3X) UNIX System V XmDragContext(3X)
export targets.
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
XmOperationChangedCallbackStruct. The reason sent
by the callback is XmCROPERATIONCHANGED.
XmNoperationCursorIcon
Specifies the cursor icon used to designate the
type of operation 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 XmNdefaultSourceCursorIcon 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 conjunction 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 XmCRTOPLEVELENTER.
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
XmCRTOPLEVELLEAVE.
Page 6 (printed 4/30/98)
XmDragContext(3X) UNIX System V XmDragContext(3X)
XmNvalidCursorForeground
Specifies the foreground pixel value of the cursor
designated as a valid cursor icon.
Inherited Resources
DragContext inherits behavior and resources from the
following superclass. For a complete description of each
resource, refer to the Core man 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
XmNdragDropFinishCallback 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.
Page 7 (printed 4/30/98)
XmDragContext(3X) UNIX System V XmDragContext(3X)
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 XmNdragMotionCallback.
typedef struct
{
int reason;
XEvent *event;
Time timeStamp;
unsigned charoperation;
unsigned charoperations;
unsigned chardropSiteStatus;
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
DropSite's XmNdragProc returns.
If the toolkit has not called an XmNdragProc and
the pointer is within an active drop site, 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
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.
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
Page 8 (printed 4/30/98)
XmDragContext(3X) UNIX System V XmDragContext(3X)
operations member. 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.
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
DropSite's XmNdragProc returns. If the
resulting set of operations is empty, the
toolkit initializes operations to XmDROPNOOP.
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
DragContext'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 initializes operations to XmDROPNOOP.
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
dropSiteStatus 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 dropSiteStatus to
XmNODROPSITE if the pointer is over an
inactive drop site or is not over a drop site.
The toolkit initializes dropSiteStatus to
XmDROPSITEVALID if all the following
Page 9 (printed 4/30/98)
XmDragContext(3X) UNIX System V XmDragContext(3X)
conditions are met:
⊕ The pointer is over an active drop site.
⊕ The DragContext's XmNexportTargets and the
DropSite's XmNimportTargets are compatible.
⊕ The initial value of the operation member
is not XmDROPNOOP.
Otherwise, the toolkit initializes
dropSiteStatus to XmDROPSITEINVALID.
A pointer to the following structure is passed for the
XmNdropFinishCallback callback:
typedef struct
{
int reason;
XEvent *event;
Time timeStamp;
unsigned charoperation;
unsigned charoperations;
unsigned chardropSiteStatus;
unsigned chardropAction;
unsigned charcompletionStatus;
}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 XmDROPMOVE,
Page 10 (printed 4/30/98)
XmDragContext(3X) UNIX System V XmDragContext(3X)
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.
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 XmDROPNOOP.
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 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.
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 XmNODROPSITE.
dropAction Identifies the drop action. The values are:
XmDROP, XmDROPCANCEL, XmDROPHELP, and
XmDROPINTERRUPT. The value XmDROPINTERRUPT is
Page 11 (printed 4/30/98)
XmDragContext(3X) UNIX System V XmDragContext(3X)
currently unsupported; if specified, it will be
interpreted as an XmDROPCANCEL.
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:
XmDROPSUCCESS
The drop was successful.
XmDROPFAILURE
The drop was unsuccessful.
A pointer to the following structure is passed to callbacks
for XmNdropSiteEnterCallback:
typedef struct
{
int reason;
XEvent *event;
Time timeStamp;
unsigned charoperation;
unsigned charoperations;
unsigned chardropSiteStatus;
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
DropSite'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
Page 12 (printed 4/30/98)
XmDragContext(3X) UNIX System V XmDragContext(3X)
operations member and the value of 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.
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
DropSite's XmNdragProc returns. If the
resulting set of operations is empty, the
toolkit initializes operations to XmDROPNOOP.
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
DragContext'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 initializes operations to XmDROPNOOP.
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
dropSiteStatus 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 dropSiteStatus to
XmDROPSITEVALID if the DragContext's
XmNexportTargets and the DropSite's
XmNimportTargets are compatible and if the
Page 13 (printed 4/30/98)
XmDragContext(3X) UNIX System V XmDragContext(3X)
initial value of the operation member is not
XmDROPNOOP. Otherwise, the toolkit initializes
dropSiteStatus to XmDROPSITEINVALID.
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 XmNdropSiteLeaveCallback.
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
XmNdropStartCallback callback:
typedef struct
{
int reason;
XEvent *event;
Time timeStamp;
unsigned charoperation;
unsigned charoperations;
unsigned chardropSiteStatus;
unsigned chardropAction;
Position x;
Position y;
}XmDropStartCallbackStruct, *XmDropStartCallback;
reason Indicates why the callback was invoked.
event Points to the XEvent that triggered the
callback.
Page 14 (printed 4/30/98)
XmDragContext(3X) UNIX System V XmDragContext(3X)
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 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.
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 XmDROPNOOP.
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 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.
dropSiteStatus
Page 15 (printed 4/30/98)
XmDragContext(3X) UNIX System V XmDragContext(3X)
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 XmNODROPSITE.
dropAction An IN/OUT member that identifies the drop
action. The values are XmDROP, XmDROPCANCEL,
XmDROPHELP, and XmDROPINTERRUPT. The value of
dropAction can be modified to change the action
actually initiated. The value XmDROPINTERRUPT
is currently unsupported; if specified, it will
be interpreted as a XmDROPCANCEL.
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
XmNoperationChangedCallback callback:
typedef struct
{
int reason;
XEvent *event;
Time timeStamp;
unsigned charoperation;
unsigned charoperations;
unsigned chardropSiteStatus;
}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.
Page 16 (printed 4/30/98)
XmDragContext(3X) UNIX System V XmDragContext(3X)
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
DropSite's XmNdragProc returns.
If the toolkit has not called an XmNdragProc and
the pointer is within an active drop site, 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
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.
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 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.
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
DropSite's XmNdragProc returns. If the
resulting set of operations is empty, the
toolkit initializes operations to XmDROPNOOP.
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
DragContext's XmNdragOperations resource.
If the toolkit has not called an XmNdragProc and
the user does select an operation, the toolkit
Page 17 (printed 4/30/98)
XmDragContext(3X) UNIX System V XmDragContext(3X)
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.
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
dropSiteStatus 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 dropSiteStatus to
XmNODROPSITE if the pointer is over an
inactive drop site or is not over a drop site.
The toolkit initializes dropSiteStatus to
XmDROPSITEVALID if all the following
conditions are met:
⊕ The pointer is over an active drop site
⊕ The DragContext's XmNexportTargets and the
DropSite's XmNimportTargets are compatible
⊕ The initial value of the operation member
is not XmDROPNOOP
Otherwise, the toolkit initializes
dropSiteStatus to XmDROPSITEINVALID.
A pointer to the following structure is passed to callbacks
for XmNtopLevelEnterCallback:
typedef struct
{
int reason;
XEvent *event;
Time timestamp;
Screen screen;
Window window;
Position x;
Position y;
unsigned chardragProtocolStyle;
}XmTopLevelEnterCallbackStruct, *XmTopLevelEnterCallback;
Page 18 (printed 4/30/98)
XmDragContext(3X) UNIX System V XmDragContext(3X)
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 XmDRAGDROPONLY,
XmDRAGDYNAMIC, XmDRAGNONE, and
XmDRAGPREREGISTER.
A pointer to the following structure is passed to callbacks
for XmNtopLevelLeaveCallback:
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.
Page 19 (printed 4/30/98)
XmDragContext(3X) UNIX System V XmDragContext(3X)
Translations
The XmDragContext translations are listed below. These
translations may not directly correspond to a translation
table.
BDrag Motion: DragMotion()
BDrag Release: FinishDrag()
KCancel: CancelDrag()
KHelp: HelpDrag()
Action Routines
The XmDragContext action routines are described below:
CancelDrag():
Cancels the drag operation and frees the
associated DragContext.
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(3X).
RELATED INFORMATION
Core(3X), XmDisplay(3X), XmDragCancel(3X), XmDragIcon(3X),
XmDragStart(3X), XmDropSite(3X), XmDropTransfer(3X), and
XmScreen(3X).
Page 20 (printed 4/30/98)