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;


VERSION
     This page documents version 1.2 of the Motif library.

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  XmClip-
     boardEndRetrieve,  multiple calls to XmClipboardRetrieve with the same for-
     mat 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  indi-
     cates  that more data remains to be copied in the given format.  It is rec-
     ommended 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 XmClipboard-
     Unlock.


     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  ob-
                 tained 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), XmClipboard-
     InquireFormat(3X), XmClipboardInquireLength(3X), XmClipboardInquirePendin-
     gItems(3X), XmClipboardLock(3X), XmClipboardRetrieve(3X), XmClipboardStart-
     Copy(3X), and XmClipboardUnlock(3X).

                                                    XmClipboardStartRetrieve(3X)