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

The Prima::Window class is a descendant of the Prima::Widget class. It represents the top-level windows that are treated specially by the system. The class's major difference from Prima::Widget is that instances of Prima::Window cannot reside inside of other windows and that the system or the window manager adds decorations to these - title bar, menus, and buttons. Prima::Window provides methods that communicate with the system and access these decorations.

USAGE

A typical program communicates with the user with the help of various widgets collected under one or more top-level windows. The creation of a Prima::Window object is straightforward:

   my $w = Prima::Window-> new(
       size => [300,300],
       text => 'Startup window',
   );

System window management

The top-level windows are special not only in their 'look', but also in 'feel': the system adds specific functions to the windows, aiding the user with the navigation through the desktop. The system often dictates the size and position of the newly created windows, and sometimes these rules are hard or even impossible to circumvent. This document would be quite long if it would venture off to describe the specificities of various window management systems, and it would never be complete - new window managers emerge every year, and the old ones unpredictable change their behavior. Therefore a word of advice: do not rely on the behavior of one window manager, test programs on at least two.

The Prima toolkit provides simple access to the buttons, title bar, and borders of the window. The buttons and title bar are managed by the ::borderIcons property, and borders by the ::borderStyle property. These properties operate with a set of the predefined constants bi::XXX and bs::XXX, correspondingly. The button constants can be combined bitwise, but not all combinations may be realized by the system. The same is valid also for the border constants, except that they cannot be combined; the value of the ::borderStyle property contains a single bs::XXX constant.

There are other requests that the toolkit can ask from the window manager. The system can be supplied with the icon that the window is shown with together. The system icon dimensions can differ from system to system, and although they can be requested via the sv::XIcon and sv::YIcon system values, the ::icon property scales the image automatically to the closest size the system can recognize. The window icon is not shown by the toolkit itself, it usually resides in the window decorations and sometimes on the taskbar, along with the window's name. The system can be requested to not add the window to the taskbar, by setting the ::taskListed property to 0.

Another issue is the window positioning. Usually, if no explicit position is given, the window is positioned automatically by the system. The same is valid for the size. But some window managers bend that to the extreme - for example, the default CDE setup forces the user to set positions of the newly created windows explicitly. There is at least one point of certainty, however. Typically, when the initial size and/or position of the top-level window are expected to be set by the system, the ::originDontCare and ::sizeDontCare properties can be set to 1 during the window creation. If these are set, the system is requested to set the size and/or the position of the window according to its policy. The reverse is not always true, unfortunately. When either of these properties is set to 0, or the explicit size or position is given, the system is requested to use these values instead, but this does not always succeed from the program's point of view. Such behavior however is expected from the user's perspective and often does not even get noticed as something special. Therefore it is a good practice to test top-level windowing code on several window managers.

Different policies define that define window positioning and sizing. Some window managers behave best when the position is given to the window including the system-dependent decorations. This hardly can be called a good policy, since it is not possible to calculate the derived window coordinates with certainty. This leads to the fact that it can be impossible to know the exact size and position of the windows size before these are set explicitly. The only, not specially efficient help the toolkit can provide here, is the properties ::frameOrigin and ::frameSize, which along with the ::origin and ::size properties reflect the position and size of the window, but also taking into account the system-dependent decorations.

Dialog execution

The execute method switches the window into the modal state. That means that the window is requested to reside on top of the other windows from the same program. The method returns after the window is dismissed in one or another way. It is special because it runs its own event loop, similar to the

  run Prima;

code. The event flow is not disrupted, but the windows and widgets that do not belong to the currently executed, 'modal' window group can not be activated. There can be many modal windows on top of each other, but only one will be accessible for the user. A typical message box window, that prevents other message boxes from being operated, is an example of this scheme. This is also 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 contains its own windows. An analogy, consider the situation when several independent applications run with their own modal message boxes being executed; the windows under the message boxes still are not accessible to the user, but the user can switch between the applications. This scheme, however, can not be programmed with a single execute()-like call without creating interlocking conditions. The shared model call, the execute_shared() method, inserts the window into the shared modal stack, activates the window, and returns immediately.

Both kinds of modal windows can coexist in the same program, but the exclusive windows prevent the shared windows from being accessed by the user. While there are exclusive windows, the shared ones have the same rights as the normal windows.

The stacking order for these two models is also slightly different. The window after a call to the execute() method is sent to the 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. The window after a call to the execute_shared() method is added to the shared window stack, to the one that the window's owner belongs to. The shared window stacks are located on so-called modal horizons, the windows with the boolean property ::modalHorizon set to 1. The default modal horizon is ::application.

The window in any modal state can return to the normal non-modal state by calling the end_modal() method. The window is then hidden and disabled, and the windows below it become accessible to the user. When the window's exclusive modal state is finished, its execute() method is finished as well; it returns the exit code, the same as the value of the ::modalResult property. Two shortcut methods end the modal state and set the ::modalResult property to the basic 'ok' or 'not ok' code, correspondingly by the ok() and cancel() methods. The behavior of the cancel() method is identical to when the user closes the modal window by clicking the system close button, pressing the Escape key, or otherwise canceling the dialog execution. The ok() method 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, the 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, which manages the menu items of a ::menu object of the Prima::Menu class, arranges 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 the case of Prima::Window is being displayed as a menu bar.

