pod::Pr...lipboard(3)

okay bestie, this is pod::Pr...lipboard(3) from the User Contributed Perl Documentation — and it's literally the manual page for Prima::Clipboard, aka GUI interprocess data exchange 💅✨

🌸 NAME 🌸

Prima::Clipboard — GUI interprocess data exchange 👑

✨ DESCRIPTION ✨

Prima::Clipboard is an interface to system clipboards. Depending on the OS, there can be only one clipboard (Win32), or three (X11). The class is also used for data exchange in drag-and-drop interactions. No cap 🫶

🦋 SYNOPSIS 🦋

Here's the whole vibe in code:

   my $c = $::application-> Clipboard;

   # paste data
   my $string = $c-> text;
   my $image  = $c-> image;
   my $other  = $c-> fetch('Other type');

   # copy datum
   $c-> text( $string);

   # copy data
   $c-> open;
   $c-> text( $string);
   $c-> image( $image);
   $c-> store( $image);
   $c-> close;

   # clear
   $c-> clear;

💅 USAGE 💅

Prima::Clipboard provides access to the system clipboard data storage. For easier communication, the system clipboard has one 'format' field, which is stored along with the data. This field is used to distinguish between data formats. Moreover, a clipboard can hold simultaneously several data instances, of different data formats. Since the primary usage of a clipboard is 'copying' and 'pasting', an application can store copied information in several formats, increasing the possibility that the receiving application can recognize the data. Slay 💖

Different systems provide a spectrum of predefined data types, but the toolkit uses only three of these out of the box — ascii text, utf8 text, and image. It does not limit, however, the data format being one of these three types — an application is free to register its own formats. Both predefined and newly defined data formats are described by a string, while the three predefined formats are represented by the 'Text', 'UTF8', and 'Image' string constants.

The most frequent usage of Prima::Clipboard is to perform two tasks — copying and pasting. Both can be exemplified by the following:

          my $c = $::application-> Clipboard;

          # paste
          my $string = $c-> text;

          # copy
          $c-> text( $string);

Here is what happens under the hood:

First, the default clipboard is accessible by an implicit name call, as an object named 'Clipboard'. This scheme makes it easily overridable. A more important point is that the default clipboard object might be accompanied by other clipboard objects. This is the case with the X11 environment, which defines also 'Primary' and 'Secondary' system clipboards. Their functionality is identical to the default clipboard, however. get_standard_clipboards() method returns strings for the clipboards, provided by the system.

Second, the code for fetching and/or storing multi-format data is somewhat different. Clipboard is viewed as a shared system resource and has to be 'opened' before a process can grab it, so other processes can access the clipboard data only after the clipboard is 'closed'.

( note: It is not so under X11, where there is no such thing as clipboard locking, -- but the toolkit imposes this model for the consistency sake) 🫶

fetch() and store() implicitly call open() and close(), but these functions must be called explicitly for the multi-format data handling. The code below illustrates the following:

           # copy text and image
           if ( $c-> open) {
              $c-> clear;
              $c-> store('Text', $string);
              $c-> store('Image', $image);
              $c-> close;
           }

           # check present formats and paste
           if ( $c-> open) {
             if ( $c-> format_exists('Text')) {
                $string = $c-> fetch('Text');
             }
             # or, check the desired format alternatively
             my %formats = map { $_ => 1 } $c-> get_formats;
             if ( $formats{'Image'}) {
                $image = $c-> fetch('Image');
             }

             $c-> close;
          }

The clear() call in the copying code is necessary so the newly written data will not mix with the old.

