Many newcomers wonder why the ICCCM protocol has to be so complicated. One answer is that each widget is a self-contained object that knows how to take care of itself but ignores other widgets. Therefore, widgets monitor their own events only and ignore the events of other widgets.

For example, suppose a user wants to copy some data from one widget (the source) to another (the destination). To do this, the user must first select the data that is to be copied. The user then moves the pointer to the destination widget and indicates where the data should be transferred. Since the destination widget does not receive the source widget's events, the destination widget does not have the following information:

The ICCCM protocol solves these problems by forcing all widgets to use atoms to describe the data to be transferred.

The ICCCM requires that the owner and destination use atoms to solve these categorization needs. In brief, an atom is a number that symbolizes a particular data category or a particular data transfer selection. For example, the ICCCM specifies that an atom called PIXMAP be used to symbolize the transfer of a pixmap. As another example, the ICCCM specifies that an atom called CLIPBOARD by used to symbolize a clipboard selection.

Atoms like PIXMAP that specify a data category are called target atoms or, more simply, targets. Atoms like CLIPBOARD that specify a kind of transfer mechanism are called selection atoms.

Widgets can display many kinds of information. Most of the displayed information (and some of the nondisplayed information) should be transferrable. The widget represents each of these different kinds of transferrable information as a target atom.

For example, consider the XmLabel widget. As you might expect, XmLabel allows users to make copies of the displayed text or pixmap. What is somewhat surprising is that XmLabel can also transfer other kinds of information. For example, XmLabel can transfer information about its foreground and background colors. In fact, the relatively simple XmLabel widget can transfer over a dozen different targets.

Each selection is represented by an atom. The display contains only one selection of each type. It is owned by a client or by no one and, if owned, is attached to a window of the owning client. Any client may assert or remove ownership of a selection.

The data represented by the selection is internal to the client that owns the selection.

Motif uses the following selection atoms:

The Atom data type is used to declare an atom variable. Use the Xlib function XInternAtom to assign an atom value to your atom variable. For example, the following code creates an Atom variable named TEXT and associates the correct atom value with the TEXT variable.

Atom TEXT = XInternAtom(XtDisplay(w), "TEXT", False);

The second argument to XInternAtom is an atom string name. You can specify an atom string name from any of the following four categories:

We recommend that you avoid making up new atom string names whenever possible. If you do make up your own, the atom string names you pick should follow the naming conventions documented in the ICCCM.

You can specify an atom string name as a constant having the XmS prefix; for example:

Atom TARGETS = XInternAtom(XtDisplay(w), XmSTARGETS, False);

or you can specify an atom string name as a string without the XmS prefix; for example, the following line of code produces the same results as the previous line of code:

Atom TARGETS = XInternAtom(XtDisplay(w), "TARGETS", False);

As we mentioned earlier, Motif also provides some atom string names that have no ICCCM equivalent. Motif atom string names that have no ICCCM equivalent have a prefix of _MOTIF are as follows:

This chapter explains all of these unique Motif atom string names.

The data transfer protocol defines a kind of dialog between the source widget and the destination widget. This dialog is somewhat different for each data transfer mechanism. For example, the dialog of a clipboard transfer is more complicated than that of a primary transfer. Nevertheless, we can describe a kind of idealized dialog that is general enough to be reasonably accurate for all four data transfer mechanisms.

This idealized data transfer sequence consists of the seven steps shown in Figure 10-1.

Figure 10-1. The Data Transfer Dialog

The user starts a data transfer (Step 1) by specifying the source widget of the data transfer. The user typically specifies the source widget by selecting some portion of a widget; for example, a line of displayed text. The user makes a selection through some keyboard or mouse event. For example, a user can select a line in an XmText widget by positioning the cursor anywhere on the line and then clicking the left mouse button three times. In some cases, Step 1 actually consists of two parts. In the first part, the user selects the data to be transferred. In the second part, the user enters some other event to specify the data transfer mechanism. For example, the user might hold down the middle mouse button to start a drag operation.

The user also indicates the destination widget (Step 2) of the data transfer. The user does this by changing focus to the destination widget and then entering some event. For example, the user specifies the destination widget of a drag and drop operation by moving the cursor to the destination widget and then releasing the middle mouse button.

After completing Steps 1 and 2, the user's role in data transfer is over. The remaining steps must all be implemented by the widget.

Don't forget that, at this stage, the destination widget has no idea what kind of data has been selected in the source widget. Therefore, at Step 3, the destination widget has to ask the source widget for a list of all the targets that the source widget can transfer. The destination widget does this by sending the source widget a message asking for its TARGETS list.

The source widget responds to the request for TARGETS (Step 4) by returning a list of all the atoms that it knows how to transfer. For example, in Figure 10-1, the source widget claims to know how to transfer the following targets:

In practice, the returned list of TARGETS will be considerably longer than in this example.

The source widget does not place the atoms in the returned TARGETS list in any particular order. For example, the first atom in the TARGETS list is not necessarily the atom that the source widget wants most to transfer.

In Step 5, the destination widget examines the list of target atoms returned by the source widget. From this list, the destination widget chooses the atom that most closely meets its needs. In Figure 10-1, the destination widget selected COMPOUND_TEXT.

