Prima - a perl graphic toolkit



NAME

Prima - a perl graphic toolkit


SYNOPSIS

        use Prima qw(Application Buttons);
        new Prima::MainWindow(
                text     => 'Hello world!',
                size     => [ 200, 200],
        )-> insert( Button =>
                centered => 1,
                text     => 'Hello world!',
                onClick  => sub { $::application-> close },
        );
        run Prima;


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.

The core classes form an hierarchy, which is displayed below:

        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

The external classes are derived from these; the list of widget classes can be found below in SEE ALSO.


BASIC PROGRAM

The very basic code shown in SYNOPSIS 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.

A basic construct for a program written with Prima obviously requires

        use Prima;

code; however, the effective programming requires usage of the other modules, for example, Prima::Buttons, which contains set of button widgets. Prima.pm module can be invoked with a list of such modules, which makes the construction

        use Prima;
        use Prima::Application;
        use Prima::Buttons;

shorter by using the following scheme:

        use Prima qw(Application Buttons);

Another basic issue is the event loop, which is called by

        run Prima;

sentence and requires a Prima::Application object to be created beforehand. Invoking Prima::Application standard module is one of the possible ways to create an application object. The program usually terminates after the event loop is finished.

The window is created by invoking

        new Prima::Window();

or

        Prima::Window-> create()

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:

        $new_object = new Class(
                parameter => value,
                parameter => value,
                ...
        );

Here, parameters are the class properties names, and differ from class to class. Classes often have common properties, primarily due to the object inheritance.

In the example, the following properties are set :

        Window::text
        Window::size
        Button::text
        Button::centered
        Button::onClick

Property values can be of any type, given that they are scalar. As depicted here, ::text property accepts a string, ::size - an anonymous array of two integers and onClick - a sub.

onXxxx are special properties that form a class of events, which share the new/create syntax, and are additive when the regular properties are substitutive (read more in the Prima::Object manpage). Events are called in the object context when a specific condition occurs. The onClick event here, for example, is called when the user presses (or otherwise activates) the button.


API

This section describes miscellaneous methods, registered in Prima:: namespace.

message TEXT
Displays a system message box with TEXT.

run
Enters the program event loop. The loop is ended when Prima::Application's destroy or close method is called.

parse_argv @ARGS
Parses prima options from @ARGS, returns unparsed arguments.


OPTIONS

Prima applications do not have a portable set of arguments; it depends on the particular platform. Run

        perl -e '$ARGV[0]=q(--help); require Prima'

or any Prima program with --help argument to get the list of supported arguments. Programmaticaly, setting and obtaining these options can be done by using Prima::options routine.

In cases where Prima argument parsing conflicts with application options, use the Prima::noARGV manpage to disable automatic parsing; also see parse_argv. Alternatively, the construct

        BEGIN { local @ARGV; require Prima; }

will also do.


SEE ALSO

The toolkit documentation is divided by several subjects, and the information can be found in the following files:

Tutorials
the Prima::tutorial manpage - introductory tutorial

Core toolkit classes
the Prima::Object manpage - basic object concepts, properties, events

the Prima::Classes manpage - binder module for the core classes

the Prima::Drawable manpage - 2-D graphic interface

the Prima::Image manpage - bitmap routines

the Prima::image-load manpage - image subsystem and file operations

the Prima::Widget manpage - window management

the Prima::Window manpage - top-level window management

the Prima::Clipboard manpage - GUI interprocess data exchange

the Prima::Menu manpage - pull-down and pop-up menu objects

the Prima::Timer manpage - programmable periodical events

the Prima::Application manpage - root of widget objects hierarchy

the Prima::Printer manpage - system printing services

the Prima::File manpage - asynchronous stream I/O

Widget library
the Prima::Buttons manpage - buttons and button grouping widgets

the Prima::Calendar manpage - calendar widget

the Prima::ComboBox manpage - combo box widget

the Prima::DetailedList manpage - multi-column list viewer with controlling header widget

the Prima::DetailedOutline manpage - a multi-column outline viewer with controlling header widget

