1Prima::Application(3) User Contributed Perl DocumentationPrima::Application(3)
2
3
4

NAME

6       Prima::Application - root of widget objects hierarchy
7

DESCRIPTION

9       Prima::Application class serves as a hierarchy root for all objects
10       with child-owner relationship. All toolkit objects, existing with non-
11       null owner property, belong by their top-level parental relationship to
12       Prima::Application object. There can be only one instance of
13       Prima::Application class at a time.
14

SYNOPSIS

16               use Prima;
17               use Prima::Application;
18
19       or
20
21               use Prima qw(Application);
22
23               Prima::MainWindow-> create();
24
25               run Prima;
26

USAGE

28       Prima::Application class, and its only instance are treated specially
29       throughout the toolkit. The object instance is contained in
30
31               $::application
32
33       scalar, defined in Prima.pm module.  The application instance must be
34       created whenever widget and window, or event loop functionality is
35       desired.  Usually
36
37               use Prima::Application;
38
39       code is enough, but $::application can also be assigned explicitly. The
40       'use' syntax has advantage as more resistant to eventual changes in the
41       toolkit design.  It can also be used in conjunction with custom
42       parameters hash, alike the general create() syntax:
43
44               use Prima::Application name => 'Test application', icon => $icon;
45
46       In addition to this functionality Prima::Application is also a wrapper
47       to a set of system functions, not directly related to object classes.
48       This functionality is generally explained in "API".
49
50   Inherited functionality
51       Prima::Application is a descendant of Prima::Widget, but it is designed
52       so because their functional outliers are closest to each other.
53       Prima::Application does not strictly conform ( in OO sense ) to any of
54       the built-in classes. It has methods copied from both Prima::Widget and
55       Prima::Window at one time, and the inherited Prima::Widget methods and
56       properties function differently.  For example, "::origin", a property
57       from Prima::Widget, is also implemented in Prima::Application, but
58       returns always (0,0), an expected but not much usable result.
59       "::size", on the contrary, returns the extent of the screen in pixels.
60       There are few properties, inherited from Prima::Widget, which return
61       actual, but uninformative results, - "::origin" is one of those, but
62       same are "::buffered", "::clipOwner", "::enabled", "::growMode",
63       "::owner" and owner-inheritance properties, "::selectable", "::shape",
64       "::syncPaint", "::tabOrder", "::tabStop", "::transparent", "::visible".
65       To this group also belongs "::modalHorizon", Prima::Window class
66       property, but defined for consistency and returning always 1.  Other
67       methods and properties, like "::size", that provide different
68       functionality are described in "API".
69
70   Global functionality
71       Prima::Application is a wrapper to functionality, that is not related
72       to one or another class clearly.  A notable example, paint mode, which
73       is derived from Prima::Drawable class, allows painting on the screen,
74       overwriting the graphic information created by the other programs.
75       Although being subject to begin_paint()/end_paint() brackets, this
76       functionality can not be attached to a class-shared API, an therefore
77       is considered global. All such functionality is gathered in the
78       Prima::Application class.
79
80       These topics enumerated below, related to the global scope, but
81       occupying more than one method or property - such functions described
82       in "API".
83
84       Painting
85           As stated above, Prima::Application provides interface to the on-
86           screen painting. This mode is triggered by
87           begin_paint()/end_paint() methods pair, and the other pair,
88           begin_paint_info()/end_paint_info() triggers the information mode.
89           This three-state paint functionality is more thoroughly described
90           in Prima::Drawable.
91
92           The painting on the screen surfaces under certain environments
93           (XQuartz, XWayland) is either silently ignored or results in an
94           error. There, "begin_paint" will return a false value
95           ("begin_paint_info" though returns true).
96
97       Hint
98           $::application hosts a special Prima::HintWidget class object,
99           accessible via "get_hint_widget()", but with color and font
100           functions aliased ( "::hintColor", "::hintBackColor", "::hintFont"
101           ).
102
103           This widget serves as a hint label, floating over widgets if the
104           mouse pointer hovers longer than "::hintPause" milliseconds.
105
106           Prima::Application internally manages all hint functionality.  The
107           hint widget itself, however, can be replaced before application
108           object is created, using "::hintClass" create-only property.
109
110       Printer
111           Result of get_printer method points to an automatically created
112           printer object, responsible for the system-driven printing.
113           Depending on the operating system, it is either Prima::Printer, if
114           the system provides GUI printing capabilities, or generic
115           Prima::PS::Printer, the PostScript document interface.
116
117           See Prima::Printer for details.
118
119       Clipboard
120           $::application hosts set of Prima::Clipboard objects, created
121           automatically to reflect the system-provided clipboard IPC
122           functionality. Their number depends on the system, - under X11
123           environment there is three clipboard objects, and only one under
124           Win32.
125
126           These are no methods to access these clipboard objects, except
127           fetch() ( or, the indirect name calling ) - the clipboard objects
128           are named after the system clipboard names, which are returned by
129           Prima::Clipboard::get_standard_clipboards.
130
131           The default clipboard is named Clipboard, and is accessible via
132
133                   my $clipboard = $::application-> Clipboard;
134
135           code.
136
137           See Prima::Clipboard for details.
138
139       Help subsystem
140           The toolkit has a built-in help viewer, that understands perl's
141           native POD ( plain old documentation ) format.  Whereas the viewer
142           functionality itself is part of the toolkit, and resides in
143           "Prima::HelpViewer" module, any custom help viewing module can be
144           assigned. Create-only "Prima::Application" properties "::helpClass"
145           and "::helpModule" can be used to set these options.
146
147           "Prima::Application" provides two methods for communicating with
148           the help viewer window: "open_help()" opens a selected topic in the
149           help window, and "close_help()" closes the window.
150
151       System-dependent information
152           A complex program will need eventually more information than the
153           toolkit provides. Or, knowing the toolkit boundaries in some
154           platforms, the program changes its behavior accordingly. Both these
155           topics are facilitated by extra system information, returned by
156           Prima::Application methods.  "get_system_value" returns a system
157           value for one of "sv::XXX" constants, so the program can read the
158           system-specific information. As well as "get_system_info" method,
159           that returns the short description of the system, it is the
160           portable call.  To the contrary, "sys_action" method is a wrapper
161           to system-dependent functionality, called in non-portable way. This
162           method is never used within the toolkit, and its usage is
163           discouraged, primarily because its options do not serve the toolkit
164           design, are subject to changes and cannot be relied upon.
165

