home | help 
XmClipboard(3)			 LessTif Manuals		  XmClipboard(3)

NAME
     XmClipboard - Motif-compatible clipboard widget

SYNOPSIS
     #include <Xm/CutPaste.h>

DESCRIPTION
     The clipboard is represented by a number of convenience functions which al-
     low  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 Less-
     Tif  source directory.  Specifically, the functions XmTextFieldCopy and Xm-
     TextFieldPaste have been implemented using the functions described below.

CONVENIENCE FUNCTIONS
     The functions are listed alphabetically below.  Do note  however  that  Xm-
     ClipboardStartCopy  is  to  be called before any of the other functions de-
     scribed in this document.

     int XmClipboardBeginCopy(Display *display, Window window, XmString clip_la-
     bel, 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 trans-
     ferred to the clipboard.  Item_id should be the same as in the call to  Xm-
     ClipboardBeginCopy.  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 XmClipboardBeginRe-
     trieve, 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 *for-
     mat_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 for-
     mat_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 indi-
     cates 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_la-
     bel, 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  identi-
     fies  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  re-
     turns 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 time-
     stamp)

     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   re-
     move_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
LessTif Project 		    May 1998			  XmClipboard(3)
home | help