.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "pod::Prima::Clipboard 3"
.TH pod::Prima::Clipboard 3 "2009-02-24" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Prima::Clipboard \- GUI interprocess data exchange
.SH "DESCRIPTION"
.IX Header "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 
\&\s-1GUI\s0 space. The system clipboard is intended for the exchange of
information of an arbitrary type between graphic applications.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&   my $c = $::application\-> Clipboard;
\&
\&   # paste data
\&   my $string = $c\-> text;
\&   my $image  = $c\-> image;
\&   my $other  = $c\-> fetch(\*(AqOther type\*(Aq);
\&
\&   # copy datum
\&   $c\-> text( $string);
\&
\&   # copy data
\&   $c\-> open;
\&   $c\-> text( $string);
\&   $c\-> image( $image);
\&   $c\-> store( $image);
\&   $c\-> close;
\&
\&   # clear
\&   $c\-> clear;
.Ve
.SH "USAGE"
.IX Header "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.
.PP
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 \f(CW\*(AqText\*(Aq\fR, \f(CW\*(AqUTF8\*(Aq\fR, and \f(CW\*(AqImage\*(Aq\fR string constants.
.PP
The most frequent usage of Prima::Clipboard is to preform
two tasks \- copying and pasting. Both can be exemplified by
the following:
.PP
.Vb 1
\&   my $c = $::application\-> Clipboard;
\&
\&   # paste
\&   my $string = $c\-> text;
\&
\&   # copy
\&   $c\-> text( $string);
.Ve
.PP
This simplistic code hides other aspects of Prima::Clipboard class.
.PP
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. \f(CW\*(C`get_standard_clipboards()\*(C'\fR method
returns strings for the clipboards, provided by the system.
.PP
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) .
.PP
\&\f(CW\*(C`fetch()\*(C'\fR and \f(CW\*(C`store()\*(C'\fR implicitly call \f(CW\*(C`open()\*(C'\fR
and \f(CW\*(C`close()\*(C'\fR, but these functions must be called explicitly
for the multi-format data handling. The code below illustrates the
said:
.PP
.Vb 7
\&    # copy text and image 
\&    if ( $c\-> open) {
\&       $c\-> clear;
\&       $c\-> store(\*(AqText\*(Aq, $string);
\&       $c\-> store(\*(AqImage\*(Aq, $image);
\&       $c\-> close;
\&    }
\&
\&    # check present formats and paste 
\&   if ( $c\-> open) { 
\&      if ( $c\-> format_exists(\*(AqText\*(Aq)) {
\&         $string = $c\-> fetch(\*(AqText\*(Aq);
\&      }
\&      # or, check the desired format alternatively
\&      my %formats = map { $_ => 1 } $c\-> get_formats;
\&      if ( $formats{\*(AqImage\*(Aq}) {
\&         $image = $c\-> fetch(\*(AqImage\*(Aq);
\&      }
\&
\&      $c\-> close;
\&   }
.Ve
.PP
The \fIclear()\fR call in the copying code is necessary so
the newly written data will not mix with the old.
.PP
At last, the newly registered formats can be accessed
by a program:
.PP
.Vb 8
\&   my $myformat = \*(AqVery Special Old Pale Data Format\*(Aq;
\&   if ( $c\-> register_format($myformat)) {
\&      $c\-> open;
\&      $c\-> clear;
\&      $c\-> store(\*(AqText\*(Aq, \*(Aqsample text\*(Aq);
\&      $c\-> store($myformat\*(Aq, \*(Aqsample ## text\*(Aq);
\&      $c\-> close;
\&   }
.Ve
.SS "Custom formats"
.IX Subsection "Custom formats"
Once registered, all processes in a \s-1GUI\s0 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.
.SS "Unicode"
.IX Subsection "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 \f(CW\*(C`fetch\*(C'\fR'ing content of \f(CW\*(C`Text\*(C'\fR and \f(CW\*(C`UTF8\*(C'\fR clipboard slots,
widgets implement their own pasting scheme. To avoid hacking widget code, usage
of \f(CW\*(C`text\*(C'\fR property is advised instead of indicating \f(CW\*(AqText\*(Aq\fR and \f(CW\*(AqUTF8\*(Aq\fR
constants. This method is used in standard widgets, and is implemented so
the programmer can reprogram its default action by overloading \f(CW\*(C`PasteText\*(C'\fR
notification of \f(CW\*(C`Prima::Application\*(C'\fR ( see \*(L"PasteText\*(R" in Prima::Application ).
.PP
The default action of \f(CW\*(C`PasteText\*(C'\fR is to query first if \f(CW\*(AqText\*(Aq\fR format is available,
and if so, return the ascii text scalar. If \f(CW\*(C`Prima::Application::wantUnicodeInput\*(C'\fR is set, 
\&\f(CW\*(AqUTF8\*(Aq\fR format is checked before resorting to \f(CW\*(AqText\*(Aq\fR. It is clear that this
scheme is not the only possibly needed, for example, an application may want
to ignore \s-1ASCII\s0 text, or, ignore \s-1UTF8\s0 text but have \f(CW\*(C`Prima::Application::wantUnicodeInput\*(C'\fR
set, etc.
.SH "API"
.IX Header "API"
.SS "Properties"
.IX Subsection "Properties"
.IP "image \s-1OBJECT\s0" 4
.IX Item "image OBJECT"
Provides access to an image, stored in the system clipboard.
In get-mode call, return \f(CW\*(C`undef\*(C'\fR if no image is stored.
.IP "text \s-1STRING\s0" 4
.IX Item "text STRING"
Provides access to text stored in the system clipboard.
In get-mode call, return \f(CW\*(C`undef\*(C'\fR if no text information is
present.
.SS "Methods"
.IX Subsection "Methods"
.IP "clear" 4
.IX Item "clear"
Deletes all data from clipboard.
.IP "close" 4
.IX Item "close"
Closes the open/close brackets. \fIopen()\fR and \fIclose()\fR can
be called recursively; only the last \fIclose()\fR removes the
actual clipboard locking, so other processes can use it as well.
.IP "deregister_format \s-1FORMAT_STRING\s0" 4
.IX Item "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.
.IP "fetch \s-1FORMAT_STRING\s0" 4
.IX Item "fetch FORMAT_STRING"
Returns the data of \s-1FORMAT_STRING\s0 data format,
if present in the clipboard. Depending on \s-1FORMAT_STRING\s0,
data is either text string for \f(CW\*(AqText\*(Aq\fR format, 
Prima::Image object for \f(CW\*(AqImage\*(Aq\fR format and a binary scalar
value for all custom formats.
.IP "format_exists \s-1FORMAT_STRING\s0" 4
.IX Item "format_exists FORMAT_STRING"
Returns a boolean flag, showing whether \s-1FORMAT_STRING\s0
format data is present in the clipboard or not.
.IP "get_handle" 4
.IX Item "get_handle"
Returns a system handle for a clipboard object.
.IP "get_formats" 4
.IX Item "get_formats"
Returns array of strings, where each is a format \s-1ID\s0,
reflecting the formats present in the clipboard.
.Sp
Only the predefined formats, and the formats registered
via \f(CW\*(C`register_format()\*(C'\fR are returned. There is no
way to see if a format, not registered before, is present.
.IP "get_registered_formats" 4
.IX Item "get_registered_formats"
Returns array of strings, each representing 
a registered format. \f(CW\*(C`Text\*(C'\fR and \f(CW\*(C`Image\*(C'\fR
are returned also.
.IP "get_standard_clipboards" 4
.IX Item "get_standard_clipboards"
Returns array of strings, each representing
a system clipboard. The default \f(CW\*(C`Clipboard\*(C'\fR
is always present. Other clipboards are optional.
As an example, this function returns only \f(CW\*(C`Clipboard\*(C'\fR
under win32, but also \f(CW\*(C`Primary\*(C'\fR and \f(CW\*(C`Secondary\*(C'\fR
under X11. The code, specific to these clipboards
must refer to this function first.
.IP "open" 4
.IX Item "open"
Opens a system clipboard and locks it for the process
single use; returns a success flag. Subsequent \f(CW\*(C`open\*(C'\fR
calls are possible, and always return 1. Each \f(CW\*(C`open()\*(C'\fR
must correspond to \f(CW\*(C`close()\*(C'\fR, otherwise the clipboard 
will stay locked until the blocking process is finished.
.IP "register_format \s-1FORMAT_STRING\s0" 4
.IX Item "register_format FORMAT_STRING"
Registers a data format under \s-1FORMAT_STRING\s0 string \s-1ID\s0,
returns a success flag. If a format is already registered,
1 is returned. All formats, registered via \f(CW\*(C`register_format()\*(C'\fR
are de-registered with \f(CW\*(C`deregister_format()\*(C'\fR when a program is
finished.
.IP "store \s-1FORMAT_STRING\s0, \s-1SCALAR\s0" 4
.IX Item "store FORMAT_STRING, SCALAR"
Stores \s-1SCALAR\s0 value into the clipboard in \s-1FORMAT_STRING\s0
data format. Depending of \s-1FORMAT_STRING\s0, \s-1SCALAR\s0 is treated as follows:
.Sp
.Vb 6
\&   FORMAT_STRING     SCALAR
\&   \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&   Text              text string in ASCII
\&   UTF8              text string in UTF8
\&   Image             Prima::Image object
\&   other formats     binary scalar value
.Ve
.Sp
\&\s-1NB\s0. 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 \fIStorable\fR module from \fI\s-1CPAN\s0\fR collection provides the system-independent
conversion routines.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dmitry Karasik, <dmitry@karasik.eu.org>.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Prima, Prima::Component, Prima::Application