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)