Provided by: libprima-perl_1.28-1.2_amd64 
NAME
Prima::MDI - top-level windows emulation classes
DESCRIPTION
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.
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.
SYNOPSIS
use Prima::MDI;
my $owner = Prima::MDIWindowOwner-> create();
my $mdi = $owner-> insert( 'Prima::MDI');
$mdi-> client-> insert( 'Prima::Button' => centered => 1 );
Prima::MDI
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.
Properties
borderIcons INTEGER
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::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"
borderStyle INTEGER
One of "bs::XXX" constants, selecting the window border style. 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 mode. If selected, the user can resize the window
interactively. The other border styles disallow resizing and affect the border width
and design only.
Default value: "bs::Sizeable"
client OBJECT
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.
When setting new client object, note that is has to be named "MDIClient" and the
window is automatically destroyed after the client is destroyed.
clientClass STRING
Assigns client widget class.
Create-only property.
Default value: "Prima::Widget"
clientProfile HASH
Assigns hash of properties, passed to the client during the creation.
Create-only property.
dragMode SCALAR
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 ).
The dragging session can be aborted by hitting Esc key or calling "sizemove_cancel"
method.
Default value: "undef".
icon HANDLE
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
iconMin HANDLE
Selects minimized button image in normal state.
iconMax HANDLE
Selects maximized button image in normal state.
iconClose HANDLE
Selects close button image in normal state.
iconRestore HANDLE
Selects restore button image in normal state.
iconMinPressed HANDLE
Selects minimize button image in pressed state.
iconMaxPressed HANDLE
Selects maximize button image in pressed state.
iconClosePressed HANDLE
Selects close button image in pressed state.
iconRestorePressed HANDLE
Selects restore button image in pressed state.
tileable BOOLEAN
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.
Default value: 1
titleHeight INTEGER
Selects height of the title bar in pixels. If 0, the default system value is used.
Default value: 0
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
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()".
Default value: "ws::Normal"
See also: "WindowState"
Methods
arrange_icons
Arranges geometrically the minimized sibling MDI windows.
cascade
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.
client2frame X1, Y1, X2, Y2
Returns a rectangle that the window would occupy if its client rectangle is assigned
to X1, Y1, X2, Y2 rectangle.
frame2client X1, Y1, X2, Y2
Returns a rectangle that the window client would occupy if the window rectangle is
assigned to X1, Y1, X2, Y2 rectangle.
get_client_rect [ WIDTH, HEIGHT ]
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.
keyMove
Initiates window moving session, navigated by the keyboard.
keySize
Initiates window resizing session, navigated by the keyboard.
mdis
Returns array of sibling MDI windows.
maximize
Maximizes window. A shortcut for "windowState(ws::Maximized)".
minimize
Minimizes window. A shortcut for "windowState(ws::Minimized)".
post_action STRING
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".
repaint_title [ STRING = "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
restore
Restores window to normal state from minimized or maximized state. A shortcut for
"windowState(ws::Normal)".
sizemove_cancel
Cancels active window moving or resizing session and returns the window to the state
before the session.
tile
Arranges sibling MDI windows so they form a grid-like structure, where all windows
occupy equal space, if possible.
Only windows with "tileable" property set to 1 are processed.
xy2part X, Y
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:
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
Events
Activate
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.
Deactivate
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.
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.
Prima::MDIMethods
Methods
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.
mdi_activate
Repaints window title in all children MDI windows.
mdis
Returns array of children MDI windows.
arrange_icons
Same as "Prima::MDI::arrange_icons".
cascade
Same as "Prima::MDI::cascade".
tile
Same as "Prima::MDI::tile".
Prima::MDIOwner
A predeclared descendant class of "Prima::Widget" and "Prima::MDIMethods".
Prima::MDIWindowOwner
A pre-declared descendant class of "Prima::Window" and "Prima::MDIMethods".
AUTHOR
Dmitry Karasik, <dmitry@karasik.eu.org>.
SEE ALSO
Prima, Prima::Widget, Prima::Window, Prima::DockManager, examples/mdi.pl