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.
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 the Prima::DockManager manpage.
use Prima qw(Application MDI Buttons);
my $owner = Prima::MDIWindowOwner-> new;
my $mdi = $owner-> insert( 'Prima::MDI');
$mdi-> client-> insert( 'Prima::Button' => centered => 1 );
run Prima;
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
the Prima::Window manpage and this page share the same information.
- 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 the Prima::Window manpage ) 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 the Prima::Application manpage ).
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
- 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
- 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.
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.
- mdismdis
-
Returns array of children MDI windows.
- arrange_iconsarrange_icons
-
Same as
Prima::MDI::arrange_icons.
- cascadecascade
-
Same as
Prima::MDI::cascade.
- tiletile
-
Same as
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, the Prima::Widget manpage, the Prima::Window manpage, the Prima::DockManager manpage, examples/mdi.pl
|