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