XmClipboardStartRetrieve(3Xm) XmClipboardStartRetrieve(3Xm)
NAME
XmClipboardStartRetrieve - a clipboard function that
starts a copy from the clipboard.
AES SUPPORT LEVEL
full-use
SYNOPSIS
#include <Xm/Xm.h>
#include <Xm/CutPaste.h>
int XmClipboardStartRetrieve (display, window,
timestamp)
Display * display;
Window window;
Time timestamp;
DESCRIPTION
XmClipboardStartRetrieve tells the clipboard routines
that the application is ready to start copying an item
from the clipboard. The clipboard will be locked by
this routine, and will stay locked until
XmClipboardEndRetrieve is called. Between a call to
XmClipboardStartRetrieve and XmClipboardEndRetrieve,
multiple calls to XmClipboardRetrieve with the same
format name will 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. Applications do not need to use
XmClipboardStartRetrieve and XmClipboardEndRetrieve, in
which case XmClipboardRetrieve works as it did before.
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 obtained by
using XtWindow. The same application
- 1 -
XmClipboardStartRetrieve(3Xm) XmClipboardStartRetrieve(3Xm)
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.
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),
XmClipboardInquireFormat(3X),
XmClipboardInquireLength(3X),
XmClipboardInquirePendingItems(3X),
XmClipboardLock(3X), XmClipboardRetrieve(3X),
XmClipboardStartCopy(3X), and XmClipboardUnlock(3X).
- 2 -