.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Prima::MDI 3" .TH Prima::MDI 3 "2009-02-24" "perl v5.14.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Prima::MDI \- top\-level windows emulation classes .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\s-1MDI\s0 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. .PP The basic classes required to use the \s-1MDI\s0 are \f(CW\*(C`Prima::MDIOwner\*(C'\fR and \&\f(CW\*(C`Prima::MDI\*(C'\fR, which are, correspondingly, sub-window owner class and sub-window class. \f(CW\*(C`Prima::MDIWindowOwner\*(C'\fR is exactly the same as \&\f(CW\*(C`Prima::MDIOwner\*(C'\fR but is a \f(CW\*(C`Prima::Window\*(C'\fR descendant: the both owner classes are different only in their first ascendants. Their second ascendant is \&\f(CW\*(C`Prima::MDIMethods\*(C'\fR package, that contains all the owner class functionality. .PP Usage of \f(CW\*(C`Prima::MDI\*(C'\fR class extends beyond the multi-document paradigm. \&\f(CW\*(C`Prima::DockManager\*(C'\fR module uses the class as a base of a dockable toolbar window class ( see Prima::DockManager. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Prima::MDI; \& \& my $owner = Prima::MDIWindowOwner\-> create(); \& my $mdi = $owner\-> insert( \*(AqPrima::MDI\*(Aq); \& $mdi\-> client\-> insert( \*(AqPrima::Button\*(Aq => centered => 1 ); .Ve .SH "Prima::MDI" .IX Header "Prima::MDI" Implements \s-1MDI\s0 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. .PP 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: .PP .Vb 6 \& 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 .Ve .PP The class mimics \s-1API\s0 of \f(CW\*(C`Prima::Window\*(C'\fR class, and in some extent Prima::Window and this page share the same information. .SS "Properties" .IX Subsection "Properties" .IP "borderIcons \s-1INTEGER\s0" 4 .IX Item "borderIcons INTEGER" Selects window decorations, which are buttons on titlebar and the titlebar itself. Can be 0 or a combination of the following \f(CW\*(C`mbi::XXX\*(C'\fR constants, which are supreset of \f(CW\*(C`bi::XXX\*(C'\fR constants ( see \*(L"borderIcons\*(R" in Prima::Window ) and are interchangeable. .Sp .Vb 6 \& 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 .Ve .Sp Default value: \f(CW\*(C`mbi::All\*(C'\fR .IP "borderStyle \s-1INTEGER\s0" 4 .IX Item "borderStyle INTEGER" One of \f(CW\*(C`bs::XXX\*(C'\fR constants, selecting the window border style. The constants are: .Sp .Vb 4 \& bs::None \- no border \& bs::Single \- thin border \& bs::Dialog \- thick border \& bs::Sizeable \- thick border with interactive resize capabilities .Ve .Sp \&\f(CW\*(C`bs::Sizeable\*(C'\fR 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. .Sp Default value: \f(CW\*(C`bs::Sizeable\*(C'\fR .IP "client \s-1OBJECT\s0" 4 .IX Item "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 \s-1MDI\s0 window creation; use \&\f(CW\*(C`clientClass\*(C'\fR and \f(CW\*(C`clientProfile\*(C'\fR properties instead. .Sp When setting new client object, note that is has to be named \f(CW\*(C`MDIClient\*(C'\fR and the window is automatically destroyed after the client is destroyed. .IP "clientClass \s-1STRING\s0" 4 .IX Item "clientClass STRING" Assigns client widget class. .Sp Create-only property. .Sp Default value: \f(CW\*(C`Prima::Widget\*(C'\fR .IP "clientProfile \s-1HASH\s0" 4 .IX Item "clientProfile HASH" Assigns hash of properties, passed to the client during the creation. .Sp Create-only property. .IP "dragMode \s-1SCALAR\s0" 4 .IX Item "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 \f(CW\*(C`undef\*(C'\fR, the system-dependant dragging style is used. ( See \&\*(L"get_system_value\*(R" in Prima::Application ). .Sp The dragging session can be aborted by hitting Esc key or calling \f(CW\*(C`sizemove_cancel\*(C'\fR method. .Sp Default value: \f(CW\*(C`undef\*(C'\fR. .IP "icon \s-1HANDLE\s0" 4 .IX Item "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. .Sp Default value: 0 .IP "iconMin \s-1HANDLE\s0" 4 .IX Item "iconMin HANDLE" Selects minimized button image in normal state. .IP "iconMax \s-1HANDLE\s0" 4 .IX Item "iconMax HANDLE" Selects maximized button image in normal state. .IP "iconClose \s-1HANDLE\s0" 4 .IX Item "iconClose HANDLE" Selects close button image in normal state. .IP "iconRestore \s-1HANDLE\s0" 4 .IX Item "iconRestore HANDLE" Selects restore button image in normal state. .IP "iconMinPressed \s-1HANDLE\s0" 4 .IX Item "iconMinPressed HANDLE" Selects minimize button image in pressed state. .IP "iconMaxPressed \s-1HANDLE\s0" 4 .IX Item "iconMaxPressed HANDLE" Selects maximize button image in pressed state. .IP "iconClosePressed \s-1HANDLE\s0" 4 .IX Item "iconClosePressed HANDLE" Selects close button image in pressed state. .IP "iconRestorePressed \s-1HANDLE\s0" 4 .IX Item "iconRestorePressed HANDLE" Selects restore button image in pressed state. .IP "tileable \s-1BOOLEAN\s0" 4 .IX Item "tileable BOOLEAN" Selects whether the window is allowed to participate in cascading and tiling auto-arrangements, performed correspondingly by \f(CW\*(C`cascade\*(C'\fR and \f(CW\*(C`tile\*(C'\fR methods. If 0, the window is never positioned automatically. .Sp Default value: 1 .IP "titleHeight \s-1INTEGER\s0" 4 .IX Item "titleHeight INTEGER" Selects height of the title bar in pixels. If 0, the default system value is used. .Sp Default value: 0 .IP "windowState \s-1STATE\s0" 4 .IX Item "windowState STATE" A three-state property, that governs the state of a window. \&\s-1STATE\s0 can be one of three \f(CW\*(C`ws::XXX\*(C'\fR constants: .Sp .Vb 3 \& ws::Normal \& ws::Minimized \& ws::Maximized .Ve .Sp The property can be changed either by explicit set-mode call or by the user. In either case, a \f(CW\*(C`WindowState\*(C'\fR notification is triggered. .Sp The property has three convenience wrappers: \f(CW\*(C`maximize()\*(C'\fR, \f(CW\*(C`minimize()\*(C'\fR and \&\f(CW\*(C`restore()\*(C'\fR. .Sp Default value: \f(CW\*(C`ws::Normal\*(C'\fR .Sp See also: \f(CW\*(C`WindowState\*(C'\fR .SS "Methods" .IX Subsection "Methods" .IP "arrange_icons" 4 .IX Item "arrange_icons" Arranges geometrically the minimized sibling \s-1MDI\s0 windows. .IP "cascade" 4 .IX Item "cascade" Arranges sibling \s-1MDI\s0 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. .Sp Only windows with \f(CW\*(C`tileable\*(C'\fR property set to 1 are processed. .IP "client2frame X1, Y1, X2, Y2" 4 .IX Item "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. .IP "frame2client X1, Y1, X2, Y2" 4 .IX Item "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. .IP "get_client_rect [ \s-1WIDTH\s0, \s-1HEIGHT\s0 ]" 4 .IX Item "get_client_rect [ WIDTH, HEIGHT ]" Returns a rectangle in the window coordinate system that the client would occupy if the window extensions are \s-1WIDTH\s0 and \s-1HEIGHT\s0. If \s-1WIDTH\s0 and \s-1HEIGHT\s0 are undefined, the current window size is used. .IP "keyMove" 4 .IX Item "keyMove" Initiates window moving session, navigated by the keyboard. .IP "keySize" 4 .IX Item "keySize" Initiates window resizing session, navigated by the keyboard. .IP "mdis" 4 .IX Item "mdis" Returns array of sibling \s-1MDI\s0 windows. .IP "maximize" 4 .IX Item "maximize" Maximizes window. A shortcut for \f(CW\*(C`windowState(ws::Maximized)\*(C'\fR. .IP "minimize" 4 .IX Item "minimize" Minimizes window. A shortcut for \f(CW\*(C`windowState(ws::Minimized)\*(C'\fR. .IP "post_action \s-1STRING\s0" 4 .IX Item "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: \f(CW\*(C`min\*(C'\fR, \f(CW\*(C`max\*(C'\fR, \f(CW\*(C`restore\*(C'\fR, \f(CW\*(C`close\*(C'\fR. .ie n .IP "repaint_title [ \s-1STRING\s0 = ""title"" ]" 4 .el .IP "repaint_title [ \s-1STRING\s0 = \f(CWtitle\fR ]" 4 .IX Item "repaint_title [ STRING = title ]" Invalidates rectangle on the title bar, corresponding to \s-1STRING\s0, which can be one of the following: .Sp .Vb 3 \& left \- redraw the menu button \& right \- redraw minimize, maximize, and close buttons \& title \- redraw the title .Ve .IP "restore" 4 .IX Item "restore" Restores window to normal state from minimized or maximized state. A shortcut for \f(CW\*(C`windowState(ws::Normal)\*(C'\fR. .IP "sizemove_cancel" 4 .IX Item "sizemove_cancel" Cancels active window moving or resizing session and returns the window to the state before the session. .IP "tile" 4 .IX Item "tile" Arranges sibling \s-1MDI\s0 windows so they form a grid-like structure, where all windows occupy equal space, if possible. .Sp Only windows with \f(CW\*(C`tileable\*(C'\fR property set to 1 are processed. .IP "xy2part X, Y" 4 .IX Item "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 \f(CW\*(C`borderStyle\*(C'\fR is set to \f(CW\*(C`bs::Sizeable\*(C'\fR. The possible return values are: .Sp .Vb 10 \& 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 .Ve .Sp In addition, if the window is sizeable, the following constants can be returned, indicating part of the border: .Sp .Vb 8 \& 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 .Ve .SS "Events" .IX Subsection "Events" .IP "Activate" 4 .IX Item "Activate" Triggered when the user activates a window. Activation mark is usually resides on a window that contains keyboard focus. .Sp The module does not provide the activation function; \f(CW\*(C`select()\*(C'\fR call is used instead. .IP "Deactivate" 4 .IX Item "Deactivate" Triggered when the user deactivates a window. Window is usually marked inactive, when it contains no keyboard focus. .Sp The module does not provide the de-activation function; \f(CW\*(C`deselect()\*(C'\fR call is used instead. .IP "WindowState \s-1STATE\s0" 4 .IX Item "WindowState STATE" Triggered when window state is changed, either by an explicit \f(CW\*(C`windowState()\*(C'\fR call, or by the user. \s-1STATE\s0 is the new window state, one of three \f(CW\*(C`ws::XXX\*(C'\fR constants. .SH "Prima::MDIMethods" .IX Header "Prima::MDIMethods" .SS "Methods" .IX Subsection "Methods" The package contains several methods for a class that is to be used as a \s-1MDI\s0 windows owner. It is enough to add class inheritance to \f(CW\*(C`Prima::MDIMethods\*(C'\fR to use the functionality. This step, however, is not required for a widget to become a \s-1MDI\s0 windows owner; the package contains helper functions only, which mostly mirror the arrangement functions of \f(CW\*(C`Prima::MDI\*(C'\fR class. .IP "mdi_activate" 4 .IX Item "mdi_activate" Repaints window title in all children \s-1MDI\s0 windows. .IP "mdis" 4 .IX Item "mdis" Returns array of children \s-1MDI\s0 windows. .IP "arrange_icons" 4 .IX Item "arrange_icons" Same as \f(CW\*(C`Prima::MDI::arrange_icons\*(C'\fR. .IP "cascade" 4 .IX Item "cascade" Same as \f(CW\*(C`Prima::MDI::cascade\*(C'\fR. .IP "tile" 4 .IX Item "tile" Same as \f(CW\*(C`Prima::MDI::tile\*(C'\fR. .SH "Prima::MDIOwner" .IX Header "Prima::MDIOwner" A predeclared descendant class of \f(CW\*(C`Prima::Widget\*(C'\fR and \f(CW\*(C`Prima::MDIMethods\*(C'\fR. .SH "Prima::MDIWindowOwner" .IX Header "Prima::MDIWindowOwner" A pre-declared descendant class of \f(CW\*(C`Prima::Window\*(C'\fR and \f(CW\*(C`Prima::MDIMethods\*(C'\fR. .SH "AUTHOR" .IX Header "AUTHOR" Dmitry Karasik, . .SH "SEE ALSO" .IX Header "SEE ALSO" Prima, Prima::Widget, Prima::Window, Prima::DockManager, \fIexamples/mdi.pl\fR