the Prima::DockManager manpage - advanced dockable widgets

the Prima::Docks manpage - dockable widgets

the Prima::Edit manpage - text editor widget

the Prima::ExtLists manpage - listbox with checkboxes

the Prima::FrameSet manpage - frameset widget class

the Prima::Grids manpage - grid widgets

the Prima::Header manpage - a multi-tabbed header widget

the Prima::HelpViewer manpage - the built-in POD file browser

the Prima::Image::TransparencyControl manpage - standard dialog for transparent color index selection

the Prima::ImageViewer manpage - bitmap viewer

the Prima::InputLine manpage - input line widget

the Prima::KeySelector manpage - key combination widget and routines

the Prima::Label manpage - static text widget

the Prima::Lists manpage - user-selectable item list widgets

the Prima::MDI manpage - top-level windows emulation classes

the Prima::Notebooks manpage - multipage widgets

the Prima::Outlines manpage - tree view widgets

the Prima::PodView manpage - POD browser widget

the Prima::ScrollBar manpage - scroll bars

the Prima::ScrollWidget manpage - scrollable generic document widget

the Prima::Sliders manpage - sliding bars, spin buttons and input lines, dial widget etc.

the Prima::StartupWindow manpage - a simplistic startup banner window

the Prima::TextView manpage - rich text browser widget

the Prima::Themes manpage - widget themes manager

Standard dialogs
the Prima::ColorDialog manpage - color selection facilities

the Prima::EditDialog manpage - find and replace dialogs

the Prima::FileDialog manpage - file system related widgets and dialogs

the Prima::FontDialog manpage - font dialog

the Prima::ImageDialog manpage - image file open and save dialogs

the Prima::MsgBox manpage - message and input dialog boxes

the Prima::PrintDialog manpage - standard printer setup dialog

the Prima::StdDlg manpage - wrapper module to the toolkit standard dialogs

Visual Builder
VB - Visual Builder for the Prima toolkit

the Prima::VB::VBLoader manpage - Visual Builder file loader

cfgmaint - configuration tool for Visual Builder

the Prima::VB::CfgMaint manpage - maintains visual builder widget palette configuration

PostScript printer interface
the Prima::PS::Drawable manpage - PostScript interface to Prima::Drawable

the Prima::PS::Encodings manpage - latin-based encodings

the Prima::PS::Fonts manpage - PostScript device fonts metrics

the Prima::PS::Printer manpage - PostScript interface to Prima::Printer

C interface to the toolkit
the Prima::internals manpage - Internal architecture

the Prima::codecs manpage - Step-by-step image codec creation

gencls - gencls, a class compiler tool.

Miscellaneous
the Prima::faq manpage - frequently asked questions

the Prima::Const manpage - predefined toolkit constants

the Prima::EventHook manpage - event filtering

the Prima::Image::AnimateGIF manpage - animate gif files

the Prima::IniFile manpage - support of Windows-like initialization files

the Prima::IntUtils manpage - internal functions

the Prima::StdBitmap manpage - shared access to the standard toolkit bitmaps

the Prima::Stress manpage - stress test module

the Prima::Tie manpage - tie widget properties to scalars or arrays

the Prima::Utils manpage - miscellaneous routines

the Prima::Widgets manpage - miscellaneous widget classes

the Prima::gp-problems manpage - Graphic subsystem portability issues

the Prima::X11 manpage - usage guide for X11 environment

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 p-class command. The command can produce output in text and pod formats; the latter feature is used by the standard Prima documentation viewer podview ( see File/Run/p-class ).


COPYRIGHT

Copyright 1997-2003 The Protein Laboratory, University of Copenhagen. All rights reserved.

Copyright 2004-2012 Dmitry Karasik. All rights reserved.

This program is distributed under the BSD License.


AUTHORS

Dmitry Karasik <dmitry@karasik.eu.org>, Anton Berezin <tobez@tobez.org>, Vadim Belman <voland@lflat.org>,

 Prima - a perl graphic toolkit