XmTransferValue(3X) UNIX System V XmTransferValue(3X)
NAME
XmTransferValue - A toolkit function that transfers data to
a destination
SYNOPSIS
#include <Xm/Xm.h>
void XmTransferValue(
XtPointer transferid,
Atom target,
XtCallbackProc proc,
XtPointer clientdata,
Time time);
VERSION
This page documents Motif 2.1.
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.
transferid
Specifies a unique indentifier for the data
transfer operation. The value must be the same as
the value of the transferid 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
Page 1 (printed 1/22/99)
XmTransferValue(3X) UNIX System V XmTransferValue(3X)
This procedure can be called before or after
XmTransferValuereturns.
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.
transferid
Specifies a unique indentifier for the data
Page 2 (printed 1/22/99)
XmTransferValue(3X) UNIX System V XmTransferValue(3X)
transfer operation. The value is the same as the
value of the transferid argument to
XmTransferValue.
flags This member is currently unused. The value is
always XmSELECTIONDEFAULT.
remaining Indicates the number of transfers remaining for
the operation specified by transferid.
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).
Page 3 (printed 1/22/99)