Prima::Application(3)

📦

version 1.74000 · 5 versions

1.74000 · opensuse-leap 16.0 (latest)
1.74 · epel 9
1.76 · fedora 43
1.78 · fedora 44
1.77 · fedora 44

okay bestie, this is the Prima::Application(3) page from the User Contributed Perl Documentation, and we're folding that manual name in right here at the top so it doesn't have to sit by itself like an awkward header line. 💖 This whole page is about the root of the widget hierarchy — the main-character app object that owns basically everything. ✨

🌸 NAME 🌸

Prima::Application — the root of the widget hierarchy.

💅 DESCRIPTION 💅

The Prima::Application class? She's the hierarchy root for the majority of Prima objects. All toolkit widgets are ultimately owned by the application object. And no cap: there can be only one instance of the Prima::Application class at a time. 👑

🎀 SYNOPSIS 🎀

use Prima qw(Application);
Prima::MainWindow->new();
run Prima;

🌈 USAGE 🌈

okay so the Prima::Application class and its only instance are treated in a special way in the toolkit's paradigm. Its only object instance is stored in the

$::application

scalar, defined in Prima.pm module. The application instance must be created whenever a widget, window, or event loop functionality is needed. Usually the

use Prima::Application;

use Prima qw(Application);

code is enough, but $::application can also be created and assigned explicitly. The 'use' syntax has an advantage as more resistant to eventual changes in the toolkit design. It can also be used in conjunction with custom parameters hash like the new() syntax:

use Prima::Application name => 'Test application', icon => $icon;

In addition to this functionality, Prima::Application is also a wrapper to a set of system functions, not directly related to the object classes. This functionality is generally explained in API.

🧬 Inherited functionality 🧬

Prima::Application is a descendant of Prima::Widget but does not conform strictly ( in the OO sense ) to any of the built-in classes. It has methods from both Prima::Widget and Prima::Window, also, the methods inherited from the Prima::Widget class may work quite differently. For example, the ::origin property from Prima::Widget is also implemented in Prima::Application, but always returns (0,0), an expected but not much usable result. The ::size property, on the contrary, returns the extent of the screen in pixels. There are a few properties inherited from Prima::Widget, which return actual but uninformative results, - ::origin is one of those, but there are several others. The methods and properties, that are like ::size providing different functionality, are described separately in API.

🌍 Global functionality 🌍

Prima::Application is a wrapper to a set of unrelated functions that do not belong to other classes. A notable example, the painting functionality that is inherited from the Prima::Drawable class, allows drawing on the screen, possibly overwriting the graphic information created by the other programs. Although it is still a subject to the begin_paint()/end_paint() brackets, this functionality does not belong to a single object and is considered global.

🎨 Painting 🎨

As stated above, the Prima::Application class provides an interface to the on-screen painting. This mode is triggered by the begin_paint()/end_paint() methods, while the other pair, begin_paint_info()/end_paint_info() triggers the information mode. This three-state paint functionality is more thoroughly described in Prima::Drawable.

The painting on the screen surfaces under certain environments (XQuartz, XWayland) is either silently ignored or results in an error. There, begin_paint may return a false value (begin_paint_info though always true).

💡 Hints 💡

$::application hosts a special Prima::HintWidget class object, accessible via get_hint_widget(), but with its color and font functions aliased ( see ::hintColor, ::hintBackColor, ::hintFont ).

This widget serves as a hint label, floating over other widgets if the mouse pointer hovers longer than ::hintPause milliseconds.

Prima::Application internally manages all of the hint functionality. The hint widget itself, however, can be replaced before the application object is created, using the ::hintClass create-only property.

🖨️ Printer 🖨️

The result of the get_printer method points to an automatically created printer object, responsible for the system printing. Depending on the operating system, it is either Prima::Printer, if the system provides GUI printing capabilities, or generic Prima::PS::Printer, the PostScript/PDF document interface.

See Prima::Printer for details.

📋 Clipboard 📋

$::application hosts a set of Prima::Clipboard objects created automatically to reflect the system-provided clipboard IPC functionality. Their number depends on the system, - under the X11 environment, there are three clipboard objects, and one under Win32.

