Man Linux: Main Page and Category List

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.

           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.