In order to be the source of a UTM data transfer, a widget must provide a callback resource named XmNconvertCallback. The following Motif toolkit widgets hold this resource:

Your application can attach an XmNconvertCallback procedure to any widget holding the XmNconvertCallback resource. UTM calls any XmNconvertCallback procedures in your application whenever the associated widget is asked to convert a selection. After calling these callbacks, UTM typically calls the widget's own internal conversion routine (the convertProc trait method of the XmQTtransfer trait)

When UTM calls your application's XmNconvertCallback procedures, UTM passes a pointer to a XmConvertCallbackStruct as the client_data argument. This callback structure is defined as follows:

typedef struct
{
        int     reason;
        XEvent  *event;
        Atom selection;
        Atom target;
        XtPointer source_data;
        XtPointer location_data;
        int flags;
        XtPointer parm;
        int parm_format;
        unsigned long parm_length;
        Atom parm_type;
        int status;
        XtPointer value;
        Atom type;
        int format;
        unsigned long length;
} XmConvertCallbackStruct;

If your application does not define any XmNconvertCallback procedures, UTM automatically calls the widget's convertProc trait method. If your application does define at least one XmNconvertCallback procedures, UTM conditionally calls the widget's convertProc trait method. Here are the conditions:

If UTM does call your widget's convertProc trait method, UTM passes it the same XmConvertCallbackStruct used by the application's XmNconvertCallback procedures. Thus, the XmConvertCallbackStruct provides a convenient conduit for the XmNconvertCallback procedures to communicate with the widget's convertProc trait method.

In order to be the destination for a UTM data transfer, a widget must provide a callback resource named XmNdestinationCallback. Appendix B lists the widgets in the standard Motif toolkit that hold this callback resource.

Your application can attach an XmNdestinationCallback procedure to any widget holding the XmNdestinationCallback resource. UTM calls any XmNdestinationCallback procedures in your application whenever the associated widget is the destination of a data transfer. After calling these callbacks, UTM typically calls the destination widget's own internal destination routine (the destinationProc trait method of the XmQTtransfer trait).

When UTM calls your application's XmNdestinationCallback procedures, UTM passes a pointer to a XmDestinationCallbackStruct as the client_data argument. This callback structure is defined as follows:

typedef struct
{
        int     reason;
        XEvent  *event;
        Atom selection;
        XtEnum operation;
        int flags;
        XtPointer transfer_id;
        XtPointer destination_data;
        XtPointer location_data;
        Time time;
} XmDestinationCallbackStruct;

The fields in an XmConvertCallbackStruct are far more dynamic than the fields in an XmDestinationCallbackStruct. In other words, an XmNconvertCallback procedure typically modifies many of the fields of its XmConvertCallbackStruct; however, an XmNdestinationCallback procedure typically leaves all the fields of its XmDestinationCallbackStruct untouched.

A typical XmNdestinationCallback procedure requests a list of targets supported by the source widget. To make this request, the procedure calls XmTransferValue. For example, here is a typical XmNdestinationCallback procedure:

void DestinationCallback(w, ignore, cs)
       Widget w;
       XtPointer ignore;
       XmDestinationCallbackStruct *cs;
{
 Atom TARGETS = XInternAtom(XtDisplay(w), "TARGETS", False);

 /* Request TARGETS that the source widget can convert. */
   XmTransferValue(cs -> transfer_id, TARGETS,
                   (XtCallbackProc) TransferProcedure,
                   NULL, XtLastTimestampProcessed() );
}

The transfer procedure is a companion routine to the XmNdestinationCallback procedure. Typically,

Steps 2 and 3 may repeat several times.

Unlike the XmNconvertCallback and XmNdestinationCallback routines, the transfer procedure is not identified by a resource. Rather, the transfer procedure is identified by the third argument in a call to XmTransferValue.

When UTM calls your application's transfer procedure, UTM passes a pointer to an XmSelectionCallbackStruct as the client_data argument. This callback structure is defined as follows:

typedef struct
{
        int     reason;
        XEvent  *event;
        Atom selection;
        Atom target;
        Atom type;
        XtPointer transfer_id;
        int flags;
        int remaining;
        XtPointer value;
        unsigned long length;
        int format;
} XmSelectionCallbackStruct;

The application must associate an XmNconvertCallback procedure with widget TextSource. The following code does just that:

XtAddCallback(TextSource, XmNconvertCallback, ConvertCallback, NULL);

The application must provide an XmNconvertCallback procedure named ConvertCallback. This procedure must handle the following requests:

Following are the relevant parts of the ConvertCallback routine:

