NAME
XmClipboard - Motif-compatible clipboard widget
SYNOPSIS
#include <Xm/CutPaste.h>
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) 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