1Prima::MDI(3) User Contributed Perl Documentation Prima::MDI(3)
2
6 Prima::MDI - top-level windows emulation classes
7
9 MDI stands for Multiple Document Interface, and is a Microsoft Windows
10 user interface, that consists of multiple non-toplevel windows
11 belonging to an application window. The module contains classes that
12 provide similar functionality; sub-window widgets realize a set of
13 operations, close to those of the real top-level windows, - iconize,
14 maximize, cascade etc.
15 The basic classes required to use the MDI are "Prima::MDIOwner" and
17 "Prima::MDI", which are, correspondingly, sub-window owner class and
18 sub-window class. "Prima::MDIWindowOwner" is exactly the same as
19 "Prima::MDIOwner" but is a "Prima::Window" descendant: the both owner
20 classes are different only in their first ascendants. Their second
21 ascendant is "Prima::MDIMethods" package, that contains all the owner
22 class functionality.
23 Usage of "Prima::MDI" class extends beyond the multi-document paradigm.
25 "Prima::DockManager" module uses the class as a base of a dockable
26 toolbar window class ( see Prima::DockManager.
27
29 use Prima qw(Application MDI Buttons);
30 my $owner = Prima::MDIWindowOwner-> new;
32 my $mdi = $owner-> insert( 'Prima::MDI');
33 $mdi-> client-> insert( 'Prima::Button' => centered => 1 );
34 run Prima;
36
38 Implements MDI window functionality. A subwindow widget consists of a
39 titlebar, titlebar buttons, and a client widget. The latter must be
40 used as an insertion target for all children widgets.
41 A subwindow can be moved and resized, both by mouse and keyboard.
43 These functions, along with maximize, minimize, and restore commands
44 are accessible via the toolbar-anchored popup menu. The default set of
45 commands is as follows:
46 Close window - Ctrl+F4
48 Restore window - Ctrl+F5 or a double click on the titlebar
49 Maximize window - Ctrl+F10 or a double click on the titlebar
50 Go to next MDI window - Ctrl+Tab
51 Go to previous MDI window - Ctrl+Shift+Tab
52 Invoke popup menu - Ctrl+Space
53 The class mimics API of "Prima::Window" class, and in some extent
55 Prima::Window and this page share the same information.
56 Properties
58 borderIcons INTEGER
59 Selects window decorations, which are buttons on titlebar and the
60 titlebar itself. Can be 0 or a combination of the following
61 "mbi::XXX" constants, which are supreset of "bi::XXX" constants (
62 see "borderIcons" in Prima::Window ) and are interchangeable.
63 mbi::SystemMenu - system menu button with icon is shown
65 mbi::Minimize - minimize button
66 mbi::Maximize - maximize ( and eventual restore )
67 mbi::TitleBar - window title
68 mbi::Close - close button
69 mbi::All - all of the above
70 Default value: "mbi::All"
72 borderStyle INTEGER
74 One of "bs::XXX" constants, selecting the window border style. The
75 constants are:
76 bs::None - no border
78 bs::Single - thin border
79 bs::Dialog - thick border
80 bs::Sizeable - thick border with interactive resize capabilities
81 "bs::Sizeable" is an unique mode. If selected, the user can resize
83 the window interactively. The other border styles disallow resizing
84 and affect the border width and design only.
85 Default value: "bs::Sizeable"
87 client OBJECT
89 Selects the client widget at runtime. When changing the client, the
90 old client children are not reparented to the new client. The
91 property cannot be used to set the client during the MDI window
92 creation; use "clientClass" and "clientProfile" properties instead.
93 When setting new client object, note that is has to be named
95 "MDIClient" and the window is automatically destroyed after the
96 client is destroyed.
97 clientClass STRING
99 Assigns client widget class.
100 Create-only property.
102 Default value: "Prima::Widget"
104 clientProfile HASH
106 Assigns hash of properties, passed to the client during the
107 creation.
108 Create-only property.
110 dragMode SCALAR
112 A three-state variable, which governs the visual feedback style
113 when the user moves or resizes a window. If 1, the window is moved
114 or resized simultaneously with the user mouse or keyboard actions.
115 If 0, a marquee rectangle is drawn, which is moved or resized as
116 the user sends the commands; the window is actually positioned and
117 / or resized after the dragging session is successfully finished.
118 If "undef", the system-dependant dragging style is used. ( See
119 "get_system_value" in Prima::Application ).
120 The dragging session can be aborted by hitting Esc key or calling
122 "sizemove_cancel" method.
123 Default value: "undef".
125 icon HANDLE
127 Selects a custom image to be drawn in the left corner of the
128 toolbar. If 0, the default image ( menu button icon ) is drawn.
129 Default value: 0
131 iconMin HANDLE
133 Selects minimized button image in normal state.
134 iconMax HANDLE
136 Selects maximized button image in normal state.
137 iconClose HANDLE
139 Selects close button image in normal state.
140 iconRestore HANDLE
142 Selects restore button image in normal state.
143 iconMinPressed HANDLE
145 Selects minimize button image in pressed state.
146 iconMaxPressed HANDLE
148 Selects maximize button image in pressed state.
149 iconClosePressed HANDLE
151 Selects close button image in pressed state.
152 iconRestorePressed HANDLE
154 Selects restore button image in pressed state.
155 tileable BOOLEAN
157 Selects whether the window is allowed to participate in cascading
158 and tiling auto-arrangements, performed correspondingly by
159 "cascade" and "tile" methods. If 0, the window is never positioned
160 automatically.
161 Default value: 1
163 titleHeight INTEGER
165 Selects height of the title bar in pixels. If 0, the default system
166 value is used.
167 Default value: 0
169 windowState STATE
171 A three-state property, that governs the state of a window. STATE
172 can be one of three "ws::XXX" constants:
173 ws::Normal
175 ws::Minimized
176 ws::Maximized
177 The property can be changed either by explicit set-mode call or by
179 the user. In either case, a "WindowState" notification is
180 triggered.
181 The property has three convenience wrappers: "maximize()",
183 "minimize()" and "restore()".
184 Default value: "ws::Normal"
186 See also: "WindowState"
188 Methods
190 arrange_icons
191 Arranges geometrically the minimized sibling MDI windows.
192 cascade
194 Arranges sibling MDI windows so they form a cascade-like structure:
195 the lowest window is expanded to the full owner window inferior
196 rectangle, window next to the lowest occupies the inferior
197 rectangle of the lowest window, etc.
198 Only windows with "tileable" property set to 1 are processed.
200 client2frame X1, Y1, X2, Y2
202 Returns a rectangle that the window would occupy if its client
203 rectangle is assigned to X1, Y1, X2, Y2 rectangle.
204 frame2client X1, Y1, X2, Y2
206 Returns a rectangle that the window client would occupy if the
207 window rectangle is assigned to X1, Y1, X2, Y2 rectangle.
208 get_client_rect [ WIDTH, HEIGHT ]
210 Returns a rectangle in the window coordinate system that the client
211 would occupy if the window extensions are WIDTH and HEIGHT. If
212 WIDTH and HEIGHT are undefined, the current window size is used.
213 keyMove
215 Initiates window moving session, navigated by the keyboard.
216 keySize
218 Initiates window resizing session, navigated by the keyboard.
219 mdis
221 Returns array of sibling MDI windows.
222 maximize
224 Maximizes window. A shortcut for "windowState(ws::Maximized)".
225 minimize
227 Minimizes window. A shortcut for "windowState(ws::Minimized)".
228 post_action STRING
230 Posts an action to the windows; the action is deferred and executed
231 in the next message loop. This is used to avoid unnecessary state
232 checks when the action-executing code returns. The current
233 implementation accepts following string commands: "min", "max",
234 "restore", "close".
235 repaint_title [ STRING = "title" ]
237 Invalidates rectangle on the title bar, corresponding to STRING,
238 which can be one of the following:
239 left - redraw the menu button
241 right - redraw minimize, maximize, and close buttons
242 title - redraw the title
243 restore
245 Restores window to normal state from minimized or maximized state.
246 A shortcut for "windowState(ws::Normal)".
247 sizemove_cancel
249 Cancels active window moving or resizing session and returns the
250 window to the state before the session.
251 tile
253 Arranges sibling MDI windows so they form a grid-like structure,
254 where all windows occupy equal space, if possible.
255 Only windows with "tileable" property set to 1 are processed.
257 xy2part X, Y
259 Maps a point in (X,Y) coordinates into a string, corresponding to a
260 part of the window: titlebar, button, or part of the border. The
261 latter can be returned only if "borderStyle" is set to
262 "bs::Sizeable". The possible return values are:
263 border - window border; the window is not sizeable
265 client - client widget
266 caption - titlebar; the window is not moveable
267 title - titlebar; the window is movable
268 close - close button
269 min - minimize button
270 max - maximize button
271 restore - restore button
272 menu - menu button
273 desktop - the point does not belong to the window
274 In addition, if the window is sizeable, the following constants can
276 be returned, indicating part of the border:
277 SizeN - upper side
279 SizeS - lower side
280 SizeW - left side
281 SizeE - right side
282 SizeSW - lower left corner
283 SizeNW - upper left corner
284 SizeSE - lower right corner
285 SizeNE - upper right corner
286 Events
288 Activate
289 Triggered when the user activates a window. Activation mark is
290 usually resides on a window that contains keyboard focus.
291 The module does not provide the activation function; "select()"
293 call is used instead.
294 Deactivate
296 Triggered when the user deactivates a window. Window is usually
297 marked inactive, when it contains no keyboard focus.
298 The module does not provide the de-activation function;
300 "deselect()" call is used instead.
301 WindowState STATE
303 Triggered when window state is changed, either by an explicit
304 "windowState()" call, or by the user. STATE is the new window
305 state, one of three "ws::XXX" constants.
306
308 Methods
309 The package contains several methods for a class that is to be used as
310 a MDI windows owner. It is enough to add class inheritance to
311 "Prima::MDIMethods" to use the functionality. This step, however, is
312 not required for a widget to become a MDI windows owner; the package
313 contains helper functions only, which mostly mirror the arrangement
314 functions of "Prima::MDI" class.
315 mdi_activate
317 Repaints window title in all children MDI windows.
318 mdis
320 Returns array of children MDI windows.
321 arrange_icons
323 Same as "Prima::MDI::arrange_icons".
324 cascade
326 Same as "Prima::MDI::cascade".
327 tile
329 Same as "Prima::MDI::tile".
330
332 A predeclared descendant class of "Prima::Widget" and
333 "Prima::MDIMethods".
334
336 A pre-declared descendant class of "Prima::Window" and
337 "Prima::MDIMethods".
338
340 Dmitry Karasik, <dmitry@karasik.eu.org>.
341
343 Prima, Prima::Widget, Prima::Window, Prima::DockManager,
344 examples/mdi.pl
345perl v5.30.0 2019-08-21 Prima::MDI(3)