XmClipboardStartCopy(3Xm) XmClipboardStartCopy(3Xm)
NAME
XmClipboardStartCopy - a clipboard function that sets
up a storage and data structure.
AES SUPPORT LEVEL
full-use
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.
- 1 -
XmClipboardStartCopy(3Xm) XmClipboardStartCopy(3Xm)
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(3X) and XmClipboardCopyByName(3X).
The widget and callback arguments must be present in
order to pass data by name. The callback format is as
- 2 -
XmClipboardStartCopy(3Xm) XmClipboardStartCopy(3Xm)
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
XmCR_CLIPBOARD_DATA_DELETE or
XmCR_CLIPBOARD_DATA_REQUEST.
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(3X), XmClipboardCopy(3X),
XmClipboardCopyByName(3X), XmClipboardEndCopy(3X),
XmClipboardEndRetrieve(3X),
XmClipboardInquireCount(3X),
XmClipboardInquireFormat(3X),
XmClipboardInquireLength(3X),
XmClipboardInquirePendingItems(3X),
XmClipboardLock(3X), XmClipboardRegisterFormat(3X),
XmClipboardRetrieve(3X), XmClipboardStartRetrieve(3X),
XmClipboardUndoCopy(3X), XmClipboardUnlock(3X), and
XmClipboardWithdrawFormat(3X).
- 3 -
XmClipboardStartCopy(3Xm) XmClipboardStartCopy(3Xm)
- 4 -