NAME

Prima::Application - root of widget objects hierarchy

DESCRIPTION

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 by their top-level parental relationship to Prima::Application object. There can be only one instance of Prima::Application class at a time.

SYNOPSIS

        use Prima;
        use Prima::Application;

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

USAGE

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

        $::application

scalar, defined in Prima.pm 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", Prima::Window class 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 graphic information created by the other programs. Although being subject to begin_paint()/end_paint() brackets, this functionality can not be attached to a class-shared API, an therefore is considered global. All such functionality is gathered in the Prima::Application class.

These topics enumerated below, related to the global scope, but occupying more than one method or property - such functions described in "API".

Painting

As stated above, Prima::Application provides interface to the 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 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" will return a false value ("begin_paint_info" though returns true).

Hint

$::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.

Printer

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, the PostScript document interface.

See Prima::Printer for details.

Clipboard

$::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.

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 by Prima::Clipboard::get_standard_clipboards.

The default clipboard is named Clipboard, and is accessible via

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

code.

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 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 help window, and close_help() closes the 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. 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, are 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

   use Prima qw(sys::GUIException)

syntax.

If you need to track signals or warnings you may do so just by using standard perl practices. It is though not advisable to call Prima interactive methods inside signals, but use minimal code in the signal handler instead. F.ex. code that would ask whether the user really 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 general '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 called inside the "Prima::run" call; if there is a call to f ex "Prima::Dialog::execute" or a manual event loop run with "yield", the 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.

Alternative syntax for setting "guiException" to 1 is a

   use Prima::sys::GUIException;

   use Prima qw(sys::GUIException);

statement.

If for some reason an exception will be thrown during the dialog, 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", 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 the global state of the flag.

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 the hint label.

Default value: Prima::HintWidget

hintColor COLOR

An alias to foreground color property for the hint label widget.

hintBackColor COLOR

An alias to background color property for the hint label widget.

hintFont %FONT

An alias to font property for the hint label widget.

hintPause TIMEOUT

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

language STRING

By default contains user interface language, deduced either from $ENV{LANG} or GUI default. When changed, updates "textDirection" propertly.

Events

Clipboard $CLIPBOARD, $ACTION, $TARGET: With (the only implemented) $ACTION copy, is called whenever another application requests clipboard data in format $TARGET. This notification is handled internally to optimize image pasting through the cliboard. Since the clipboard pasting semantics in Prima is such that data must be supplied to the clipboard in advance, before another application can request it, there is a problem which format to use. In order to not encode an image or other complex data in all possible formats but do that on demand and in the format the other application wants, this notification can be used.
Only implemented for X11.
CopyImage $CLIPBOARD, $IMAGE: The notification stores $IMAGE in clipboard.
CopyText $CLIPBOARD, $TEXT: The notification stores $TEXT in clipboard.
Die $@, $STACK: Called when an exception occurs inside the event loop "Prima::run". By default, consults the "guiException" property, and if it is set, displays the system message dialog allowing the user to decide when to do next.
Idle: Called when the event loop handled all pending events, and is about to sleep waiting for more.
PasteImage $CLIPBOARD, $$IMAGE_REF: The notification queries $CLIPBOARD for image content and stores in $$IMAGE_REF. Default action is that '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 is devised to read images from clipboard in GTK environment.
PasteText $CLIPBOARD, $$TEXT_REF: The notification queries $CLIPBOARD for text content and stores in $$TEXT_REF. Default action is that 'Text' format is queried if "wantUnicodeInput" is unset. Otherwise, 'UTF8' format is queried beforehand.
The "PasteText" mechanism is devised to ease defining text unicode/ascii conversion between clipboard and standard widgets, in a standard way.

Methods

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.

begin_paint

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.

begin_paint_info

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.

close

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.

close_help

Closes the help viewer window.

end_paint

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

end_paint_info

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

font_encodings

