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