<HTML><HEAD><TITLE>Manpage of XmClipboard</TITLE>
</HEAD><BODY>
<H1>XmClipboard</H1>
Section: LessTif Manuals (3)<BR>Updated: May 1998<BR><A HREF="#index">Index</A>
<BR><A HREF="lesstif.html">Return to Main Contents</A>
<HR>

<A NAME="lbAB">&nbsp;</A>
<H2>NAME</H2>

XmClipboard
<A NAME="lbAC">&nbsp;</A>
<H2>SYNOPSIS</H2>

<B>#include &lt;<A HREF="include/Xm/CutPaste.h">Xm/CutPaste.h</A>&gt;</B>

<A NAME="lbAD">&nbsp;</A>
<H2>DESCRIPTION</H2>

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.
<P>

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.
<P>

Examples of the use of these functions can be found in the implementation
of the
<B><A HREF="XmTextField.html">XmTextField</A></B>(3)

widget, in
<I>lib/Xm/TextF.c</I>

under the root of the LessTif source directory.
Specifically, the functions XmTextFieldCopy and XmTextFieldPaste have
been implemented using the functions described below.
<A NAME="lbAE">&nbsp;</A>
<H2>CONVENIENCE FUNCTIONS</H2>

<P>

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.
<P>


<B>int XmClipboardBeginCopy(Display *display, Window window, XmString clip_label, Widget widget, VoidProc callback, long *item_id)</B>

<P>

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.
<P>


<B>int XmClipboardCancelCopy(Display *display, Window window, long item_id)</B>

<P>

Just what the name says : cancel a pending copy operation.
<P>


<B>int XmClipboardCopy(Display *display, Window window, long item_id, char *format_name, XtPointer buffer, unsigned long length, long private_id, long *data_id)</B>

<P>

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.
<P>


<B>int XmClipboardCopyByName(Display *display, Window window, long data_id, XtPointer buffer, unsigned long length, long private_id)</B>

<P>


<B>int XmClipboardEndCopy(Display *display, Window window, long item_id)</B>

<P>

See description of XmClipboardBeginCopy and XmClipboardCopy.
<P>


<B>int XmClipboardEndRetrieve(Display *display, Window window)</B>

<P>

Ends a cycle of retrieval calls,
started with a call to XmClipboardBeginRetrieve,
and with calls of XmClipboardRetrieve in the middle.
<P>


<B>int XmClipboardInquireCount(Display *display, Window window, int *count, unsigned long *max_length)</B>

<P>


<B>int XmClipboardInquireFormat(Display *display, Window window, int index, XtPointer format_name_buf, unsigned long buffer_len, unsigned long *copied_len)</B>

<P>


<B>int XmClipboardInquireLength(Display *display, Window window, char *format_name, unsigned long *length)</B>

<P>

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.
<P>


<B>int XmClipboardInquirePendingItems(Display *display, Window window, char *format_name, XmClipboardPendingList *item_list, unsigned long *count)</B>

<P>


<B>int XmClipboardLock(Display *display, Window window)</B>

<P>


<B>int XmClipboardRegisterFormat(Display *display, char *format_name, int format_length)</B>

<P>


<B>int XmClipboardRetrieve(Display *display, Window window, char *format_name, XtPointer buffer, unsigned long length, unsigned long *num_bytes, long *private_id)</B>

<P>

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).
<P>

This function can return
<B>ClipboardLocked</B>.

<P>


<B>int XmClipboardStartCopy(Display *display, Window window, XmString clip_label, Time timestamp, Widget widget, XmCutPasteProc callback, long *item_id)</B>

<P>

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.
<P>

This function can return
<B>ClipboardLocked</B>.

<P>


<B>int XmClipboardStartRetrieve(Display *display, Window window, Time timestamp)</B>

<P>

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.
<P>

This function can return
<B>ClipboardLocked</B>.

<P>


<B>int XmClipboardUndoCopy(Display *display, Window window)</B>

<P>


<B>int XmClipboardUnlock(Display *display, Window window, Boolean remove_all_locks)</B>

<P>


<B>int XmClipboardWithdrawFormat(Display *display, Window window, int data_id)</B>

<A NAME="lbAF">&nbsp;</A>
<H2>CALLBACKS</H2>

<P>

The callback functions triggered by XmClipboardStartCopy should have the
following signature :
<P>

<B>void CallbackFunction(Widget w, int *data_id, int *private, int *reason)</B>

<P>

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.
<A NAME="lbAG">&nbsp;</A>
<H2>RETURN VALUES</H2>

All of the functions described in this page can return the following codes :
<P>

<B>ClipboardSuccess</B>

the call ended successfully
<P>

<B>ClipboardFail</B>

failure for various reasons - see the explanation with the function
<P>

<B>ClipboardLocked</B>

some other application has locked the clipboard already
<P>

<B>ClipboardNoData</B>

it's empty or the format wasn't found
<P>

<B>ClipboardTruncate</B>

the data was truncated because the buffer was too small
<P>

<B>ClipboardBadFormat</B>

the format name was NULL or the format didn't have length 8, 16, or 32
<A NAME="lbAH">&nbsp;</A>
<H2>SEE ALSO</H2>

<P>

<HR>
<A NAME="index">&nbsp;</A><H2>Index</H2>
<DL>
<DT><A HREF="#lbAB">NAME</A><DD>
<DT><A HREF="#lbAC">SYNOPSIS</A><DD>
<DT><A HREF="#lbAD">DESCRIPTION</A><DD>
<DT><A HREF="#lbAE">CONVENIENCE FUNCTIONS</A><DD>
<DT><A HREF="#lbAF">CALLBACKS</A><DD>
<DT><A HREF="#lbAG">RETURN VALUES</A><DD>
<DT><A HREF="#lbAH">SEE ALSO</A><DD>
</DL>
<HR>
This document was created by
<A HREF="http://www.debian.org/Packages/unstable/doc/man2html.html">man2html</A>,
using the manual pages.<BR>
Time: 22:45:31 GMT, January 14, 2000
</BODY>
</HTML>
