--- name: "XmClipboard" section: "3" platform: "linux" package: "lesstif-doc" version: "1:0.95.2-1.1" release: "Debian 7 (Wheezy)" platforms: ["linux"] url: "https://new.carta.tech/XmClipboard" --- # XmClipboard(3) Motif-compatible clipboard widget ## NAME XmClipboard - Motif-compatible clipboard widget ## SYNOPSIS **#include \** ## DESCRIPTION The clipboard is represented by a number of convenience functions which allow a widget or an application to exchange information with other widgets or applications. The APIs described in this document are to be used by application writers, but the LessTif widgets use them internally as well when the user performs an action commanding the widget to interact with the clipboard. Examples of the use of these functions can be found in the implementation of the [**XmTextField**(3)](/XmTextField/3.md) widget, in *lib/Xm/TextF.c* under the root of the LessTif source directory. Specifically, the functions XmTextFieldCopy and XmTextFieldPaste have been implemented using the functions described below. ## CONVENIENCE FUNCTIONS The functions are listed alphabetically below. Do note however that XmClipboardStartCopy is to be called before any of the other functions described in this document. **int XmClipboardBeginCopy(Display \*display, Window window, XmString clip\_label, Widget widget, VoidProc callback, long \*item\_id)** This appears to be the same as XmClipboardStartCopy. This function should be called first, then XmClipboardCopy may be called, potentially multiple times; the sequence must be ended with a call of XmClipboardEndCopy. **int XmClipboardCancelCopy(Display \*display, Window window, long item\_id)** Just what the name says : cancel a pending copy operation. **int XmClipboardCopy(Display \*display, Window window, long item\_id, char \*format\_name, XtPointer buffer, unsigned long length, long private\_id, long \*data\_id)** This function allows you to try to copy the buffer that needs to be transferred to the clipboard. Item\_id should be the same as in the call to XmClipboardBeginCopy. Private\_id is a number that you can pass. **int XmClipboardCopyByName(Display \*display, Window window, long data\_id, XtPointer buffer, unsigned long length, long private\_id)** **int XmClipboardEndCopy(Display \*display, Window window, long item\_id)** See description of XmClipboardBeginCopy and XmClipboardCopy. **int XmClipboardEndRetrieve(Display \*display, Window window)** Ends a cycle of retrieval calls, started with a call to XmClipboardBeginRetrieve, and with calls of XmClipboardRetrieve in the middle. **int XmClipboardInquireCount(Display \*display, Window window, int \*count, unsigned long \*max\_length)** **int XmClipboardInquireFormat(Display \*display, Window window, int index, XtPointer format\_name\_buf, unsigned long buffer\_len, unsigned long \*copied\_len)** **int XmClipboardInquireLength(Display \*display, Window window, char \*format\_name, unsigned long \*length)** You can call this function just beforeXmClipboardRetrieve to figure out how much data is waiting. This way you can allocate storage dynamically. An example of the use of this function is in the LessTif sources in the file lib/Xm/TextF.c, in function XmTextFieldPaste. **int XmClipboardInquirePendingItems(Display \*display, Window window, char \*format\_name, XmClipboardPendingList \*item\_list, unsigned long \*count)** **int XmClipboardLock(Display \*display, Window window)** **int XmClipboardRegisterFormat(Display \*display, char \*format\_name, int format\_length)** **int XmClipboardRetrieve(Display \*display, Window window, char \*format\_name, XtPointer buffer, unsigned long length, unsigned long \*num\_bytes, long \*private\_id)** Copy a chunk of the clipboard's data into application memory. Length indicates the buffer's size. Private\_id returns private data associated with the data item (this is just a number). This function can return **ClipboardLocked**. **int XmClipboardStartCopy(Display \*display, Window window, XmString clip\_label, Time timestamp, Widget widget, XmCutPasteProc callback, long \*item\_id)** This function creates temporary storage that will receive clipboard data. It must be called before any other XmClipboard operation. Window identifies the widget's window; it should be passed to all clipboard routines in the same application. Clip\_label identifies the data item by name. Widget is the widget ID receiving callbacks mentioned in callback. Item\_id returns a number to be used by the other clipboard copy functions to refer to this particular object. This function can return **ClipboardLocked**. **int XmClipboardStartRetrieve(Display \*display, Window window, Time timestamp)** This function indicates the start of incremental retrieval of data from the clipboard. Increments can be copied now with XmClipboardRetrieve, while XmClipboardEndRetrieve should be called to finish copying the contents of the clipboard. These functions should be called with identical format\_name arguments. This function can return **ClipboardLocked**. **int XmClipboardUndoCopy(Display \*display, Window window)** **int XmClipboardUnlock(Display \*display, Window window, Boolean remove\_all\_locks)** **int XmClipboardWithdrawFormat(Display \*display, Window window, int data\_id)** ## CALLBACKS The callback functions triggered by XmClipboardStartCopy should have the following signature : **void CallbackFunction(Widget w, int \*data\_id, int \*private, int \*reason)** The data\_id points to the data passed by name. The private pointer points to data passed from XmClipboardCopy. The reason field can either return XmCR\_CLIPBOARD\_DATA\_DELETE or XmCR\_CLIPBOARD\_DATA\_REQUEST. ## RETURN VALUES All of the functions described in this page can return the following codes : **ClipboardSuccess** the call ended successfully **ClipboardFail** failure for various reasons - see the explanation with the function **ClipboardLocked** some other application has locked the clipboard already **ClipboardNoData** it's empty or the format wasn't found **ClipboardTruncate** the data was truncated because the buffer was too small **ClipboardBadFormat** the format name was NULL or the format didn't have length 8, 16, or 32 ## SEE ALSO