XmClipboardStartCopy(Xm) UNIX System V
NAME
XmClipboardStartCopy - a clipboard function that sets up a
storage and data structure.
SYNOPSIS
#include <Xm/Xm.h>
#include <Xm/CutPaste.h>
int XmClipboardStartCopy (display, window, clip_label,
timestamp, widget, callback, item_id)
Display * display;
Window window;
XmString clip_label;
Time timestamp;
Widget widget;
VoidProc callback;
long * item_id;
DESCRIPTION
XmClipboardStartCopy sets up storage and data structures to
receive clipboard data. An application calls this function
during a cut or copy operation. The data item that these
structures receive then becomes the next data item in the
clipboard.
Copying a large piece of data to the clipboard can take
time. It is possible that, once copied, no application will
ever request that data. The Motif Toolkit provides a
mechanism so that an application does not need to actually
pass data to the clipboard until the data has been requested
by some application.
Instead, the application passes format and length
information in XmClipboardCopy to the clipboard functions,
along with a widget ID and a callback function address that
is passed in XmClipboardStartCopy. The widget ID is needed
for communications between the clipboard functions in the
application that owns the data and the clipboard functions
in the application that requests the data.
The callback functions are responsible for copying the
actual data to the clipboard via XmClipboardCopyByName. The
callback function is also called if the data item is removed
from the clipboard, and the actual data is therefore no
longer needed.
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 instance should
pass the same window ID to each of the clipboard
functions that it calls.
clip_label Specifies the label to be associated with the
data item. This argument is used to identify
the data item, for example, in a clipboard
viewer. An example of a label is the name of
the application that places the data in the
clipboard.
timestamp Specifies the time of the event that triggered
the copy.
widget Specifies the ID of the widget that will receive
messages requesting data previously passed by
name. This argument must be present in order to
pass data by name. Any valid widget ID in your
application can be used for this purpose and all
the message handling is taken care of by the cut
and paste functions.
callback Specifies the address of the callback function
that is called when the clipboard needs data
that was originally passed by name. This is
also the callback to receive the delete message
for items that were originally passed by name.
This argument must be present in order to pass
data by name.
item_id Specifies the number assigned to this data item.
The application uses this number in calls to
XmClipboardCopy, XmClipboardEndCopy, and
XmClipboardCancelCopy.
For more information on passing data by name, see
XmClipboardCopy(Xm) and XmClipboardCopyByName(Xm).
The widget and callback arguments must be present in order
to pass data by name. The callback format is as follows:
function name
Widget widget;
int * data_id;
int * private;
int * reason;
widget Specifies the ID of the widget passed to this
function.
data_id Specifies the identifying number returned by
XmClipboardCopy, which identifies the pass-by-
name data.
private Specifies the private information passed to
XmClipboardCopy.
reason Specifies the reason, which is either
XmCRCLIPBOARDDATADELETE or
XmCRCLIPBOARDDATAREQUEST.
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
XmClipboardCancelCopy(Xm), XmClipboardCopy(Xm),
XmClipboardCopyByName(Xm), XmClipboardEndCopy(Xm),
XmClipboardEndRetrieve(Xm), XmClipboardInquireCount(Xm),
XmClipboardInquireFormat(Xm), XmClipboardInquireLength(Xm),
XmClipboardInquirePendingItems(Xm), XmClipboardLock(Xm),
XmClipboardRegisterFormat(Xm), XmClipboardRetrieve(Xm),
XmClipboardStartRetrieve(Xm), XmClipboardUndoCopy(Xm),
XmClipboardUnlock(Xm), and XmClipboardWithdrawFormat(Xm).
(printed 2/14/90) XmClipboardStartCopy(Xm)