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