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 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 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 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 How'd I check what libraries are compiled in?
126 perl -MPrima -e 'print map { $_->{name}.qq(\n) } @{Prima::Image->codecs};'
127 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 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 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 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:/WINNT .
157 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 ppm install --force http://cpan.uwinnipeg.ca/PPMPackages/10xx/Prima.ppd
164 (Justin Allegakoen and Randy Kobes:thanks!)
166 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 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 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 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 I've found a bug!
196 Send the bug report into the mailing list or to CPAN RT.
197
199 How can I use .fm files of the Visual Builder inside my program?
200 podview Prima::VB::VBLoader
201 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 Note that drawing on images will be severly limited - only pixel and
209 put_image methods would work.
210 How would I change several properties with a single call?
212 $widget-> set(
213 property1 => $value1,
214 property2 => $value2,
215 ...
216 );
217 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 If the feature is generic enough, you can send a patch in the list.
224 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 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 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 perl -MPrima -MPrima::Application -le '$_=$::application->font; print $_->width, q( ), $_->height';
241 This way, the window and the widgets would get resized automatically
243 under another font.
244 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 my $input = $owner-> insert( InputLine, ... );
252 my $widget = $owner-> insert( Widget, bottom => $input-> top + 2 );
253 Of course one can change the font as well, but it is a bad idea since
255 users would get annoyed by this.
256 Third, one can use geometry managers, similar to the ones in Tk. See
258 Prima::Widget::pack and Prima::Widget::place.
259 Finally, check the widget layouts with Prima::Stress written
261 specifically for this purpose:
262 perl -MPrima::Stress myprogram
264 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 · Test your widget class with different default settings, such as
271 colors, fonts, parent sizes, widget properties such as buffered and
272 visible.
273 · 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 · 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 If there is a functionality better off performed by the user-level
287 code, consider creating an individual notification for this
288 purpose.
289 · Repaint only the changed areas, not the whole widget.
291 If your widget has scrollable areas, use "scroll" method.
293 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 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 Remember, that inside on_paint all coordinates are inclusive-
307 inclusive, and outside inclusive-exclusive.
308 Note, that "buffered" property does not guarantee that the widget
310 output would be actually buffered.
311 · Write some documentation and example of use.
313 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 How would I use unicode/UTF8 in Prima?
320 Basically,
321 $::application-> wantUnicodeInput(1)
323 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 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 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 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 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 It is possible to run things in parallel by calling the event
360 processing by hands: instead of entering the main loop with
361 run Prima;
363 one can write
365 while ( 1) {
367 ... do some calculations ..
368 $::application->yield;
369 }
370 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 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 Note: Win32 runtime library does not support asynchronous pipes, only
382 asyncronous sockets. Cygwin does support both asyncronous pipes and
383 sockets.
384 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 · Prima has to be loaded before AnyEvent.
397 · 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 · 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 · 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 · 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 · 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 See full example in examples/socket_anyevent.pl and
423 examples/socket_anyevent_poe.pl.
424 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 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 output: 3 4 1 2
437 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 use Prima qw(Application);
446 use Prima::Utils qw(post);
447 post( sub { print "@_\n" }, 'a');
449 print "b";
450 run Prima;
451 output: ba
453 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 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 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 pp -A utils/par.txt -o a.out my_program
473
475 Dmitry Karasik, <dmitry@karasik.eu.org>.
476
478 Prima
479perl v5.30.0 2019-08-21 pod::Prima::faq(3)