Man Linux: Main Page and Category List

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;

       or

               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.

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

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

       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.

       modalHorizon BOOLEAN
           A read-only property. Used as a landmark for the lowest-level modal
           horizon.  Always returns 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 red, green, and blue component,
           with intensity range from 0 to 255.

       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.

       size WIDTH, HEIGHT
           A read-only property.

           Returns two integers, width and height of the screen.

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

       wantUnicodeInput BOOLEAN
           Selects if the system is allowed to generate key codes in unicode.
           Returns the effective state of the unicode input flag, which cannot
           be changed if perl or operating system do not support UTF8.

           If 1, "Prima::Clipboard::text" property may return UTF8 text from
           system clipboards is available.

           Default value: 0

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

       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_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::Os2
                       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::GTK2

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

           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

           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, or
           if the exception was signaled. In the latter case, the loop can be
           safely re-started.

       lock
           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 perlpod ) - the string is treated as "manpage/section", where
           ’manpage’ is the file with POD content and ’section’ is the topic
           inside the manpage.

       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
           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() 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 cycle.

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

SEE ALSO

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