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 thePrima::
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
'sdestroy
orclose
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::Widget::pack - Tk::pack geometry manager
Prima::Widget::place - Tk::place geometry manager
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 viewerpodview
( 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>,