XmDragContext - The DragContext widget class
#include <Xm/DragDrop.h>
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 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 XmDRAG_DYNAMIC or XmDRAG_PREFER_DYNAMIC, then a dynamic visual style (cursor) is used. Otherwise, a preregister visual style is used.
DragContext inherits behavior and resources from Core.
The class pointer is xmDragContextClass.
The class name is XmDragContext.
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).
| 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 |
DragContext inherits behavior and resources from the following superclass. For a complete description of each resource, refer to the Core man page.
| 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 |
| 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 |
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;
A pointer to the following structure is passed to callbacks for XmNdragMotionCallback.
typedef struct
{
int reason;
XEvent *event;
Time timeStamp;
unsigned char operation;
unsigned char operations;
unsigned char dropSiteStatus;
Position x;
Position y;
}XmDragMotionCallbackStruct, *XmDragMotionCallback;
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 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.
If the toolkit has just called a DropSite's XmNdragProc, the toolkit initializes operations to the bitwise AND of the DropSite's XmNdropSiteOperations 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 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 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 XmDROP_NOOP.
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 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:
A pointer to the following structure is passed for the XmNdropFinishCallback 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;
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.
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 XmNdropSiteOperations and the value of the operations member of the XmDropProcCallbackStruct at the time the DropSite's XmNdragProc 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 corresponding operation and the value of the DragContext's XmNdragOperations resource. If the resulting set of operations is empty, the toolkit initializes operations to XmDROP_NOOP.
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 XmNdragProc returns.
If the pointer is not over an active drop site when the drop begins, the toolkit initializes dropSiteStatus to XmNO_DROP_SITE.
A pointer to the following structure is passed to callbacks for XmNdropSiteEnterCallback:
typedef struct
{
int reason;
XEvent *event;
Time timeStamp;
unsigned char operation;
unsigned char operations;
unsigned char dropSiteStatus;
Position x;
Position y;
}XmDropSiteEnterCallbackStruct, *XmDropSiteEnterCallback;
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 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 just called a DropSite's XmNdragProc, the toolkit initializes operations to the bitwise AND of the DropSite's XmNdropSiteOperations 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 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 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 XmDROP_NOOP.
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 XmDROP_SITE_VALID if the DragContext's XmNexportTargets and the DropSite's XmNimportTargets are compatible and if the initial value of the operation member is not XmDROP_NOOP. Otherwise, the toolkit initializes dropSiteStatus to XmDROP_SITE_INVALID.
A pointer to the following structure is passed to callbacks for XmNdropSiteLeaveCallback.
typedef struct
{
int reason;
XEvent *event;
Time timeStamp;
}XmDropSiteLeaveCallbackStruct, *XmDropSiteLeaveCallback;
A pointer to the following structure is passed for the XmNdropStartCallback 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;
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 XmNdragProc 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.
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 XmNdropSiteOperations and the value of the operations member of the XmDropProcCallbackStruct at the time the DropSite's XmNdragProc 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 corresponding operation and the value of the DragContext's XmNdragOperations resource. If the resulting set of operations is empty, the toolkit initializes operations to XmDROP_NOOP.
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 XmNdragProc returns.
If the pointer is not over an active drop site when the drop begins, the toolkit initializes dropSiteStatus to XmNO_DROP_SITE.
A pointer to the following structure is passed to the XmNoperationChangedCallback callback:
typedef struct
{
int reason;
XEvent *event;
Time timeStamp;
unsigned char operation;
unsigned char operations;
unsigned char dropSiteStatus;
}XmOperationChangedCallbackStruct, *XmOperationChangedCallback;
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 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.
If the toolkit has just called a DropSite's XmNdragProc, the toolkit initializes operations to the bitwise AND of the DropSite's XmNdropSiteOperations 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 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 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 XmDROP_NOOP.
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 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:
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 char dragProtocolStyle;
}XmTopLevelEnterCallbackStruct, *XmTopLevelEnterCallback;
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;
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()
The XmDragContext action routines are described below:
The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see VirtualBindings(3X).
Core(3X), XmDisplay(3X), XmDragCancel(3X), XmDragIcon(3X), XmDragStart(3X), XmDropSite(3X), XmDropTransfer(3X), and XmScreen(3X).