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

NAME

6       XmClipboardRetrieve  —  A clipboard function that retrieves a data item
7       from the clipboard
8

SYNOPSIS

10       #include <Xm/CutPaste.h>
11       int XmClipboardRetrieve (display, window, format_name,
12               buffer, length, num_bytes, private_id)
13               Display * display;
14               Window  window;
15               char    * format_name;
16               XtPointer       buffer;
17               unsigned long   length;
18               unsigned long   * num_bytes;
19               long    * private_id;
20       (void)
21

DESCRIPTION

23       XmClipboardRetrieve retrieves the  current  data  item  from  clipboard
24       storage.  It  returns a warning if the clipboard is locked, if there is
25       no data on the clipboard, or if the data needs to be truncated  because
26       the buffer length is too short.
27
28       Between a call to XmClipboardStartRetrieve and a call to XmClipboardEn‐
29       dRetrieve, multiple calls to XmClipboardRetrieve with the  same  format
30       name result in data being incrementally copied from the clipboard until
31       the data in that format has all been copied.
32
33       The return value XmClipboardTruncate from calls to  XmClipboardRetrieve
34       indicates  that more data remains to be copied in the given format.  It
35       is recommended that any calls to the Inquire functions that the  appli‐
36       cation  needs  to  make  to  effect the copy from the clipboard be made
37       between the call to XmClipboardStartRetrieve  and  the  first  call  to
38       XmClipboardRetrieve.  This  way,  the application does not need to call
39       XmClipboardLock and XmClipboardUnlock.
40
41       display   Specifies  a  pointer  to  the  Display  structure  that  was
42                 returned in a previous call to XOpenDisplay or XtDisplay.
43
44       window    Specifies the window ID of a widget that relates the applica‐
45                 tion window to the clipboard. The widget's window ID  can  be
46                 obtained  through  XtWindow.   The  same application instance
47                 should pass the same window ID to each of the clipboard func‐
48                 tions that it calls.
49
50       format_name
51                 Specifies the name of a format in which the data is stored on
52                 the clipboard.
53
54       buffer    Specifies the buffer to which the application wants the clip‐
55                 board to copy the data.  The function allocates space to hold
56                 the data  returned  into  the  buffer.   The  application  is
57                 responsible  for managing this allocated space.  The applica‐
58                 tion can recover this allocated space by calling XtFree.
59
60       length    Specifies the length of the application buffer.
61
62       num_bytes Specifies the number of bytes of data copied into the  appli‐
63                 cation buffer.
64
65       private_id
66                 Specifies  the  private data stored with the data item by the
67                 application that placed the data item on  the  clipboard.  If
68                 the  application  did  not  store  private data with the data
69                 item, this argument returns 0 (zero).
70

RETURN

72       XmClipboardSuccess
73                 The function was successful.
74
75       XmClipboardLocked
76                 The function failed  because  the  clipboard  was  locked  by
77                 another application. The application can continue to call the
78                 function again with the same parameters until the  lock  goes
79                 away.  This  gives  the application the opportunity to ask if
80                 the user wants to keep trying or to give up on the operation.
81
82       XmClipboardTruncate
83                 The data returned is truncated because the user did not  pro‐
84                 vide a buffer large enough to hold the data.
85
86       XmClipboardNoData
87                 The function could not find data on the clipboard correspond‐
88                 ing to the format requested. This  could  occur  because  the
89                 clipboard is empty; there is data on the clipboard but not in
90                 the requested format; or the data in the requested format was
91                 passed by name and is no longer available.
92
94       XmClipboardEndRetrieve(3), XmClipboardLock(3), XmClipboardStartCopy(3),
95       XmClipboardStartRetrieve(3), and XmClipboardUnlock(3).
96
97
98
99                                             XmClipboardRetrieve(library call)
Impressum