Application - root of widget objects hierarchy


Application - root of widget objects hierarchy


Prima::Application class serves as a hierarchy root for all objects with child-owner relationship. All toolkit objects, existing with non-null owner property, belong in their top-level parental relationship to Prima::Application object. There can be only one instance of Prima::Application class at one time.


Prima::Application class, and its only instance are treated specially throughout the toolkit. The object instance is contained in


scalar, defined in module. The application instance must be created whenever widget and window, or event loop functionality is desired. Usually

   use Prima::Application;

code is enough, but $::application can also be assigned explicitly. The 'use' syntax has advantage as more resistant to eventual changes in the toolkit design. It can also be used in conjunction with custom parameters hash, alike the general create() 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 object classes. This functionality is generally explained in API.

Inherited functionality

Prima::Application is a descendant of Prima::Widget, but it is designed so because their functional outliers are closest to each other. Prima::Application does not strictly conform ( in OO sense ) to any of the built-in classes. It has methods copied from both Prima::Widget and Prima::Window at one time, and the inherited Prima::Widget methods and properties function differently. For example, ::origin, a property from Prima::Widget, is also implemented in Prima::Application, but returns always (0,0), an expected but not much usable result. ::size, on the contrary, returns the extent of the screen in pixels. There are few properties, inherited from Prima::Widget, which return actual, but uninformative results, - ::origin is one of those, but same are ::buffered, ::clipOwner, ::enabled, ::growMode, ::owner and owner-inheritance properties, ::selectable, ::shape, ::syncPaint, ::tabOrder, ::tabStop, ::transparent, ::visible. To this group also belongs ::modalHorizon, a Prima::Window property, but defined for consistency and returning always 1. Other methods and properties, like ::size, that provide different functionality are described in API.

Global functionality

Prima::Application is a wrapper to functionality, that is not related to one or another class clearly. A notable example, paint mode, which is derived from Prima::Drawable class, allows painting on the screen, overwriting the information output by other programs. Although being subject to begin_paint()/end_paint() brackets, this functionality can not be attached to a class-shared API, an therefore considered 'global'. All such functionality is gathered in the Prima::Application class.

These topics enumerated below, related do global function, but occupying more than one method or property - such functions described in API.

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

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

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

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

Result of <get_printer()> method points to an automatically created printer object, responsible for the system-driven printing. Depending on the operating system, it is either Prima::Printer, if the system provides GUI printing capabilities, or generic Prima::PS::Printer, a PostScript document interface.

See the Prima::Printer manpage for details.

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

These are no methods to access these clipboard objects, except fetch() ( or, the indirect name calling ) - the clipboard objects are named after the system clipboard names, which are returned from Prima::Clipboard::get_standard_clipboards.

The default clipboard is named Clipboard, and is accessible via

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


See the Prima::Clipboard manpage 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 part of the toolkit, and resides in Prima::HelpViewer module, any custom help viewing module can be assigned. 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 window, and close_help() closes that window.

System-dependent information
A complex program will need eventually more information than the toolkit provides. Or, knowing the toolkit boundaries in some platforms, the program changes its behavior accordingly. Both these topics are facilitated by extra system information, returned by Prima::Application methods. get_system_value returns a system value for one of sv::XXX constants, so the program can read the system-specific information. As well as get_system_info method, that returns the short description of the system, it is the portable call. All systems return such information. To the contrary, sys_action method is a wrapper to system-dependent functionality, called in non-portable way. This method is never used within the toolkit, and its usage is discouraged, primarily because its options do not serve the toolkit design, so are subject to change and cannot be relied upon.



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 general 'one main window' application layouts.

Default value: 0

Holds the icon object, associated with the application. If undef, a system-provided default icon is assumed. Prima::Window object instances inherit the application icon by default.

insertMode BOOLEAN
A system boolean flag, showing whether text widgets through the system should insert ( 1 ) or overwrite ( 0 ) text on user input. Not all systems provide such unifying functionality.

helpClass STRING
Specifies a class of object, used as a help viewing package. The default value is Prima::HelpViewer.

Run-time changes to the property do not affect the help subsystem until close_help call is made.

helpModule STRING
Specifies a perl module, loaded indirectly when a help viewing call is made via open_help. Used when ::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 close_help call is made.

