XmClipboard

#include <Xm/CutPaste.h>

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 API's 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) 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.

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)

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.

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