There are no specific methods to access these clipboard objects, except bring() ( or the indirect name call ); the clipboard objects are named after the system clipboard names, which are returned by the Prima::Clipboard::get_standard_clipboards method.

The default clipboard is named Clipboard, and is accessible via the

my $clipboard = $::application-> Clipboard;

call.

See Prima::Clipboard for details.

📖 Help subsystem 📖

The toolkit has a built-in help viewer, that understands perl's native POD ( plain old documentation ) format. Whereas the viewer functionality itself is a part of the toolkit that resides in the Prima::HelpViewer module, any custom help viewing module can be assigned. The create-only Prima::Application properties ::helpClass and ::helpModule can be used to set these options.

Prima::Application provides two methods for communicating with the help viewer window: open_help() opens a selected topic in the help window, and close_help() closes the window.

🖥️ System-dependent information 🖥️

A complex program will need eventually more information than the toolkit provides. Knowing the toolkit boundaries in some platforms, the program may change its behavior accordingly. Both these topics are facilitated by extra system information returned by Prima::Application methods. The get_system_value method returns a system-defined value for each of the sv::XXX constants, so the program can read the system-specific information. Another method get_system_info returns the short description of the system that augments perl's $^O variable.

The sys_action method is a wrapper to system-dependent functionality that is called in a non-portable way. This method is rarely used in the toolkit, its usage is discouraged, primarily because its options do not serve the toolkit design, its syntax is subject to changes, and cannot be relied upon.

🚨 Exceptions and signals 🚨

By default Prima doesn't track exceptions caused by die, warn, and signals. Currently, it is possible to enable a GUI dialog tracking the die exceptions, by either operating the boolean guiException property or using the

use Prima qw(sys::GUIException)

syntax.

If you need to track signals or warnings you may do so by using standard perl practices. It is though not advisable to call Prima interactive methods directly inside signal handlers but use a minimal code instead. F.ex. code that would ask whether the user wants to quit would look like this:

use Prima qw(Utils MsgBox);
$SIG{INT} = sub {
   Prima::Utils::post( sub {
       exit if message_box("Got Ctrl+C", "Do you really want to quit?", mb::YesNo) == mb::Yes;
   });
};

and if you want to treat all warnings as potentially fatal, like this:

use Prima qw(Utils MsgBox);
$SIG{__WARN__} = sub {
   my ($warn, $stack) = ($_[0], Carp::longmess);
   Prima::Utils::post( sub {
       exit if $::application && Prima::MsgBox::signal_dialog("Warning", $warn, $stack) == mb::Abort;
   });
};

See also: Die, "signal_dialog" in Prima::MsgBox

🔥 API 🔥

💖 Properties 💖

autoClose BOOLEAN — if set to 1, issues close() after the last top-level window is destroyed. Does not influence anything if set to 0.

This feature is designed to help with generic 'one main window' application layouts.

Default value: 0

guiException BOOLEAN — if set to 1, when a die exception is thrown, displays a system message dialog, allowing the user to choose the course of action -- to stop, to continue, etc.

Is 0 by default.

Note that the exception is only handled inside the Prima::run and Prima::Dialog::execute calls; if there is a call to f ex Prima::Window::execute or a manual event loop run with yield, the signal dialog will not be shown. One needs to explicitly call $::application->notify(Die => $@) and check the notification result to decide whether to propagate the exception or not.

The alternative syntax for setting guiException to 1 is the

use Prima::sys::GUIException;

use Prima qw(sys::GUIException);

statement.

If for some reason an exception is thrown during dialog execution, it will not be handled by Prima but by the current $SIG{__DIE__} handler.

See also: "signal_dialog" in Prima::MsgBox .

icon OBJECT — holds the icon object associated with the application. If undef, the system-provided default icon is assumed. Prima::Window objects inherit this application icon by default.
insertMode BOOLEAN — the system boolean flag signaling whether text widgets through the system should insert ( 1 ) or overwrite ( 0 ) text on user input. Not all systems provide the global state of the flag.
helpClass STRING — specifies the class of the object used as the help viewing package. The default value is Prima::HelpViewer. Run-time changes to the property do not affect the help subsystem until a call to close_help is made.
helpModule STRING — specifies the perl module loaded indirectly when a help viewing call is made via the open_help method. Used when the ::helpClass property is overridden and the new class is contained in a third-party module. Run-time changes to the property do not affect the help subsystem until a call to close_help is made.
hintClass STRING — create-only property.

