NAME¶
Prima::Window - top-level window management
SYNOPSIS¶
use Prima;
use Prima::Application;
# this window, when closed, terminated the application
my $main = Prima::MainWindow-> new( text => 'Hello world' );
# this is a modal window
my $dialog = Prima::Dialog->create( size => [ 100, 100 ]);
my $result = $dialog-> execute;
$dialog-> destroy;
run Prima;
DESCRIPTION¶
Prima::Window is a descendant of Prima::Widget class. It deals with top-level
windows, the windows that are specially treated by the system. Its major
difference from Prima::Widget is that instances of Prima::Window can only be
inferior by the screen, not the other windows, and that the system or window
manager add decorations to these - usually menus, buttons and title bars.
Prima::Window provides methods that communicate with the system and hint these
decorations.
USAGE¶
A typical program communicates with the user with aid of widgets, collected upon
one or more top-level windows. Prima::Widget already has all functionality
required for these child-parent operations, so Prima::Window is not special in
respect of widget grouping and relationship. Its usage therefore is
straightforward:
my $w = Prima::Window-> create(
size => [300,300],
text => 'Startup window',
);
There are more about Prima::Window in areas, that it is specifically designed to
- the system window management and the dialog execution.
System window management¶
As noted before, top-level windows are special for the system, not only in their
'look', but also in 'feel': the system adds specific functions to the windows,
aiding the user to navigate through the desktop. The system ofter dictates the
size and position for windows, and some times these rules are hard or even
impossible to circumvent. This document will be long if it would venture to
describe the features of different window management systems, and the task
would be never accomplished - brand new window managers emerge every month,
and the old change their behavior in an unpredictable way. The only golden
rule is to never rely on the behavior of one window manager, and test programs
with at least two.
The Prima toolkit provides simple access to buttons, title bar and borders of a
window. Buttons and title bar are managed by the "::borderIcons"
property, and borders by the "::borderStyle" property. These operate
with set of predefined constants, "bi::XXX" and "bs::XXX",
correspondingly. The button constants can be combined with each other, but not
all combinations may be granted by the system. The same is valid also for the
border constant, except that they can not be combined - the value of
"::borderStyle" is one of the integer constants.
There are other hints that the toolkit can set for a window manager. The system
can be supplied with an icon that a window is bound to; the icon dimensions
are much different, and although can be requested via "sv::XIcon"
and "sv::YIcon" system values, the "::icon" property
scales the image automatically to the closest system-recognizable dimension.
The window icon is not shown by the toolkit, it is usually resides in the
window decorations and sometimes on a task bar, along with the window's name.
The system can be hinted to not reflect the window on the task bar, by setting
the "::taskListed" property to 0.
Another issue is the window positioning. Usually, if no explicit position was
given, the window is positioned automatically by the system. The same is valid
for the size. But some window managers bend it to the extreme - for example,
default CDE setup force the user to set newly created windows' positions
explicitly. However, there is at least one point of certainty. Typically, when
the initial size and/or position of a top-level window are expected to be set
by the system, the "::originDontCare" and "::sizeDontCare"
properties can be set to 1 during window creation. If these set, the system is
asked to size/position a window regarding its own windowing policy. The
reverse is not always true, unfortunately. Either if these properties set to
0, or explicit size or positions are given, the system is hinted to use these
values instead, but this does not always happen. Actually, this behavior is
expected by the user and often does not get even noticed as something special.
Therefore it is a good practice to test a top-level windowing code with
several window managers.
There are different policies about window positioning and sizing; some window
managers behave best when the position is given to the window with the
system-dependent decorations. It is hardly can be called a good policy, since
it is not possible to calculate the derived window coordinates with certainty.
This problem results in that it is impossible to be sure about window position
and size before these are set explicitly. The only, not much efficient help
the toolkit can provide is the property pair "::frameOrigin" and
"::frameSize", which along with "::origin" and
"::size" reflect the position and size of a window, but taking into
account the system-dependent decorations.
Dialog execution¶
Method of Prima::Window, "execute()" brings a window in a modal state
on top of other toolkit windows, and returns after the window is dismissed in
one or another way. This method is special as it is an implicit event loop,
similar to
run Prima;
code. The event flow is not disrupted, but the windows and widgets that do not
belong to the currently executed, the 'modal' window group can not be
activated. There can be many modal windows on top of each other, but only one
is accessible. As an example a message box can be depicted, a window that
prevents the user to work with the application windows until dismissed. There
can be other message boxes on top of each other, preventing the windows below
from operation as well. This scheme is called the 'exclusive' modality.
The toolkit also provides the shared modality scheme, where there can be several
stacks of modal windows, not interfering with each other. Each window stack is
distinct and contains its own windows. An example analogy is when several
independent applications run with modal message boxes being activated. This
scheme, however, can not be achieved with single
execute()-like call
without creating interlocking conditions. The shared model call,
"execute_shared()", inserts the window into the shared modal stack,
activates the window and returns immediately.
The both kinds of modal windows can coexist, but the exclusive windows prevents
the shared from operation; while there are exclusive windows, the shared have
same rights as the usual windows.
The stacking order for these two models is slightly different. A window after
execute() call is set on top of the last exclusive modal window, or, in
other words, is added to the exclusive window stack. There can be only one
exclusive window stack, but many shared window stacks; a window after
execute_shared() call is added to a shared window stack, to the one the
window's owner belongs to. The shared window stacks are rooted in so-called
modal horizons, windows with boolean property "::modalHorizon" set
to "true". The default horizon is "::application".
A window in modal state can return to the normal (non-modal) state by calling
"end_modal()" method. The window is then hidden and disabled, and
the windows below are accessible to the user. If the window was in the
exclusive modal state, the
execute() call is finished and returns the
exit code, the value of "::modalResult" property. There two shortuct
methods that end modal state, setting "::modalResult" to the basic
'ok' and 'not ok' code, correspondingly "ok()" and
"cancel()" methods. Behavior of "cancel()" is identical to
when the user closes the modal window by clicking the system close button,
pressing Escape key, or otherwise cancelling the dialog execution.
"ok()" sets "::modalResult" to "mb::OK",
"cancel()" to "mb::Cancel", correspondingly. There are
more "mb::XXX" constants, but these have no special meaning, any
integer value can be passed. For example, "Prima::MsgBox::message"
method uses these constants so the message window can return up to four
different "mb" codes.
A top-level window can be equipped with a menu bar. Its outlook is
system-dependent, but can be controlled by the toolkit up to a certain level.
The "::menuItems" property, that manages the menu items of a
"::menu" object of Prima::Menu class, arrange the layout of the
menu. The syntax of the items-derived properties is described in Prima::Menu,
but it must be reiterated that menu items contain only hints, not requests for
their exact representation. The same is valid for the color and font
properties, "::menuColorIndex" and "::menuFont".
Only one menu at a time can be displayed in a top-level window, although a
window can be an owner for many menu objects. The key property is
"Prima::Menu::selected" - if a menu object is selected on a widget
or a window object, it refers to the default menu actions, which, in case of
Prima::Window is being displayed as menu bar.
NB: A window can be an owner for several menu objects and still do not have a
menu bar displayed, if no menu objects are marked as selected.
Prima::Dialog¶
Prima::Dialog, a descendant from Prima::Window, introduces no new functionality.
It has its default values adjusted so the colors use more appropriate system
colors, and hints the system that the outlook of a window is to be different,
to resemble the system dialogs on systems where such are provided.
Prima::MainWindow¶
The class is a simple descendant of Prima::Window, which overloads
"on_destroy" notification and calls
"$application->close" inside it. The purpose of declaration of a
separate class for such a trifle difference is that many programs are designed
under a paradigm where these is a main window, which is most 'important' to
the user. As such consruct is used more often than any other, it is considered
an optimization to write
Prima::MainWindow-> create( ... )
rather than
Prima::Window-> create( ..., onDestroy => sub { $::application-> close })
, although these lines are equivalent.
Also, the $::main_window is pointed to a newly created main window.
API¶
Properties¶
- borderIcons INTEGER
- Hints the system about window's decorations, by selecting the combination
of "bi::XXX" constants. The constants are:
bi::SystemMenu - system menu button and/or close button
( usually with icon ) is shown
bi::Minimize - minimize button
bi::Maximize - maximize ( and eventual restore )
bi::TitleBar - window title
bi::All - all of the above
Not all systems respect these hints, and many systems provide more
navigating decoration controls than these.
- borderStyle STYLE
- Hints the system about window's border style, by selecting one of
"bs::XXX" constants. The constants are:
bs::None - no border
bs::Single - thin border
bs::Dialog - thick border
bs::Sizeable - thick border with interactive resize capabilities
"bs::Sizeable" is an unique window mode. If selected, the user can
resize the window, not only by dragging the window borders with the mouse
but by other system-dependent means. The other border styles disallow
interactive resizing.
Not all systems recognize all these hints, although many recognize
interactive resizing flag.
- frameHeight HEIGHT
- Maintains the height of a window, including the window decorations.
- frameOrigin X_OFFSET, Y_OFFSET
- Maintains the left X and bottom Y boundaries of a window's decorations
relative to the screen.
- frameSize WIDTH, HEIGHT
- Maintains the width and height of a window, including the window
decorations.
- frameWidth WIDTH
- Maintains the width of a window, including the window decorations.
- icon OBJECT
- Hints the system about an icon, associated with a window. If OBJECT is
"undef", the system-default icon is assumed.
See also: "ownerIcon"
- menu OBJECT
- Manages a Prima::Menu object associated with a window. Prima::Window can
host many Prima::Menu objects, but only the one that is set in
"::menu" property will be seen as a menu bar.
See also: "Prima::Menu", "menuItems"
- menuColorIndex INDEX, COLOR
- Maintains eight color properties of a menu, associated with a window.
INDEX must be one of "ci::XXX" constants ( see Prima::Widget,
colorIndex section ).
See also: "menuItems", "menuFont", "menu"
- menuColor COLOR
- Basic foreground menu color.
See also: "menuItems", "menuColorIndex",
"menuFont", "menu"
- menuBackColor COLOR
- Basic background menu color.
See also: "menuItems", "menuColorIndex",
"menuFont", "menu"
- menuDark3DColor COLOR
- Color for drawing dark shadings in menus.
See also: "menuItems", "menuColorIndex",
"menuFont", "menu"
- menuDisabledColor COLOR
- Foreground color for disabled items in menus.
See also: "menuItems", "menuColorIndex",
"menuFont", "menu"
- menuDisabledBackColor COLOR
- Background color for disabled items in menus.
See also: "menuItems", "menuColorIndex",
"menuFont", "menu"
- menuFont %FONT
- Maintains the font of a menu, associated with a window.
See also: "menuItems", "menuColorIndex",
"menu"
- menuHiliteColor COLOR
- Foreground color for selected items in menus.
See also: "menuItems", "menuColorIndex",
"menuFont", "menu"
- menuHiliteBackColor COLOR
- Background color for selected items in menus.
See also: "menuItems", "menuColorIndex",
"menuFont", "menu"
- menuItems [ ITEM_LIST ]
- Manages items of a Prima::Menu object associated with a window. The
ITEM_LIST format is same as "Prima::AbstractMenu::items" and is
described in Prima::Menu.
See also: "menu", "menuColorIndex",
"menuFont"
- menuLight3DColor COLOR
- Color for drawing light shadings in menus.
See also: "menuItems", "menuColorIndex",
"menuFont", "menu"
- modalHorizon BOOLEAN
- Reflects if a window serves as root to the shared modal window stack. A
window with "::modalHorizon" set to 1 in shared modal state
groups its children windows in a window stack, separate from other shared
modal stacks. The "::modalHorizon" is therefore useful only when
several shared modal window stacks are needed.
The property also serves as an additional grouping factor for widgets and
windows. For example, default keyboard navigation by tab and arrow keys is
limited to the windows and widgets of a single window stack.
- modalResult INTEGER
- Maintains a custom integer value, returned by "execute()".
Historically it is one of "mb::XXX" constants, but any integer
value can be used. The most useful "mb::" constants are:
mb::OK, mb::Ok
mb::Cancel
mb::Yes
mb::No
mb::Abort
mb::Retry
mb::Ignore
mb::Help
NB: These constants are defined so they can be bitwise-or'ed, and
Prima::MsgBox package uses this feature, where one of its functions
parameters is a combination of "mb::" constants.
- onTop BOOLEAN
- If set, the window is hinted to stay on top of all other windows.
Default value: 0
- ownerIcon BOOLEAN
- If 1, the icon is synchronized with the owner's. Automatically set to 0 if
"::icon" property is explicitly set. Default value is 1, so
assigning an icon to $::application spawns the icon to all windows.
- taskListed BOOLEAN
- If set to 0, hints the system against reflecting existence of a window
into a system task bar, or a top-level window list, or otherwise lower the
window's value before the other windows. If 1, does not hint anything.
Default value: 1
- windowState STATE
- A three-state property, that governs the state of a window. STATE can be
one of three "ws::XXX" constants:
ws::Normal
ws::Minimized
ws::Maximized
There can be more or less, or other window states provided by the system,
but these three were chosen as a 'least common denominator'. The property
can be changed either by explicit set-mode call or by the user. In either
case, a "WindowState" notification is triggered.
The property has three convenience wrappers: "maximize()",
"minimize()" and "restore()".
See also: "WindowState"
Methods¶
- cancel
- A standard method to dismiss a modal window with "mb::Cancel"
result. The effect of calling this method is equal to when the user
selects a 'close window' action with system-provided menu, button or other
tool.
See also: "ok", "modalResult", "execute",
"execute_shared"
- end_modal
- If a window is in modal state, the "EndModal" notification is
activated. Then the window is returned from the modal state, gets hidden
and disabled. If the window was on top in the exclusive modal state, the
last called "execute()" function finishes. If the window was not
on top in the exclusive modal state, the corresponding
"execute()" function finishes after all subsequent
execute() calls are finished.
- execute INSERT_BEFORE = undef
- A window is turned to the exclusive modal state and is put on top of
non-modal and shared-modal windows. By default, if INSERT_BEFORE object is
undef, the window is also put on top of other exclusive-modal windows; if
INSERT_BEFORE is one of the exclusive-modal windows the window is placed
in queue before the INSERT_BEFORE window. The window is showed and
enabled, if necessary, and "Execute" notification is triggered.
The function is returned when a window is dismissed, or if the
system-dependent 'exit'-event is triggered by the user ( the latter case
falls through all execute() calls and terminates "run
Prima;" call, exiting gracefully).
- execute_shared INSERT_BEFORE = undef
- A window is turned to the shared modal state and is put on top of
non-modal windows in the stack of its "::modalHorizon". A window
with "::modalHorizon" set to 1 starts its own stack, independent
of all other window stacks.
By default, if INSERT_BEFORE object is undef, the window is also put on top
of other shared-modal windows in its stack. If INSERT_BEFORE is one of the
shared-modal windows in its stack, the window is placed in queue before
the INSERT_BEFORE window.
The window is showed and enabled, if necessary, and "Execute"
notification is triggered.
The function is returned immediately.
- get_default_menu_font
- Returns the default font for a Prima::Menu class.
- get_modal
- Returns one of three constants, reflecting the modal state of a window:
mt::None
mt::Shared
mt::Exclusive
Value of "mt::None" is 0, so result of get_modal() can be
also treated as a boolean value, if only the fact of modality is needed to
check.
- get_modal_window MODALITY_TYPE = mt::Exclusive, NEXT = 1
- Returns a modal window, that is next to the given window in the modality
chain. MODALITY_TYPE selects the chain, and can be either
"mt::Exclusive" or "mt::Shared". NEXT is a boolean
flag, selecting the lookup direction; if it is 1, the 'upper' window is
returned, if 0, the 'lower' one ( in a simple case when window A is made
modal (executed) after modal window B, the A window is the 'upper' one ).
If a window has no immediate modal relations, "undef" is
returned.
- maximize
- Maximizes window. A shortcut for
"windowState(ws::Maximized)".
- minimize
- Minimizes window. A shortcut for
"windowState(ws::Minimized)".
- ok
- A standard method to dismiss a modal window with "mb::OK"
result. Typically the effect of calling this method is equal to when the
user presses the enter key of a modal window, signaling that the default
action is to be taken.
See also: "cancel", "modalResult", "execute",
"execute_shared"
- restore
- Restores window to normal state from minimized or maximized state. A
shortcut for "windowState(ws::Normal)".
Events¶
- Activate
- Triggered when a window is activated by the user. Activation mark is
usually resides on a window that contains keyboard focus, and is usually
reflected by highlighted system decorations.
The toolkit does not provide standalone activation functions;
"select()" call is used instead.
- Deactivate
- Triggered when a window is deactivated by the user. Window is usually
marked inactive, when it contains no keyboard focus.
The toolkit does not provide standalone de-activation functions;
"deselect()" call is used instead.
- EndModal
- Called before a window leaves modal state.
- Execute
- Called after a window enters modal state.
- WindowState STATE
- Triggered when window state is changed, either by an explicit
"windowState()" call, or by the user. STATE is the new window
state, one of three "ws::XXX" constants.
AUTHOR¶
Dmitry Karasik, <dmitry@karasik.eu.org>.
SEE ALSO¶
Prima, Prima::Object, Prima::Drawable, Prima::Widget.