Prima(3)

NAME
Prima - a perl graphic toolkit

SYNOPSIS
  use Prima qw(Application Buttons);

  Prima::MainWindow-> create(
      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

  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 = Class-> create(
     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 "create" 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 "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.

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.

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

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

    Prima::Classes - binder module for the core classes

    Prima::Drawable - 2-D graphic interface

    Prima::Image - bitmap routines

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

    Prima::Widget - window management

        Prima::Widget::pack - Tk::pack geometry manager

        Prima::Widget::place - Tk::place geometry manager

    Prima::Window - top-level window management

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

    Prima::Timer - programmable periodical events

    Prima::Application - root of widget objects hierarchy

    Prima::Printer - system printing services

    Prima::File - asynchronous stream I/O

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

    Prima::Calendar - calendar widget

    Prima::ComboBox - combo box widget

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

    Prima::DockManager - advanced dockable widgets

    Prima::Docks - dockable widgets

    Prima::Edit - text editor widget

    Prima::ExtLists - listbox with checkboxes

    Prima::FrameSet - frameset widget class

    Prima::Grids - grid widgets

    Prima::Header - a multi-tabbed header widget

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

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

    Prima::ImageViewer - bitmap viewer

    Prima::InputLine - input line widget

    Prima::KeySelector - key combination widget and routines

    Prima::Label - static text widget

    Prima::Lists - user-selectable item list widgets

    Prima::MDI - top-level windows emulation classes

    Prima::Notebooks - multipage widgets

    Prima::Outlines - tree view widgets

    Prima::PodView - POD browser widget

    Prima::ScrollBar - scroll bars

    Prima::ScrollWidget - scrollable generic document widget

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

    Prima::StartupWindow - a simplistic startup banner window

    Prima::TextView - rich text browser widget

    Prima::Themes - widget themes manager

Standard dialogs
    Prima::ColorDialog - color selection facilities

    Prima::EditDialog - find and replace dialogs

    Prima::FileDialog - file system related widgets and dialogs

    Prima::FontDialog - font dialog

    Prima::ImageDialog - image file open and save dialogs

    Prima::MsgBox - message and input dialog boxes

    Prima::PrintDialog - standard printer setup dialog

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

Visual Builder
    VB - Visual Builder for the Prima toolkit

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

    cfgmaint - configuration tool for Visual Builder

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

PostScript printer interface
    Prima::PS::Drawable - PostScript interface to "Prima::Drawable"

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

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

    Prima::PS::Printer - PostScript interface to "Prima::Printer"

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

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

    gencls - "gencls", a class compiler tool.

    Prima::Make - module for automated Makefile creation

Miscellaneous
    Prima::Const - predefined toolkit constants

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

    Prima::IntUtils - internal functions

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

    Prima::Stress - stress test module

    Prima::Utils - miscellaneous routines

    Prima::Widgets - miscellaneous widget classes

    Prima::gp-problems - Graphic subsystem portability issues

COPYRIGHT
Copyright 1997, 2002 The Protein Laboratory, University of Copenhagen. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

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