The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.

NAME

Prima - a Perl graphic toolkit

SYNOPSIS

use Prima qw(Application Buttons);

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

run Prima;

See more screenshots at http://prima.eu.org/big-picture.

DESCRIPTION

Prima is a classic 2D GUI toolkit that works under Windows and X11 environments. The toolkit features a rich widget library, extensive 2D graphic support, PDF generation, modern Unicode text input and output, and supports a wide set of image formats. Additionally, the RAD-style Visual Builder and POD viewer are included. The toolkit can interoperate with other popular event loop libraries.

CLASS HIERARCHY

The toolkit is built with a combination of two basic sets of classes - core and external. The core classes are coded in C and form a baseline 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 an easily expandable set of widgets, written entirely in Perl and communicating with the system using Prima library calls.

The core classes form a 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::Region
		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 a 'Hello, world' title and a button with the same text. The program terminates after the button is pressed.

A basic construct for a program written with Prima requires

use Prima;

code; however, effective programming requires the usage of the other modules, for example, Prima::Buttons, which contains various button widgets. The Prima.pm module can be invoked together 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;

code and requires a Prima::Application object to be created beforehand. Invoking the 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 main window is created by invoking

Prima::MainWindow->new();

or

Prima::MainWindow->create()

code with additional parameters. All Prima objects are created by the same scheme; the class name is passed as the first parameter, and a custom set of parameters is passed afterward:

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

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

In the example, the following properties are used:

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

Property values can be of any scalar type. For example, the ::text property accepts a string, ::size - an anonymous array of two integers, and onClick - a sub.

onXxxx are special properties that describe events that can be used together with the new/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 the Prima:: namespace.

message TEXT

Displays a system message box with TEXT.

open_file, save_file

When the Prima::Dialog::FileDialog module is loaded, these shortcut methods are registered in the Prima:: namespace as an alternative to the same methods in the module's namespace. The methods execute standard file open and save dialogs, correspondingly.

See Prima::Dialog::FileDialog for more.

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 a --help argument to get the list of supported arguments. Programmatically, setting and obtaining these options can be done by using the Prima::options routine.

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

BEGIN { local @ARGV; require Prima; }

will also do.

SEE ALSO

The toolkit documentation is divided into several sections; the individual manuals can be found in the following files:

Tutorials

Prima::tutorial - introductory tutorial

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::Region - generic shape for clipping and hit testing

Prima::Image - bitmap routines

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

Prima::Widget - window management

Prima::Window - top-level window management

Prima::Clipboard - GUI interprocess data exchange

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

Prima::Timer - programmable periodical events

Prima::Application - the root of widget objects hierarchy

Prima::Printer - system printing services

Prima::File - asynchronous stream I/O

Widget library

Prima::Buttons - buttons, checkboxes, radios

Prima::Calendar - calendar widget

Prima::ComboBox - combo box widget

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

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

Prima::DockManager - advanced dockable widgets

Prima::Docks - dockable widgets

Prima::Edit - text editor

Prima::ExtLists - listbox with checkboxes

Prima::FrameSet - frameset widget

Prima::Grids - grid widgets

Prima::HelpViewer - the built-in POD browser

Prima::ImageViewer - image viewer

Prima::InputLine - input line widget

Prima::KeySelector - key combination widget and routines

Prima::Menus - menu widgets

Prima::Label - static text widget

Prima::Lists - list widgets

Prima::MDI - top-level window emulation

Prima::Notebooks - multipage widgets

Prima::Outlines - tree view widgets

Prima::PodView - POD browser widget

Prima::ScrollBar - scroll bars

Prima::Sliders - sliding bars, spin buttons, dial widgets, etc.

Prima::Spinner - spinner animation widget

Prima::TextView - rich text browser widget

Prima::Widget::Date - date picker widget

Prima::Widget::Time - time input widget

Standard dialogs

Prima::Dialog::ColorDialog - color selection facilities

Prima::Dialog::FindDialog - find and replace dialogs

Prima::Dialog::FileDialog - file system-related widgets and dialogs

Prima::Dialog::FontDialog - font dialog

Prima::Dialog::ImageDialog - image file open and save dialogs

Prima::Image::TransparencyControl - transparent color index selection

Prima::MsgBox - message and input dialog boxes

Prima::Dialog::PrintDialog - standard printer setup dialog

Drawing helpers

Prima::Drawable::Antialias - plot antialiased shapes

Prima::Drawable::CurvedText - fit text to path

Prima::Drawable::Glyphs - bi-directional text input and complex scripts output

Prima::Drawable::Gradient - gradient fills for primitives

Prima::Drawable::Markup - allow markup in widgets

Prima::Drawable::Metafile - graphics recorder

Prima::Drawable::Path - stroke and fill complex paths

Prima::Drawable::Pod - POD parser and renderer

Prima::Drawable::Subcanvas - paint a hierarchy of widgets to any drawable

Prima::Drawable::TextBlock - rich text representation

Visual Builder

VB - Visual Builder for the Prima toolkit

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

prima-cfgmaint - configuration tool for Visual Builder

Prima::VB::CfgMaint - configures the widget palette in the Visual Builder

prima-fmview - .fm file viewer

PostScript printer interface

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

Prima::PS::PDF - PDF interface to Prima::Drawable

Prima::PS::Printer - PostScript and PDF interfaces to Prima::Printer

Widget helpers

Prima::Widget::BidiInput - heuristics for i18n input

Prima::Widget::Fader - fading- in/out functions

Prima::Widget::GroupScroller - optional automatic scroll bars

Prima::Widget::Header - multi-column header widget

Prima::Widget::IntIndents - indenting support

Prima::Widget::Link - links embedded in widgets

Prima::Widget::ListBoxUtils - common paint routine for listboxes

Prima::Widget::MouseScroller - auto-repeating mouse events

Prima::Widget::Panel - simple panel widget

Prima::Widget::RubberBand - dynamic rubberbands

Prima::Widget::ScrollWidget - scrollable generic document widget

Prima::Widget::StartupWindow - a simplistic startup banner window

Prima::Widget::UndoActions - undo and redo the content of editable widgets

C interface to the toolkit

Prima::internals - Internal architecture

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

prima-gencls - prima-gencls, a class compiler tool.

prima-tmlink - prima-tmlink, optimizer tool for files produced by prima-gencls.

Miscellaneous

Prima::faq - frequently asked questions

Prima::Const - predefined toolkit constants

Prima::EventHook - event filtering

Prima::Image::Animate - animate gif and webp files

Prima::Image::base64 - hardcoded image files

Prima::Image::Exif - manipulate Exif records

Prima::Image::Loader - progressive loading and saving for multiframe images

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

podview - POD viewer

prima-pod2pdf - POD printer

Prima::StdBitmap - shared access to the standard bitmaps

Prima::Stress - stress test module

Prima::Themes - widget themes manager

Prima::Tie - tie widget properties to scalars and arrays

Prima::types - builtin types

Prima::Utils - miscellaneous routines

System-specific modules and documentation

Prima::gp-problems - Graphic subsystem portability issues

Prima::X11 - usage guide for X11 environment

Prima::sys::gtk::FileDialog - GTK file system dialogs

Prima::sys::win32::FileDialog - Windows file system dialogs

Prima::sys::XQuartz - MacOSX/XQuartz facilities

Prima::sys::FS - unicode-aware core file functions

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

COPYRIGHT

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

Copyright 2004-2024 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>,