Prima::Window - top-level window management


   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;


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.


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.


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.


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.

See also mainWindow.



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.


       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.


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

frameWidth WIDTH

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


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

See also: ownerIcon

mainWindow BOOLEAN

Tells the system that the window is the main window for the application. The X11 implementation uses this field to associate dialogs with the main application window.

Manages the Prima::Menu object associated with the window. Prima::Window can host many Prima::Menu objects, but only the one that is registered in the ::menu property is visualized as the menu bar.

See also: Prima::Menu, menuItems

Manages eight color properties of a menu associated with the window. INDEX must be one of the ci::XXX constants ( see Prima::Widget, colorIndex section ).

See also: menuItems, menuFont, menu

Basic foreground menu color.

See also: menuItems, menuColorIndex, menuFont, menu

Basic background menu color.

See also: menuItems, menuColorIndex, menuFont, menu

The color for drawing dark shades in menus.

See also: menuItems, menuColorIndex, menuFont, menu

Foreground color for the disabled items in menus.

See also: menuItems, menuColorIndex, menuFont, menu

Background color for the disabled items in menus.

See also: menuItems, menuColorIndex, menuFont, menu

Manages the font of the menu

See also: menuItems, menuColorIndex, menu

Foreground color for the selected items in menus.

See also: menuItems, menuColorIndex, menuFont, menu

Background color for the selected items in menus.

See also: menuItems, menuColorIndex, menuFont, menu

Manages items of the Prima::Menu object that is associated with the window. The ITEM_LIST format is the same as in the Prima::AbstractMenu::items property and is described in Prima::Menu.

See also: menu, menuColorIndex, menuFont

Color for drawing light shades in menus.

See also: menuItems, menuColorIndex, menuFont, menu

modalHorizon BOOLEAN

Sets a flag that tells if the window serves as root to the shared modal window stack. A window with ::modalHorizon set to 1 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 the same window stack.

modalResult INTEGER

Manages a custom integer value returned by the execute() method. Historically it is one of the mb::XXX constants, but any integer value can be used. The most useful mb:: constants are:

   mb::OK, mb::Ok

Note: These constants are defined so they can be or'ed bitwise, and the Prima::MsgBox package uses this feature in one of its parameters that can be a combination of the mb:: constants.


If set, the window is requested to stay on top of all other windows in the system.

Default value: 0

ownerIcon BOOLEAN

If 1, the icon is synchronized with the owner's. Automatically set to 0 if the ::icon property is explicitly set. The default value is 1, so assigning an icon to $::application automatically assigns it to all windows.

taskListed BOOLEAN

If set to 0, requests that the system should not show the window in the system taskbar or the top-level window menu, if there is any.

If 1, does not request anything.

Default value: 1

windowState STATE

The property that manages the state of the window. STATE can be one of the four ws::XXX constants:


There can be other window states provided by the system, but these four were chosen as a 'least common denominator'. The property can be changed either by an explicit set-mode call or by the user. In either case, a WindowState notification is triggered.

The property has the corresponding convenience wrappers: maximize(), minimize(), restore(), and fullscreen().

See also: WindowState



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


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.


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


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.

See also: get_handle


Returns the default font for the Prima::Menu class.


Returns one of the three constants that reflect the modal state of the window:


The value of mt::None is 0, so the result of get_modal() can be also treated as a boolean value if one needs to check if the window is modal or not.

get_modal_window MODALITY_TYPE = mt::Exclusive, NEXT = 1

Returns the 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 the boolean flag selecting the lookup direction; if it is 1, the 'upper' window is returned, otherwise the 'lower' one ( in a simple case when the window A is made modal (executed) after the modal window B, the A window is the 'upper' one ).

If the window has no immediate modal siblings, undef is returned.


Maximizes the window. A shortcut for windowState(ws::Maximized).


Minimizes the window. A shortcut for windowState(ws::Minimized).


The standard method to dismiss the modal window with the mb::OK result. Typically the effect of calling this method is equal to when the user presses the enter key of on the modal window, signalling that the default action is to be taken.

See also: cancel, modalResult, execute, execute_shared


Restores the window to a normal state from the minimized or maximized state. A shortcut for windowState(ws::Normal).



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.


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.


Called before the window leaves the modal state.


Called as soon as the window enters the modal state.


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.


Dmitry Karasik, <>.


Prima, Prima::Object, Prima::Drawable, Prima::Widget.