1pod::Prima::Clipboard(3U)ser Contributed Perl Documentatipoond::Prima::Clipboard(3)
2
6 Prima::Clipboard - GUI interprocess data exchange
7
9 Prima::Clipboard is an interface to system clipboards. Depending on the
10 OS, there can be only one clipboard (Win32), or three (X11). The class
11 is also used for data exchange in drag-and-drop interactions.
12
14 my $c = $::application-> Clipboard;
15 # paste data
17 my $string = $c-> text;
18 my $image = $c-> image;
19 my $other = $c-> fetch('Other type');
20 # copy datum
22 $c-> text( $string);
23 # copy data
25 $c-> open;
26 $c-> text( $string);
27 $c-> image( $image);
28 $c-> store( $image);
29 $c-> close;
30 # clear
32 $c-> clear;
33
35 Prima::Clipboard provides access to the system clipboard data storage.
36 For the easier communication, the system clipboard has one 'format'
37 field, that is stored along with the data. This field is used to
38 distinguish between data formats. Moreover, a clipboard can hold
39 simultaneously several data instances, of different data formats. Since
40 the primary usage of a clipboard is 'copying' and 'pasting', an
41 application can store copied information in several formats, increasing
42 possibility that the receiving application can recognize the data.
43 Different systems provide spectrum of predefined data types, but the
45 toolkit uses only three of these out of the box - ascii text, utf8
46 text, and image. It does not limit, however, the data format being one
47 of these three types - an application is free to register its own
48 formats. Both predefined and newly defined data formats are described
49 by a string, and the three predefined formats are represented by
50 'Text', 'UTF8', and 'Image' string constants.
51 The most frequent usage of Prima::Clipboard is to preform two tasks -
53 copying and pasting. Both can be exemplified by the following:
54 my $c = $::application-> Clipboard;
56 # paste
58 my $string = $c-> text;
59 # copy
61 $c-> text( $string);
62 Here is what happens under the hood:
64 First, the default clipboard is accessible by an implicit name call, as
66 an object named 'Clipboard'. This scheme makes it easily overridable.
67 A more important point is, that the default clipboard object might be
68 accompanied by other clipboard objects. This is the case with X11
69 environment, which defines also 'Primary' and 'Secondary' system
70 clipboards. Their functionality is identical to the default clipboard,
71 however. get_standard_clipboards() method returns strings for the
72 clipboards, provided by the system.
73 Second, code for fetching and/or storing multi-format data is somewhat
75 different. Clipboard is viewed as a shared system resource, and has to
76 be 'opened', before a process can grab it, so other processes can
77 access the clipboard data only after the clipboard is 'closed' ( note:
78 It is not so under X11, where there is no such thing as clipboard
79 locking, -- but the toolkit imposes this model for the consistency
80 sake).
81 fetch() and store() implicitly call open() and close(), but these
83 functions must be called explicitly for the multi-format data handling.
84 The code below illustrates the said:
85 # copy text and image
87 if ( $c-> open) {
88 $c-> clear;
89 $c-> store('Text', $string);
90 $c-> store('Image', $image);
91 $c-> close;
92 }
93 # check present formats and paste
95 if ( $c-> open) {
96 if ( $c-> format_exists('Text')) {
97 $string = $c-> fetch('Text');
98 }
99 # or, check the desired format alternatively
100 my %formats = map { $_ => 1 } $c-> get_formats;
101 if ( $formats{'Image'}) {
102 $image = $c-> fetch('Image');
103 }
104 $c-> close;
106 }
107 The clear() call in the copying code is necessary so the newly written
109 data will not mix with the old.
110 At last, the newly registered formats can be accessed by a program:
112 my $myformat = 'Very Special Old Pale Data Format';
114 if ( $c-> register_format($myformat)) {
115 $c-> open;
116 $c-> clear;
117 $c-> store('Text', 'sample text');
118 $c-> store($myformat', 'sample ## text');
119 $c-> close;
120 }
121 On-demand storage
123 Under X11 it is possible to skip the generation of data in all possible
124 clipboard format when when copying. The native X11 mechanism allows to
125 ask the source application for the exact data format needed by the
126 target application, and the toolkit uses special event "onClipboard"
127 triggered on the application whenever necessary.
128 By default this event handler responds to querying image in file
130 encoded formats (gif,jpg) under X11 on the fly. It can be extended to
131 generate other formats as well. See "Events" in Prima::Application
132 Clipboard for the details.
133 Custom formats
135 Once registered, all processes in a GUI space can access the data by
136 this format. The registration must take place also if a Prima-driven
137 program needs to read data in a format, defined by an another program.
138 In either case, the duplicate registration is a valid case. When no
139 longer needed, a format can be de-registered. It is not a mandatory
140 action, however - the toolkit cleans up before exit. Moreover, the
141 system maintains a reference counter on the custom-registered formats;
142 de-registering thus does not mean deletion. If two processes use a
143 custom format, and one exits and re-starts, the other still can access
144 the data in the same format, registered by its previous incarnation.
145 Unicode
147 Applications can interchange text in both ascii and utf8, leaving the
148 selection choice to reader programs. While it is possible to access
149 both at the same time, by "fetch"'ing content of "Text" and "UTF8"
150 clipboard slots, the widget proposes its own pasting scheme, where the
151 mechanics are hidden under the "text" property call. The property is
152 advised to be used instead of individual 'Text' and 'UTF8' formats.
153 This method is used in all the standard widgets, and is implemented so
154 the programmer can reprogram its default action by overloading
155 "PasteText" notification of "Prima::Application" ( see "PasteText" in
156 Prima::Application ).
157 The default action of "PasteText" is to query first if 'Text' format is
159 available, and if so, return the ascii text scalar. If
160 "Prima::Application::wantUnicodeInput" is set (default), 'UTF8' format
161 is checked before resorting to 'Text'. It is clear that this scheme is
162 not the only possibly needed, for example, an application may want to
163 ignore ASCII text, or, ignore UTF8 text but have
164 "Prima::Application::wantUnicodeInput" set, etc.
165 The symmetric action is "CopyText", that allows for a custom text
167 conversion code to be installed.
168 Images
170 Image data can be transferred in different formats in different OSes.
171 The lowest level is raw pixel data in display-based format, whereas
172 GTK-based applications can also exchange images in file-based formats,
173 such as bmp, png etc. To avoid further complications in the
174 implementations, "PasteImage" action was introduced to handle these
175 cases, together with a symmetrical "CopyImage".
176 The default action of "PasteImage" is to check whether lossless encoded
178 image data is present, and if so, load a new image from this data,
179 before falling back to OS-dependent image storage.
180 When storing the image on the clipboard, only the default format, raw
182 pixel data is used. Under X11 the toolkit can also serve images encoded
183 as file formats.
184 Note: Under X11 you'll need to keep the image alive during the whole
186 time it might get copied from the application - Prima doesn't keep a
187 copy of the image, only the reference. Changing the image after it was
188 stored in the clipboard will affect the clipboard content.
189 Exact and meta formats
191 Prima registers two special meta formats, "Image" and "Text", that
192 interoperate with the system clipboard, storing data in the format that
193 matches best with system convention when copying and pasting images and
194 text, correspondingly. It is recommended to use meta-format calls
195 (has_format, text, image, copy, paste) rather than exact format calls
196 (format_exists, store, fetch) when possible.
197 Where the exact format method operate on a single format data storage,
199 meta format calls may operate on several exact formats. F.ex. "text"
200 can check whether there exists a UTF-8 text storage, before resorting
201 to 8-bit text. "image" on X11 is even more complicated, and may use
202 image codecs to transfer encoded PNG streams, for example.
203
205 Properties
206 image OBJECT, [KEEP]
207 Provides access to an image, stored in the system clipboard. In
208 get-mode call return "undef" if no image is stored. In set-mode
209 clears the clipboard unless KEEP is set.
210 text STRING, [KEEP]
212 Provides access to the text stored in the system clipboard. In get-
213 mode call return "undef" if no text information is present. In
214 set-mode clears the clipboard unless KEEP is set.
215 Methods
217 clear
218 Deletes all data from clipboard.
219 close
221 Closes the open/close brackets. open() and close() can be called
222 recursively; only the last close() removes the actual clipboard
223 locking, so other processes can use it as well.
224 copy FORMAT, DATA, KEEP
226 Sets DATA in FORMAT. Clears the clipboard before unless KEEP is
227 set.
228 deregister_format FORMAT_STRING
230 De-registers a previously registered data format. Called
231 implicitly for all not de-registered format before a clipboard
232 object is destroyed.
233 fetch FORMAT_STRING
235 Returns the data of exact FORMAT_STRING data format, if present in
236 the clipboard. Depending on FORMAT_STRING, data is either text
237 string for 'Text' format, Prima::Image object for 'Image' format
238 and a binary scalar value for all custom formats.
239 format_exists FORMAT_STRING
241 Returns a boolean flag, showing whether FORMAT_STRING exact format
242 data is present in the clipboard or not.
243 has_format FORMAT_STRING
245 Returns a boolean flag, showing whether FORMAT_STRING meta format
246 data is present in the clipboard or not.
247 get_handle
249 Returns the system handle for the clipboard object.
250 get_formats INCLUDE_UNREGISTERED = 0
252 Returns an array of strings, where each is a format ID, reflecting
253 the formats present in the clipboard.
254 Only the predefined formats, and the formats registered via
256 register_format() are returned if "INCLUDE_UNREGISTERED" is unset.
257 If the flag is set, then all existing formats returned, however
258 their names are not necessarily are the same as registered with
259 Prima.
260 get_registered_formats
262 Returns an array of strings, each representing a registered format.
263 "Text" and "Image" are returned also.
264 get_standard_clipboards
266 Returns array of strings, each representing a system clipboard. The
267 default "Clipboard" is always present. Other clipboards are
268 optional. As an example, this function returns only "Clipboard"
269 under win32, but also "Primary" and "Secondary" under X11. The
270 code, specific to these clipboards must refer to this function
271 first.
272 is_dnd
274 Returns 1 if the clipboard is the special clipboard used as a proxy
275 for drag and drop interactions.
276 See also: "Widget/Drag and drop", "Application/get_dnd_clipboard".
278 open
280 Opens a system clipboard and locks it for the process single use;
281 returns a success flag. Subsequent "open" calls are possible, and
282 always return 1. Each open() must correspond to close(), otherwise
283 the clipboard will stay locked until the blocking process is
284 finished.
285 paste FORMAT_STRING
287 Returns data of meta format FORMAT_STRING if found in the
288 clipboard, or undef otherwise.
289 register_format FORMAT_STRING
291 Registers a data format under FORMAT_STRING string ID, returns a
292 success flag. If a format is already registered, 1 is returned.
293 All formats, registered via register_format() are de-registered
294 with deregister_format() when a program is finished.
295 store FORMAT_STRING, SCALAR
297 Stores SCALAR value into the clipboard in FORMAT_STRING exact data
298 format. Depending of FORMAT_STRING, SCALAR is treated as follows:
299 FORMAT_STRING SCALAR
301 ------------------------------------
302 Text text string in ASCII
303 UTF8 text string in UTF8
304 Image Prima::Image object
305 other formats binary scalar value
306 NB. All custom formats treated as a binary data. In case when the
308 data are transferred between hosts with different byte orders no
309 implicit conversions are made. It is up to the programmer whether
310 to convert the data in a portable format, or leave it as is. The
311 former option is of course preferable. As far as the author knows,
312 the Storable module from CPAN collection provides the system-
313 independent conversion routines.
314
316 Dmitry Karasik, <dmitry@karasik.eu.org>.
317
319 Prima, Prima::Component, Prima::Application
320perl v5.36.0 2023-03-20 pod::Prima::Clipboard(3)