void
ConvertCallback(Widget  w,
                     XtPointer ignore,
                     XtPointer call_data)
{
 XmConvertCallbackStruct  *ccs = (XmConvertCallbackStruct *)call_data;
 char    *selected_text;
 char    *copy_of_selected_text;
 Atom TARGETS = XInternAtom(XtDisplay(w), "TARGETS", False);
 Atom _MOTIF_CLIPBOARD_TARGETS = XInternAtom(XtDisplay(w),
                              "_MOTIF_CLIPBOARD_TARGETS", False);
 Atom MYTEXT = XInternAtom(XtDisplay(w), "MYTEXT", False);
 int   n=0;
 Atom *targs = (Atom *)XtMalloc(sizeof(Atom) * 2);

  if ((ccs->target == TARGETS) ||
     (ccs->target == _MOTIF_CLIPBOARD_TARGETS)) {

  /* Use targs to hold a list of targets that my application can
     convert. This list will be merged with the targets that the
     XmText widget can convert. */
    targs[n] = MYTEXT; n++;
    ccs->value = (XtPointer) targs;
    ccs->type = XA_ATOM;
    ccs->format = 32;
    ccs->length = n;
    ccs->status = XmCONVERT_MERGE;
  }
  else if (ccs->target == MYTEXT)  {
  /* Get the selection. */
    selected_text = XmTextGetSelection(w);
    copy_of_selected_text = selected_text;

  /* Convert any lowercase letters in the selection to uppercase. */
    while (*selected_text++)  {
       if (islower(*selected_text))
         *selected_text = toupper(*selected_text);
    }

  /* Place the converted text into the XmConvertCallbackStruct. */
    ccs->value = copy_of_selected_text;
    ccs->type = ccs->target;
    ccs->format = 8;
    ccs->length = strlen(copy_of_selected_text);
    ccs->status = XmCONVERT_DONE;
  }
}

Notice how ConvertCallback sets the value of the status member of the XmConvertCallbackStruct. For example, when the destination requests TARGETS or _MOTIF_CLIPBOARD_TARGETS, ConvertCallback sets status to XmCONVERT_MERGE. This status tells UTM to call the convertProc trait method of XmText. This trait method will add MYTEXT to the list of supported targets. As another example, consider that ConvertCallback is taking full responsibility to convert the selection to MYTEXT. For this case, ConvertCallback sets status to XmCONVERT_DONE. This status tells UTM not to bother calling the convertProc trait method of XmText. Finally, consider what happens when ConvertCallback is asked to convert a target other than TARGETS, _MOTIF_CLIPBOARD_TARGETS, or MYTEXT. In this case, the status member will retain its default value of XmCONVERT_DEFAULT. This status tells UTM to call the convertProc trait method of XmText, and that the trait method will be reponsible for converting the target.

The application must associate an XmNdestinationCallback procedure with widget TextDestination. The following code does just that:

XtAddCallback(TextDestination, XmNdestinationCallback,
              DestinationCallback, NULL);

The application must provide an XmNdestinationCallback procedure named DestinationCallback. We have implemented this procedure in a very basic fashion. This procedure merely requests a list of the targets that the source widget supports:

void
DestinationCallback(Widget  w,
                        XtPointer ignore,
                        XtPointer call_data)
{
 XmDestinationCallbackStruct *dcs =
           (XmDestinationCallbackStruct *)call_data;
 Atom TARGETS = XInternAtom(XtDisplay(w), "TARGETS", False);

 /* Ask the source to return a list of all the targets supported. */
   XmTransferValue(dcs->transfer_id, TARGETS,
                   (XtCallbackProc)TransferProc,
                   NULL, XtLastTimestampProcessed() );
}

When the source returns the list of TARGETS, UTM calls the application's transfer procedure. The transfer procedure, TransferProc in this case, is named by the third argument to XmTransferValue.

Here is the algorithm for the transfer procedure. The transfer procedure must examine the returned list of targets to see if the list contains MYTEXT. If it does, ask the source to convert the selection to MYTEXT. When the source completes the conversion, the transfer procedure must paste the converted text into the TextDestination widget.

Following is the code for TransferProc:

void
TransferProc(Widget  w,
             XtPointer ignore,
             XtPointer call_data)
{
 XmSelectionCallbackStruct *scs =
       (XmSelectionCallbackStruct *) call_data;
 Atom TARGETS = XInternAtom(XtDisplay(w), "TARGETS", False);
 Atom MYTEXT = XInternAtom(XtDisplay(w), "MYTEXT", False);
 Atom  *targets = (Atom *)scs->value;
 int    MYTEXT_is_supported = 0;
 unsigned long    n;


   if ((scs->target == TARGETS) && (scs->type == XA_ATOM))  {
     for (n=0; n<=scs->length; n++)  {
      /* Look through list of returned TARGETS to see if
         MYTEXT is there. */
        if (targets[n] == MYTEXT)
          MYTEXT_is_supported = 1;
     }

     if (MYTEXT_is_supported)
     /* Now ask the source widget to convert the selection
          to MYTEXT. */
       XmTransferValue(scs->transfer_id, MYTEXT,
                   (XtCallbackProc)TransferProc,
                   NULL, XtLastTimestampProcessed() );
   }

  if ((scs->target == MYTEXT)) {
    XmTextPosition current_insertion_position;
  /* Source widget has converted MYTEXT, paste it into the
     destination widget. */
    current_insertion_position = XmTextGetInsertionPosition(w);
    XmTextInsert(w, current_insertion_position, (char *)scs->value);
    XmTransferDone(scs->transfer_id, XmTRANSFER_DONE_SUCCEED);
  }
}

Notice how TransferProc calls XmTransferDone. This call marks the end of the transfer. Therefore, UTM will not call the destinationProc trait method inside the TextDestination widget.

If the source does not know how to convert MYTEXT, UTM will call the destinationProc trait method inside the TextDestination widget.