NAME

       XmTransferValue  —  A  toolkit  function  that transfers data to a destination "XmTransferValue" "toolkit
       functions" "XmTransferValue"

SYNOPSIS

       #include <Xm/Xm.h>

       void XmTransferValue(
       XtPointer transfer_id,
       Atom target,
       XtCallbackProc proc,
       XtPointer client_data,
       Time time);

DESCRIPTION

       XmTransferValue converts a selection, transferring any data from the selection owner, in the  context  of
       an   already-initiated   data  transfer  operation.   An  application  can  call  this  routine  from  an
       XmNdestinationCallback procedure or any function called as a result.

       The caller of XmTransferValue supplies the target to which the selection is converted.  The  caller  also
       supplies a callback procedure to handle the data that results from the conversion.

       transfer_id
                 Specifies  a unique indentifier for the data transfer operation.  The value must be the same as
                 the  value  of  the  transfer_id  member  of  the  XmDestinationCallbackStruct  passed  to  the
                 XmNdestinationCallback procedure.

       target    Specifies the target to which the selection is to be converted.

       proc      Specifies  a  callback  procedure  to  be invoked when the selection has been converted and the
                 data, if any, is available.  This procedure is responsible for inserting or otherwise  handling
                 any  data  transferred.   The  procedure  can  also  terminate  the  data  transfer  by calling
                 XmTransferDone.  The proc receives three arguments:

                    •  The widget that requested the conversion

                    •  The value of the client_data argument

                    •  A pointer to an XmSelectionCallbackStruct

                 This procedure can be called before or after XmTransferValue returns.

       client_data
                 Specifies data to be passed to the callback procedure (the value of the proc argument) when the
                 selection has been converted.

       time      Specifies  the  time  of the XEvent that triggered the data transfer.  You should typically set
                 this field to XtLastTimestampProcessed.

       The  callback   procedure   (the   value   of   the   proc   argument)   receives   a   pointer   to   an
       XmSelectionCallbackStruct, which has the following definition:

       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).

RELATED

       XmTransferSetParameters(3), XmTransferSendRequest(3), and XmTransferStartRequest(3).

                                                                                              XmTransferValue(3)