hintClass STRING
Create-only property.

Specifies a class of widget, used as a hint label.

Default value: Prima::HintWidget

hintColor COLOR
An alias to foreground color property for hint label widget.

hintBackColor COLOR
An alias to background color property for hint label widget.

hintFont %FONT
An alias to font property for hint label widget.

hintPause TIMEOUT
Selects the timeout ( in milliseconds ) before hint label is shown when the mouse pointer hovers over a widget.

modalHorizon BOOLEAN
A read-only property. Used as a landmark for the lowest-level modal horizon. Returns always 1.

palette [ @PALETTE ]
Used only within paint and information modes. Selects solid colors in a system palette, as many as possible. PALETTE is an array of integer triplets, where each is R, G and B component.

printerClass STRING
Create-only property.

Specifies a class of object, used as a printer. The default value is system-dependent, but is either Prima::Printer or Prima::PS::Printer.

printerModule STRING
Create-only property.

Specifies a perl module, loaded indirectly before a printer object of ::printerClass class is created. Used when ::printerClass property is overridden and the new class is contained in a third-party module.

pointerVisible BOOLEAN
Governs the system pointer visibility. If 0, hides the pointer so it is not visible in all system windows. Therefore this property usage must be considered with care.

A read-only property.

Returns two integers, width and height of the screen.

If 1, the toolkit is allowed to show a hint label over a widget. If 0, it is forbidden. In addition to functionality of ::showHint property in Prima::Widget, Prima::Application::showHint is an another layer of hint visibility control - if it is 0, all hint actions are disabled, disregarding ::showHint value of widgets.


add_startup_notification @CALLBACK
CALLBACK is an array of anonymous subs, which is executed when Prima::Application object is created. If the application object is already created during the call, CALLBACKs called immediately.

Useful for add-on packages initialization.

Enters the enabled ( active paint ) state, returns success flag. Once the object is in enabled state, painting and drawing methods can perform write operations on the whole screen.

Enters the information state, returns success flag. The object information state is same as enabled state ( see begin_paint()), except that painting and drawing methods are not permitted to change the screen.

Issues a system termination call, resulting in calling close for all top-level windows. The call can be interrupted by these, and thus canceled. If not canceled, stops the application event loop.

Closes the help viewer window.

Quits the enabled state and returns application object to a normal state.

Quits the information state and returns application object to a normal state.

Returns array of encodings, represented by strings, that are recognized by the system and available in at least one font. Each system provides different sets of encoding strings; the font encodings are not portable.

fonts NAME = '', ENCODING = ''
Returns hash of font hashes ( see the Prima::Drawable manpage, Fonts section ) describing fonts of NAME font family and of ENCODING. If NAME is '' or undef, returns one fonts 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 ( not present in font_encodings result), it is treated as if it was '' or undef.

In the special case, when both NAME and ENCODING are '' or undef, each font metric hash contains element encodings, that points to array of the font encodings, available for the fonts of NAME font family.

Returns object reference to a currently active window, if 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 is generally believed that an active window is the one that has keyboard focus on one of its children widgets.

Returns a title font, that the system uses to draw top-level window captions. The method can be called with a class string instead of an object instance.

Returns width of the system cursor in pixels. The method can be called with a class string instead of an object instance.

Returns the default system font. The method can be called with a class string instead of an object instance.

Returns dimensions of the system scrollbars - width of the standard vertical scrollbar and height of the standard horizon scrollbar. The method can be called with a class string instead of an object instance.

get_default_window_borders BORDER_STYLE = bs::Sizeable
Returns width and height of standard system window border decorations for one of bs::XXX constants. The method can be called with a class string instead of an object instance.

Returns object reference to a currently focused widget, if any, that belongs to the program. If no such widget exists, undef is returned.

Returns Prima::Image object with WIDTH and HEIGHT dimensions filled with graphic content of the screen, copied from X_OFFSET and Y_OFFSET coordinates. If WIDTH and HEIGHT extend beyond the screen dimensions, they are adjusted. If the offsets are outside screen boundaries, or WIDTH and HEIGHT are zero or negative, undef is returned.

