NAME    [Toc]    [Back]

       XmClipboardRetrieve  - A clipboard function that retrieves
       a data item from the clipboard

SYNOPSIS    [Toc]    [Back]

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

       int  XmClipboardRetrieve  (display,  window,  format_name,
       buffer, length, num_bytes, private_id)
               Display * display;
               Window window;
               char * format_name;
               XtPointer buffer;
               unsigned long length;
               unsigned long * num_bytes;
               long * private_id;

DESCRIPTION    [Toc]    [Back]

       XmClipboardRetrieve  retrieves  the current data item from
       clipboard storage.  It returns a warning if the  clipboard
       is locked; if there is no data on the clipboard; or if the
       data needs to be truncated because the  buffer  length  is
       too short.

       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 name of
       a format in which the data is  stored  on  the  clipboard.
       Specifies  the  buffer  to which the application wants the
       clipboard to copy the data.  Specifies the length  of  the
       application buffer.  Specifies the number of bytes of data
       copied into the application buffer.  Specifies the private
       data  stored  with  the  data item by the application that
       placed the data item on the clipboard. If the  application
       did  not store private data with the data item, this argument
 returns zero.

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.  The data
       returned is truncated because the user did not  provide  a
       buffer  large enough to hold the data.  The function could
       not find data on the clipboard corresponding to the format
       requested.  This  could  occur  because  the  clipboard is
       empty; there is data on  the  clipboard  but  not  in  the
       requested  format; or the data in the requested format was
       passed by name and is no longer available.

SEE ALSO    [Toc]    [Back]

       XmClipboardEndRetrieve(3X),  XmClipboardLock(3X),  XmClipboardStartCopy(3X),  XmClipboardStartRetrieve(3X), XmClipboardUnlock(3X)



                                          XmClipboardRetrieve(3X)