Motif Programmer's Guide Migration Version

Motif 2.1 Programmer's Guide

Utility Routines

The Motif clipboard interface has routines to lock and unlock the clipboard, to make inquiries about its contents, and to register new targets.

XmClipboardLock prevents another application from gaining access to the Motif clipboard. XmClipboardUnlock allows other applications to gain access. The clipboard interface automatically locks the clipboard during calls to XmClipboardStartRetrieve and XmClipboardEndRetrieve. At other times, an application can use XmClipboardLock and XmClipboardUnlock to lock the clipboard explicitly.

The clipboard interface includes four routines for making inquiries about the clipboard contents:

XmClipboardInquireCount returns the number of targets for which data exists on the clipboard.

XmClipboardInquireFormat returns the name of the target for a given index of targets on the clipboard. An application could retrieve the names of all the targets associated with data on the clipboard by first calling XmClipboardInquireCount to find out how many such targets exist and then calling XmClipboardInquireFormat with indices from 1 to the number of targets, inclusive. Note that the first index for XmClipboardInquireFormat is 1, not 0.

XmClipboardInquireLength returns the number of bytes of data associated with a given target on the clipboard.

XmClipboardInquirePendingItems returns a list of pairs of data ID and private ID for a given target if that target exists on the clipboard and if the owner has asserted that it will supply the actual data on request (but has not yet done so).

An application that makes more than one call to an inquiry function at a time should use XmClipboardLock and XmClipboardUnlock to lock the clipboard for the duration of the interaction.

XmClipboardRegisterFormat registers a new target with the clipboard interface. The application supplies the length of the data in bits along with the name of the target so that the correct byte order will be maintained when transferring data across platforms. All targets defined in ICCCM are preregistered; the application does not have to call XmClipboardRegisterFormat for these.