1pod::Prima::Window(3) User Contributed Perl Documentationpod::Prima::Window(3)
2
3
4

NAME

6       Prima::Window - top-level window management
7

SYNOPSIS

9          use Prima;
10          use Prima::Application;
11
12          # this window, when closed, terminated the application
13          my $main = Prima::MainWindow-> new( text => 'Hello world' );
14
15          # this is a modal window
16          my $dialog = Prima::Dialog->create( size => [ 100, 100 ]);
17          my $result = $dialog-> execute;
18          $dialog-> destroy;
19
20          run Prima;
21

DESCRIPTION

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

USAGE

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
38          my $w = Prima::Window-> create(
39              size => [300,300],
40              text => 'Startup window',
41          );
42
43       There are more about Prima::Window in areas, that it is specifically
44       designed to - the system window management and the dialog execution.
45
46   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
59       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
69       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
79       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
96       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
107   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
113         run Prima;
114
115       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
124       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
133       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
137       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
147       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
163   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
173       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
179       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
182   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
189   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
198          Prima::MainWindow-> create( ... )
199
200       rather than
201
202          Prima::Window-> create( ...,
203             mainWindow => 1,
204             onDestroy  => sub { $::application-> close }
205          )
206
207       , although these lines are equivalent.
208
209       Also, the $::main_window is pointed to a newly created main window.
210
211       See also "mainWindow".
212

API

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
219              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
226           Not all systems respect these hints, and many systems provide more
227           navigating decoration controls than these.
228
229       borderStyle STYLE
230           Hints the system about window's border style, by selecting one of
231           "bs::XXX" constants. The constants are:
232
233              bs::None      - no border
234              bs::Single    - thin border
235              bs::Dialog    - thick border
236              bs::Sizeable  - thick border with interactive resize capabilities
237
238           "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
243           Not all systems recognize all these hints, although many recognize
244           interactive resizing flag.
245
246       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
252           Example:
253
254              $window->effects({
255                  effect1 => {
256                     key1 => $value1,
257                     ...
258                  },
259              });
260
261           Currently, the following effects are implemented:
262
263           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
271               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
275       frameHeight HEIGHT
276           Maintains the height of a window, including the window decorations.
277
278       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
282       frameSize WIDTH, HEIGHT
283           Maintains the width and height of a window, including the window
284           decorations.
285
286       frameWidth WIDTH
287           Maintains the width of a window, including the window decorations.
288
289       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
293           See also: "ownerIcon"
294
295       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
304       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
309           See also: "Prima::Menu", "menuItems"
310
311       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
316           See also: "menuItems", "menuFont", "menu"
317
318       menuColor COLOR
319           Basic foreground menu color.
320
321           See also: "menuItems", "menuColorIndex", "menuFont", "menu"
322
323       menuBackColor COLOR
324           Basic background menu color.
325
326           See also: "menuItems", "menuColorIndex", "menuFont", "menu"
327
328       menuDark3DColor COLOR
329           Color for drawing dark shadings in menus.
330
331           See also: "menuItems", "menuColorIndex", "menuFont", "menu"
332
333       menuDisabledColor COLOR
334           Foreground color for disabled items in menus.
335
336           See also: "menuItems", "menuColorIndex", "menuFont", "menu"
337
338       menuDisabledBackColor COLOR
339           Background color for disabled items in menus.
340
341           See also: "menuItems", "menuColorIndex", "menuFont", "menu"
342
343       menuFont %FONT
344           Maintains the font of a menu, associated with a window.
345
346           See also: "menuItems", "menuColorIndex", "menu"
347
348       menuHiliteColor COLOR
349           Foreground color for selected items in menus.
350
351           See also: "menuItems", "menuColorIndex", "menuFont", "menu"
352
353       menuHiliteBackColor COLOR
354           Background color for selected items in menus.
355
356           See also: "menuItems", "menuColorIndex", "menuFont", "menu"
357
358       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
363           See also: "menu", "menuColorIndex", "menuFont"
364
365       menuLight3DColor COLOR
366           Color for drawing light shadings in menus.
367
368           See also: "menuItems", "menuColorIndex", "menuFont", "menu"
369
370       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
377           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
382       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
387              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
396           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
400       onTop BOOLEAN
401           If set, the window is hinted to stay on top of all other windows.
402
403           Default value: 0
404
405       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
411       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
417           Default value: 1
418
419       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
423              ws::Normal
424              ws::Minimized
425              ws::Maximized
426
427           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
433           The property has three convenience wrappers: "maximize()",
434           "minimize()" and "restore()".
435
436           See also: "WindowState"
437
438   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
445           See also: "ok", "modalResult", "execute", "execute_shared"
446
447       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
456       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
465           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
470       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
476           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
481           The window is showed and enabled, if necessary, and "Execute"
482           notification is triggered.
483
484           The function is returned immediately.
485
486       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
493           See also: "get_handle"
494
495       get_default_menu_font
496           Returns the default font for a Prima::Menu class.
497
498       get_modal
499           Returns one of three constants, reflecting the modal state of a
500           window:
501
502              mt::None
503              mt::Shared
504              mt::Exclusive
505
506           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
510       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
519           If a window has no immediate modal relations,  "undef" is returned.
520
521       maximize
522           Maximizes window. A shortcut for "windowState(ws::Maximized)".
523
524       minimize
525           Minimizes window. A shortcut for "windowState(ws::Minimized)".
526
527       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
532           See also: "cancel", "modalResult", "execute", "execute_shared"
533
534       restore
535           Restores window to normal state from minimized or maximized state.
536           A shortcut for "windowState(ws::Normal)".
537
538   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
544           The toolkit does not provide standalone activation functions;
545           "select()" call is used instead.
546
547       Deactivate
548           Triggered when a window is deactivated by the user.  Window is
549           usually marked inactive, when it contains no keyboard focus.
550
551           The toolkit does not provide standalone de-activation functions;
552           "deselect()" call is used instead.
553
554       EndModal
555           Called before a window leaves modal state.
556
557       Execute
558           Called after a window enters modal state.
559
560       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
565       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

AUTHOR

571       Dmitry Karasik, <dmitry@karasik.eu.org>.
572

SEE ALSO

574       Prima, Prima::Object, Prima::Drawable, Prima::Widget.
575
576
577
578perl v5.32.0                      2020-07-28             pod::Prima::Window(3)
Impressum