1pod::Prima::Window(3) User Contributed Perl Documentationpod::Prima::Window(3)
2
6 Prima::Window - top-level window management
7
9 use Prima;
10 use Prima::Application;
11 # this window, when closed, terminated the application
13 my $main = Prima::MainWindow-> new( text => 'Hello world' );
14 # this is a modal window
16 my $dialog = Prima::Dialog->create( size => [ 100, 100 ]);
17 my $result = $dialog-> execute;
18 $dialog-> destroy;
19 run Prima;
21
23 Prima::Window is a descendant of Prima::Widget class. It deals with
24 top-level windows, the windows that are specially treated by the
25 system. Its major difference from Prima::Widget is that instances of
26 Prima::Window can only be inferior by the screen, not the other
27 windows, and that the system or window manager add decorations to these
28 - usually menus, buttons and title bars. Prima::Window provides methods
29 that communicate with the system and hint these decorations.
30
32 A typical program communicates with the user with aid of widgets,
33 collected upon one or more top-level windows. Prima::Widget already
34 has all functionality required for these child-parent operations, so
35 Prima::Window is not special in respect of widget grouping and
36 relationship. Its usage therefore is straightforward:
37 my $w = Prima::Window-> create(
39 size => [300,300],
40 text => 'Startup window',
41 );
42 There are more about Prima::Window in areas, that it is specifically
44 designed to - the system window management and the dialog execution.
45 System window management
47 As noted before, top-level windows are special for the system, not only
48 in their 'look', but also in 'feel': the system adds specific functions
49 to the windows, aiding the user to navigate through the desktop. The
50 system ofter dictates the size and position for windows, and some times
51 these rules are hard or even impossible to circumvent. This document
52 will be long if it would venture to describe the features of different
53 window management systems, and the task would be never accomplished -
54 brand new window managers emerge every month, and the old change their
55 behavior in an unpredictable way. The only golden rule is to never rely
56 on the behavior of one window manager, and test programs with at least
57 two.
58 The Prima toolkit provides simple access to buttons, title bar and
60 borders of a window. Buttons and title bar are managed by the
61 "::borderIcons" property, and borders by the "::borderStyle" property.
62 These operate with set of predefined constants, "bi::XXX" and
63 "bs::XXX", correspondingly. The button constants can be combined with
64 each other, but not all combinations may be granted by the system. The
65 same is valid also for the border constant, except that they can not be
66 combined - the value of "::borderStyle" is one of the integer
67 constants.
68 There are other hints that the toolkit can set for a window manager.
70 The system can be supplied with an icon that a window is bound to; the
71 icon dimensions are much different, and although can be requested via
72 "sv::XIcon" and "sv::YIcon" system values, the "::icon" property scales
73 the image automatically to the closest system-recognizable dimension.
74 The window icon is not shown by the toolkit, it is usually resides in
75 the window decorations and sometimes on a task bar, along with the
76 window's name. The system can be hinted to not reflect the window on
77 the task bar, by setting the "::taskListed" property to 0.
78 Another issue is the window positioning. Usually, if no explicit
80 position was given, the window is positioned automatically by the
81 system. The same is valid for the size. But some window managers bend
82 it to the extreme - for example, default CDE setup force the user to
83 set newly created windows' positions explicitly. However, there is at
84 least one point of certainty. Typically, when the initial size and/or
85 position of a top-level window are expected to be set by the system,
86 the "::originDontCare" and "::sizeDontCare" properties can be set to 1
87 during window creation. If these set, the system is asked to
88 size/position a window regarding its own windowing policy. The reverse
89 is not always true, unfortunately. Either if these properties set to
90 0, or explicit size or positions are given, the system is hinted to use
91 these values instead, but this does not always happen. Actually, this
92 behavior is expected by the user and often does not get even noticed as
93 something special. Therefore it is a good practice to test a top-level
94 windowing code with several window managers.
95 There are different policies about window positioning and sizing; some
97 window managers behave best when the position is given to the window
98 with the system-dependent decorations. It is hardly can be called a
99 good policy, since it is not possible to calculate the derived window
100 coordinates with certainty. This problem results in that it is
101 impossible to be sure about window position and size before these are
102 set explicitly. The only, not much efficient help the toolkit can
103 provide is the property pair "::frameOrigin" and "::frameSize", which
104 along with "::origin" and "::size" reflect the position and size of a
105 window, but taking into account the system-dependent decorations.
106 Dialog execution
108 Method of Prima::Window, "execute()" brings a window in a modal state
109 on top of other toolkit windows, and returns after the window is
110 dismissed in one or another way. This method is special as it is an
111 implicit event loop, similar to
112 run Prima;
114 code. The event flow is not disrupted, but the windows and widgets that
116 do not belong to the currently executed, the 'modal' window group can
117 not be activated. There can be many modal windows on top of each other,
118 but only one is accessible. As an example a message box can be
119 depicted, a window that prevents the user to work with the application
120 windows until dismissed. There can be other message boxes on top of
121 each other, preventing the windows below from operation as well. This
122 scheme is called the 'exclusive' modality.
123 The toolkit also provides the shared modality scheme, where there can
125 be several stacks of modal windows, not interfering with each other.
126 Each window stack is distinct and contains its own windows. An example
127 analogy is when several independent applications run with modal message
128 boxes being activated. This scheme, however, can not be achieved with
129 single execute()-like call without creating interlocking conditions.
130 The shared model call, "execute_shared()", inserts the window into the
131 shared modal stack, activates the window and returns immediately.
132 The both kinds of modal windows can coexist, but the exclusive windows
134 prevents the shared from operation; while there are exclusive windows,
135 the shared have same rights as the usual windows.
136 The stacking order for these two models is slightly different. A
138 window after execute() call is set on top of the last exclusive modal
139 window, or, in other words, is added to the exclusive window stack.
140 There can be only one exclusive window stack, but many shared window
141 stacks; a window after execute_shared() call is added to a shared
142 window stack, to the one the window's owner belongs to. The shared
143 window stacks are rooted in so-called modal horizons, windows with
144 boolean property "::modalHorizon" set to "true". The default horizon is
145 "::application".
146 A window in modal state can return to the normal (non-modal) state by
148 calling "end_modal()" method. The window is then hidden and disabled,
149 and the windows below are accessible to the user. If the window was in
150 the exclusive modal state, the execute() call is finished and returns
151 the exit code, the value of "::modalResult" property. There two
152 shortuct methods that end modal state, setting "::modalResult" to the
153 basic 'ok' and 'not ok' code, correspondingly "ok()" and "cancel()"
154 methods. Behavior of "cancel()" is identical to when the user closes
155 the modal window by clicking the system close button, pressing Escape
156 key, or otherwise cancelling the dialog execution. "ok()" sets
157 "::modalResult" to "mb::OK", "cancel()" to "mb::Cancel",
158 correspondingly. There are more "mb::XXX" constants, but these have no
159 special meaning, any integer value can be passed. For example,
160 "Prima::MsgBox::message" method uses these constants so the message
161 window can return up to four different "mb" codes.
162 Menu
164 A top-level window can be equipped with a menu bar. Its outlook is
165 system-dependent, but can be controlled by the toolkit up to a certain
166 level. The "::menuItems" property, that manages the menu items of a
167 "::menu" object of Prima::Menu class, arrange the layout of the menu.
168 The syntax of the items-derived properties is described in Prima::Menu,
169 but it must be reiterated that menu items contain only hints, not
170 requests for their exact representation. The same is valid for the
171 color and font properties, "::menuColorIndex" and "::menuFont".
172 Only one menu at a time can be displayed in a top-level window,
174 although a window can be an owner for many menu objects. The key
175 property is "Prima::Menu::selected" - if a menu object is selected on a
176 widget or a window object, it refers to the default menu actions,
177 which, in case of Prima::Window is being displayed as menu bar.
178 NB: A window can be an owner for several menu objects and still do not
180 have a menu bar displayed, if no menu objects are marked as selected.
181 Prima::Dialog
183 Prima::Dialog, a descendant from Prima::Window, introduces no new
184 functionality. It has its default values adjusted so the colors use
185 more appropriate system colors, and hints the system that the outlook
186 of a window is to be different, to resemble the system dialogs on
187 systems where such are provided.
188 Prima::MainWindow
190 The class is a simple descendant of Prima::Window, which overloads
191 "on_destroy" notification and calls "$application->close" inside it.
192 The purpose of declaration of a separate class for such a trifle
193 difference is that many programs are designed under a paradigm where
194 these is a main window, which is most 'important' to the user. As such
195 the construct is used more often than any other, it is considered an
196 optimization to write
197 Prima::MainWindow-> create( ... )
199 rather than
201 Prima::Window-> create( ...,
203 mainWindow => 1,
204 onDestroy => sub { $::application-> close }
205 )
206 , although these lines are equivalent.
208 Also, the $::main_window is pointed to a newly created main window.
210 See also "mainWindow".
212
214 Properties
215 borderIcons INTEGER
216 Hints the system about window's decorations, by selecting the
217 combination of "bi::XXX" constants. The constants are:
218 bi::SystemMenu - system menu button and/or close button
220 ( usually with icon ) is shown
221 bi::Minimize - minimize button
222 bi::Maximize - maximize ( and eventual restore )
223 bi::TitleBar - window title
224 bi::All - all of the above
225 Not all systems respect these hints, and many systems provide more
227 navigating decoration controls than these.
228 borderStyle STYLE
230 Hints the system about window's border style, by selecting one of
231 "bs::XXX" constants. The constants are:
232 bs::None - no border
234 bs::Single - thin border
235 bs::Dialog - thick border
236 bs::Sizeable - thick border with interactive resize capabilities
237 "bs::Sizeable" is an unique window mode. If selected, the user can
239 resize the window, not only by dragging the window borders with the
240 mouse but by other system-dependent means. The other border styles
241 disallow interactive resizing.
242 Not all systems recognize all these hints, although many recognize
244 interactive resizing flag.
245 effects HASH or undef
247 This generic property implements system-specific window effects,
248 not necessarily portable. The format of the hash is also system-
249 specific. The only portable behavior here is that setting the value
250 to "undef" cancels all effects.
251 Example:
253 $window->effects({
255 effect1 => {
256 key1 => $value1,
257 ...
258 },
259 });
260 Currently, the following effects are implemented:
262 dwm_blur enable => $BOOL, transition_on_maximized => $BOOL, mask =>
264 $Prima::Region
265 This effect is implemented only on Win32 version 7 or later,
266 using Win32 API call DwmEnableBlurBehindWindow
267 <http://msdn.microsoft.com/en-
268 us/library/windows/desktop/aa969508>. See the MS reference for
269 details.
270 To determine whether this effect is available or not, use
272 "$::application->get_system_value(sv::DWM)" call. See
273 examples/dwm_blur.pl for example of use.
274 frameHeight HEIGHT
276 Maintains the height of a window, including the window decorations.
277 frameOrigin X_OFFSET, Y_OFFSET
279 Maintains the left X and bottom Y boundaries of a window's
280 decorations relative to the screen.
281 frameSize WIDTH, HEIGHT
283 Maintains the width and height of a window, including the window
284 decorations.
285 frameWidth WIDTH
287 Maintains the width of a window, including the window decorations.
288 icon OBJECT
290 Hints the system about an icon, associated with a window. If
291 OBJECT is "undef", the system-default icon is assumed.
292 See also: "ownerIcon"
294 mainWindow BOOLEAN
296 Tells the system that the window is the main window for the
297 application. When dialogs and modal windows are not anchored to
298 any specific window, the main window is used. In this context,
299 anchoring means that if, for example, a window spawns a dialog, and
300 then is minimized or obscured, and then the user clicks on either
301 window, both can be brought forward (also in correct Z-order) by
302 the system window manager.
303 menu OBJECT
305 Manages a Prima::Menu object associated with a window.
306 Prima::Window can host many Prima::Menu objects, but only the one
307 that is set in "::menu" property will be seen as a menu bar.
308 See also: "Prima::Menu", "menuItems"
310 menuColorIndex INDEX, COLOR
312 Maintains eight color properties of a menu, associated with a
313 window. INDEX must be one of "ci::XXX" constants ( see
314 Prima::Widget, colorIndex section ).
315 See also: "menuItems", "menuFont", "menu"
317 menuColor COLOR
319 Basic foreground menu color.
320 See also: "menuItems", "menuColorIndex", "menuFont", "menu"
322 menuBackColor COLOR
324 Basic background menu color.
325 See also: "menuItems", "menuColorIndex", "menuFont", "menu"
327 menuDark3DColor COLOR
329 Color for drawing dark shadings in menus.
330 See also: "menuItems", "menuColorIndex", "menuFont", "menu"
332 menuDisabledColor COLOR
334 Foreground color for disabled items in menus.
335 See also: "menuItems", "menuColorIndex", "menuFont", "menu"
337 menuDisabledBackColor COLOR
339 Background color for disabled items in menus.
340 See also: "menuItems", "menuColorIndex", "menuFont", "menu"
342 menuFont %FONT
344 Maintains the font of a menu, associated with a window.
345 See also: "menuItems", "menuColorIndex", "menu"
347 menuHiliteColor COLOR
349 Foreground color for selected items in menus.
350 See also: "menuItems", "menuColorIndex", "menuFont", "menu"
352 menuHiliteBackColor COLOR
354 Background color for selected items in menus.
355 See also: "menuItems", "menuColorIndex", "menuFont", "menu"
357 menuItems [ ITEM_LIST ]
359 Manages items of a Prima::Menu object associated with a window.
360 The ITEM_LIST format is same as "Prima::AbstractMenu::items" and is
361 described in Prima::Menu.
362 See also: "menu", "menuColorIndex", "menuFont"
364 menuLight3DColor COLOR
366 Color for drawing light shadings in menus.
367 See also: "menuItems", "menuColorIndex", "menuFont", "menu"
369 modalHorizon BOOLEAN
371 Reflects if a window serves as root to the shared modal window
372 stack. A window with "::modalHorizon" set to 1 in shared modal
373 state groups its children windows in a window stack, separate from
374 other shared modal stacks. The "::modalHorizon" is therefore useful
375 only when several shared modal window stacks are needed.
376 The property also serves as an additional grouping factor for
378 widgets and windows. For example, default keyboard navigation by
379 tab and arrow keys is limited to the windows and widgets of a
380 single window stack.
381 modalResult INTEGER
383 Maintains a custom integer value, returned by "execute()".
384 Historically it is one of "mb::XXX" constants, but any integer
385 value can be used. The most useful "mb::" constants are:
386 mb::OK, mb::Ok
388 mb::Cancel
389 mb::Yes
390 mb::No
391 mb::Abort
392 mb::Retry
393 mb::Ignore
394 mb::Help
395 NB: These constants are defined so they can be bitwise-or'ed, and
397 Prima::MsgBox package uses this feature, where one of its functions
398 parameters is a combination of "mb::" constants.
399 onTop BOOLEAN
401 If set, the window is hinted to stay on top of all other windows.
402 Default value: 0
404 ownerIcon BOOLEAN
406 If 1, the icon is synchronized with the owner's. Automatically set
407 to 0 if "::icon" property is explicitly set. Default value is 1,
408 so assigning an icon to $::application spawns the icon to all
409 windows.
410 taskListed BOOLEAN
412 If set to 0, hints the system against reflecting existence of a
413 window into a system task bar, or a top-level window list, or
414 otherwise lower the window's value before the other windows. If 1,
415 does not hint anything.
416 Default value: 1
418 windowState STATE
420 A three-state property, that governs the state of a window. STATE
421 can be one of three "ws::XXX" constants:
422 ws::Normal
424 ws::Minimized
425 ws::Maximized
426 There can be more or less, or other window states provided by the
428 system, but these three were chosen as a 'least common
429 denominator'. The property can be changed either by explicit set-
430 mode call or by the user. In either case, a "WindowState"
431 notification is triggered.
432 The property has three convenience wrappers: "maximize()",
434 "minimize()" and "restore()".
435 See also: "WindowState"
437 Methods
439 cancel
440 A standard method to dismiss a modal window with "mb::Cancel"
441 result. The effect of calling this method is equal to when the user
442 selects a 'close window' action with system-provided menu, button
443 or other tool.
444 See also: "ok", "modalResult", "execute", "execute_shared"
446 end_modal
448 If a window is in modal state, the "EndModal" notification is
449 activated. Then the window is returned from the modal state, gets
450 hidden and disabled. If the window was on top in the exclusive
451 modal state, the last called "execute()" function finishes. If the
452 window was not on top in the exclusive modal state, the
453 corresponding "execute()" function finishes after all subsequent
454 execute() calls are finished.
455 execute INSERT_BEFORE = undef
457 A window is turned to the exclusive modal state and is put on top
458 of non-modal and shared-modal windows. By default, if
459 INSERT_BEFORE object is undef, the window is also put on top of
460 other exclusive-modal windows; if INSERT_BEFORE is one of the
461 exclusive-modal windows the window is placed in queue before the
462 INSERT_BEFORE window. The window is showed and enabled, if
463 necessary, and "Execute" notification is triggered.
464 The function is returned when a window is dismissed, or if the
466 system-dependent 'exit'-event is triggered by the user ( the latter
467 case falls through all execute() calls and terminates "run Prima;"
468 call, exiting gracefully).
469 execute_shared INSERT_BEFORE = undef
471 A window is turned to the shared modal state and is put on top of
472 non-modal windows in the stack of its "::modalHorizon". A window
473 with "::modalHorizon" set to 1 starts its own stack, independent of
474 all other window stacks.
475 By default, if INSERT_BEFORE object is undef, the window is also
477 put on top of other shared-modal windows in its stack. If
478 INSERT_BEFORE is one of the shared-modal windows in its stack, the
479 window is placed in queue before the INSERT_BEFORE window.
480 The window is showed and enabled, if necessary, and "Execute"
482 notification is triggered.
483 The function is returned immediately.
485 get_client_handle
487 Returns a system handle for a system window that is inserted in
488 top-level windows and covers all of its area. Is different from
489 "Window::get_handle" in that it returns the system handle of the
490 top-level window itself. In other terms, window returned by this
491 function is a child of the window returned by "Window::get_handle".
492 See also: "get_handle"
494 get_default_menu_font
496 Returns the default font for a Prima::Menu class.
497 get_modal
499 Returns one of three constants, reflecting the modal state of a
500 window:
501 mt::None
503 mt::Shared
504 mt::Exclusive
505 Value of "mt::None" is 0, so result of get_modal() can be also
507 treated as a boolean value, if only the fact of modality is needed
508 to check.
509 get_modal_window MODALITY_TYPE = mt::Exclusive, NEXT = 1
511 Returns a modal window, that is next to the given window in the
512 modality chain. MODALITY_TYPE selects the chain, and can be either
513 "mt::Exclusive" or "mt::Shared". NEXT is a boolean flag, selecting
514 the lookup direction; if it is 1, the 'upper' window is returned,
515 if 0, the 'lower' one ( in a simple case when window A is made
516 modal (executed) after modal window B, the A window is the 'upper'
517 one ).
518 If a window has no immediate modal relations, "undef" is returned.
520 maximize
522 Maximizes window. A shortcut for "windowState(ws::Maximized)".
523 minimize
525 Minimizes window. A shortcut for "windowState(ws::Minimized)".
526 ok A standard method to dismiss a modal window with "mb::OK" result.
528 Typically the effect of calling this method is equal to when the
529 user presses the enter key of a modal window, signaling that the
530 default action is to be taken.
531 See also: "cancel", "modalResult", "execute", "execute_shared"
533 restore
535 Restores window to normal state from minimized or maximized state.
536 A shortcut for "windowState(ws::Normal)".
537 Events
539 Activate
540 Triggered when a window is activated by the user. Activation mark
541 is usually resides on a window that contains keyboard focus, and is
542 usually reflected by highlighted system decorations.
543 The toolkit does not provide standalone activation functions;
545 "select()" call is used instead.
546 Deactivate
548 Triggered when a window is deactivated by the user. Window is
549 usually marked inactive, when it contains no keyboard focus.
550 The toolkit does not provide standalone de-activation functions;
552 "deselect()" call is used instead.
553 EndModal
555 Called before a window leaves modal state.
556 Execute
558 Called after a window enters modal state.
559 SysHandle
561 Same as in "Widget", but it addition to the Widget properties that
562 may trigger the event, the following "Window" properties can
563 trigger it as well: taskListed, borderIcons, borderStyle, onTop
564 WindowState STATE
566 Triggered when window state is changed, either by an explicit
567 "windowState()" call, or by the user. STATE is the new window
568 state, one of three "ws::XXX" constants.
569
571 Dmitry Karasik, <dmitry@karasik.eu.org>.
572
574 Prima, Prima::Object, Prima::Drawable, Prima::Widget.
575perl v5.32.0 2020-07-28 pod::Prima::Window(3)