XmTransferValue(library call) XmTransferValue(library call)
NAME [Toc] [Back]
XmTransferValue - A toolkit function that transfers data to a
destination
SYNOPSIS [Toc] [Back]
#include <Xm/Xm.h>
void XmTransferValue(
XtPointer transfer_id,
Atom target,
XtCallbackProc proc,
XtPointer client_data,
Time time);
DESCRIPTION [Toc] [Back]
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
- 1 - Formatted: January 24, 2005
XmTransferValue(library call) XmTransferValue(library call)
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.
- 2 - Formatted: January 24, 2005
XmTransferValue(library call) XmTransferValue(library call)
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 [Toc] [Back]
XmTransferSetParameters(3), XmTransferSendRequest(3), and
XmTransferStartRequest(3).
- 3 - Formatted: January 24, 2005 [ Back ] |