Specifies the class of the widget used as the hint label.

Default value: Prima::HintWidget

hintColor COLOR — the alias to the foreground color property of the hint label widget.
hintBackColor COLOR — the alias to the background color property of the hint label widget.
hintFont %FONT — the alias to the font property of the hint label widget.
hintPause TIMEOUT — sets how long, in milliseconds, the pointer has to just chill hovering over a widget before the hint label pops up. Basically the patience setting of your app 🫶
language STRING — by default this holds the UI language, which gets deduced either from the $ENV{LANG} environment variable (on unix) or from a system default setting (on win32). Change it and the textDirection property gets updated too, slay 🦋

✨ EVENTS ✨

Clipboard $CLIPBOARD, $ACTION, $TARGET — with (the only implemented) $ACTION copy, this fires whenever another application requests clipboard data in the format $TARGET. it's handled internally so image pasting through the clipboard can be optimised. here's the situation: clipboard pasting semantics in Prima are such that data has to be supplied to the clipboard in advance, before another application can request it — so which format do you even pick?? rather than encoding an image or other complex data in all possible formats, you do it on demand in whatever format the other application wants, and this notification is your girl 💅

only implemented for X11.

CopyImage $CLIPBOARD, $IMAGE — the notification stores $IMAGE in the clipboard 🖼️
CopyText $CLIPBOARD, $TEXT — the notification stores $TEXT in the clipboard 📝
Die $@, $STACK — called when an exception occurs inside the event loop Prima::run. by default it consults the guiException property, and if that's set, it displays the system message dialog letting the user decide what to do next 🙈
Idle — called when the event loop has handled all pending events and is about to go to sleep waiting for more. nap time bestie 😴
PasteImage $CLIPBOARD, $$IMAGE_REF — the notification queries $CLIPBOARD for image content and stores it in $$IMAGE_REF. the default action is that the 'Image' format is queried. on unix, encoded formats 'image/bmp', 'image/png' etc are queried if the default 'Image' is not found 🦋

the PasteImage mechanism can read images from the clipboard in the GTK environment.

PasteText $CLIPBOARD, $$TEXT_REF — the notification queries $CLIPBOARD for text content and stores it in the $$TEXT_REF scalar. its default action is that only the 'Text' format is queried if wantUnicodeInput is unset. otherwise, the 'UTF8' format is queried first 🌈

the PasteText mechanism exists to make defining text unicode/ascii conversion between clipboard and standard widgets easy, in a unified way. lowkey genius.

✨ METHODS ✨

add_startup_notification @CALLBACK — CALLBACK is an array of anonymous subs, and all of them get executed when the Prima::Application object is created. if the application object already exists by the time you call this, the CALLBACKs are called immediately, no waiting around 💖

super useful for initializing add-on packages.

begin_paint — enters the enabled (active paint) state and returns the success flag. once the object is in the enabled state, painting and drawing methods can perform drawing operations on the whole screen 🎨
begin_paint_info — enters the information state and returns the success flag. the object's information state is the same as the enabled state (see begin_paint), except that painting and drawing methods are not permitted to change the screen.
close — issues a system termination call, which results in calling the close method for all top-level windows. that call can be interrupted by those windows and effectively canceled. if it's not canceled, it stops the application event loop 🚪
close_help — closes the help viewer window.
end_paint — quits the enabled state and returns the application object to the normal state.
end_paint_info — quits the information state and returns the application object to the normal state.
font_encodings — returns an array of encodings as strings, the ones the system recognizes and that are available for at least one font. every system hands you a different set of encoding strings, so heads up: font encodings are not portable 😭
fonts NAME = '', ENCODING = '' — returns a hash of font hashes (see Fonts in Prima::Drawable) describing fonts of the NAME font family and of the ENCODING text encoding. if NAME is '' or undef, it returns one font hash for each of the font families that match the ENCODING string. if ENCODING is '' or undef, no encoding match is performed. if ENCODING is not valid (i.e. not present in the font_encodings result), it's treated as if it were '' or undef 🧚

