The DropSite Registry
Format
#include <Xm/DragDrop.h>
DESCRIPTION
A client registers a widget or gadget as a drop site using the XmDropSiteRegister function. In addition, this routine defines the behavior and capabilities of a drop site by specifying appropriate resources. For example, the XmNimportTargets and XmNnumImportTargets resources identify respectively the selection target types and number of types supported by a drop site. The visual animation effects associated with a drop site are also described with DropSite resources.
Drop site animation effects that occur in response to the pointer entering a valid drop site are called drag-under effects. A receiver can select from several animation styles supplied by the toolkit or can provide customized animation effects. Drag-under effects supplied by the toolkit include border highlighting, shadow in/out drawing, and pixmap representation.
When a preregister drag protocol style is used, the toolkit generates drag-under visual effects based on the value of the XmNanimationStyle resource. In dynamic mode, if the drop site XmNdragProc resource is NULL, the toolkit also provides animation effects based on the XmNanimationStyle resource. Otherwise, if the XmNdragProc routine is specified, the receiver can either assume responsibility for animation effects (through the XmNdragProc routine) or rely on the toolkit to provide animation. An application can either handle all or none of the animation effects for a particular drop site. That is, an application should never do a partial job of animation on a particular drop site.
Drop sites may overlap. The initial stacking order corresponds to the order in which the drop sites were registered. When a drop site overlaps another drop site, the drag-under effects of the drop site underneath are clipped by the obscuring drop site(s).
The XmDropSiteUpdate routine sets resources for a widget that is registered as a drop site. XmDropSiteRetrieve gets drop site resource values previously specified for a registered widget. These routines are used instead of XtSetValues and XtGetValues.
XmDropSite does not inherit from any widget class.
The following table defines a set of widget resources used by the programmer to specify data. 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 XmDropSiteUpdate (S), retrieved by using XmDropSiteRetrieve (G), or is not applicable (N/A).
| XmDropSite Resource Set | ||||
| Name | Class | Type | Default | Access |
| XmNanimationMask | XmCAnimationMask | Pixmap | XmUNSPECIFIED_PIXMAP | CSG |
| XmNanimationPixmap | XmCAnimationPixmap | Pixmap | XmUNSPECIFIED_PIXMAP | CSG |
| XmNanimationPixmapDepth | XmCAnimationPixmapDepth | int | 0 | CSG |
| XmNanimationStyle | XmCAnimationStyle | unsigned char | XmDRAG_UNDER_HIGHLIGHT | CSG |
| XmNdragProc | XmCDragProc | XtCallbackProc | NULL | CSG |
| XmNdropProc | XmCDropProc | XtCallbackProc | NULL | CSG |
| XmNdropRectangles | XmCDropRectangles | XRectangle * | dynamic | CSG |
| XmNdropSiteActivity | XmCDropSiteActivity | unsigned char | XmDROP_SITE_ACTIVE | CSG |
| XmNdropSiteOperations | XmCDropSiteOperations | unsigned char | XmDROP_MOVE | XmDROP_COPY | CSG |
| XmNdropSiteType | XmCDropSiteType | unsigned char | XmDROP_SITE_SIMPLE | CG |
| XmNimportTargets | XmCImportTargets | Atom * | NULL | CSG |
| XmNnumDropRectangles | XmCNumDropRectangles | Cardinal | 1 | CSG |
| XmNnumImportTargets | XmCNumImportTargets | Cardinal | 0 | CSG |
The drag procedure may change the values of some members of the XmDragProcCallbackStruct passed to it. After the drag procedure returns, the toolkit uses the final values in initializing some members of the callback structure passed to the appropriate callbacks of the initiator (the DragContext's XmNdropSiteEnterCallback, XmNdropSiteLeaveCallback, XmNdragMotionCallback, or XmNoperationChangedCallback callbacks).
The drop procedure may change the values of some members of the XmDropProcCallbackStruct passed to it. After the drop procedure returns, the toolkit uses the final values in initializing some members of the XmDropStartCallbackStruct passed to the initiator's drop start callbacks (the DragContext's XmNdropStartCallback callbacks).
Retrieving this resource returns allocated memory that needs to be freed with the XtFree function.
A pointer to the following structure is passed to the XmNdragProc routine when the drop site receives crossing, motion, or operation changed messages:
typedef struct
{
int
reason;
XEvent *
event;
Time
timeStamp;
Widget
dragContext;
Position x;
Position y;
unsigned char
dropSiteStatus;
unsigned char
operation;
unsigned char
operations;
Boolean
animate;
} XmDragProcCallbackStruct, *XmDragProcCallback;
When reason is XmCR_DROP_SITE_ENTER_MESSAGE or XmCR_OPERATION_CHANGED, or reason is XmCR_DRAG_MOTION or XmCR_DROP_SITE_LEAVE_MESSAGE and the pointer is not in the same drop site as on the previous invocation of the drag procedure, 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.
When the reason is XmCR_DRAG_MOTION or XmCR_DROP_SITE_LEAVE_MESSAGE and the pointer is within the same drop site as on the previous invocation of the drag procedure, the toolkit initializes dropSiteStatus to the value of dropSiteStatus at the time the previous invocation of the drag procedure returns.
The drag procedure may change the value of this member. After the drag procedure returns, the toolkit uses the final value in initializing the dropSiteStatus member of the callback struct passed to the appropriate callbacks of the initiator.
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.
The drag procedure may change the value of this member. After the drag procedure returns, the toolkit uses the final value in initializing the operation member of the callback struct passed to the appropriate callbacks of the initiator.
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 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.
The drag procedure may change the value of this member. After the drag procedure returns, the toolkit uses the final value in initializing the operations member of the callback struct passed to the appropriate callbacks of the initiator.
A pointer to the following structure is passed to the XmNdropProc routine when the drop site receives a drop message:
typedef struct
{
int
reason;
XEvent *
event;
Time
timeStamp;
Widget
dragContext;
Position x;
Position y;
unsigned char
dropSiteStatus;
unsigned char
operation;
unsigned char
operations;
unsigned char
dropAction;
} XmDropProcCallbackStruct, *XmDropProcCallback;
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.
The drop procedure may change the value of this member. After the drop procedure returns, the toolkit uses the final value in initializing the dropSiteStatus member of the XmDropStartCallbackStruct passed to the initiator's drop start callbacks (the DragContext's XmNdropStartCallback callbacks).
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 it finds none of these operations in the set, it initializes operation to XmDROP_NOOP.
The drop procedure may change the value of this member. After the drop procedure returns, the toolkit uses the final value in initializing the operation member of the XmDropStartCallbackStruct passed to the initiator's drop start callbacks (the DragContext's XmNdropStartCallback callbacks).
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 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.
The drop procedure may change the value of this member. After the drop procedure returns, the toolkit uses the final value in initializing the operations member of the XmDropStartCallbackStruct passed to the initiator's drop start callbacks (the DragContext's XmNdropStartCallback callbacks).
The drop procedure may change the value of this member. After the drop procedure returns, the toolkit uses the final value in initializing the dropAction member of the XmDropStartCallbackStruct passed to the initiator's drop start callbacks (the DragContext's XmNdropStartCallback callbacks).
RELATED INFORMATION
XmDragContext (3), XmDragIcon (3), XmDropSiteConfigureStackingOrder (3), XmDropSiteEndUpdate (3), XmDropSiteQueryStackingOrder (3), XmDropSiteRegister (3), XmDropSiteStartUpdate (3), XmDropSiteUpdate (3), XmDropSiteUnregister (3), XmDropTransfer (3), and XmTargetsAreCompatible (3).