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