XmClipboardCopy(3X)

     NAME
          XmClipboardCopy - A clipboard function that copies a data
          item to temporary storage for later copying to clipboard

     SYNOPSIS
          #include <Xm/Xm.h>
          #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 longlength;
               long       private_id;
               long       * data_id;

     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 a widget's window ID that relates the
               application window to the clipboard.  The widget's
               window ID can be obtained by using 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.  Format is known as target
               in the ICCCM.

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

          length
               Specifies the length 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 VALUE
          ClipboardSuccess
               The function is successful.

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

          ClipboardFail
               The function failed because XmClipboardStartCopy was
               not called or because the data item contains too many
               formats.
     RELATED INFORMATION
          XmClipboardCopyByName(3X), XmClipboardEndCopy(3X), and
          XmClipboardStartCopy(3X).