XmQTtransfer(3X) UNIX System V XmQTtransfer(3X)
NAME
XmQTtransfer - A trait that implements data transfer to and
from a widget
SYNOPSIS
#include <Xm/TransferT.h>
typedef struct {
int version;
XmConvertCallbackProc convertProc;
XmDestinationCallbackProc destinationProc;
XmDestinationCallbackProc destinationPreHookProc;
} XmTransferTraitRec, *XmTransferTrait;
void (*XmConvertCallbackProc)(
Widget,
XtPointer,
XtPointer,
void (*XmDestinationCallbackProc)(
Widget,
XtPointer,
XtPointer);
VERSION
This page documents Motif 2.1.
DESCRIPTION
The XmQTtransfer trait is installed on any widget that can
be a source or destination for data transfer. The usual
means of transferring data is the conversion of a selection.
The selections supported by Motif are PRIMARY, SECONDARY,
CLIPBOARD, and MOTIFDROP (for drag and drop operations).
A widget can be the source or destination for zero or more
of these selections.
If your widget is to be a source of data in a transfer, then
your widget must supply a convertProc trait method. This
trait method is responsible for converting data to a
requested target. If your widget is to be a data transfer
destination, then your widget must supply a destinationProc
trait method and can optionally supply a
destinatinoPreHookProc trait method. The destinationProc
trait method is responsible for requesting target(s) from
the source and for providing the name of a transfer
procedure to handle the returned data. The
destinationPreHookProc trait method is used to prepare data
for the destinationProc method.
The standard Motif widgets XmContainer, XmLabel,
XmLabelGadget, XmList, XmScale, XmText, and XmTextField all
hold this trait. XmLabel, XmLabelGadget, XmList, and
XmScaleprovide only convertProc methods. XmContainer,
XmText, and XmTextFieldprovide both convertProc and
Page 1 (printed 1/22/99)
XmQTtransfer(3X) UNIX System V XmQTtransfer(3X)
destinationProc methods.
(See the ExmStringTransfer demonstration widget in the
demos/widgets/Exm/lib directory for an example usage of this
trait.)
The convertProc Trait Method
void convertProc(
Widget widget,
XtPointer clientdata,
XtPointer calldata);
The convertProc method is invoked when the widget is the
source for a data transfer operation. This method converts
a selection to a requested target. The call_data argument
is a pointer to an XmConvertCallbackStruct structure. The
method typically examines the selection and targetmembers of
this structure. It returns the converted data in the value
member and returns an indicator of the conversion status in
the status member.
When the target member of the structure is TARGETS, the
convertProc method usually provides data by calling
XmeStandardTargets and then adding any targets to which the
convertProc method converts data. The method can call
XmeStandardConvert to convert data to any of the standard
targets.
The convertProc method is invoked after any
XmNconvertCallback procedures are called. The callback
procedures can perform all or part of the conversion
themselves, refuse the conversion, or let the convertProc
method handle the conversion. If the callback procedures
perform the complete conversion or refuse the conversion,
the convertProc method is not called. More specifically,
the convertProc method is not called if, after all callback
procedures have returned, the value of the statusmember of
the XmConvertCallbackStruct is other than XmCONVERTDEFAULT
or XmCONVERTMERGE.
widget Specifies the widget that is asked to convert the
data.
client_data
This argument is currently unused. The value is
always NULL.
call_data Specifies a pointer to an XmConvertCallbackStruct
structure.
Following is a description of the
XmConvertCallbackStructstructure:
Page 2 (printed 1/22/99)
XmQTtransfer(3X) UNIX System V XmQTtransfer(3X)
typedef struct {
int reason;
XEvent *event;
Atom selection;
Atom target;
XtPointer source_data;
XtPointer location_data;
int flag;
XtPointer parm;
int parm_format;
unsigned long parm_length;
Atom parm_type;
int status;
XtPointer value;
Atom type;
int format;
unsigned long length;
} XmConvertCallbackStruct;
reason Indicates why the callback was invoked.
event Points to the XEvent that triggered the callback.
It can be NULL.
selection Indicates the selection for which conversion is
being requested. Possible values are CLIPBOARD,
PRIMARY, SECONDARY, and MOTIFDROP.
target Indicates the conversion target.
source_data
Contains information about the selection source.
When the selection is MOTIFDROP, source_data is
the DragContext. Otherwise, it is NULL.
location_data
Contains information about the location of data to
be converted. If the value is NULL, the data to
be transferred consists of the widget's current
selection. Otherwise, the type and interpretation
of the value are specific to the widget class.
flag This member is currently unused.
parm Contains parameter data for this target. If no
parameter data exists, the value is NULL.
When selection is CLIPBOARD and target is
MOTIFCLIPBOARDTARGETS or
MOTIFDEFERREDCLIPBOARDTARGETS, the value is
the requested operation (XmCOPY, XmMOVE, or
XmLINK).
Page 3 (printed 1/22/99)
XmQTtransfer(3X) UNIX System V XmQTtransfer(3X)
parm_format
Specifies whether the data in parm should be
viewed as a list of 8-bit, 16-bit, or 32-bit
quantities. Possible values are 0 (when parm is
NULL), 8, 16, and 32.
parm_length
Specifies the number of elements of data in parm,
where each element has the number of bits
specified by parm_format. When parm is NULL, the
value is 0.
parm_type Specifies the parameter type of parm.
status An IN/OUT member that specifies the status of the
conversion. The initial value set by the toolkit
is XmCONVERTDEFAULT, but an XmNconvertCallback
procedure may have set a different value.
Following are the possible values:
XmCONVERTDEFAULT
This value means that the convertProc
trait method, if it wishes, should
perform the entire conversion. If the
convertProc produces any data, it
overwrites the data provided by the
callback procedures in the value member.
XmCONVERTMERGE
This value means that the convertProc
trait method should merge its converted
data, if any, with the data provided by
the callback procedures. If the
convertProc produces any data, it uses
XmeConvertMerge to append its data to
the data provided by the callback
procedures in the value member. This
value is intended for use with targets
that result in lists of data, such as
TARGETS.
XmCONVERTDONE
The status member never has this value
on entry to convertProc. When the
convertProc trait method finishes a
successful conversion, it sets status to
XmCONVERTDONE.
XmCONVERTREFUSE
The status member never has this value
on entry to the convertProc. When the
convertProc trait method terminates an
Page 4 (printed 1/22/99)
XmQTtransfer(3X) UNIX System V XmQTtransfer(3X)
unsuccessful conversion, it sets status
to XmCONVERTREFUSE.
Before returning, the convertProc trait method
should always set statusto either XmCONVERTDONE,
indicating a successful conversion, or
XmCONVERTREFUSE, indicating an unsuccessful
conversion.
value An IN/OUT parameter that contains any data that
the callback procedures or the convertProc trait
method produces as a result of the conversion.
The initial value is NULL. If the convertProc
trait method sets this member, it must ensure that
the type, format, and length members correspond to
the data in value. The convertProc trait method
is responsible for allocating memory when it sets
this member. The toolkit frees this memory when
it is no longer needed.
type An IN/OUT parameter that indicates the type of the
data in the value member. The initial value is
INTEGER.
format An IN/OUT parameter that specifies whether the
data in valueshould be viewed as a list of 8-bit,
16-bit, or 32-bit quantities. The initial value
is 8. The convertProc trait method can set this
member to 8, 16, or 32.
length An IN/OUT member that specifies the number of
elements of data in value, where each element has
the number of bits specified by format. The
initial value is 0.
The destinationProc Trait Method
void destinationProc(
Widget widget,
XtPointer clientdata,
XtPointer calldata);
The destinationProc trait method is invoked when the widget
is the destination for a data transfer operation. The
call_data argument is a pointer to an
XmDestinationCallbackStruct structure. This method requests
conversion of a selection to an appropriate target, usually
by calling XmTransferValue. The method usually supplies a
callback to XmTransferValue that receives and possibly
inserts the converted data. The XmTransferValue callback
returns an indicator of the transfer status. Either the
destinationProc trait method or the XmTransferValuecallback
can also terminate the transfer operation by calling
Page 5 (printed 1/22/99)
XmQTtransfer(3X) UNIX System V XmQTtransfer(3X)
XmTransferDone.
The destinationProc trait method is invoked after any
XmNdestinationCallback procedures are called and after all
data conversions initiated by those callback procedures are
complete. The callback procedures can perform the data
transfer themselves, refuse the transfer, or let the
destinationProc trait method handle the transfer. If the
callback procedures perform the transfer themselves or
refuse the transfer, the destinationProc trait method is not
called. More specifically, the destinationProc trait method
is not invoked if a callback procedure has called
XmTransferDone with a transfer status other than
XmTRANSFERDEFAULT.
widget Specifies the widget that is the destination for
the transfer.
client_data
This argument is currently unused. The value is
always NULL.
call_data Specifies a pointer to an
XmDestinationCallbackStruct structure.
Following is a description of the
XmDestinationCallbackStructstructure:
typedef struct {
int reason;
XEvent *event;
Atom selection;
XtEnum operation;
int flags;
XtPointer transfer_id;
XtPointer destination_data;
XtPointer location_data;
Time time;
} XmDestinationCallbackStruct;
reason Indicates why the callback was invoked.
event Points to the XEvent that triggered the callback.
It can be NULL.
selection Indicates the selection for which data transfer is
being requested. Possible values are CLIPBOARD,
PRIMARY, SECONDARY, and MOTIFDROP.
operation Indicates the type of transfer operation
requested.
Page 6 (printed 1/22/99)
XmQTtransfer(3X) UNIX System V XmQTtransfer(3X)
⊕ When the selection is PRIMARY, possible
values are XmMOVE, XmCOPY, and XmLINK.
⊕ When the selection is SECONDARY or
CLIPBOARD, possible values are XmCOPY and
XmLINK.
⊕ When the selection is MOTIFDROP, possible
values are XmMOVE, XmCOPY, XmLINK, and
XmOTHER. A value of XmOTHER means that the
callback procedure must get further
information from the
XmDropProcCallbackStruct in the
destination_data member.
flags Indicates whether or not the destination widget is
also the source of the data to be transferred.
Following are the possible values:
XmCONVERTINGNONE
The destination widget is not the source
of the data to be transferred.
XmCONVERTINGSAME
The destination widget is the source of
the data to be transferred.
transfer_id
Serves as a unique ID to identify the transfer
transaction.
destination_data
Contains information about the destination. When
the selection is MOTIFDROP, the destinationProc
trait method is called by the drop site's
XmNdropProc, and destination_datais a pointer to
the XmDropProcCallbackStruct passed to the
XmNdropProc procedure. When the selection is
SECONDARY, destination_data is an Atom
representing a target recommmended by the
selection owner for use in converting the
selection. Otherwise, destination_data is NULL.
location_data
Contains information about the location where data
is to be transferred. The value is always NULL
when the selection is SECONDARY or CLIPBOARD. If
the value is NULL, the data is to be inserted at
the widget's cursor position. Otherwise, the type
and interpretation of the value are specific to
the widget class. The value of location_data is
only valid for the duration of a transfer. Once
Page 7 (printed 1/22/99)
XmQTtransfer(3X) UNIX System V XmQTtransfer(3X)
transfer done procedures start to be called,
location_data will no longer be stable.
time Indicates the time when the transfer operation
began.
The destinationPreHookProc Trait Method
void destinationPreHookProc(
Widget widget,
XtPointer clientdata,
XtPointer calldata);
The destinationPreHookProc trait method is invoked when the
widget is the destination for a data transfer operation.
This method is called before any XmNdestinationCallback
procedures are invoked. The call_data argument is a pointer
to an XmDestinationCallbackStruct structure. The method can
provide any information, such as a value for the
location_data member of the structure, that the
XmNdestinationCallback procedures or the
destinationProctrait method may need.
widget Specifies the widget that is the destination for
the transfer.
client_data
This argument is currently unused. The value is
always NULL.
call_data Specifies a pointer to an
XmDestinationCallbackStruct structure.
RELATED
ExmStringTransfer(3), XmTransferDone(3), XmTransferValue(3),
XmeClipboardSink(3), XmeClipboardSource(3),
XmeConvertMerge(3), XmeDragSource(3), XmeDropSink(3),
XmeGetEncodingAtom(3), XmePrimarySink(3),
XmePrimarySource(3), XmeSecondarySink(3),
XmeSecondarySource(3), XmeSecondaryTransfer(3),
XmeStandardConvert(3), XmeStandardTargets(3), and
XmeTransferAddDoneProc(3).
Page 8 (printed 1/22/99)