A drag and drop transaction consists of the following actions:

A drop can be between applications or within the same application. An application can be both source and destination of a drop, source only, destination only, or not participate in drag and drop at all.

The user can request help about a drop site, if available, by dragging to the drop site, and pressing KHelp (usually F1).

The user can cancel the drag at any time by pressing KCancel, usually Escape.

The drag icon consists of three parts:

In the following illustration, the running figure is the source icon, the arrow in the upper left is the state icon, and the rectangles with the corner folded over indicate a Copy is desired.

Figure 15-1. A Drag Icon

These parts can be combined (blended) and attached to each other in different ways. The default blending and attachment are shown in the previous illustration.

Parts of the drag icon may change shape or color as it is being dragged through potential drop sites, providing visual feedback about possible drop sites to the user. These changes are drag-over effects.

Applications can use the default drag icon effects, or provide more sophisticated or custom drag icons. The application or user can customize these drag-over effects in resource files.

A widget registered as a drop site may change visually as a drag icon passes over it. These visual cues are drag-under effects. The sensitive area of the widget is the part that responds to drag and drop. By default it is the whole widget, but applications can specify that only parts of the widget respond to drag and drop.

Various highlighting styles are possible:

Applications can use the default drag-under visual effects, or create more sophisticated or custom effects, such as special animation or sound effects.

Visual effects also take place during the drop:

These drop effects cannot be changed by the application or the user.

Applications can use drag and drop functionality on any of several levels:

A Simple Drag Receiver

This sample program displays a Label widget and registers it as a drop site. It accepts compound text, and supports only the Copy operation (that is, it does not support Move or Link).

When a valid drop is made on the Label widget, its HandleDrop routine changes the Label widget's label to compound text passed from the initiator.

The appropriate include files, the DropTransferCallback routine, the HandleDrop routine, and a few lines in the main routine to register the drop site are all that is needed to customize a Label widget to accept a drop and change its label in response. The details of this additional code are covered in later sections of this chapter.

Figure 15-2. A Label Widget Receiver Before and After Drag

/* file: DNDlabel.c */ #include <signal.h> #include <stdio.h> #include <X11/Xlib.h> #include <Xm/Xm.h> #include <Xm/BulletinB.h> #include <Xm/AtomMgr.h> #include <Xm/Label.h> #include <Xm/DragDrop.h> #include <X11/Xatom.h> #define MAX_ARGS 10 /* global variables */ Widget myDC; Atom COMPOUND_TEXT; /* This routine transfers information from the initiator */ static void TransferProc(w, closure, seltype, type, value, length, format) Widget w; XtPointer closure; Atom *seltype; Atom *type; XtPointer value; unsigned long *length; int format; { int n; Arg args[MAX_ARGS]; /* information from the drag initiator is passed in * compound compound text format. Convert it to compound * string and replace the Label label. */ if (*type = COMPOUND_TEXT) { n = 0; XtSetArg(args[n], XmNlabelString, XmCvtCTToXmString(value)); n++; XtSetValues(closure, args, n); } } /* This routine is performed when a drop is made. It decides what information it wants and uses TransferProc to transfer the data from the initiator */ static void HandleDrop(w, client_data, call_data) Widget w; XtPointer client_data, call_data; { XmDropProcCallback DropData; XmDropTransferEntryRec transferEntries[2]; XmDropTransferEntry transferList; Arg args[MAX_ARGS]; int n; DropData = (XmDropProcCallback)call_data; /* set the transfer resources */ n = 0; /* if the action is not Drop or the operation is not Copy, * cancel the drop */ if ((DropData->dropAction != XmDROP) || (DropData->operation != XmDROP_COPY)) XtSetArg(args[n], XmNtransferStatus, XmTRANSFER_FAILURE); n++; else { /* the drop can continue. Establish the transfer list * and start the transfer */ transferEntries[0].target = COMPOUND_TEXT; transferEntries[0].client_data = (XtPointer)w; transferList = transferEntries; XtSetArg(args[n], XmNdropTransfers, transferList); n++; XtSetArg(args[n], XmNnumDropTransfers, 1); n++; XtSetArg(args[n], XmNtransferProc, TransferProc); n++; } /* start the transfer or cancel */ XmDropTransferStart(DropData->dragContext, args, n); } /* This program creates a Label widget, which is * registered as a drop site. The label changes when compound * text is dropped on it. */ void main (argc, argv) unsigned int argc; char **argv; { Arg args[MAX_ARGS]; int n; Widget topLevel, BulletinB, Label; XtAppContext app_context; Atom importList[1]; /* make supporting widget structure for the Label widget */ topLevel = XtAppInitialize(&app_context, "XMTest", NULL, 0, &argc, argv, NULL, NULL, 0); n = 0; BulletinB = XmCreateBulletinBoard(topLevel, "BulletinB", args, n); XtManageChild(BulletinB); COMPOUND_TEXT = XmInternAtom(XtDisplay(topLevel), "COMPOUND_TEXT", False); /* create a Label widget */ n = 0; Label = XmCreateLabel(BulletinB, "title", args, n); XtManageChild(Label); /* register the label as a drop site */ importList[0] = COMPOUND_TEXT; n = 0; XtSetArg(args[n], XmNimportTargets, importList); n++; XtSetArg(args[n], XmNnumImportTargets, 1); n++; XtSetArg(args[n], XmNdropSiteOperations, XmDROP_COPY); n++; XtSetArg(args[n], XmNdropProc, HandleDrop); n++; XmDropSiteRegister(Label, args, n); XtRealizeWidget(topLevel); XtAppMainLoop(app_context); }

A Simple Drag Source

This program creates a ScrollBar widget which is to be used as a drag source. The normal action for Button 2 Press has been overridden to cause it to call the StartDrag routine, which causes the drag to begin. The program allows only the Copy operation, and will reply to requests for compound text.

When a drag is started on the ScrollBar, the default drag icons are used.

When a transfer request is received by the DragConvertProc routine, it returns the value of the scrollbar slider converted into compound text.

The code necessary to make a normal ScrollBar widget into a source for drag and drop is the appropriate include files, the DragConvertProc routine, the StartDrag routine, and translation and action commands. The details of this additional code are covered in later sections of this chapter.

Figure 15-3. A ScrollBar Widget as Drag Source

/* file: DNDscroll.c */ #include <signal.h> #include <stdio.h> #include <X11/Xlib.h> #include <Xm/Xm.h> #include <Xm/BulletinB.h> #include <Xm/ScrollBar.h> #include <Xm/AtomMgr.h> #include <Xm/DragDrop.h> #include <X11/Xatom.h> #define MAX_ARGS 10 /* global variables */ Widget scrollbar; Atom COMPOUND_TEXT; /* this routine returns the value of the scrollbar slider, * converted into compound text. */ static Boolean DragConvertProc(w, selection, target, typeRtn, valueRtn, lengthRtn, formatRtn, max_lengthRtn, client_data, request_id) Widget w; Atom *selection; Atom *target; Atom *typeRtn; XtPointer *valueRtn; unsigned long *lengthRtn; int *formatRtn; unsigned long *max_lengthRtn; XtPointer client_data; XtRequestId *request_id; { Widget dc; XmString cstring; static char tmpstring[100]; int *value; int n; Arg args[MAX_ARGS]; char *ctext; char *passtext; /* this routine processes only compound text */ if (*target != COMPOUND_TEXT) return(False); /* get the value of the scrollbar slider */ n = 0; XtSetArg(args[n], XmNvalue, &value); n++; XtGetValues(scrollbar, args, n); /* convert the slider value to compound text */ sprintf(tmpstring, "%d", value); cstring = XmStringCreateLocalized(tmpstring); ctext = XmCvtXmStringToCT(cstring); passtext = XtMalloc(strlen(ctext)+1); memcpy(passtext, ctext, strlen(ctext)+1); /* format the value for transfer. convert the value from * compound string to compound text for the transfer */ *typeRtn = COMPOUND_TEXT; *valueRtn = (XtPointer) passtext; *lengthRtn = strlen(passtext); *formatRtn = 8; return(True); } /* This routine is performed by the initiator when a drag * starts (in this case, when mouse button 2 was pressed). * It starts the drag processing, and establishes a drag * context. */ static void StartDrag(w, event) Widget w; XEvent *event; { Arg args[MAX_ARGS]; Cardinal n; Atom exportList[1]; /* establish the list of valid target types */ exportList[0] = COMPOUND_TEXT; n = 0; XtSetArg(args[n], XmNexportTargets, exportList); n++; XtSetArg(args[n], XmNnumExportTargets, 1); n++; XtSetArg(args[n], XmNdragOperations, XmDROP_COPY); n++; XtSetArg(args[n], XmNconvertProc, DragConvertProc); n++; XmDragStart(w, event, args, n); } /* translations and actions. Pressing mouse button 2 * overrides the normal scrollbar action and calls StartDrag * to start a drag transaction */ static char dragTranslations[] = "#override <Btn2Down>: StartDrag()"; static XtActionsRec dragActions[] = { {"StartDrag", (XtActionProc)StartDrag} }; /* This routine creates a window with a scrollbar in it. */ void main (argc, argv) unsigned int argc; char **argv; { Arg args[MAX_ARGS]; int n; Widget topLevel, BulletinB; XtAppContext app_context; Atom importList[1]; XtTranslations parsed_xlations; /* create widget structure for scrollbar widget */ topLevel = XtAppInitialize(&app_context, "DNDscroll", NULL, 0, &argc, argv, NULL, NULL, 0); COMPOUND_TEXT = XmInternAtom(XtDisplay(topLevel), "COMPOUND_TEXT", False); n = 0; BulletinB = XmCreateBulletinBoard(topLevel, "BBoard", args, n); XtManageChild(BulletinB); /* override button two press to start a drag */ parsed_xlations = XtParseTranslationTable(dragTranslations); XtAppAddActions(app_context, dragActions, XtNumber(dragActions)); /* create a scroll bar widget */ n = 0; XtSetArg(args[n], XmNtranslations, parsed_xlations); n++; XtSetArg(args[n], XmNorientation, XmHORIZONTAL); n++; XtSetArg(args[n], XmNwidth, 150); n++; scrollbar = XmCreateScrollBar(BulletinB, "testscroll", args, n); XtManageChild(scrollbar); XtRealizeWidget(topLevel); XtAppMainLoop(app_context); }

