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)