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 skin SCALAR
338 Exactly same as "skin" in Prima::Widget, but is mentioned here
339 because it is possible to change the whole application skin by
340 changing this property, f ex like this:
341 use Prima::Application skin => 'flat';
343 textDirection BOOLEAN
345 Contains preferred text direction, initially calculated from the
346 preferred interface language. If 0 ( default ), the preferred text
347 direction is left-to-right (LTR), otherwise right-to-left (RTL),
348 f.ex. for arabic and hebrew languages.
349 The value is used as a default when shaping text and setting widget
351 input direction.
352 uiScaling FLOAT
354 The property contains an advisory multiplier factor, useful for UI
355 elements that have a fixed pixel value, but that would like to be
356 represented in a useful manner when the display resolution is too
357 high (on modern High-DPI displays) or too low (on ancient
358 monitors).
359 By default, it acquires the system display resolution, and sets the
361 scaling factor so that when the DPI is 96 it is 1.0, 192 it is 2.0,
362 etc. The increase step is 0.25, so that bitmaps may look not that
363 distorted. However, when the value is manually set, there is no
364 such step, any value can be set.
365 See also: "Stress" in Prima.
367 wantUnicodeInput BOOLEAN
369 Selects if the system is allowed to generate key codes in unicode.
370 Returns the effective state of the unicode input flag, which cannot
371 be changed if perl or operating system do not support UTF8.
372 If 1, "Prima::Clipboard::text" property may return UTF8 text from
374 system clipboards is available.
375 Default value: 1
377 Events
379 Clipboard $CLIPBOARD, $ACTION, $TARGET
380 With (the only implemented) $ACTION copy, is called whenever
381 another application requests clipboard data in format $TARGET. This
382 notification is handled internally to optimize image pasting
383 through the cliboard. Since the clipboard pasting semantics in
384 Prima is such that data must be supplied to the clipboard in
385 advance, before another application can request it, there is a
386 problem which format to use. In order to not encode an image or
387 other complex data in all possible formats but do that on demand
388 and in the format the other application wants, this notification
389 can be used.
390 Only implemented for X11.
392 CopyImage $CLIPBOARD, $IMAGE
394 The notification stores $IMAGE in clipboard.
395 CopyText $CLIPBOARD, $TEXT
397 The notification stores $TEXT in clipboard.
398 Die $@, $STACK
400 Called when an exception occurs inside the event loop "Prima::run".
401 By default, consults the "guiException" property, and if it is set,
402 displays the system message dialog allowing the user to decide when
403 to do next.
404 Idle
406 Called when the event loop handled all pending events, and is about
407 to sleep waiting for more.
408 PasteImage $CLIPBOARD, $$IMAGE_REF
410 The notification queries $CLIPBOARD for image content and stores in
411 $$IMAGE_REF. Default action is that 'Image' format is queried. On
412 unix, encoded formats 'image/bmp', 'image/png' etc are queried if
413 the default 'Image' is not found.
414 The "PasteImage" mechanism is devised to read images from clipboard
416 in GTK environment.
417 PasteText $CLIPBOARD, $$TEXT_REF
419 The notification queries $CLIPBOARD for text content and stores in
420 $$TEXT_REF. Default action is that 'Text' format is queried if
421 "wantUnicodeInput" is unset. Otherwise, 'UTF8' format is queried
422 beforehand.
423 The "PasteText" mechanism is devised to ease defining text
425 unicode/ascii conversion between clipboard and standard widgets, in
426 a standard way.
427 Methods
429 add_startup_notification @CALLBACK
430 CALLBACK is an array of anonymous subs, which is executed when
431 Prima::Application object is created. If the application object is
432 already created during the call, CALLBACKs called immediately.
433 Useful for add-on packages initialization.
435 begin_paint
437 Enters the enabled ( active paint ) state, returns success flag.
438 Once the object is in enabled state, painting and drawing methods
439 can perform write operations on the whole screen.
440 begin_paint_info
442 Enters the information state, returns success flag. The object
443 information state is same as enabled state ( see begin_paint()),
444 except that painting and drawing methods are not permitted to
445 change the screen.
446 close
448 Issues a system termination call, resulting in calling "close" for
449 all top-level windows. The call can be interrupted by these, and
450 thus canceled. If not canceled, stops the application event loop.
451 close_help
453 Closes the help viewer window.
454 end_paint
456 Quits the enabled state and returns application object to the
457 normal state.
458 end_paint_info
460 Quits the information state and returns application object to the
461 normal state.
462 font_encodings
464 Returns array of encodings, represented by strings, that are
465 recognized by the system and available for at least one font. Each
466 system provides different sets of encoding strings; the font
467 encodings are not portable.
468 fonts NAME = '', ENCODING = ''
470 Returns hash of font hashes ( see "Fonts" in Prima::Drawable )
471 describing fonts of NAME font family and of ENCODING. If NAME is ''
472 or "undef", returns one fonts hash for each of the font families
473 that match the ENCODING string. If ENCODING is '' or "undef", no
474 encoding match is performed. If ENCODING is not valid ( not
475 present in "font_encodings" result), it is treated as if it was ''
476 or "undef".
477 In the special case, when both NAME and ENCODING are '' or "undef",
479 each font metric hash contains element "encodings", that points to
480 array of the font encodings, available for the fonts of NAME font
481 family.
482 get_active_window
484 Returns object reference to a currently active window, if any, that
485 belongs to the program. If no such window exists, "undef" is
486 returned.
487 The exact definition of 'active window' is system-dependent, but it
489 is generally believed that an active window is the one that has
490 keyboard focus on one of its children widgets.
491 get_caption_font
493 Returns a title font, that the system uses to draw top-level window
494 captions. The method can be called with a class string instead of
495 an object instance.
496 get_default_cursor_width
498 Returns width of the system cursor in pixels. The method can be
499 called with a class string instead of an object instance.
500 get_default_font
502 Returns the default system font. The method can be called with a
503 class string instead of an object instance.
504 get_default_scrollbar_metrics
506 Returns dimensions of the system scrollbars - width of the standard
507 vertical scrollbar and height of the standard horizon scrollbar.
508 The method can be called with a class string instead of an object
509 instance.
510 get_dnd_clipboard
512 Returns the predefined special clipboard used as a proxy for drag
513 and drop interactions.
514 See also: "Widget/Drag and drop", "Clipboard/is_dnd".
516 get_default_window_borders BORDER_STYLE = bs::Sizeable
518 Returns width and height of standard system window border
519 decorations for one of "bs::XXX" constants. The method can be
520 called with a class string instead of an object instance.
521 get_focused_widget
523 Returns object reference to a currently focused widget, if any,
524 that belongs to the program. If no such widget exists, "undef" is
525 returned.
526 get_fullscreen_image
528 Syntax sugar for grabbing whole screen as in
529 $::application->get_image( 0, 0, $::application->size)
531 (MacOSX/XQuartz: get_image() does not grab all screen bits, but
533 "get_fullscreen_image" does (given Prima is compiled with Cocoa
534 library)).
535 get_hint_widget
537 Returns the hint label widget, attached automatically to
538 Prima::Application object during startup. The widget is of
539 "::hintClass" class, Prima::HintWidget by default.
540 get_image X_OFFSET, Y_OFFSET, WIDTH, HEIGHT
542 Returns Prima::Image object with WIDTH and HEIGHT dimensions filled
543 with graphic content of the screen, copied from X_OFFSET and
544 Y_OFFSET coordinates. If WIDTH and HEIGHT extend beyond the screen
545 dimensions, they are adjusted. If the offsets are outside screen
546 boundaries, or WIDTH and HEIGHT are zero or negative, "undef" is
547 returned.
548 Note: When running on MacOSX under XQuartz, the latter does not
550 give access to the whole screen, so the function will not be able
551 to grab top-level menu bar. This problem is addressed in
552 "get_fullscreen_image".
553 get_indents
555 Returns 4 integers that corresponds to extensions of eventual
556 desktop decorations that the windowing system may present on the
557 left, bottom, right, and top edges of the screen. For example, for
558 win32 this reports the size of the part of the scraan that windows
559 taskbar may occupies, if any.
560 get_printer
562 Returns the printer object, attached automatically to
563 Prima::Application object. The object is of "::printerClass" class.
564 get_message_font
566 Returns the font the system uses to draw the message text. The
567 method can be called with a class string instead of an object
568 instance.
569 get_modal_window MODALITY_TYPE = mt::Exclusive, TOPMOST = 1
571 Returns the modal window, that resides on an end of a modality
572 chain. MODALITY_TYPE selects the chain, and can be either
573 "mt::Exclusive" or "mt::Shared". TOPMOST is a boolean flag,
574 selecting the lookup direction; if it is 1, the 'topmost' window is
575 returned, if 0, the 'lowest' one ( in a simple case when window A
576 is made modal (executed) after modal window B, the A window is the
577 'topmost' one ).
578 If a chain is empty "undef" is returned. In case when a chain
580 consists of just one window, TOPMOST value is apparently
581 irrelevant.
582 get_monitor_rects
584 Returns set of rects in format [X,Y,WIDTH,HEIGHT] identifying
585 monitor configurations. Currently works under X11 only.
586 get_scroll_rate
588 Returns two integer values of two system-specific scrolling
589 timeouts. The first is the initial timeout, that is applied when
590 the user drags the mouse from a scrollable widget ( a text field,
591 for example ), and the widget is about to scroll, but the actual
592 scroll is performed after the timeout is expired. The second is the
593 repetitive timeout, - if the dragging condition did not change, the
594 scrolling performs automatically after this timeout. The timeout
595 values are in milliseconds.
596 get_system_info
598 Returns a hash with information about the system. The hash result
599 contains the following keys:
600 apc One of "apc::XXX" constants, reflecting the platform.
602 Currently, the list of the supported platforms is:
603 apc::Win32
605 apc::Unix
606 gui One of "gui::XXX" constants, reflecting the graphic user
608 interface used in the system:
609 gui::Default
611 gui::PM
612 gui::Windows
613 gui::XLib
614 gui::GTK
615 guiDescription
617 Description of graphic user interface, returned as an arbitrary
618 string.
619 guiLanguage
621 Preferred language of the interface, returned as an ISO 639
622 code.
623 system
625 An arbitrary string, representing the operating system
626 software.
627 release
629 An arbitrary string, reflecting the OS version information.
630 vendor
632 The OS vendor string
633 architecture
635 The machine architecture string
636 The method can be called with a class string instead of an object
638 instance.
639 get_system_value
641 Returns the system integer value, associated with one of "sv::XXX"
642 constants. The constants are:
643 sv::YMenu - height of menu bar in top-level windows
645 sv::YTitleBar - height of title bar in top-level windows
646 sv::XIcon - width and height of main icon dimensions,
647 sv::YIcon acceptable by the system
648 sv::XSmallIcon - width and height of alternate icon dimensions,
649 sv::YSmallIcon acceptable by the system
650 sv::XPointer - width and height of mouse pointer icon
651 sv::YPointer acceptable by the system
652 sv::XScrollbar - width of the default vertical scrollbar
653 sv::YScrollbar - height of the default horizontal scrollbar
654 ( see get_default_scrollbar_metrics() )
655 sv::XCursor - width of the system cursor
656 ( see get_default_cursor_width() )
657 sv::AutoScrollFirst - the initial and the repetitive
658 sv::AutoScrollNext scroll timeouts
659 ( see get_scroll_rate() )
660 sv::InsertMode - the system insert mode
661 ( see insertMode )
662 sv::XbsNone - widths and heights of the top-level window
663 sv::YbsNone decorations, correspondingly, with borderStyle
664 sv::XbsSizeable bs::None, bs::Sizeable, bs::Single, and
665 sv::YbsSizeable bs::Dialog.
666 sv::XbsSingle ( see get_default_window_borders() )
667 sv::YbsSingle
668 sv::XbsDialog
669 sv::YbsDialog
670 sv::MousePresent - 1 if the mouse is present, 0 otherwise
671 sv::MouseButtons - number of the mouse buttons
672 sv::WheelPresent - 1 if the mouse wheel is present, 0 otherwise
673 sv::SubmenuDelay - timeout ( in ms ) before a sub-menu shows on
674 an implicit selection
675 sv::FullDrag - 1 if the top-level windows are dragged dynamically,
676 0 - with marquee mode
677 sv::DblClickDelay - mouse double-click timeout in milliseconds
678 sv::ShapeExtension - 1 if Prima::Widget::shape functionality is supported,
679 0 otherwise
680 sv::ColorPointer - 1 if system accepts color pointer icons.
681 sv::CanUTF8_Input - 1 if system can generate key codes in unicode
682 sv::CanUTF8_Output - 1 if system can output utf8 text
683 sv::CompositeDisplay - 1 if system uses double-buffering and alpha composition for the desktop,
684 0 if it doesn't, -1 if unknown
685 sv::LayeredWidgets - 1 if system supports layering
686 sv::FixedPointerSize - 0 if system doesn't support arbitrary sized pointers and will resize custom icons to the system size
687 sv::MenuCheckSize - width and height of default menu check icon
688 sv::FriBidi - 1 if Prima is compiled with libfribidi and full bidi unicode support is available
689 sv::Antialias - 1 if system supports antialiasing and alpha layer for primitives
690 sv::LibThai - 1 if Prima is compiled with libthai
691 The method can be called with a class string instead of an object
693 instance.
694 get_widget_from_handle HANDLE
696 HANDLE is an integer value of a toolkit widget. It is usually
697 passed to the program by other IPC means, so it returns the
698 associated widget. If no widget is associated with HANDLE, "undef"
699 is returned.
700 get_widget_from_point X_OFFSET, Y_OFFSET
702 Returns the widget that occupies screen area under
703 (X_OFFSET,Y_OFFSET) coordinates. If no toolkit widget are found,
704 "undef" is returned.
705 go The main event loop. Called by
707 run Prima;
709 standard code. Returns when the program is about to terminate, if
711 "stop" was called, or if the exception was signaled. In the latter
712 two cases, the loop can be safely re-started.
713 lock
715 Effectively blocks the graphic output for all widgets. The output
716 can be restored with unlock().
717 load_font FONTNAME
719 Registers font resource in system-specific format. The resource is
720 freed after prgram ends.
721 Notes for win32: To add a font whose information comes from several
723 resource files, point FONTNAME to a string with the file names
724 separated by a "|" - for example, " abcxxxxx.pfm | abcxxxxx.pfb ".
725 Notes for unix: available only when Prima is compiled with
727 fontconfig and Xft .
728 Returns number of font resources added.
730 open_help TOPIC
732 Opens the help viewer window with TOPIC string in link POD format (
733 see perlpod ) - the string is treated as "manpage/section", where
734 'manpage' is the file with POD content and 'section' is the topic
735 inside the manpage.
736 Alternatively can handle the syntax in form of "
738 file://path|section " where "path" is the file with the pod content
739 and "section" is an optional pod section within the file.
740 stop
742 Breaks the event loop. The loop can be started again by "go"
743 thereafter.
744 sync
746 Synchronizes all pending requests where there are any. Is an
747 effective XSync(false) on X11, and is a no-op otherwise.
748 sys_action CALL
750 CALL is an arbitrary string of the system service name and the
751 parameters to it. This functionality is non-portable, and its
752 usage should be avoided. The system services provided are not
753 documented and subject to change. The actual services can be looked
754 in the toolkit source code under apc_system_action tag.
755 unlock
757 Unblocks the graphic output for all widgets, previously locked with
758 lock().
759 yield $wait_for_event=0
761 An event dispatcher, called from within the event loop. If the
762 event loop can be schematized, then in
763 while ( application not closed ) {
765 yield
766 }
767 draft yield() is the only function, called repeatedly within the
769 event loop. yield(0) call shouldn't be used to organize event
770 loops, but it can be employed to process stacked system events
771 explicitly, to increase responsiveness of a program, for example,
772 inside a long calculation cycle.
773 yield(1) though is adapted exactly for external implementation of
775 event loops; it does exactly the same as yeild(0), but if there are
776 no events, it sleeps until there comes at least one, processes it,
777 and then returns. The return value is 0 if the application doesn't
778 need more event processings, because of shutting down. The
779 corresponding code will be
780 while ( yield(1)) {
782 ...
783 }
784 but in turn, this call cannot be used for UI responsiveness inside
786 tight cycles.
787 The method can be called with a class string instead of an object
789 instance; however, the $::application object must be initialized.
790
792 Dmitry Karasik, <dmitry@karasik.eu.org>.
793
795 Prima, Prima::Object, Prima::Widget, Prima::Window
796perl v5.38.0 2023-07-21 Prima::Application(3)