XmDragContext(3) Library Functions Manual XmDragContext(3) NAME XmDragContext -- The DragContext widget class SYNOPSIS #include <Xm/DragDrop.h> DESCRIPTION DragContexts are special widgets used in drag and drop transactions. A DragContext is implemented as a widget, but a client does not explicitly create a DragContext widget. Instead, a client initiates a drag and drop transaction by calling XmDragStart, and this routine initializes and re- turns a DragContext widget. There is a unique DragContext for each drag op- eration. The toolkit frees a DragContext when a transaction is complete; therefore, an application programmer should not explicitly destroy a Drag- Context. 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 dif- ferent clients, there are two separate DragContexts. In this case, the ini- tiator calls XmDragStart and the toolkit provides a DragContext for the re- ceiver client. The only resources pertinent to the receiver are XmNexport- Targets 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 re- source, XmNexportTargets, identifies the selection targets for the drag source. These export targets are compared with the XmNimportTargets re- source list specified by a drop site. The DragContext resource, XmNdragOp- erations, identifies the valid operations that can be applied to the source data by the initiator. The drop site counterpart resource is XmNdropSiteOp- erations, 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 re- sulting drag protocol style is Drop Only or None and the XmNdragInitiator- ProtocolStyle is XmDRAG_DYNAMIC or XmDRAG_PREFER_DYNAMIC, then a dynamic visual style (cursor) is used. Otherwise, a preregister visual style is used. Classes DragContext inherits behavior and resources from Core. The class pointer is xmDragContextClass. The class name is XmDragContext. New Resources The following table defines a set of widget resources used by the program- mer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a re- source by name or by class in a .Xdefaults file, remove the XmN or XmC pre- fix 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 be- tween words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). +------------------------------------------------------------------------------------------------------------------------+ | | XmDragContext Resource Set | | | | Name | Class | Type | Default | Access | +-----------------------------+------------------------+----------------------------+---------------------------+--------+ | XmNblendModel | XmCBlendModel | unsigned char | XmBLEND_ALL | CG | +-----------------------------+------------------------+----------------------------+---------------------------+--------+ | XmNclientData | XmCClientData | XtPointer | NULL | CSG | +-----------------------------+------------------------+----------------------------+---------------------------+--------+ | XmNconvertProc | XmCConvertProc | XtConvertSelectionIncrProc | NULL | CSG | +-----------------------------+------------------------+----------------------------+---------------------------+--------+ | XmNcursorBackground | XmCCursorBackground | Pixel | dynamic | CSG | +-----------------------------+------------------------+----------------------------+---------------------------+--------+ | XmNcursorForeground | XmCCursorForeground | Pixel | dynamic | CSG | +-----------------------------+------------------------+----------------------------+---------------------------+--------+ | XmNdragDropFinishCallback | XmCCallback | XtCallbackList | NULL | CSG | +-----------------------------+------------------------+----------------------------+---------------------------+--------+ | XmNdragMotionCallback | XmCCallback | XtCallbackList | NULL | C | +-----------------------------+------------------------+----------------------------+---------------------------+--------+ | XmNdragOperations | XmCDragOperations | unsigned char | XmDROP_COPY | XmDROP_MOVE | C | +-----------------------------+------------------------+----------------------------+---------------------------+--------+ | XmNdropFinishCallback | XmCCallback | XtCallbackList | NULL | C | +-----------------------------+------------------------+----------------------------+---------------------------+--------+ | XmNdropSiteEnterCallback | XmCCallback | XtCallbackList | NULL | C | +-----------------------------+------------------------+----------------------------+---------------------------+--------+ | XmNdropSiteLeaveCallback | XmCCallback | XtCallbackList | NULL | C | +-----------------------------+------------------------+----------------------------+---------------------------+--------+ | XmNdropStartCallback | XmCCallback | XtCallbackList | NULL | C | +-----------------------------+------------------------+----------------------------+---------------------------+--------+ | XmNexportTargets | XmCExportTargets | Atom * | NULL | CSG | +-----------------------------+------------------------+----------------------------+---------------------------+--------+ | XmNincremental | XmCIncremental | Boolean | False | CSG | +-----------------------------+------------------------+----------------------------+---------------------------+--------+ | XmNinvalidCursorForeground | XmCCursorForeground | Pixel | dynamic | CSG | +-----------------------------+------------------------+----------------------------+---------------------------+--------+ | XmNnoneCursorForeground | XmCCursorForeground | Pixel | dynamic | CSG | +-----------------------------+------------------------+----------------------------+---------------------------+--------+ | XmNnumExportTargets | XmCNumExportTargets | Cardinal | 0 | CSG | +-----------------------------+------------------------+----------------------------+---------------------------+--------+ | XmNoperationChangedCallback | XmCCallback | XtCallbackList | NULL | C | +-----------------------------+------------------------+----------------------------+---------------------------+--------+ | XmNoperationCursorIcon | XmCOperationCursorIcon | Widget | dynamic | CSG | +-----------------------------+------------------------+----------------------------+---------------------------+--------+ | XmNsourceCursorIcon | XmCSourceCursorIcon | Widget | dynamic | CSG | +-----------------------------+------------------------+----------------------------+---------------------------+--------+ | XmNsourcePixmapIcon | XmCSourcePixmapIcon | Widget | dynamic | CSG | +-----------------------------+------------------------+----------------------------+---------------------------+--------+ | XmNstateCursorIcon | XmCStateCursorIcon | Widget | dynamic | CSG | +-----------------------------+------------------------+----------------------------+---------------------------+--------+ | XmNtopLevelEnterCallback | XmCCallback | XtCallbackList | NULL | C | +-----------------------------+------------------------+----------------------------+---------------------------+--------+ | XmNtopLevelLeaveCallback | XmCCallback | XtCallbackList | NULL | C | +-----------------------------+------------------------+----------------------------+---------------------------+--------+ | XmNvalidCursorForeground | XmCCursorForeground | Pixel | dynamic | CSG | +-----------------------------+------------------------+----------------------------+---------------------------+--------+ +-----------------------------+------------------------+----------------------------+---------------------------+--------+ XmNblendModel Specifies which combination of DragIcons are blended to produce a drag-over visual. XmBLEND_ALL Blends all three DragIcons: the source, state and oper- ation icons. The icons are layered from top to bottom with the operation icon on top and the source icon on the bottom. The hotspot is derived from the state icon. XmBLEND_STATE_SOURCE Blends the state and source icons only. The hotspot is derived from the state icon. XmBLEND_JUST_SOURCE Specifies that only the source icon is used, which the initiator updates as required. XmBLEND_NONE Specifies that no drag-over visual is generated. The client tracks the drop site status through callback routines and updates the drag-over visuals as neces- sary. XmNclientData Specifies the client data to be passed to XmNconvertProc when it is invoked. XmNconvertProc If XmNincremental is True, specifies a procedure of type XtCon- vertSelectionIncrProc that converts the source data to the for- mat(s) requested by the receiver client. The widget argument passed to this procedure is the DragContext widget. The selec- tion atom passed is _MOTIF_DROP. If XmNincremental is False, the procedure is an XtConvertSelectionProc, and should ignore the max_length, client_data, and request_id arguments and should han- dle 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 Lan- guage 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 transac- tion is completed. The type of the structure whose address is passed to this callback is XmDragDropFinishCallbackStruct. The reason sent by the callback is XmCR_DRAG_DROP_FINISH. XmNdragMotionCallback Specifies the list of callbacks that are invoked when the pointer moves. The type of structure whose address is passed to this callback is XmDragMotionCallbackStruct. The reason sent by the callback is XmCR_DRAG_MOTION. XmNdragOperations Specifies the set of valid operations associated with an initia- tor client for a drag transaction. This resource is a bit mask that is formed by combining one or more of the following values using a bitwise operation such as inclusive OR (|): XmDROP_COPY, XmDROP_LINK, XmDROP_MOVE. The value XmDROP_NOOP for this re- source indicates that no operations are valid. For Text and TextField widgets, this resource is set to XmDROP_COPY | Xm- DROP_MOVE; for List widgets, it is set to XmDROP_COPY. XmNdropFinishCallback Specifies the list of callbacks that are invoked when the drop is completed. The type of the structure whose address is passed to this callback is XmDropFinishCallbackStruct. The reason sent by the callback is XmCR_DROP_FINISH. XmNdropSiteEnterCallback Specifies the list of callbacks that are invoked when the pointer enters a drop site. The type of the structure whose address is passed to this callback is XmDropSiteEnterCallbackStruct. The reason sent by the callback is XmCR_DROP_SITE_ENTER. XmNdropSiteLeaveCallback Specifies the list of callbacks that are invoked when the pointer leaves a drop site. The type of the structure whose address is passed to this callback is XmDropSiteLeaveCallbackStruct. The reason sent by the callback is XmCR_DROP_SITE_LEAVE. XmNdropStartCallback Specifies the list of callbacks that are invoked when a drop is initiated. The type of the structure whose address is passed to this callback is XmDropStartCallbackStruct. The reason sent by the callback is XmCR_DROP_START. XmNexportTargets Specifies the list of target atoms associated with this source. This resource identifies the selection targets this source can be converted to. XmNincremental Specifies a Boolean value that indicates whether the transfer on the initiator side uses the Xt incremental selection transfer mechanism described in X Toolkit Intrinsics--C Language Inter- face. If the value is True, the initiator uses incremental transfer; if the value is False, the initiator uses atomic trans- fer. XmNinvalidCursorForeground Specifies the foreground pixel value of the cursor when the state is invalid. This resource defaults to the value of the XmNcursor- Foreground resource. XmNnoneCursorForeground Specifies the foreground pixel value of the cursor when the state is none. This resource defaults to the value of the XmNcursor- Foreground resource. XmNnumExportTargets Specifies the number of entries in the list of 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 XmCR_OPERATION_CHANGED. 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 dy- namic visual style is used. If NULL, the XmNdefaultSourceCursorI- con 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 XmCR_TOP_LEVEL_ENTER. XmNtopLevelLeaveCallback Specifies the list of callbacks that are called when the pointer leaves a top level window or the root window (due to changing screens). The type of the structure whose address is passed to this callback is XmTopLevelLeaveCallbackStruct. The reason sent by the callback is XmCR_TOP_LEVEL_LEAVE. XmNvalidCursorForeground Specifies the foreground pixel value of the cursor designated as a valid cursor icon. Inherited Resources DragContext inherits behavior and resources from the superclass described in the following table. For a complete description of each resource, refer to the Core reference page. +----------------------------------------------------------------------------------------------------------------+ | | Core Resource Set | | | | Name | Class | Type | Default | Access | +-------------------------------+-------------------------------+----------------+----------------------+--------+ | XmNaccelerators | XmCAccelerators | XtAccelerators | dynamic | CSG | +-------------------------------+-------------------------------+----------------+----------------------+--------+ | XmNancestorSensitive | XmCSensitive | Boolean | dynamic | G | +-------------------------------+-------------------------------+----------------+----------------------+--------+ | XmNbackground | XmCBackground | Pixel | dynamic | CSG | +-------------------------------+-------------------------------+----------------+----------------------+--------+ | XmNbackgroundPixmap | XmCPixmap | Pixmap | XmUNSPECIFIED_PIXMAP | CSG | +-------------------------------+-------------------------------+----------------+----------------------+--------+ | XmNborderColor | XmCBorderColor | Pixel | XtDefaultForeground | CSG | +-------------------------------+-------------------------------+----------------+----------------------+--------+ | XmNborderPixmap | XmCPixmap | Pixmap | XmUNSPECIFIED_PIXMAP | CSG | +-------------------------------+-------------------------------+----------------+----------------------+--------+ | XmNborderWidth | XmCBorderWidth | Dimension | 0 | CSG | +-------------------------------+-------------------------------+----------------+----------------------+--------+ | XmNcolormap | XmCColormap | Colormap | dynamic | CG | +-------------------------------+-------------------------------+----------------+----------------------+--------+ | XmNdepth | XmCDepth | int | dynamic | CG | +-------------------------------+-------------------------------+----------------+----------------------+--------+ | XmNdestroyCallback | XmCCallback | XtCallbackList | NULL | C | +-------------------------------+-------------------------------+----------------+----------------------+--------+ | XmNheight | XmCHeight | Dimension | dynamic | CSG | +-------------------------------+-------------------------------+----------------+----------------------+--------+ | XmNinitialResourcesPersistent | XmCInitialResourcesPersistent | Boolean | True | C | +-------------------------------+-------------------------------+----------------+----------------------+--------+ | XmNmappedWhenManaged | XmCMappedWhenManaged | Boolean | True | CSG | +-------------------------------+-------------------------------+----------------+----------------------+--------+ | XmNscreen | XmCScreen | Screen * | dynamic | CG | +-------------------------------+-------------------------------+----------------+----------------------+--------+ | XmNsensitive | XmCSensitive | Boolean | True | CSG | +-------------------------------+-------------------------------+----------------+----------------------+--------+ | XmNtranslations | XmCTranslations | XtTranslations | dynamic | CSG | +-------------------------------+-------------------------------+----------------+----------------------+--------+ | XmNwidth | XmCWidth | Dimension | dynamic | CSG | +-------------------------------+-------------------------------+----------------+----------------------+--------+ | XmNx | XmCPosition | Position | 0 | CSG | +-------------------------------+-------------------------------+----------------+----------------------+--------+ | XmNy | XmCPosition | Position | 0 | CSG | +-------------------------------+-------------------------------+----------------+----------------------+--------+ +-------------------------------+-------------------------------+----------------+----------------------+--------+ Callback Information Each of the DragContext callbacks has an associated callback structure. A pointer to the following structure is passed to the XmNdragDropFinish- Callback callback: typedef struct { int reason; XEvent *event; Time timeStamp; }XmDragDropFinishCallbackStruct, *XmDragDropFinishCallback; reason Indicates why the callback was invoked event Points to the XEvent that triggered the callback timeStamp Specifies the time at which either the drag or the drop was com- pleted A pointer to the following structure is passed to callbacks for XmNdragMo- tionCallback: typedef struct { int reason; XEvent *event; Time timeStamp; unsigned char operation; unsigned char operations; unsigned char dropSiteStatus; Position x; Position y; }XmDragMotionCallbackStruct, *XmDragMotionCallback; reason Indicates why the callback was invoked. event Points to the XEvent that triggered the callback. timeStamp Specifies the timestamp of the logical event. operation Identifies an operation. If the toolkit has just called a DropSite's XmNdragProc, the toolkit initializes operation to the value of the operation mem- ber 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 XmNdrop- SiteOperations resource. The toolkit searches this set first for XmDROP_MOVE, then for XmDROP_COPY, then for XmDROP_LINK, and ini- tializes operation to the first operation it finds in the set. If the toolkit finds none of these operations in the set, it ini- tializes 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 opera- tions member. The toolkit searches this set first for Xm- DROP_MOVE, then for XmDROP_COPY, then for XmDROP_LINK, and ini- tializes operation to the first operation it finds in the set. If the toolkit finds none of these operations in the set, it ini- tializes operation to XmDROP_NOOP. operationsIndicates 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 Drop- Site's XmNdropOperations and the value of the operations member of the XmDragProcCallbackStruct at the time the DropSite's XmN- dragProc 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 XmNdrag- Operations 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 Xm- DROP_NOOP. dropSiteStatus Indicates whether or not a drop site is valid. If the toolkit has just called a DropSite's XmNdragProc, the toolkit initializes dropSiteStatus to the value of the dropSiteS- tatus 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: * The pointer is over an active drop site. * The DragContext's XmNexportTargets and the DropSite's XmN- importTargets are compatible. * The initial value of the operation member is not Xm- DROP_NOOP. Otherwise, the toolkit initializes dropSiteStatus to Xm- DROP_SITE_INVALID. A pointer to the following structure is passed for the XmNdropFinishCall- back callback: typedef struct { int reason; XEvent *event; Time timeStamp; unsigned char operation; unsigned char operations; unsigned char dropSiteStatus; unsigned char dropAction; unsigned char completionStatus; }XmDropFinishCallbackStruct, *XmDropFinishCallback; reason Indicates why the callback was invoked. event Points to the XEvent that triggered the callback. timeStamp Specifies the time at which the drop was completed. operation Identifies an operation. If the pointer is over an active drop site when the drop begins, the toolkit initializes operation to the value of the operation member of the XmDropProcCallbackStruct at the time the DropSite's XmNdropProc returns. If the pointer is not over an active drop site when the drop be- gins, 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 op- eration it finds in the set. If it finds none of these opera- tions in the set, it initializes operation to XmDROP_NOOP. operationsIndicates 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 mem- ber of the XmDropProcCallbackStruct at the time the DropSite's XmNdropProc returns. If the resulting set of operations is empty, the toolkit initializes operations to XmDROP_NOOP. If the pointer is not over an active drop site when the drop be- gins 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 be- gins and if the user does select an operation, the toolkit ini- tializes operations to the bitwise AND of the corresponding oper- ation and the value of the DragContext's XmNdragOperations re- source. If the resulting set of operations is empty, the toolkit initializes operations to XmDROP_NOOP. dropSiteStatus Indicates whether or not a drop site is valid. If the pointer is over an active drop site when the drop begins, the toolkit initializes dropSiteStatus to the value of the drop- SiteStatus 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 be- gins, the toolkit initializes dropSiteStatus to XmNO_DROP_SITE. dropActionIdentifies the drop action. The values are XmDROP, XmDROP_CANCEL, XmDROP_HELP, and XmDROP_INTERRUPT. The XmDROP_INTERRUPT value is currently unsupported; if specified, it will be interpreted as an XmDROP_CANCEL. completionStatus An IN/OUT member that indicates the status of the drop action. After the last callback procedure has returned, the final value of this member determines what visual transition effects will be applied. There are two values: XmDROP_SUCCESS The drop was successful. XmDROP_FAILURE The drop was unsuccessful. A pointer to the following structure is passed to callbacks for XmNdropSi- teEnterCallback: typedef struct { int reason; XEvent *event; Time timeStamp; unsigned char operation; unsigned char operations; unsigned char dropSiteStatus; Position x; Position y; }XmDropSiteEnterCallbackStruct, *XmDropSiteEnterCallback; reason Indicates why the callback was invoked. event Points to the XEvent that triggered the callback. timeStamp Specifies the time the crossing event occurred. operation Identifies an operation. If the toolkit has just called a DropSite's XmNdragProc, the toolkit initializes operation to the value of the operation mem- ber of the XmDragProcCallbackStruct at the time the DropSite's XmNdragProc returns. If the toolkit has not called an XmNdragProc, it initializes op- eration by selecting an operation from the bitwise AND of the initial value of the operations member and the value of the Drop- Site's XmNdropSiteOperations resource. The toolkit searches this set first for XmDROP_MOVE, then for XmDROP_COPY, then for Xm- DROP_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. operationsIndicates 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 Drop- Site's XmNdropOperations and the value of the operations member of the XmDragProcCallbackStruct at the time the DropSite's XmN- dragProc 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 XmNdrag- Operations 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 Xm- DROP_NOOP. dropSiteStatus Indicates whether or not a drop site is valid. If the toolkit has just called a DropSite's XmNdragProc, the toolkit initializes dropSiteStatus to the value of the dropSiteS- tatus member of the XmDragProcCallbackStruct at the time the DropSite's XmNdragProc returns. If the toolkit has not called XmNdragProc, it initializes drop- SiteStatus to XmDROP_SITE_VALID if the DragContext's XmNexport- Targets 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 Xm- DROP_SITE_INVALID. x Indicates the x-coordinate of the pointer in root window coordi- nates. y Indicates the y-coordinate of the pointer in root window coordi- nates. A pointer to the following structure is passed to callbacks for XmNdrop- SiteLeaveCallback: 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 char operation; unsigned char operations; unsigned char dropSiteStatus; unsigned char dropAction; Position x; Position y; }XmDropStartCallbackStruct, *XmDropStartCallback; reason Indicates why the callback was invoked. event Points to the XEvent that triggered the callback. timeStamp Specifies the time at which the drag was completed. operation Identifies an operation. If the pointer is over an active drop site when the drop begins, the toolkit initializes operation to the value of the operation member of the XmDropProcCallbackStruct at the time the DropSite's XmNdropProc returns. If the pointer is not over an active drop site when the drop be- gins, 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 op- eration it finds in the set. If it finds none of these opera- tions in the set, it initializes operation to XmDROP_NOOP. operationsIndicates 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 mem- ber of the XmDropProcCallbackStruct at the time the DropSite's XmNdropProc returns. If the resulting set of operations is empty, the toolkit initializes operations to XmDROP_NOOP. If the pointer is not over an active drop site when the drop be- gins 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 be- gins and if the user does select an operation, the toolkit ini- tializes operations to the bitwise AND of the corresponding oper- ation and the value of the DragContext's XmNdragOperations re- source. If the resulting set of operations is empty, the toolkit initializes operations to XmDROP_NOOP. dropSiteStatus Indicates whether or not a drop site is valid. If the pointer is over an active drop site when the drop begins, the toolkit initializes dropSiteStatus to the value of the drop- SiteStatus 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 be- gins, the toolkit initializes dropSiteStatus to XmNO_DROP_SITE. This field is invalid if the dropAction field is set to Xm- DROP_CANCEL. dropActionAn IN/OUT member that identifies the drop action. The values are XmDROP, XmDROP_CANCEL, XmDROP_HELP, and XmDROP_INTERRUPT. The value of dropAction can be modified to change the action actually initiated. The value XmDROP_INTERRUPT is currently unsupported; if specified, it will be interpreted as an XmDROP_CANCEL. x Indicates the x-coordinate of the pointer in root window coordi- nates. y Indicates the y-coordinate of the pointer in root window coordi- nates. A pointer to the following structure is passed to the XmNoperationChanged- Callback callback: typedef struct { int reason; XEvent *event; Time timeStamp; unsigned char operation; unsigned char operations; unsigned char dropSiteStatus; }XmOperationChangedCallbackStruct, *XmOperationChangedCallback; reason Indicates why the callback was invoked. event Points to the XEvent that triggered the callback. timeStamp Specifies the time at which the crossing event occurred. operation Identifies an operation. If the toolkit has just called a DropSite's XmNdragProc, the toolkit initializes operation to the value of the operation mem- ber 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 XmNdrop- SiteOperations resource. The toolkit searches this set first for XmDROP_MOVE, then for XmDROP_COPY, then for XmDROP_LINK, and ini- tializes operation to the first operation it finds in the set. If the toolkit finds none of these operations in the set, it ini- tializes 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 opera- tions member. The toolkit searches this set first for Xm- DROP_MOVE, then for XmDROP_COPY, then for XmDROP_LINK, and ini- tializes operation to the first operation it finds in the set. If the toolkit finds none of these operations in the set, it ini- tializes operation to XmDROP_NOOP. operationsIndicates 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 Drop- Site's XmNdropOperations and the value of the operations member of the XmDragProcCallbackStruct at the time the DropSite's XmN- dragProc 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 XmNdrag- Operations 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 Xm- DROP_NOOP. dropSiteStatus Indicates whether or not a drop site is valid. If the toolkit has just called a DropSite's XmNdragProc, the toolkit initializes dropSiteStatus to the value of the dropSiteS- tatus member of the XmDragProcCallbackStruct at the time the DropSite's XmNdragProc returns. If the toolkit has not called an XmNdragProc it initializes drop- SiteStatus 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 condi- tions are met: * The pointer is over an active drop site * The DragContext's XmNexportTargets and the DropSite's XmN- importTargets are compatible * The initial value of the operation member is not Xm- DROP_NOOP Otherwise, the toolkit initializes dropSiteStatus to Xm- DROP_SITE_INVALID. A pointer to the following structure is passed to callbacks for XmNtopLeve- lEnterCallback: typedef struct { int reason; XEvent *event; Time timeStamp; Screen screen; Window window; Position x; Position y; unsigned char dragProtocolStyle; }XmTopLevelEnterCallbackStruct, *XmTopLevelEnterCallback; reason Indicates why the callback was invoked. event Points to the XEvent that triggered the callback. timeStamp Specifies the timestamp of the logical event. screen Specifies the screen associated with the top-level window or root window being entered. window Specifies the ID of the top-level window or root window being en- tered. x Indicates the x-coordinate of the pointer in root window coordi- nates. y Indicates the y-coordinate of the pointer in root window coordi- nates. dragProtocolStyle Specifies the protocol style adopted by the initiator. The values are XmDRAG_DROP_ONLY, XmDRAG_DYNAMIC, XmDRAG_NONE, and Xm- DRAG_PREREGISTER. A pointer to the following structure is passed to callbacks for XmNtopLev- elLeaveCallback: typedef struct { int reason; XEvent *event; Time timeStamp; Screen screen; Window window; }XmTopLevelLeaveCallbackStruct, *XmTopLevelLeaveCallback; reason Indicates why the callback was invoked event Points to the XEvent that triggered the callback timeStamp Specifies the timestamp of the logical event screen Specifies a screen associated with the top-level window or root window being left window Specifies the ID of the top-level window or root window being left Translations The XmDragContext translations are described in the following list. The following key names are listed in the X standard key event translation ta- ble syntax. This format is the one used by Motif to specify the widget ac- tions corresponding to a given key. A brief overview of the format is pro- vided under VirtualBindings(3). For a complete description of the format, please refer to the X Toolkit Instrinsics Documentation. Button1<Enter>: DragMotion() Button1<Leave>: DragMotion() Button1<Motion>: DragMotion() Button2<Enter>: DragMotion() Button2<Leave>: DragMotion() Button2<Motion>: DragMotion() <Btn2Up>: FinishDrag() <Btn1Up>: FinishDrag() <Key>Return: FinishDrag() <Key><osfActivate>: FinishDrag() <BtnDown>:IgnoreButtons() <BtnUp>: IgnoreButtons() :<Key><osfCancel>: CancelDrag() :<Key><osfHelp>: HelpDrag() :<Key><osfUp>: DragKey(Up) :<Key><osfDown>: DragKey(Down) :<Key><osfLeft>: DragKey(Left) :<Key><osfRight>: DragKey(Right) :<KeyUp>: DragKey(Update) :<KeyDown>: DragKey(Update) Action Routines The XmDragContext action routines are CancelDrag(): Cancels the drag operation and frees the associated DragContext. DragKey(String) If the value of String is Left, Right, Up, or Down, this action moves the dragged object in the corresponding location. Any other values of String are ignored. DragMotion(): Drags the selected data as the pointer is moved. FinishDrag(): Finishes the drag operation and starts the drop operation. HelpDrag(): Initiates a conditional drop that enables the receiver to provide help information to the user. The user can cancel or continue the drop operation in response to this information. Virtual Bindings The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see VirtualBindings(3). RELATED INFORMATION Core(3), XmDisplay(3), XmDragCancel(3), XmDragIcon(3), XmDragStart(3), Xm- DropSite(3), XmDropTransfer(3), and XmScreen(3). XmDragContext(3)
NAME | SYNOPSIS | DESCRIPTION | RELATED INFORMATION
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=XmDragContext&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>