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)