Prima::Application - root of widget objects hierarchy |
Prima::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 by their top-level parental relationship to Prima::Application object. There can be only one instance of Prima::Application class at a time.
use Prima; use Prima::Application;
or
use Prima qw(Application);
Prima::MainWindow-> create();
run Prima;
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.
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.
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.
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.
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.
See the Prima::Printer manpage for details.
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 the Prima::Clipboard manpage for details.
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.
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.
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
undef
, a system-provided default icon is assumed.
Prima::Window object instances inherit the application
icon by default.
Run-time changes to the property do not affect the help
subsystem until close_help
call is made.
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.
Specifies a class of widget, used as the hint label.
Default value: Prima::HintWidget
Specifies a class of object, used as a printer.
The default value is system-dependent, but is either
Prima::Printer
or Prima::PS::Printer
.
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.
Returns two integers, width and height of the screen.
::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.
If 1, Prima::Clipboard::text
property may return UTF8 text
from system clipboards is available.
Default value: 0
$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.
$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.
Useful for add-on packages initialization.
begin_paint()
),
except that painting and drawing methods are not permitted to change
the screen.
close
for all top-level windows. The call can be interrupted by these,
and thus canceled. If not canceled, stops the application event loop.
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.
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.
bs::XXX
constants.
The method can be called with a class string instead of an object instance.
undef
is returned.
::hintClass
class, Prima::HintWidget by
default.
undef
is returned.
::printerClass
class.
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.
apc::XXX
constants, reflecting the platform.
Currently, the list of the supported platforms is:
apc::Os2 apc::Win32 apc::Unix
gui::XXX
constants, reflecting the graphic
user interface used in the system:
gui::Default gui::PM gui::Windows gui::XLib gui::GTK2
The method can be called with a class string instead of an object instance.
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 for the desktop
The method can be called with a class string instead of an object instance.
undef
is returned.
undef
is returned.
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.
unlock()
.
XSync(false)
on X11, and is a no-op otherwise.
lock()
.
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.
Dmitry Karasik, <dmitry@karasik.eu.org>.
Prima, the Prima::Object manpage, the Prima::Widget manpage, the Prima::Window manpage
Prima::Application - root of widget objects hierarchy |