Text, List, Label, and Button widgets are automatically drag sources. Applications need do nothing further to use them. An application can allow any widget to be a drag source by establishing a callback when BTransfer is pressed within that widget. The application that owns the widget in which the drop was started is the initiator.

A drag icon, which is a pictorial representation of the data being dragged, replaces the normal cursor while the drag is in effect. The icon may change as it moves around the screen. The actual data is not being dragged, only a representation of it. The data is transferred to a new location only when the drop is made, through the drop transfer protocol.

Any widget can be registered as a drop site. Text and TextField widgets are automatically registered as drop sites. If an application wants to use these as drop sites, it does not need to register them separately.

The DropSite registry contains information about widgets that have been registered as drop sites. Although the drag icon can be dropped anywhere on the screen, only widgets that have been registered as drop sites can accept information from the initiator. The receiver is the application controlling the current drop site.

The "sensitive area" is the part of the widget that responds to drag and drop. By default, the sensitive area is the whole widget. However, the application can specify that only part of the widget is sensitive.

Widgets that are drop sites can be stacked on each other, with one widget partially or completely within the boundary of another. The sensitive areas of lower drop sites are clipped if they are covered by a higher widget.

The stacking order of the widgets with drop sites can be changed by the application.

The protocol describes how the initiator and receiver clients interact through the toolkit with each other.

Motif provides a number of Xt objects and widgets to encapsulate the underlying protocol; however, these are not mapped onto the screen:

Motif provides the following functions to support drag and drop processing:

Each drag source and drop site specifies what kinds of data types it can process, called targets. These targets are atoms, such as XA_STRING.

The DragContext resources XmNexportTargets and XmNnumExportTargets provide a list and number of the data types provided by the drag source. These are export targets.

The DropSite resources XmNimportTargets and XmNnumImportTargets provide a list and number of the data types accepted by the drop site. These are known as import targets.

Any number of targets may be listed for each source and site. A drop site is considered valid for a particular drag if at least one of its targets matches any of the source's targets and if the source and drop site operations are compatible.

An application can define anything it wants as a target. Be aware, however, that other applications might not recognize that target.

There are three ways that the initiator and receiver can interact with each other:

When a drag is started, the initiator provides a list of valid operations in the DragContext XmNdragOperations resource. When a drop site is registered, the receiver provides a list of operations it supports in the DropSite XmNdropSiteOperations resource. These lists are the values XmDROP_MOVE, XmDROP_COPY, or XmDROP_LINK, connected by the bitwise OR operator (|). For example, the following value means that Move and Copy are valid operations, but Link is not:

XmDROP_MOVE | XmDROP_COPY

The value XmDROP_NOOP indicates that there are no operations possible for a drop at the current site.

Callback structures for both DragContext and DropSite have operation and operations fields. The operations field lists all valid operations if a drop were to occur at this point. The operation field shows the operations that would happen if a drop occurred at this point. As the drag icon moves over different potential drop sites, the values in its callback structures change in response to what operations the drop sites allow. If there are no common operations between a drag source and a drop site, the operation and operations fields are set to XmDROP_NOOP, and the dropSiteStatus field is set to XmDROP_SITE_INVALID.

The user can specify an operation using key combinations discussed earlier in this chapter. The user can also change the operation at any time until the drop starts.

The initiator and the receiver need to be able to handle all the operations their application supports. If the operation is Move, the receiver first gets a copy of the data, then tells the initiator that it can delete the data. If the operation is Copy, both applications have the data, making two copies of it. If the operation is Link, there is only one copy of the data, and the receiver establishes a link to that copy.

This section provides an overview of the actions of the initiator client and the receiver client while a drag and drop transaction is in progress. The actions are covered in more detail later in the chapter.

Before a drag starts

When the drag starts (typically a BTransfer Press event)

During a drag

When the drop occurs

When data is transferred between initiator and receiver

After the drop has finished

The toolkit on the initiator side is in charge during the drag. The protocol in effect determines how it will find the information about drop sites that it needs to manage visuals, and how extensively the initiator and receiver clients are involved during the drag.

There are two kinds of drag protocol styles:

The code for the initiator is the same regardless of the protocol. The code for the receiver applications is the same except that in the dynamic mode, the receiver's XmNdragProc is called.

The drag protocol in use can change during the course of a drag. When the drag icon enters or leaves a top-level window, the source and potential drop receiver negotiate a mutually acceptable drag protocol, as described in Section 15.3.2, "Choosing the Protocol and Visual Style."

The user can specify which drag protocol to use or the application can specify the drag protocol in resource file.

The preregister drag protocol can be used with a minimum of additional coding in an application, because the toolkit manages the drag-over visual effects using the default drag icons specified in the XmScreen object. Or the application can override the default XmScreen icons with custom icons, but still allow the toolkit to manage the effects.

The dynamic drag protocol requires more work for the application program, but allows a receiver application to provide visual effects beyond the capabilities of the toolkit.

The drag protocol in use has an effect on the system performance as described later in this section.

myclient*dragInitiatorProtocolStyle: DRAG_PREFER_DYNAMIC
myclient*dragReceiverProtocolStyle:  DRAG_PREFER_DYNAMIC

When a drop is made, the receiver checks what action should happen:

The drop protocol is a superset of the Xt incremental and nonincremental protocol, with two main differences:

The drop protocol is handled by a DropTransfer widget created by XmDropTransferStart in the receiver client. The receiver creates a list of information and target types desired from the initiator, along with an XmNtransferProc to handle any processing needed during the transfer. The toolkit processes the requests one at a time, until it has finished with the list.

The receiver must call XmDropTransferStart, even if the number of transfer requests is zero. Otherwise, the initiator will keep waiting for a transfer request.

For each transfer request, the initiator's XmNconvertProc is called. This procedure reads and processes the request and returns the information.

Text and TextField widgets register themselves as drop sites. An application must register any other widgets it wants to use for drop sites. A widget may be registered as only one drop site.

XmDropSiteRegister registers a widget as a drop site, establishes callbacks to be used when a drag is made through the drop site or a drop is made in the drop site, and provides target and operation information. If the protocol is preregister, the information is stored in a database, which is read by the toolkit during the drag. If the drag protocol is dynamic, messaging is used to check for possible drop sites within a widget.

The application must register an XmNdropProc routine to establish a list of transfer requests and start the transfer. The other resources can be left at their default values if those values are acceptable to the application.

The optional XmNdragProc routine is executed only if the drag protocol is dynamic. It is called in response to events during the drag, and allows the receiver to provide additional drag-under effects or additional drag processing.

The XmNdropSiteOperations resource lists all operations that the drop site will support, combined by the bitwise OR operations (|). For example, the default value

XmDROP_COPY | XmDROP_MOVE

means that Copy and Move are valid operations, but Link is not. During a drag, the toolkit on the receiver side compares this list with the DragContext's XmNdragOperations list and the user-selected operation to arrive at the operation that will be performed if a drop occurs on this site, along with a list of all operations possible between the initiator and the current drop site.

