view release on metacpan or  search on metacpan

pod/Prima/Window.pod  view on Meta::CPAN

=head1 NAME

Prima::Window - top-level window management

=head1 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;

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

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

=head2 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 often 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 C<::borderIcons> property, and borders by the C<::borderStyle>
property. These operate with set of predefined constants, C<bi::XXX>
and C<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 C<::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
C<sv::XIcon> and C<sv::YIcon> system values, the C<::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 C<::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 C<::originDontCare> and
C<::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 C<::frameOrigin> and C<::frameSize>, which along with C<::origin>
and C<::size> reflect the position and size of a window, but taking into
account the system-dependent decorations.

=head2 Dialog execution

Method of Prima::Window, C<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.