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 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

SYNOPSIS

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

USAGE

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
46       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
54       The most frequent usage of Prima::Clipboard is to preform two tasks -
55       copying and pasting. Both can be exemplified by the following:
56
57          my $c = $::application-> Clipboard;
58
59          # paste
60          my $string = $c-> text;
61
62          # copy
63          $c-> text( $string);
64
65       This simplistic code hides other aspects of Prima::Clipboard class.
66
67       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
76       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
83       "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
87           # 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
95           # 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
106             $c-> close;
107          }
108
109       The clear() call in the copying code is necessary so the newly written
110       data will not mix with the old.
111
112       At last, the newly registered formats can be accessed by a program:
113
114          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
123   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
135   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
146       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
154       The symmetric action is "CopyText", that allows for a custom text
155       conversion code to be installed.
156
157   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
165       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
169       When storing the image on the clipboard, only the default format, raw
170       pixel data is used.
171
172   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
180       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

API

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
193       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
198   Methods
199       clear
200           Deletes all data from clipboard.
201
202       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
207       copy FORMAT, DATA, KEEP
208           Sets DATA in FORMAT. Clears the clipboard before unless KEEP is
209           set.
210
211       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
216       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
222       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
226       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
230       get_handle
231           Returns a system handle for a clipboard object.
232
233       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
237           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
243       get_registered_formats
244           Returns array of strings, each representing a registered format.
245           "Text" and "Image" are returned also.
246
247       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
255       is_dnd
256           Returns 1 if the clipboard is the special clipboard used as a proxy
257           for drag and drop interactions.
258
259           See also: "Widget/Drag and drop", "Application/get_dnd_clipboard".
260
261       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
268       paste FORMAT_STRING
269           Returns data of meta format FORMAT_STRING if found in the
270           clipboard, or undef otherwise.
271
272       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
278       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
282              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
289           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

AUTHOR

298       Dmitry Karasik, <dmitry@karasik.eu.org>.
299

SEE ALSO

301       Prima, Prima::Component, Prima::Application
302
303
304
305perl v5.34.0                      2021-07-22          pod::Prima::Clipboard(3)
Impressum