1Prima::MDI(3)         User Contributed Perl Documentation        Prima::MDI(3)
2
3
4

NAME

6       Prima::MDI - top-level windows emulation classes
7

DESCRIPTION

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
16       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
24       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

SYNOPSIS

29               use Prima qw(Application MDI Buttons);
30
31               my $owner = Prima::MDIWindowOwner-> new;
32               my $mdi   = $owner-> insert( 'Prima::MDI');
33               $mdi-> client-> insert( 'Prima::Button' => centered => 1 );
34
35               run Prima;
36

Prima::MDI

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
42       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
47               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
54       The class mimics API of "Prima::Window" class, and in some extent
55       Prima::Window and this page share the same information.
56
57   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
64                   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
71           Default value: "mbi::All"
72
73       borderStyle INTEGER
74           One of "bs::XXX" constants, selecting the window border style.  The
75           constants are:
76
77                   bs::None      - no border
78                   bs::Single    - thin border
79                   bs::Dialog    - thick border
80                   bs::Sizeable  - thick border with interactive resize capabilities
81
82           "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
86           Default value: "bs::Sizeable"
87
88       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
94           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
98       clientClass STRING
99           Assigns client widget class.
100
101           Create-only property.
102
103           Default value: "Prima::Widget"
104
105       clientProfile HASH
106           Assigns hash of properties, passed to the client during the
107           creation.
108
109           Create-only property.
110
111       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
121           The dragging session can be aborted by hitting Esc key or calling
122           "sizemove_cancel" method.
123
124           Default value: "undef".
125
126       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
130           Default value: 0
131
132       iconMin HANDLE
133           Selects minimized button image in normal state.
134
135       iconMax HANDLE
136           Selects maximized button image in normal state.
137
138       iconClose HANDLE
139           Selects close button image in normal state.
140
141       iconRestore HANDLE
142           Selects restore button image in normal state.
143
144       iconMinPressed HANDLE
145           Selects minimize button image in pressed state.
146
147       iconMaxPressed HANDLE
148           Selects maximize button image in pressed state.
149
150       iconClosePressed HANDLE
151           Selects close button image in pressed state.
152
153       iconRestorePressed HANDLE
154           Selects restore button image in pressed state.
155
156       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
162           Default value: 1
163
164       titleHeight INTEGER
165           Selects height of the title bar in pixels. If 0, the default system
166           value is used.
167
168           Default value: 0
169
170       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
174                   ws::Normal
175                   ws::Minimized
176                   ws::Maximized
177
178           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
182           The property has three convenience wrappers: "maximize()",
183           "minimize()" and "restore()".
184
185           Default value: "ws::Normal"
186
187           See also: "WindowState"
188
189   Methods
190       arrange_icons
191           Arranges geometrically the minimized sibling MDI windows.
192
193       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
199           Only windows with "tileable" property set to 1 are processed.
200
201       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
205       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
209       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
214       keyMove
215           Initiates window moving session, navigated by the keyboard.
216
217       keySize
218           Initiates window resizing session, navigated by the keyboard.
219
220       mdis
221           Returns array of sibling MDI windows.
222
223       maximize
224           Maximizes window. A shortcut for "windowState(ws::Maximized)".
225
226       minimize
227           Minimizes window. A shortcut for "windowState(ws::Minimized)".
228
229       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
236       repaint_title [ STRING = "title" ]
237           Invalidates rectangle on the title bar, corresponding to STRING,
238           which can be one of the following:
239
240                   left    - redraw the menu button
241                   right   - redraw minimize, maximize, and close buttons
242                   title   - redraw the title
243
244       restore
245           Restores window to normal state from minimized or maximized state.
246           A shortcut for "windowState(ws::Normal)".
247
248       sizemove_cancel
249           Cancels active window moving or resizing session and returns the
250           window to the state before the session.
251
252       tile
253           Arranges sibling MDI windows so they form a grid-like structure,
254           where all windows occupy equal space, if possible.
255
256           Only windows with "tileable" property set to 1 are processed.
257
258       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
264                   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
275           In addition, if the window is sizeable, the following constants can
276           be returned, indicating part of the border:
277
278                   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
287   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
292           The module does not provide the activation function; "select()"
293           call is used instead.
294
295       Deactivate
296           Triggered when the user deactivates a window.  Window is usually
297           marked inactive, when it contains no keyboard focus.
298
299           The module does not provide the de-activation function;
300           "deselect()" call is used instead.
301
302       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

Prima::MDIMethods

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
316       mdi_activate
317           Repaints window title in all children MDI windows.
318
319       mdis
320           Returns array of children MDI windows.
321
322       arrange_icons
323           Same as "Prima::MDI::arrange_icons".
324
325       cascade
326           Same as "Prima::MDI::cascade".
327
328       tile
329           Same as "Prima::MDI::tile".
330

Prima::MDIOwner

332       A predeclared descendant class of "Prima::Widget" and
333       "Prima::MDIMethods".
334

Prima::MDIWindowOwner

336       A pre-declared descendant class of "Prima::Window" and
337       "Prima::MDIMethods".
338

AUTHOR

340       Dmitry Karasik, <dmitry@karasik.eu.org>.
341

SEE ALSO

343       Prima, Prima::Widget, Prima::Window, Prima::DockManager,
344       examples/mdi.pl
345
346
347
348perl v5.34.0                      2021-07-22                     Prima::MDI(3)
Impressum