In Step 6, the source widget converts the data that the user has selected into the data representation that the destination widget has requested. For example, in Figure 10-1, the source widget has to convert the selected data to COMPOUND_TEXT. In some cases, the source widget does not have to do much work to convert the data. For example, perhaps the source widget stores text as COMPOUND_TEXT anyway. In other cases, the source widget might have to fight a considerable battle to convert the data into the proper representation. For example, perhaps the source widget stores text in XmString format. In this case, the source widget will have to convert the string from XmString format to COMPOUND_TEXT format.

A surprisingly high percentage of a data transfer widget is devoted to data conversion. When the source widget is finished converting the data, the source widget sends the converted data to the destination widget.

In Step 7, the destination widget pastes the received data into the appropriate portion of the widget.

You may be wondering what happens if the destination widget wants more than one kind of data from the source widget. For example, suppose that the destination widget wants the source widget to transfer both a pixmap and a colormap. There are two possible ways to handle this. One possibility is that Steps 5, 6, and 7 will be repeated. Another possibility is that, in Step 5, the destination widget can request a multiple data transfer, and, in Step 6, the source widget can honor that request by passing several different kinds of data back at the same time.

You must decide what data transfer mechanisms your widget will support. Ideally, your widget should support as many data transfer mechanisms as possible. Writing a widget that supports multiple data transfer mechanisms is only slightly more time consuming than writing a widget that supports only one data transfer mechanism. Most of the data transfer code is independent of a particular form of data transfer.

You might be writing a read-only widget. In other words, the user is not allowed to transfer data into the widget. For these widgets, you need only supply the source side of data transfer; you can omit the destination side.

One way to help you decide what data transfer mechanisms your widget should support is to examine how the widgets in the Motif toolkit support data transfer. (By the way, as of Motif Release 2.0, all the widgets in the Motif toolkit use UTM to implement data transfer.) Table 10-2 summarizes the data transfer methods supported in the standard widget set. When an entry says "Source only" or "Drag only," it means that a user can copy data in this widget but cannot cut data out of it or paste data into it. For example, a user can copy text from an XmLabel to an XmText widget but cannot copy text from an XmText to an XmLabel widget.

Users trigger data transfer by pressing keys or mouse buttons. Your widget must supply data transfer translations compatible with the Motif Style Guide.

Widgets typically provide two different kinds of translations to support data transfer.

The first kind of data transfer translation allows the user to select the data to be transferred. For example, the XmText widget provides several translations that allow a user to select different subsets of the displayed text. These subsets range from one character to the entire text. By contrast, XmLabel does not allow a user to select a portion of its displayed text; the user can only select the entire displayed text.

In addition to providing selection translations, your widget must also supply translations that let the user initiate and complete the data transfer. For example, if a widget is to support drag and drop, the widget must supply a translation that allows the user to mark the start of the drag operation. (Typically, the user starts a drag operation with a Button2 or Button2Press event.) The four different kinds of data transfer each require different translations.

The easiest way to supply appropriate Motif translations for your widget is to copy the data translations of the standard Motif widget that is most similar to your own. Translations for standard Motif widgets are documented in the Motif Programmer's Reference.

Your widget must provide actions that respond to the user's data transfer request. These action methods have to call the appropriate UTM Xme set-up routine. The routine your action calls depends on the type of data transfer, and on whether the action method is for the source side of the transfer or the destination side of the transfer.

If you are writing an action method that represents the source side of a data transfer, the action method must call one of the following routines:

For example, suppose a widget is to serve as a source for a clipboard transfer. This widget must respond to a selection translation by calling XmeClipboardSource.

Broadly speaking, each of the preceding Xme routines makes the following sequence of calls:

Actions in destination widgets must call one of the following routines:

For example, suppose a widget is to serve as a destination for a clipboard transfer. When the user triggers a clipboard paste, the clipboard paste action must call XmeClipboardSink.

Broadly speaking, each of the preceding four routines trigger the following sequence of calls:

The procedures and callbacks are described later in this section.

Your widget must install the XmQTtransfer trait in order to support UTM data transfers.

Your widget can install XmQTtransfer as it would install any trait; namely by calling XmeTraitSet. Typically, the call is made from a class_part_initialize method.

Widgets capable of acting as a source for data transfer must provide a convertProc trait method. Widgets capable of acting as a destination for data transfer must provide at least a destinationProc trait method. Frequently, a widget will be both a source and a destination. In this case, your widget must supply both trait methods. Destination widgets may optionally also provide a destinationPreHookProc trait method.

For example, the ExmStringTransfer widget installs the XmQTtransfer trait as part of its ClassPartInitialize method. The code that does the installation is as follows:

ClassPartInitialize(WidgetClass widgetclass)
{
  XmeTraitSet((XtPointer) widgetclass, XmQTtransfer, (XtPointer)
              &StringTrT);
}

where the StringTrT variable is declared earlier in the StringTrans.c file as follows:

static XmConstXmTransferTraitRec StringTrT = {
  0,                                           /* version */
  (XmConvertCallbackProc) ConvertProc,         /* convertProc */
  (XmDestinationCallbackProc) DestinationProc, /* destinationProc */
  NULL,                                        /*no destinationPreHookProc */
};

Source widgets must supply a convertProc (convert procedure) trait method. The convertProc method is one of the trait methods of the XmQTtransfer trait. (See Chapter 18 for complete syntactic details on the XmQTtransfer trait.) UTM automatically calls convertProc whenever an object (typically, a destination widget) requests a conversion from the widget.

The convertProc has the same prototype as any Intrinsics callback. Therefore, the third argument to convertProc is call_data. UTM will pass an XmConvertCallbackStruct to the call_data argument. The XmConvertCallbackStruct contains all the raw data required for the conversion. For example, the targets member of this structure contains the name of the target atom that the destination procedure wants converted.

