NAME

       XmClipboardStartCopy   —   A   clipboard   function   that   sets   up   a  storage  and  data  structure
       "XmClipboardStartCopy" "clipboard functions" "XmClipboardStartCopy"

SYNOPSIS

       #include <Xm/CutPaste.h>
       int XmClipboardStartCopy (display, window, clip_label,
               timestamp, widget, callback, item_id)
               Display * display;
               Window  window;
               XmString        clip_label;
               Time    timestamp;
               Widget  widget;
               XmCutPasteProc  callback;
               long    * item_id;
       (void)

DESCRIPTION

       XmClipboardStartCopy sets up storage and data structures to receive clipboard data.  An application calls
       this function during a cut or copy operation.  The data item that these structures receive  then  becomes
       the next data item in the clipboard.

       Copying  a large piece of data to the clipboard can take a long time.  It is possible that, once the data
       is copied, no application will ever request that data. The Motif Toolkit provides a mechanism so that  an
       application  does  not  need  to actually pass data to the clipboard until the data has been requested by
       some application.

       Instead, the application passes format  and  length  information  in  XmClipboardCopy  to  the  clipboard
       functions, along with a widget ID and a callback function address that is passed in XmClipboardStartCopy.
       The  widget  ID  is  necessary for communications between the clipboard functions in the application that
       owns the data and the clipboard functions in the application that requests the data.

       The  callback  functions  are  responsible  for  copying  the  actual  data  to  the  clipboard   through
       XmClipboardCopyByName.  The  callback  function  is  also  called  if  the  data item is removed from the
       clipboard and the actual data is no longer needed.

       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.

       clip_label
                 Specifies the label to be associated with the data item.  This argument is used to identify the
                 data item, as in a clipboard viewer.  An example of a label is the name of the application that
                 places the data in the clipboard.

       timestamp Specifies the time of the event that triggered the copy.  A valid timestamp must  be  supplied;
                 it is not sufficient to use CurrentTime.

       widget    Specifies  the  ID  of  the  widget that receives messages requesting data previously passed by
                 name. This argument must be present in order to pass data by name. Any valid widget ID in  your
                 application  can  be used for this purpose and all the message handling is taken care of by the
                 cut and paste functions.

       callback  Specifies the address of the callback function that is called when  the  clipboard  needs  data
                 that was originally passed by name. This is also the callback to receive the delete message for
                 items  that were originally passed by name. This argument must be present in order to pass data
                 by name.

       item_id   Specifies the number assigned to this data item.  The application uses this number in calls  to
                 XmClipboardCopy, XmClipboardEndCopy, and XmClipboardCancelCopy.

       For more information on passing data by name, see XmClipboardCopy(3) and XmClipboardCopyByName(3).

       The  widget  and callback arguments must be present in order to pass data by name. The callback format is
       as follows:

       void (*callback) (widget, data_id, private, reason)
               Widget  widget;
               long    *data_id;
               long    *private;
               int     *reason;
       (void)

       widget    Specifies the ID of the widget passed to this function.

       data_id   Specifies the identifying number returned by XmClipboardCopy, which identifies the pass-by-name
                 data.

       private   Specifies the private information passed to XmClipboardCopy.

       reason    Specifies  the  reason.  XmCR_CLIPBOARD_DATA_DELETE  or  XmCR_CLIPBOARD_DATA_REQUEST  are   the
                 possible values.

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.

RELATED

       XmClipboardCancelCopy(3),     XmClipboardCopy(3),     XmClipboardCopyByName(3),    XmClipboardEndCopy(3),
       XmClipboardEndRetrieve(3),            XmClipboardInquireCount(3),            XmClipboardInquireFormat(3),
       XmClipboardInquireLength(3),            XmClipboardInquirePendingItems(3),            XmClipboardLock(3),
       XmClipboardRegisterFormat(3),            XmClipboardRetrieve(3),             XmClipboardStartRetrieve(3),
       XmClipboardUndoCopy(3), XmClipboardUnlock(3), and XmClipboardWithdrawFormat(3).

                                                                                         XmClipboardStartCopy(3)