[ Previous | Next | Contents | Glossary | Home | Search ]
Motif 2.1 Widget Writer's Guide

XmeClipboardSource

A toolkit function that places data on the clipboard

Format

#include <Xm/Xm.h>
Boolean XmeClipboardSourceWidget
widgetXtEnum opTime
time

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 XmQTtransfer trait.) 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 widget to convert the CLIPBOARD selection to that target. XmeClipboardSource then calls XmClipboardCopy to copy the converted data to the clipboard.

    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 widget return a target, XmeClipboardSource asks the widget to convert the CLIPBOARD selection to the _MOTIF_SNAPSHOT target. 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 widget to convert the snapshot data to that target, using as the selection the 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.

        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 time value. 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).

        4. [ Previous | Next | Contents | Glossary | Home | Search ]