1pod::Prima::Clipboard(3U)ser Contributed Perl Documentatipoond::Prima::Clipboard(3)
2
3
4

NAME

6       Prima::Clipboard - GUI interprocess data exchange
7

DESCRIPTION

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

SYNOPSIS

14          my $c = $::application-> Clipboard;
15
16          # paste data
17          my $string = $c-> text;
18          my $image  = $c-> image;
19          my $other  = $c-> fetch('Other type');
20
21          # copy datum
22          $c-> text( $string);
23
24          # copy data
25          $c-> open;
26          $c-> text( $string);
27          $c-> image( $image);
28          $c-> store( $image);
29          $c-> close;
30
31          # clear
32          $c-> clear;
33

USAGE

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
44       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
52       The most frequent usage of Prima::Clipboard is to preform two tasks -
53       copying and pasting. Both can be exemplified by the following:
54
55          my $c = $::application-> Clipboard;
56
57          # paste
58          my $string = $c-> text;
59
60          # copy
61          $c-> text( $string);
62
63       Here is what happens under the hood:
64
65       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
74       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 cosistency
80       sake).
81
82       "fetch()" and "store()" implicitly call "open()" and "close()", but
83       these functions must be called explicitly for the multi-format data
84       handling. The code below illustrates the said:
85
86           # 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
94           # 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
105             $c-> close;
106          }
107
108       The clear() call in the copying code is necessary so the newly written
109       data will not mix with the old.
110
111       At last, the newly registered formats can be accessed by a program:
112
113          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
122   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
129       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
134   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
146   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 wiget 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
158       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
166       The symmetric action is "CopyText", that allows for a custom text
167       conversion code to be installed.
168
169   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
177       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
181       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
185   Exact and meta formats
186       Prima registers two special meta formats, "Image" and "Text", that
187       interoperate with the system clipboard, storing data in the format that
188       matches best with system convention when copying and pasting images and
189       text, correspondinly. It is recommended to use meta-format calls
190       (has_format, text, image, copy, paste) rather than exact format calls
191       (format_exists, store, fetch) when possible.
192
193       Where the exact format method operate on a single format data storage,
194       meta format calls may operate on several exact formats. F.ex. "text"
195       can check whether there exists a UTF-8 text storage, before resorting
196       to 8-bit text.  "image" on X11 is even more complicated, and may use
197       image codecs to transfer encoded PNG streams, for example.
198

API

200   Properties
201       image OBJECT, [KEEP]
202           Provides access to an image, stored in the system clipboard. In
203           get-mode call return "undef" if no image is stored.  In set-mode
204           clears the clipboard unless KEEP is set.
205
206       text STRING, [KEEP]
207           Provides access to the text stored in the system clipboard. In get-
208           mode call return "undef" if no text information is present.  In
209           set-mode clears the clipboard unless KEEP is set.
210
211   Methods
212       clear
213           Deletes all data from clipboard.
214
215       close
216           Closes the open/close brackets. open() and close() can be called
217           recursively; only the last close() removes the actual clipboard
218           locking, so other processes can use it as well.
219
220       copy FORMAT, DATA, KEEP
221           Sets DATA in FORMAT. Clears the clipboard before unless KEEP is
222           set.
223
224       deregister_format FORMAT_STRING
225           De-registers a previously registered data format.  Called
226           implicitly for all not de-registered format before a clipboard
227           object is destroyed.
228
229       fetch FORMAT_STRING
230           Returns the data of exact FORMAT_STRING data format, if present in
231           the clipboard.  Depending on FORMAT_STRING, data is either text
232           string for 'Text' format, Prima::Image object for 'Image' format
233           and a binary scalar value for all custom formats.
234
235       format_exists FORMAT_STRING
236           Returns a boolean flag, showing whether FORMAT_STRING exact format
237           data is present in the clipboard or not.
238
239       has_format FORMAT_STRING
240           Returns a boolean flag, showing whether FORMAT_STRING meta format
241           data is present in the clipboard or not.
242
243       get_handle
244           Returns the system handle for the clipboard object.
245
246       get_formats INCLUDE_UNREGISTERED = 0
247           Returns an array of strings, where each is a format ID, reflecting
248           the formats present in the clipboard.
249
250           Only the predefined formats, and the formats registered via
251           "register_format()" are returned if "INCLUDE_UNREGISTERED" is
252           unset.  If the flag is set, then all existing formats returned,
253           however their names are not necessarily are the same as registered
254           with Prima.
255
256       get_registered_formats
257           Returns an array of strings, each representing a registered format.
258           "Text" and "Image" are returned also.
259
260       get_standard_clipboards
261           Returns array of strings, each representing a system clipboard. The
262           default "Clipboard" is always present. Other clipboards are
263           optional. As an example, this function returns only "Clipboard"
264           under win32, but also "Primary" and "Secondary" under X11. The
265           code, specific to these clipboards must refer to this function
266           first.
267
268       is_dnd
269           Returns 1 if the clipboard is the special clipboard used as a proxy
270           for drag and drop interactions.
271
272           See also: "Widget/Drag and drop", "Application/get_dnd_clipboard".
273
274       open
275           Opens a system clipboard and locks it for the process single use;
276           returns a success flag. Subsequent "open" calls are possible, and
277           always return 1. Each "open()" must correspond to "close()",
278           otherwise the clipboard will stay locked until the blocking process
279           is finished.
280
281       paste FORMAT_STRING
282           Returns data of meta format FORMAT_STRING if found in the
283           clipboard, or undef otherwise.
284
285       register_format FORMAT_STRING
286           Registers a data format under FORMAT_STRING string ID, returns a
287           success flag.  If a format is already registered, 1 is returned.
288           All formats, registered via "register_format()" are de-registered
289           with "deregister_format()" when a program is finished.
290
291       store FORMAT_STRING, SCALAR
292           Stores SCALAR value into the clipboard in FORMAT_STRING exact data
293           format.  Depending of FORMAT_STRING, SCALAR is treated as follows:
294
295              FORMAT_STRING     SCALAR
296              ------------------------------------
297              Text              text string in ASCII
298              UTF8              text string in UTF8
299              Image             Prima::Image object
300              other formats     binary scalar value
301
302           NB. All custom formats treated as a binary data. In case when the
303           data are transferred between hosts with different byte orders no
304           implicit conversions are made. It is up to the programmer whether
305           to convert the data in a portable format, or leave it as is. The
306           former option is of course preferable. As far as the author knows,
307           the Storable module from CPAN collection provides the system-
308           independent conversion routines.
309

AUTHOR

311       Dmitry Karasik, <dmitry@karasik.eu.org>.
312

SEE ALSO

314       Prima, Prima::Component, Prima::Application
315
316
317
318perl v5.34.1                      2022-04-20          pod::Prima::Clipboard(3)
Impressum