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 often 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 on
109       top of other toolkit windows, and returns after the window is dismissed
110       in one or another way.  This method is special as it is an implicit
111       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, and
149       the windows below are accessible to the user. If the window was in the
150       exclusive modal state, the execute() call is finished and returns the
151       exit code, the value of "::modalResult" property. There two shortcut
152       methods that end modal state, setting "::modalResult" to the basic 'ok'
153       and 'not ok' code, correspondingly ok() and cancel() methods. Behavior
154       of cancel() is identical to when the user closes the modal window by
155       clicking the system close button, pressing Escape key, or otherwise
156       canceling the dialog execution. ok() sets "::modalResult" to "mb::OK",
157       cancel() to "mb::Cancel", correspondingly.  There are more "mb::XXX"
158       constants, but these have no special meaning, any integer value can be
159       passed. For example, "Prima::MsgBox::message" method uses these
160       constants so the message window can return up to four different "mb"
161       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           Previously this was the mechanism for setting the DWM blur on
262           Windows 7 and 8, but as Windows 10 removed it, this capability was
263           also removed, so as for now this is basically an empty call.
264
265       frameHeight HEIGHT
266           Maintains the height of a window, including the window decorations.
267
268       frameOrigin X_OFFSET, Y_OFFSET
269           Maintains the left X and bottom Y boundaries of a window's
270           decorations relative to the screen.
271
272       frameSize WIDTH, HEIGHT
273           Maintains the width and height of a window, including the window
274           decorations.
275
276       frameWidth WIDTH
277           Maintains the width of a window, including the window decorations.
278
279       icon OBJECT
280           Hints the system about an icon, associated with a window.  If
281           OBJECT is "undef", the system-default icon is assumed.
282
283           See also: "ownerIcon"
284
285       mainWindow BOOLEAN
286           Tells the system that the window is the main window for the
287           application.  When dialogs and modal windows are not anchored to
288           any specific window, the main window is used. In this context,
289           anchoring means that if, for example, a window spawns a dialog, and
290           then is minimized or obscured, and then the user clicks on either
291           window, both can be brought forward (also in correct Z-order) by
292           the system window manager.
293
294       menu OBJECT
295           Manages a Prima::Menu object associated with a window.
296           Prima::Window can host many Prima::Menu objects, but only the one
297           that is set in "::menu" property will be seen as a menu bar.
298
299           See also: "Prima::Menu", "menuItems"
300
301       menuColorIndex INDEX, COLOR
302           Maintains eight color properties of a menu, associated with a
303           window. INDEX must be one of "ci::XXX" constants ( see
304           Prima::Widget, colorIndex section ).
305
306           See also: "menuItems", "menuFont", "menu"
307
308       menuColor COLOR
309           Basic foreground menu color.
310
311           See also: "menuItems", "menuColorIndex", "menuFont", "menu"
312
313       menuBackColor COLOR
314           Basic background menu color.
315
316           See also: "menuItems", "menuColorIndex", "menuFont", "menu"
317
318       menuDark3DColor COLOR
319           Color for drawing dark shadings in menus.
320
321           See also: "menuItems", "menuColorIndex", "menuFont", "menu"
322
323       menuDisabledColor COLOR
324           Foreground color for disabled items in menus.
325
326           See also: "menuItems", "menuColorIndex", "menuFont", "menu"
327
328       menuDisabledBackColor COLOR
329           Background color for disabled items in menus.
330
331           See also: "menuItems", "menuColorIndex", "menuFont", "menu"
332
333       menuFont %FONT
334           Maintains the font of a menu, associated with a window.
335
336           See also: "menuItems", "menuColorIndex", "menu"
337
338       menuHiliteColor COLOR
339           Foreground color for selected items in menus.
340
341           See also: "menuItems", "menuColorIndex", "menuFont", "menu"
342
343       menuHiliteBackColor COLOR
344           Background color for selected items in menus.
345
346           See also: "menuItems", "menuColorIndex", "menuFont", "menu"
347
348       menuItems [ ITEM_LIST ]
349           Manages items of a Prima::Menu object associated with a window.
350           The ITEM_LIST format is same as "Prima::AbstractMenu::items" and is
351           described in Prima::Menu.
352
353           See also: "menu", "menuColorIndex", "menuFont"
354
355       menuLight3DColor COLOR
356           Color for drawing light shadings in menus.
357
358           See also: "menuItems", "menuColorIndex", "menuFont", "menu"
359
360       modalHorizon BOOLEAN
361           Reflects if a window serves as root to the shared modal window
362           stack.  A window with "::modalHorizon" set to 1 in shared modal
363           state groups its children windows in a window stack, separate from
364           other shared modal stacks. The "::modalHorizon" is therefore useful
365           only when several shared modal window stacks are needed.
366
367           The property also serves as an additional grouping factor for
368           widgets and windows. For example, default keyboard navigation by
369           tab and arrow keys is limited to the windows and widgets of a
370           single window stack.
371
372       modalResult INTEGER
373           Maintains a custom integer value, returned by execute().
374           Historically it is one of "mb::XXX" constants, but any integer
375           value can be used. The most useful "mb::" constants are:
376
377              mb::OK, mb::Ok
378              mb::Cancel
379              mb::Yes
380              mb::No
381              mb::Abort
382              mb::Retry
383              mb::Ignore
384              mb::Help
385
386           NB: These constants are defined so they can be bitwise-or'ed, and
387           Prima::MsgBox package uses this feature, where one of its functions
388           parameters is a combination of "mb::" constants.
389
390       onTop BOOLEAN
391           If set, the window is hinted to stay on top of all other windows.
392
393           Default value: 0
394
395       ownerIcon BOOLEAN
396           If 1, the icon is synchronized with the owner's.  Automatically set
397           to 0 if "::icon" property is explicitly set.  Default value is 1,
398           so assigning an icon to $::application spawns the icon to all
399           windows.
400
401       taskListed BOOLEAN
402           If set to 0, hints the system against reflecting existence of a
403           window into a system task bar, or a top-level window list, or
404           otherwise lower the window's value before the other windows. If 1,
405           does not hint anything.
406
407           Default value: 1
408
409       windowState STATE
410           A three-state property, that governs the state of a window.  STATE
411           can be one of four "ws::XXX" constants:
412
413              ws::Normal
414              ws::Minimized
415              ws::Maximized
416              ws::Fullscreen
417
418           There can be more or less, or other window states provided by the
419           system, but these four were chosen as a 'least common denominator'.
420           The property can be changed either by explicit set-mode call or by
421           the user. In either case, a "WindowState" notification is
422           triggered.
423
424           The property has three convenience wrappers: maximize(),
425           minimize(), restore(), and fullscreen().
426
427           See also: "WindowState"
428
429   Methods
430       cancel
431           A standard method to dismiss a modal window with "mb::Cancel"
432           result. The effect of calling this method is equal to when the user
433           selects a 'close window' action with system-provided menu, button
434           or other tool.
435
436           See also: "ok", "modalResult", "execute", "execute_shared"
437
438       end_modal
439           If a window is in modal state, the "EndModal" notification is
440           activated.  Then the window is returned from the modal state, gets
441           hidden and disabled.  If the window was on top in the exclusive
442           modal state, the last called execute() function finishes.  If the
443           window was not on top in the exclusive modal state, the
444           corresponding execute() function finishes after all subsequent
445           execute() calls are finished.
446
447       execute INSERT_BEFORE = undef
448           A window is turned to the exclusive modal state and is put on top
449           of non-modal and shared-modal windows.  By default, if
450           INSERT_BEFORE object is undef, the window is also put on top of
451           other exclusive-modal windows; if INSERT_BEFORE is one of the
452           exclusive-modal windows the window is placed in queue before the
453           INSERT_BEFORE window.  The window is showed and enabled, if
454           necessary, and "Execute" notification is triggered.
455
456           The function is returned when a window is dismissed, or if the
457           system-dependent 'exit'-event is triggered by the user ( the latter
458           case falls through all execute() calls and terminates "run Prima;"
459           call, exiting gracefully).
460
461       execute_shared INSERT_BEFORE = undef
462           A window is turned to the shared modal state and is put on top of
463           non-modal windows in the stack of its "::modalHorizon". A window
464           with "::modalHorizon" set to 1 starts its own stack, independent of
465           all other window stacks.
466
467           By default, if INSERT_BEFORE object is undef, the window is also
468           put on top of other shared-modal windows in its stack.  If
469           INSERT_BEFORE is one of the shared-modal windows in its stack, the
470           window is placed in queue before the INSERT_BEFORE window.
471
472           The window is showed and enabled, if necessary, and "Execute"
473           notification is triggered.
474
475           The function is returned immediately.
476
477       fullscreen
478           Sets window in a fullscreen mode. A shortcut for
479           windowState(ws::Fullscreen).
480
481       get_client_handle
482           Returns a system handle for a system window that is inserted in
483           top-level windows and covers all of its area. Is different from
484           "Window::get_handle" in that it returns the system handle of the
485           top-level window itself. In other terms, window returned by this
486           function is a child of the window returned by "Window::get_handle".
487
488           See also: "get_handle"
489
490       get_default_menu_font
491           Returns the default font for a Prima::Menu class.
492
493       get_modal
494           Returns one of three constants, reflecting the modal state of a
495           window:
496
497              mt::None
498              mt::Shared
499              mt::Exclusive
500
501           Value of "mt::None" is 0, so result of get_modal() can be also
502           treated as a boolean value, if only the fact of modality is needed
503           to check.
504
505       get_modal_window MODALITY_TYPE = mt::Exclusive, NEXT = 1
506           Returns a modal window, that is next to the given window in the
507           modality chain. MODALITY_TYPE selects the chain, and can be either
508           "mt::Exclusive" or "mt::Shared". NEXT is a boolean flag, selecting
509           the lookup direction; if it is 1, the 'upper' window is returned,
510           if 0, the 'lower' one ( in a simple case when window A is made
511           modal (executed) after modal window B, the A window is the 'upper'
512           one ).
513
514           If a window has no immediate modal relations,  "undef" is returned.
515
516       maximize
517           Maximizes window. A shortcut for windowState(ws::Maximized).
518
519       minimize
520           Minimizes window. A shortcut for windowState(ws::Minimized).
521
522       ok  A standard method to dismiss a modal window with "mb::OK" result.
523           Typically the effect of calling this method is equal to when the
524           user presses the enter key of a modal window, signaling that the
525           default action is to be taken.
526
527           See also: "cancel", "modalResult", "execute", "execute_shared"
528
529       restore
530           Restores window to normal state from minimized or maximized state.
531           A shortcut for windowState(ws::Normal).
532
533   Events
534       Activate
535           Triggered when a window is activated by the user.  Activation mark
536           is usually resides on a window that contains keyboard focus, and is
537           usually reflected by highlighted system decorations.
538
539           The toolkit does not provide standalone activation functions;
540           select() call is used instead.
541
542       Deactivate
543           Triggered when a window is deactivated by the user.  Window is
544           usually marked inactive, when it contains no keyboard focus.
545
546           The toolkit does not provide standalone de-activation functions;
547           deselect() call is used instead.
548
549       EndModal
550           Called before a window leaves modal state.
551
552       Execute
553           Called after a window enters modal state.
554
555       SysHandle
556           Same as in "Widget", but it addition to the Widget properties that
557           may trigger the event, the following "Window" properties can
558           trigger it as well: taskListed, borderIcons, borderStyle, onTop
559
560       WindowState STATE
561           Triggered when window state is changed, either by an explicit
562           windowState() call, or by the user.  STATE is the new window state,
563           one of three "ws::XXX" constants.
564

AUTHOR

566       Dmitry Karasik, <dmitry@karasik.eu.org>.
567

SEE ALSO

569       Prima, Prima::Object, Prima::Drawable, Prima::Widget.
570
571
572
573perl v5.38.0                      2023-07-21             pod::Prima::Window(3)
Impressum