'\" t

...\" DragCont.sgm /main/12 1996/09/08 20:39:46 rws $

.de P!

.fl

\!!1 setgray

.fl

\\&.\"

.fl

\!!0 setgray

.fl			\" force out current output buffer

\!!save /psv exch def currentpoint translate 0 0 moveto

\!!/showpage{}def

.fl			\" prolog

.sy sed -e 's/^/!/' \\$1\" bring in postscript file

\!!psv restore

.

.de pF

.ie     ?\\*(f1?? .ds f1 \\n(.f

.el .ie ?\\*(f2?? .ds f2 \\n(.f

.el .ie ?\\*(f3?? .ds f3 \\n(.f

.el .ie ?\\*(f4?? .ds f4 \\n(.f

.el .tm ? font overflow

.ft \\$1

..

.de fP

.ie     !?\\*(f4?? \{\

.	ft \\*(f4

.	ds f4\"

'	br \}

.el .ie !?\\*(f3?? \{\

.	ft \\*(f3

.	ds f3\"

'	br \}

.el .ie !?\\*(f2?? \{\

.	ft \\*(f2

.	ds f2\"

'	br \}

.el .ie !?\\*(f1?? \{\

.	ft \\*(f1

.	ds f1\"

'	br \}

.el .tm ? font underflow

..

.ds f1\"

.ds f2\"

.ds f3\"

.ds f4\"

.ta 8n 16n 24n 32n 40n 48n 56n 64n 72n 

.TH "XmDragContext" "library call"

.SH "NAME"

\fBXmDragContext\fP \(em The DragContext widget class

.iX "XmDragContext"

.iX "widget class" "DragContext"

.SH "SYNOPSIS"

.PP

.nf

#include <Xm/DragDrop\&.h>

.fi

.SH "DESCRIPTION"

.PP

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 \fBXmDragStart\fP, 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\&.

.PP

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

\fBXmDragStart\fP and the toolkit provides a DragContext for the

receiver client\&. The only resources pertinent to the receiver

are \fBXmNexportTargets\fP and \fBXmNnumExportTargets\fP\&. These

can both be passed as arguments to the \fBXmDropSiteRetrieve\fP

function to obtain information about the current drop site\&.

.PP

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, \fBXmNexportTargets\fP, identifies the selection

targets for the drag source\&. These export targets are compared with the

\fBXmNimportTargets\fP resource list specified by a drop site\&.

The DragContext resource, \fBXmNdragOperations\fP, identifies the

valid operations that can be applied to the source data by the

initiator\&. The drop site counterpart resource is

\fBXmNdropSiteOperations\fP, which indicates a drop site\&'s supported

operations\&.

.PP

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\&.

.PP

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 \fBXmNdragInitiatorProtocolStyle\fP is

\fBXmDRAG_DYNAMIC\fP or \fBXmDRAG_PREFER_DYNAMIC\fP,

then a dynamic visual style (cursor) is used\&. Otherwise, a preregister

visual style is used\&.

.SS "Classes"

.PP

DragContext inherits behavior and resources from \fBCore\fP\&.

.PP

The class pointer is \fBxmDragContextClass\fP\&.

.PP

The class name is \fBXmDragContext\fP\&.

.SS "New Resources"

.PP

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 \fB\&.Xdefaults\fP file, remove the \fBXmN\fP or \fBXmC\fP prefix and use

the remaining letters\&. To specify one of the defined values for a

resource in a \fB\&.Xdefaults\fP file, remove the \fBXm\fP 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)\&.

.PP

.TS

tab(?) box;

c s s s s

l| l| l| l| l.

\fBXmDragContext Resource Set\fP

\fBName\fP?\fBClass\fP?\fBType\fP?\fBDefault\fP?\fBAccess\fP

_?_?_?_?_?

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

_?_?_?_?_?

.TE

.IP "\fBXmNblendModel\fP" 10

Specifies which combination of DragIcons are blended to produce

a drag-over visual\&.

.RS

.IP "\fBXmBLEND_ALL\fP" 10

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\&.

.IP "\fBXmBLEND_STATE_SOURCE\fP" 10

Blends the state and source icons only\&. The hotspot is derived

from the state icon\&.

.IP "\fBXmBLEND_JUST_SOURCE\fP" 10

Specifies that only the source icon is used, which the initiator

updates as required\&.

.IP "\fBXmBLEND_NONE\fP" 10

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\&.

.RE

.IP "\fBXmNclientData\fP" 10

Specifies the client data to be passed to \fBXmNconvertProc\fP

when it is invoked\&.

.IP "\fBXmNconvertProc\fP" 10

If \fBXmNincremental\fP is True, specifies a procedure of type

\fBXtConvertSelectionIncrProc\fP that

converts the source data to the format(s) requested by the receiver

client\&.

The \fIwidget\fP argument passed to this procedure is the DragContext

widget\&.

The selection atom passed is _MOTIF_DROP\&.

If \fBXmNincremental\fP is False, the procedure is an

\fBXtConvertSelectionProc\fP, and should ignore the

\fImax_length\fP, \fIclient_data\fP, and \fIrequest_id\fP arguments and

should handle the conversion atomically\&.

Data returned by \fBXmNconvertProc\fP must be allocated using

\fBXtMalloc\fP, and will be freed automatically by the toolkit after the

transfer\&.

For additional information on selection conversion procedures, see \fIX

Toolkit Intrinsics\(emC Language Interface\fP\&.

.IP "\fBXmNcursorBackground\fP" 10

Specifies the background pixel value of the cursor\&.

.IP "\fBXmNcursorForeground\fP" 10

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 \fBXmDragStart\fP function\&.

.IP "\fBXmNdragDropFinishCallback\fP" 10

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 \fBXmDragDropFinishCallbackStruct\fR\&. The reason sent by

the callback is \fBXmCR_DRAG_DROP_FINISH\fP\&.

.IP "\fBXmNdragMotionCallback\fP" 10

Specifies the list of callbacks that are invoked when the pointer moves\&.

The type of structure whose address is passed to this callback is

\fBXmDragMotionCallbackStruct\fR\&. The reason sent by the callback

is \fBXmCR_DRAG_MOTION\fP\&.

.IP "\fBXmNdragOperations\fP" 10

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 (|):

\fBXmDROP_COPY\fP, \fBXmDROP_LINK\fP, \fBXmDROP_MOVE\fP\&.

The value \fBXmDROP_NOOP\fP for this resource indicates that no

operations are valid\&.

For Text and TextField widgets, this resource is set to

\fBXmDROP_COPY\fP | \fBXmDROP_MOVE\fP; for List widgets, it is set to

\fBXmDROP_COPY\fP\&.

.IP "\fBXmNdropFinishCallback\fP" 10

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 \fBXmDropFinishCallbackStruct\fR\&. The reason sent

by the callback is \fBXmCR_DROP_FINISH\fP\&.

.IP "\fBXmNdropSiteEnterCallback\fP" 10

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 \fBXmDropSiteEnterCallbackStruct\fR\&. The reason sent by the

callback is \fBXmCR_DROP_SITE_ENTER\fP\&.

.IP "\fBXmNdropSiteLeaveCallback\fP" 10

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 \fBXmDropSiteLeaveCallbackStruct\fR\&. The reason sent by

the callback is \fBXmCR_DROP_SITE_LEAVE\fP\&.

.IP "\fBXmNdropStartCallback\fP" 10

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 \fBXmDropStartCallbackStruct\fR\&. The reason sent by the

callback is \fBXmCR_DROP_START\fP\&.

.IP "\fBXmNexportTargets\fP" 10

Specifies the list of target atoms associated with this source\&.

This resource identifies the selection targets this source

can be converted to\&.

.IP "\fBXmNincremental\fP" 10

Specifies a Boolean value that indicates whether the transfer on the

initiator side uses the Xt incremental selection transfer mechanism

described in \fIX Toolkit Intrinsics\(emC Language Interface\fP\&.

If the value is True, the initiator uses incremental transfer; if the

value is False, the initiator uses atomic transfer\&.

.IP "\fBXmNinvalidCursorForeground\fP" 10

Specifies the foreground pixel value of the cursor when the state

is invalid\&. This resource defaults to the value of the

\fBXmNcursorForeground\fP resource\&.

.IP "\fBXmNnoneCursorForeground\fP" 10

Specifies the foreground pixel value of the cursor when the state

is none\&. This resource defaults to the value of the

\fBXmNcursorForeground\fP resource\&.

.IP "\fBXmNnumExportTargets\fP" 10

Specifies the number of entries in the list of export targets\&.

.IP "\fBXmNoperationChangedCallback\fP" 10

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 \fBXmOperationChangedCallbackStruct\fR\&. The reason sent by the

callback is \fBXmCR_OPERATION_CHANGED\fP\&.

.IP "\fBXmNoperationCursorIcon\fP" 10

Specifies the cursor icon used to designate the type of operation

performed by the drag transaction\&. If NULL, \fBXmScreen\fP

resources provide default icons for copy, link, and move

operations\&.

.IP "\fBXmNsourceCursorIcon\fP" 10

Specifies the cursor icon used to represent the source when

a dynamic visual style is used\&. If NULL, the

\fBXmNdefaultSourceCursorIcon\fP resource of \fBXmScreen\fP provides

a default cursor icon\&.

.IP "\fBXmNsourcePixmapIcon\fP" 10

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 \fBXmDragStart\fP\&.

If NULL, \fBXmNsourceCursorIcon\fP is used\&.

.IP "\fBXmNstateCursorIcon\fP" 10

Specifies the cursor icon used to designate the state of a drop site\&.

If NULL, \fBXmScreen\fP resources provide default icons for a valid,

invalid, and no drop site condition\&.

.IP "\fBXmNtopLevelEnterCallback\fP" 10

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

\fBXmTopLevelEnterCallbackStruct\fR\&. The reason sent by the

callback is \fBXmCR_TOP_LEVEL_ENTER\fP\&.

.IP "\fBXmNtopLevelLeaveCallback\fP" 10

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 \fBXmTopLevelLeaveCallbackStruct\fR\&. The

reason sent by the callback is \fBXmCR_TOP_LEVEL_LEAVE\fP\&.

.IP "\fBXmNvalidCursorForeground\fP" 10

Specifies the foreground pixel value of the cursor designated as a

valid cursor icon\&.

.SS "Inherited Resources"

.PP

DragContext inherits behavior and resources from the superclass

described in the following table\&.

For a complete description of each resource, refer

to the \fBCore\fP reference page\&.

.PP

.TS

tab(?) box;

c s s s s

l| l| l| l| l.

\fBCore Resource Set\fP

\fBName\fP?\fBClass\fP?\fBType\fP?\fBDefault\fP?\fBAccess\fP

_?_?_?_?_?

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

_?_?_?_?_?

.TE

.SS "Callback Information"

.PP

Each of the DragContext callbacks has an associated callback

structure\&.

.PP

A pointer to the following structure is passed to the

\fBXmNdragDropFinishCallback\fP callback:

.PP

.nf

typedef struct

{

        int \fIreason\fP;

        XEvent  *\fIevent\fP;

        Time \fItimeStamp\fP;

}XmDragDropFinishCallbackStruct, *XmDragDropFinishCallback;

.fi

.IP "\fIreason\fP" 10

Indicates why the callback was invoked

.IP "\fIevent\fP" 10

Points to the \fBXEvent\fP that triggered the callback

.IP "\fBtimeStamp\fP" 10

Specifies the time at which either the drag or the drop was completed

.PP

A pointer to the following structure is passed to callbacks for

\fBXmNdragMotionCallback\fP:

.PP

.nf

typedef struct

{

        int \fIreason\fP;

        XEvent *\fIevent\fP;

        Time \fItimeStamp\fP;

        unsigned char \fIoperation\fP;

        unsigned char \fIoperations\fP;

        unsigned char \fIdropSiteStatus\fP;

        Position \fIx\fP;

        Position \fIy\fP;

}XmDragMotionCallbackStruct, *XmDragMotionCallback;

.fi

.IP "\fIreason\fP" 10

Indicates why the callback was invoked\&.

.IP "\fIevent\fP" 10

Points to the \fBXEvent\fP that triggered the callback\&.

.IP "\fBtimeStamp\fP" 10

Specifies the timestamp of the logical event\&.

.IP "\fIoperation\fP" 10

Identifies an operation\&.

.IP "" 10

If the toolkit has just called a DropSite\&'s \fBXmNdragProc\fP, the

toolkit initializes \fIoperation\fP to the value of the \fIoperation\fP

member of the \fBXmDragProcCallbackStruct\fR at the time the DropSite\&'s

\fBXmNdragProc\fP returns\&.

.IP "" 10

If the toolkit has not called an \fBXmNdragProc\fP and the pointer is

within an active drop site, the toolkit initializes \fIoperation\fP by

selecting an operation from the bitwise AND of the initial value of the

\fIoperations\fP member and the value of the DropSite\&'s

\fBXmNdropSiteOperations\fP resource\&.

The toolkit searches this set first for \fBXmDROP_MOVE\fP, then for

\fBXmDROP_COPY\fP, then for \fBXmDROP_LINK\fP, and initializes

\fIoperation\fP to the first operation it finds in the set\&.

If the toolkit finds none of these operations in the set, it initializes

\fIoperation\fP to \fBXmDROP_NOOP\fP\&.

.IP "" 10

If the toolkit has not called an \fBXmNdragProc\fP and the pointer is

not within an active drop site, the toolkit initializes \fIoperation\fP

by selecting an operation from the initial value of the \fIoperations\fP

member\&.

The toolkit searches this set first for \fBXmDROP_MOVE\fP, then for

\fBXmDROP_COPY\fP, then for \fBXmDROP_LINK\fP, and initializes

\fIoperation\fP to the first operation it finds in the set\&.

If the toolkit finds none of these operations in the set, it initializes

\fIoperation\fP to \fBXmDROP_NOOP\fP\&.

.IP "\fIoperations\fP" 10

Indicates the set of operations supported for the source data\&.

.IP "" 10

If the toolkit has just called a DropSite\&'s \fBXmNdragProc\fP, the

toolkit initializes \fIoperations\fP to the bitwise AND of the

DropSite\&'s \fBXmNdropOperations\fP and the value of the \fIoperations\fP

member of the \fBXmDragProcCallbackStruct\fR at the time the DropSite\&'s

\fBXmNdragProc\fP returns\&.

If the resulting set of operations is empty, the toolkit initializes

\fIoperations\fP to \fBXmDROP_NOOP\fP\&.

.IP "" 10

If the toolkit has not called an \fBXmNdragProc\fP and the user does not

select an operation (by pressing a modifier key), the toolkit

initializes \fIoperations\fP to the value of the DragContext\&'s

\fBXmNdragOperations\fP resource\&.

.IP "" 10

If the toolkit has not called an \fBXmNdragProc\fP and the user does

select an operation, the toolkit initializes \fIoperations\fP to the

bitwise AND of the corresponding operation and the value of the

DragContext\&'s \fBXmNdragOperations\fP resource\&.

If the resulting set of operations is empty, the toolkit initializes

\fIoperations\fP to \fBXmDROP_NOOP\fP\&.

.IP "\fBdropSiteStatus\fP" 10

Indicates whether or not a drop site is valid\&.

.IP "" 10

If the toolkit has just called a DropSite\&'s \fBXmNdragProc\fP, the

toolkit initializes \fBdropSiteStatus\fP to the value of the

\fBdropSiteStatus\fP member of the \fBXmDragProcCallbackStruct\fR at the

time the DropSite\&'s \fBXmNdragProc\fP returns\&.

.IP "" 10

If the toolkit has not called an \fBXmNdragProc\fP, it initializes

\fBdropSiteStatus\fP as follows:

the toolkit initializes \fBdropSiteStatus\fP to \fBXmNO_DROP_SITE\fP if

the pointer is over an inactive drop site or is not over a drop site\&.

The toolkit initializes \fBdropSiteStatus\fP to \fBXmDROP_SITE_VALID\fP

if all the following conditions are met:

.RS

.IP "   \(bu" 6

The pointer is over an active drop site\&.

.IP "   \(bu" 6

The DragContext\&'s \fBXmNexportTargets\fP and the DropSite\&'s

\fBXmNimportTargets\fP are compatible\&.

.IP "   \(bu" 6

The initial value of the \fIoperation\fP member is not

\fBXmDROP_NOOP\fP\&.

.RE

.IP "" 10

Otherwise, the toolkit initializes \fBdropSiteStatus\fP to

\fBXmDROP_SITE_INVALID\fP\&.

.PP

A pointer to the following structure is passed for the

\fBXmNdropFinishCallback\fP callback:

.PP

.nf

typedef struct

{

        int \fIreason\fP;

        XEvent *\fIevent\fP;

        Time \fItimeStamp\fP;

        unsigned char \fIoperation\fP;

        unsigned char \fIoperations\fP;

        unsigned char \fIdropSiteStatus\fP;

        unsigned char \fIdropAction\fP;

        unsigned char \fIcompletionStatus\fP;

}XmDropFinishCallbackStruct, *XmDropFinishCallback;

.fi

.IP "\fIreason\fP" 10

Indicates why the callback was invoked\&.

.IP "\fIevent\fP" 10

Points to the \fBXEvent\fP that triggered the callback\&.

.IP "\fBtimeStamp\fP" 10

Specifies the time at which the drop was completed\&.

.IP "\fIoperation\fP" 10

Identifies an operation\&.

.IP "" 10

If the pointer is over an active drop site when the drop begins, the

toolkit initializes \fIoperation\fP to the value of the \fIoperation\fP

member of the \fBXmDropProcCallbackStruct\fR at the time the DropSite\&'s

\fBXmNdropProc\fP returns\&.

.IP "" 10

If the pointer is not over an active drop site when the drop begins, the

toolkit initializes \fIoperation\fP by selecting an operation from the

initial value of the \fIoperations\fP member\&.

The toolkit searches this set first for \fBXmDROP_MOVE\fP, then for

\fBXmDROP_COPY\fP, then for \fBXmDROP_LINK\fP, and initializes

\fIoperation\fP to the first operation it finds in the set\&.

If it finds none of these operations in the set, it initializes

\fIoperation\fP to \fBXmDROP_NOOP\fP\&.

.IP "\fIoperations\fP" 10

Indicates the set of operations supported for the source data\&.

.IP "" 10

If the pointer is over an active drop site when the drop begins, the

toolkit initializes \fIoperations\fP to the bitwise AND of the

DropSite\&'s \fBXmNdropOperations\fP and the value of the \fIoperations\fP

member of the \fBXmDropProcCallbackStruct\fR at the time the DropSite\&'s

\fBXmNdropProc\fP returns\&.

If the resulting set of operations is empty, the toolkit initializes

\fIoperations\fP to \fBXmDROP_NOOP\fP\&.

.IP "" 10

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 \fIoperations\fP to the value of the

DragContext\&'s \fBXmNdragOperations\fP resource\&.

.IP "" 10

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

\fIoperations\fP to the bitwise AND of the corresponding operation and

the value of the DragContext\&'s \fBXmNdragOperations\fP resource\&.

If the resulting set of operations is empty, the toolkit initializes

\fIoperations\fP to \fBXmDROP_NOOP\fP\&.

.IP "\fBdropSiteStatus\fP" 10

Indicates whether or not a drop site is valid\&.

.IP "" 10

If the pointer is over an active drop site when the drop begins, the

toolkit initializes \fBdropSiteStatus\fP to the value of the

\fBdropSiteStatus\fP member of the \fBXmDropProcCallbackStruct\fR at the

time the DropSite\&'s \fBXmNdropProc\fP returns\&.

.IP "" 10

If the pointer is not over an active drop site when the drop begins, the

toolkit initializes \fBdropSiteStatus\fP to \fBXmNO_DROP_SITE\fP\&.

.IP "\fBdropAction\fP" 10

Identifies the drop action\&. The values are \fBXmDROP\fP,

\fBXmDROP_CANCEL\fP, \fBXmDROP_HELP\fP, and \fBXmDROP_INTERRUPT\fP\&.

The \fBXmDROP_INTERRUPT\fP value is currently unsupported; if

specified, it will be interpreted as an \fBXmDROP_CANCEL\fP\&.

.IP "\fBcompletionStatus\fP" 10

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:

.RS

.IP "\fBXmDROP_SUCCESS\fP" 10

The drop was successful\&.

.IP "\fBXmDROP_FAILURE\fP" 10

The drop was unsuccessful\&.

.RE

.PP

A pointer to the following structure is passed to callbacks for

\fBXmNdropSiteEnterCallback\fP:

.PP

.nf

typedef struct

{

        int \fIreason\fP;

        XEvent *\fIevent\fP;

        Time \fItimeStamp\fP;

        unsigned char \fIoperation\fP;

        unsigned char \fIoperations\fP;

        unsigned char \fIdropSiteStatus\fP;

        Position \fIx\fP;

        Position \fIy\fP;

}XmDropSiteEnterCallbackStruct, *XmDropSiteEnterCallback;

.fi

.IP "\fIreason\fP" 10

Indicates why the callback was invoked\&.

.IP "\fIevent\fP" 10

Points to the \fBXEvent\fP that triggered the callback\&.

.IP "\fBtimeStamp\fP" 10

Specifies the time the crossing event occurred\&.

.IP "\fIoperation\fP" 10

Identifies an operation\&.

.IP "" 10

If the toolkit has just called a DropSite\&'s \fBXmNdragProc\fP, the

toolkit initializes \fIoperation\fP to the value of the \fIoperation\fP

member of the \fBXmDragProcCallbackStruct\fR at the time the DropSite\&'s

\fBXmNdragProc\fP returns\&.

.IP "" 10

If the toolkit has not called an \fBXmNdragProc\fP, it initializes

\fIoperation\fP by selecting an operation from the bitwise AND of the

initial value of the \fIoperations\fP member and the value of the

DropSite\&'s \fBXmNdropSiteOperations\fP resource\&.

The toolkit searches this set first for \fBXmDROP_MOVE\fP, then for

\fBXmDROP_COPY\fP, then for \fBXmDROP_LINK\fP, and initializes

\fIoperation\fP to the first operation it finds in the set\&.

If the toolkit finds none of these operations in the set, it initializes

\fIoperation\fP to \fBXmDROP_NOOP\fP\&.

.IP "\fIoperations\fP" 10

Indicates the set of operations supported for the source data\&.

.IP "" 10

If the toolkit has just called a DropSite\&'s \fBXmNdragProc\fP, the

toolkit initializes \fIoperations\fP to the bitwise AND of the

DropSite\&'s \fBXmNdropOperations\fP and the value of the \fIoperations\fP

member of the \fBXmDragProcCallbackStruct\fR at the time the DropSite\&'s

\fBXmNdragProc\fP returns\&.

If the resulting set of operations is empty, the toolkit initializes

\fIoperations\fP to \fBXmDROP_NOOP\fP\&.

.IP "" 10

If the toolkit has not called an \fBXmNdragProc\fP and the user does not

select an operation (by pressing a modifier key), the toolkit

initializes \fIoperations\fP to the value of the DragContext\&'s

\fBXmNdragOperations\fP resource\&.

.IP "" 10

If the toolkit has not called an \fBXmNdragProc\fP and the user does

select an operation, the toolkit initializes \fIoperations\fP to the

bitwise AND of the corresponding operation and the value of the

DragContext\&'s \fBXmNdragOperations\fP resource\&.

If the resulting set of operations is empty, the toolkit initializes

\fIoperations\fP to \fBXmDROP_NOOP\fP\&.

.IP "\fBdropSiteStatus\fP" 10

Indicates whether or not a drop site is valid\&.

.IP "" 10

If the toolkit has just called a DropSite\&'s \fBXmNdragProc\fP, the

toolkit initializes \fBdropSiteStatus\fP to the value of the

\fBdropSiteStatus\fP member of the \fBXmDragProcCallbackStruct\fR at the

time the DropSite\&'s \fBXmNdragProc\fP returns\&.

.IP "" 10

If the toolkit has not called \fBXmNdragProc\fP, it initializes

\fBdropSiteStatus\fP to \fBXmDROP_SITE_VALID\fP

if the DragContext\&'s \fBXmNexportTargets\fP and the DropSite\&'s

\fBXmNimportTargets\fP are compatible and if the initial value of the

\fIoperation\fP member is not \fBXmDROP_NOOP\fP\&.

Otherwise, the toolkit initializes \fBdropSiteStatus\fP to

\fBXmDROP_SITE_INVALID\fP\&.

.IP "\fIx\fP" 10

Indicates the x-coordinate of the pointer in root window coordinates\&.

.IP "\fIy\fP" 10

Indicates the y-coordinate of the pointer in root window coordinates\&.

.PP

A pointer to the following structure is passed to callbacks for

\fBXmNdropSiteLeaveCallback\fP:

.PP

.nf

typedef struct

{

        int \fIreason\fP;

        XEvent *\fIevent\fP;

        Time \fItimeStamp\fP;

}XmDropSiteLeaveCallbackStruct, *XmDropSiteLeaveCallback;

.fi

.IP "\fIreason\fP" 10

Indicates why the callback was invoked

.IP "\fIevent\fP" 10

Points to the \fBXEvent\fP that triggered the callback

.IP "\fBtimeStamp\fP" 10

Specifies the timestamp of the logical event

.PP

A pointer to the following structure is passed for the

\fBXmNdropStartCallback\fP callback:

.PP

.nf

typedef struct

{

        int \fIreason\fP;

        XEvent *\fIevent\fP;

        Time \fItimeStamp\fP;

        unsigned char \fIoperation\fP;

        unsigned char \fIoperations\fP;

        unsigned char \fIdropSiteStatus\fP;

        unsigned char \fIdropAction\fP;

        Position \fIx\fP;

        Position \fIy\fP;

}XmDropStartCallbackStruct, *XmDropStartCallback;

.fi

.IP "\fIreason\fP" 10

Indicates why the callback was invoked\&.

.IP "\fIevent\fP" 10

Points to the \fBXEvent\fP that triggered the callback\&.

.IP "\fBtimeStamp\fP" 10

Specifies the time at which the drag was completed\&.

.IP "\fIoperation\fP" 10

Identifies an operation\&.

.IP "" 10

If the pointer is over an active drop site when the drop begins, the

toolkit initializes \fIoperation\fP to the value of the \fIoperation\fP

member of the \fBXmDropProcCallbackStruct\fR at the time the DropSite\&'s

\fBXmNdropProc\fP returns\&.

.IP "" 10

If the pointer is not over an active drop site when the drop begins, the

toolkit initializes \fIoperation\fP by selecting an operation from the

initial value of the \fIoperations\fP member\&.

The toolkit searches this set first for \fBXmDROP_MOVE\fP, then for

\fBXmDROP_COPY\fP, then for \fBXmDROP_LINK\fP, and initializes

\fIoperation\fP to the first operation it finds in the set\&.

If it finds none of these operations in the set, it initializes

\fIoperation\fP to \fBXmDROP_NOOP\fP\&.

.IP "\fIoperations\fP" 10

Indicates the set of operations supported for the source data\&.

.IP "" 10

If the pointer is over an active drop site when the drop begins, the

toolkit initializes \fIoperations\fP to the bitwise AND of the

DropSite\&'s \fBXmNdropOperations\fP and the value of the \fIoperations\fP

member of the \fBXmDropProcCallbackStruct\fR at the time the DropSite\&'s

\fBXmNdropProc\fP returns\&.

If the resulting set of operations is empty, the toolkit initializes

\fIoperations\fP to \fBXmDROP_NOOP\fP\&.

.IP "" 10

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 \fIoperations\fP to the value of the

DragContext\&'s \fBXmNdragOperations\fP resource\&.

.IP "" 10

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

\fIoperations\fP to the bitwise AND of the corresponding operation and

the value of the DragContext\&'s \fBXmNdragOperations\fP resource\&.

If the resulting set of operations is empty, the toolkit initializes

\fIoperations\fP to \fBXmDROP_NOOP\fP\&.

.IP "\fBdropSiteStatus\fP" 10

Indicates whether or not a drop site is valid\&.

.IP "" 10

If the pointer is over an active drop site when the drop begins, the

toolkit initializes \fBdropSiteStatus\fP to the value of the

\fBdropSiteStatus\fP member of the \fBXmDropProcCallbackStruct\fR at the

time the DropSite\&'s \fBXmNdropProc\fP returns\&.

.IP "" 10

If the pointer is not over an active drop site when the drop begins, the

toolkit initializes \fBdropSiteStatus\fP to \fBXmNO_DROP_SITE\fP\&.

.IP "" 10

This field is invalid if the \fBdropAction\fP field is set to

\fBXmDROP_CANCEL\fP\&.

.IP "\fBdropAction\fP" 10

An IN/OUT member that identifies the drop action\&.

The values are \fBXmDROP\fP, \fBXmDROP_CANCEL\fP, \fBXmDROP_HELP\fP,

and \fBXmDROP_INTERRUPT\fP\&. The value of \fBdropAction\fP can be

modified to change the action actually initiated\&.

The value \fBXmDROP_INTERRUPT\fP is currently unsupported; if

specified, it will be interpreted as an \fBXmDROP_CANCEL\fP\&.

.IP "\fIx\fP" 10

Indicates the x-coordinate of the pointer in root window coordinates\&.

.IP "\fIy\fP" 10

Indicates the y-coordinate of the pointer in root window coordinates\&.

.PP

A pointer to the following structure is passed to the

\fBXmNoperationChangedCallback\fP callback:

.PP

.nf

typedef struct

{

        int \fIreason\fP;

        XEvent  *\fIevent\fP;

        Time \fItimeStamp\fP;

        unsigned char \fIoperation\fP;

        unsigned char \fIoperations\fP;

        unsigned char \fIdropSiteStatus\fP;

}XmOperationChangedCallbackStruct, *XmOperationChangedCallback;

.fi

.IP "\fIreason\fP" 10

Indicates why the callback was invoked\&.

.IP "\fIevent\fP" 10

Points to the \fBXEvent\fP that triggered the callback\&.

.IP "\fBtimeStamp\fP" 10

Specifies the time at which the crossing event occurred\&.

.IP "\fIoperation\fP" 10

Identifies an operation\&.

.IP "" 10

If the toolkit has just called a DropSite\&'s \fBXmNdragProc\fP, the

toolkit initializes \fIoperation\fP to the value of the \fIoperation\fP

member of the \fBXmDragProcCallbackStruct\fR at the time the DropSite\&'s

\fBXmNdragProc\fP returns\&.

.IP "" 10

If the toolkit has not called an \fBXmNdragProc\fP, and the pointer is

within an active drop site, the toolkit initializes \fIoperation\fP by

selecting an operation from the bitwise AND of the initial value of the

\fIoperations\fP member and the value of the DropSite\&'s

\fBXmNdropSiteOperations\fP resource\&.

The toolkit searches this set first for \fBXmDROP_MOVE\fP, then for

\fBXmDROP_COPY\fP, then for \fBXmDROP_LINK\fP, and initializes

\fIoperation\fP to the first operation it finds in the set\&.

If the toolkit finds none of these operations in the set, it initializes

\fIoperation\fP to \fBXmDROP_NOOP\fP\&.

.IP "" 10

If the toolkit has not called an \fBXmNdragProc\fP, and the pointer is

not within an active drop site, the toolkit initializes \fIoperation\fP

by selecting an operation from the initial value of the \fIoperations\fP

member\&.

The toolkit searches this set first for \fBXmDROP_MOVE\fP, then for

\fBXmDROP_COPY\fP, then for \fBXmDROP_LINK\fP, and initializes

\fIoperation\fP to the first operation it finds in the set\&.

If the toolkit finds none of these operations in the set, it initializes

\fIoperation\fP to \fBXmDROP_NOOP\fP\&.

.IP "\fIoperations\fP" 10

Indicates the set of operations supported for the source data\&.

.IP "" 10

If the toolkit has just called a DropSite\&'s \fBXmNdragProc\fP, the

toolkit initializes \fIoperations\fP to the bitwise AND of the

DropSite\&'s \fBXmNdropOperations\fP and the value of the \fIoperations\fP

member of the \fBXmDragProcCallbackStruct\fR at the time the DropSite\&'s

\fBXmNdragProc\fP returns\&.

If the resulting set of operations is empty, the toolkit initializes

\fIoperations\fP to \fBXmDROP_NOOP\fP\&.

.IP "" 10

If the toolkit has not called an \fBXmNdragProc\fP, and the user does not

select an operation (by pressing a modifier key), the toolkit

initializes \fIoperations\fP to the value of the DragContext\&'s

\fBXmNdragOperations\fP resource\&.

.IP "" 10

If the toolkit has not called an \fBXmNdragProc\fP, and the user does

select an operation, the toolkit initializes \fIoperations\fP to the

bitwise AND of the corresponding operation and the value of the

DragContext\&'s \fBXmNdragOperations\fP resource\&.

If the resulting set of operations is empty, the toolkit initializes

\fIoperations\fP to \fBXmDROP_NOOP\fP\&.

.IP "\fBdropSiteStatus\fP" 10

Indicates whether or not a drop site is valid\&.

.IP "" 10

If the toolkit has just called a DropSite\&'s \fBXmNdragProc\fP, the

toolkit initializes \fBdropSiteStatus\fP to the value of the

\fBdropSiteStatus\fP member of the \fBXmDragProcCallbackStruct\fR at the

time the DropSite\&'s \fBXmNdragProc\fP returns\&.

.IP "" 10

If the toolkit has not called an \fBXmNdragProc\fP it initializes

\fBdropSiteStatus\fP to \fBXmNO_DROP_SITE\fP if

the pointer is over an inactive drop site or is not over a drop site\&.

The toolkit initializes \fBdropSiteStatus\fP to \fBXmDROP_SITE_VALID\fP

if all the following conditions are met:

.RS

.IP "   \(bu" 6

The pointer is over an active drop site

.IP "   \(bu" 6

The DragContext\&'s \fBXmNexportTargets\fP and the DropSite\&'s

\fBXmNimportTargets\fP are compatible

.IP "   \(bu" 6

The initial value of the \fIoperation\fP member is not

\fBXmDROP_NOOP\fP

.RE

.IP "" 10

Otherwise, the toolkit initializes \fBdropSiteStatus\fP to

\fBXmDROP_SITE_INVALID\fP\&.