in the special case where both NAME and ENCODING are '' or undef, each font metric hash contains the element encodings, which points to an array of the font encodings available for the fonts of the NAME font family. so much info, we love to see it.

get_active_window — returns the object reference to the currently active window, if there is any, that belongs to the program. if no such window exists, undef is returned.

the exact definition of 'active window' is system-dependent, but it's generally believed that an active window is the one that has keyboard focus on one of its children widgets 👑

get_caption_font — returns the title font the system uses to draw top-level window captions. you can call this method with a class string instead of an object instance 🌸
get_default_cursor_width — returns the width of the system cursor in pixels. can be called with a class string instead of an object instance.
get_default_font — returns the default system font. can be called with a class string instead of an object instance ✨
get_default_scrollbar_metrics — returns the dimensions of the system scrollbars: the width of the standard vertical scrollbar and the height of the standard horizon scrollbar. can be called with a class string instead of an object instance.
get_dnd_clipboard — returns the predefined special clipboard used as a proxy for drag-and-drop interactions 🫶

See also: Widget/Drag and drop, Clipboard/is_dnd.

get_default_window_borders BORDER_STYLE = bs::Sizeable — returns the width and height of the standard system window border decorations for one of the bs::XXX constants. can be called with a class string instead of an object instance.
get_focused_widget — returns the object reference to the currently focused widget, if there is any, that belongs to the program. if no such widget exists, undef is returned.
get_fullscreen_image — syntax sugar for grabbing the whole screen, like so:

$::application->get_image( 0, 0, $::application->size)

(MacOSX/XQuartz note: get_image() does not grab all screen bits, but get_fullscreen_image does if Prima is compiled with the Cocoa library 🍓)

get_hint_widget — returns the hint label widget, which gets attached automatically to the Prima::Application object during startup. the widget is of the ::hintClass class, Prima::HintWidget by default 💜
get_image X_OFFSET, Y_OFFSET, WIDTH, HEIGHT — bestie, this is the screen-grab icon 💅 It returns a Prima::Image object with WIDTH and HEIGHT dimensions, filled with the graphic content of the screen copied from the X_OFFSET and Y_OFFSET coordinates. If WIDTH and HEIGHT extend beyond the screen dimensions, they get adjusted. If the offsets are outside the screen boundaries, or if WIDTH and HEIGHT are zero or negative, undef is returned.

Note: when you're running on MacOSX under XQuartz, XQuartz does not give access to the whole screen, so this function won't be able to grab the top-level menu bar 😭 That exact problem is handled by the get_fullscreen_image method.

get_indents — returns 4 integers that correspond to extensions of eventual desktop decorations that the windowing system may present on the left, bottom, right, and top edges of the screen. For example, on win32 this reports the size of the part of the screen that the windows taskbar may occupy, if any 🪟
get_printer — returns the printer object attached automatically to the Prima::Application object. That object is an instance of the ::printerClass class 🖨️✨
get_message_font — returns the font the system uses to draw the message text. This method can be called with a class string instead of an object instance 🎀
get_modal_window MODALITY_TYPE = mt::Exclusive, TOPMOST = 1 — returns the modal window that resides on an end of the modality chain. MODALITY_TYPE selects the chain, and it can be either mt::Exclusive or mt::Shared. TOPMOST is a boolean flag selecting the lookup direction: if it is 1, the 'topmost' window is returned; if it is 0, the 'lower-most' one is returned (in a simple case when window A is made modal / executed after modal window B, the A window is the 'topmost' one 👑).

If the chain is empty, undef is returned. In case the chain consists of just one window, the TOPMOST value is irrelevant 💁‍♀️

