1XmClipboardStartCopy(library call)          XmClipboardStartCopy(library call)
2
3
4

NAME

6       XmClipboardStartCopy  — A clipboard function that sets up a storage and
7       data structure
8

SYNOPSIS

10       #include <Xm/CutPaste.h>
11       int XmClipboardStartCopy (display, window, clip_label,
12               timestamp, widget, callback, item_id)
13               Display * display;
14               Window  window;
15               XmString        clip_label;
16               Time    timestamp;
17               Widget  widget;
18               XmCutPasteProc  callback;
19               long    * item_id;
20       (void)
21

DESCRIPTION

23       XmClipboardStartCopy sets up storage and  data  structures  to  receive
24       clipboard  data.   An  application  calls this function during a cut or
25       copy operation.  The data  item  that  these  structures  receive  then
26       becomes the next data item in the clipboard.
27
28       Copying  a  large  piece of data to the clipboard can take a long time.
29       It is possible that, once the data is copied, no application will  ever
30       request  that  data.  The Motif Toolkit provides a mechanism so that an
31       application does not need to actually pass data to the clipboard  until
32       the data has been requested by some application.
33
34       Instead,  the  application  passes  format  and  length  information in
35       XmClipboardCopy to the clipboard functions, along with a widget ID  and
36       a callback function address that is passed in XmClipboardStartCopy. The
37       widget ID is necessary for communications between the  clipboard  func‐
38       tions in the application that owns the data and the clipboard functions
39       in the application that requests the data.
40
41       The callback functions are responsible for copying the actual  data  to
42       the  clipboard  through XmClipboardCopyByName. The callback function is
43       also called if the data item is removed  from  the  clipboard  and  the
44       actual data is no longer needed.
45
46       display   Specifies  a  pointer  to  the  Display  structure  that  was
47                 returned in a previous call to XOpenDisplay or XtDisplay.
48
49       window    Specifies the window ID of a widget that relates the applica‐
50                 tion  window  to the clipboard. The widget's window ID can be
51                 obtained through XtWindow.   The  same  application  instance
52                 should pass the same window ID to each of the clipboard func‐
53                 tions that it calls.
54
55       clip_label
56                 Specifies the label to be  associated  with  the  data  item.
57                 This  argument  is  used  to  identify the data item, as in a
58                 clipboard viewer.  An example of a label is the name  of  the
59                 application that places the data in the clipboard.
60
61       timestamp Specifies  the  time of the event that triggered the copy.  A
62                 valid timestamp must be supplied; it is not sufficient to use
63                 CurrentTime.
64
65       widget    Specifies  the  ID  of  the  widget  that  receives  messages
66                 requesting data previously passed by name. This argument must
67                 be present in order to pass data by name. Any valid widget ID
68                 in your application can be used for this purpose and all  the
69                 message  handling is taken care of by the cut and paste func‐
70                 tions.
71
72       callback  Specifies the address of the callback function that is called
73                 when  the  clipboard needs data that was originally passed by
74                 name. This is also the callback to receive the delete message
75                 for  items that were originally passed by name. This argument
76                 must be present in order to pass data by name.
77
78       item_id   Specifies the number assigned to this data item.  The  appli‐
79                 cation  uses this number in calls to XmClipboardCopy, XmClip‐
80                 boardEndCopy, and XmClipboardCancelCopy.
81
82       For more information on passing data by  name,  see  XmClipboardCopy(3)
83       and XmClipboardCopyByName(3).
84
85       The widget and callback arguments must be present in order to pass data
86       by name. The callback format is as follows:
87
88       void (*callback) (widget, data_id, private, reason)
89               Widget  widget;
90               long    *data_id;
91               long    *private;
92               int     *reason;
93       (void)
94
95       widget    Specifies the ID of the widget passed to this function.
96
97       data_id   Specifies the identifying number returned by XmClipboardCopy,
98                 which identifies the pass-by-name data.
99
100       private   Specifies the private information passed to XmClipboardCopy.
101
102       reason    Specifies    the    reason.   XmCR_CLIPBOARD_DATA_DELETE   or
103                 XmCR_CLIPBOARD_DATA_REQUEST are the possible values.
104

RETURN

106       XmClipboardSuccess
107                 The function was successful.
108
109       XmClipboardLocked
110                 The function failed  because  the  clipboard  was  locked  by
111                 another application. The application can continue to call the
112                 function again with the same parameters until the  lock  goes
113                 away.  This  gives  the application the opportunity to ask if
114                 the user wants to keep trying or to give up on the operation.
115
117       XmClipboardCancelCopy(3), XmClipboardCopy(3), XmClipboardCopyByName(3),
118       XmClipboardEndCopy(3),  XmClipboardEndRetrieve(3),  XmClipboardInquire‐
119       Count(3),   XmClipboardInquireFormat(3),   XmClipboardInquireLength(3),
120       XmClipboardInquirePendingItems(3),  XmClipboardLock(3), XmClipboardReg‐
121       isterFormat(3),  XmClipboardRetrieve(3),   XmClipboardStartRetrieve(3),
122       XmClipboardUndoCopy(3),  XmClipboardUnlock(3), and XmClipboardWithdraw‐
123       Format(3).
124
125
126
127                                            XmClipboardStartCopy(library call)
Impressum