XmClipboardStartRetrieve(3X)

     NAME
          XmClipboardStartRetrieve - A clipboard function that starts
          a copy from the clipboard

     SYNOPSIS
          #include <Xm/Xm.h>
          #include <Xm/CutPaste.h>

          int XmClipboardStartRetrieve (display, window, timestamp)
               Display   * display;
               Window    window;
               Time      timestamp;

     DESCRIPTION
          XmClipboardStartRetrieve tells the clipboard routines that
          the application is ready to start copying an item from the
          clipboard.  The clipboard is locked by this routine and
          stays locked until XmClipboardEndRetrieve is called.
          Between a call to XmClipboardStartRetrieve and a call to
          XmClipboardEndRetrieve, multiple calls to
          XmClipboardRetrieve with the same format name result in data
          being incrementally copied from the clipboard until the data
          in that format has all been copied.

          The return value ClipboardTruncate from calls to
          XmClipboardRetrieve indicates that more data remains to be
          copied in the given format.  It is recommended that any
          calls to the Inquire functions that the application needs to
          make to effect the copy from the clipboard be made between
          the call to XmClipboardStartRetrieve and the first call to
          XmClipboardRetrieve.  That way, the application does not
          need to call XmClipboardLock and XmClipboardUnlock.

          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.

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

     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.

     RELATED INFORMATION
          XmClipboardEndRetrieve(3X), XmClipboardInquireCount(3X),
          XmClipboardInquireFormat(3X), XmClipboardInquireLength(3X),
          XmClipboardInquirePendingItems(3X), XmClipboardLock(3X),
          XmClipboardRetrieve(3X), XmClipboardStartCopy(3X), and
          XmClipboardUnlock(3X).