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::MDI;
30 my $owner = Prima::MDIWindowOwner-> create();
32 my $mdi = $owner-> insert( 'Prima::MDI');
33 $mdi-> client-> insert( 'Prima::Button' => centered => 1 );
34
36 Implements MDI window functionality. A subwindow widget consists of a
37 titlebar, titlebar buttons, and a client widget. The latter must be
38 used as an insertion target for all children widgets.
39 A subwindow can be moved and resized, both by mouse and keyboard.
41 These functions, along with maximize, minimize, and restore commands
42 are accessible via the toolbar-anchored popup menu. The default set of
43 commands is as follows:
44 Close window - Ctrl+F4
46 Restore window - Ctrl+F5 or a double click on the titlebar
47 Maximize window - Ctrl+F10 or a double click on the titlebar
48 Go to next MDI window - Ctrl+Tab
49 Go to previous MDI window - Ctrl+Shift+Tab
50 Invoke popup menu - Ctrl+Space
51 The class mimics API of "Prima::Window" class, and in some extent
53 Prima::Window and this page share the same information.
54 Properties
56 borderIcons INTEGER
57 Selects window decorations, which are buttons on titlebar and the
58 titlebar itself. Can be 0 or a combination of the following
59 "mbi::XXX" constants, which are supreset of "bi::XXX" constants (
60 see "borderIcons" in Prima::Window ) and are interchangeable.
61 mbi::SystemMenu - system menu button with icon is shown
63 mbi::Minimize - minimize button
64 mbi::Maximize - maximize ( and eventual restore )
65 mbi::TitleBar - window title
66 mbi::Close - close button
67 mbi::All - all of the above
68 Default value: "mbi::All"
70 borderStyle INTEGER
72 One of "bs::XXX" constants, selecting the window border style. The
73 constants are:
74 bs::None - no border
76 bs::Single - thin border
77 bs::Dialog - thick border
78 bs::Sizeable - thick border with interactive resize capabilities
79 "bs::Sizeable" is an unique mode. If selected, the user can resize
81 the window interactively. The other border styles disallow resizing
82 and affect the border width and design only.
83 Default value: "bs::Sizeable"
85 client OBJECT
87 Selects the client widget at runtime. When changing the client, the
88 old client children are not reparented to the new client. The
89 property cannot be used to set the client during the MDI window
90 creation; use "clientClass" and "clientProfile" properties instead.
91 When setting new client object, note that is has to be named
93 "MDIClient" and the window is automatically destroyed after the
94 client is destroyed.
95 clientClass STRING
97 Assigns client widget class.
98 Create-only property.
100 Default value: "Prima::Widget"
102 clientProfile HASH
104 Assigns hash of properties, passed to the client during the
105 creation.
106 Create-only property.
108 dragMode SCALAR
110 A three-state variable, which governs the visual feedback style
111 when the user moves or resizes a window. If 1, the window is moved
112 or resized simultaneously with the user mouse or keyboard actions.
113 If 0, a marquee rectangle is drawn, which is moved or resized as
114 the user sends the commands; the window is actually positioned and
115 / or resized after the dragging session is successfully finished.
116 If "undef", the system-dependant dragging style is used. ( See
117 "get_system_value" in Prima::Application ).
118 The dragging session can be aborted by hitting Esc key or calling
120 "sizemove_cancel" method.
121 Default value: "undef".
123 icon HANDLE
125 Selects a custom image to be drawn in the left corner of the
126 toolbar. If 0, the default image ( menu button icon ) is drawn.
127 Default value: 0
129 iconMin HANDLE
131 Selects minimized button image in normal state.
132 iconMax HANDLE
134 Selects maximized button image in normal state.
135 iconClose HANDLE
137 Selects close button image in normal state.
138 iconRestore HANDLE
140 Selects restore button image in normal state.
141 iconMinPressed HANDLE
143 Selects minimize button image in pressed state.
144 iconMaxPressed HANDLE
146 Selects maximize button image in pressed state.
147 iconClosePressed HANDLE
149 Selects close button image in pressed state.
150 iconRestorePressed HANDLE
152 Selects restore button image in pressed state.
153 tileable BOOLEAN
155 Selects whether the window is allowed to participate in cascading
156 and tiling auto-arrangements, performed correspondingly by
157 "cascade" and "tile" methods. If 0, the window is never positioned
158 automatically.
159 Default value: 1
161 titleHeight INTEGER
163 Selects height of the title bar in pixels. If 0, the default system
164 value is used.
165 Default value: 0
167 windowState STATE
169 A three-state property, that governs the state of a window. STATE
170 can be one of three "ws::XXX" constants:
171 ws::Normal
173 ws::Minimized
174 ws::Maximized
175 The property can be changed either by explicit set-mode call or by
177 the user. In either case, a "WindowState" notification is
178 triggered.
179 The property has three convenience wrappers: "maximize()",
181 "minimize()" and "restore()".
182 Default value: "ws::Normal"
184 See also: "WindowState"
186 Methods
188 arrange_icons
189 Arranges geometrically the minimized sibling MDI windows.
190 cascade
192 Arranges sibling MDI windows so they form a cascade-like structure:
193 the lowest window is expanded to the full owner window inferior
194 rectangle, window next to the lowest occupies the inferior
195 rectangle of the lowest window, etc.
196 Only windows with "tileable" property set to 1 are processed.
198 client2frame X1, Y1, X2, Y2
200 Returns a rectangle that the window would occupy if its client
201 rectangle is assigned to X1, Y1, X2, Y2 rectangle.
202 frame2client X1, Y1, X2, Y2
204 Returns a rectangle that the window client would occupy if the
205 window rectangle is assigned to X1, Y1, X2, Y2 rectangle.
206 get_client_rect [ WIDTH, HEIGHT ]
208 Returns a rectangle in the window coordinate system that the client
209 would occupy if the window extensions are WIDTH and HEIGHT. If
210 WIDTH and HEIGHT are undefined, the current window size is used.
211 keyMove
213 Initiates window moving session, navigated by the keyboard.
214 keySize
216 Initiates window resizing session, navigated by the keyboard.
217 mdis
219 Returns array of sibling MDI windows.
220 maximize
222 Maximizes window. A shortcut for "windowState(ws::Maximized)".
223 minimize
225 Minimizes window. A shortcut for "windowState(ws::Minimized)".
226 post_action STRING
228 Posts an action to the windows; the action is deferred and executed
229 in the next message loop. This is used to avoid unnecessary state
230 checks when the action-executing code returns. The current
231 implementation accepts following string commands: "min", "max",
232 "restore", "close".
233 repaint_title [ STRING = "title" ]
235 Invalidates rectangle on the title bar, corresponding to STRING,
236 which can be one of the following:
237 left - redraw the menu button
239 right - redraw minimize, maximize, and close buttons
240 title - redraw the title
241 restore
243 Restores window to normal state from minimized or maximized state.
244 A shortcut for "windowState(ws::Normal)".
245 sizemove_cancel
247 Cancels active window moving or resizing session and returns the
248 window to the state before the session.
249 tile
251 Arranges sibling MDI windows so they form a grid-like structure,
252 where all windows occupy equal space, if possible.
253 Only windows with "tileable" property set to 1 are processed.
255 xy2part X, Y
257 Maps a point in (X,Y) coordinates into a string, corresponding to a
258 part of the window: titlebar, button, or part of the border. The
259 latter can be returned only if "borderStyle" is set to
260 "bs::Sizeable". The possible return values are:
261 border - window border; the window is not sizeable
263 client - client widget
264 caption - titlebar; the window is not moveable
265 title - titlebar; the window is movable
266 close - close button
267 min - minimize button
268 max - maximize button
269 restore - restore button
270 menu - menu button
271 desktop - the point does not belong to the window
272 In addition, if the window is sizeable, the following constants can
274 be returned, indicating part of the border:
275 SizeN - upper side
277 SizeS - lower side
278 SizeW - left side
279 SizeE - right side
280 SizeSW - lower left corner
281 SizeNW - upper left corner
282 SizeSE - lower right corner
283 SizeNE - upper right corner
284 Events
286 Activate
287 Triggered when the user activates a window. Activation mark is
288 usually resides on a window that contains keyboard focus.
289 The module does not provide the activation function; "select()"
291 call is used instead.
292 Deactivate
294 Triggered when the user deactivates a window. Window is usually
295 marked inactive, when it contains no keyboard focus.
296 The module does not provide the de-activation function;
298 "deselect()" call is used instead.
299 WindowState STATE
301 Triggered when window state is changed, either by an explicit
302 "windowState()" call, or by the user. STATE is the new window
303 state, one of three "ws::XXX" constants.
304
306 Methods
307 The package contains several methods for a class that is to be used as
308 a MDI windows owner. It is enough to add class inheritance to
309 "Prima::MDIMethods" to use the functionality. This step, however, is
310 not required for a widget to become a MDI windows owner; the package
311 contains helper functions only, which mostly mirror the arrangement
312 functions of "Prima::MDI" class.
313 mdi_activate
315 Repaints window title in all children MDI windows.
316 mdis
318 Returns array of children MDI windows.
319 arrange_icons
321 Same as "Prima::MDI::arrange_icons".
322 cascade
324 Same as "Prima::MDI::cascade".
325 tile
327 Same as "Prima::MDI::tile".
328
330 A predeclared descendant class of "Prima::Widget" and
331 "Prima::MDIMethods".
332
334 A pre-declared descendant class of "Prima::Window" and
335 "Prima::MDIMethods".
336
338 Dmitry Karasik, <dmitry@karasik.eu.org>.
339
341 Prima, Prima::Widget, Prima::Window, Prima::DockManager,
342 examples/mdi.pl
343perl v5.28.0 2017-02-28 Prima::MDI(3)