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 Hint
93 $::application hosts a special Prima::HintWidget class object,
94 accessible via "get_hint_widget()", but with color and font
95 functions aliased ( "::hintColor", "::hintBackColor", "::hintFont"
96 ).
97 This widget serves as a hint label, floating over widgets if the
99 mouse pointer hovers longer than "::hintPause" milliseconds.
100 Prima::Application internally manages all hint functionality. The
102 hint widget itself, however, can be replaced before application
103 object is created, using "::hintClass" create-only property.
104 Printer
106 Result of get_printer method points to an automatically created
107 printer object, responsible for the system-driven printing.
108 Depending on the operating system, it is either Prima::Printer, if
109 the system provides GUI printing capabilities, or generic
110 Prima::PS::Printer, the PostScript document interface.
111 See Prima::Printer for details.
113 Clipboard
115 $::application hosts set of Prima::Clipboard objects, created
116 automatically to reflect the system-provided clipboard IPC
117 functionality. Their number depends on the system, - under X11
118 environment there is three clipboard objects, and only one under
119 Win32.
120 These are no methods to access these clipboard objects, except
122 fetch() ( or, the indirect name calling ) - the clipboard objects
123 are named after the system clipboard names, which are returned by
124 Prima::Clipboard::get_standard_clipboards.
125 The default clipboard is named Clipboard, and is accessible via
127 my $clipboard = $::application-> Clipboard;
129 code.
131 See Prima::Clipboard for details.
133 Help subsystem
135 The toolkit has a built-in help viewer, that understands perl's
136 native POD ( plain old documentation ) format. Whereas the viewer
137 functionality itself is part of the toolkit, and resides in
138 "Prima::HelpViewer" module, any custom help viewing module can be
139 assigned. Create-only "Prima::Application" properties "::helpClass"
140 and "::helpModule" can be used to set these options.
141 "Prima::Application" provides two methods for communicating with
143 the help viewer window: "open_help()" opens a selected topic in the
144 help window, and "close_help()" closes the window.
145 System-dependent information
147 A complex program will need eventually more information than the
148 toolkit provides. Or, knowing the toolkit boundaries in some
149 platforms, the program changes its behavior accordingly. Both these
150 topics are facilitated by extra system information, returned by
151 Prima::Application methods. "get_system_value" returns a system
152 value for one of "sv::XXX" constants, so the program can read the
153 system-specific information. As well as "get_system_info" method,
154 that returns the short description of the system, it is the
155 portable call. To the contrary, "sys_action" method is a wrapper
156 to system-dependent functionality, called in non-portable way. This
157 method is never used within the toolkit, and its usage is
158 discouraged, primarily because its options do not serve the toolkit
159 design, are subject to changes and cannot be relied upon.
160
162 Properties
163 autoClose BOOLEAN
164 If set to 1, issues "close()" after the last top-level window is
165 destroyed. Does not influence anything if set to 0.
166 This feature is designed to help with general 'one main window'
168 application layouts.
169 Default value: 0
171 icon OBJECT
173 Holds the icon object, associated with the application. If
174 "undef", a system-provided default icon is assumed. Prima::Window
175 object instances inherit the application icon by default.
176 insertMode BOOLEAN
178 A system boolean flag, showing whether text widgets through the
179 system should insert ( 1 ) or overwrite ( 0 ) text on user input.
180 Not all systems provide the global state of the flag.
181 helpClass STRING
183 Specifies a class of object, used as a help viewing package. The
184 default value is Prima::HelpViewer.
185 Run-time changes to the property do not affect the help subsystem
187 until "close_help" call is made.
188 helpModule STRING
190 Specifies a perl module, loaded indirectly when a help viewing call
191 is made via "open_help". Used when "::helpClass" property is
192 overridden and the new class is contained in a third-party module.
193 Run-time changes to the property do not affect the help subsystem
195 until "close_help" call is made.
196 hintClass STRING
198 Create-only property.
199 Specifies a class of widget, used as the hint label.
201 Default value: Prima::HintWidget
203 hintColor COLOR
205 An alias to foreground color property for the hint label widget.
206 hintBackColor COLOR
208 An alias to background color property for the hint label widget.
209 hintFont %FONT
211 An alias to font property for the hint label widget.
212 hintPause TIMEOUT
214 Selects the timeout in milliseconds before the hint label is shown
215 when the mouse pointer hovers over a widget.
216 modalHorizon BOOLEAN
218 A read-only property. Used as a landmark for the lowest-level modal
219 horizon. Always returns 1.
220 palette [ @PALETTE ]
222 Used only within paint and information modes. Selects solid colors
223 in a system palette, as many as possible. PALETTE is an array of
224 integer triplets, where each is red, green, and blue component,
225 with intensity range from 0 to 255.
226 printerClass STRING
228 Create-only property.
229 Specifies a class of object, used as a printer. The default value
231 is system-dependent, but is either "Prima::Printer" or
232 "Prima::PS::Printer".
233 printerModule STRING
235 Create-only property.
236 Specifies a perl module, loaded indirectly before a printer object
238 of "::printerClass" class is created. Used when "::printerClass"
239 property is overridden and the new class is contained in a third-
240 party module.
241 pointerVisible BOOLEAN
243 Governs the system pointer visibility. If 0, hides the pointer so
244 it is not visible in all system windows. Therefore this property
245 usage must be considered with care.
246 size WIDTH, HEIGHT
248 A read-only property.
249 Returns two integers, width and height of the screen.
251 showHint BOOLEAN
253 If 1, the toolkit is allowed to show the hint label over a widget.
254 If 0, the display of the hint is forbidden. In addition to
255 functionality of "::showHint" property in Prima::Widget,
256 Prima::Application::showHint is another layer of hint visibility
257 control - if it is 0, all hint actions are disabled, disregarding
258 "::showHint" value in widgets.
259 uiScaling FLOAT
261 The property contains an advisory multiplier factor, useful for UI
262 elements that have a fixed pixel value, but that would like to be
263 represented in a useful manner when the display resolution is too
264 high (on modern High-DPI displays) or too low (on ancient
265 monitors).
266 By default, it acquires the system display resolution, and sets the
268 scaling factor so that when the DPI is 96 it is 1.0, 192 it is 2.0,
269 etc. The increase step is 0.25, so that bitmaps may look not that
270 distorted. However, when the value is manually set, there is no
271 such step, any value can be set.
272 See also: "Stress" in Prima.
274 wantUnicodeInput BOOLEAN
276 Selects if the system is allowed to generate key codes in unicode.
277 Returns the effective state of the unicode input flag, which cannot
278 be changed if perl or operating system do not support UTF8.
279 If 1, "Prima::Clipboard::text" property may return UTF8 text from
281 system clipboards is available.
282 Default value: 0
284 Events
286 CopyImage $CLIPBOARD, $IMAGE
287 The notification stores $IMAGE in clipboard.
288 CopyText $CLIPBOARD, $TEXT
290 The notification stores $TEXT in clipboard.
291 Idle
293 Called when the event loop handled all pending events, and is about
294 to sleep waiting for more.
295 PasteImage $CLIPBOARD, $$IMAGE_REF
297 The notification queries $CLIPBOARD for image content and stores in
298 $$IMAGE_REF. Default action is that 'Image' format is queried. On
299 unix, encoded formats 'image/bmp', 'image/png' etc are queried if
300 the default 'Image' is not found.
301 The "PasteImage" mechanism is devised to read images from clipboard
303 in GTK environment.
304 PasteText $CLIPBOARD, $$TEXT_REF
306 The notification queries $CLIPBOARD for text content and stores in
307 $$TEXT_REF. Default action is that 'Text' format is queried if
308 "wantUnicodeInput" is unset. Otherwise, 'UTF8' format is queried
309 beforehand.
310 The "PasteText" mechanism is devised to ease defining text
312 unicode/ascii conversion between clipboard and standard widgets, in
313 a standard way.
314 Methods
316 add_startup_notification @CALLBACK
317 CALLBACK is an array of anonymous subs, which is executed when
318 Prima::Application object is created. If the application object is
319 already created during the call, CALLBACKs called immediately.
320 Useful for add-on packages initialization.
322 begin_paint
324 Enters the enabled ( active paint ) state, returns success flag.
325 Once the object is in enabled state, painting and drawing methods
326 can perform write operations on the whole screen.
327 begin_paint_info
329 Enters the information state, returns success flag. The object
330 information state is same as enabled state ( see "begin_paint()"),
331 except that painting and drawing methods are not permitted to
332 change the screen.
333 close
335 Issues a system termination call, resulting in calling "close" for
336 all top-level windows. The call can be interrupted by these, and
337 thus canceled. If not canceled, stops the application event loop.
338 close_help
340 Closes the help viewer window.
341 end_paint
343 Quits the enabled state and returns application object to the
344 normal state.
345 end_paint_info
347 Quits the information state and returns application object to the
348 normal state.
349 font_encodings
351 Returns array of encodings, represented by strings, that are
352 recognized by the system and available for at least one font. Each
353 system provides different sets of encoding strings; the font
354 encodings are not portable.
355 fonts NAME = '', ENCODING = ''
357 Returns hash of font hashes ( see "Fonts" in Prima::Drawable )
358 describing fonts of NAME font family and of ENCODING. If NAME is ''
359 or "undef", returns one fonts hash for each of the font families
360 that match the ENCODING string. If ENCODING is '' or "undef", no
361 encoding match is performed. If ENCODING is not valid ( not
362 present in "font_encodings" result), it is treated as if it was ''
363 or "undef".
364 In the special case, when both NAME and ENCODING are '' or "undef",
366 each font metric hash contains element "encodings", that points to
367 array of the font encodings, available for the fonts of NAME font
368 family.
369 get_active_window
371 Returns object reference to a currently active window, if any, that
372 belongs to the program. If no such window exists, "undef" is
373 returned.
374 The exact definition of 'active window' is system-dependent, but it
376 is generally believed that an active window is the one that has
377 keyboard focus on one of its children widgets.
378 get_caption_font
380 Returns a title font, that the system uses to draw top-level window
381 captions. The method can be called with a class string instead of
382 an object instance.
383 get_default_cursor_width
385 Returns width of the system cursor in pixels. The method can be
386 called with a class string instead of an object instance.
387 get_default_font
389 Returns the default system font. The method can be called with a
390 class string instead of an object instance.
391 get_default_scrollbar_metrics
393 Returns dimensions of the system scrollbars - width of the standard
394 vertical scrollbar and height of the standard horizon scrollbar.
395 The method can be called with a class string instead of an object
396 instance.
397 get_default_window_borders BORDER_STYLE = bs::Sizeable
399 Returns width and height of standard system window border
400 decorations for one of "bs::XXX" constants. The method can be
401 called with a class string instead of an object instance.
402 get_focused_widget
404 Returns object reference to a currently focused widget, if any,
405 that belongs to the program. If no such widget exists, "undef" is
406 returned.
407 get_hint_widget
409 Returns the hint label widget, attached automatically to
410 Prima::Application object during startup. The widget is of
411 "::hintClass" class, Prima::HintWidget by default.
412 get_image X_OFFSET, Y_OFFSET, WIDTH, HEIGHT
414 Returns Prima::Image object with WIDTH and HEIGHT dimensions filled
415 with graphic content of the screen, copied from X_OFFSET and
416 Y_OFFSET coordinates. If WIDTH and HEIGHT extend beyond the screen
417 dimensions, they are adjusted. If the offsets are outside screen
418 boundaries, or WIDTH and HEIGHT are zero or negative, "undef" is
419 returned.
420 get_indents
422 Returns 4 integers that corresponds to extensions of eventual
423 desktop decorations that the windowing system may present on the
424 left, bottom, right, and top edges of the screen. For example, for
425 win32 this reports the size of the part of the scraan that windows
426 taskbar may occupies, if any.
427 get_printer
429 Returns the printer object, attached automatically to
430 Prima::Application object. The object is of "::printerClass" class.
431 get_message_font
433 Returns the font the system uses to draw the message text. The
434 method can be called with a class string instead of an object
435 instance.
436 get_modal_window MODALITY_TYPE = mt::Exclusive, TOPMOST = 1
438 Returns the modal window, that resides on an end of a modality
439 chain. MODALITY_TYPE selects the chain, and can be either
440 "mt::Exclusive" or "mt::Shared". TOPMOST is a boolean flag,
441 selecting the lookup direction; if it is 1, the 'topmost' window is
442 returned, if 0, the 'lowest' one ( in a simple case when window A
443 is made modal (executed) after modal window B, the A window is the
444 'topmost' one ).
445 If a chain is empty "undef" is returned. In case when a chain
447 consists of just one window, TOPMOST value is apparently
448 irrelevant.
449 get_monitor_rects
451 Returns set of rects in format [X,Y,WIDTH,HEIGHT] identifying
452 monitor configurations. Currently works under X11 only.
453 get_scroll_rate
455 Returns two integer values of two system-specific scrolling
456 timeouts. The first is the initial timeout, that is applied when
457 the user drags the mouse from a scrollable widget ( a text field,
458 for example ), and the widget is about to scroll, but the actual
459 scroll is performed after the timeout is expired. The second is the
460 repetitive timeout, - if the dragging condition did not change, the
461 scrolling performs automatically after this timeout. The timeout
462 values are in milliseconds.
463 get_system_info
465 Returns a hash with information about the system. The hash result
466 contains the following keys:
467 apc One of "apc::XXX" constants, reflecting the platform.
469 Currently, the list of the supported platforms is:
470 apc::Win32
472 apc::Unix
473 gui One of "gui::XXX" constants, reflecting the graphic user
475 interface used in the system:
476 gui::Default
478 gui::PM
479 gui::Windows
480 gui::XLib
481 gui::GTK2
482 guiDescription
484 Description of graphic user interface, returned as an arbitrary
485 string.
486 system
488 An arbitrary string, representing the operating system
489 software.
490 release
492 An arbitrary string, reflecting the OS version information.
493 vendor
495 The OS vendor string
496 architecture
498 The machine architecture string
499 The method can be called with a class string instead of an object
501 instance.
502 get_system_value
504 Returns the system integer value, associated with one of "sv::XXX"
505 constants. The constants are:
506 sv::YMenu - height of menu bar in top-level windows
508 sv::YTitleBar - height of title bar in top-level windows
509 sv::XIcon - width and height of main icon dimensions,
510 sv::YIcon acceptable by the system
511 sv::XSmallIcon - width and height of alternate icon dimensions,
512 sv::YSmallIcon acceptable by the system
513 sv::XPointer - width and height of mouse pointer icon
514 sv::YPointer acceptable by the system
515 sv::XScrollbar - width of the default vertical scrollbar
516 sv::YScrollbar - height of the default horizontal scrollbar
517 ( see get_default_scrollbar_metrics() )
518 sv::XCursor - width of the system cursor
519 ( see get_default_cursor_width() )
520 sv::AutoScrollFirst - the initial and the repetitive
521 sv::AutoScrollNext scroll timeouts
522 ( see get_scroll_rate() )
523 sv::InsertMode - the system insert mode
524 ( see insertMode )
525 sv::XbsNone - widths and heights of the top-level window
526 sv::YbsNone decorations, correspondingly, with borderStyle
527 sv::XbsSizeable bs::None, bs::Sizeable, bs::Single, and
528 sv::YbsSizeable bs::Dialog.
529 sv::XbsSingle ( see get_default_window_borders() )
530 sv::YbsSingle
531 sv::XbsDialog
532 sv::YbsDialog
533 sv::MousePresent - 1 if the mouse is present, 0 otherwise
534 sv::MouseButtons - number of the mouse buttons
535 sv::WheelPresent - 1 if the mouse wheel is present, 0 otherwise
536 sv::SubmenuDelay - timeout ( in ms ) before a sub-menu shows on
537 an implicit selection
538 sv::FullDrag - 1 if the top-level windows are dragged dynamically,
539 0 - with marquee mode
540 sv::DblClickDelay - mouse double-click timeout in milliseconds
541 sv::ShapeExtension - 1 if Prima::Widget::shape functionality is supported,
542 0 otherwise
543 sv::ColorPointer - 1 if system accepts color pointer icons.
544 sv::CanUTF8_Input - 1 if system can generate key codes in unicode
545 sv::CanUTF8_Output - 1 if system can output utf8 text
546 sv::CompositeDisplay - 1 if system uses double-buffering and alpha composition for the desktop,
547 0 if it doesn't, -1 if unknown
548 sv::LayeredWidgets - 1 if system supports layering
549 sv::DWM - 1 if system supports DWM API
550 The method can be called with a class string instead of an object
552 instance.
553 get_widget_from_handle HANDLE
555 HANDLE is an integer value of a toolkit widget. It is usually
556 passed to the program by other IPC means, so it returns the
557 associated widget. If no widget is associated with HANDLE, "undef"
558 is returned.
559 get_widget_from_point X_OFFSET, Y_OFFSET
561 Returns the widget that occupies screen area under
562 (X_OFFSET,Y_OFFSET) coordinates. If no toolkit widget are found,
563 "undef" is returned.
564 go The main event loop. Called by
566 run Prima;
568 standard code. Returns when the program is about to terminate, or
570 if the exception was signaled. In the latter case, the loop can be
571 safely re-started.
572 lock
574 Effectively blocks the graphic output for all widgets. The output
575 can be restored with "unlock()".
576 load_font FONTNAME
578 Registers font resource in system-specific format. The resource is
579 freed after prgram ends.
580 Notes for win32: To add a font whose information comes from several
582 resource files, point FONTNAME to a string with the file names
583 separated by a "|" - for example, " abcxxxxx.pfm | abcxxxxx.pfb ".
584 Notes for unix: available only when Prima is compiled with
586 fontconfig and Xft .
587 Returns number of font resources added.
589 open_help TOPIC
591 Opens the help viewer window with TOPIC string in link POD format (
592 see perlpod ) - the string is treated as "manpage/section", where
593 'manpage' is the file with POD content and 'section' is the topic
594 inside the manpage.
595 sync
597 Synchronizes all pending requests where there are any. Is an
598 effective "XSync(false)" on X11, and is a no-op otherwise.
599 sys_action CALL
601 CALL is an arbitrary string of the system service name and the
602 parameters to it. This functionality is non-portable, and its
603 usage should be avoided. The system services provided are not
604 documented and subject to change. The actual services can be looked
605 in the toolkit source code under apc_system_action tag.
606 unlock
608 Unblocks the graphic output for all widgets, previously locked with
609 "lock()".
610 yield $wait_for_event=0
612 An event dispatcher, called from within the event loop. If the
613 event loop can be schematized, then in
614 while ( application not closed ) {
616 yield
617 }
618 draft yield() is the only function, called repeatedly within the
620 event loop. yield(0) call shouldn't be used to organize event
621 loops, but it can be employed to process stacked system events
622 explicitly, to increase responsiveness of a program, for example,
623 inside a long calculation cycle.
624 yield(1) though is adapted exactly for external implementation of
626 event loops; it does exactly the same as yeild(0), but if there are
627 no events, it sleeps until there comes at least one, processes it,
628 and then returns. The return value is 0 if the application doesn't
629 need more event processins, because of shutting down. The
630 corresponding code will be
631 while ( yield(1)) {
633 ...
634 }
635 but in turn, this call cannot be used for UI responsiveness inside
637 tight cycles.
638 The method can be called with a class string instead of an object
640 instance; however, the $::application object must be initialized.
641
643 Dmitry Karasik, <dmitry@karasik.eu.org>.
644
646 Prima, Prima::Object, Prima::Widget, Prima::Window
647perl v5.28.0 2017-02-28 Prima::Application(3)