Prima(3)

NAME
Prima - a perl graphic toolkit

SYNOPSIS
  use Prima qw(Application Buttons);
  Prima::Window-> 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 the SEE ALSO entry elsewhere in this document.

BASIC PROGRAM
The very basic code shown in the section on "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, what 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 before. 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 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.

find_image PATH
    Converts PATH from perl module notation into a file path, and searches for the file in "@INC" paths set. If a file is found, its full filename is returned; otherwise "undef" is returned.

message TEXT
    Displays a system message box with TEXT.

path [ FILE ]
    If called with no parameters, returns path to a directory, usually ~/.prima, that can be used to contain the user settings of a toolkit module or a program. If FILE is specified, appends it to the path and returns the full file name. In the latter case the path is automatically created by "File::Path::mkpath" unless already exists.

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

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

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::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::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::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

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
    the VB manpage - Visual Builder for the Prima toolkit

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

    the cfgmaint manpage - 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

    the gencls manpage - "gencls", a class compiler tool.

    the Prima::Make manpage - module for automated Makefile creation

Miscellaneous
    the Prima::Const manpage - predefined toolkit constants

    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::Utils manpage - miscellanneous routines

    the Prima::Widgets manpage - miscellaneous widget classes

    the Prima::gp-problems manpage - 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>,