1XmClipboard(3) LessTif Manuals XmClipboard(3)
2
6 XmClipboard
7
9 #include <Xm/CutPaste.h>
10
12 The clipboard is represented by a number of convenience functions which
13 allow a widget or an application to exchange information with other
14 widgets or applications.
15 The API's described in this document are to be used by application
17 writers, but the LessTif widgets use them internally as well when the
18 user performs an action commanding the widget to interact with the
19 clipboard.
20 Examples of the use of these functions can be found in the implementa‐
22 tion of the XmTextField(3) widget, in lib/Xm/TextF.c under the root of
23 the LessTif source directory. Specifically, the functions XmTextField‐
24 Copy and XmTextFieldPaste have been implemented using the functions
25 described below.
26
28 The functions are listed alphabetically below. Do note however that
29 XmClipboardStartCopy is to be called before any of the other functions
30 described in this document.
31 int XmClipboardBeginCopy(Display *display, Window window, XmString
33 clip_label, Widget widget, VoidProc callback, long *item_id)
34 This appears to be the same as XmClipboardStartCopy. This function
36 should be called first, then XmClipboardCopy may be called, potentially
37 multiple times; the sequence must be ended with a call of XmClipboard‐
38 EndCopy.
39 int XmClipboardCancelCopy(Display *display, Window window, long
41 item_id)
42 Just what the name says : cancel a pending copy operation.
44 int XmClipboardCopy(Display *display, Window window, long item_id, char
46 *format_name, XtPointer buffer, unsigned long length, long private_id,
47 long *data_id)
48 This function allows you to try to copy the buffer that needs to be
50 transferred to the clipboard. Item_id should be the same as in the
51 call to XmClipboardBeginCopy. Private_id is a number that you can
52 pass.
53 int XmClipboardCopyByName(Display *display, Window window, long
55 data_id, XtPointer buffer, unsigned long length, long private_id)
56 int XmClipboardEndCopy(Display *display, Window window, long item_id)
58 See description of XmClipboardBeginCopy and XmClipboardCopy.
60 int XmClipboardEndRetrieve(Display *display, Window window)
62 Ends a cycle of retrieval calls, started with a call to XmClipboardBe‐
64 ginRetrieve, and with calls of XmClipboardRetrieve in the middle.
65 int XmClipboardInquireCount(Display *display, Window window, int
67 *count, unsigned long *max_length)
68 int XmClipboardInquireFormat(Display *display, Window window, int
70 index, XtPointer format_name_buf, unsigned long buffer_len, unsigned
71 long *copied_len)
72 int XmClipboardInquireLength(Display *display, Window window, char
74 *format_name, unsigned long *length)
75 You can call this function just beforeXmClipboardRetrieve to figure out
77 how much data is waiting. This way you can allocate storage dynami‐
78 cally. An example of the use of this function is in the LessTif
79 sources in the file lib/Xm/TextF.c, in function XmTextFieldPaste.
80 int XmClipboardInquirePendingItems(Display *display, Window window,
82 char *format_name, XmClipboardPendingList *item_list, unsigned long
83 *count)
84 int XmClipboardLock(Display *display, Window window)
86 int XmClipboardRegisterFormat(Display *display, char *format_name, int
88 format_length)
89 int XmClipboardRetrieve(Display *display, Window window, char *for‐
91 mat_name, XtPointer buffer, unsigned long length, unsigned long
92 *num_bytes, long *private_id)
93 Copy a chunk of the clipboard's data into application memory. Length
95 indicates the buffer's size. Private_id returns private data associ‐
96 ated with the data item (this is just a number).
97 This function can return ClipboardLocked.
99 int XmClipboardStartCopy(Display *display, Window window, XmString
101 clip_label, Time timestamp, Widget widget, XmCutPasteProc callback,
102 long *item_id)
103 This function creates temporary storage that will receive clipboard
105 data. It must be called before any other XmClipboard operation. Win‐
106 dow identifies the widget's window; it should be passed to all clip‐
107 board routines in the same application. Clip_label identifies the data
108 item by name. Widget is the widget ID receiving callbacks mentioned in
109 callback. Item_id returns a number to be used by the other clipboard
110 copy functions to refer to this particular object.
111 This function can return ClipboardLocked.
113 int XmClipboardStartRetrieve(Display *display, Window window, Time
115 timestamp)
116 This function indicates the start of incremental retrieval of data from
118 the clipboard. Increments can be copied now with XmClipboardRetrieve,
119 while XmClipboardEndRetrieve should be called to finish copying the
120 contents of the clipboard. These functions should be called with iden‐
121 tical format_name arguments.
122 This function can return ClipboardLocked.
124 int XmClipboardUndoCopy(Display *display, Window window)
126 int XmClipboardUnlock(Display *display, Window window, Boolean
128 remove_all_locks)
129 int XmClipboardWithdrawFormat(Display *display, Window window, int
131 data_id)
132
134 The callback functions triggered by XmClipboardStartCopy should have
135 the following signature :
136 void CallbackFunction(Widget w, int *data_id, int *private, int *rea‐
138 son)
139 The data_id points to the data passed by name. The private pointer
141 points to data passed from XmClipboardCopy. The reason field can
142 either return XmCR_CLIPBOARD_DATA_DELETE or XmCR_CLIP‐
143 BOARD_DATA_REQUEST.
144
146 All of the functions described in this page can return the following
147 codes :
148 ClipboardSuccess the call ended successfully
150 ClipboardFail failure for various reasons - see the explanation with
152 the function
153 ClipboardLocked some other application has locked the clipboard already
155 ClipboardNoData it's empty or the format wasn't found
157 ClipboardTruncate the data was truncated because the buffer was too
159 small
160 ClipboardBadFormat the format name was NULL or the format didn't have
162 length 8, 16, or 32
163
165LessTif Project May 1998 XmClipboard(3)