API

167   Properties
168       autoClose BOOLEAN
169           If set to 1, issues "close()" after the last top-level window is
170           destroyed.  Does not influence anything if set to 0.
171
172           This feature is designed to help with general 'one main window'
173           application layouts.
174
175           Default value: 0
176
177       icon OBJECT
178           Holds the icon object, associated with the application.  If
179           "undef", a system-provided default icon is assumed.  Prima::Window
180           object instances inherit the application icon by default.
181
182       insertMode BOOLEAN
183           A system boolean flag, showing whether text widgets through the
184           system should insert ( 1 ) or overwrite ( 0 ) text on user input.
185           Not all systems provide the global state of the flag.
186
187       helpClass STRING
188           Specifies a class of object, used as a help viewing package.  The
189           default value is Prima::HelpViewer.
190
191           Run-time changes to the property do not affect the help subsystem
192           until "close_help" call is made.
193
194       helpModule STRING
195           Specifies a perl module, loaded indirectly when a help viewing call
196           is made via "open_help".  Used when "::helpClass" property is
197           overridden and the new class is contained in a third-party module.
198
199           Run-time changes to the property do not affect the help subsystem
200           until "close_help" call is made.
201
202       hintClass STRING
203           Create-only property.
204
205           Specifies a class of widget, used as the hint label.
206
207           Default value: Prima::HintWidget
208
209       hintColor COLOR
210           An alias to foreground color property for the hint label widget.
211
212       hintBackColor COLOR
213           An alias to background color property for the hint label widget.
214
215       hintFont %FONT
216           An alias to font property for the hint label widget.
217
218       hintPause TIMEOUT
219           Selects the timeout in milliseconds before the hint label is shown
220           when the mouse pointer hovers over a widget.
221
222       language STRING
223           By default contains user interface language, deduced either from
224           $ENV{LANG} or GUI default. When changed, updates "textDirection"
225           propertly.
226
227           See also: "get_system_info".
228
229       modalHorizon BOOLEAN
230           A read-only property. Used as a landmark for the lowest-level modal
231           horizon.  Always returns 1.
232
233       palette [ @PALETTE ]
234           Used only within paint and information modes.  Selects solid colors
235           in a system palette, as many as possible.  PALETTE is an array of
236           integer triplets, where each is red, green, and blue component,
237           with intensity range from 0 to 255.
238
239       printerClass STRING
240           Create-only property.
241
242           Specifies a class of object, used as a printer.  The default value
243           is system-dependent, but is either "Prima::Printer" or
244           "Prima::PS::Printer".
245
246       printerModule STRING
247           Create-only property.
248
249           Specifies a perl module, loaded indirectly before a printer object
250           of "::printerClass" class is created.  Used when "::printerClass"
251           property is overridden and the new class is contained in a third-
252           party module.
253
254       pointerVisible BOOLEAN
255           Governs the system pointer visibility.  If 0, hides the pointer so
256           it is not visible in all system windows. Therefore this property
257           usage must be considered with care.
258
259       size WIDTH, HEIGHT
260           A read-only property.
261
262           Returns two integers, width and height of the screen.
263
264       showHint BOOLEAN
265           If 1, the toolkit is allowed to show the hint label over a widget.
266           If 0, the display of the hint is forbidden. In addition to
267           functionality of "::showHint" property in Prima::Widget,
268           Prima::Application::showHint is another layer of hint visibility
269           control - if it is 0, all hint actions are disabled, disregarding
270           "::showHint" value in widgets.
271
272       textDirection BOOLEAN
273           Contains preferred text direction, initially calculated from the
274           preferred interface language.  If 0 ( default ), the preferred text
275           direction is left-to-right (LTR), otherwise right-to-left (RTL),
276           f.ex. for arabic and hebrew languages.
277
278           The value is used as a default when shaping text and setting widget
279           input direction.
280
281       uiScaling FLOAT
282           The property contains an advisory multiplier factor, useful for UI
283           elements that have a fixed pixel value, but that would like to be
284           represented in a useful manner when the display resolution is too
285           high (on modern High-DPI displays) or too low (on ancient
286           monitors).
287
288           By default, it acquires the system display resolution, and sets the
289           scaling factor so that when the DPI is 96 it is 1.0, 192 it is 2.0,
290           etc. The increase step is 0.25, so that bitmaps may look not that
291           distorted. However, when the value is manually set, there is no
292           such step, any value can be set.
293
294           See also: "Stress" in Prima.
295
296       wantUnicodeInput BOOLEAN
297           Selects if the system is allowed to generate key codes in unicode.
298           Returns the effective state of the unicode input flag, which cannot
299           be changed if perl or operating system do not support UTF8.
300
301           If 1, "Prima::Clipboard::text" property may return UTF8 text from
302           system clipboards is available.
303
304           Default value: 1
305
306   Events
307       Clipboard $CLIPBOARD, $ACTION, $TARGET
308           With (the only implemented) $ACTION copy, is called whenever
309           another application requests clipboard data in format $TARGET. This
310           notification is handled internally to optimize image pasting
311           through the cliboard. Since the clipboard pasting semantics in
312           Prima is such that data must be supplied to the clipboard in
313           advance, before another application can request it, there is a
314           problem which format to use. In order to not encode an image or
315           other complex data in all possible formats but do that on demand
316           and in the format the other application wants, this notification
317           can be used.
318
319           Only implemented for X11.
320
321       CopyImage $CLIPBOARD, $IMAGE
322           The notification stores $IMAGE in clipboard.
323
324       CopyText $CLIPBOARD, $TEXT
325           The notification stores $TEXT in clipboard.
326
327       Idle
328           Called when the event loop handled all pending events, and is about
329           to sleep waiting for more.
330
331       PasteImage $CLIPBOARD, $$IMAGE_REF
332           The notification queries $CLIPBOARD for image content and stores in
333           $$IMAGE_REF. Default action is that 'Image' format is queried.  On
334           unix, encoded formats 'image/bmp', 'image/png' etc are queried if
335           the default 'Image' is not found.
336
337           The "PasteImage" mechanism is devised to read images from clipboard
338           in GTK environment.
339
340       PasteText $CLIPBOARD, $$TEXT_REF
341           The notification queries $CLIPBOARD for text content and stores in
342           $$TEXT_REF. Default action is that 'Text' format is queried if
343           "wantUnicodeInput" is unset. Otherwise, 'UTF8' format is queried
344           beforehand.
345
346           The "PasteText" mechanism is devised to ease defining text
347           unicode/ascii conversion between clipboard and standard widgets, in
348           a standard way.
349
350   Methods
351       add_startup_notification @CALLBACK
352           CALLBACK is an array of anonymous subs, which is executed when
353           Prima::Application object is created. If the application object is
354           already created during the call, CALLBACKs called immediately.
355
356           Useful for add-on packages initialization.
357
358       begin_paint
359           Enters the enabled ( active paint ) state, returns success flag.
360           Once the object is in enabled state, painting and drawing methods
361           can perform write operations on the whole screen.
362
363       begin_paint_info
364           Enters the information state, returns success flag.  The object
365           information state is same as enabled state ( see "begin_paint()"),
366           except that painting and drawing methods are not permitted to
367           change the screen.
368
369       close
370           Issues a system termination call, resulting in calling "close" for
371           all top-level windows. The call can be interrupted by these, and
372           thus canceled. If not canceled, stops the application event loop.
373
374       close_help
375           Closes the help viewer window.
376
377       end_paint
378           Quits the enabled state and returns application object to the
379           normal state.
380
381       end_paint_info
382           Quits the information state and returns application object to the
383           normal state.
384
385       font_encodings
386           Returns array of encodings, represented by strings, that are
387           recognized by the system and available for at least one font. Each
388           system provides different sets of encoding strings; the font
389           encodings are not portable.
390
391       fonts NAME = '', ENCODING = ''
392           Returns hash of font hashes ( see "Fonts" in Prima::Drawable )
393           describing fonts of NAME font family and of ENCODING. If NAME is ''
394           or "undef", returns one fonts hash for each of the font families
395           that match the ENCODING string. If ENCODING is '' or "undef", no
396           encoding match is performed.  If ENCODING is not valid ( not
397           present in "font_encodings" result), it is treated as if it was ''
398           or "undef".
399
400           In the special case, when both NAME and ENCODING are '' or "undef",
401           each font metric hash contains element "encodings", that points to
402           array of the font encodings, available for the fonts of NAME font
403           family.
404
405       get_active_window
406           Returns object reference to a currently active window, if any, that
407           belongs to the program. If no such window exists, "undef" is
408           returned.
409
410           The exact definition of 'active window' is system-dependent, but it
411           is generally believed that an active window is the one that has
412           keyboard focus on one of its children widgets.
413
414       get_caption_font
415           Returns a title font, that the system uses to draw top-level window
416           captions.  The method can be called with a class string instead of
417           an object instance.
418
419       get_default_cursor_width
420           Returns width of the system cursor in pixels.  The method can be
421           called with a class string instead of an object instance.
422
423       get_default_font
424           Returns the default system font.  The method can be called with a
425           class string instead of an object instance.
426
427       get_default_scrollbar_metrics
428           Returns dimensions of the system scrollbars - width of the standard
429           vertical scrollbar and height of the standard horizon scrollbar.
430           The method can be called with a class string instead of an object
431           instance.
432
433       get_dnd_clipboard
434           Returns the predefined special clipboard used as a proxy for drag
435           and drop interactions.
436
437           See also: "Widget/Drag and drop", "Clipboard/is_dnd".
438
439       get_default_window_borders BORDER_STYLE = bs::Sizeable
440           Returns width and height of standard system window border
441           decorations for one of "bs::XXX" constants.  The method can be
442           called with a class string instead of an object instance.
443
444       get_focused_widget
445           Returns object reference to a currently focused widget, if any,
446           that belongs to the program. If no such widget exists, "undef" is
447           returned.
448
449       get_fullscreen_image
450           Syntax sugar for grabbing whole screen as in
451
452              $::application->get_image( 0, 0, $::application->size)
453
454           (MacOSX/XQuartz: get_image() does not grab all screen bits, but
455           "get_fullscreen_image" does (given Prima is compiled with Cocoa
456           library)).
457
458       get_hint_widget
459           Returns the hint label widget, attached automatically to
460           Prima::Application object during startup. The widget is of
461           "::hintClass" class, Prima::HintWidget by default.
462
463       get_image X_OFFSET, Y_OFFSET, WIDTH, HEIGHT
464           Returns Prima::Image object with WIDTH and HEIGHT dimensions filled
465           with graphic content of the screen, copied from X_OFFSET and
466           Y_OFFSET coordinates.  If WIDTH and HEIGHT extend beyond the screen
467           dimensions, they are adjusted.  If the offsets are outside screen
468           boundaries, or WIDTH and HEIGHT are zero or negative, "undef" is
469           returned.
470
471           Note: When running on MacOSX under XQuartz, the latter does not
472           give access to the whole screen, so the function will not be able
473           to grab top-level menu bar.  This problem is addressed in
474           "get_fullscreen_image".
475
476       get_indents
477           Returns 4 integers that corresponds to extensions of eventual
478           desktop decorations that the windowing system may present on the
479           left, bottom, right, and top edges of the screen. For example, for
480           win32 this reports the size of the part of the scraan that windows
481           taskbar may occupies, if any.
482
483       get_printer
484           Returns the printer object, attached automatically to
485           Prima::Application object. The object is of "::printerClass" class.
486
487       get_message_font
488           Returns the font the system uses to draw the message text.  The
489           method can be called with a class string instead of an object
490           instance.
491
492       get_modal_window MODALITY_TYPE = mt::Exclusive, TOPMOST = 1
493           Returns the modal window, that resides on an end of a modality
494           chain.  MODALITY_TYPE selects the chain, and can be either
495           "mt::Exclusive" or "mt::Shared". TOPMOST is a boolean flag,
496           selecting the lookup direction; if it is 1, the 'topmost' window is
497           returned, if 0, the 'lowest' one ( in a simple case when window A
498           is made modal (executed) after modal window B, the A window is the
499           'topmost' one ).
500
501           If a chain is empty "undef" is returned. In case when a chain
502           consists of just one window, TOPMOST value is apparently
503           irrelevant.
504
505       get_monitor_rects
506           Returns set of rects in format [X,Y,WIDTH,HEIGHT] identifying
507           monitor configurations. Currently works under X11 only.
508
509       get_scroll_rate
510           Returns two integer values of two system-specific scrolling
511           timeouts. The first is the initial timeout, that is applied when
512           the user drags the mouse from a scrollable widget ( a text field,
513           for example ), and the widget is about to scroll, but the actual
514           scroll is performed after the timeout is expired. The second is the
515           repetitive timeout, - if the dragging condition did not change, the
516           scrolling performs automatically after this timeout. The timeout
517           values are in milliseconds.
518
519       get_system_info
520           Returns a hash with information about the system.  The hash result
521           contains the following keys:
522
523           apc One of "apc::XXX" constants, reflecting the platform.
524               Currently, the list of the supported platforms is:
525
526                       apc::Win32
527                       apc::Unix
528
529           gui One of "gui::XXX" constants, reflecting the graphic user
530               interface used in the system:
531
532                       gui::Default
533                       gui::PM
534                       gui::Windows
535                       gui::XLib
536                       gui::GTK
537
538           guiDescription
539               Description of graphic user interface, returned as an arbitrary
540               string.
541
542           guiLanguage
543               Preferred language of the interface, returned as an ISO 639
544               code.
545
546           system
547               An arbitrary string, representing the operating system
548               software.
549
550           release
551               An arbitrary string, reflecting the OS version information.
552
553           vendor
554               The OS vendor string
555
556           architecture
557               The machine architecture string
558
559           The method can be called with a class string instead of an object
560           instance.
561
562       get_system_value
563           Returns the system integer value, associated with one of "sv::XXX"
564           constants. The constants are:
565
566                   sv::YMenu            - height of menu bar in top-level windows
567                   sv::YTitleBar        - height of title bar in top-level windows
568                   sv::XIcon            - width and height of main icon dimensions,
569                   sv::YIcon              acceptable by the system
570                   sv::XSmallIcon       - width and height of alternate icon dimensions,
571                   sv::YSmallIcon         acceptable by the system
572                   sv::XPointer         - width and height of mouse pointer icon
573                   sv::YPointer           acceptable by the system
574                   sv::XScrollbar       - width of the default vertical scrollbar
575                   sv::YScrollbar       - height of the default horizontal scrollbar
576                                                                           ( see get_default_scrollbar_metrics() )
577                   sv::XCursor          - width of the system cursor
578                                                                           ( see get_default_cursor_width() )
579                   sv::AutoScrollFirst  - the initial and the repetitive
580                   sv::AutoScrollNext     scroll timeouts
581                                                                           ( see get_scroll_rate() )
582                   sv::InsertMode       - the system insert mode
583                                                                           ( see insertMode )
584                   sv::XbsNone          - widths and heights of the top-level window
585                   sv::YbsNone            decorations, correspondingly, with borderStyle
586                   sv::XbsSizeable        bs::None, bs::Sizeable, bs::Single, and
587                   sv::YbsSizeable        bs::Dialog.
588                   sv::XbsSingle          ( see get_default_window_borders() )
589                   sv::YbsSingle
590                   sv::XbsDialog
591                   sv::YbsDialog
592                   sv::MousePresent     - 1 if the mouse is present, 0 otherwise
593                   sv::MouseButtons     - number of the mouse buttons
594                   sv::WheelPresent     - 1 if the mouse wheel is present, 0 otherwise
595                   sv::SubmenuDelay     - timeout ( in ms ) before a sub-menu shows on
596                                                                           an implicit selection
597                   sv::FullDrag         - 1 if the top-level windows are dragged dynamically,
598                                                                           0 - with marquee mode
599                   sv::DblClickDelay    - mouse double-click timeout in milliseconds
600                   sv::ShapeExtension   - 1 if Prima::Widget::shape functionality is supported,
601                                                                           0 otherwise
602                   sv::ColorPointer     - 1 if system accepts color pointer icons.
603                   sv::CanUTF8_Input    - 1 if system can generate key codes in unicode
604                   sv::CanUTF8_Output   - 1 if system can output utf8 text
605                   sv::CompositeDisplay - 1 if system uses double-buffering and alpha composition for the desktop,
606                                          0 if it doesn't, -1 if unknown
607                   sv::LayeredWidgets   - 1 if system supports layering
608                   sv::FixedPointerSize - 0 if system doesn't support arbitrary sized pointers and will resize custom icons to the system size
609                   sv::MenuCheckSize    - width and height of default menu check icon
610                   sv::FriBidi          - 1 if Prima is compiled with libfribidi and full bidi unicode support is available
611                   sv::Antialias        - 1 if system supports antialiasing and alpha layer for primitives
612                   sv::LibThai          - 1 if Prima is compiled with libthai
613
614           The method can be called with a class string instead of an object
615           instance.
616
617       get_widget_from_handle HANDLE
618           HANDLE is an integer value of a toolkit widget. It is usually
619           passed to the program by other IPC means, so it returns the
620           associated widget.  If no widget is associated with HANDLE, "undef"
621           is returned.
622
623       get_widget_from_point X_OFFSET, Y_OFFSET
624           Returns the widget that occupies screen area under
625           (X_OFFSET,Y_OFFSET) coordinates. If no toolkit widget are found,
626           "undef" is returned.
627
628       go  The main event loop. Called by
629
630           run Prima;
631
632           standard code. Returns when the program is about to terminate, if
633           "stop" was called, or if the exception was signaled. In the latter
634           two cases, the loop can be safely re-started.
635
636       lock
637           Effectively blocks the graphic output for all widgets.  The output
638           can be restored with "unlock()".
639
640       load_font FONTNAME
641           Registers font resource in system-specific format. The resource is
642           freed after prgram ends.
643
644           Notes for win32: To add a font whose information comes from several
645           resource files, point FONTNAME to a string with the file names
646           separated by a "|" - for example, " abcxxxxx.pfm | abcxxxxx.pfb ".
647
648           Notes for unix: available only when Prima is compiled with
649           fontconfig and Xft .
650
651           Returns number of font resources added.
652
653       open_help TOPIC
654           Opens the help viewer window with TOPIC string in link POD format (
655           see perlpod ) - the string is treated as "manpage/section", where
656           'manpage' is the file with POD content and 'section' is the topic
657           inside the manpage.
658
659       stop
660           Breaks the event loop. The loop can be started again by "go"
661           thereafter.
662
663       sync
664           Synchronizes all pending requests where there are any. Is an
665           effective "XSync(false)" on X11, and is a no-op otherwise.
666
667       sys_action CALL
668           CALL is an arbitrary string of the system service name and the
669           parameters to it.  This functionality is non-portable, and its
670           usage should be avoided.  The system services provided are not
671           documented and subject to change. The actual services can be looked
672           in the toolkit source code under apc_system_action tag.
673
674       unlock
675           Unblocks the graphic output for all widgets, previously locked with
676           "lock()".
677
678       yield $wait_for_event=0
679           An event dispatcher, called from within the event loop.  If the
680           event loop can be schematized, then in
681
682                   while ( application not closed ) {
683                           yield
684                   }
685
686           draft yield() is the only function, called repeatedly within the
687           event loop.  yield(0) call shouldn't be used to organize event
688           loops, but it can be employed to process stacked system events
689           explicitly, to increase responsiveness of a program, for example,
690           inside a long calculation cycle.
691
692           yield(1) though is adapted exactly for external implementation of
693           event loops; it does exactly the same as yeild(0), but if there are
694           no events, it sleeps until there comes at least one, processes it,
695           and then returns. The return value is 0 if the application doesn't
696           need more event processins, because of shutting down.  The
697           corresponding code will be
698
699                   while ( yield(1)) {
700                       ...
701                   }
702
703           but in turn, this call cannot be used for UI responsiveness inside
704           tight cycles.
705
706           The method can be called with a class string instead of an object
707           instance; however, the $::application object must be initialized.
708

AUTHOR

710       Dmitry Karasik, <dmitry@karasik.eu.org>.
711

SEE ALSO

713       Prima, Prima::Object, Prima::Widget, Prima::Window
714
715
716
717perl v5.34.1                      2022-04-20             Prima::Application(3)
Impressum