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 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 into the Prima mailing list.
138 Prima doesn't run
140 Again, there are reasons for Prima to fail during the start.
141 First, check whether all main files are installed correctly. Prima.pm
143 must be in your perl directory, and Prima library file ( Prima.a or
144 Prima.so for unix, Prima.dll for win32 ) is copied in the correct
145 location in the perl tree.
146 Second, try to run 'perl -MPrima -e 1' . If Prima.pm is not found, the
148 error message would something like
149 Can't locate Prima.pm in @INC
151 If Prima library or one of the libraries it depends on cannot be found,
153 perl Dynaloader would complain. On win32 this usually happen when some
154 dll files Prima needs are not found. If this is the case, try to copy
155 these files into your PATH, for example in C:/WINNT .
156 Prima doesn't get installed using ppm (ActiveState)
158 Prima uses a non-conventional build process, which is not picked up by
159 automated ActiveState ppm builder. So if you run "ppm install Prima"
160 and it succeeds but installs nothing, try this:
161 ppm install --force http://cpan.uwinnipeg.ca/PPMPackages/10xx/Prima.ppd
163 (Justin Allegakoen and Randy Kobes:thanks!)
165 Prima error: Can't open display
167 This error happens when you've compiled Prima for X11, and no
168 connection to X11 display can be established. Check your DISPLAY
169 environment variable, or use --display parameter when running Prima. If
170 you do not want Prima to connect to the display, for example, to use it
171 inside of a CGI script, either use --no-x11 parameter or include "use
172 Prima::noX11" statement in your program.
173 X11: my fonts are bad!
175 Check whether you have Xft and fontconfig installed. Prima benefits
176 greatly from having been compiled with Xft/fontconfig. Read more in
177 Prima::X11 .
178 Where are the docs installed?
180 Prima documentation comes in .pm and .pod files. These, when installed,
181 are copied under perl tree, and under man tree in unix. So, 'perldoc
182 Prima' should be sufficient to invoke the main page of the Prima
183 documentation. Other pages can be invoked as 'perldoc Prima::Buttons',
184 say, or, for the graphical pod reader, 'podview Prima::Buttons'.
185 podview is the Prima doc viewer, which is also capable of displaying
186 any POD page.
187 There is also a pdf file on the Prima web site www.prima.eu.org, which
189 contains the same set of documentation but composed as a single book.
190 Its sources are in utils/makedoc directory, somewhat rudimentary and
191 require an installation of latex and dvips to produce one of tex, dvi,
192 ps, or pdf targets.
193 I've found a bug!
195 Send the bug report into the mailing list or to CPAN RT.
196
198 How can I use .fm files of the Visual Builder inside my program?
199 podview Prima::VB::VBLoader
200 I want to use Prima inside CGI for loading and converting images only,
202 without X11 display.
203 use Prima::noX11; # this prevents Prima from connecting to X11 display
204 use Prima;
205 my $i = Prima::Image-> load( ... )
206 Note that drawing on images will be severly limited - only pixel and
208 put_image methods would work.
209 How would I change several properties with a single call?
211 $widget-> set(
212 property1 => $value1,
213 property2 => $value2,
214 ...
215 );
216 I want Prima::Edit to have feature XXX
218 If the feature is not governed by none of the "Prima::Edit" properties,
219 you've to overload "::on_paint". It is not that hard as you might
220 think.
221 If the feature is generic enough, you can send a patch in the list.
223 Tk ( Wx, Qt, whatever ) has a feature Prima doesn't.
225 Well, I'd probably love to see the feature in Prima as well, but I
226 don't have a time to write it myself. Send in a patch, and I promise
227 I'll check it out.
228 I wrote a program and it looks ugly with another font size
230 This would most certainly happen when you rely on your own screen
231 properties. There are several ways to avoid this problem.
232 First, if one programs a window where there are many widgets
234 independent of each other size, one actually can supply coordinates for
235 these widgets as they are positioned on a screen. Don't forget to set
236 "designScale" property of the parent window, which contains dimensions
237 of the font used to design the window. One can get these by executing
238 perl -MPrima -MPrima::Application -le '$_=$::application->font; print $_->width, q( ), $_->height';
240 This way, the window and the widgets would get resized automatically
242 under another font.
243 Second, in case the widget layout is not that independent, one can
245 position the widgets relatively to each other by explicitly calculating
246 widget extension. For example, an "InputLine" would have height
247 relative to the font, and to have a widget placed exactly say 2 pixels
248 above the input line, code something like
249 my $input = $owner-> insert( InputLine, ... );
251 my $widget = $owner-> insert( Widget, bottom => $input-> top + 2 );
252 Of course one can change the font as well, but it is a bad idea since
254 users would get annoyed by this.
255 Third, one can use geometry managers, similar to the ones in Tk. See
257 Prima::Widget::pack and Prima::Widget::place.
258 Finally, check the widget layouts with Prima::Stress written
260 specifically for this purpose:
261 perl -MPrima::Stress myprogram
263 How would I write a widget class myself?
265 There are lots and lots of examples of this. Find a widget class
266 similar to what you are about to write, and follow the idea. There are,
267 though, some non-evident moments worth to enumerate.
268 · Test your widget class with different default settings, such as
270 colors, fonts, parent sizes, widget properties such as buffered and
271 visible.
272 · Try to avoid special properties for "create", where for example a
274 particular property must always be supplied, or never supplied, or
275 a particular combination of properties is expected. See if the DWIM
276 principle can be applied instead.
277 · Do not be afraid to define and re-define notification types. These
279 have large number of options, to be programmed once and then used
280 as a DWIM helper. Consider for which notifications user callback
281 routines ( onXxxx ) would be best to be called first, or last,
282 whether a notification should be of multiple or single callback
283 type.
284 If there is a functionality better off performed by the user-level
286 code, consider creating an individual notification for this
287 purpose.
288 · Repaint only the changed areas, not the whole widget.
290 If your widget has scrollable areas, use "scroll" method.
292 Inside "on_paint" check whether the whole or only a part of the
294 widget is about to be repainted. Simple optimizations here increase
295 the speed.
296 Avoid using pre-cooked data in "on_paint", such as when for example
298 only a particular part of a widget was invalidated, and this fact
299 is stored in an internal variable. This is because when the actual
300 "on_paint" call is executed, the invalid area may be larger than
301 was invalidated by the class actions. If you must though, compare
302 values of "clipRect" property to see whether the invalid area is
303 indeed the same as it is expected.
304 Remember, that inside on_paint all coordinates are inclusive-
306 inclusive, and outside inclusive-exclusive.
307 Note, that "buffered" property does not guarantee that the widget
309 output would be actually buffered.
310 · Write some documentation and example of use.
312 How would I add my widget class to the VB palette?
314 Check Prima/VB/examples/Widgety.pm . This file, if loaded through 'Add
315 widget' command in VB, adds example widget class and example VB
316 property into the VB palette and Object Inspector.
317 How would I use unicode/UTF8 in Prima?
319 Basically,
320 $::application-> wantUnicodeInput(1)
322 is enough to tell Prima to provide input in Unicode/UTF8. Note, that if
324 the data received in that fashion are to be put through file I/O, the
325 'utf8' IO layer must be selected ( see open ).
326 Prima can input and output UTF8 text if the underlying system
328 capabilities support that ( check Prima::Application::get_system_value,
329 "sv::CanUTF8_Input" and "sv::CanUTF8_Output" ). Displaying UTF8 text
330 is unproblematic, because Perl scalars can be unambiguously told
331 whether the text they contain is in UTF8 or not. The text that comes
332 from the user input - keyboard and clipboard - can be treated and
333 reported to Prima either as UTF8 or plain text, depending on
334 "Prima::Application::wantUnicodeInput" property.
335 The keyboard input is also easy, because a character key event comes
337 with the character code, not the character itself, and conversion
338 between these is done via standard perl's "chr" and "ord". The
339 clipboard input is more complicated, because the clipboard may contain
340 both UTF8 and plain text data at once, and it must be decided by the
341 programmer explicitly which one is desired. See more in "Unicode" in
342 Prima::Clipboard.
343 Is there a way to display POD text that comes with my program / package ?
345 $::application-> open_help( $0 );
346 $::application-> open_help( 'My::Package/BUGS' );
347 How to implement parallel processing?
349 Prima doesn't work if called from more than one thread, since Perl
350 scalars cannot be shared between threads automatically, but only if
351 explicitly told, by using thread::shared. Prima does work in
352 multithread environments though, but only given it runs within a
353 dedicated thread. It is important not to call Prima methods from any
354 other thread, because scalars that may be created inside these calls
355 will be unavailable to the Prima core, which would result in strange
356 errors.
357 It is possible to run things in parallel by calling the event
359 processing by hands: instead of entering the main loop with
360 run Prima;
362 one can write
364 while ( 1) {
366 ... do some calculations ..
367 $::application->yield;
368 }
369 That'll give Prima a chance to handle accumulated events, but that
371 technique is only viable if calculations can be quantized into
372 relatively short time frames.
373 The generic solution would be harder to implement and debug, but it
375 scales well. The idea is to fork a process, and communicate with it via
376 its stdin and/or stdout ( see perlipc how to do that), and use
377 Prima::File to asyncronously read data passed through a pipe or a
378 socket.
379 Note: Win32 runtime library does not support asynchronous pipes, only
381 asyncronous sockets. Cygwin does support both asyncronous pipes and
382 sockets.
383 How do I use Prima with AnyEvent ?
385 Prima works well with AnyEvent but there are some minor differences in
386 using Prima. AnyEvent is a generic event processing library that
387 supports various underlying event loop implementations such as EV,
388 Event, POE etc. Prima internally uses its own event loop to perform
389 its event handling and AnyEvent can support that by automatically
390 selecting POE to be the internal implementation when Prima is loaded.
391 However, you may use AnyEvent with any other internal event loop
392 implementation such as EV along with Prima with varying results
393 depending on the event library used. There are a few points to note:
394 · Prima has to be loaded before AnyEvent.
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
399 is 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
410 Prima" and should not call AnyEvent's condition variable "recv"
411 function.
412 · If you want to use another event library implementation of
414 AnyEvent, you have to not call "run Prima" but instead call
415 AnyEvent's condition variable "recv" function.
416 · You have to use "$::application->yield" in an "AnyEvent->timer"
418 object to allow for the Prima UI to update periodically, if you're
419 not using POE::Loop::Prima.
420 See full example in examples/socket_anyevent.pl and
422 examples/socket_anyevent_poe.pl.
423 How do I post an asynchronous message?
425 "Prima::Component::post_message" method posts a message through the
426 system event dispatcher and returns immediately; when the message is
427 arrived, "onPostMessage" notification is triggered:
428 use Prima qw(Application);
430 my $w = Prima::MainWindow-> create( onPostMessage => sub { shift; print "@_\n" });
431 $w-> post_message(1,2);
432 print "3 4 ";
433 run Prima;
434 output: 3 4 1 2
436 This technique is fine when all calls to the "post_message" on the
438 object are controlled. To multiplex callbacks one can use one of the
439 two scalars passed to "post_message" as callback identification. This
440 is done by "post" in Prima::Utils, that internally intercepts
441 $::application's "PostMessage" and provides the procedural interface to
442 the same function:
443 use Prima qw(Application);
445 use Prima::Utils qw(post);
446 post( sub { print "@_\n" }, 'a');
448 print "b";
449 run Prima;
450 output: ba
452 Now to address widgets inside TabbedNotebook / TabbedScrollNotebook ?
454 The tabbed notebooks work as parent widgets for "Prima::Notebook", that
455 doesn't have any interface elements on its own, and provides only page
456 flipping function. The sub-widgets, therefore, are to be addressed as
457 "$TabbedNotebook-> Notebook-> MyButton".
458 How to compile a Prima-based module using XS?
460 Take a look at IPA, Prima::OpenGL, Prima::Image::Magick,
461 PDL::PrimaImage, and PDL::Drawing::Prima . These modules compile
462 against Prima dynamic module, start from there. Note - it's important
463 to include PRIMA_VERSION_BOOTCHECK in the "BOOT:" section, to avoid
464 binary incompatibilites, if there should be any.
465
467 Dmitry Karasik, <dmitry@karasik.eu.org>.
468
470 Prima
471perl v5.28.0 2017-02-28 pod::Prima::faq(3)