1pod::Prima::faq(3)    User Contributed Perl Documentation   pod::Prima::faq(3)
2
3
4

NAME

6       Prima::faq - Frequently asked questions about Prima
7

DESCRIPTION

9       The FAQ covers various topics around Prima, such as distribution,
10       compilation, installation, and programming.
11

COMMON

13   What is Prima?
14       Prima is a general purpose extensible graphical user interface toolkit
15       with a rich set of standard widgets and an emphasis on 2D image
16       processing tasks. A Perl program using PRIMA looks and behaves
17       identically on X, Win32.
18
19   Yeah, right. So what is Prima again?
20       Ok. A Yet Another Perl GUI.
21
22   Why bother with the Yet Another thing, while there is Perl-Tk and plenty of
23       others?
24       Prima was started on OS/2, where Tk didn't really run. We have had two
25       options - either port Tk, or write something on our own, probably
26       better than the existing tools.  We believe that we've succeeded.
27
28       Interestingly enough, Prima still builds for OS/2 (as of July 2012),
29       but its support was killed because noone needs it anyway.
30
31   Why Perl?
32       Why not? Perl is great. The high-level GUI logic fits badly into C,
33       C++, or the like, so a scripting language is probably the way to go
34       here.
35
36   But I want to use Prima in another language.
37       Unless your language has runtime binding with perl, you cannot.
38
39   Who wrote Prima?
40       Dmitry Karasik implemented the majority of the toolkit, after the
41       original idea by Anton Berezin. The latter and set of contributors
42       helped the development of the toolkit since then.
43
44   What is the copyright?
45       The copyright is a modified BSD license, where only two first
46       paragraphs remain out of the original four. The text of copyright is
47       present is almost all files of the toolkit.
48
49   I'd like to contribute.
50       You can do this is several ways. The project would probably best
51       benefit from the advocacy, because not many people use it. Of course,
52       you can send in new widgets, patches, suggestions, or even donations.
53       Also, documentation is the thing that needs a particular attention,
54       since my native language is not English, so if there are volunteers for
55       polishing of the Prima docs, you are very welcome.
56

INSTALLATION