If an application wants to use only one operation, such as Copy, it should set the XmNdropSiteOperations field to just that operation to ensure that the toolkit chooses the correct operation and drag icon during the drag and drop transaction.

Drop sites that represent copying devices, such as printers, or transformation devices, such as compilers, should perform a Copy rather than a Move if both are possible.

The XmNdropSiteActivity resource indicates whether the drop site is available for use:

The XmDropSiteUnregister function removes a widget from the DropSite registry. Once a widget is unregistered, it displays no drag-under visual effects and cannot accept a drop.

The difference between an unregistered drop site and an inactive drop site is that the inactive drop site is still registered; it still uses memory, but does not engage in any drag and drop transactions. One use for inactive drop sites is to provide the correct clipping on overlapping drop sites. An unregistered drop site is no longer involved in the drag and drop system. It is the same as a widget that was never registered.

The following code from the main routine in DNDlabel.c in "A Simple Drag Receiver" generates a simple drop site on a Label widget. The only target type it recognizes is compound text. The only operation it will accept is Copy. The other resources, including drag-under effects, are left at their default values.

Figure 15-4. A Label Widget

Label = XmCreateLabel(BulletinB, "title", args, n);
XtManageChild(Label);
/* register the label as a drop site */
importList[0] = COMPOUND_TEXT;
n = 0;
XtSetArg(args[n], XmNimportTargets, importList); n++;
XtSetArg(args[n], XmNnumImportTargets, 1); n++;
XtSetArg(args[n], XmNdropSiteOperations, XmDROP_COPY); n++;
XtSetArg(args[n], XmNdropProc, HandleDrop); n++;
XmDropSiteRegister(Label, args, n);
XtRealizeWidget(topLevel);
XtAppMainLoop(app_context);

Specially Shaped Drop Sites

The shape of a simple drop site can be specified as the union of a set of specified rectangles clipped by the associated widget.

If only part of the widget is to be sensitive to a drop, it is defined by a list of rectangles in the XmNdropRectangles resource. If the resource is NULL, the drop site is the smallest enclosing widget and the shape of the drop site is the shape of the widget.

The rectangles that make up the drop site do not need to be contiguous. All the noncontiguous segments of the drop site act as one; they are all highlighted the same way at the same time. A drop on one segment is the same as a drop on any of the other segments. This might look to the user as if there were several drop sites on a single widget, but the application handles nested drop sites differently from drop sites made of noncontiguous segments. Nested drop sites, whether simulated or real, may have different drag-under effects, targets, operations, or callback procedures.

The following example establishes a sensitive area shaped like a plus sign on a DrawnButton widget named Button2. Even if the drag icon is within the Button2 widget, no drag-under effects are shown until the drag icon is within the sensitive area. The area is visible only when a drag icon enters it and highlighting occurs. The sensitive area is the only part of the widget that accepts a drop. This code is not in one of the three example programs included in Section 15.2.1, "Complexity of Drag and Drop Programs," and Appendix B, "Drag and Drop Example Program."

Figure 15-5. Specially Shaped Drop Site

XRectangle plus[] = { {30, 0, 30, 30}, {0, 30, 90, 30}, {30, 60, 30, 30}, }; . . . n = 0; XtSetArg(args[n], XmNimportTargets, importList); n++; XtSetArg(args[n], XmNnumImportTargets, 1); n++; XtSetArg(args[n], XmNdropProc, HandleDrop); n++; XtSetArg(args[n], XmNdropRectangles, plus); n++; XtSetArg(args[n], XmNnumDropRectangles, 3); n++; XmDropSiteRegister(Button2, args, n);

Drag-Under Visual Effects

Drag-under visual effects are displayed only when the pointer is within the sensitive area of the drop site widget. Various drag-under styles can be chosen in the XmNanimationStyle DropSite resource:

XmDRAG_UNDER_HIGHLIGHT		A solid border around the sensitive area of the drop site is used to show the drop site is valid. This is the default value.
XmDRAG_UNDER_SHADOW_OUT		The sensitive area of the drop site looks pushed out when it is valid.
XmDRAG_UNDER_SHADOW_IN		The sensitive are of the drop site looks pushed in when it is valid.
XmDRAG_UNDER_PIXMAP		A custom pixmap is used to indicate the drop site is valid. The pixmap is specified in XmNanimationPixmap.
XmDRAG_UNDER_NONE		No indication is given that the drop site is valid.

The following illustration shows the default drag-under animation around the Label widget drop site.

Figure 15-6. Default Drag-Under Animation

If the value of XmNanimationStyle is XmDRAG_UNDER_PIXMAP, the resources XmNanimationPixmap, XmNanimationMask, and XmNanimationPixmapDepth are used to provide more information about the pixmap. If the depth does not match the depth of the window controlling the drop site widget, no animation occurs. Except for XmDRAG_UNDER_PIXMAP, the colors used for the visual effects are based on the colors of the widget associated with the drop site.

The dynamic protocol provides the most control over the drop site animation. It is the only way to get visual effects that do not remain the same for the duration of the drag icon's stay in the drop site, for example, a background that flashes.

The procedure registered in the DropSite's XmNdragProc resource is called only when the dynamic protocol is in effect. This procedure is optional. Applications that need to provide special drag-under effects or other special processing during a drag can do so with this procedure.

The XmNdragProc procedure is called in response to messages from the toolkit, before the initiator's equivalent drag callback. Fields in the callback structure provide information to the receiver about the drag.

The reason field in the callback structure indicates why the procedure was called.

The operations field lists all the operations that are valid for the drop site with the current drag source. The operations field is initialized by the toolkit as follows:

The operation field indicates the type of action a successful drop will perform. The toolkit initializes the operation field by taking the following steps, in order of precedence from highest to lowest:

The dropSiteStatus field provides an indication of whether a transfer between the initiator and this drop site could occur. The value that the toolkit selects for the dropSiteStatus field depends on the reason the XmNdragProc procedure was entered:

The XmNdragProc procedure can update operation, operations, or dropSiteStatus further during its execution. The final values for these fields are available to the initiator in its drag callback structures. If the receiver's XmNdragProc procedure is called more than once while the drag icon is within the drop site (for example, because of motion events), the values used by the toolkit when it initializes the drag callback operations, operation, and dropSiteStatus fields are the ones at the end of the previous call to XmNdragProc.

The animate field tells the toolkit who should provide the drag-under visual effects. It is initially set to True, but the XmNdragProc routine can set it to False.

The DragProcCallback routine in the DNDDemo.c program in Appendix B, "Drag and Drop Example Program," is an example of a DragProc routine. It can process every drag message, changes the operations, operation, and dropSiteStatus as necessary, and sets the animate field to True, allowing the toolkit to manage the drag-under effects. The DragProcCallback routine is shown in the next section of this chapter.

Simulating Nested Drop Sites

A widget can be registered as only a single drop site. However, if the application needs one or more drop sites entirely enclosed within another drop site, there are two ways to accomplish this:

• Widgets that contain other widgets that are drop sites should be registered as composite drop sites as described earlier in this chapter.

  This method allows the toolkit to manage drop site messages and drag-under effects for each nested drop site.

• An application can simulate multiple drop sites on a single widget in the XmNdragProc and XmNdropProc routines. Because the XmNdragProc routine is executed only in the dynamic drag protocol mode, this method would not work if the drag procotol chosen is preregister.

  This method requires that the application manage all drag-under effects, because the toolkit is not aware of the simulated nesting.

To simulate nested drop sites on a single widget:

1. Register the widget as a single active drop site. Set XmNdropSiteOperations to all the operations possible for any of the nested drop sites. Set XmNimportTargets to all the targets possible for any of the nested drop sites. Register an XmNdragProc routine to provide any special drag-under effects for the simulated drop sites.

   The operations, operation, and dropSiteStatus fields are initialized by the toolkit only when this outer drop site is entered or left. The simulated drop sites must be managed by the application.

2. When either XmNdragProc or XmNdropProc is called, check the x and y fields in the callback structure to determine which of the nested drop sites contains the pointer.

3. If the pointer is within a simulated nested drop site, update the callback fields as follows:

   • When the pointer enters the simulated nested drop site, save the value of the operations and operation fields.

   • Remove any operations from the operations field that do not apply to the simulated drop site.

   • Set operation to the valid operation preferred by the simulated drop site, or to XmDROP_NOOP if the operations list does not contain the preferred operation.

   • The dropSiteStatus field must reflect the status of the simulated drop site so that the initiator can manage drag-over effects correctly:

     - Set the dropSiteStatus to XmDROP_SITE_VALID if the operation is allowed in the simulated drop site and if there is at least one target in common between the simulated drop site and the initiator. (Use the XmTargetsAreCompatible routine to check the targets.)

     - Set the dropSiteStatus to XmDROP_SITE_INVALID if the operation is not allowed in the simulated drop site, if there are no targets in common, or if the operation is XmDROP_NOOP.

   • Display appropriate drag-under visual effects.

   • When the pointer leaves the simulated drop site, restore the original values of operations and operation that apply to the outer drop site.