get_monitor_rects — returns a set of rectangles in the format of (X,Y,WIDTH,HEIGHT) identifying monitor layouts 🖥️🖥️
get_scroll_rate — returns two integer values of two system-specific scrolling timeouts. The first is the initial timeout that is applied when the user drags the mouse from a scrollable widget (a text field, for example), and the widget is about to scroll, but the actual scroll is performed after the timeout has expired. The second value is the repetitive timeout: if the dragging condition did not change, the scrolling performs automatically after this timeout. The timeout values are in milliseconds ⏱️
get_system_info — returns a hash with the following keys containing information about the system:
- apc — one of the apc::XXX constants reporting the platform the program is running on. Currently, the list of supported platforms is one of these two:
  - apc::Win32
  - apc::Unix
- gui — one of the gui::XXX constants reporting the graphic user interface used in the system:
  - gui::Default
  - gui::Windows
  - gui::XLib
  - gui::GTK
- guiDescription — description of the graphic user interface, returned as an arbitrary string.
- guiLanguage — the preferred language of the interface, returned as an ISO 639 code.
- system — an arbitrary string representing the operating system software.
- release — an arbitrary string containing the OS version information.
- vendor — the OS vendor string.
- architecture — the machine architecture string.

The method can be called with a class string instead of an object instance 🧚

get_system_value — returns the system integer value associated with one of the sv::XXX constants. The constants are:
- sv::YMenu — height of menu bar in top-level windows.
- sv::YTitleBar — height of title bar in top-level windows.
- sv::XIcon, sv::YIcon — width and height of main icon dimensions acceptable by the system.
- sv::XSmallIcon, sv::YSmallIcon — width and height of alternate icon dimensions acceptable by the system.
- sv::XPointer, sv::YPointer — width and height of mouse pointer icon acceptable by the system.
- sv::XScrollbar — width of the default vertical scrollbar.
- sv::YScrollbar — height of the default horizontal scrollbar (see get_default_scrollbar_metrics()).
- sv::XCursor — width of the system cursor (see get_default_cursor_width()).
- sv::AutoScrollFirst, sv::AutoScrollNext — the initial and the repetitive scroll timeouts (see get_scroll_rate()).
- sv::InsertMode — the system insert mode (see insertMode).
- sv::XbsNone, sv::YbsNone — width and height of the top-level window decorations with borderStyle bs::None (see get_default_window_borders()).
- sv::XbsSizeable, sv::YbsSizeable — width and height of the top-level window decorations with borderStyle bs::Sizeable (see get_default_window_borders()).
- sv::XbsSingle, sv::YbsSingle — width and height of the top-level window decorations with borderStyle bs::Single (see get_default_window_borders()).
- sv::XbsDialog, sv::YbsDialog — width and height of the top-level window decorations with borderStyle bs::Dialog (see get_default_window_borders()).
- sv::MousePresent — 1 if the mouse is present, 0 otherwise.
- sv::MouseButtons — number of the mouse buttons.
- sv::WheelPresent — 1 if the mouse wheel is present, 0 otherwise.
- sv::SubmenuDelay — timeout (in ms) before a sub-menu shows on an implicit selection.
- sv::FullDrag — 1 if the top-level windows are dragged dynamically, 0 with marquee mode.
- sv::DblClickDelay — mouse double-click timeout in milliseconds.
- sv::ShapeExtension — 1 if Prima::Widget::shape functionality is supported, 0 otherwise.
- sv::ColorPointer — 1 if the system accepts color pointer icons.
- sv::CanUTF8_Input — 1 if the system can generate key codes in unicode.
- sv::CanUTF8_Output — 1 if the system can output utf8 text.
- sv::CompositeDisplay — 1 if the system uses double-buffering and alpha composition for the desktop, 0 if it doesn't, -1 if unknown.
- sv::LayeredWidgets — 1 if the system supports layering.
- sv::FixedPointerSize — 0 if the system doesn't support arbitrarily sized pointers and will resize custom icons to the system size.
- sv::MenuCheckSize — width and height of default menu check icon.
- sv::FriBidi — 1 if Prima is compiled with libfribidi and full bidi unicode support is available.
- sv::Antialias — 1 if the system supports antialiasing and alpha layer for primitives.
- sv::LibThai — 1 if Prima is compiled with libthai.

The method can be called with a class string instead of an object instance 🌸

