XmClipboard(3)

1XmClipboard(3)                  LessTif Manuals                 XmClipboard(3)
2
3
4

NAME

6       XmClipboard - Motif-compatible clipboard widget
7

SYNOPSIS

9       #include <Xm/CutPaste.h>
10

DESCRIPTION

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
16       The APIs described in this document are to be used by application writ‐
17       ers, but the LessTif widgets use them internally as well when the  user
18       performs  an  action  commanding  the widget to interact with the clip‐
19       board.
20
21       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

CONVENIENCE FUNCTIONS

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
32       int  XmClipboardBeginCopy(Display  *display,  Window  window,  XmString
33       clip_label, Widget widget, VoidProc callback, long *item_id)
34
35       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
40       int  XmClipboardCancelCopy(Display  *display,   Window   window,   long
41       item_id)
42
43       Just what the name says : cancel a pending copy operation.
44
45       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
49       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
54       int  XmClipboardCopyByName(Display  *display,   Window   window,   long
55       data_id, XtPointer buffer, unsigned long length, long private_id)
56
57       int XmClipboardEndCopy(Display *display, Window window, long item_id)
58
59       See description of XmClipboardBeginCopy and XmClipboardCopy.
60
61       int XmClipboardEndRetrieve(Display *display, Window window)
62
63       Ends  a cycle of retrieval calls, started with a call to XmClipboardBe‐
64       ginRetrieve, and with calls of XmClipboardRetrieve in the middle.
65
66       int  XmClipboardInquireCount(Display  *display,  Window   window,   int
67       *count, unsigned long *max_length)
68
69       int   XmClipboardInquireFormat(Display  *display,  Window  window,  int
70       index, XtPointer format_name_buf, unsigned  long  buffer_len,  unsigned
71       long *copied_len)
72
73       int  XmClipboardInquireLength(Display  *display,  Window  window,  char
74       *format_name, unsigned long *length)
75
76       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
81       int  XmClipboardInquirePendingItems(Display  *display,  Window  window,
82       char *format_name,  XmClipboardPendingList  *item_list,  unsigned  long
83       *count)
84
85       int XmClipboardLock(Display *display, Window window)
86
87       int  XmClipboardRegisterFormat(Display *display, char *format_name, int
88       format_length)
89
90       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
94       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
98       This function can return ClipboardLocked.
99
100       int  XmClipboardStartCopy(Display  *display,  Window  window,  XmString
101       clip_label,  Time  timestamp,  Widget  widget, XmCutPasteProc callback,
102       long *item_id)
103
104       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
112       This function can return ClipboardLocked.
113
114       int  XmClipboardStartRetrieve(Display  *display,  Window  window,  Time
115       timestamp)
116
117       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
123       This function can return ClipboardLocked.
124
125       int XmClipboardUndoCopy(Display *display, Window window)
126
127       int   XmClipboardUnlock(Display   *display,   Window   window,  Boolean
128       remove_all_locks)
129
130       int  XmClipboardWithdrawFormat(Display  *display,  Window  window,  int
131       data_id)
132

CALLBACKS

134       The  callback  functions  triggered by XmClipboardStartCopy should have
135       the following signature :
136
137       void CallbackFunction(Widget w, int *data_id, int *private,  int  *rea‐
138       son)
139
140       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

RETURN VALUES

146       All of the functions described in this page can  return  the  following
147       codes :
148
149       ClipboardSuccess the call ended successfully
150
151       ClipboardFail  failure  for  various reasons - see the explanation with
152       the function
153
154       ClipboardLocked some other application has locked the clipboard already
155
156       ClipboardNoData it's empty or the format wasn't found
157
158       ClipboardTruncate the data was truncated because  the  buffer  was  too
159       small
160
161       ClipboardBadFormat  the  format name was NULL or the format didn't have
162       length 8, 16, or 32
163

NAME

SYNOPSIS

DESCRIPTION

CONVENIENCE FUNCTIONS

CALLBACKS

RETURN VALUES

SEE ALSO