Returns array of encodings, represented by strings, that are recognized by the system and available for 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 "Fonts" in Prima::Drawable ) 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.

get_active_window

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.

get_caption_font

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.

get_default_cursor_width

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

get_default_font

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

get_default_scrollbar_metrics

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_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 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.

get_focused_widget

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

get_fullscreen_image

Syntax sugar for grabbing whole screen as in

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

(MacOSX/XQuartz: get_image() does not grab all screen bits, but "get_fullscreen_image" does (given Prima is compiled with Cocoa library)).

get_hint_widget

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

get_image X_OFFSET, Y_OFFSET, WIDTH, HEIGHT

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.

Note: When running on MacOSX under XQuartz, the latter does not give access to the whole screen, so the function will not be able to grab top-level menu bar. This problem is addressed in "get_fullscreen_image".

get_indents

Returns 4 integers that corresponds 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, for win32 this reports the size of the part of the scraan that windows taskbar may occupies, if any.

get_printer

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

get_message_font

Returns the 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 the 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.

get_monitor_rects

Returns set of rects in format [X,Y,WIDTH,HEIGHT] identifying monitor configurations. Currently works under X11 only.

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 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.

get_system_info

Returns a hash with information about the system. The hash result contains the following keys:

apc

One of "apc::XXX" constants, reflecting the platform. Currently, the list of the supported platforms is:

        apc::Win32
        apc::Unix

gui

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

        gui::Default
        gui::PM
        gui::Windows
        gui::XLib
        gui::GTK

guiDescription

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

guiLanguage

Preferred language of the interface, returned as an ISO 639 code.

system

An arbitrary string, representing the operating system software.

release

An arbitrary string, reflecting 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 "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 get_default_scrollbar_metrics() )
        sv::XCursor          - width of the system cursor
                                                                ( see get_default_cursor_width() )
        sv::AutoScrollFirst  - the initial and the repetitive
        sv::AutoScrollNext     scroll timeouts
                                                                ( see get_scroll_rate() )
        sv::InsertMode       - the system insert mode
                                                                ( see 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 get_default_window_borders() )
        sv::YbsSingle
        sv::XbsDialog
        sv::YbsDialog
        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
        sv::CompositeDisplay - 1 if system uses double-buffering and alpha composition for the desktop,
                               0 if it doesn't, -1 if unknown
        sv::LayeredWidgets   - 1 if system supports layering
        sv::FixedPointerSize - 0 if system doesn't support arbitrary 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 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. It is usually passed to the 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 the widget that occupies screen area under (X_OFFSET,Y_OFFSET) coordinates. If no toolkit widget are found, "undef" is returned.

go

The main event loop. Called by

run Prima;

standard code. Returns when the program is about to terminate, if "stop" was called, or if the exception was signaled. In the latter two cases, the loop can be safely re-started.

lock

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

load_font FONTNAME

Registers font resource in system-specific format. The resource is freed after prgram 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 number of font resources added.

open_help TOPIC

Opens the help viewer window with TOPIC string in 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 can handle the syntax in 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

Breaks the event loop. The loop can be started again by "go" thereafter.

sync

Synchronizes all pending requests where there are any. Is an effective XSync(false) on X11, and 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 subject to change. The actual services can be looked in the toolkit source code under apc_system_action tag.

unlock

Unblocks 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

        while ( application not closed ) {
                yield
        }

draft yield() is the only function, called repeatedly within the event loop. yield(0) call shouldn't 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 cycle.

yield(1) though is adapted exactly for external implementation of event loops; it does exactly the same as yeild(0), but if there are no events, it sleeps until there comes at least one, processes it, and then returns. The return value is 0 if the application doesn't need more event processins, because of shutting down. The corresponding code will be

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

but in turn, this call cannot be used for UI responsiveness inside tight cycles.

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

AUTHOR

Dmitry Karasik, <dmitry@karasik.eu.org>.