.\" 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 "Prima 3"
.TH Prima 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 \- a perl graphic toolkit
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&        use Prima qw(Application Buttons);
\&
\&        new Prima::MainWindow(
\&                text     => \*(AqHello world!\*(Aq,
\&                size     => [ 200, 200],
\&        )\-> insert( Button =>
\&                centered => 1,
\&                text     => \*(AqHello world!\*(Aq,
\&                onClick  => sub { $::application\-> close },
\&        );
\&
\&        run Prima;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The toolkit is combined from two basic set of classes \- core and external. The
core classes are coded in C and form a base line for every Prima object 
written in perl. The usage of C is possible together with the toolkit; however,
its full power is revealed in the perl domain. The external classes present 
easily expandable set of widgets, written completely in perl and communicating 
with the system using Prima library calls.
.PP
The core classes form an hierarchy, which is displayed below:
.PP
.Vb 10
\&        Prima::Object
\&                Prima::Component
\&                        Prima::AbstractMenu
\&                                Prima::AccelTable
\&                                Prima::Menu
\&                                Prima::Popup
\&                        Prima::Clipboard
\&                        Prima::Drawable
\&                                Prima::DeviceBitmap
\&                                Prima::Printer
\&                                Prima::Image
\&                                        Prima::Icon
\&                        Prima::File
\&                        Prima::Timer
\&                        Prima::Widget
\&                                Prima::Application
\&                                Prima::Window
.Ve
.PP
The external classes are derived from these; the list of widget classes
can be found below in \*(L"\s-1SEE\s0 \s-1ALSO\s0\*(R".
.SH "BASIC PROGRAM"
.IX Header "BASIC PROGRAM"
The very basic code shown in \*(L"\s-1SYNOPSIS\s0\*(R" is explained here. 
The code creates a window with 'Hello,
world' title and a centered button with the same text. The program
terminates after the button is pressed.
.PP
A basic construct for a program written with Prima obviously requires
.PP
.Vb 1
\&        use Prima;
.Ve
.PP
code; however, the effective programming requires usage of the other
modules, for example, \f(CW\*(C`Prima::Buttons\*(C'\fR, which contains set of
button widgets. \f(CW\*(C`Prima.pm\*(C'\fR module can be
invoked with a list of such modules, which makes the construction
.PP
.Vb 3
\&        use Prima;
\&        use Prima::Application;
\&        use Prima::Buttons;
.Ve
.PP
shorter by using the following scheme:
.PP
.Vb 1
\&        use Prima qw(Application Buttons);
.Ve
.PP
Another basic issue is the event loop, which is called by
.PP
.Vb 1
\&        run Prima;
.Ve
.PP
sentence and requires a \f(CW\*(C`Prima::Application\*(C'\fR object to be created beforehand.
Invoking \f(CW\*(C`Prima::Application\*(C'\fR standard module is one of the possible ways to 
create an application object. The program usually terminates after the event loop
is finished.
.PP
The window is created by invoking
.PP
.Vb 1
\&        new Prima::Window();
.Ve
.PP
or
.PP
.Vb 1
\&        Prima::Window\-> create()
.Ve
.PP
code with the additional parameters. Actually, all Prima objects are created by such a
scheme. The class name is passed as the first parameter, and a custom set
of parameters is passed afterwards. These parameters are usually 
represented in a hash syntax, although actually passed as an array.
The hash syntax is preferred for the code readability:
.PP
.Vb 5
\&        $new_object = new Class(
\&                parameter => value,
\&                parameter => value,
\&                ...
\&        );
.Ve
.PP
Here, parameters are the class properties names, and differ from class to
class. Classes often have common properties, primarily due to the
object inheritance.
.PP
In the example, the following properties are set :
.PP
.Vb 5
\&        Window::text
\&        Window::size
\&        Button::text
\&        Button::centered
\&        Button::onClick
.Ve
.PP
Property values can be of any type, given that they are scalar. As depicted
here, \f(CW\*(C`::text\*(C'\fR property accepts a string, \f(CW\*(C`::size\*(C'\fR \- an anonymous array 
of two integers and \f(CW\*(C`onClick\*(C'\fR \- a sub.
.PP
onXxxx are special properties that form a class of \fIevents\fR, 
which share the \f(CW\*(C`new\*(C'\fR/\f(CW\*(C`create\*(C'\fR syntax, and are additive when 
the regular properties are substitutive (read more in Prima::Object). 
Events are called in the object context when a specific condition occurs. 
The \f(CW\*(C`onClick\*(C'\fR event here, for example, is called when the 
user presses (or otherwise activates) the button.
.SH "API"
.IX Header "API"
This section describes miscellaneous methods, registered in \f(CW\*(C`Prima::\*(C'\fR
namespace.
.IP "message \s-1TEXT\s0" 4
.IX Item "message TEXT"
Displays a system message box with \s-1TEXT\s0.
.IP "run" 4
.IX Item "run"
Enters the program event loop. The loop is ended when \f(CW\*(C`Prima::Application\*(C'\fR's \f(CW\*(C`destroy\*(C'\fR
or \f(CW\*(C`close\*(C'\fR method is called.
.ie n .IP "parse_argv @ARGS" 4
.el .IP "parse_argv \f(CW@ARGS\fR" 4
.IX Item "parse_argv @ARGS"
Parses prima options from \f(CW@ARGS\fR, returns unparsed arguments.
.SH "OPTIONS"
.IX Header "OPTIONS"
Prima applications do not have a portable set of arguments; it depends on the
particular platform. Run
.PP
.Vb 1
\&        perl \-e \*(Aq$ARGV[0]=q(\-\-help); require Prima\*(Aq
.Ve
.PP
or any Prima program with \f(CW\*(C`\-\-help\*(C'\fR argument to get the list of supported
arguments. Programmaticaly, setting and obtaining these options can be done
by using \f(CW\*(C`Prima::options\*(C'\fR routine.
.PP
In cases where Prima argument parsing conflicts with application options, use
Prima::noARGV to disable automatic parsing; also see parse_argv. 
Alternatively, the construct
.PP
.Vb 1
\&        BEGIN { local @ARGV; require Prima; }
.Ve
.PP
will also do.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
The toolkit documentation is divided by several
subjects, and the information can
be found in the following files:
.IP "Tutorials" 4
.IX Item "Tutorials"
Prima::tutorial \- introductory tutorial
.IP "Core toolkit classes" 4
.IX Item "Core toolkit classes"
Prima::Object \- basic object concepts, properties, events
.Sp
Prima::Classes \- binder module for the core classes
.Sp
Prima::Drawable \- 2\-D graphic interface
.Sp
Prima::Image  \- bitmap routines
.Sp
Prima::image\-load \- image subsystem and file operations
.Sp
Prima::Widget \- window management
.RS 4
.IP "\(bu" 2
Prima::Widget::pack \- Tk::pack geometry manager
.IP "\(bu" 2
Prima::Widget::place \- Tk::place geometry manager
.RE
.RS 4
.Sp
Prima::Window \- top-level window management
.Sp
Prima::Clipboard \- \s-1GUI\s0 interprocess data exchange
.Sp
Prima::Menu \- pull-down and pop-up menu objects
.Sp
Prima::Timer \- programmable periodical events
.Sp
Prima::Application \- root of widget objects hierarchy
.Sp
Prima::Printer \- system printing services
.Sp
Prima::File \- asynchronous stream I/O
.RE
.IP "Widget library" 4
.IX Item "Widget library"
Prima::Buttons \- buttons and button grouping widgets
.Sp
Prima::Calendar \- calendar widget
.Sp
Prima::ComboBox \- combo box widget
.Sp
Prima::DetailedList \- multi-column list viewer with controlling header widget
.Sp
Prima::DetailedOutline \- a multi-column outline viewer with controlling header widget
.Sp
Prima::DockManager \- advanced dockable widgets
.Sp
Prima::Docks \- dockable widgets
.Sp
Prima::Edit \- text editor widget
.Sp
Prima::ExtLists \- listbox with checkboxes
.Sp
Prima::FrameSet \- frameset widget class
.Sp
Prima::Grids \- grid widgets
.Sp
Prima::Header \- a multi-tabbed header widget
.Sp
Prima::HelpViewer \- the built-in \s-1POD\s0 file browser
.Sp
Prima::Image::TransparencyControl \- standard dialog for transparent color index selection
.Sp
Prima::ImageViewer \- bitmap viewer
.Sp
Prima::InputLine \- input line widget
.Sp
Prima::KeySelector \- key combination widget and routines
.Sp
Prima::Label \- static text widget
.Sp
Prima::Lists \- user-selectable item list widgets
.Sp
Prima::MDI \- top-level windows emulation classes
.Sp
Prima::Notebooks \- multipage widgets
.Sp
Prima::Outlines \- tree view widgets
.Sp
Prima::PodView \- \s-1POD\s0 browser widget
.Sp
Prima::ScrollBar \- scroll bars
.Sp
Prima::ScrollWidget \- scrollable generic document widget
.Sp
Prima::Sliders \- sliding bars, spin buttons and input lines, dial widget etc.
.Sp
Prima::StartupWindow \- a simplistic startup banner window
.Sp
Prima::TextView \- rich text browser widget
.Sp
Prima::Themes \- widget themes manager
.IP "Standard dialogs" 4
.IX Item "Standard dialogs"
Prima::ColorDialog \- color selection facilities
.Sp
Prima::EditDialog \- find and replace dialogs
.Sp
Prima::FileDialog \- file system related widgets and dialogs
.Sp
Prima::FontDialog \- font dialog
.Sp
Prima::ImageDialog \- image file open and save dialogs
.Sp
Prima::MsgBox \- message and input dialog boxes
.Sp
Prima::PrintDialog \- standard printer setup dialog
.Sp
Prima::StdDlg \- wrapper module to the toolkit standard dialogs
.IP "Visual Builder" 4
.IX Item "Visual Builder"
\&\s-1VB\s0 \- Visual Builder for the Prima toolkit
.Sp
Prima::VB::VBLoader \- Visual Builder file loader
.Sp
cfgmaint \- configuration tool for Visual Builder
.Sp
Prima::VB::CfgMaint \- maintains visual builder widget palette configuration
.IP "PostScript printer interface" 4
.IX Item "PostScript printer interface"
Prima::PS::Drawable \- PostScript interface to \f(CW\*(C`Prima::Drawable\*(C'\fR
.Sp
Prima::PS::Encodings \- latin-based encodings
.Sp
Prima::PS::Fonts \- PostScript device fonts metrics
.Sp
Prima::PS::Printer \- PostScript interface to \f(CW\*(C`Prima::Printer\*(C'\fR
.IP "C interface to the toolkit" 4
.IX Item "C interface to the toolkit"
Prima::internals \- Internal architecture
.Sp
Prima::codecs    \- Step-by-step image codec creation
.Sp
gencls           \- \f(CW\*(C`gencls\*(C'\fR, a class compiler tool.
.IP "Miscellaneous" 4
.IX Item "Miscellaneous"
Prima::faq \- frequently asked questions
.Sp
Prima::Const \- predefined toolkit constants
.Sp
Prima::EventHook \- event filtering
.Sp
Prima::Image::AnimateGIF \- animate gif files
.Sp
Prima::IniFile \- support of Windows-like initialization files
.Sp
Prima::IntUtils \- internal functions
.Sp
Prima::StdBitmap \- shared access to the standard toolkit bitmaps
.Sp
Prima::Stress \- stress test module
.Sp
Prima::Tie \- tie widget properties to scalars or arrays
.Sp
Prima::Utils \- miscellaneous routines
.Sp
Prima::Widgets \- miscellaneous widget classes
.Sp
Prima::gp\-problems \- Graphic subsystem portability issues
.Sp
Prima::X11 \- usage guide for X11 environment
.IP "Class information" 4
.IX Item "Class information"
The Prima manual pages often provide information for more than one Prima class.
To quickly find out the manual page of a desired class, as well as display the
inheritance information, use \f(CW\*(C`p\-class\*(C'\fR command. The command can produce output in
text and pod formats; the latter feature is used by the standard Prima documentation
viewer \f(CW\*(C`podview\*(C'\fR ( see File/Run/p\-class ).
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 1997, 2003 The Protein Laboratory, University of Copenhagen. All
rights reserved.
.PP
Copyright 2004 Dmitry Karasik. All rights reserved.
.PP
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
.SH "AUTHORS"
.IX Header "AUTHORS"
Dmitry Karasik <dmitry@karasik.eu.org>,
Anton Berezin <tobez@tobez.org>,
Vadim Belman <voland@lflat.org>,