XmClipboardStartCopy






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



     #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)



     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









                             ‐2‐


          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.









                             ‐3‐


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.



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.



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