1Prima::Application(3) User Contributed Perl DocumentationPrima::Application(3)
2
6 Prima::Application - root of widget objects hierarchy
7
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
16 use Prima;
17 use Prima::Application;
18 or
20 use Prima qw(Application);
22 Prima::MainWindow-> create();
24 run Prima;
26
28 Prima::Application class, and its only instance are treated specially
29 throughout the toolkit. The object instance is contained in
30 $::application
32 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 use Prima::Application;
38 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 use Prima::Application name => 'Test application', icon => $icon;
45 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 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 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 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 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 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 Hint
98 $::application hosts a special Prima::HintWidget class object,
99 accessible via get_hint_widget(), but with color and font functions
100 aliased ( "::hintColor", "::hintBackColor", "::hintFont" ).
101 This widget serves as a hint label, floating over widgets if the
103 mouse pointer hovers longer than "::hintPause" milliseconds.
104 Prima::Application internally manages all hint functionality. The
106 hint widget itself, however, can be replaced before application
107 object is created, using "::hintClass" create-only property.
108 Printer
110 Result of get_printer method points to an automatically created
111 printer object, responsible for the system-driven printing.
112 Depending on the operating system, it is either Prima::Printer, if
113 the system provides GUI printing capabilities, or generic
114 Prima::PS::Printer, the PostScript document interface.
115 See Prima::Printer for details.
117 Clipboard
119 $::application hosts set of Prima::Clipboard objects, created
120 automatically to reflect the system-provided clipboard IPC
121 functionality. Their number depends on the system, - under X11
122 environment there is three clipboard objects, and only one under
123 Win32.
124 These are no methods to access these clipboard objects, except
126 fetch() ( or, the indirect name calling ) - the clipboard objects
127 are named after the system clipboard names, which are returned by
128 Prima::Clipboard::get_standard_clipboards.
129 The default clipboard is named Clipboard, and is accessible via
131 my $clipboard = $::application-> Clipboard;
133 code.
135 See Prima::Clipboard for details.
137 Help subsystem
139 The toolkit has a built-in help viewer, that understands perl's
140 native POD ( plain old documentation ) format. Whereas the viewer
141 functionality itself is part of the toolkit, and resides in
142 "Prima::HelpViewer" module, any custom help viewing module can be
143 assigned. Create-only "Prima::Application" properties "::helpClass"
144 and "::helpModule" can be used to set these options.
145 "Prima::Application" provides two methods for communicating with
147 the help viewer window: open_help() opens a selected topic in the
148 help window, and close_help() closes the window.
149 System-dependent information
151 A complex program will need eventually more information than the
152 toolkit provides. Or, knowing the toolkit boundaries in some
153 platforms, the program changes its behavior accordingly. Both these
154 topics are facilitated by extra system information, returned by
155 Prima::Application methods. "get_system_value" returns a system
156 value for one of "sv::XXX" constants, so the program can read the
157 system-specific information. As well as "get_system_info" method,
158 that returns the short description of the system, it is the
159 portable call. To the contrary, "sys_action" method is a wrapper
160 to system-dependent functionality, called in non-portable way. This
161 method is never used within the toolkit, and its usage is
162 discouraged, primarily because its options do not serve the toolkit
163 design, are subject to changes and cannot be relied upon.
164 Exceptions and signals
166 By default Prima doesn't track exceptions caused by "die", "warn",
167 and signals. Currently it is possible to enable a GUI dialog
168 tracking the "die" exceptions, by either operating the boolean
169 "guiException" property, or using
170 use Prima qw(sys::GUIException)
172 syntax.
174 If you need to track signals or warnings you may do so just by
176 using standard perl practices. It is though not advisable to call
177 Prima interactive methods inside signals, but use minimal code in
178 the signal handler instead. F.ex. code that would ask whether the
179 user really wants to quit would look like this:
180 use Prima qw(Utils MsgBox);
182 $SIG{INT} = sub {
183 Prima::Utils::post( sub {
184 exit if message_box("Got Ctrl+C", "Do you really want to quit?", mb::YesNo) == mb::Yes;
185 });
186 };
187 and if you want to treat all warnings as potentially fatal, like
189 this:
190 use Prima qw(Utils MsgBox);
192 $SIG{__WARN__} = sub {
193 my ($warn, $stack) = ($_[0], Carp::longmess);
194 Prima::Utils::post( sub {
195 exit if $::application && Prima::MsgBox::signal_dialog("Warning", $warn, $stack) == mb::Abort;
196 });
197 };
198 See also: Die, "signal_dialog" in Prima::MsgBox
200
202 Properties
203 autoClose BOOLEAN
204 If set to 1, issues close() after the last top-level window is
205 destroyed. Does not influence anything if set to 0.
206 This feature is designed to help with general 'one main window'
208 application layouts.
209 Default value: 0
211 guiException BOOLEAN
213 If set to 1, when a "die" exception is thrown, displays a system
214 message dialog. allowing the user to choose the course of action
215 -- to stop, to continue, etc.
216 Is 0 by default.
218 Note that the exception is only called inside the "Prima::run"
220 call; if there is a call to f ex "Prima::Dialog::execute" or a
221 manual event loop run with "yield", the dialog will not be shown.
222 One needs to explicitly call "$::application->notify(Die => $@)"
223 and check the notification result to decide whether to propagate
224 the exception or not.
225 Alternative syntax for setting "guiException" to 1 is a
227 use Prima::sys::GUIException;
229 or
231 use Prima qw(sys::GUIException);
233 statement.
235 If for some reason an exception will be thrown during the dialog,
237 it will not be handled by Prima but by the current $SIG{__DIE__}
238 handler.
239 See also "signal_dialog" in Prima::MsgBox .
241 icon OBJECT
243 Holds the icon object, associated with the application. If
244 "undef", a system-provided default icon is assumed. Prima::Window
245 object instances inherit the application icon by default.
246 insertMode BOOLEAN
248 A system boolean flag, showing whether text widgets through the
249 system should insert ( 1 ) or overwrite ( 0 ) text on user input.
250 Not all systems provide the global state of the flag.
251 helpClass STRING
253 Specifies a class of object, used as a help viewing package. The
254 default value is Prima::HelpViewer.
255 Run-time changes to the property do not affect the help subsystem
257 until "close_help" call is made.
258 helpModule STRING
260 Specifies a perl module, loaded indirectly when a help viewing call
261 is made via "open_help". Used when "::helpClass" property is
262 overridden and the new class is contained in a third-party module.
263 Run-time changes to the property do not affect the help subsystem
265 until "close_help" call is made.
266 hintClass STRING
268 Create-only property.
269 Specifies a class of widget, used as the hint label.
271 Default value: Prima::HintWidget
273 hintColor COLOR
275 An alias to foreground color property for the hint label widget.
276 hintBackColor COLOR
278 An alias to background color property for the hint label widget.
279 hintFont %FONT
281 An alias to font property for the hint label widget.
282 hintPause TIMEOUT
284 Selects the timeout in milliseconds before the hint label is shown
285 when the mouse pointer hovers over a widget.
286 language STRING
288 By default contains user interface language, deduced either from
289 $ENV{LANG} or GUI default. When changed, updates "textDirection"
290 propertly.
291 See also: "get_system_info".
293 modalHorizon BOOLEAN
295 A read-only property. Used as a landmark for the lowest-level modal
296 horizon. Always returns 1.
297 palette [ @PALETTE ]
299 Used only within paint and information modes. Selects solid colors
300 in a system palette, as many as possible. PALETTE is an array of
301 integer triplets, where each is red, green, and blue component,
302 with intensity range from 0 to 255.
303 printerClass STRING
305 Create-only property.
306 Specifies a class of object, used as a printer. The default value
308 is system-dependent, but is either "Prima::Printer" or
309 "Prima::PS::Printer".
310 printerModule STRING
312 Create-only property.
313 Specifies a perl module, loaded indirectly before a printer object
315 of "::printerClass" class is created. Used when "::printerClass"
316 property is overridden and the new class is contained in a third-
317 party module.
318 pointerVisible BOOLEAN
320 Governs the system pointer visibility. If 0, hides the pointer so
321 it is not visible in all system windows. Therefore this property
322 usage must be considered with care.
323 size WIDTH, HEIGHT
325 A read-only property.
326 Returns two integers, width and height of the screen.
328 showHint BOOLEAN
330 If 1, the toolkit is allowed to show the hint label over a widget.
331 If 0, the display of the hint is forbidden. In addition to
332 functionality of "::showHint" property in Prima::Widget,
333 Prima::Application::showHint is another layer of hint visibility
334 control - if it is 0, all hint actions are disabled, disregarding
335 "::showHint" value in widgets.
336 textDirection BOOLEAN
338 Contains preferred text direction, initially calculated from the
339 preferred interface language. If 0 ( default ), the preferred text
340 direction is left-to-right (LTR), otherwise right-to-left (RTL),
341 f.ex. for arabic and hebrew languages.
342 The value is used as a default when shaping text and setting widget
344 input direction.
345 uiScaling FLOAT
347 The property contains an advisory multiplier factor, useful for UI
348 elements that have a fixed pixel value, but that would like to be
349 represented in a useful manner when the display resolution is too
350 high (on modern High-DPI displays) or too low (on ancient
351 monitors).
352 By default, it acquires the system display resolution, and sets the
354 scaling factor so that when the DPI is 96 it is 1.0, 192 it is 2.0,
355 etc. The increase step is 0.25, so that bitmaps may look not that
356 distorted. However, when the value is manually set, there is no
357 such step, any value can be set.
358 See also: "Stress" in Prima.
360 wantUnicodeInput BOOLEAN
362 Selects if the system is allowed to generate key codes in unicode.
363 Returns the effective state of the unicode input flag, which cannot
364 be changed if perl or operating system do not support UTF8.
365 If 1, "Prima::Clipboard::text" property may return UTF8 text from
367 system clipboards is available.
368 Default value: 1
370 Events
372 Clipboard $CLIPBOARD, $ACTION, $TARGET
373 With (the only implemented) $ACTION copy, is called whenever
374 another application requests clipboard data in format $TARGET. This
375 notification is handled internally to optimize image pasting
376 through the cliboard. Since the clipboard pasting semantics in
377 Prima is such that data must be supplied to the clipboard in
378 advance, before another application can request it, there is a
379 problem which format to use. In order to not encode an image or
380 other complex data in all possible formats but do that on demand
381 and in the format the other application wants, this notification
382 can be used.
383 Only implemented for X11.
385 CopyImage $CLIPBOARD, $IMAGE
387 The notification stores $IMAGE in clipboard.
388 CopyText $CLIPBOARD, $TEXT
390 The notification stores $TEXT in clipboard.
391 Die $@, $STACK
393 Called when an exception occurs inside the event loop "Prima::run".
394 By default, consults the "guiException" property, and if it is set,
395 displays the system message dialog allowing the user to decide when
396 to do next.
397 Idle
399 Called when the event loop handled all pending events, and is about
400 to sleep waiting for more.
401 PasteImage $CLIPBOARD, $$IMAGE_REF
403 The notification queries $CLIPBOARD for image content and stores in
404 $$IMAGE_REF. Default action is that 'Image' format is queried. On
405 unix, encoded formats 'image/bmp', 'image/png' etc are queried if
406 the default 'Image' is not found.
407 The "PasteImage" mechanism is devised to read images from clipboard
409 in GTK environment.
410 PasteText $CLIPBOARD, $$TEXT_REF
412 The notification queries $CLIPBOARD for text content and stores in
413 $$TEXT_REF. Default action is that 'Text' format is queried if
414 "wantUnicodeInput" is unset. Otherwise, 'UTF8' format is queried
415 beforehand.
416 The "PasteText" mechanism is devised to ease defining text
418 unicode/ascii conversion between clipboard and standard widgets, in
419 a standard way.
420 Methods
422 add_startup_notification @CALLBACK
423 CALLBACK is an array of anonymous subs, which is executed when
424 Prima::Application object is created. If the application object is
425 already created during the call, CALLBACKs called immediately.
426 Useful for add-on packages initialization.
428 begin_paint
430 Enters the enabled ( active paint ) state, returns success flag.
431 Once the object is in enabled state, painting and drawing methods
432 can perform write operations on the whole screen.
433 begin_paint_info
435 Enters the information state, returns success flag. The object
436 information state is same as enabled state ( see begin_paint()),
437 except that painting and drawing methods are not permitted to
438 change the screen.
439 close
441 Issues a system termination call, resulting in calling "close" for
442 all top-level windows. The call can be interrupted by these, and
443 thus canceled. If not canceled, stops the application event loop.
444 close_help
446 Closes the help viewer window.
447 end_paint
449 Quits the enabled state and returns application object to the
450 normal state.
451 end_paint_info
453 Quits the information state and returns application object to the
454 normal state.
455 font_encodings
457 Returns array of encodings, represented by strings, that are
458 recognized by the system and available for at least one font. Each
459 system provides different sets of encoding strings; the font
460 encodings are not portable.
461 fonts NAME = '', ENCODING = ''
463 Returns hash of font hashes ( see "Fonts" in Prima::Drawable )
464 describing fonts of NAME font family and of ENCODING. If NAME is ''
465 or "undef", returns one fonts hash for each of the font families
466 that match the ENCODING string. If ENCODING is '' or "undef", no
467 encoding match is performed. If ENCODING is not valid ( not
468 present in "font_encodings" result), it is treated as if it was ''
469 or "undef".
470 In the special case, when both NAME and ENCODING are '' or "undef",
472 each font metric hash contains element "encodings", that points to
473 array of the font encodings, available for the fonts of NAME font
474 family.
475 get_active_window
477 Returns object reference to a currently active window, if any, that
478 belongs to the program. If no such window exists, "undef" is
479 returned.
480 The exact definition of 'active window' is system-dependent, but it
482 is generally believed that an active window is the one that has
483 keyboard focus on one of its children widgets.
484 get_caption_font
486 Returns a title font, that the system uses to draw top-level window
487 captions. The method can be called with a class string instead of
488 an object instance.
489 get_default_cursor_width
491 Returns width of the system cursor in pixels. The method can be
492 called with a class string instead of an object instance.
493 get_default_font
495 Returns the default system font. The method can be called with a
496 class string instead of an object instance.
497 get_default_scrollbar_metrics
499 Returns dimensions of the system scrollbars - width of the standard
500 vertical scrollbar and height of the standard horizon scrollbar.
501 The method can be called with a class string instead of an object
502 instance.
503 get_dnd_clipboard
505 Returns the predefined special clipboard used as a proxy for drag
506 and drop interactions.
507 See also: "Widget/Drag and drop", "Clipboard/is_dnd".
509 get_default_window_borders BORDER_STYLE = bs::Sizeable
511 Returns width and height of standard system window border
512 decorations for one of "bs::XXX" constants. The method can be
513 called with a class string instead of an object instance.
514 get_focused_widget
516 Returns object reference to a currently focused widget, if any,
517 that belongs to the program. If no such widget exists, "undef" is
518 returned.
519 get_fullscreen_image
521 Syntax sugar for grabbing whole screen as in
522 $::application->get_image( 0, 0, $::application->size)
524 (MacOSX/XQuartz: get_image() does not grab all screen bits, but
526 "get_fullscreen_image" does (given Prima is compiled with Cocoa
527 library)).
528 get_hint_widget
530 Returns the hint label widget, attached automatically to
531 Prima::Application object during startup. The widget is of
532 "::hintClass" class, Prima::HintWidget by default.
533 get_image X_OFFSET, Y_OFFSET, WIDTH, HEIGHT
535 Returns Prima::Image object with WIDTH and HEIGHT dimensions filled
536 with graphic content of the screen, copied from X_OFFSET and
537 Y_OFFSET coordinates. If WIDTH and HEIGHT extend beyond the screen
538 dimensions, they are adjusted. If the offsets are outside screen
539 boundaries, or WIDTH and HEIGHT are zero or negative, "undef" is
540 returned.
541 Note: When running on MacOSX under XQuartz, the latter does not
543 give access to the whole screen, so the function will not be able
544 to grab top-level menu bar. This problem is addressed in
545 "get_fullscreen_image".
546 get_indents
548 Returns 4 integers that corresponds to extensions of eventual
549 desktop decorations that the windowing system may present on the
550 left, bottom, right, and top edges of the screen. For example, for
551 win32 this reports the size of the part of the scraan that windows
552 taskbar may occupies, if any.
553 get_printer
555 Returns the printer object, attached automatically to
556 Prima::Application object. The object is of "::printerClass" class.
557 get_message_font
559 Returns the font the system uses to draw the message text. The
560 method can be called with a class string instead of an object
561 instance.
562 get_modal_window MODALITY_TYPE = mt::Exclusive, TOPMOST = 1
564 Returns the modal window, that resides on an end of a modality
565 chain. MODALITY_TYPE selects the chain, and can be either
566 "mt::Exclusive" or "mt::Shared". TOPMOST is a boolean flag,
567 selecting the lookup direction; if it is 1, the 'topmost' window is
568 returned, if 0, the 'lowest' one ( in a simple case when window A
569 is made modal (executed) after modal window B, the A window is the
570 'topmost' one ).
571 If a chain is empty "undef" is returned. In case when a chain
573 consists of just one window, TOPMOST value is apparently
574 irrelevant.
575 get_monitor_rects
577 Returns set of rects in format [X,Y,WIDTH,HEIGHT] identifying
578 monitor configurations. Currently works under X11 only.
579 get_scroll_rate
581 Returns two integer values of two system-specific scrolling
582 timeouts. The first is the initial timeout, that is applied when
583 the user drags the mouse from a scrollable widget ( a text field,
584 for example ), and the widget is about to scroll, but the actual
585 scroll is performed after the timeout is expired. The second is the
586 repetitive timeout, - if the dragging condition did not change, the
587 scrolling performs automatically after this timeout. The timeout
588 values are in milliseconds.
589 get_system_info
591 Returns a hash with information about the system. The hash result
592 contains the following keys:
593 apc One of "apc::XXX" constants, reflecting the platform.
595 Currently, the list of the supported platforms is:
596 apc::Win32
598 apc::Unix
599 gui One of "gui::XXX" constants, reflecting the graphic user
601 interface used in the system:
602 gui::Default
604 gui::PM
605 gui::Windows
606 gui::XLib
607 gui::GTK
608 guiDescription
610 Description of graphic user interface, returned as an arbitrary
611 string.
612 guiLanguage
614 Preferred language of the interface, returned as an ISO 639
615 code.
616 system
618 An arbitrary string, representing the operating system
619 software.
620 release
622 An arbitrary string, reflecting the OS version information.
623 vendor
625 The OS vendor string
626 architecture
628 The machine architecture string
629 The method can be called with a class string instead of an object
631 instance.
632 get_system_value
634 Returns the system integer value, associated with one of "sv::XXX"
635 constants. The constants are:
636 sv::YMenu - height of menu bar in top-level windows
638 sv::YTitleBar - height of title bar in top-level windows
639 sv::XIcon - width and height of main icon dimensions,
640 sv::YIcon acceptable by the system
641 sv::XSmallIcon - width and height of alternate icon dimensions,
642 sv::YSmallIcon acceptable by the system
643 sv::XPointer - width and height of mouse pointer icon
644 sv::YPointer acceptable by the system
645 sv::XScrollbar - width of the default vertical scrollbar
646 sv::YScrollbar - height of the default horizontal scrollbar
647 ( see get_default_scrollbar_metrics() )
648 sv::XCursor - width of the system cursor
649 ( see get_default_cursor_width() )
650 sv::AutoScrollFirst - the initial and the repetitive
651 sv::AutoScrollNext scroll timeouts
652 ( see get_scroll_rate() )
653 sv::InsertMode - the system insert mode
654 ( see insertMode )
655 sv::XbsNone - widths and heights of the top-level window
656 sv::YbsNone decorations, correspondingly, with borderStyle
657 sv::XbsSizeable bs::None, bs::Sizeable, bs::Single, and
658 sv::YbsSizeable bs::Dialog.
659 sv::XbsSingle ( see get_default_window_borders() )
660 sv::YbsSingle
661 sv::XbsDialog
662 sv::YbsDialog
663 sv::MousePresent - 1 if the mouse is present, 0 otherwise
664 sv::MouseButtons - number of the mouse buttons
665 sv::WheelPresent - 1 if the mouse wheel is present, 0 otherwise
666 sv::SubmenuDelay - timeout ( in ms ) before a sub-menu shows on
667 an implicit selection
668 sv::FullDrag - 1 if the top-level windows are dragged dynamically,
669 0 - with marquee mode
670 sv::DblClickDelay - mouse double-click timeout in milliseconds
671 sv::ShapeExtension - 1 if Prima::Widget::shape functionality is supported,
672 0 otherwise
673 sv::ColorPointer - 1 if system accepts color pointer icons.
674 sv::CanUTF8_Input - 1 if system can generate key codes in unicode
675 sv::CanUTF8_Output - 1 if system can output utf8 text
676 sv::CompositeDisplay - 1 if system uses double-buffering and alpha composition for the desktop,
677 0 if it doesn't, -1 if unknown
678 sv::LayeredWidgets - 1 if system supports layering
679 sv::FixedPointerSize - 0 if system doesn't support arbitrary sized pointers and will resize custom icons to the system size
680 sv::MenuCheckSize - width and height of default menu check icon
681 sv::FriBidi - 1 if Prima is compiled with libfribidi and full bidi unicode support is available
682 sv::Antialias - 1 if system supports antialiasing and alpha layer for primitives
683 sv::LibThai - 1 if Prima is compiled with libthai
684 The method can be called with a class string instead of an object
686 instance.
687 get_widget_from_handle HANDLE
689 HANDLE is an integer value of a toolkit widget. It is usually
690 passed to the program by other IPC means, so it returns the
691 associated widget. If no widget is associated with HANDLE, "undef"
692 is returned.
693 get_widget_from_point X_OFFSET, Y_OFFSET
695 Returns the widget that occupies screen area under
696 (X_OFFSET,Y_OFFSET) coordinates. If no toolkit widget are found,
697 "undef" is returned.
698 go The main event loop. Called by
700 run Prima;
702 standard code. Returns when the program is about to terminate, if
704 "stop" was called, or if the exception was signaled. In the latter
705 two cases, the loop can be safely re-started.
706 lock
708 Effectively blocks the graphic output for all widgets. The output
709 can be restored with unlock().
710 load_font FONTNAME
712 Registers font resource in system-specific format. The resource is
713 freed after prgram ends.
714 Notes for win32: To add a font whose information comes from several
716 resource files, point FONTNAME to a string with the file names
717 separated by a "|" - for example, " abcxxxxx.pfm | abcxxxxx.pfb ".
718 Notes for unix: available only when Prima is compiled with
720 fontconfig and Xft .
721 Returns number of font resources added.
723 open_help TOPIC
725 Opens the help viewer window with TOPIC string in link POD format (
726 see perlpod ) - the string is treated as "manpage/section", where
727 'manpage' is the file with POD content and 'section' is the topic
728 inside the manpage.
729 Alternatively can handle the syntax in form of "
731 file://path|section " where "path" is the file with the pod content
732 and "section" is an optional pod section within the file.
733 stop
735 Breaks the event loop. The loop can be started again by "go"
736 thereafter.
737 sync
739 Synchronizes all pending requests where there are any. Is an
740 effective XSync(false) on X11, and is a no-op otherwise.
741 sys_action CALL
743 CALL is an arbitrary string of the system service name and the
744 parameters to it. This functionality is non-portable, and its
745 usage should be avoided. The system services provided are not
746 documented and subject to change. The actual services can be looked
747 in the toolkit source code under apc_system_action tag.
748 unlock
750 Unblocks the graphic output for all widgets, previously locked with
751 lock().
752 yield $wait_for_event=0
754 An event dispatcher, called from within the event loop. If the
755 event loop can be schematized, then in
756 while ( application not closed ) {
758 yield
759 }
760 draft yield() is the only function, called repeatedly within the
762 event loop. yield(0) call shouldn't be used to organize event
763 loops, but it can be employed to process stacked system events
764 explicitly, to increase responsiveness of a program, for example,
765 inside a long calculation cycle.
766 yield(1) though is adapted exactly for external implementation of
768 event loops; it does exactly the same as yeild(0), but if there are
769 no events, it sleeps until there comes at least one, processes it,
770 and then returns. The return value is 0 if the application doesn't
771 need more event processins, because of shutting down. The
772 corresponding code will be
773 while ( yield(1)) {
775 ...
776 }
777 but in turn, this call cannot be used for UI responsiveness inside
779 tight cycles.
780 The method can be called with a class string instead of an object
782 instance; however, the $::application object must be initialized.
783
785 Dmitry Karasik, <dmitry@karasik.eu.org>.
786
788 Prima, Prima::Object, Prima::Widget, Prima::Window
789perl v5.36.0 2023-03-20 Prima::Application(3)