Note: A window can be an owner for several menu objects and still not have a menu bar displayed, if no menu objects are marked as selected.

Prima::Dialog

The Prima::Dialog class, a descendant from Prima::Window, introduces no new functionality. It only has its default values adjusted so that the colors it uses are matching the appropriate system dialog colors. It also requests the system that the look of the dialog 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 the Prima::Window class that overloads the Destroy notification and calls the $application->close inside it. The purpose of the declaration of a separate class for such a trifle difference is that many programs are designed under the paradigm where there exists the main window that is most important to the user. Since such a construct is used more often than any other, it is considered to be an optimization to write

   Prima::MainWindow->new( ... )

rather than

   Prima::Window->new( ...,
      mainWindow => 1,
      onDestroy  => sub { $::application-> close }
   )

Additionally, the $::main_window scalar points to the newly created main window.

API

Properties

borderIcons INTEGER

Requests the system to provide decorations for the window, by selecting a combination of the bi::XXX constants. These constants are:

   bi::SystemMenu  - the system menu button and/or close button
                     ( usually with the icon )
   bi::Minimize    - minimize button
   bi::Maximize    - maximize/restore button
   bi::TitleBar    - the window title
   bi::All         - all of the above

Not all systems respect these requests, and some systems provide more decoration controls, but these are not addressable by the toolkit.

borderStyle STYLE

Requests the system to set the window border style, by selecting one of the bs::XXX constants. These constants are:

   bs::None      - no border
   bs::Single    - thin border
   bs::Dialog    - thick border
   bs::Sizeable  - border that can be resized

bs::Sizeable is a 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 do not allow interactive resizing.

Not all systems recognize all of the requests, although all recognize the interactive resizing request.

effects HASH or undef

This generic property implements system-specific window effects, not necessarily portable. The format of the hash is also system-specific. The only portable behavior here is that setting the value to undef cancels all the effects.

Example:

   $window->effects({
       effect1 => {
          key1 => $value1,
          ...
       },
   });

Previously this mechanism was used for setting the DWM blur on Windows 7 and 8, but as Windows 10 removed it, this capability was also removed, so for now this is an empty call reserved for future use.

frameHeight HEIGHT

Maintains the height of the window, including the window decorations.

frameOrigin X_OFFSET, Y_OFFSET

Maintains the left X and bottom Y boundaries of the window's decorations relative to the screen.

frameSize WIDTH, HEIGHT

Maintains the width and height of the window, including the window decorations.

frameWidth WIDTH

Maintains the width of the window, including the window decorations.

icon OBJECT

Requests the system to associate the icon with the window. If OBJECT is set to undef, removes the association.

Methods

cancel

A standard method to dismiss the modal window with the mb::Cancel result. The effect of calling this method is equal to the action when the user closes the window with the system-provided menu, button, or some other command.

See also: ok, modalResult, execute, execute_shared

end_modal

Turns off the window modal state, sends the EndModal notification, and hides and disables the window. If the window is on top in the exclusive modal state, the last called execute() method 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

Switches the window to the exclusive modal state and puts it on top of all 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 the queue before the INSERT_BEFORE window. The window is made visible and enabled, if necessary, and the Execute notification is triggered.

The function is returned after the window is dismissed, or if the system-dependent 'exit'-event is triggered by the user ( the latter case makes the execution fall through all of the running execute() calls and terminates the run Prima; call, exiting gracefully).

execute_shared INSERT_BEFORE = undef

Switches the window to the shared modal state and put it on top of all non-modal windows that belong to the same modal horizon. If the window has the ::modalHorizon property value set to 1, starts its own stack, independent of all other window stacks.

By default, if the INSERT_BEFORE object is undef, the window is also put on top of other shared-modal windows in the same stack. If INSERT_BEFORE is one of the shared-modal windows in the stack, the window is placed in the queue before the INSERT_BEFORE window.

The window is made visible and enabled, if necessary, and the Execute notification is triggered.

The function returns immediately.

fullscreen

Sets the window in the fullscreen mode. A shortcut for the windowState(ws::Fullscreen) call.

get_client_handle

Returns the system handle for the special client window that is inserted in the top-level window and covers all of its areas. It is different from the get_handle method in that the latter returns the system handle of the top-level window itself. In other terms, the handle returned by this function is a child of the window returned by get_handle.

Events

Activate

Triggered when the window is activated by the user. The active window is the one that has the keyboard focus; its decorations are usually highlighted by the system.

The toolkit does not provide a standalone activation function, the select() method is used for this instead.

Deactivate

Triggered when the window is deactivated by the user. The window is marked inactive when it has no keyboard focus.

The toolkit does not provide a standalone deactivation function, the deselect() method is used for this instead.

EndModal

Called before the window leaves the modal state.

Execute

Called as soon as the window enters the modal state.

SysHandle

Same as in the Prima::Widget class, but in addition to the Widget properties that may trigger the event, the following Window properties can trigger it as well: taskListed, borderIcons, borderStyle, onTop

WindowState STATE

Triggered when the window state is changed, either by an explicit windowState() call or by the user. STATE is the new window state, one of the four ws::XXX constants.

AUTHOR

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

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)