Man Linux: Main Page and Category List

NAME

       Prima::Clipboard - GUI interprocess data exchange

DESCRIPTION

       Prima::Clipboard class is a descendant of Prima::Component.  It serves
       as an interface to the specific data storage, called clipboard, visible
       to all clients of one GUI space. The system clipboard is intended for
       the exchange of information of an arbitrary type between graphic
       applications.

SYNOPSIS

          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 the easier communication, the system clipboard has one ’format’
       field, that 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
       possibility that the receiving application recognizes the data.

       Different systems provide spectrum of predefined data types, but the
       toolkit uses only three of these - 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, and the three
       predefined formats are represented by 'Text', 'UTF8', and 'Image'
       string constants.

       The most frequent usage of Prima::Clipboard is to preform 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);

       This simplistic code hides other aspects of Prima::Clipboard class.

       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 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, code for fetching and storing multi-format data is somewhat
       different. Clipboard is viewed as a shared system resource, and have 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 the clipboard locking is advisory,
       and any process can grab clipboard at any time) .

       "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 said:

           # 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 a program:

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

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

   Unicode
       In real life, application often interchange text in both ascii and
       utf8, leaving the choice to reader programs.  While it is possible to
       access both at the same time, by "fetch"’ing content of "Text" and
       "UTF8" clipboard slots, widgets implement their own pasting scheme. To
       avoid hacking widget code, usage of "text" property is advised instead
       of indicating 'Text' and 'UTF8' constants. This method is used in
       standard widgets, and is implemented so the programmer can reprogram
       its default action by overloading "PasteText" notification of
       "Prima::Application" ( see "PasteText" in Prima::Application ).

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

API

   Properties
       image OBJECT
           Provides access to an image, stored in the system clipboard.  In
           get-mode call, return "undef" if no image is stored.

       text STRING
           Provides access to text stored in the system clipboard.  In get-
           mode call, return "undef" if no text information is present.

   Methods
       clear
           Deletes all data from clipboard.

       close
           Closes the open/close brackets. open() and close() can be called
           recursively; only the last close() removes the actual clipboard
           locking, so other processes can use it as well.

       deregister_format FORMAT_STRING
           De-registers a previously registered data format.  Called
           implicitly for all not de-registered format before a clipboard
           object is destroyed.

       fetch FORMAT_STRING
           Returns the data of FORMAT_STRING data format, if present in the
           clipboard. Depending on FORMAT_STRING, data is either text string
           for 'Text' format, Prima::Image object for 'Image' format and a
           binary scalar value for all custom formats.

       format_exists FORMAT_STRING
           Returns a boolean flag, showing whether FORMAT_STRING format data
           is present in the clipboard or not.

       get_handle
           Returns a system handle for a clipboard object.

       get_formats
           Returns 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. There is no way to see if a
           format, not registered before, is present.

       get_registered_formats
           Returns array of strings, each representing a registered format.
           "Text" and "Image" are returned also.

       get_standard_clipboards
           Returns 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.

       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.

       register_format FORMAT_STRING
           Registers a data format under FORMAT_STRING string ID, 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 SCALAR value into the clipboard in FORMAT_STRING data
           format. Depending of FORMAT_STRING, SCALAR 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

           NB. All custom formats treated as a binary data. In 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 in 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 CPAN collection provides the system-
           independent conversion routines.

AUTHOR

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

SEE ALSO

       Prima, Prima::Component, Prima::Application