58   Where can I download Prima?
59       <http://www.prima.eu.org> contains links to source and binary download
60       resources, instructions on how to subscribe to the Prima mailing list,
61       documentation, and some other useful info.
62
63   What is better, source or binary?
64       Depends where your are and what are your goals. On unix, the best is to
65       use the source. On win32 the binaries probably are preferred. If you
66       happen to use cygwin you probably still better off using the source.
67
68   How to install binary distribution?
69       First, check if you've downloaded Prima binary for the correct version
70       of Perl.  For win32 ActiveState builds, difference in the minor digits
71       of the Perl version shouldn't be a problem, for example, binary
72       distribution for Perl build #805 should work with Perl build #808, etc
73       etc.
74
75       To install, unpack the archive and type 'perl ms_install.pl'.  The
76       files will be copied into the perl tree.
77
78   How to compile Prima from source?
79       Type the following:
80
81          perl Makefile.PL
82          make
83          make install
84
85       If the 'perl Makefile.PL' fails complaining to strange errors, you can
86       check makefile.log to see if anything is wrong. A typical situation
87       here is that Makefile.PL may report that is cannot find Perl library,
88       for example, where there actually it invokes the compiler in a wrong
89       way.
90
91       Note, that in order to get Prima working from sources, your system must
92       contain graphic libraries, such as libgif or ligjpeg, for Prima to load
93       graphic files.
94
95   What's about the graphic libraries?
96       To load and save images, Prima employs graphic libraries. Such as, to
97       load GIF files, libgif library is used, etc. Makefile.PL finds
98       available libraries and links Prima against these. It is possible to
99       compile Prima without any, but this is not really useful.
100
101       On every supported platform Prima can make use of the following graphic
102       libraries:
103
104          libX11   - XBM bitmaps
105          libXpm   - Xpm pixmaps
106          libjpeg  - JPEG images
107          libgif   - GIF images
108          libpng   - PNG images
109          libtiff  - tiff images
110          libwebp,libwebpdemux,libwebpmux  - WebP images
111
112       Strawberry perl and Cygwin come with most of them, so on these
113       installations Prima just compiles without any throuble. For other perl
114       builds, use one of "Prima::codecs::" modules that contains the needed
115       include and lib files. If you're installing Prima through CPAN, that
116       gets done authomatically.
117
118   img/codec_XXX.c compile error
119       "img/codec_XXX.c" files are C sources for support of the graphic
120       libraries. In case a particular codec does not compile, the ultimate
121       fix is to remove the file and re-run Makefile.PL . This way, the
122       problem can be avoided easily, although at cost of a lacking support
123       for a graphic format.
124
125   How'd I check what libraries are compiled in?
126          perl -MPrima -e 'print map { $_->{name}.qq(\n) } @{Prima::Image->codecs};'
127
128   I have a graphic library installed, but Makefile.PL doesn't find it
129       The library is probably located in a weird directory so Makefile.PL
130       must be told to use it by adding LIBPATH+=/some/weird/lib, and possibly
131       INCPATH+=/some/weird/include in the command line. Check makefile.log
132       created by Makefile.PL for the actual errors reported when it tries to
133       use the library.
134
135   Compile error
136       There are various reasons why a compilation may fail. The best would be
137       to copy the output together with outputs of env and perl -V and send
138       these into the Prima mailing list.
139
140   Prima doesn't run
141       Again, there are reasons for Prima to fail during the start.
142
143       First, check whether all main files are installed correctly. Prima.pm
144       must be in your perl directory, and Prima library file ( Prima.a or
145       Prima.so for unix, Prima.dll for win32 ) is copied in the correct
146       location in the perl tree.
147
148       Second, try to run 'perl -MPrima -e 1' . If Prima.pm is not found, the
149       error message would something like
150
151         Can't locate Prima.pm in @INC
152
153       If Prima library or one of the libraries it depends on cannot be found,
154       perl Dynaloader would complain. On win32 this usually happen when some
155       dll files Prima needs are not found. If this is the case, try to copy
156       these files into your PATH, for example in C:/WINNT .
157
158   Prima doesn't get installed using ppm (ActiveState)
159       Prima uses a non-conventional build process, which is not picked up by
160       automated ActiveState ppm builder. So if you run "ppm install Prima"
161       and it succeeds but installs nothing, try this:
162
163         ppm install --force http://cpan.uwinnipeg.ca/PPMPackages/10xx/Prima.ppd
164
165       (Justin Allegakoen and Randy Kobes:thanks!)
166
167   Prima error: Can't open display
168       This error happens when you've compiled Prima for X11, and no
169       connection to X11 display can be established. Check your DISPLAY
170       environment variable, or use --display parameter when running Prima. If
171       you do not want Prima to connect to the display, for example, to use it
172       inside of a CGI script, either use --no-x11 parameter or include "use
173       Prima::noX11" statement in your program.
174
175   X11: my fonts are bad!
176       Check whether you have Xft and fontconfig installed. Prima benefits
177       greatly from having been compiled with Xft/fontconfig. Read more in
178       Prima::X11 .
179
180   Where are the docs installed?
181       Prima documentation comes in .pm and .pod files. These, when installed,
182       are copied under perl tree, and under man tree in unix. So, 'perldoc
183       Prima' should be sufficient to invoke the main page of the Prima
184       documentation. Other pages can be invoked as 'perldoc Prima::Buttons',
185       say, or, for the graphical pod reader, 'podview Prima::Buttons'.
186       podview is the Prima doc viewer, which is also capable of displaying
187       any POD page.
188
189       There is also a pdf file on the Prima web site www.prima.eu.org, which
190       contains the same set of documentation but composed as a single book.
191       Its sources are in utils/makedoc directory, somewhat rudimentary and
192       require an installation of latex and dvips to produce one of tex, dvi,
193       ps, or pdf targets.
194
195   I've found a bug!
196       Send the bug report into the mailing list or to CPAN RT.
197

