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

NAME

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

DESCRIPTION

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

SYNOPSIS

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

USAGE

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

API

167   Properties
168       autoClose BOOLEAN
169           If set to 1, issues "close()" after the last top-level window is
170           destroyed.  Does not influence anything if set to 0.
171
172           This feature is designed to help with general 'one main window'
173           application layouts.
174
175           Default value: 0
176
177       icon OBJECT
178           Holds the icon object, associated with the application.  If
179           "undef", a system-provided default icon is assumed.  Prima::Window
180           object instances inherit the application icon by default.
181
182       insertMode BOOLEAN
183           A system boolean flag, showing whether text widgets through the
184           system should insert ( 1 ) or overwrite ( 0 ) text on user input.
185           Not all systems provide the global state of the flag.
186
187       helpClass STRING
188           Specifies a class of object, used as a help viewing package.  The
189           default value is Prima::HelpViewer.
190
191           Run-time changes to the property do not affect the help subsystem
192           until "close_help" call is made.
193
194       helpModule STRING
195           Specifies a perl module, loaded indirectly when a help viewing call
196           is made via "open_help".  Used when "::helpClass" property is
197           overridden and the new class is contained in a third-party module.
198
199           Run-time changes to the property do not affect the help subsystem
200           until "close_help" call is made.
201
202       hintClass STRING
203           Create-only property.
204
205           Specifies a class of widget, used as the hint label.
206
207           Default value: Prima::HintWidget
208
209       hintColor COLOR
210           An alias to foreground color property for the hint label widget.
211
212       hintBackColor COLOR
213           An alias to background color property for the hint label widget.
214
215       hintFont %FONT
216           An alias to font property for the hint label widget.
217
218       hintPause TIMEOUT
219           Selects the timeout in milliseconds before the hint label is shown
220           when the mouse pointer hovers over a widget.
221
222       modalHorizon BOOLEAN
223           A read-only property. Used as a landmark for the lowest-level modal
224           horizon.  Always returns 1.
225
226       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
232       printerClass STRING
233           Create-only property.
234
235           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
239       printerModule STRING
240           Create-only property.
241
242           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
247       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
252       size WIDTH, HEIGHT
253           A read-only property.
254
255           Returns two integers, width and height of the screen.
256
257       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
265       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
272           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
278           See also: "Stress" in Prima.
279
280       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
285           If 1, "Prima::Clipboard::text" property may return UTF8 text from
286           system clipboards is available.
287
288           Default value: 0
289
290   Events
291       CopyImage $CLIPBOARD, $IMAGE
292           The notification stores $IMAGE in clipboard.
293
294       CopyText $CLIPBOARD, $TEXT
295           The notification stores $TEXT in clipboard.
296
297       Idle
298           Called when the event loop handled all pending events, and is about
299           to sleep waiting for more.
300
301       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
307           The "PasteImage" mechanism is devised to read images from clipboard
308           in GTK environment.
309
310       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
316           The "PasteText" mechanism is devised to ease defining text
317           unicode/ascii conversion between clipboard and standard widgets, in
318           a standard way.
319
320   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
326           Useful for add-on packages initialization.
327
328       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
333       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
339       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
344       close_help
345           Closes the help viewer window.
346
347       end_paint
348           Quits the enabled state and returns application object to the
349           normal state.
350
351       end_paint_info
352           Quits the information state and returns application object to the
353           normal state.
354
355       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
361       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
370           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
375       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
380           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
384       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
389       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
393       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
397       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
403       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
408       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
413       get_fullscreen_image
414           Syntax sugar for grabbing whole screen as in
415
416              $::application->get_image( 0, 0, $::application->size)
417
418           (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
422       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
427       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
435           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
440       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
447       get_printer
448           Returns the printer object, attached automatically to
449           Prima::Application object. The object is of "::printerClass" class.
450
451       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
456       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
465           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
469       get_monitor_rects
470           Returns set of rects in format [X,Y,WIDTH,HEIGHT] identifying
471           monitor configurations. Currently works under X11 only.
472
473       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
483       get_system_info
484           Returns a hash with information about the system.  The hash result
485           contains the following keys:
486
487           apc One of "apc::XXX" constants, reflecting the platform.
488               Currently, the list of the supported platforms is:
489
490                       apc::Win32
491                       apc::Unix
492
493           gui One of "gui::XXX" constants, reflecting the graphic user
494               interface used in the system:
495
496                       gui::Default
497                       gui::PM
498                       gui::Windows
499                       gui::XLib
500                       gui::GTK
501
502           guiDescription
503               Description of graphic user interface, returned as an arbitrary
504               string.
505
506           system
507               An arbitrary string, representing the operating system
508               software.
509
510           release
511               An arbitrary string, reflecting the OS version information.
512
513           vendor
514               The OS vendor string
515
516           architecture
517               The machine architecture string
518
519           The method can be called with a class string instead of an object
520           instance.
521
522       get_system_value
523           Returns the system integer value, associated with one of "sv::XXX"
524           constants. The constants are:
525
526                   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
571           The method can be called with a class string instead of an object
572           instance.
573
574       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
580       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
585       go  The main event loop. Called by
586
587           run Prima;
588
589           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
593       lock
594           Effectively blocks the graphic output for all widgets.  The output
595           can be restored with "unlock()".
596
597       load_font FONTNAME
598           Registers font resource in system-specific format. The resource is
599           freed after prgram ends.
600
601           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
605           Notes for unix: available only when Prima is compiled with
606           fontconfig and Xft .
607
608           Returns number of font resources added.
609
610       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
616       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
620       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
627       unlock
628           Unblocks the graphic output for all widgets, previously locked with
629           "lock()".
630
631       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
635                   while ( application not closed ) {
636                           yield
637                   }
638
639           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
645           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
652                   while ( yield(1)) {
653                       ...
654                   }
655
656           but in turn, this call cannot be used for UI responsiveness inside
657           tight cycles.
658
659           The method can be called with a class string instead of an object
660           instance; however, the $::application object must be initialized.
661

AUTHOR

663       Dmitry Karasik, <dmitry@karasik.eu.org>.
664

SEE ALSO

666       Prima, Prima::Object, Prima::Widget, Prima::Window
667
668
669
670perl v5.30.1                      2020-01-30             Prima::Application(3)
Impressum