1pod::Prima::faq(3) User Contributed Perl Documentation pod::Prima::faq(3)
2
6 Prima::faq - Frequently asked questions about Prima
7
9 The FAQ covers various topics around Prima, such as distribution,
10 compilation, installation, and programming.
11
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 Yeah, right. So what is Prima again?
20 Ok. A Yet Another Perl GUI.
21 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 Interestingly enough, Prima still builds for OS/2 (as of July 2012),
29 but its support was killed because no one needs it anyway.
30 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 But I want to use Prima in another language.
37 Unless your language has runtime binding with perl, you cannot.
38 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 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 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
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 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 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 To install, unpack the archive and type 'perl ms_install.pl'. The
76 files will be copied into the perl tree.
77 How to compile Prima from source?
79 Type the following:
80 perl Makefile.PL
82 make
83 make install
84 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 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 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 On every supported platform Prima can make use of the following graphic
102 libraries:
103 libXpm - Xpm pixmaps
105 libjpeg - JPEG images
106 libgif - GIF images
107 libpng - PNG images
108 libtiff - tiff images
109 libwebp,libwebpdemux,libwebpmux - WebP images
110 Strawberry perl and Cygwin come with most of them, so on these
112 installations Prima just compiles without any trouble. For other perl
113 builds, use one of "Prima::codecs::" modules that contains the needed
114 include and lib files. If you're installing Prima through CPAN, that
115 gets done automatically.
116 img/codec_XXX.c compile error
118 "img/codec_XXX.c" files are C sources for support of the graphic
119 libraries. In case a particular codec does not compile, the ultimate
120 fix is to remove the file and re-run Makefile.PL . This way, the
121 problem can be avoided easily, although at cost of a lacking support
122 for a graphic format.
123 How'd I check what libraries are compiled in?
125 perl -MPrima -e 'print map { $_->{name}.qq(\n) } @{Prima::Image->codecs};'
126 I have a graphic library installed, but Makefile.PL doesn't find it
128 The library is probably located in a weird directory so Makefile.PL
129 must be told to use it by adding LIBPATH+=/some/weird/lib, and possibly
130 INCPATH+=/some/weird/include in the command line. Check makefile.log
131 created by Makefile.PL for the actual errors reported when it tries to
132 use the library.
133 Compile error
135 There are various reasons why a compilation may fail. The best would be
136 to copy the output together with outputs of env and perl -V and send
137 these to the author or better open a github issue here
138 <https://github.com/dk/Prima/issues>.
139 Prima doesn't run
141 Again, there are reasons for Prima to fail during the start.
142 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 Second, try to run 'perl -MPrima -e 1' . If Prima.pm is not found, the
149 error message would be something like
150 Can't locate Prima.pm in @INC
152 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:/Windows .
157 Prima doesn't get installed using ppm (ActiveState)
159 Prima uses a non-conventional build process, which is not picked up by
160 the automated ActiveState ppm builder. So if you run "ppm install
161 Prima" and it succeeds but installs nothing, try this:
162 ppm install --force http://cpan.uwinnipeg.ca/PPMPackages/10xx/Prima.ppd
164 (Justin Allegakoen and Randy Kobes:thanks!)
166 Alternatively you could try to install a compiler with "ppm install
168 MinGW" and then build Prima yourself.
169 Prima error: Can't open display
171 This error happens when you've compiled Prima for X11, and no
172 connection to X11 display can be established. Check your DISPLAY
173 environment variable, or use --display parameter when running Prima. If
174 you do not want Prima to connect to the display, for example, to use it
175 inside of a CGI script, either use --no-x11 parameter or include "use
176 Prima::noX11" statement in your program.
177 X11: my fonts are bad!
179 Check whether you have Xft and fontconfig installed. Prima benefits
180 greatly from having been compiled with Xft/fontconfig. Read more in
181 Prima::X11 .
182 Where are the docs installed?
184 Prima documentation comes in .pm and .pod files. These, when installed,
185 are copied under perl tree, and under man tree in unix. So, 'perldoc
186 Prima' should be sufficient to invoke the main page of the Prima
187 documentation. Other pages can be invoked as 'perldoc Prima::Buttons',
188 say, or, for the graphical pod reader, 'podview Prima::Buttons'.
189 podview is the Prima doc viewer, which is also capable of displaying
190 any POD page.
191 There is also a pdf file on the Prima web site www.prima.eu.org, which
193 contains the same set of documentation but composed as a single book.
194 Its sources are in utils/makedoc directory, somewhat rudimentary and
195 require an installation of latex and dvips to produce one of tex, dvi,
196 ps, or pdf targets.
197 Screen grabbing doesn't work on MacOSX.
199 It does if you 1) compile Prima with cocoa 2) allow the application
200 (XQuartz and probably terminal) to access the screen. To do the latter,
201 Choose Apple menu, System Preferences, click Security & Privacy, then
202 click Privacy. Click on an icon on the left lower corner to allow
203 changes. Then, in the screen recording tab, add XQuartz to the list of
204 allowed applications. Note that it might not work if you run your
205 application from a (remote) ssh session - I couldn't find how to a how
206 to enable screen grabbing for sshd.
207 I've found a bug!
209 <https://github.com/dk/Prima/issues> is the place.
210
212 How can I use .fm files of the Visual Builder inside my program?
213 podview Prima::VB::VBLoader
214 I want to use Prima inside CGI for loading and converting images only,
216 without X11 display.
217 use Prima::noX11; # this prevents Prima from connecting to X11 display
218 use Prima;
219 my $i = Prima::Image-> load( ... )
220 Note that drawing on images will be somewhat limited.
222 How would I change several properties with a single call?
224 $widget-> set(
225 property1 => $value1,
226 property2 => $value2,
227 ...
228 );
229 I want Prima::Edit to have feature XXX
231 If the feature is not governed by none of the "Prima::Edit" properties,
232 you need to overload "::on_paint". It is not that hard as you might
233 think.
234 If the feature is generic enough, you can send a patch in the list.
236 Tk ( Wx, Qt, whatever ) has a feature Prima doesn't.
238 Well, I'd probably love to see the feature in Prima as well, but I
239 don't have a time to write it myself. Send in a patch, and I promise
240 I'll check it out.
241 I wrote a program and it looks ugly with another font size
243 This would most certainly happen when you rely on your own screen
244 properties. There are several ways to avoid this problem.
245 First, if one programs a window where there are many widgets
247 independent of each other size, one actually can supply coordinates for
248 these widgets as they are positioned on a screen. Don't forget to set
249 "designScale" property of the parent window, which contains dimensions
250 of the font used to design the window. One can get these by executing
251 perl -MPrima -MPrima::Application -le '$_=$::application->font; print $_->width, q( ), $_->height';
253 This way, the window and the widgets would get resized automatically
255 under another font.
256 Second, in case the widget layout is not that independent, one can
258 position the widgets relatively to each other by explicitly calculating
259 widget extension. For example, an "InputLine" would have height
260 relative to the font, and to have a widget placed exactly say 2 pixels
261 above the input line, code something like
262 my $input = $owner-> insert( InputLine, ... );
264 my $widget = $owner-> insert( Widget, bottom => $input-> top + 2 );
265 Of course one can change the font as well, but it is a bad idea since
267 users would get annoyed by this.
268 Third, one can use geometry managers, similar to the ones in Tk. See
270 Prima::Widget::pack and Prima::Widget::place.
271 Finally, check the widget layouts with Prima::Stress written
273 specifically for this purpose:
274 perl -MPrima::Stress myprogram
276 How would I write a widget class myself?
278 There are lots and lots of examples of this. Find a widget class
279 similar to what you are about to write, and follow the idea. There are,
280 though, some non-evident moments worth to enumerate.
281 • Test your widget class with different default settings, such as
283 colors, fonts, parent sizes, widget properties such as buffered and
284 visible.
285 • Try to avoid special properties for "create", where for example a
287 particular property must always be supplied, or never supplied, or
288 a particular combination of properties is expected. See if the DWIM
289 principle can be applied instead.
290 • Do not be afraid to define and re-define notification types. These
292 have large number of options, to be programmed once and then used
293 as a DWIM helper. Consider for which notifications user callback
294 routines ( onXxxx ) would be best to be called first, or last,
295 whether a notification should be of multiple or single callback
296 type.
297 If there is a functionality better off performed by the user-level
299 code, consider creating an individual notification for this
300 purpose.
301 • Repaint only the changed areas, not the whole widget.
303 If your widget has scrollable areas, use "scroll" method.
305 Inside "on_paint" check whether the whole or only a part of the
307 widget is about to be repainted. Simple optimizations here increase
308 the speed.
309 Avoid using pre-cooked data in "on_paint", such as when for example
311 only a particular part of a widget was invalidated, and this fact
312 is stored in an internal variable. This is because when the actual
313 "on_paint" call is executed, the invalid area may be larger than
314 was invalidated by the class actions. If you must though, compare
315 values of "clipRect" property to see whether the invalid area is
316 indeed the same as it is expected.
317 Remember, that inside on_paint all coordinates are inclusive-
319 inclusive, while the widget coordinates generally are inclusive-
320 exclusive.
321 Note, that "buffered" property does not guarantee that the widget
323 output would be actually buffered. Same goes with "antialias" and
324 "layered"; these functions are opportunistic.
325 • Write some documentation and example of use.
327 How would I add my widget class to the VB palette?
329 Check Prima/VB/examples/Widgety.pm . This file, if loaded through 'Add
330 widget' command in VB, adds example widget class and example VB
331 property into the VB palette and Object Inspector.
332 How would I use unicode/UTF8 in Prima?
334 Prima by default is unicode-aware, in some areas more than the Perl (as
335 of 5.32) itself.
336 For example on win32 Perl has big difficulties with files with unicode
338 characters, and this is recommended to mitigate using Prima::sys::FS,
339 which overrides "open", "opendir" and the like builtin functions with
340 their unicode-friendly versions. It doesn't though overload "-f","-e"
341 syntax, so use "_f","_e" etc instead.
342 Displaying UTF8 text is unproblematic, because Perl scalars can be
344 unambiguously told whether the text they contain is in UTF8 or not. The
345 text that comes from the user input, i e keyboard and clipboard, can be
346 treated and reported to Prima either as UTF8 r plain text, depending on
347 "Prima::Application::wantUnicodeInput" property, which is set to 1 by
348 default. Remember though that if data are to be put through file I/O,
349 the 'utf8' IO layer must be selected ( see open ).
350 The keyboard input is also easy, because a character key event comes
352 with the character code, not the character itself, and conversion
353 between these is done via standard perl's "chr" and "ord".
354 The clipboard input is more complicated, because the clipboard may
356 contain both UTF8 and plain text data at once, and it must be decided
357 by the programmer explicitly which one is desired. See more in
358 "Unicode" in Prima::Clipboard.
359 Is there a way to display POD text that comes with my program / package ?
361 $::application-> open_help( "file://$0" );
362 $::application-> open_help( "file://$0|DESCRIPTION" );
363 $::application-> open_help( 'My::Package/BUGS' );
364 How to implement parallel processing?
366 Prima doesn't work if called from more than one thread, since Perl
367 scalars cannot be shared between threads automatically, but only if
368 explicitly told, by using thread::shared. Prima does work in
369 multithread environments though, but only given it runs within a
370 dedicated thread. It is important not to call Prima methods from any
371 other thread, because scalars that may be created inside these calls
372 will be unavailable to the Prima core, which would result in strange
373 errors.
374 It is possible to run things in parallel by calling the event
376 processing by hands: instead of entering the main loop with
377 run Prima;
379 one can write
381 while ( $::application-> yield) {
383 ... do some calculations ..
384 }
385 That'll give Prima a chance to handle accumulated events, but that
387 technique is only viable if calculations can be quantized into
388 relatively short time frames.
389 The generic solution would be harder to implement and debug, but it
391 scales well. The idea is to fork a process, and communicate with it via
392 its stdin and/or stdout ( see perlipc how to do that), and use
393 Prima::File to asynchronously read data passed through a pipe or a
394 socket.
395 Note: Win32 runtime library does not support asynchronous pipes, only
397 asynchronous sockets. Cygwin does support both asynchronous pipes and
398 sockets.
399 How do I use Prima with AnyEvent or POE ?
401 • Prima::sys::AnyEvent can be used to organize event loops driven by
402 Prima with AnyEvent support:
403 use Prima qw(sys::AnyEvent);
405 use AnyEvent;
406 my $ev = AnyEvent->timer(after => 1, cb => sub { print "waited 1 second!\n" });
408 run Prima;
409 this is the preferred, but not the only solution.
411 • If you need AnyEvent to drive the event loop, you can fire up the
413 Prima yield() call once in a while:
414 my $timer = AnyEvent->timer(after => 0, interval => 1/20, cb => sub {
416 $::application->yield;
417 });
418 • If you want to use Prima's internal event loop system you have to
420 install POE::Loop::Prima and include it in your code before Prima
421 is loaded like below:
422 use POE 'Loop::Prima';
423 use Prima qw/Application/;
424 use AnyEvent;
425 You can call "AnyEvent::detect" to check if the implementation is
427 'AnyEvent::Impl::POE' if you want to use Prima's event loop or it
428 should be the event loop implementation you expect such as
429 'AnyEvent::Impl::EV';
430 If you use POE::Loop::Prima then you can continue to call "run
432 Prima" and should not call AnyEvent's condition variable "recv"
433 function.
434 • If you want to use another event library implementation of
436 AnyEvent, you have to not call "run Prima" but instead call
437 AnyEvent's condition variable "recv" function.
438 See full examples in examples/socket_anyevent1.pl,
440 examples/socket_anyevent2.pl, and examples/socket_anyevent_poe.pl.
441 How do I post an asynchronous message?
443 "Prima::Component::post_message" method posts a message through the
444 system event dispatcher and returns immediately; when the message is
445 arrived, "onPostMessage" notification is triggered:
446 use Prima qw(Application);
448 my $w = Prima::MainWindow-> create( onPostMessage => sub { shift; print "@_\n" });
449 $w-> post_message(1,2);
450 print "3 4 ";
451 run Prima;
452 output: 3 4 1 2
454 This technique is fine when all calls to the "post_message" on the
456 object are controlled. To multiplex callbacks one can use one of the
457 two scalars passed to "post_message" as callback identification. This
458 is done by "post" in Prima::Utils, that internally intercepts
459 $::application's "PostMessage" and provides the procedural interface to
460 the same function:
461 use Prima qw(Application);
463 use Prima::Utils qw(post);
464 post( sub { print "@_\n" }, 'a');
466 print "b";
467 run Prima;
468 output: ba
470 Now to address widgets inside TabbedNotebook / TabbedScrollNotebook ?
472 The tabbed notebooks work as parent widgets for "Prima::Notebook", that
473 doesn't have any interface elements on its own, and provides only page
474 flipping function. The sub-widgets, therefore, are to be addressed as
475 "$TabbedNotebook-> Notebook-> MyButton".
476 How to compile a Prima-based module using XS?
478 Take a look at Prima::IPA, Prima::OpenGL, Prima::Image::Magick,
479 PDL::PrimaImage, and PDL::Drawing::Prima . These modules compile
480 against Prima dynamic module, start from there. Note - it's important
481 to include PRIMA_VERSION_BOOTCHECK in the "BOOT:" section, to avoid
482 binary incompatibilities, if there should be any.
483 How do I generate Prima executables with PAR?
485 You'll need some files that PAR cannot detect automatically. During the
486 compilation phase Makefile.PL creates utils/par.txt file that contains
487 these files. Include them with this command:
488 pp -A utils/par.txt -o a.out my_program
490
492 Dmitry Karasik, <dmitry@karasik.eu.org>.
493
495 Prima
496perl v5.38.0 2023-07-21 pod::Prima::faq(3)