[ Previous | Next | Contents | Glossary | Home | Search ]
Motif 2.1 Programmer's Guide



Implementation Overview

This section provides an overview of UTM from an application programmer's perspective. For complete details, see the Motif Widget Writer's Guide. This section explores the following three kinds of routines that an application might write in order to implement a UTM data transfer:

  1. An XmNconvertCallback procedure associated with the source widget

  2. An XmNdestinationCallback procedure associated with the destination widget

  3. A transfer procedure associated with the XmNdestinationCallback procedure

    In brief, an XmNdestinationCallback procedure requests specific targets. An XmNconvertCallback procedure converts selections to the requested targets. A transfer procedure pastes the converted selections into the destination widget.

  4. XmNconvertCallback Procedure

    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:

    1. XmPrimitive and all its subclasses

    2. XmContainer

    3. XmDrawingArea

    4. XmScale

      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;

      reason
      Indicates why the callback was invoked.

      event
      Points to the XEvent that triggered the callback. It can be NULL.

      selection
      Indicates the selection for which conversion is being requested. Possible values are CLIPBOARD, PRIMARY, SECONDARY, and _MOTIF_DROP.

      target
      Indicates the target to convert.

      source_data
      Contains information about the selection source. When the selection is _MOTIF_DROP, source_data is the DragContext. Otherwise, source_data is NULL.

      location_data
      Contains information about the location of data to be converted. If the value is NULL, the data to be transferred consists of the widget's current selection. Otherwise, the type and interpretation of the value are specific to the widget class.

      flags
      Indicates the status of the conversion. Following are the possible values:

      XmCONVERTING_NONE
      This flag is currently unused.

      XmCONVERTING_PARTIAL
      The target widget was able to be converted, but some data was lost.

      XmCONVERTING_SAME
      The conversion target is the source of the data to be transferred.

      XmCONVERTING_TRANSACT
      This flag is currently unused.

      parm
      Contains parameter data for this target. If no parameter data exists, the value is NULL.

      When selection is CLIPBOARD and target is _MOTIF_CLIPBOARD_TARGETS or _MOTIF_DEFERRED_CLIPBOARD_TARGETS, the value is the requested operation (XmCOPY, XmMOVE, or XmLINK).

      parm_format
      Specifies whether the data in parm should be viewed as a list of char, short, or long quantities. Possible values are 0 (when parm is NULL), 8 (when the data in parm should be viewed as a list of chars), 16 (when the data in parm should be viewed as a list of shorts), or 32 (when the data in parm should be viewed as a list of longs). Note that parm_format symbolizes a data type, not the number of bits in each list element. For example, on some machines, a parm_format of 32 means that the data in parm should be viewed as a list of 64-bit quantities, not 32-bit quantities.

      parm_length
      Specifies the number of elements of data in parm, where each element has the size specified by parm_format. When parm is NULL, the value is 0.

      parm_type
      Specifies the parameter type of parm.

      status
      An IN/OUT member that specifies the status of the conversion. The initial value is XmCONVERT_DEFAULT. The callback procedure can set this member to one of the following values:

      XmCONVERT_DEFAULT
      This value means that the widget's convertProc trait method, if any, is called after the callback procedures return. If the widget's convertProc trait method produces any data, it overwrites the data provided by the callback procedures in the value member.

      XmCONVERT_MERGE
      This value means that the widget's convertProc trait method, if any, is called after the callback procedures return. If the widget's convertProc trait method produces any data, it appends its data to the data provided by the callback procedures in the value member. This value is intended for use with targets that result in lists of data, such as TARGETS.

      XmCONVERT_DONE
      This value means that the callback procedure has successfully finished the conversion. The widget's convertProc trait method, if any, is not called after the callback procedures return.

      XmCONVERT_REFUSE
      This value means that the callback procedure has terminated the conversion process without completing the requested conversion. The widget's convertProc trait method, if any, is not called after the callback procedures return.

      value
      An IN/OUT parameter that contains any data that the callback procedure produces as a result of the conversion. The initial value is NULL. If the callback procedure sets this member, it must ensure that the type, format, and length members correspond to the data in value. The callback procedure is responsible for allocating memory when it sets this member. The toolkit frees this memory when it is no longer needed.

      type
      An IN/OUT parameter that indicates the type of the data in the value member. The initial value is INTEGER.

      format
      An IN/OUT parameter that specifies whether the data in value should be viewed as a list of char, short, or long quantities. The initial value is 8. The callback procedure can set this member to 8 (for a list of char), 16 (for a list of short), or 32 (for a list of long).

      length
      An IN/OUT member that specifies the number of elements of data in value, where each element has the size symbolized by format. The initial value is 0.

      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:

      1. If your XmNconvertCallback procedures are taking full responsibility for converting the selection to a particular target, then UTM will not call the widget's convertProc trait method. An XmNconvertCallback procedure notes that it is taking full responsibility by setting the status member of the XmConvertCallbackStruct to XmCONVERT_DONE or XmCONVERT_REFUSE.

      2. If your XmNconvertCallback procedures are not taking full responsibility for converting the selection to a particular target, then UTM will call the widget's convertProc trait method. An XmNconvertCallback procedure notes that it is not taking full responsibility by setting the status member of the XmConvertCallbackStruct to XmCONVERT_DEFAULT or XmCONVERT_MERGE.

        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.

      3. XmNdestinationCallback Procedure

        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;

        reason
        Indicates why the callback was invoked.

        event
        Points to the XEvent that triggered the callback. It can be NULL.

        selection
        Indicates the selection for which data transfer is being requested. Possible values are PRIMARY, SECONDARY, CLIPBOARD, and _MOTIF_DROP.

        operation
        Indicates the type of transfer operation requested.

        1. When the selection is PRIMARY or SECONDARY, possible values are XmMOVE, XmCOPY, and XmLINK.

        2. When the selection is CLIPBOARD, possible values are XmCOPY and XmLINK.

        3. When the selection is _MOTIF_DROP, possible values are XmMOVE, XmCOPY, XmLINK, and XmOTHER. A value of XmOTHER means that the callback procedure must get further information from the XmDropProcCallbackStruct in the destination_data member.

        4. flags
          Indicates whether or not the destination widget is also the source of the data to be transferred. Following are the possible values:

          XmCONVERTING_NONE
          The destination widget is not the source of the data to be transferred.

          XmCONVERTING_SAME
          The destination widget is the source of the data to be transferred.

          transfer_id
          Serves as a unique ID to identify the transfer transaction.

          destination_data
          Contains information about the destination. When the selection is _MOTIF_DROP, the callback procedures are called by the drop site's XmNdropProc, and destination_data is a pointer to the XmDropProcCallbackStruct passed to the XmNdropProc procedure. When the selection is SECONDARY, destination_data is an Atom representing a target recommended by the selection owner for use in converting the selection. Otherwise, destination_data is NULL.

          location_data
          Contains information about the location where data is to be transferred. The interpretation of this value varies considerably from widget to widget. Once XmTransferDone procedures start to be called, location_data will no longer be stable.

          time
          Indicates the time when the transfer operation began.

          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() );
          }

          Transfer Procedure

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

          1. The XmNdestinationCallback procedure calls XmTransferValue to ask for a list of targets supported by the source.

          2. When the source completes the conversion, UTM returns control to the transfer procedure.

          3. The transfer procedure examines the returned list of targets. If the list contains a desired target, the transfer procedure requests it by calling XmTransferValue.

            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;

            reason
            Indicates why the callback was invoked.

            event
            Points to the XEvent that triggered the callback. It can be NULL.

            selection
            Specifies the selection that has been converted.

            target
            Specifies the target to which XmTransferValue requested conversion. The value is the same as the value of the target argument to XmTransferValue.

            type
            Specifies the type of the selection value. This is not the target, but the type used to represent the target. The value XT_CONVERT_FAIL means that the selection owner did not respond to the conversion request within the Intrinsics selection timeout interval.

            transfer_id
            Specifies a unique indentifier for the data transfer operation. The value is the same as the value of the transfer_id argument to XmTransferValue.

            flags
            This member is currently unused. The value is always XmSELECTION_DEFAULT.

            remaining
            Indicates the number of transfers remaining for the operation specified by transfer_id.

            value
            Represents the data transferred by this request. The application is responsible for freeing the value by calling XtFree.

            length
            Indicates the number of elements of data in value, where each element has the size symbolized by format. If value is NULL, length is 0.

            format
            Indicates whether the data in value should be viewed as a list of char, short, or long quantities. Possible values are 8 (for a list of char), 16 (for a list of short), or 32 (for a list of long).


          4. [ Previous | Next | Contents | Glossary | Home | Search ]