PROGRAMMING

199   How can I use .fm files of the Visual Builder inside my program?
200       podview Prima::VB::VBLoader
201
202   I want to use Prima inside CGI for loading and converting images only,
203       without X11 display.
204          use Prima::noX11; # this prevents Prima from connecting to X11 display
205          use Prima;
206          my $i = Prima::Image-> load( ... )
207
208       Note that drawing on images will be severly limited - only pixel and
209       put_image methods would work.
210
211   How would I change several properties with a single call?
212          $widget-> set(
213             property1 => $value1,
214             property2 => $value2,
215             ...
216          );
217
218   I want Prima::Edit to have feature XXX
219       If the feature is not governed by none of the "Prima::Edit" properties,
220       you've to overload "::on_paint". It is not that hard as you might
221       think.
222
223       If the feature is generic enough, you can send a patch in the list.
224
225   Tk ( Wx, Qt, whatever ) has a feature Prima doesn't.
226       Well, I'd probably love to see the feature in Prima as well, but I
227       don't have a time to write it myself. Send in a patch, and I promise
228       I'll check it out.
229
230   I wrote a program and it looks ugly with another font size
231       This would most certainly happen when you rely on your own screen
232       properties.  There are several ways to avoid this problem.
233
234       First, if one programs a window where there are many widgets
235       independent of each other size, one actually can supply coordinates for
236       these widgets as they are positioned on a screen. Don't forget to set
237       "designScale" property of the parent window, which contains dimensions
238       of the font used to design the window. One can get these by executing
239
240           perl -MPrima -MPrima::Application -le '$_=$::application->font; print $_->width, q( ), $_->height';
241
242       This way, the window and the widgets would get resized automatically
243       under another font.
244
245       Second, in case the widget layout is not that independent, one can
246       position the widgets relatively to each other by explicitly calculating
247       widget extension. For example, an "InputLine" would have height
248       relative to the font, and to have a widget placed exactly say 2 pixels
249       above the input line, code something like
250
251           my $input = $owner-> insert( InputLine, ... );
252           my $widget = $owner-> insert( Widget, bottom => $input-> top + 2 );
253
254       Of course one can change the font as well, but it is a bad idea since
255       users would get annoyed by this.
256
257       Third, one can use geometry managers, similar to the ones in Tk. See
258       Prima::Widget::pack and Prima::Widget::place.
259
260       Finally, check the widget layouts with Prima::Stress written
261       specifically for this purpose:
262
263           perl -MPrima::Stress myprogram
264
265   How would I write a widget class myself?
266       There are lots and lots of examples of this. Find a widget class
267       similar to what you are about to write, and follow the idea. There are,
268       though, some non-evident moments worth to enumerate.
269
270       ·   Test your widget class with different default settings, such as
271           colors, fonts, parent sizes, widget properties such as buffered and
272           visible.
273
274       ·   Try to avoid special properties for "create", where for example a
275           particular property must always be supplied, or never supplied, or
276           a particular combination of properties is expected. See if the DWIM
277           principle can be applied instead.
278
279       ·   Do not be afraid to define and re-define notification types. These
280           have large number of options, to be programmed once and then used
281           as a DWIM helper. Consider for which notifications user callback
282           routines ( onXxxx ) would be best to be called first, or last,
283           whether a notification should be of multiple or single callback
284           type.
285
286           If there is a functionality better off performed by the user-level
287           code, consider creating an individual notification for this
288           purpose.
289
290       ·   Repaint only the changed areas, not the whole widget.
291
292           If your widget has scrollable areas, use "scroll" method.
293
294           Inside "on_paint" check whether the whole or only a part of the
295           widget is about to be repainted. Simple optimizations here increase
296           the speed.
297
298           Avoid using pre-cooked data in "on_paint", such as when for example
299           only a particular part of a widget was invalidated, and this fact
300           is stored in an internal variable. This is because when the actual
301           "on_paint" call is executed, the invalid area may be larger than
302           was invalidated by the class actions. If you must though, compare
303           values of "clipRect" property to see whether the invalid area is
304           indeed the same as it is expected.
305
306           Remember, that inside on_paint all coordinates are inclusive-
307           inclusive, and outside inclusive-exclusive.
308
309           Note, that "buffered" property does not guarantee that the widget
310           output would be actually buffered.
311
312       ·   Write some documentation and example of use.
313
314   How would I add my widget class to the VB palette?
315       Check Prima/VB/examples/Widgety.pm . This file, if loaded through 'Add
316       widget' command in VB, adds example widget class and example VB
317       property into the VB palette and Object Inspector.
318
319   How would I use unicode/UTF8 in Prima?
320       Basically,
321
322          $::application-> wantUnicodeInput(1)
323
324       is enough to tell Prima to provide input in Unicode/UTF8. Note, that if
325       the data received in that fashion are to be put through file I/O, the
326       'utf8' IO layer must be selected ( see open ).
327
328       Prima can input and output UTF8 text if the underlying system
329       capabilities support that ( check Prima::Application::get_system_value,
330       "sv::CanUTF8_Input" and "sv::CanUTF8_Output" ).  Displaying UTF8 text
331       is unproblematic, because Perl scalars can be unambiguously told
332       whether the text they contain is in UTF8 or not. The text that comes
333       from the user input - keyboard and clipboard - can be treated and
334       reported to Prima either as UTF8 or plain text, depending on
335       "Prima::Application::wantUnicodeInput" property.
336
337       The keyboard input is also easy, because a character key event comes
338       with the character code, not the character itself, and conversion
339       between these is done via standard perl's "chr" and "ord".  The
340       clipboard input is more complicated, because the clipboard may contain
341       both UTF8 and plain text data at once, and it must be decided by the
342       programmer explicitly which one is desired.  See more in "Unicode" in
343       Prima::Clipboard.
344
345   Is there a way to display POD text that comes with my program / package ?
346          $::application-> open_help( "file://$0" );
347          $::application-> open_help( 'My::Package/BUGS' );
348
349   How to implement parallel processing?
350       Prima doesn't work if called from more than one thread, since Perl
351       scalars cannot be shared between threads automatically, but only if
352       explicitly told, by using thread::shared. Prima does work in
353       multithread environments though, but only given it runs within a
354       dedicated thread. It is important not to call Prima methods from any
355       other thread, because scalars that may be created inside these calls
356       will be unavailable to the Prima core, which would result in strange
357       errors.
358
359       It is possible to run things in parallel by calling the event
360       processing by hands: instead of entering the main loop with
361
362          run Prima;
363
364       one can write
365
366          while ( 1) {
367             ... do some calculations ..
368             $::application->yield;
369          }
370
371       That'll give Prima a chance to handle accumulated events, but that
372       technique is only viable if calculations can be quantized into
373       relatively short time frames.
374
375       The generic solution would be harder to implement and debug, but it
376       scales well. The idea is to fork a process, and communicate with it via
377       its stdin and/or stdout ( see perlipc how to do that), and use
378       Prima::File to asyncronously read data passed through a pipe or a
379       socket.
380
381       Note: Win32 runtime library does not support asynchronous pipes, only
382       asyncronous sockets.  Cygwin does support both asyncronous pipes and
383       sockets.
384
385   How do I use Prima with AnyEvent ?
386       Prima works well with AnyEvent but there are some minor differences in
387       using Prima. AnyEvent is a generic event processing library that
388       supports various underlying event loop implementations such as EV,
389       Event, POE etc.  Prima internally uses its own event loop to perform
390       its event handling and AnyEvent can support that by automatically
391       selecting POE to be the internal implementation when Prima is loaded.
392       However, you may use AnyEvent with any other internal event loop
393       implementation such as EV along with Prima with varying results
394       depending on the event library used. There are a few points to note:
395
396       ·   Prima has to be loaded before AnyEvent.
397
398       ·   If you want to use Prima's internal event loop system you have to
399           install POE::Loop::Prima and include it in your code before Prima
400           is loaded like below:
401                   use POE 'Loop::Prima';
402                   use Prima qw/Application/;
403                   use AnyEvent;
404
405       ·   You can call "AnyEvent::detect" to check if the implementation is
406           'AnyEvent::Impl::POE' if you want to use Prima's event loop or it
407           should be the event loop implementation you expect such as
408           'AnyEvent::Impl::EV';
409
410       ·   If you use POE::Loop::Prima then you can continue to call "run
411           Prima" and should not call AnyEvent's condition variable "recv"
412           function.
413
414       ·   If you want to use another event library implementation of
415           AnyEvent, you have to not call "run Prima" but instead call
416           AnyEvent's condition variable "recv" function.
417
418       ·   You have to use "$::application->yield" in an "AnyEvent->timer"
419           object to allow for the Prima UI to update periodically, if you're
420           not using POE::Loop::Prima.
421
422       See full example in examples/socket_anyevent.pl and
423       examples/socket_anyevent_poe.pl.
424
425   How do I post an asynchronous message?
426       "Prima::Component::post_message" method posts a message through the
427       system event dispatcher and returns immediately; when the message is
428       arrived, "onPostMessage" notification is triggered:
429
430          use Prima qw(Application);
431          my $w = Prima::MainWindow-> create( onPostMessage => sub { shift; print "@_\n" });
432          $w-> post_message(1,2);
433          print "3 4 ";
434          run Prima;
435
436          output: 3 4 1 2
437
438       This technique is fine when all calls to the "post_message" on the
439       object are controlled.  To multiplex callbacks one can use one of the
440       two scalars passed to "post_message" as callback identification. This
441       is done by "post" in Prima::Utils, that internally intercepts
442       $::application's "PostMessage" and provides the procedural interface to
443       the same function:
444
445          use Prima qw(Application);
446          use Prima::Utils qw(post);
447
448          post( sub { print "@_\n" }, 'a');
449          print "b";
450          run Prima;
451
452          output: ba
453
454   Now to address widgets inside TabbedNotebook / TabbedScrollNotebook ?
455       The tabbed notebooks work as parent widgets for "Prima::Notebook", that
456       doesn't have any interface elements on its own, and provides only page
457       flipping function. The sub-widgets, therefore, are to be addressed as
458       "$TabbedNotebook-> Notebook-> MyButton".
459
460   How to compile a Prima-based module using XS?
461       Take a look at Prima::IPA, Prima::OpenGL, Prima::Image::Magick,
462       PDL::PrimaImage, and PDL::Drawing::Prima . These modules compile
463       against Prima dynamic module, start from there. Note - it's important
464       to include PRIMA_VERSION_BOOTCHECK in the "BOOT:" section, to avoid
465       binary incompatibilites, if there should be any.
466
467   How do I generate Prima executables with PAR?
468       You'll need some files that PAR cannot detect automatically. During the
469       compilation phase Makefile.PL creates utils/par.txt file that contains
470       these files. Include them with this command:
471
472          pp -A utils/par.txt -o a.out my_program
473

AUTHOR

475       Dmitry Karasik, <dmitry@karasik.eu.org>.
476

SEE ALSO

478       Prima
479
480
481
482perl v5.30.1                      2020-01-30                pod::Prima::faq(3)
Impressum