Prima::Clipboard - GUI interprocess data exchange |
Prima::Clipboard - GUI interprocess data exchange
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.
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;
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; }
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.
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 the Prima::Application manpage ).
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.
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, PasteImage
action was introduced to handle these cases.
The default action of PasteImage
is to query first if 'Image'
format is
available, and if so, return the Image object. This by default reads data from
raw image buffer, but if fails, on unix the logic proceeds by checking data in
formats 'image/bmp', 'image/png' etc. BMP
is checked first because the
corresponding codec is always compiled in Prima, it doesn't depend on external
libraries. Next is checked PNG
format, because it is lossless, then TIFF
,
then all others.
When storing the image on the clipboard, only the default format, raw pixel data is used.
undef
if no image is stored.
undef
if no text information is
present.
open()
and close()
can
be called recursively; only the last close()
removes the
actual clipboard locking, so other processes can use it as well.
'Text'
format,
Prima::Image object for 'Image'
format and a binary scalar
value for all custom formats.
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.
Text
and Image
are returned also.
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
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()
are de-registered with deregister_format()
when a program is
finished.
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.
Dmitry Karasik, <dmitry@karasik.eu.org>.
Prima, the Prima::Component manpage, the Prima::Application manpage
Prima::Clipboard - GUI interprocess data exchange |