NAME

       XmClipboardStartRetrieve  —  A  clipboard function that prepares to retrieve data from the
       clipboard "XmClipboardStartRetrieve" "clipboard functions" "XmClipboardStartRetrieve"

SYNOPSIS

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

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

                                                                      XmClipboardStartRetrieve(3)