NAME    [Toc]    [Back]

       XmClipboardStartCopy - A clipboard function that sets up a
       storage and data structure

SYNOPSIS    [Toc]    [Back]

       #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;
               XmCutPasteProc callback;
               long * item_id;

DESCRIPTION    [Toc]    [Back]

       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 a
       long 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.  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  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.
       Specifies the time of the event that triggered the copy. A
       valid timestamp must be supplied; it is not sufficient  to
       use  CurrentTime.   Specifies  the  ID  of the widget that
       receives 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.   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.
       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 follows:

       void (*callback) (widget, data_id, private, reason)
               Widget widget;
               long *data_id;
               long *private;
               int *reason;

       Specifies the ID of the widget passed  to  this  function.
       Specifies  the identifying number returned by XmClipboardCopy,
 which identifies the pass-by-name  data.   Specifies
       the private information passed to XmClipboardCopy.  Specifies
   the   reason,   which    is    either    XmCR_CLIPBOARD_DATA_DELETE
 or XmCR_CLIPBOARD_DATA_REQUEST.

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.

SEE ALSO    [Toc]    [Back]

       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), XmClipboardWithdrawFormat(3X)



                                         XmClipboardStartCopy(3X)