XmClipboardStartRetrieve(3X)

     NAME
          XmClipboardStartRetrieve - A clipboard function that
          prepares to retrieve data from the clipboard

     SYNOPSIS
          #include <Xm/CutPaste.h>
          int XmClipboardStartRetrieve (display, window, timestamp)
                  Display * display;
                  Window  window;
                  Time    timestamp;
          (void)

     VERSION
          This page documents Motif 2.1.

     DESCRIPTION
          XmClipboardStartRetrievetells 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 retrieved.

          A return value of XmClipboardTruncate 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 complete the copy from the clipboard be made between
          the call to XmClipboardStartRetrieve and the first call to
          XmClipboardRetrieve. This 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 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.

          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
          XmClipboardSuccess
                    The function is 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
          XmClipboardEndRetrieve(3), XmClipboardInquireCount(3),
          XmClipboardInquireFormat(3), XmClipboardInquireLength(3),
          XmClipboardInquirePendingItems(3), XmClipboardLock(3),
          XmClipboardRetrieve(3), XmClipboardStartCopy(3), and
          XmClipboardUnlock(3).