get_widget_from_handle HANDLE — HANDLE is an integer value of a toolkit widget handle as used in the underlying GUI level; for example, it is a HWND value on win32. It is usually passed to the program by other IPC means, so that the method can return the associated widget. If no widget is associated with HANDLE, undef is returned 🔍
get_widget_from_point X_OFFSET, Y_OFFSET — returns the widget that occupies the screen area under the (X_OFFSET,Y_OFFSET) coordinates. If no toolkit widgets are found, undef is returned 📍
go — the main event loop. Called by the standard code:

run Prima;

It returns when the program is about to terminate, if stop was called, or if an exception was signaled. In the latter two cases, the loop can be safely restarted 🔁

lock — effectively blocks the graphic output for all widgets. The output can be restored with unlock() 🔒
load_font FONTNAME — registers a font resource in the system-specific format. The resource is freed after the program ends.

Notes for win32: to add a font whose information comes from several resource files, point FONTNAME to a string with the file names separated by a | — for example, abcxxxxx.pfm | abcxxxxx.pfb.

Notes for unix: available only when Prima is compiled with fontconfig and Xft.

Returns the number of the font resources added 🔤✨

open_help TOPIC — opens the help viewer window with the TOPIC string in the link POD format (see perlpod). The string is treated as manpage/section, where 'manpage' is the file with POD content and 'section' is the topic inside the manpage.

Alternatively, it can handle the syntax in the form of file://path|section, where path is the file with the pod content and section is an optional pod section within the file 📖🦋

stop — stops the event loop. The loop can be started again 🛑
sync — synchronizes all pending requests where there are any. It is an effective XSync(false) on X11, and it is a no-op otherwise 🔄
sys_action CALL — CALL is an arbitrary string of the system service name and the parameters to it. This functionality is non-portable, and its usage should be avoided. The system services provided are not documented and are subject to change. The actual services can be looked at in the toolkit source code under the apc_system_action tag ⚠️
unlock — unlocks the graphic output for all widgets previously locked with lock() 🔓
yield $wait_for_event=0 — an event dispatcher, called from within the event loop. If the event loop can be schematized, then in this code:

while ( application not closed ) {
        yield
}

yield() is the only function called repeatedly inside the loop. The yield(0) call shouldn't be used to organize event loops, but it can be employed to process stacked system events explicitly, to increase the responsiveness of a program — for example, inside a long calculation cycle 💫

Okay so yield(1)? That one's adapted exactly for when you're implementing event loops externally, like off in your own little world 🌀 It does the same thing as yield(0), except — and this is the moment — if there are no events waiting, it sleeps until at least one shows up, processes it, and then returns 😴➡️⚡ So it's the patient bestie of the two.

The return value is 0 if the application doesn't need any more event processing, which happens because it's shutting down 🛑 So the corresponding code is literally:

while ( yield(1)) {
    ...
}

But — and I need you to hear me on this one — this call cannot be used for increasing UI responsiveness inside tight calculation loops 🚫 Like, don't try to sneak it into your number-crunching to make the window feel snappy, that's not what she's for, no cap 💀

Oh and plot twist: the method can be called with a class string instead of an object instance 🎀 However, the $::application object must be initialized. Non-negotiable, bestie ✨

👑 AUTHOR

Dmitry Karasik, <dmitry@karasik.eu.org> 💖 (shoutout to the icon who made all this happen, we stan fr fr 🫶)

🌸 SEE ALSO

Prima
Prima::Object
Prima::Widget
Prima::Window

Go read those next, they're the whole ecosystem and you're gonna want the full tour 🦋

And that's the page!! 🎉 This little gem is from perl v5.42.0, dated 2024-08-20, and it's the Prima::Application(3) manpage — go forth and slay your event loop 💅✨

📦 where this page comes from

opensuse-leap 16.0: perl-Prima 1.74000-bp160.1.13 · AGPL-3.0-only AND BSD-2-Clause
opensuse-leap 16.0: perl-Prima 1.74000-bp160.1.13 · AGPL-3.0-only AND BSD-2-Clause
opensuse-leap 16.0: perl-Prima 1.74000-bp160.1.13 · AGPL-3.0-only AND BSD-2-Clause
opensuse-leap 16.0: perl-Prima 1.74000-bp160.1.13 · AGPL-3.0-only AND BSD-2-Clause
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms