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