NAME

       XmClipboardCopy  —  A  clipboard function that copies a data item to temporary storage for
       later copying to clipboard "XmClipboardCopy" "clipboard functions" "XmClipboardCopy"

SYNOPSIS

       #include <Xm/CutPaste.h>
       int XmClipboardCopy (display, window, item_id, format_name,
               buffer, length, private_id, data_id)
               Display * display;
               Window  window;
               long    item_id;
               char    * format_name;
               XtPointer       buffer;
               unsigned long   length;
               long    private_id;
               long    * data_id;
       (void)

DESCRIPTION

       XmClipboardCopy copies a data item to temporary storage.  The  data  item  is  moved  from
       temporary  storage  to  the  clipboard data structure when a call to XmClipboardEndCopy is
       made.  Additional calls  to  XmClipboardCopy  before  a  call  to  XmClipboardEndCopy  add
       additional  data  item formats to the same data item or append data to an existing format.
       Formats are described in the Inter-Client  Communication  Conventions  Manual  (ICCCM)  as
       targets.

       NOTE: Do not call XmClipboardCopy before a call to XmClipboardStartCopy has been made. The
       latter function allocates temporary storage required by XmClipboardCopy.

       If the buffer argument is NULL, the data is considered to be passed by  name.   When  data
       that  has  been  passed by name is later requested by another application, the application
       that owns the data receives a callback with a request for the data. The  application  that
       owns  the data must then transfer the data to the clipboard with the XmClipboardCopyByName
       function.  When a data item that was passed by name is deleted  from  the  clipboard,  the
       application  that  owns  the  data  receives a callback stating that the data is no longer
       needed.

       For information on the callback  function,  see  the  callback  argument  description  for
       XmClipboardStartCopy.

       display   Specifies  a  pointer  to  the Display structure that was returned in a previous
                 call to XOpenDisplay or XtDisplay.

       window    Specifies the window ID of a widget that relates the application window  to  the
                 clipboard.  The  widget's  window ID can be obtained through XtWindow.  The same
                 application instance should pass the same window ID to  each  of  the  clipboard
                 functions that it calls.

       item_id   Specifies  the number assigned to this data item.  This number was returned by a
                 previous call to XmClipboardStartCopy.

       format_name
                 Specifies the name of the format in  which  the  data  item  is  stored  on  the
                 clipboard. The format was known as target in the ICCCM.

       buffer    Specifies the buffer from which the clipboard copies the data.

       length    Specifies the length, in bytes, of the data being copied to the clipboard.

       private_id
                 Specifies  the  private  data  that the application wants to store with the data
                 item.

       data_id   Specifies an  identifying  number  assigned  to  the  data  item  that  uniquely
                 identifies  the  data  item  and the format.  This argument is required only for
                 data that is passed by name.

RETURN

       XmClipboardSuccess
                 The function was successful.

       XmClipboardLocked
                 The function failed because the clipboard was locked by another application. The
                 application  can  continue  to  call the function again with the same parameters
                 until the lock goes away. This gives the application the opportunity to  ask  if
                 the user wants to keep trying or to give up on the operation.

       XmClipboardFail
                 The  function  failed because XmClipboardStartCopy was not called or because the
                 data item contains too many formats.

RELATED

       XmClipboardCopyByName(3), XmClipboardEndCopy(3), and XmClipboardStartCopy(3).

                                                                               XmClipboardCopy(3)