'\" t
...\" TransfV.sgm /main/11 1996/08/31 18:08:44 rws $
.de P!
.fl
\!!1 setgray
.fl
\\&.\"
.fl
\!!0 setgray
.fl			\" force out current output buffer
\!!save /psv exch def currentpoint translate 0 0 moveto
\!!/showpage{}def
.fl			\" prolog
.sy sed -e 's/^/!/' \\$1\" bring in postscript file
\!!psv restore
.
.de pF
.ie     \\*(f1 .ds f1 \\n(.f
.el .ie \\*(f2 .ds f2 \\n(.f
.el .ie \\*(f3 .ds f3 \\n(.f
.el .ie \\*(f4 .ds f4 \\n(.f
.el .tm ? font overflow
.ft \\$1
..
.de fP
.ie     !\\*(f4 \{\
.	ft \\*(f4
.	ds f4\"
'	br \}
.el .ie !\\*(f3 \{\
.	ft \\*(f3
.	ds f3\"
'	br \}
.el .ie !\\*(f2 \{\
.	ft \\*(f2
.	ds f2\"
'	br \}
.el .ie !\\*(f1 \{\
.	ft \\*(f1
.	ds f1\"
'	br \}
.el .tm ? font underflow
..
.ds f1\"
.ds f2\"
.ds f3\"
.ds f4\"
.ta 8n 16n 24n 32n 40n 48n 56n 64n 72n 
.TH "XmTransferValue" "library call"
.SH "NAME"
\fBXmTransferValue\fP \(em A toolkit function that transfers data to a destination
.iX "XmTransferValue"
.iX "toolkit functions" "XmTransferValue"
.SH "SYNOPSIS"
.PP
.nf
#include <Xm/Xm\&.h>
.sp \n(PDu
\fBvoid \fBXmTransferValue\fP\fR(
\fBXtPointer \fBtransfer_id\fR\fR,
\fBAtom \fBtarget\fR\fR,
\fBXtCallbackProc \fBproc\fR\fR,
\fBXtPointer \fBclient_data\fR\fR,
\fBTime \fBtime\fR\fR);
.fi
.SH "DESCRIPTION"
.PP
\fBXmTransferValue\fP 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
\fBXmNdestinationCallback\fP procedure or any function called as a
result\&.
.PP
The caller of \fBXmTransferValue\fP 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\&.
.IP "\fBtransfer_id\fP" 10
Specifies a unique indentifier for the data transfer operation\&.
The value must be the same as the value of the \fBtransfer_id\fP member
of the \fBXmDestinationCallbackStruct\fR passed to the
\fBXmNdestinationCallback\fP procedure\&.
.IP "\fItarget\fP" 10
Specifies the target to which the selection is to be converted\&.
.IP "\fIproc\fP" 10
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
\fBXmTransferDone\fP\&.
The \fIproc\fP receives three arguments:
.RS
.IP "   \(bu" 6
The widget that requested the conversion
.IP "   \(bu" 6
The value of the \fIclient_data\fP argument
.IP "   \(bu" 6
A pointer to an \fBXmSelectionCallbackStruct\fR
.RE
.IP "" 10
This procedure can be called before or after \fBXmTransferValue\fP
returns\&.
.IP "\fIclient_data\fP" 10
Specifies data to be passed to the callback procedure (the value of the
\fIproc\fP argument) when the selection has been converted\&.
.IP "\fItime\fP" 10
Specifies the time of the \fBXEvent\fP that triggered the data transfer\&.
You should typically set this field to \fBXtLastTimestampProcessed\fP\&.
.PP
The callback procedure (the value of the \fIproc\fP argument) receives a
pointer to an \fBXmSelectionCallbackStruct\fR, which has the following
definition:
.PP
.nf
typedef struct
{
        int \fIreason\fP;
        XEvent *\fIevent\fP;
        Atom \fIselection\fP;
        Atom \fItarget\fP;
        Atom \fItype\fP;
        XtPointer \fItransfer_id\fP;
        int \fIflags\fP;
        int \fIremaining\fP;
        XtPointer \fIvalue\fP;
        unsigned long \fIlength\fP;
        int \fIformat\fP;
} XmSelectionCallbackStruct;
.fi
.IP "\fIreason\fP" 10
Indicates why the callback was invoked\&.
.IP "\fIevent\fP" 10
Points to the \fBXEvent\fP that triggered the callback\&.
It can be NULL\&.
.IP "\fIselection\fP" 10
Specifies the selection that has been converted\&.
.IP "\fItarget\fP" 10
Specifies the target to which \fBXmTransferValue\fP requested
conversion\&.
The value is the same as the value of the \fItarget\fP argument to
\fBXmTransferValue\fP\&.
.IP "\fItype\fP" 10
Specifies the type of the selection value\&.
This is not the target, but the type used to represent the target\&.
The value \fBXT_CONVERT_FAIL\fP means that the selection owner did not
respond to the conversion request within the Intrinsics selection
timeout interval\&.
.IP "\fBtransfer_id\fP" 10
Specifies a unique indentifier for the data transfer operation\&.
The value is the same as the value of the \fBtransfer_id\fP argument to
\fBXmTransferValue\fP\&.
.IP "\fIflags\fP" 10
This member is currently unused\&.
The value is always \fBXmSELECTION_DEFAULT\fP\&.
.IP "\fIremaining\fP" 10
Indicates the number of transfers remaining for the operation specified
by \fBtransfer_id\fP\&.
.IP "\fIvalue\fP" 10
Represents the data transferred by this request\&.
The application is responsible for freeing the value by calling
\fBXtFree\fP\&.
.IP "\fIlength\fP" 10
Indicates the number of elements of data in
\fIvalue\fP, where each element has the size symbolized by \fIformat\fP\&.
If \fIvalue\fP is NULL, \fIlength\fP is 0\&.
.IP "\fIformat\fP" 10
Indicates whether the data in \fIvalue\fP should be viewed as a list of
\fIchar\fP, \fIshort\fP, or \fIlong\fP quantities\&.
Possible values are 8 (for a list of \fIchar\fP),
16 (for a list of \fIshort\fP), or 32 (for a list of \fIlong\fP)\&.
.SH "RELATED"
.PP
\fBXmTransferSetParameters\fP(3),
\fBXmTransferSendRequest\fP(3),
and
\fBXmTransferStartRequest\fP(3)\&.
...\" created by instant / docbook-to-man, Sun 22 Dec 1996, 20:33