4. If the pointer is not within a simulated drop site, but drops are allowed in the outer drop site, update the fields as described in the previous step.

5. If the pointer is not within a simulated drop site, and drops are not allowed in the outer drop site, set the dropSiteStatus field to XmDROP_SITE_INVALID.

If the preregister protocol is in effect, the simulated drop sites cannot be managed during the move, because XmNdragProc is not performed; but they can be managed at the drop with XmNdropProc.

In the following example, only the top-level window, DNDDemo, is registered as a drop site. The user can create rectangles within the window that then act like drop sites themselves. The user can drag and drop colors from one of the six buttons in the lower part of the window onto the rectangles to change the color of the rectangle. However, these rectangles are not registered drop sites, they are simulated.

The user can also drag these rectangles to new locations.

Figure 15-7. Simulated Drop Sites

The RegisterDropSite routine registers the DrawingArea widget as a drop site. The list of operations and targets may not be valid for each simulated drop site, but are valid for other simulated drop sites.

RegisterDropSite(w) Widget w; { Display *display = XtDisplay(w); Atom targets[3]; Arg args[5]; int n = 0; /* Only accept moves or copies */ XtSetArg(args[n], XmNdragOperations, XmDROP_COPY | XmDROP_MOVE); n++; /* set all possible targets for any of the * nested drop sites */ targets[0] = XmInternAtom(display, "_MY_RECTANGLE", False); targets[1] = XmInternAtom(display, "BACKGROUND", False); targets[2] = XmInternAtom(display, "PIXMAP", False); XtSetArg(args[n], XmNimportTargets, targets); n++; XtSetArg(args[n], XmNnumImportTargets, 3); n++; /* register a dragProc - necessary for simulating nested * drop sites */ XtSetArg(args[n], XmNdragProc, DragProcCallback); n++; /* register a dropProc */ XtSetArg(args[n], XmNdropProc, DropProcCallback); n++; XmDropSiteRegister(w, args, n); }

The XmNdragProc routine, DragProcCallback, is called whenever a drag icon enters the registered drop site (the top level window). The RectFind routine from DNDDraw.c in Appendix B, "Drag and Drop Example Program," determines if the pointer is in a simulated drop site. The CheckTargets routine determines if the object being dragged is one of the six colors (bgFound) or one of the created rectangles (rectFound). (The value pixFound to represent a pixmap being dragged is coded in this routine, but not in the rest of the program.)

The only drag-under visual is displayed when a color is dragged to a rectangle. The outline of the rectangle is highlighted.

The entire DragProcCallback routine is too long to be listed in its entirety here. The section dealing with the drop site enter message is used as an example.

