Ubuntu Manpage: Prima::Window - top-level window management

Provided by: libprima-perl_1.28-1.4_amd64

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.

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

AUTHOR

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

NAME

SYNOPSIS

DESCRIPTION

USAGE

API

AUTHOR

SEE ALSO