1pod::Prima::Clipboard(3U)ser Contributed Perl Documentatipoond::Prima::Clipboard(3)
2
6 Prima::Clipboard - GUI interprocess data exchange
7
9 Prima::Clipboard class is a descendant of Prima::Component. It serves
10 as an interface to the specific data storage, called clipboard, visible
11 to all clients of one GUI space. The system clipboard is intended for
12 the exchange of information of an arbitrary type between graphic
13 applications.
14
16 my $c = $::application-> Clipboard;
17 # paste data
19 my $string = $c-> text;
20 my $image = $c-> image;
21 my $other = $c-> fetch('Other type');
22 # copy datum
24 $c-> text( $string);
25 # copy data
27 $c-> open;
28 $c-> text( $string);
29 $c-> image( $image);
30 $c-> store( $image);
31 $c-> close;
32 # clear
34 $c-> clear;
35
37 Prima::Clipboard provides access to the system clipboard data storage.
38 For the easier communication, the system clipboard has one 'format'
39 field, that is stored along with the data. This field is used to
40 distinguish between data formats. Moreover, a clipboard can hold
41 simultaneously several data instances, of different data formats. Since
42 the primary usage of a clipboard is 'copying' and 'pasting', an
43 application can store copied information in several formats, increasing
44 possibility that the receiving application recognizes the data.
45 Different systems provide spectrum of predefined data types, but the
47 toolkit uses only three of these - ascii text, utf8 text, and image. It
48 does not limit, however, the data format being one of these three types
49 - an application is free to register its own formats. Both predefined
50 and newly defined data formats are described by a string, and the three
51 predefined formats are represented by 'Text', 'UTF8', and 'Image'
52 string constants.
53 The most frequent usage of Prima::Clipboard is to preform two tasks -
55 copying and pasting. Both can be exemplified by the following:
56 my $c = $::application-> Clipboard;
58 # paste
60 my $string = $c-> text;
61 # copy
63 $c-> text( $string);
64 This simplistic code hides other aspects of Prima::Clipboard class.
66 First, the default clipboard is accessible by an implicit name call, as
68 an object named 'Clipboard'. This scheme makes it easily overridable.
69 A more important point is, that the default clipboard object might be
70 accompanied by other clipboard objects. This is the case with X11
71 environment, which defines also 'Primary' and 'Secondary' system
72 clipboards. Their functionality is identical to the default clipboard,
73 however. "get_standard_clipboards()" method returns strings for the
74 clipboards, provided by the system.
75 Second, code for fetching and storing multi-format data is somewhat
77 different. Clipboard is viewed as a shared system resource, and have
78 to be 'opened', before a process can grab it, so other processes can
79 access the clipboard data only after the clipboard is 'closed' ( Note:
80 It is not so under X11, where there the clipboard locking is advisory,
81 and any process can grab clipboard at any time) .
82 "fetch()" and "store()" implicitly call "open()" and "close()", but
84 these functions must be called explicitly for the multi-format data
85 handling. The code below illustrates the said:
86 # copy text and image
88 if ( $c-> open) {
89 $c-> clear;
90 $c-> store('Text', $string);
91 $c-> store('Image', $image);
92 $c-> close;
93 }
94 # check present formats and paste
96 if ( $c-> open) {
97 if ( $c-> format_exists('Text')) {
98 $string = $c-> fetch('Text');
99 }
100 # or, check the desired format alternatively
101 my %formats = map { $_ => 1 } $c-> get_formats;
102 if ( $formats{'Image'}) {
103 $image = $c-> fetch('Image');
104 }
105 $c-> close;
107 }
108 The clear() call in the copying code is necessary so the newly written
110 data will not mix with the old.
111 At last, the newly registered formats can be accessed by a program:
113 my $myformat = 'Very Special Old Pale Data Format';
115 if ( $c-> register_format($myformat)) {
116 $c-> open;
117 $c-> clear;
118 $c-> store('Text', 'sample text');
119 $c-> store($myformat', 'sample ## text');
120 $c-> close;
121 }
122 Custom formats
124 Once registered, all processes in a GUI space can access the data by
125 this format. The registration must take place also if a Prima-driven
126 program needs to read data in a format, defined by an another program.
127 In either case, the duplicate registration is a valid event. When no
128 longer needed, a format can be de-registered. It is not a mandatory
129 action, however - the toolkit cleans up before exit. Moreover, the
130 system maintains a reference counter on the custom-registered formats;
131 de-registering does not mean deletion, thus. If two processes use a
132 custom format, and one exits and re-starts, it still can access the
133 data in the same format, registered by its previous incarnation.
134 Unicode
136 In real life, application often interchange text in both ascii and
137 utf8, leaving the choice to reader programs. While it is possible to
138 access both at the same time, by "fetch"'ing content of "Text" and
139 "UTF8" clipboard slots, widgets implement their own pasting scheme. To
140 avoid hacking widget code, usage of "text" property is advised instead
141 of indicating 'Text' and 'UTF8' constants. This method is used in
142 standard widgets, and is implemented so the programmer can reprogram
143 its default action by overloading "PasteText" notification of
144 "Prima::Application" ( see "PasteText" in Prima::Application ).
145 The default action of "PasteText" is to query first if 'Text' format is
147 available, and if so, return the ascii text scalar. If
148 "Prima::Application::wantUnicodeInput" is set, 'UTF8' format is checked
149 before resorting to 'Text'. It is clear that this scheme is not the
150 only possibly needed, for example, an application may want to ignore
151 ASCII text, or, ignore UTF8 text but have
152 "Prima::Application::wantUnicodeInput" set, etc.
153 The symmetric action is "CopyText", that allows for a custom text
155 conversion code to be installed.
156 Images
158 Image data can be transferred in different formats in different OSes.
159 The lowest level is raw pixel data in display-based format, whereas
160 GTK-based applications can also exchange images in file-based formats,
161 such as bmp, png etc. To avoid further complications in the
162 implementations, "PasteImage" action was introduced to handle these
163 cases, together with a symmetrical "CopyImage".
164 The default action of "PasteImage" is to check whether lossless encoded
166 image data is present, and if so, load a new image from this data,
167 before falling back to OS-dependent image storage.
168 When storing the image on the clipboard, only the default format, raw
170 pixel data is used.
171 Exact and meta formats
173 Prima registers two special meta formats, "Image" and "Text", that
174 interoperate with the system clipboard, storing data in the format that
175 matches best with system convention when copying and pasting images and
176 text, correspondinly. It is recommended to use meta-format calls
177 (has_format, text, image, copy, paste) rather than exact format calls
178 (format_exists, store, fetch) when possible.
179 Where the exact format method operate on a single format data storage,
181 meta format calls may operate on several exact formats. F.ex. "text"
182 can check whether there exists a UTF-8 text storage, before resorting
183 to 8-bit text. "image" on X11 is even more complicated, and may use
184 image codecs to transfer encoded PNG streams, for example.
185
187 Properties
188 image OBJECT, [KEEP]
189 Provides access to an image, stored in the system clipboard. In
190 get-mode call, return "undef" if no image is stored. In set-mode
191 clears the clipboard unless KEEP is set.
192 text STRING, [KEEP]
194 Provides access to text stored in the system clipboard. In get-
195 mode call, return "undef" if no text information is present. In
196 set-mode clears the clipboard unless KEEP is set.
197 Methods
199 clear
200 Deletes all data from clipboard.
201 close
203 Closes the open/close brackets. open() and close() can be called
204 recursively; only the last close() removes the actual clipboard
205 locking, so other processes can use it as well.
206 copy FORMAT, DATA, KEEP
208 Sets DATA in FORMAT. Clears the clipboard before unless KEEP is
209 set.
210 deregister_format FORMAT_STRING
212 De-registers a previously registered data format. Called
213 implicitly for all not de-registered format before a clipboard
214 object is destroyed.
215 fetch FORMAT_STRING
217 Returns the data of exact FORMAT_STRING data format, if present in
218 the clipboard. Depending on FORMAT_STRING, data is either text
219 string for 'Text' format, Prima::Image object for 'Image' format
220 and a binary scalar value for all custom formats.
221 format_exists FORMAT_STRING
223 Returns a boolean flag, showing whether FORMAT_STRING exact format
224 data is present in the clipboard or not.
225 has_format FORMAT_STRING
227 Returns a boolean flag, showing whether FORMAT_STRING meta format
228 data is present in the clipboard or not.
229 get_handle
231 Returns a system handle for a clipboard object.
232 get_formats INCLUDE_UNREGISTERED = 0
234 Returns array of strings, where each is a format ID, reflecting the
235 formats present in the clipboard.
236 Only the predefined formats, and the formats registered via
238 "register_format()" are returned if "INCLUDE_UNREGISTERED" is
239 unset. If the flag is set, then all existing formats returned,
240 however their names are not necessarily are the same as registered
241 with Prima.
242 get_registered_formats
244 Returns array of strings, each representing a registered format.
245 "Text" and "Image" are returned also.
246 get_standard_clipboards
248 Returns array of strings, each representing a system clipboard. The
249 default "Clipboard" is always present. Other clipboards are
250 optional. As an example, this function returns only "Clipboard"
251 under win32, but also "Primary" and "Secondary" under X11. The
252 code, specific to these clipboards must refer to this function
253 first.
254 is_dnd
256 Returns 1 if the clipboard is the special clipboard used as a proxy
257 for drag and drop interactions.
258 See also: "Widget/Drag and drop", "Application/get_dnd_clipboard".
260 open
262 Opens a system clipboard and locks it for the process single use;
263 returns a success flag. Subsequent "open" calls are possible, and
264 always return 1. Each "open()" must correspond to "close()",
265 otherwise the clipboard will stay locked until the blocking process
266 is finished.
267 paste FORMAT_STRING
269 Returns data of meta format FORMAT_STRING if found in the
270 clipboard, or undef otherwise.
271 register_format FORMAT_STRING
273 Registers a data format under FORMAT_STRING string ID, returns a
274 success flag. If a format is already registered, 1 is returned. All
275 formats, registered via "register_format()" are de-registered with
276 "deregister_format()" when a program is finished.
277 store FORMAT_STRING, SCALAR
279 Stores SCALAR value into the clipboard in FORMAT_STRING exact data
280 format. Depending of FORMAT_STRING, SCALAR is treated as follows:
281 FORMAT_STRING SCALAR
283 ------------------------------------
284 Text text string in ASCII
285 UTF8 text string in UTF8
286 Image Prima::Image object
287 other formats binary scalar value
288 NB. All custom formats treated as a binary data. In case when the
290 data are transferred between hosts with different byte orders no
291 implicit conversions are made. It is up to the programmer whether
292 to convert the data in a portable format, or leave it as is. The
293 former option is of course preferable. As far as the author knows,
294 the Storable module from CPAN collection provides the system-
295 independent conversion routines.
296
298 Dmitry Karasik, <dmitry@karasik.eu.org>.
299
301 Prima, Prima::Component, Prima::Application
302perl v5.32.1 2021-01-27 pod::Prima::Clipboard(3)