static void DragProcCallback(w, client, call) Widget w; XtPointer client; XtPointer call; { XmDragProcCallbackStruct *cb = (XmDragProcCallbackStruct *) call; Display *display = XtDisplay(w); Boolean rectFound, bgFound, pixFound; static unsigned char initial_operations; static unsigned char initial_operation; RectPtr rect; CheckTargets(cb->dragContext, display, &rectFound, &bgFound, &pixFound); switch(cb->reason) { case XmCR_DROP_SITE_ENTER_MESSAGE: /* save the value of the operations and operation * fields */ initial_operations = cb->operations; initial_operation = cb->operation; rect = RectFind(cb->x, cb->y); /* Remove any operations for the operations field * which do not apply to the simulated drop site. */ if (rect) { if (bgFound || pixFound) { cb->operations = XmDROP_COPY; RectHighlight(w, rect); } else if (rectFound) { cb->operations = cb->operations & (XmDROP_COPY | XmDROP_MOVE); RectUnhighlight(w); } } else { cb->operations = initial_operations & (XmDROP_COPY | XmDROP_MOVE); RectUnhighlight(w); } /* Set operation to the valid operation preferred * by the simulated drop site or to XmDROP_NOOP * if the operations list does not contain the * preferred operation. */ if (rect) { if (bgFound || pixFound) { if (cb->operations & XmDROP_COPY) cb->operation = XmDROP_COPY; else cb->operation = XmDROP_NOOP; } else if (rectFound) { if (cb->operations & XmDROP_MOVE) cb->operation = XmDROP_MOVE; else if (cb->operations & XmDROP_COPY) cb->operation = XmDROP_COPY; else cb->operation = XmDROP_NOOP; } } else { if (rectFound) { if (cb->operations & XmDROP_MOVE) cb->operation = XmDROP_MOVE; else if (cb->operations & XmDROP_COPY) cb->operation = XmDROP_COPY; else cb->operation = XmDROP_NOOP; } else cb->operation = initial_operation; } /* * Set dropSiteStatus to XmDROP_SITE_INVALID if * the operation field is XmDROP_NOOP, or if there * are no common targets between the source and * the nested drop site. Otherwise, set * dropSiteStatus to XmDROP_SITE_VALID. */ if (cb->operation == XmDROP_NOOP || (rect && (!rectFound && !bgFound && !pixFound)) || (!rect && !rectFound)) cb->dropSiteStatus = XmINVALID_DROP_SITE; else cb->dropSiteStatus = XmVALID_DROP_SITE; /* * Display appropriate drag-under visuals. Only * highlight the rectangle if we are changing * rectangle attributes. */ if (rect && bgFound || pixFound && cb->dropSiteStatus == XmVALID_DROP_SITE) RectHighlight(w, rect); break; case XmCR_DROP_SITE_LEAVE_MESSAGE: . . .

The initiator client must be able to recognize the BTransfer Press event within a widget it allows to be a drag source. It may have to override an already-assigned translation for the widget.

The following example from the main routine of DNDscroll.c in "A Simple Drag Source" overrides the existing mouse button 2 translation for the ScrollBar widget, and maps it to the StartDrag routine, which will start the drag transaction.

static char dragTranslations[] = 
     "#override <Btn2Down>: StartDrag()";
static XtActionsRec dragActions[] = 
     { {"StartDrag", (XtActionProc)StartDrag}, };
     .
     .
XtTranslations parsed_xlations;
     .
     .
/* override button two press to start a drag */
parsed_xlations = XtParseTranslationTable(dragTranslations); 
XtAppAddActions(app_context, dragActions,
                  XtNumber(dragActions));
/* create a scroll bar widget */ 
n = 0;
XtSetArg(args[n], XmNtranslations, parsed_xlations); n++;
scrollbar = XmCreateScrollBar(BulletinB, "testscroll",
                                args, n);   
XtManageChild(scrollbar);

Translation may be more complicated in some editable widgets, in which BTransfer Click is used for primary transfer, and BTransfer Motion is used for drag and drop.

Not every widget in an application can be a drag source. Text, Label, Button, and List widgets are automatically defined as drag sources. Other widgets must have a translation for BTransfer assigned to them, establish DragContext resources for the widget, and call the XmDragStart routine to become drag sources. If the user tries to drag objects from a widget that is not recognized as a drag source by either the toolkit or the source application, nothing happens.

The XmDragStart function initiates a drag and creates a DragContext widget. At a minimum, the XmNconvertProc DragContext resource, must be specified. Other resources are optional, for example, those specifying drag-over visual effects.

The XmNdragOperations resource lists all the operations that the initiator will support for this drag source, combined by the bitwise OR operation (|). During a drag, the toolkit compares this list with the receiver's XmNdropSiteOperations list and the user-selected operation to arrive at the operation that will be performed if a drop occurs on this site.

If an application wants to use only one operation, it should set the XmNdragOperations resource to just that operation to ensure that the correct operation and drag icon are chosen by the toolkit during the drag and drop transaction.

The following example from DNDscroll.c in "A Simple Drag Source" establishes a target type of compound text and an operation of Copy, then establishes a DragContext for this transaction with XmDragStart. This drag source does not have any custom drag icons or any drag callbacks.

static void StartDrag(w, event)
Widget  w;
XEvent  *event;
{
   Arg             args[MAX_ARGS];
   Cardinal        n;
   Atom            exportList[1];
   /* establish the list of valid target types */
   exportList[0] = COMPOUND_TEXT;
   n = 0; 
   XtSetArg(args[n], XmNexportTargets, exportList); n++;
   XtSetArg(args[n], XmNnumExportTargets, 1); n++;
   XtSetArg(args[n], XmNdragOperations, XmDROP_COPY); n++;
   XtSetArg(args[n], XmNconvertProc, DragConvertProc); n++;
   XmDragStart(w, event, args, n);
}

If drag or drop callbacks are desired, they are added to the DragContext's callback resources. For example, a callback procedure named EnterCallBack that is performed when the pointer enters an active drop site could be added as follows:

Widget         dc;
   .
   .
   .
   dc = XmDragStart(w, event, args, n);
   XtAddCallback(dc, XmNdropSiteEnterCallback, EnterCallBack,
                   NULL); 

XtGetValues is used to check the values of widgets resources established as drag sources earlier in the application, and XtSetValues is used to update these values. The widget ID used is the DragContext, not the source widget ID, so that the change applies only to the widget during the drag.

If the widget is a predefined drag source (Text, Label, Button, or List), overriding the default behavior becomes more complex. The widget calls XmDragStart when the drag starts, and the application cannot call XmDragStart again for the widget. Instead, it must update the existing DragContext. First it must find the DragContext for the widget, then establish the new behavior. One possible means to accomplish this is as follows:

For instance, Text allows the Copy and Move operations. If an application can support only Copy, it must update the DragContext's XmNdragOperations resource.

When the user moves the mouse, a drag icon representing the object being dragged moves around the screen instead of the usual pointer. As the icon is dragged over portions of the screen, the icon may change to show the status of a possible drop. These drag-over visual effects help the user know how to proceed with the drag.

There are four ways to provide drag-over visual effects:

If the application provides custom icons and they are unsuitable for some reason, the toolkit defaults to the XmScreen drag-over visuals.

The drag icon consists of a source icon, optionally combined with a state icon and an operation icon.

Each drag icon has a hotspot. Since a drag icon could be quite large, the hotspot provides a single pixel that is used in providing drag-over and drag-under effects. For example, if the drag icon moves into the area of a valid drop site, neither the drag icon or the drop site will provide visual clues until the hotspot has moved into the area. By default, the hotspot is the upper left corner of the state icon.

In the following illustration, the running figure is the source icon, the state icon is the arrow in the corner, and the operation icon shows a Copy will happen if a drop is made. The default blending and attachment values are used.

Figure 15-8. A Drag Icon

Source Icon

The source icon is a picture representing the object being dragged. It can be either a pixmap or cursor. The client can specify a custom pixmap in the DragContext resource XmNsourcePixmapIcon or a custom cursor in the XmNsourceCursorIcon resource. If these resources are NULL or not usable (too large, not a bitmap, or created on a different screen, for example), the default cursor given in the XmScreen resource XmNdefaultSourceCursorIcon is used.

The pixmap icon is used with the preregister visual style. The colormap is based on the source widget. The cursor icon is used for the dynamic visual style.

The following illustration shows the default source icons for general purpose, List, Label, and Text widgets.

Figure 15-9. Source Icons

*.validCursorIcon:          green
*.invalidCursorIcon:        red
*.noneCursorIcon:           yellow

Operation Icon

The operation icon is a cursor that indicates what operation is to happen when the drop is made. The default operation icons are the values of the XmScreen resources XmNdefaultMoveCursorIcon, XmNdefaultCopyCursorIcon, and XmNdefaultLinkCursorIcon.

A custom operation icon can be specified in the DragContext resource XmNoperationCursorIcon. The icon should be changed as the operation changes, using the drag callbacks. If this resource is NULL, not a bitmap, or not defined on the same screen as XmScreen, the default XmScreen icons are used.

The following illustration shows the default Copy, Link, and Move operation icons.

Figure 15-10. Operation Icons

If the operation in effect is XmDROP_NOOP, meaning that no operation is possible, then the operation icon is left blank, as shown in the following illustration. This condition also sets the dropSiteStatus to XmDROP_SITE_INVALID.

Figure 15-11. Copy and Noop Drag Icons

Drag Icon Blending and Attachment

The client can specify which of the three icons to mix together to form the drag icon with the XmNblendModel DragContext resource:

XmBLEND_ALL		Use the source icon, state icon, and operation icon. The hotspot comes from the state icon. This is the default value. The order listed is also the order of the blend.
XmBLEND_STATE_SOURCE		Use only the source icon and state icon. The hotspot comes from the state icon.
XmBLEND_JUST_SOURCE		Use only the source icon. The hotspot comes from the source icon.
XmBLEND_NONE		Do not display any drag icon. The client handles all drag-over effects.

The XmNattachment DragIcon resource specifies where the state and operation icons will be placed on the source icon. The default placement is both the state and operation icons at the attachment point of the source icon, with the operation icon on top. The default value is XmATTACH_NORTH_WEST.

XmNoffsetX and XmNoffsetY are used to place the icon relative to the attachment point.

If the attachment point is XmATTACH_HOT, the state and operation icons are attached to the source icon at a point the same x and y distance from the upper left corner of the source icon as the pointer is from the upper left corner of the widget containing the source. This attachment style is particularly useful when the application makes a custom source icon that exactly reflects the source widget at the time the drag starts.

In the following illustration, the custom source icon is an outline of the scrollbar. When the drag was started, the pointer was on the slider. The operation and state icons are placed at the same location on the source icon.

Figure 15-12. An Attach_Hot Icon

When the state or operation icon is blended with a source icon, a specified point of the icon's XmNpixmap is aligned with the upper left corner of the source icon. The resulting XmNpixmap is large enough to include both, and the resulting XmNmask has 1 bits wherever either the source icon or source mask did.

If a dynamic cursor style is being used, and the resulting blended cursor is too large for the screen, the blending is done with the XmScreen XmNdefaultSourceCursorIcon instead of the DragContext's XmNsourceCursorIcon. If it is still too large, it is clipped relative to the hotspot (that is, if the hotspot is at an edge, the other edge is clipped; if the hotspot is in the center, opposite edges are clipped equally).

Creating a Drag Icon

Any of the three parts of a drag icon can be customized: the source icon, the state icon, and the operation icon.

Use the XmCreateDragIcon function to create any of these parts. The XmNattachment resource is not used for the source icon. The other resources specify pixmap, size, and hotspot details. The DragContext XmNblendModel resource indicates which hotspot is used for the entire drag icon.

The following example from DNDDemo.c in Appendix B, "Drag and Drop Example Program," creates a source icon from a bitmap. The source icon is the palette and the state icon is the paintbrush. (Actually, the state icon is not shown when the drag starts, because the blend style is XmBLEND_JUST_SOURCE. It is shown here as if the blend style were XmBLEND_ALL.)

Figure 15-13. Custom Source Icon

The ColorRect function is called when a drag starts from one of the color rectangles in the lower portion of the window. Among its other duties, it establishes the drag icon from source bits from the DNDDraw.c file in Appendix B, "Drag and Drop Example Program."

/* If the server will handle a large icon, create one */ if (appInfo->maxCursorWidth >= ICON_WIDTH && appInfo->maxCursorHeight >= ICON_HEIGHT) { source_bits = SOURCE_ICON_BITS; source_mask = SOURCE_ICON_MASK; state_bits = STATE_ICON_BITS; state_mask = STATE_ICON_MASK; width = ICON_WIDTH; height = ICON_HEIGHT; } else { /* If the server will handle a small icon, create one */ source_bits = SMALL_SOURCE_ICON_BITS; source_mask = SMALL_SOURCE_ICON_MASK; state_bits = SMALL_STATE_ICON_BITS; state_mask = SMALL_STATE_ICON_MASK; width = SMALL_ICON_WIDTH; height = SMALL_ICON_HEIGHT; } /* Create the drag cursor icons */ sourceIcon = GetDragIconFromBits(w, source_bits, source_mask, width, height, background, foreground); stateIcon = GetDragIconFromBits(w, state_bits, state_mask, width, height, background, foreground); /* Setup the arglist for the drag context that is * created at drag start */ n = 0; . . . XtSetArg(args[n], XmNsourceCursorIcon, sourceIcon); n++; XtSetArg(args[n], XmNstateCursorIcon, stateIcon); n++; . . . /* start the drag. This creates a drag context. */ myDC = XmDragStart(w, event, args, n); }

The GetDragIconFromBits function turns the bits into a bitmap.

static Widget GetDragIconFromBits(w, bits, mask, width, height, background, foreground) Widget w; char *bits; char *mask; Dimension width; Dimension height; Pixel background; Pixel foreground; { Pixmap icon, iconMask; Display *display = XtDisplay(w); icon = XCreateBitmapFromData(display, DefaultRootWindow(display), bits, width, height); iconMask = XCreateBitmapFromData(display, DefaultRootWindow(display), mask, width, height); return(GetDragIcon(w, icon, iconMask, width, height, background, foreground)); }

The GetDragIcon function uses the bitmap created by the GetDragIconFromBits function to create a drag icon.

static Widget GetDragIcon(w, icon, iconMask, width, height, background, foreground) Widget w; Pixmap icon; Pixmap iconMask; Dimension width; Dimension height; Pixel background; Pixel foreground; { Widget dragIcon; Arg args[10]; int n = 0; XtSetArg(args[n], XmNhotX, ICON_X_HOT); n++; XtSetArg(args[n], XmNhotY, ICON_Y_HOT); n++; XtSetArg(args[n], XmNwidth, width); n++; XtSetArg(args[n], XmNheight, height); n++; XtSetArg(args[n], XmNmaxWidth, appInfo->maxCursorWidth); n++; XtSetArg(args[n], XmNmaxHeight, appInfo->maxCursorHeight); n++; XtSetArg(args[n], XmNbackground, background); n++; XtSetArg(args[n], XmNforeground, foreground); n++; XtSetArg(args[n], XmNpixmap, icon); n++; XtSetArg(args[n], XmNmask, iconMask); n++; dragIcon = XmCreateDragIcon(w, "dragIcon", args, n); return(dragIcon); }

Callbacks notify the initiator of how the drag is proceeding. The receiver's XmNdragProc (if any) is first notified of the action and given a chance to update the operation, operations, and dropSiteStatus fields in its callback structure. The new values are available to the initiator's drag callback in the appropriate callback structure.

These drag callbacks are all optional. They enable the initiator to monitor the progress of the drag and manage its visual effects accordingly. Otherwise, the toolkit on the initiator side handles the drag-over effects.

Callback structures for these routines contain information about the drag. The callback structures for XmNdragMotionCallback, XmNoperationChangedCallback, and XmNdropSiteEnterCallback contain the operations, operation, and dropSiteStatus fields (among others), which are initialized by the toolkit before the callback is called.

The operations field lists all operations possible for a drop on the current site, whether the site is registered as a DropSite or not. The toolkit initializes the operations field as follows:

The operation field shows the operation that will occur if a drop happens at the current cursor location. It is initialized as follows:

The dropSiteStatus field in the callback structure indicates if the drag icon is over a valid drop site, an invalid drop site, or no drop site. The callback procedure can use this information to display the appropriate drag-over visuals. The toolkit initializes the dropSiteStatus field as follows:

If the application has not stored the DragContext ID in a global location, these callbacks can find the DragContext ID by passing the timeStamp field from the callback structure to the XmGetDragContext function.

This example shows a callback that is called when a new drop site is entered. It checks the validity of the drop site, and uses one of three custom source icons, depending on the status.

static void EnterCB(w, client_data, call_data)
Widget          w;
XtPointer       client_data, call_data;
{
   XmDragContext                   dc;
   XmDropSiteEnterCallback         EnterData;
   Cardinal                        n;
   Arg                             args[MAX_ARGS];
   dc = (XmDragContext)w;
   EnterData = (XmDropSiteEnterCallback )call_data;
   n = 0;
   if (EnterData->dropSiteStatus == XmVALID_DROP_SITE) {
      XtSetArg(args[n], XmNsourceCursorIcon,
                 GetValidIcon(w)); n++;
      XtSetValues(dc, args, n);
      }
   if (EnterData->dropSiteStatus == XmINVALID_DROP_SITE) {
      XtSetArg(args[n], XmNsourceCursorIcon,
                 GetInvalidIcon(w)); n++;
      XtSetValues(dc, args, n);
      }
   if (EnterData->dropSiteStatus == XmNO_DROP_SITE) {
      XtSetArg(args[n], XmNsourceCursorIcon,
                 GetNeutralIcon(w)); n++;
      XtSetValues(dc, args, n);
      }
}

If a drag callback is desired, it is added to the DragContext's callback resources.The following example adds a callback named EnterCB that is performed when the pointer enters an active drop site:

Widget       dc;
   dc = XmDragStart(w, event, args, n);
   XtAddCallback(dc, XmNdropSiteEnterCallback, EnterCB,
                   NULL);

The initiator can find information about the current drop site with the XmDropSiteRetrieve function. It must pass in the DragContext, so that the toolkit knows what drop site the request is for. The initiator can find the value of any drop site resource except the callback routines

The following example gets the number and list of import targets for a drop site. The example shows a drop site enter callback, but it could be in any of the initiator's drag callbacks.

XmDropSiteEnterCallback      DragData;
     .
     .
     .
n = 0;
XtSetArg(args[n], XmNimportTargets, &importTargets); n++;
XtSetArg(args[n], XmNnumImportTargets,
           &numImportTargets); n++;
XmDropSiteRetrieve(DragData->DragContext, args, n);

The drag in progress can be cancelled in either of two ways. Both ways are treated the same by the toolkit.

The initiator is notified of the cancel by the XmNdropStartCallback with a dropAction field value of XmDROP_CANCEL.

The receiver is notified by a XmCR_DROP_SITE_LEAVE_MESSAGE message. This message is processed by the XmNdragProc in the dynamic protocol mode. This allows any drag-under effects to be undone.

When a drop occurs (except for a Cancel), a message is sent from the toolkit on the initiator side to the receiver, and the receiver's XmNdropProc is called. Fields in its callback structure provide information about the drop to the receiver.

The operations, operation, and dropSiteStatus fields are initialized by the toolkit in a similar manner to that described for the receiver's XmNdragProc earlier in this chapter.

The XmNdropProc routine can update the operations, operation, and dropSiteStatus fields further. The final values are available to the initiator in its drop callback structures.

The dropAction field indicates if a normal drop is requested, or if the user requested help. For information about processing a help request, refer to Section 15.6.4, "Providing Help."

If the receiver takes too long before ending the XmNdropProc routine, the toolkit will cause the drag to time out. Therefore, if the receiver needs to do any processing before the transfer other than verifying that a transfer can take place, it should start a new process and end the XmNdropProc routine.

Either the XmNdropProc routine or one of its subprocedures must start a transfer by calling XmDropTransferStart. The initiator waits for a transfer request to finish its part in the drop. If a drop is not possible, the drop is cancelled as described below. If a drop is possible, the XmNdropProc routine provides the appropriate details to start the transfer.

The XmNdropProc procedure creates a list of DropTransfer entries containing target and client-specific information for each transfer desired. There is a separate entry for each data-target type combination. For example, if the data is desired in both TEXT and COMPOUND_TEXT forms, there would be two entries on the list. This list and the number of items in the list are used by XmDropTransferStart to start the transfer.

The receiver establishes the values of the DropTransfer resources before calling XmDropTransferStart. Following are the DropTransfer resources:

The following example from DNDlabel.c in "A Simple Drag Receiver" creates a transfer request list of one transfer entry, asking that the initiator send its data in compound text format. Copy is the only action it accepts; the rest result in a cancelled drop. The DropTransferCallback routine receives and processes the data from the initiator.

static void HandleDrop(w, client_data, call_data)
Widget          w;
XtPointer       client_data, call_data;
{
   XmDropProcCallback      DropData;
   XmDropTransferEntryRec  transferEntries[2];
   XmDropTransferEntry     transferList;
   Arg                     args[MAX_ARGS];
   int                     n;
   DropData = (XmDropProcCallback)call_data;
   /* set the transfer resources */
   n = 0; 
   /* if the action is Help, or the operation is not Copy, 
    *cancel the drop */
   if ((DropData->dropAction != XmDROP) ||
       (DropData->operation != XmDROP_COPY)) 
      XtSetArg(args[n], XmNtransferStatus,
                 XmTRANSFER_FAILURE); n++;
   else {
      /* the drop can continue.  Establish the transfer list
       * and start the transfer */
      transferEntries[0].target = COMPOUND_TEXT;
      transferEntries[0].client_data = (XtPointer)w;
      transferList = transferEntries;
      XtSetArg(args[n], XmNdropTransfers, transferList); n++;
      XtSetArg(args[n], XmNnumDropTransfers, 1); n++;
      XtSetArg(args[n], XmNtransferProc,
                 DropTransferCallback); n++;
      }
   /* start the transfer or cancel */ 
   XmDropTransferStart(DropData->dragContext, args, n);
}

If the program could accept transfers in more than one target type, for example, TEXT and COMPOUND_TEXT, then a separate transfer entry is needed for each request:

transferEntries[0].target = COMPOUND_TEXT;
transferEntries[1].target = TEXT;
     .
     .
     .
XtSetArg(args[n], XmNnumDropTransfers, 2); n++;

The toolkit on the receiver side is in charge of the transfer procedure. Information about the transfer is stored in a DropTransfer widget, which is created by the XmDropTransferStart routine.

Before calling XmDropTransferStart, the receiver stores a list of DropTransfer transfer entries in the XmNdropTransfers resource. Each entry contains target and client-specific information for each transfer desired. It also registers a procedure to receive transfers from the initiator in the XmNtransferProc resource. These resources, along with the other DropTransfer resources, are used by the XmDropTransferStart function.

The toolkit processes the items on the list, one at a time, decrementing XmNnumDropTransfers each time. When the XmNnumDropTransfers value is zero, the drop is finished. The toolkit on the receiver side sends a message to the initiator, whose XmNdropFinishCallback is then called.

If XmNincremental is True, the Xt selection incremental transfer protocol is used between the toolkit and the receiver, regardless of what the initiator sent. Refer to the Xt documentation for details of how to use incremental transfer. If the value is False, the transfer between the toolkit and the receiver is made in one pass, regardless of how the initiator sent it.

The XmNtransferProc routine receives each transfer from the initiator. If more than one target type is acceptable to the receiver, this procedure needs to check which target type was used in this transfer, and process the transferred data accordingly.

The XmNtransferProc routine can examine and update the DropTransfer resources during the transfer with XtGetValues and XtSetValues.

The XmDropTransferAdd routine is used to add to the transfer list after the transfer has begun. For example, this routine is used when a Move operation is performed, to add a new transfer entry record telling the initiator to delete the data. It can be used in other situations where the entire transfer list is not known when XmDropTransferStart is called.

If there are problems with the drop, it can be cancelled as described later in the chapter.

The following example from DNDlabel.c in "A Simple Drag Receiver" receives compound string data from the initiator, and uses it to replace the label of the Label widget.

static void TransferProc(w, closure, seltype, type,
                           value, length, format) 
Widget           w;
XtPointer        closure;
Atom             *seltype;
Atom             *type;
XtPointer        value;
unsigned long    *length;
int              format;
{
   int         n;
   Arg         args[MAX_ARGS];
   /* information from the drag initiator is passed in
    * compound  text format.  Convert it to compound string
    * and replace the Label label. */
   if (*type = COMPOUND_TEXT) {
      n = 0;
      XtSetArg(args[n], XmNlabelString,
                 XmCvtCTToXmString(value)); 
      n++;
      XtSetValues(closure, args, n);
      } 
}

If the program is able to handle more than one target type, this routine needs to check for them all. For instance:

   if (*type = COMPOUND_TEXT) {
      /* code to change the label to the compound text
         passed */
      }
   else if (*type = TEXT) {
      /* code to change the label to the text passed */
      }

A drop can be cancelled only by the receiver, from the XmNdropProc procedure or any subroutine it calls, such as XmNtransferProc. To cancel a drop:

The transfer will be cancelled at the next transfer request. The drop is over, and the initiator's XmNdropFinishCallback and XmNdragDropFinishCallback routines are called.

The following example is from a program's XmNdropProc routine:

XtSetArg(args[n], XmNtransferStatus,
           XmTRANSFER_FAILURE); n++;
XtSetArg(args[n], XmNnumDropTransfers, 0); n++;
XmDropTransferStart(DropData->dragContext, args, n);

It might not always be obvious to the user what the result of dropping a particular source on a drop site might be. The user can request more information about the drop site by pressing KHelp while the drag icon is over the drop site.

When the user presses KHelp, the receiver's XmNdropProc routine is called with a value of XmDROP_HELP in the dropAction field of its callback structure. If the receiver supports help, it should post a dialog, providing information about the type of drop this site expects, and what it will do when a successful drop occurs.

The receiver should then exit the XmNdropProc routine without waiting for a response from the user. When the XmNdropProc routine has finished, the initiator's XmNdropStartCallback is called with a dropAction of XmDROP_HELP if the initiator has registered that callback. The initiator is not expected to do anything at this point, but it could provide special processing such as changing the drag icon.

Typically, the help dialog allows the user the opportunity to continue the drop or to cancel the drop. If more than one operation is possible, the dialog should explain the consequences of each operation and let the user select one. The dialog procedure may change the operation based on the user's selection:

In either case, the help procedure must call XmDropTranferStart before it ends to either start the transfers or notify the initiator that no transfers will be requested.

The receiver may want to issue help information if a drop is considered invalid, even if the user has not requested it. If so, the receiver's XmNdropProc sets the dropAction field to XmDROP_HELP, and displays the help dialog as if help had been requested.

The following example taken from DNDDemo.c in Appendix B, "Drag and Drop Example Program," shows how the help dialog shown in the illustration was created.

Figure 15-14. Help Dialog

The XmDropProc DropProcCallback routine checks if the drop is normal or if there is a request for help.

static void DropProcCallback(w, client, call)
Widget w;
XtPointer client;
XtPointer call;
{
    XmDropProcCallbackStruct *cb = 
                 (XmDropProcCallbackStruct *)call;
    if (appInfo->highlightRect != NULL)
        RectUnhighlight(w);
    if (cb->dropAction != XmDROP_HELP)
        HandleDrop(w, call);
    else
        HandleHelp(w, call);
}

The HandleHelp routine displays the help dialog. The text presented in the dialog depends on the drop site and the operation. Callback routines are registered to be performed when either of the dialog pushbuttons is pressed.

static void HandleHelp(w, call)
Widget w;
XtPointer call;
{
    XmDropProcCallbackStruct *cb =
                     (XmDropProcCallbackStruct *)call;
    static XmDropProcCallbackStruct client;
    Boolean                 rectFound, bgFound, pixFound;
    XmString                helpStr;
    RectPtr                 rect;
    Arg                     args[5];
    XmString                tempStr, buttonArray[2];
    int                     n = 0;
    /* the drop is valid until it is determined invalid */
    cb->dropSiteStatus = XmVALID_DROP_SITE;
    /* if we haven't created a help dialog, create one now */
    if (helpDialog == NULL) {
        XtSetArg(args[n], XmNdialogStyle, 
             XmDIALOG_FULL_APPLICATION_MODAL); n++;
        XtSetArg(args[n], XmNtitle, "Drop Help"); n++;
        helpDialog = XmCreateMessageDialog(topLevel, "Help", 
             args, n);
        n = 0;
        buttonArray[0] = XmStringCreateSimple("Move");
        buttonArray[1] = XmStringCreateSimple("Copy");
        XtSetArg(args[n], XmNbuttons, buttonArray); n++;
        XtSetArg(args[n], XmNbuttonCount, 2); n++;
        XtSetArg(args[n], XmNbuttonSet, 0); n++;
        XtSetArg(args[n], XmNsimpleCallback,
                   ChangeOperation); n++;
        tempStr = XmStringCreateSimple("Operations:");
        XtSetArg(args[n], XmNoptionLabel, tempStr); n++;
        helpMenu = XmCreateSimpleOptionMenu(helpDialog,
                        "helpMenu", args, n);
        XmStringFree(tempStr);
        XmStringFree(buttonArray[0]);
        XmStringFree(buttonArray[1]);
        XtAddCallback(helpDialog, XmNokCallback,
             (XtCallbackProc) HandleOK, (XtPointer) &client);
        XtAddCallback(helpDialog, XmNcancelCallback,
             (XtCallbackProc) CancelDrop,
             (XtPointer) &client);
        XtUnmanageChild(XmMessageBoxGetChild(helpDialog, 
             XmDIALOG_HELP_BUTTON));
        XtRealizeWidget(helpDialog);
    }
    /* pass the necessary callback information along */
    client.dragContext = cb->dragContext;
    client.x = cb->x;
    client.y = cb->y;
    client.dropSiteStatus = cb->dropSiteStatus;
    client.operation = cb->operation;
    client.operations = cb->operations;
    /* find the valid targets */
    CheckTargets(cb->dragContext, XtDisplay(w),
                   &rectFound, &bgFound, &pixFound);
    /* determine the appropriate help message */
    if (rectFound) {
        if (cb->operations == XmDROP_MOVE | XmDROP_COPY) {
            XtManageChild(helpMenu);
            helpStr = XmStringCreateLtoR(HELP_MSG4, 
                 XmFONTLIST_DEFAULT_TAG);
            XtManageChild(XmMessageBoxGetChild(helpDialog, 
                 XmDIALOG_OK_BUTTON));
        }
        else if (cb->operation == XmDROP_MOVE) {
            XtUnmanageChild(helpMenu);
            helpStr = XmStringCreateLtoR(HELP_MSG2, 
                 XmFONTLIST_DEFAULT_TAG);
            XtManageChild(XmMessageBoxGetChild(helpDialog, 
                 XmDIALOG_OK_BUTTON));
        }
        else if (cb->operation == XmDROP_COPY) {
            XtUnmanageChild(helpMenu);
            helpStr = XmStringCreateLtoR(HELP_MSG3, 
                 XmFONTLIST_DEFAULT_TAG);
            XtManageChild(XmMessageBoxGetChild(helpDialog, 
                 XmDIALOG_OK_BUTTON));
        }
    }
    else if (bgFound ||
             pixFound && cb->operation == XmDROP_COPY) {
        XtUnmanageChild(helpMenu);
        rect = RectFind(cb->x, cb->y);
        if (rect) {
            helpStr = XmStringCreateLtoR(HELP_MSG1, 
                 XmFONTLIST_DEFAULT_TAG);
            XtManageChild(XmMessageBoxGetChild(helpDialog, 
                 XmDIALOG_OK_BUTTON));
        }
        else {
            helpStr = XmStringCreateLtoR(HELP_MSG5, 
                 XmFONTLIST_DEFAULT_TAG);
            XtUnmanageChild(XmMessageBoxGetChild(helpDialog, 
                 XmDIALOG_OK_BUTTON));
        }
    }
    else {
        XtUnmanageChild(helpMenu);
        helpStr = XmStringCreateLtoR(HELP_MSG5, 
             XmFONTLIST_DEFAULT_TAG);
        XtUnmanageChild(XmMessageBoxGetChild(helpDialog, 
             XmDIALOG_OK_BUTTON));
    }
    /* set the help message into the dialog */
    XtSetArg(args[0], XmNmessageString, helpStr);
    XtSetValues(helpDialog, args, 1);
    /* Free the XmString */
    XmStringFree(helpStr);
    /* map the help dialog */
    XtManageChild(helpDialog);
}

The HandleOK callback routine is performed when the user selects the OK button. It allows the drop to continue normally by calling the HandleDrop routine.

static void HandleOK(w, client, call)
Widget w;
XtPointer client;
XtPointer call;
{
    XmDropProcCallbackStruct *cb =
                (XmDropProcCallbackStruct *)client;
    cb->operation = appInfo->operation;
    HandleDrop(w, (XtPointer) cb);
}

The CancelDrop callback routine is performed when the user selects the Cancel button. It cancels the drop by calling XmDropTransferStart with indicators that the drop failed.

static void CancelDrop(w, client, call)
Widget w;
XtPointer client;
XtPointer call;
{
    XmDropProcCallbackStruct *cb =
                       (XmDropProcCallbackStruct *)client;
    Arg                args[2];
    /* On help, we need to cancel the drop transfer */
    XtSetArg(args[0], XmNtransferStatus,
               XmTRANSFER_FAILURE);
    XtSetArg(args[1], XmNnumDropTransfers, 0);
    /* we need to start the drop transfer to cancel
       the transfer */
    XmDropTransferStart(cb->dragContext, args, 2);
}

The receiver's XmNdropProc routine receives the drop message first if the drop occurred over a widget that was registered as a drop site. It verifies that a drop is possible, and updates fields in its callback structure. These fields become available to the initiator in its XmNdropStartCallback callback structure. The initiator can perform any actions necessary before the information is transferred, for example, providing a new drag icon.

The toolkit initializes the operation, operations, and dropSiteStatus fields as described in Section 15.5.5, "Drag Callbacks," with one difference: the initialization for the drag callbacks uses the values at the end of the receiver's XmNdragProc, while the initialization for the drop callbacks uses the values at the end of the receiver's XmNdropProc.

The dropAction field indicates the action that the receiver has taken. XmDROP shows that a normal drop is in progress. XmDROP_CANCEL shows that the receiver has cancelled the drop. If the action is XmDROP_HELP, the initiator is not expected to do anything, although this callback provides the opportunity to do so if desired (for example, changing the drag icon to reflect the Help request).

This procedure will not know the resolution of the help dialog. However, if the user chooses to continue, the initiator's XmNconvertProc routine is called as part of the transfer process, and if the user chooses to cancel, the receiver's XmNdropFinishCallback is called with a dropAction of XmDROP_CANCEL.

The drag initiator must register a callback to process transfers in the XmNconvertProc DragContext resource. This routine is called when the receiver client invokes XmDropTransferStart. Before calling XmDropTransferStart, the receiver makes a list of the target formats it wants.

The initiator's XmNconvertProc callback routine processes transfer requests from the receiver. The routine should be able to return information about each object being dragged in each possible target format for that item.

If the DropTransfer XmNincremental resource is True, information is transferred between the initiator and the toolkit using the Xt selection incremental protocol. If the value is False, the information is transferred between the initiator and the toolkit in one pass. The initiator and receiver need not be using the same incremental or nonincremental protocol.

The XmNconvertProc routine is called for each target type desired by the receiver, a single target type for each request. The XmNconvertProc routine should be able to perform any of the operations listed in the DragContext's XmNdragOperations resource on data in any of the target types listed in the XmNexportTargets resource:

In the following example from DNDscroll.c in "A Simple Drag Source" the routine returns the value of the scrollbar slider in only one target type, compound text. This information is passed to the receiver's XmNtransferProc routine. This routine is called once for each item in the receiver's XmNdropTransfers list. Copy is the only operation allowed by the application, so this routine need not process any delete requests from the receiver.

static
Boolean DragConvertProc(w, selection, target, typeRtn, 
                        valueRtn, lengthRtn, formatRtn, 
                        max_lengthRtn, client_data, 
                        request_id)
Widget              w;
Atom                *selection;
Atom                *target;
Atom                *typeRtn;
XtPointer           *valueRtn;
unsigned long       *lengthRtn;
int                 *formatRtn;
unsigned long       *max_lengthRtn;
XtPointer           client_data;
XtRequestId         *request_id;
{
   XmString    cstring;
   static char tmpstring[100];
   int         *value;
   int         n;
   Arg         args[MAX_ARGS];
   char          *ctext;
   char        *passtext;
   /* this routine processes only compound text */
   if (*target != COMPOUND_TEXT)
      return(False);
   /* get the value of the scrollbar slider */
   n = 0;
   XtSetArg(args[n], XmNvalue, &value); n++;
   XtGetValues(scrollbar, args, n);
   /* convert the slider value to compound text */
   sprintf(tmpstring, "%d", value);
   cstring = XmStringCreateLocalized(tmpstring);
   ctext = XmCvtXmStringToCT(cstring);
   passtext = XtMalloc(strlen(ctext)+1);
   memcpy(passtext, ctext, strlen(ctext)+1);
   /* Format the value for transfer.  Convert the value
    * from compound string to compound text for the
    * transfer */
   *typeRtn = COMPOUND_TEXT;
   *valueRtn = (XtPointer) passtext;
   *lengthRtn = strlen(passtext);
   *formatRtn = 8;
   return(True);
}

If the DNDscroll.c program in "A Simple Drag Source" processed more than one target, such as text and compound text, then this routine would have to handle both types. For example:

if (*target = COMPOUND_TEXT) {
   /* processing to convert the slider to compound string
      format */
   }
else if (*target = TEXT) {
   /* processing to convert the slider to text format */
   }
else
   return(False);

The XmNdropFinishCallback is called when the receiver's XmNtransferProc routine has finished processing all the transfers desired by the receiver.

The completionStatus field indicates whether the entire drop was successful or not.

The operations, operation, dropSiteStatus, and dropAction fields are initialized as for the XmNdropStartCallback procedure.

The XmdragDropFinishCallback routine is performed when the complete drag and drop transaction has finished. This routine is called immediately after the initiator's XmNdropFinishCallback has finished. The initiator frees any remaining structures it has allocated during the drag.

The following sample code destroys any cursor icons that were created during the drag:

static void DnDFinishCallback(w, client_data, call_data)
Widget          w;
XtPointer       client_data, call_data;
{
   XmDragContext    dc;
   Widget           source_icon, state_icon, op_icon;
   Arg              args[MAX_ARGS];
   int              n;
   dc = (XmDragContext)w;
   source_icon = state_icon = op_icon = NULL;
   n = 0;
   XtSetArg(args[n], XmNsourceCursorIcon,
              &source_icon); n++;
   XtSetArg(args[n], XmNstateCursorIcon,
              &state_icon); n++;
   XtSetArg(args[n], XmNoperationCursorIcon,
              &op_icon); n++;
   XtGetValues(dc, args, n);
   if (source_icon != NULL)
      XtDestroyWidget(source_icon);
      if (state_icon != NULL)
         XtDestroyWidget(state_icon);
      if (op_icon != NULL)
         XtDestroyWidget(op_icon);
}