NAME    [Toc]    [Back]

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

SYNOPSIS    [Toc]    [Back]

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

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

DESCRIPTION    [Toc]    [Back]

       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.
  Specifies a pointer to the Display  structure  that
       was  returned in a previous call to XOpenDisplay or XtDisplay.
  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.  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    [Toc]    [Back]

       The function is successful.  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.

SEE ALSO    [Toc]    [Back]

       XmClipboardEndRetrieve(3X),   XmClipboardInquireCount(3X),
       XmClipboardInquireFormat(3X),          XmClipboardInquireLength(3X),   XmClipboardInquirePendingItems(3X),  XmClipboardLock(3X), XmClipboardRetrieve(3X),  XmClipboardStartCopy(3X), XmClipboardUnlock(3X)



                                     XmClipboardStartRetrieve(3X)