Returns a hint label widget, attached automatically to Prima::Application object during startup. The widget is of ::hintClass class, Prima::HintWidget by default.

Returns a printer object, attached automatically to Prima::Application object. The object is of ::printerClass class.

Returns a font the system uses to draw the message text. The method can be called with a class string instead of an object instance.

get_modal_window MODALITY_TYPE = mt::Exclusive, TOPMOST = 1
Returns a modal window, that resides on an end of a modality chain. MODALITY_TYPE selects the chain, and 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 0, the 'lowest' one ( in a simple case when window A is made modal (executed) after modal window B, the A window is the 'topmost' one ).

If a chain is empty undef is returned. In case when a chain consists of just one window, TOPMOST value is apparently irrelevant.

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 ( text field, for example ), and the widget is about to scroll, but the actual scroll is performed after the timeout is expired. The second is the repetitive timeout, - if the dragging condition did not change, the scrolling performs automatically after this timeout. The timeout values are in milliseconds.

Returns a hash with information about the system. The hash result contains the following keys:
One of apc::XXX constants, reflecting the platform. Currently, the list of the supported platforms is:

One of gui::XXX constants, reflecting the graphic user interface used in the system:

The meaning of this field is somewhat vague, and the field might be deprecated in future releases.

Description of graphic user interface, returned as an arbitrary string.

An arbitrary string, representing the operating system software.

An arbitrary string, reflecting the OS version information.

The OS vendor string

The machine architecture string

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

Returns the system integer value, associated with one of 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            - width and height of main icon dimensions, 
   sv::YIcon              acceptable by the system
   sv::XSmallIcon       - width and height of alternate icon dimensions,  
   sv::YSmallIcon         acceptable by the system 
   sv::XPointer         - width and height of mouse pointer icon
   sv::YPointer           acceptable by the system  
   sv::XScrollbar       - width of the default vertical scrollbar
   sv::YScrollbar       - height of the default horizontal scrollbar 
                          ( see C<get_default_scrollbar_metrics()> )
   sv::XCursor          - width of the system cursor
                          ( see C<get_default_cursor_width()> )
   sv::AutoScrollFirst  - the initial and the repetitive 
   sv::AutoScrollNext     scroll timeouts
                          ( see C<get_scroll_rate()>
   sv::InsertMode       - the system insert mode
                          ( see C<::insertMode>
   sv::XbsNone          - widths and heights of the top-level window
   sv::YbsNone            decorations, correspondingly, with borderStyle
   sv::XbsSizeable        bs::None, bs::Sizeable, bs::Single, and
   sv::YbsSizeable        bs::Dialog. 
   sv::XbsSingle          ( see C<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 system accepts color pointer icons.
   sv::CanUTF8_Input    - 1 if system can generate key codes in unicode 
   sv::CanUTF8_Output   - 1 if system can output utf8 text

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. It is usually passed to a program by other IPC means, so it returns the associated widget. If no widget is associated with HANDLE, undef is returned.

get_widget_from_point X_OFFSET, Y_OFFSET
Returns a widget that occupies screen area under (X_OFFSET,Y_OFFSET) coordinates. If no toolkit widget are found, undef is returned.

The main event loop. Called by
  run Prima;

standard code. Returns when the program is about to terminate, or if the exception was signaled. In the latter case, can be safely re-started.

Effectively blocks the graphic output for all widgets. The output can be restored with unlock().

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

sys_action CALL
CALL is an arbitrary string, contained the system service name and the parameters to it. This functionality is non-portable, and should be avoided. The system services provided are not documented and probably subject to change. The actual services can be looked in the toolkit source code under apc_system_action tag.

Unblocks the graphic output for all widgets, previously locked with lock().

An event dispatcher, called from within the event loop. If the event loop can be schematized, then in
   while ( application not closed ) {

draft yield() is the only function, called repeatedly within the event loop. yield() cannot be used to organize event loops, but it can be employed to process stacked system events explicitly, to increase responsiveness of a program, for example, inside a long calculation loop.

The method can be called with a class string instead of an object instance; however, the $::application object must be initialized.


Dmitry Karasik, <>.


Prima, the Prima::Object manpage, the Prima::Widget manpage, the Prima::Window manpage

 Application - root of widget objects hierarchy