XmTransferValue

Motif 2.1 Programmer's Reference

XmTransferValue

A toolkit function that transfers data to a destination

Format

#include
<Xm/Xm.h>
void XmTransferValue
XtPointer
transfer_idAtom targetXtCallbackProc
procXtPointer client_dataTime
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).