Prima::MDI - top-level windows emulation classes
MDI stands for Multiple Document Interface, and is a Microsoft Windows user interface, that consists of multiple non-toplevel windows belonging to an application window. The module contains classes that provide similar functionality; sub-window widgets realize a set of operations, close to those of the real top-level windows, - iconize, maximize, cascade etc.
The basic classes required to use the MDI are Prima::MDIOwner and Prima::MDI, which are, correspondingly, sub-window owner class and sub-window class. Prima::MDIWindowOwner is exactly the same as Prima::MDIOwner but is a Prima::Window descendant: the both owner classes are different only in their first ascendants. Their second ascendant is Prima::MDIMethods package, that contains all the owner class functionality.
Prima::MDIOwner
Prima::MDI
Prima::MDIWindowOwner
Prima::Window
Prima::MDIMethods
Usage of Prima::MDI class extends beyond the multi-document paradigm. Prima::DockManager module uses the class as a base of a dockable toolbar window class ( see Prima::DockManager.
Prima::DockManager
use Prima::MDI; my $owner = Prima::MDIWindowOwner-> create(); my $mdi = $owner-> insert( 'Prima::MDI'); $mdi-> client-> insert( 'Prima::Button' => centered => 1 );
Implements MDI window functionality. A subwindow widget consists of a titlebar, titlebar buttons, and a client widget. The latter must be used as an insertion target for all children widgets.
A subwindow can be moved and resized, both by mouse and keyboard. These functions, along with maximize, minimize, and restore commands are accessible via the toolbar-anchored popup menu. The default set of commands is as follows:
Close window - Ctrl+F4 Restore window - Ctrl+F5 or a double click on the titlebar Maximize window - Ctrl+F10 or a double click on the titlebar Go to next MDI window - Ctrl+Tab Go to previous MDI window - Ctrl+Shift+Tab Invoke popup menu - Ctrl+Space
The class mimics API of Prima::Window class, and in some extent Prima::Window and this page share the same information.
Selects window decorations, which are buttons on titlebar and the titlebar itself. Can be 0 or a combination of the following mbi::XXX constants, which are supreset of bi::XXX constants ( see "borderIcons" in Prima::Window ) and are interchangeable.
mbi::XXX
bi::XXX
mbi::SystemMenu - system menu button with icon is shown mbi::Minimize - minimize button mbi::Maximize - maximize ( and eventual restore ) mbi::TitleBar - window title mbi::Close - close button mbi::All - all of the above
Default value: mbi::All
mbi::All
One of bs::XXX constants, selecting the window border style. The constants are:
bs::XXX
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 mode. If selected, the user can resize the window interactively. The other border styles disallow resizing and affect the border width and design only.
bs::Sizeable
Default value: bs::Sizeable
Selects the client widget at runtime. When changing the client, the old client children are not reparented to the new client. The property cannot be used to set the client during the MDI window creation; use clientClass and clientProfile properties instead.
clientClass
clientProfile
When setting new client object, note that is has to be named MDIClient and the window is automatically destroyed after the client is destroyed.
MDIClient
Assigns client widget class.
Create-only property.
Default value: Prima::Widget
Prima::Widget
Assigns hash of properties, passed to the client during the creation.
A three-state variable, which governs the visual feedback style when the user moves or resizes a window. If 1, the window is moved or resized simultaneously with the user mouse or keyboard actions. If 0, a marquee rectangle is drawn, which is moved or resized as the user sends the commands; the window is actually positioned and / or resized after the dragging session is successfully finished. If undef, the system-dependant dragging style is used. ( See "get_system_value" in Prima::Application ).
undef
The dragging session can be aborted by hitting Esc key or calling sizemove_cancel method.
sizemove_cancel
Default value: undef.
Selects a custom image to be drawn in the left corner of the toolbar. If 0, the default image ( menu button icon ) is drawn.
Default value: 0
Selects minimized button image in normal state.
Selects maximized button image in normal state.
Selects close button image in normal state.
Selects restore button image in normal state.
Selects minimize button image in pressed state.
Selects maximize button image in pressed state.
Selects close button image in pressed state.
Selects restore button image in pressed state.
Selects whether the window is allowed to participate in cascading and tiling auto-arrangements, performed correspondingly by cascade and tile methods. If 0, the window is never positioned automatically.
cascade
tile
Default value: 1
Selects height of the title bar in pixels. If 0, the default system value is used.
A three-state property, that governs the state of a window. STATE can be one of three ws::XXX constants:
ws::XXX
ws::Normal ws::Minimized ws::Maximized
The property can be changed either by explicit set-mode call or by the user. In either case, a WindowState notification is triggered.
WindowState
The property has three convenience wrappers: maximize(), minimize() and restore().
maximize()
minimize()
restore()
Default value: ws::Normal
ws::Normal
See also: WindowState
Arranges geometrically the minimized sibling MDI windows.
Arranges sibling MDI windows so they form a cascade-like structure: the lowest window is expanded to the full owner window inferior rectangle, window next to the lowest occupies the inferior rectangle of the lowest window, etc.
Only windows with tileable property set to 1 are processed.
tileable
Returns a rectangle that the window would occupy if its client rectangle is assigned to X1, Y1, X2, Y2 rectangle.
Returns a rectangle that the window client would occupy if the window rectangle is assigned to X1, Y1, X2, Y2 rectangle.
Returns a rectangle in the window coordinate system that the client would occupy if the window extensions are WIDTH and HEIGHT. If WIDTH and HEIGHT are undefined, the current window size is used.
Initiates window moving session, navigated by the keyboard.
Initiates window resizing session, navigated by the keyboard.
Returns array of sibling MDI windows.
Maximizes window. A shortcut for windowState(ws::Maximized).
windowState(ws::Maximized)
Minimizes window. A shortcut for windowState(ws::Minimized).
windowState(ws::Minimized)
Posts an action to the windows; the action is deferred and executed in the next message loop. This is used to avoid unnecessary state checks when the action-executing code returns. The current implementation accepts following string commands: min, max, restore, close.
min
max
restore
close
title
Invalidates rectangle on the title bar, corresponding to STRING, which can be one of the following:
left - redraw the menu button right - redraw minimize, maximize, and close buttons title - redraw the title
Restores window to normal state from minimized or maximized state. A shortcut for windowState(ws::Normal).
windowState(ws::Normal)
Cancels active window moving or resizing session and returns the window to the state before the session.
Arranges sibling MDI windows so they form a grid-like structure, where all windows occupy equal space, if possible.
Maps a point in (X,Y) coordinates into a string, corresponding to a part of the window: titlebar, button, or part of the border. The latter can be returned only if borderStyle is set to bs::Sizeable. The possible return values are:
borderStyle
border - window border; the window is not sizeable client - client widget caption - titlebar; the window is not moveable title - titlebar; the window is movable close - close button min - minimize button max - maximize button restore - restore button menu - menu button desktop - the point does not belong to the window
In addition, if the window is sizeable, the following constants can be returned, indicating part of the border:
SizeN - upper side SizeS - lower side SizeW - left side SizeE - right side SizeSW - lower left corner SizeNW - upper left corner SizeSE - lower right corner SizeNE - upper right corner
Triggered when the user activates a window. Activation mark is usually resides on a window that contains keyboard focus.
The module does not provide the activation function; select() call is used instead.
select()
Triggered when the user deactivates a window. Window is usually marked inactive, when it contains no keyboard focus.
The module does not provide the de-activation function; deselect() call is used instead.
deselect()
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.
windowState()
The package contains several methods for a class that is to be used as a MDI windows owner. It is enough to add class inheritance to Prima::MDIMethods to use the functionality. This step, however, is not required for a widget to become a MDI windows owner; the package contains helper functions only, which mostly mirror the arrangement functions of Prima::MDI class.
Repaints window title in all children MDI windows.
Returns array of children MDI windows.
Same as Prima::MDI::arrange_icons.
Prima::MDI::arrange_icons
Same as Prima::MDI::cascade.
Prima::MDI::cascade
Same as Prima::MDI::tile.
Prima::MDI::tile
A predeclared descendant class of Prima::Widget and Prima::MDIMethods.
A pre-declared descendant class of Prima::Window and Prima::MDIMethods.
Dmitry Karasik, <dmitry@karasik.eu.org>.
Prima, Prima::Widget, Prima::Window, Prima::DockManager, examples/mdi.pl
To install Prima, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Prima
CPAN shell
perl -MCPAN -e shell install Prima
For more information on module installation, please visit the detailed CPAN module installation guide.