Prima(3)

📦
version 1.74000 · 5 versions
, in opensuse-leap 16.0

💖 NAME 💖

okay so welcome to Prima(3) — User Contributed Perl Documentation, bestie — and the name says it all: Prima is a Perl graphic toolkit. 🎀✨

✨ SYNOPSIS ✨

here's the little hello-world moment, literally iconic:

        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 🌸

so Prima is a classic 2D GUI toolkit that works under Windows and X11 environments. it 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. plus — not me being dramatic — 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. periodt. 💖

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 👀

okay so the toolkit docs are split into a bunch of sections, and the individual manuals live in these files — bestie, this is your map 🗺️✨

🎀 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 — alternative API for 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 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>,

that's the whole vibe check, bestie 💅 this page is from perl v5.42.0, dated 2024-08-20, and it's literally Prima(3) — mwah 💖🎀

📦 where this page comes from