XmeClipboardSource(3X) UNIX System V XmeClipboardSource(3X)
NAME
XmeClipboardSource - A toolkit function that places data on
the clipboard
SYNOPSIS
#include <Xm/Xm.h>
Boolean XmeClipboardSource(
Widget widget,
XtEnum op,
Time time);
VERSION
This page documents Motif 2.1.
DESCRIPTION
XmeClipboardSource places widget data on the clipboard,
using the Motif clipboard interface. If there is an owner
of CLIPBOARD_MANAGER, calling XmeClipboardSource produces
undefined results.
This reference page uses the term "the conversion routines
associated with widget widget." Whenever you see that term,
it means that XmeClipboardSource is making the following
sequence of calls:
1. Calls the application's XmNconvertCallback procedures,
if any.
2. Calls the source widget's convertProc trait method.
(convertProc is one of the trait methods of the
XmQTtransfertrait.) However, if any
XmNconvertCallback procedure returns XmCONVERT_DONE or
XmCONVERT_REFUSE, then XmePrimarySource will not call
convertProc.
If the selection member is CLIPBOARD and the target member
is _MOTIF_CLIPBOARD_TARGETS or
_MOTIF_DEFERRED_CLIPBOARD_TARGETS, then XmeClipboardSource
sets the value of the parm member of the
XmConvertCallbackStruct to the value of the op argument.
XmeClipboardSource makes the following sequence of calls:
1. XmeClipboardSource asks the conversion routines
associated with widget widget to convert the CLIPBOARD
selection to _MOTIF_CLIPBOARD_TARGETS.
2. For each returned target, XmeClipboardSource asks the
conversion routines associated with widget widgetto
convert the CLIPBOARD selection to that target.
XmeClipboardSource then calls XmClipboardCopy to copy
the converted data to the clipboard.
Page 1 (printed 7/20/06)
XmeClipboardSource(3X) UNIX System V XmeClipboardSource(3X)
3. XmeClipboardSource asks the conversion routines
associated with widget widget to convert the CLIPBOARD
selection to _MOTIF_DEFERRED_CLIPBOARD_TARGETS.
4. If any of the conversion routines associated with
widget widgetreturn a target, XmeClipboardSource asks
the widget to convert the CLIPBOARD selection to the
_MOTIF_SNAPSHOTtarget. The responding conversion
routine is expected to save a snapshot of the data and
to return a distinguisher atom that uniquely
identifies the snapshot.
5. XmeClipboardSource places each deferred target on the
clipboard by name, using XmClipboardCopy.
6. If the op argument is XmMOVE and the data is
successfully transferred, XmeClipboardSource asks the
conversion routines associated with widget widget to
convert the CLIPBOARD selection to the DELETE target.
In addition, XmeClipboardSource establishes a callback that
is automatically called whenever a request is made to
convert data to a deferred target. This callback is
responsible for converting snapshot data to a particular
target. Here is the sequence of calls that the callback
makes:
1. The callback asks the conversion routines associated
with widget widgetto convert the snapshot data to that
target, using as the selectionthe distinguisher atom
returned from the _MOTIF_SNAPSHOT conversion.
2. The callback copies the converted data to the
clipboard, using XmClipboardCopyByName.
3. When the snapshot data is no longer needed, the
callback asks each of the conversion routines
associated with widget widget to convert the snapshot
to the DONE target, using the distinguisher atom as
the selection.
The widget responding to _MOTIF_SNAPSHOT must own the
snapshot atom.
The _MOTIF_SNAPSHOT target takes an optional parameter which
should be used to distinguish the current selection. If the
parameter is NULL, the conversion routine must allocate a
distinguisher atom and assign it to the selection member of
the XmConvertCallbackStruct.
widget Specifies the widget that is the source for the
data.
Page 2 (printed 7/20/06)
XmeClipboardSource(3X) UNIX System V XmeClipboardSource(3X)
op Specifies the transfer operation. Possible values
are XmMOVE, XmCOPY, and XmLINK.
time Specifies the time of the transfer. This is
usually the timestamp from the event passed to an
action routine. You should call
XtLastTimeStampProcessed to generate the
timevalue. If you set time to CurrentTime or 0,
UTM will automatically change the call to
XtLastTimeStampProcessed.
RETURN
This function returns False if the clipboard is locked or if
no data is placed on the clipboard. Otherwise, it returns
True.
RELATED
XmQTtransfer(3), XmTransferDone(3), XmTransferValue(3),
XmeClipboardSink(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 3 (printed 7/20/06)
