XmClipboardRetrieve(3X)

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

     SYNOPSIS
          #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;
          (void)

     VERSION
          This page documents Motif 2.1.

     DESCRIPTION
          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
          XmClipboardRetrievewith 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 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 effect 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.
          format_name
                    Specifies the name of a format in which the data
                    is stored on the clipboard.

          buffer    Specifies the buffer to which the application
                    wants the clipboard to copy the data.  The
                    function allocates space to hold the data returned
                    into the buffer.  The application is responsible
                    for managing this allocated space.  The
                    application can recover this allocated space by
                    calling XtFree.

          length    Specifies the length of the application buffer.

          num_bytes Specifies the number of bytes of data copied into
                    the application buffer.

          private_id
                    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 0 (zero).

     RETURN
          XmClipboardSuccess
                    The function was 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.

          XmClipboardTruncate
                    The data returned is truncated because the user
                    did not provide a buffer large enough to hold the
                    data.

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

     RELATED
          XmClipboardEndRetrieve(3), XmClipboardLock(3),
          XmClipboardStartCopy(3), XmClipboardStartRetrieve(3), and
          XmClipboardUnlock(3).