At last, the newly registered formats can be accessed by the following example code:

          my $myformat = 'Very Special Old Pale Data Format';
          if ( $c-> register_format($myformat)) {
             $c-> open;
             $c-> clear;
             $c-> store('Text', 'sample text');
             $c-> store($myformat', 'sample ## text');
             $c-> close;
          }

🎀 On-demand storage 🎀

Under X11 it is possible to skip the generation of data in all possible clipboard formats when copying the data. The native X11 mechanism allows to ask the source application for the exact data format needed by the target application, and the toolkit uses the special notification "onClipboard" triggered on the application whenever necessary.

By default, this event handler responds to querying images in file-encoded formats (gif,jpg) under X11 on the fly. It can be extended to generate other formats as well. See "Events" in Prima::Application Clipboard for the details.

🌈 Custom formats 🌈

Once registered, all processes in the GUI space can access the data in this format. The registration must take place also if a Prima-driven program needs to read data in a format, defined by another program. In either case, the duplicate registration is a valid case. When no longer needed, the format can be de-registered. It is not a mandatory action, however — the toolkit de-registers these formats before exiting. Moreover, the system maintains a reference counter on the custom-registered formats; de-registering thus does not mean deletion. If two processes use a custom format, and one exits and re-starts, the other still can access the data in the same format, registered by its previous incarnation. Iconic 🎀

🧚 Unicode 🧚

Applications can interchange text in both ascii and utf8, leaving the selection choice to reader programs. While it is possible to access both at the same time, by fetch-ing content of the "Text" and "UTF8" clipboard slots, the widget proposes its own pasting scheme, where the mechanics are hidden under the "text" property call. The property is advised to be used instead of individual 'Text' and 'UTF8' formats. This method is used in all the standard widgets and is implemented so the programmer can reprogram its default action by overloading the "PasteText" notification of "Prima::Application" ( see "PasteText" in Prima::Application ).

The default action of "PasteText" is to query first if the 'Text' format is available, and if so, return the ascii text scalar. If Prima::Application::wantUnicodeInput is set (default), the 'UTF8' format is checked before resorting to 'Text'. This scheme is not the only possibly needed, for example, an application may want to ignore ASCII text, or, recognize UTF8 text but have the Prima::Application::wantUnicodeInput cleared, etc.

The symmetric action is "CopyText", which allows for a custom text conversion code to be installed.

🦋 Images 🦋

Image data can be transferred in different formats in different OSes. The lowest level is raw pixel data in display-based format, whereas GTK-based applications can also exchange images in file-based formats, such as bmp, png, etc. To avoid further complications in the implementations, the "PasteImage" action was introduced to handle these cases, together with a symmetrical "CopyImage".

The default action of "PasteImage" is to check whether lossless encoded image data is present, and if so, load a new image from this data, before falling back to the OS-dependent image storage.

When storing the image on the clipboard, only the default format, raw pixel data is used. Under X11 the toolkit can also serve images encoded as file formats.

Note: Under X11 you'll need to keep the image alive during the whole time it might get copied from the application — Prima doesn't keep a copy of the image, only the reference. Changing the image after it was stored in the clipboard will affect the clipboard content. 💀

⭐ Exact and meta formats ⭐

Prima registers two special meta formats, "Image" and "Text", that interoperate with the system clipboard, storing data in the format that matches best with system conventions when copying and pasting images and text, correspondingly. It is recommended to use the meta-format calls (has_format, text, image, copy, paste) rather than exact format calls (format_exists, store, fetch) whenever possible.

Where the exact format method operates on a single format data storage, meta format calls may operate on several exact formats. F.ex. "text" can check whether there exists a UTF-8 text storage before resorting to 8-bit text. "image" on X11 is even more complicated and may use image codecs to transfer encoded PNG streams, for example.

🍓 Special system formats 🍓

Warning: this section is experimental. 🙈

Under win32, it is possible to access files dropped from Explorer. The application must register a special "Win32.CF_HDROP" format, and read raw binary data in the "onDragEnd" handler:

               use constant CF_HDROP => "Win32.CF_HDROP";
               $::application-> Clipboard-> register_format( CF_HDROP );

               onDragEnd => sub {
                       my ( $self, $clipboard, $action, $modmap, $x, $y, $counterpart, $ref) = @_;
                       if ($clipboard->has_format(CF_HDROP)) {
                               my $raw = $clipboard->fetch(CF_HDROP);
                               my ($offset, $x, $y, $nonclient, $wide) = unpack("Lllll", $raw);
                               my $files = substr($raw, $offset);
                               if ($wide) {
                                       use Encode;
                                       $files = Encode::decode("utf-16le", $files);
                               }
                               my @files = split "\x0", $files;
                               print "dropped files: [@files] at [$x,$y]\n";
                       }
               }

✨ API ✨

okay bestie, this is the part where the clipboard actually does stuff. no cap. 💅

💖 Properties 💖

these are the two big get/set access points, and the page calls them Properties:

• image OBJECT, [KEEP] — gives you access to an image stored in the system clipboard. in get-mode it returns undef if no image is stored. in set-mode it clears the clipboard unless the KEEP flag is set. 🎀
• text STRING, [KEEP] — gives you access to the text stored in the system clipboard. in get-mode it returns undef if no text information is present. in set-mode it clears the clipboard unless the KEEP flag is set. ✨

---

🛠️ Methods 🛠️

• clear — deletes all data from the clipboard. bye-bye, clipboard contents 👋
• close — closes the open/close brackets. open() and close() can be called recursively. only the last close() removes the actual clipboard locking, so that other processes can use it as well. team player behavior fr fr 🫶
• copy FORMAT, DATA, KEEP — sets DATA in FORMAT. clears the clipboard first unless the KEEP flag is set. 💾
• deregister_format FORMAT_STRING — de-registers a previously registered data format. it's called implicitly for all custom formats before the program exits. 🧹
• fetch FORMAT_STRING — returns the data of the exact FORMAT_STRING data format, if it's present in the clipboard. depending on FORMAT_STRING, the data is either a text string for the 'Text' format, a Prima::Image object for the 'Image' format, or a binary scalar value for all custom formats. 🔍
• format_exists FORMAT_STRING — returns a boolean flag reflecting whether the FORMAT_STRING exact format data is present in the clipboard or not. yes/no girlie 💁‍♀️
• has_format FORMAT_STRING — returns a boolean flag reflecting whether the FORMAT_STRING meta format data is present in the clipboard or not. another yes/no moment ✨
• get_handle — returns the system handle for the clipboard object. the backstage pass 🎟️
• get_formats INCLUDE_UNREGISTERED = 0 — returns an array of strings, where each is a format ID, reflecting the formats present in the clipboard.

only the predefined formats and the formats registered via register_format() are returned if INCLUDE_UNREGISTERED is unset. if the flag is set, then all existing formats are returned, however their names are not necessarily the same as those registered with Prima. 👀

• get_registered_formats — returns an array of strings, each representing a registered format. "Text" and "Image" are returned also. 🏷️
• get_standard_clipboards — returns an array of strings, each representing a system clipboard. the default "Clipboard" is always present. other clipboards are optional. as an example, this function returns only "Clipboard" under win32, but also "Primary" and "Secondary" under X11. the code specific to these clipboards must refer to this function first. 🗂️

the drag-and-drop clipboard name is also returned here; it is system-specific. 🖱️

• is_dnd — returns 1 if the clipboard is the special clipboard used as a proxy for drag-and-drop interactions. 🫳

see also: "Widget/Drag and drop", "Application/get_dnd_clipboard".

• open — opens a system clipboard and locks it for the process single use; returns a success flag. subsequent "open" calls are possible and always return 1. each open() must correspond to close(), otherwise the clipboard will stay locked until the blocking process is finished. 🔒
• paste FORMAT_STRING — returns data of meta format FORMAT_STRING if found in the clipboard, or undef otherwise. 📋
• register_format FORMAT_STRING — registers a data format under FORMAT_STRING string ID, and returns a success flag. if a format is already registered, 1 is returned. all formats registered via register_format() are de-registered with deregister_format() when a program is finished. 📝
• store FORMAT_STRING, SCALAR — stores the SCALAR value into the clipboard in FORMAT_STRING exact data format. depending on FORMAT_STRING, the SCALAR value is treated as follows:

FORMAT_STRING     SCALAR
------------------------------------
Text              text string in ASCII
UTF8              text string in UTF8
Image             Prima::Image object
other formats     binary scalar value

Note: all custom formats are treated as binary data. in the case when the data are transferred between hosts with different byte orders, no implicit conversions are made. it is up to the programmer whether to convert the data into a portable format or leave it as is. the former option is of course preferable. as far as the author knows, the Storable module from the CPAN collection provides the system-independent conversion routines. 🧠✨

---

👑 AUTHOR 👑

Dmitry Karasik, <dmitry@karasik.eu.org>. 💌

---

🌈 SEE ALSO 🌈

Prima, Prima::Component, Prima::Application — go read those next, bestie. iykyk 🦋

---

okay that's the whole page! this one is pod::Pr...lipboard(3), from perl v5.42.0, dated 2024-08-20. mwah 💋🎀