Your convertProc must respond to the following two general kinds of requests:

Later on in this chapter, we will discuss the specific targets your widget should support.

Your widget must supply a destinationProc (destination procedure) trait method in order to serve as a destination widget in a data transfer. The destinationProc trait method is one of the trait methods of the XmQTtransfer trait. (See Chapter 18 for complete syntactic details on the XmQTtransfer trait.) UTM automatically calls destinationProc whenever a user requests that data be transferred to the destination widget. The destinationProc trait method is responsible for requesting data from the source widget and for pasting this data into the destination widget. However, the destinationProc trait method will ask a transfer procedure to take over some of these responsibilities.

UTM calls destinationProc after calling any XmNdestinationCallback procedures defined by the application. The toolkit passes destinationProc an XmDestinationCallbackStruct structure. This structure contains all the fields necessary to make requests to the source widget.

The destinationProc trait method should typically call XmTransferValue to request a conversion from the source widget XmTransferValue automatically calls the source widget's convertProc. When the convertProc finishes, XmTransferValue typically calls the destination widget's transfer procedure. The name of the transfer procedure is identified by the third argument to the XmTransferValue call.

The destinationProc trait method can terminate a data transfer by calling XmTransferDone.

XmTransferValue, together with XmTransferDone, form the UTM replacements for the following older calls:

If you are writing a destination widget, you will probably have to write one or more transfer procedures. UTM calls a transfer procedure when the convertProc trait method finishes the conversion. UTM passes the transfer procedure a pointer to an XmSelectionCallbackStruct. (See the XmTransferDone(3) reference page of the Motif Programmer's Reference for details on this structure.) The value member of XmSelectionCallbackStruct holds the selection converted to the target that the destination widget has requested. The target procedure will take that converted target and paste it into the destination widget.

UTM automatically calls any XmNconvertCallback procedures immediately prior to calling the convertProc trait method of the source widget. UTM automatically passes an XmConvertCallbackStruct to the application's XmNconvertCallback procedures. These procedures are free to modify the fields of this structure. UTM will pass this structure, modifications and all, to your source widget's convertProc trait method.

If the application does not provide any XmNconvertCallback procedures, then UTM simply calls the convertProc trait method. If the application does provide XmNconvertCallback procedures, then UTM conditionally calls convertProc depending on the value in the status member of the XmConvertCallbackStruct. If the status member holds XmCONVERT_DONE or XmCONVERT_REFUSE, then UTM will not call the source widget's convertProc trait method. If the status member holds some other value, then UTM will call the source widget's convertProc trait method.

Throughout this chapter, we use the term "conversion routines" to refer to a combination of the XmNconvertCallback procedures of the application and the convertProc trait method of the source widget.

UTM automatically calls any XmNdestinationCallback procedures immediately prior to calling the destinationProc trait method.

Throughout this chapter, we use the term "destination routines" to refer to a combination of the XmNdestinationCallback procedures of the application and the destinationProc trait method of the destination widget.

Broadly speaking, an application's UTM callbacks can interact with your widget's UTM trait methods in any of the following three ways:

In case 1, your widget must be prepared to do all the conversion and transfer work itself. Preparing for this case simply means that your widget's UTM trait methods must be self-sufficient. In other words, your widget must handle all the targets that your widget documentation says it handles.

In case 2, your widget's UTM trait methods never get called.

In case 3, your widget's UTM trait methods must react appropriately to data passed by the application's UTM callback procedures. Consider the following situation. Suppose you write a widget that displays text. Being a good widget writer, you code your widget so that its UTM trait methods support all the standard textual targets. However, suppose an application programmer decides to supplement your widget's list of targets by writing a UTM application callback that supports an additional textual target, _FORMATTED_TEXT. Therefore, the following things must happen:

Of the preceding three bulleted items, only the first requires extra coding by the widget writer. When an application adds a new target, the application must set the status member of the XmConvertCallbackStruct to XmCONVERT_MERGE. (Remember that UTM automatically passes an XmConvertCallbackStruct to your widget's convertProc trait method.) Therefore, your widget's convertProc trait method should always examine the status member to see if it holds XmCONVERT_MERGE. If it does, convertProc should call XmeConvertMerge. The following code illustrates how this is done:

if (cs -> status == XmCONVERT_MERGE) {
  XmeConvertMerge(value, type, format, length, cs);
  XtFree((char *) value);
}

The XmeConvertMerge routine merges two groups of list-like targets. In this case, XmeConvertMerge merges the sole target from the application _FORMATTED_TEXT with the list of targets already supported by your widget.

A primary transfer involves interaction among a user, an application, a source widget, and a destination widget. Following are the steps involved in a typical primary transfer:

The ExmStringTransfer demonstration widget supports primary transfer. The following translations are relevant to the primary transfer:

<Btn1Down>:  ExmStringTransferMoveFocus()ExmStringTransferCopyPrimary()\n\
<Btn2Down>:  ExmStringTransferProcessDrag()\n\

A user starts a primary copy by pressing Btn1Down. However, the Btn2Down translation is far more puzzling because Btn2Down could mean either a primary paste or the start of a drag operation. ExmStringTransferProcessDrag solves this puzzle by determining whether or not ExmStringTransfer currently owns the primary selection. If it does, ExmStringTransferProcessDrag calls the ExmStringTransferPastePrimary routine.

The ExmStringTransfer widget contains the following relatively simple copy primary routine:

static void
ExmStringTransferCopyPrimary(
     Widget w,
     XEvent *event,
     String *params,
     Cardinal *num_params)
{
 Time time;
 ExmStringTransfer stw = (ExmStringTransfer) w;
  /* First we must obtain a timestamp. This is required for
     ICCCM compliance. XtLastTimestampProcessed holds the timestamp
     from the last event the Intrinsics saw with a timestamp. */
  time = XtLastTimestampProcessed(XtDisplay(w));

  /* Own the primary selection. Indicate this to the user by
     reversing the foreground and background in the text rendition
     (eventually) */
  stw->string_transfer.own_primary = True;

  /* Once we call XmePrimarySource,  the widget's transfer trait
     convert method will get called if a destination wishes to
     obtain the PRIMARY selection. */
  XmePrimarySource(w, time);

  /* Update the widget to show the new state */
  stw->core.widget_class->core_class.expose(w, NULL, NULL);
}

In the preceding code, stw->string_transfer.own_primary is a Boolean field. ExmStringTransfer sets this field to True when the widget holds the primary selection and False when the widget relinquishes the primary selection.

The most important part of the paste primary routine of ExmStringTransfer is its call to XmePrimarySink. Following is the complete ExmStringTransferPastePrimary routine:

static void
ExmStringTransferPastePrimary(
     Widget w,
     XEvent *event,
     String *params,
     Cardinal *num_params)
{
  Time time;
  unsigned int op;
  /* First we must obtain a timestamp. This is required for
     ICCCM compliant ownership of a selection. We use
     XtLastTimestampProcessed which holds the timestamp
     from the last event the Intrinsics saw with a timestamp. */
  time = XtLastTimestampProcessed(XtDisplay(w));

  /* We determine the right operation to perform by looking
     at the modifiers present */
  if (event -> xbutton.state & ShiftMask) {
    if (event -> xbutton.state & ControlMask)
      op = XmLINK;
    else
      op = XmMOVE;
  } else
    op = XmCOPY;

  /* Calling XmePrimarySink will start the process of requesting
     the PRIMARY selection to be pasted using the transfer trait
     destination callback for this widget class */
  XmePrimarySink(w, op, NULL, time);
}

The second argument to XmePrimarySink (called op in the preceding code) describes the kind of operation that the user has requested. UTM will copy the value of op into the operation member of the XmDestinationCallbackStruct.

Motif provides a large set of XmClipboard routines. (See the Motif Programmer's Reference for details on each routine, or see the Motif Programmer's Guide for a summary of the routines.)

Although these routines are still supported, we recommend that you use UTM instead. In other words, you should use UTM as your interface to the clipboard.

A clipboard transfer really consists of two separate transfers. In the first transfer, the source widget transfers the data to the clipboard. The clipboard acts as a pseudo-destination widget for this first transfer. In the second transfer, the clipboard transfers the data to the destination widget. For this second transfer, the clipboard acts as a pseudo-source widget.

When the source widget transfers data to the clipboard, the source widget has no idea what target the destination widget might request. Therefore, the source widget typically converts the selection to several different targets and transfers each of these targets to the clipboard. For example, if the source widget displays text, the source widget might transfer the selected text to the clipboard one time for each of the five standard textual targets. When the destination widget requests the data from the clipboard, the destination widget will (hopefully) ask for one of the five standard textual targets. If it does, the clipboard can transfer the selection to the destination widget.

Clipboard transfer is inherently less efficient than primary transfer. However, Motif does provide a somewhat more efficient mechanism for clipboard transfer called "deferred" clipboard transfer.

The main problem with any clipboard transfer is that the source widget has to copy many different versions of the selection to the clipboard. Using deferred clipboard transfer does not really solve this problem; however, it does make the copying operations significantly cheaper. That is because the source widget need only copy "pointers" or references to the selection, rather than copying the selection itself.

UTM always asks your clipboard source widget to provide a list of its immediate clipboard targets (_MOTIF_CLIPBOARD_TARGETS) and its list of deferred clipboard targets (_MOTIF_DEFERRED_CLIPBOARD_TARGETS ). It is up to you to decide which clipboard targets fall into which category. It is acceptable to make all clipboard targets immediate, or to make them all deferred, or to use some combination of the two. One rule of thumb is that a clipboard target should be deferred if it is relatively expensive to copy it to the clipboard.

This section explains how you must use snapshots to implement deferred clipboard targets.

If your source widget is to act as a clipboard source, UTM will ask your convertProc trait method to convert the _MOTIF_DEFERRED_CLIPBOARD_TARGETS target. Your convertProc trait method should respond to this request as it would respond to any request for a list of targets; namely, by building a list of deferred clipboard targets. For example, suppose we want the list of deferred clipboard targets to consist of _MOTIF_COMPOUND_STRING and STRING. In this case, the following convertProc code should be sufficient:

ConvertProc(
     Widget w,
     XtPointer client_data,
     XtPointer call_data)
{
 XmConvertCallbackStruct *cs = (XmConvertCallbackStruct *) call_data;
 Atom _MOTIF_DEFERRED_CLIPBOARD_TARGETS = XInternAtom(XtDisplay(w),
                         "_MOTIF_DEFERRED_CLIPBOARD_TARGETS", False);
 Atom _MOTIF_COMPOUND_STRING = XInternAtom(XtDisplay(w),
                         "_MOTIF_COMPOUND_STRING", False);
 Atom STRING = XInternAtom(XtDisplay(w), "STRING", False);
 ...

  if (cs->target = _MOTIF_DEFERRED_CLIPBOARD_TARGETS)  {
    Atom *targs = (Atom *) XtMalloc(sizeof(Atom) * 2);
    int   n;
    n = 0;
    targs[n] = _MOTIF_COMPOUND_STRING; n++;
    targs[n] = STRING; n++;

    cs->value = (XtPointer)targs;
    cs->type = XA_ATOM;
    cs->length = n;
    cs->format = 32;
  }
  ...

Since the length member of the XmConvertCallbackStruct was non-zero, UTM will call the convertProc trait method again This time, UTM will ask your convertProc trait method to convert the _MOTIF_SNAPSHOT target. Your convertProc must respond to this target by doing the following:

A snapshot is nothing more than a copy of the current clipboard selection in whatever format you decide to save it in. (UTM does not define how the snapshot must be stored.) If you want, you can go ahead and convert the selection to _MOTIF_COMPOUND_STRING format and to STRING format and then save the converted selection somewhere in your widget. However, it will probably be more efficient just to save the selection somewhere safe and to worry about doing the conversions later.

The distinguisher atom must be unique, so you are going to have to devise some algorithm for generating unique atom string names. One idea is to base the snapshot atom string name on the widget ID itself. For example:

static Atom
GenerateUniqueDistinguisherAtom(Widget w)
{
  char  distinguisher_atom_string[32];
  ExmMyWidget  my_widget = (ExmMyWidget)w;
   sprintf(distinguisher_atom_string, "_EXM_SNAP_%lX_%X", (long)w,
                 my_widget.snap_counter++);
   return (XInternAtom(XtDisplay(w), distinguisher_atom_string, False));
}

Then your convertProc trait method can convert the _MOTIF_SNAPSHOT request as follows:

 ...
 Atom *distinguisher_pointer;

 if (cs->target = _MOTIF_SNAPSHOT)  {
   /* Save the clipboard selection somewhere. */
     ...

   /* Now return the distinguisher atom. */
     distinguisher_pointer = (Atom *) XtMalloc(sizeof(Atom));

    *distinguisher_pointer = GenerateUniqueDistinguisherAtom(w);
     cs->value = (XtPointer)distinguisher_pointer;
     cs->type  = XA_ATOM;
     cs->length = 1;
     cs->format = 32;
 }
 ...

UTM stores this distinguisher atom on the clipboard. This one distinguisher atom symbolizes both the deferred clipboard targets ( STRING and _MOTIF_COMPOUND_STRING). Later, the destination widget may request one of the deferred clipboard targets; for example, STRING. If it does, UTM will call your widget's convertProc trait method, passing the following in the XmConvertCallbackStruct:

Your widget's convertProc trait method must respond to this request by finding the snapshot and converting it to STRING. When the conversion is completed, UTM automatically passes the converted data to the clipboard. Then, the clipboard automatically passes the converted data to the destination widget.

This section takes you step by step through a typical clipboard transfer. Remember that this is a typical transfer, but it is by no means the only way a clipboard transfer might happen. In this section, we use the term "conversion routines" to mean a combination of any XmNconvertCallback routines of the application and the convertProc trait method of the source widget.

Following are the steps:

The ExmStringTransfer demonstration widget supports clipboard transfer. The following translations are relevant to clipboard transfer:

:<Key>osfPaste: ExmStringTransferPasteClipboard()\n\
:<Key>osfCut: ExmStringTransferCopyClipboard()\n\
:s <Key>osfInsert: ExmStringTransferPasteClipboard()\n\
:s <Key>osfDelete: ExmStringTransferCopyClipboard()\n\

To copy the text in an ExmStringTransfer widget to the clipboard, a user can either press the osfCut or osfDelete virtual keys. Despite their ominous names, these keys do not remove or alter any text in the ExmStringTransfer widget. A user pastes data from the clipboard to an ExmStringTransfer widget by pressing the Shift osfInsert or Shift osfDelete virtual keys.

The clipboard copy routine of ExmStringTransfer is shown as follows:

static void
ExmStringTransferCopyClipboard(
     Widget w,
     XEvent *event,
     String *params,
     Cardinal *num_params)
{
  Time time;

  /* First we must obtain a timestamp. This is required for
     ICCCM compliant ownership of a selection. We use
     XtLastTimestampProcessed which holds the timestamp
     from the last event the Intrinsics saw with a timestamp. */
  time = XtLastTimestampProcessed(XtDisplay(w));

  /* When we call XmeClipboardSource,  either the Motif clipboard
     will request the current selection data or an external
     clipboard manager will obtain the data. When the data is
     obtained, the CLIPBOARD selection will be owned by the
     data holder */
  XmeClipboardSource(w, XmCOPY, time);
}

The clipboard paste routine of the ExmStringTransfer widget is shown as follows:

static void
ExmStringTransferPasteClipboard(
     Widget w,
     XEvent *event,
     String *params,
     Cardinal *num_params)
{
  /* Calling XmeClipboardSink will start the process of requesting
     the CLIPBOARD selection to be pasted using the transfer trait
     destination callback for this widget class */
  XmeClipboardSink(w, XmCOPY, NULL);
}

Drag and drop was introduced in Motif Release 1.2. If you wrote a drag and drop application or widget at Release 1.2, it should continue to work at Motif Release 2.0. However, if you are writing a widget at Motif Release 2.0, you should use UTM to implement any drag and drop features.

We recommend converting any existing pre-UTM drag and drop code to UTM.

This section takes you step by step through a typical drag and drop transfer. Remember that this is a typical transfer, but it is by no means the only way a drag and drop transfer might happen. In this section, we use the term "conversion routines" to mean a combination of any XmNconvertCallback routines of the application and the convertProc trait method of the source widget.

Following are the steps:

ExmStringTransfer provides only one drag and drop translation, which is as follows:

<Btn2Down>:             ExmStringTransferProcessDrag()\n\

Notice that there is no explicit action method associated with Btn2Up. In other words, ExmStringTransfer does not need to provide code that detects when the user is signalling to do a drop. Instead, ExmStringTransfer simply registers itself as a potential drop site. Once registered, the drag and drop system built into Motif will catch the Btn2Up event.

To register itself as a potential drop site, ExmStringTransfer has to specify a list of its import targets. That is, the widget must describe the kinds of targets that can be copied into it. The majority of the RegisterDropSite method establishes this import target list. The actual registration of the import targets as a drop site takes place through the XmeDropSink call.

The ExmStringTransferProcessDrag method initiates a drag operation by initializing the XmDragContext. (See the Motif Programmer's Guide for more information on XmDragContext.) The code for ExmStringTransferProcessDrag appears as follows:

static void
ExmStringTransferProcessDrag(
     Widget w,
     XEvent *event,
     String *params,
     Cardinal *num_params)
{
 ExmStringTransferWidget stw = (ExmStringTransferWidget) w;
 Arg args[4];
 Cardinal n;

  if (! stw -> string_transfer.own_primary) {
    ExmStringTransferPastePrimary(w, event, params, num_params);
    return;
  }

  /* Initialize DragContext resources. We want the drag icon to
     indicate text, and we support only the COPY operation. */
  n = 0;
  /* Normal drag and drop behavior will be to use the foreground
     and background of the widget when creating the cursor or
     or the pixmap drag icon */
  XtSetArg(args[n], XmNcursorBackground, stw->core.background_pixel);  n++;
  XtSetArg(args[n], XmNcursorForeground, stw->primitive.foreground);  n++;
  /* We use the default text drag icon, the same as used in
     the standard Motif widgets. */
  XtSetArg(args[n], XmNsourceCursorIcon, XmeGetTextualDragIcon(w));  n++;
  XtSetArg(args[n], XmNdragOperations, XmDROP_COPY); n++;
  (void) XmeDragSource(w, NULL, event, args, n);
}

XmeDragSource ultimately creates a DragIcon; the first three resources—XmNcursorBackground, XmNcursorForeground, and XmNsourceCursorIcon—control the appearance of that DragIcon. The convenience function XmeGetTextualDragIcon gets the standard Motif textual DragIcon If you are writing a widget that is dragging something other than text, then you would specify a different DragIcon.

ExmStringTransfer can be a drop site. To be a drop site, the widget's Initialize method calls a routine named RegisterDropSite. RegisterDropSite builds a list of drop (import) targets and then calls XmeDropSink. The RegisterDropSite routine is as follows:

static void
RegisterDropSite(
     Widget w)
{
  Atom TEXT = XInternAtom(XtDisplay(w), "TEXT", False);
  Atom COMPOUND_TEXT = XInternAtom(XtDisplay(w), "COMPOUND_TEXT", False);
  Atom LOCALE_ATOM = XmeGetEncodingAtom(w);
  Atom MOTIF_C_S = XInternAtom(XtDisplay(w), "_MOTIF_COMPOUND_STRING", False);
  Atom targets[5];
  Arg args[2];
  int n, nt;

  /* Set up import targets. These are the targets from which we can
     generate a compound string when a drop is made. */
  nt = 0;
  targets[nt++] = MOTIF_C_S;
  targets[nt++] = COMPOUND_TEXT;
  targets[nt++] = LOCALE_ATOM;
  if (LOCALE_ATOM != XA_STRING) {
    targets[nt++] = XA_STRING;
  }
  if (LOCALE_ATOM != TEXT) {
    targets[nt++] = TEXT;
  }
  /* If you add any more targets, bump the array size. */

  n = 0;
  XtSetArg(args[n], XmNimportTargets, targets); n++;
  XtSetArg(args[n], XmNnumImportTargets, nt); n++;
  XmeDropSink(w, args, n);
}

According to the code, the user can drop any one of several different standard textual targets into the widget.

A conversion routine must declare Atom variables for every target referenced in the convert procedure. The ConvertProc trait method of ExmStringTransfer used XInternAtom as follows to create most of its Atom variables:

enum { CLIPBOARD, TEXT, COMPOUND_TEXT, FOREGROUND,
       BACKGROUND, TARGETS, MOTIF_DROP,
       MOTIF_C_S, MOTIF_EXPORT_TARGETS,
       CLIPBOARD_IMMEDIATE, LOSE_SELECTION,
       /* special values */ LOCALE_ATOM, NUM_ATOMS };
char* atom_names[] = {
    XmSCLIPBOARD, XmSTEXT, XmSCOMPOUND_TEXT, "FOREGROUND",
    "BACKGROUND", XmSTARGETS, XmS_MOTIF_DROP,
    XmS_MOTIF_COMPOUND_STRING, XmS_MOTIF_EXPORT_TARGETS,
    XmS_MOTIF_CLIPBOARD_TARGETS, XmS_MOTIF_LOSE_SELECTION };
Atom atoms[NUM_ATOMS];

assert(XtNumber(atom_names) == NUM_ATOMS - 1);
XInternAtoms(XtDisplay(w), atom_names, NUM_ATOMS - 1, False, atoms);
atoms[LOCALE_ATOM] = XmeGetEncodingAtom(w);

Wherever the code referenced one of these atoms (say "MOTIF_C_S"), that would be replaced by an index into the array ("atoms[MOTIF_C_S]"). The LOCALE_ATOM was the only exception; ConvertProc called XmeGetEncodingAtom as follows to get the LOCALE_ATOM:

Atom LOCALE_ATOM = XmeGetEncodingAtom(w);

The ICCCM insists that source widgets respond to a TARGETS request by returning a list of all the target atoms that your widget can convert. If your widget serves as a source for a clipboard transfer, then your conversion routine must also be able to handle the request for a list of _MOTIF_CLIPBOARD_TARGETS and _MOTIF_DEFERRED_CLIPBOARD_TARGETS. (See Section 10.5 for more details on this target.) If your widget serves as a source for a drag and drop transfer, then your conversion routine must also be able to handle the request for a list of _MOTIF_EXPORT_TARGETS. (See Section 10.6 for more details on this target.)

To help handle the TARGETS request, Motif provides the XmeStandardTargets routine. This routine carves out enough dynamic memory to hold a list of all the standard and nonstandard targets your widget supports. Then, this routine fills the first slots of this dynamic memory with the names of the standard targets. It is up to your code to fill in the remaining slots with the names of the nonstandard targets.

For example, the ExmStringTransfer widget needs to respond to TARGETS by returning a list consisting of all the standard targets and all the standard textual targets. The following code fragment shows how to build this list of targets:

XmConvertCallbackStruct *cs = (XmConvertCallbackStruct *) call_data;
...
 if (cs->target == TARGETS) {
   /* We convert the standard targets, plus up to five additional
      standard textual targets. */
   Atom *targs = XmeStandardTargets(w, 5, &n);

   targs[n] = MOTIF_C_S; n++;
   targs[n] = COMPOUND_TEXT; n++;
   targs[n] = LOCALE_ATOM; n++;
   if (LOCALE_ATOM != XA_STRING) {
     targs[n] = XA_STRING; n++;
   }
   if (LOCALE_ATOM != TEXT) {
     targs[n] = TEXT; n++;
   }

   value = (XtPointer) targs;
   type = XA_ATOM;
   length = n;
   format = 32;
   ...
 }

(ConvertProc will eventually assign the values of the value, type, length, and format variables to their respective XmConvertCallbackStruct member fields.)

Although TARGETS should include all the standard targets, the more specialized target list requests (such as _MOTIF_EXPORT_TARGETS) do not have to. If you do not want the standard targets to be part of a targets list, use XtMalloc instead of XmeStandardTargets; for example:

if (cs -> target == MOTIF_EXPORT_TARGETS) {
  Atom *targs = (Atom *) XtMalloc(sizeof(Atom) * 7);

All Motif source widgets should be able to convert requests for the following standard targets:

Fortunately, your conversion routine does not have to write conversion code for most of these targets. Your conversion routine can call XmeStandardConvert, which automatically converts 9 of the 10 standard targets. XmeStandardConvert cannot convert TIMESTAMP; however, the Intrinsics can. Even though XmeStandardConvert can convert TARGETS, your own conversion routine should typically take responsibility for doing this conversion. That is, XmeStandardConvert will convert TARGETS by returning a list of all the standard targets only. This returned list will be insufficient if your conversion routine can also convert some nonstandard targets.

For example, the following code from the ConvertProc trait method of ExmStringTransfer demonstrates how to convert the standard targets:

XmConvertCallbackStruct *cs = (XmConvertCallbackStruct *) call_data;
  ...
  XmeStandardConvert(w, NULL, cs);
  if (cs -> value == NULL) /* could not convert the target */
    cs -> status = XmCONVERT_REFUSE;
  else /* successfully converted the target */
       cs -> status = XmCONVERT_DONE;

Textual widgets vary a lot in the richness of the text they support. Some textual widgets only store the ASCII values of each character. Other textual widgets store a great wealth of information about the text, such as the fonts or the locale encoding. When a user tries to transfer data between two different kinds of textual widgets, there is no guarantee that the two widgets will share the same level of text "richness." For example, perhaps the source widget stores font information about its text, and the destination widget simply stores the ASCII value of each character.

The source widget must be able to supply the destination widget with text at the richest level that the source widget supports. In addition, the source widget must also be able to supply text at all poorer levels beneath that richest level. Here are the levels of text, from poorest to richest:

For example, a widget that displays text in XmString format must be able to convert requests from destination widgets for all five textual targets.

A selection owner can use XmbTextListToTextProperty or XwcTextListToTextProperty to convert text in its own locale to a text property. The type of the property is determined by the composition of the text and by the encoding style passed to XmbTextListToTextProperty. Encoding styles exist for converting text to STRING, COMPOUND_TEXT, and the encoding of the locale. Another encoding style specifies conversion to STRING if all the characters in the text can be so converted, or otherwise to COMPOUND_TEXT.

A Motif application that has text in compound strings can use XmCvtXmStringToCT to convert a compound string to compound text The application can then place the compound text in the requestor's property by using type COMPOUND_TEXT.

STRING, COMPOUND_TEXT, and the locale encoding can also be selection targets.To obtain a text selection in its own locale, an application can request conversion to one of these targets and can then call XmbTextPropertyToTextList or XwcTextPropertyToTextList to convert the returned property to text in the current locale. An application can also request conversion to TEXT, but there is no guarantee that it can convert the returned property to text in the current locale.

One possible strategy is first to request conversion to TARGETS. If one of the returned targets is the encoding of the current locale (as determined by a call to XmbTextListToTextProperty with an encoding style of XTextStyle), the application can request conversion to that target. Otherwise, if one of the returned targets is COMPOUND_TEXT, the application can request conversion to that target. If neither the locale encoding nor COMPOUND_TEXT is one of the returned targets, the application can request conversion to STRING or TEXT if the selection owner supports one of those targets.

A Motif application that has text in compound strings can request conversion of a selection to COMPOUND_TEXT and can then use XmCvtCTToXmString to convert the returned property to a compound string.

The ConvertProc trait method of ExmStringTransfer does not do these conversions itself. Instead, ConvertProc calls the ConvertCompoundString routine as follows to handle the text conversions:

if (cs->target == MOTIF_C_S ||
    cs->target == COMPOUND_TEXT || cs->target == TEXT ||
    cs->target == LOCALE_ATOM   || cs->target == XA_STRING) {
  /* Convert the compound string to the appropriate target. */
  cstatus = ConvertCompoundString(w, cstring, cs -> target, &value,
                                  &type, &format, &length, &nchars);

Some targets have side effects for the owner. Among these targets are the following:

The following fragment suggests the framework for an idealized convertProc trait method:

static void
ConvertProc(Widget w,
            XtPointer client_data,
            XtPointer call_data)
{
 /* Cast call_data to an XmConvertCallbackStruct. */
   XmConvertCallbackStruct *cs = (XmConvertCallbackStruct *)call_data;

 /* Declare Atom variables for all targets used in converProc */
   Atom TEXT = XInternAtom(XtDisplay(w), "TEXT", False);
   ...

 /* Handle requests for TARGETS by building a list of all standard
    targets and all X nonstandard targets. */
   nonstandard_targets = 5;
   if (cs->target == TARGETS)
     Atom *targs = XmeStandardTargets(w, nonstandard_targets, &n);

 /* If your widget supports CLIPBOARD transfer, handle requests for
    _MOTIF_CLIPBOARD_TARGETS and _MOTIF_DEFERRED_CLIPBOARD_TARGETS. */
   if (cs->target == _MOTIF_CLIPBOARD_TARGETS)
     XtMalloc(...) /* generate list of immediate clipboard targets */
   else if (cs->target == _MOTIF_DEFERRED_CLIPBOARD_TARGETS)
     XtMalloc(...) /* generate list of deferred clipboard targets */

 /* If your widget supports drag, handle requests for _MOTIF_EXPORT_TARGETS. */
   if (cs->target == _MOTIF_EXPORT_TARGETS)
     XtMalloc(...) /* generate list of draggable targets */

 /* If a previous conversion routine has supplied a list of some kind of
    target, merge it with the list your conversion routine has created. */
   if (cs->status == XmCONVERT_MERGE)
     XmeConvertMerge(cs->value, cs->type, cs->format, cs->length, cs);
     ...

 /* Handle requests for nonstandard targets by converting to the requested
    target. */
   ...

 /* Handle requests for standard targets by calling XmeStandardConvert. */
   XmeStandardConvert(w, NULL, ConvertCallbackStruct);

 /* Return the appropriate status. */
   if (conversion was not successful)
     cs->status = XmCONVERT_REFUSE;
   else if (conversion was successful)
     cs->status = XmCONVERT_DONE;
}

In a typical text transfer, the source widget is capable of converting multiple textual targets. The destination widget in a textual transfer needs to pick the richest of these textual targets. The routine in ExmStringTransfer that does this is called PreferredTarget. DestinationProc and TransferProc call PreferredTarget when the source widget returns its list of supported targets.

PreferredTarget uses the following algorithm to determine which textual target to pick. If the locale atom is present, the precedence order is as follows:

If the locale atom is not present, PreferredTargets uses this order:

The code in PreferredTarget that implements the precedence is as follows:

static Atom
PreferredTarget(
     Widget w,
     Atom *targets,
     Cardinal num_targets)
{
  ...
  int n;
  int cs_index = -1;
  int ct_index = -1;
  int locale_index = -1;
  int string_index = -1;
  int text_index = -1;
 /* Which targets can the source convert? Examine the returned targets. */
  for (n = 0; n < num_targets; n++) {
    if (targets[n] == MOTIF_C_S) cs_index = n;
    if (targets[n] == COMPOUND_TEXT) ct_index = n;
    if (targets[n] == TEXT) text_index = n;
    if (targets[n] == LOCALE_ATOM) locale_index = n;
    if (targets[n] == XA_STRING) string_index = n;
  }

 /* If the source supports the locale atom, specify the
    precedence order as follows. */
  if (locale_index >= 0) {
    if (cs_index >= 0) return targets[cs_index];
    if (text_index >= 0) return targets[text_index];
    if (ct_index >= 0) return targets[ct_index];
    if (locale_index >= 0) return targets[locale_index];
    if (string_index >= 0) return targets[string_index];
  } else {
 /* If the source does not support the locale atom, specify the
    precedence order as follows. */
    if (cs_index >= 0) return targets[cs_index];
    if (ct_index >= 0) return targets[ct_index];
    if (string_index >= 0) return targets[string_index];
  }

  return None;
}