--- name: "Prima" section: "3" platform: "linux" package: "libprima-perl" version: "1.28-1.3+b3" release: "Debian 8 (Jessie)" platforms: ["linux"] url: "https://new.carta.tech/Prima" --- # Prima(3) 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 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. - 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 Prima::noARGV 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 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::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 - 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::DetailedOutline - a multi-column outline 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. - Miscellaneous Prima::faq - frequently asked questions Prima::Const - predefined toolkit constants Prima::EventHook - event filtering Prima::Image::AnimateGIF - animate gif files 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::Tie - tie widget properties to scalars or arrays Prima::Utils - miscellaneous routines Prima::Widgets - miscellaneous widget classes Prima::gp-problems - Graphic subsystem portability issues Prima::X11 - 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 Dmitry Karasik. 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 \, Anton Berezin \, Vadim Belman \,