1=head1 NAME 2 3Prima::faq - Frequently asked questions about Prima 4 5=head1 DESCRIPTION 6 7The FAQ covers various topics around Prima, such as distribution, compilation, 8installation, and programming. 9 10=head1 COMMON 11 12=head2 What is Prima? 13 14Prima is a general purpose extensible graphical user interface toolkit with a 15rich set of standard widgets and an emphasis on 2D image processing tasks. A 16Perl program using PRIMA looks and behaves identically on X, Win32. 17 18=head2 Yeah, right. So what is Prima again? 19 20Ok. A Yet Another Perl GUI. 21 22=head2 Why bother with the Yet Another thing, while there is Perl-Tk and plenty of others? 23 24Prima was started on OS/2, where Tk didn't really run. We have had two options 25- either port Tk, or write something on our own, probably better than the 26existing tools. We believe that we've succeeded. 27 28Interestingly enough, Prima still builds for OS/2 (as of July 2012), but its support 29was killed because noone needs it anyway. 30 31=head2 Why Perl? 32 33Why not? Perl is great. The high-level GUI logic fits badly into C, C++, or the 34like, so a scripting language is probably the way to go here. 35 36=head2 But I want to use Prima in another language. 37 38Unless your language has runtime binding with perl, you cannot. 39 40=head2 Who wrote Prima? 41 42Dmitry Karasik implemented the majority of the toolkit, after the original idea 43by Anton Berezin. The latter and set of contributors helped the development of 44the toolkit since then. 45 46=head2 What is the copyright? 47 48The copyright is a modified BSD license, where only two first paragraphs remain 49out of the original four. The text of copyright is present is almost all files 50of the toolkit. 51 52=head2 I'd like to contribute. 53 54You can do this is several ways. The project would probably best benefit from 55the advocacy, because not many people use it. Of course, you can send in new 56widgets, patches, suggestions, or even donations. Also, documentation is the 57thing that needs a particular attention, since my native language is not 58English, so if there are volunteers for polishing of the Prima docs, you are 59very welcome. 60 61=head1 INSTALLATION 62 63=head2 Where can I download Prima? 64 65L<http://www.prima.eu.org> contains links to source and binary download 66resources, instructions on how to subscribe to the Prima mailing list, 67documentation, and some other useful info. 68 69=head2 What is better, source or binary? 70 71Depends where your are and what are your goals. On unix, the best is to use the 72source. On win32 the binaries probably are preferred. If you happen to 73use cygwin you probably still better off using the source. 74 75=head2 How to install binary distribution? 76 77First, check if you've downloaded Prima binary for the correct version of Perl. 78For win32 ActiveState builds, difference in the minor digits of the Perl 79version shouldn't be a problem, for example, binary distribution for Perl build 80#805 should work with Perl build #808, etc etc. 81 82To install, unpack the archive and type 'perl ms_install.pl'. The files will 83be copied into the perl tree. 84 85=head2 How to compile Prima from source? 86 87Type the following: 88 89 perl Makefile.PL 90 make 91 make install 92 93If the 'perl Makefile.PL' fails complaining to strange errors, you can check 94makefile.log to see if anything is wrong. A typical situation here is that 95Makefile.PL may report that is cannot find Perl library, for example, where 96there actually it invokes the compiler in a wrong way. 97 98Note, that in order to get Prima working from sources, your system must contain 99graphic libraries, such as libgif or ligjpeg, for Prima to load graphic 100files. 101 102=head2 What's about the graphic libraries? 103 104To load and save images, Prima employs graphic libraries. Such as, to load GIF 105files, libgif library is used, etc. Makefile.PL finds available libraries and 106links Prima against these. It is possible to compile Prima without any, but this 107is not really useful. 108 109On every supported platform Prima can make use of the following graphic 110libraries: 111 112 libX11 - XBM bitmaps 113 libXpm - Xpm pixmaps 114 libjpeg - JPEG images 115 libgif - GIF images 116 libpng - PNG images 117 libtiff - tiff images 118 libwebp,libwebpdemux,libwebpmux - WebP images 119 120Strawberry perl and Cygwin come with most of them, so on these installations Prima just 121compiles without any throuble. For other perl builds, use one of C<Prima::codecs::> 122modules that contains the needed include and lib files. If you're installing Prima 123through CPAN, that gets done authomatically. 124 125=head2 img/codec_XXX.c compile error 126 127C<img/codec_XXX.c> files are C sources for support of the graphic libraries. In 128case a particular codec does not compile, the ultimate fix is to remove the 129file and re-run Makefile.PL . This way, the problem can be avoided easily, 130although at cost of a lacking support for a graphic format. 131 132=head2 How'd I check what libraries are compiled in? 133 134 perl -MPrima -e 'print map { $_->{name}.qq(\n) } @{Prima::Image->codecs};' 135 136=head2 I have a graphic library installed, but Makefile.PL doesn't find it 137 138The library is probably located in a weird directory so Makefile.PL must be 139told to use it by adding LIBPATH+=/some/weird/lib, and possibly 140INCPATH+=/some/weird/include in the command line. Check makefile.log created by 141Makefile.PL for the actual errors reported when it tries to use the 142library. 143 144=head2 Compile error 145 146There are various reasons why a compilation may fail. The best would be 147to copy the output together with outputs of env and perl -V and send these into 148the Prima mailing list. 149 150=head2 Prima doesn't run 151 152Again, there are reasons for Prima to fail during the start. 153 154First, check whether all main files are installed correctly. F<Prima.pm> must 155be in your perl directory, and Prima library file ( F<Prima.a> or F<Prima.so> for 156unix, F<Prima.dll> for win32 ) is copied in the 157correct location in the perl tree. 158 159Second, try to run 'perl -MPrima -e 1' . If Prima.pm is not found, the error 160message would something like 161 162 Can't locate Prima.pm in @INC 163 164If Prima library or one of the libraries it depends on cannot be found, perl 165Dynaloader would complain. On win32 this usually happen when 166some dll files Prima needs are not found. If this is the case, try 167to copy these files into your PATH, for example in C:/WINNT . 168 169=head2 Prima doesn't get installed using ppm (ActiveState) 170 171Prima uses a non-conventional build process, which is not picked up by 172automated ActiveState ppm builder. So if you run "ppm install Prima" and 173it succeeds but installs nothing, try this: 174 175 ppm install --force http://cpan.uwinnipeg.ca/PPMPackages/10xx/Prima.ppd 176 177(Justin Allegakoen and Randy Kobes:thanks!) 178 179=head2 Prima error: Can't open display 180 181This error happens when you've compiled Prima for X11, and no connection to X11 182display can be established. Check your DISPLAY environment variable, or use 183--display parameter when running Prima. If you do not want Prima to connect to 184the display, for example, to use it inside of a CGI script, either use --no-x11 185parameter or include C<use Prima::noX11> statement in your program. 186 187=head2 X11: my fonts are bad! 188 189Check whether you have Xft and fontconfig installed. Prima benefits greatly from 190having been compiled with Xft/fontconfig. Read more in L<Prima::X11> . 191 192=head2 Where are the docs installed? 193 194Prima documentation comes in .pm and .pod files. These, when installed, 195are copied under perl tree, and under man tree in unix. So, 196'perldoc Prima' should be sufficient to invoke the main page 197of the Prima documentation. Other pages can be invoked as 'perldoc Prima::Buttons', 198say, or, for the graphical pod reader, 'podview Prima::Buttons'. podview 199is the Prima doc viewer, which is also capable of displaying any POD page. 200 201There is also a pdf file on the Prima web site www.prima.eu.org, which contains 202the same set of documentation but composed as a single book. Its sources are 203in utils/makedoc directory, somewhat rudimentary and require an installation 204of latex and dvips to produce one of tex, dvi, ps, or pdf targets. 205 206=head2 I've found a bug! 207 208Send the bug report into the mailing list or to CPAN RT. 209 210=head1 PROGRAMMING 211 212=head2 How can I use .fm files of the Visual Builder inside my program? 213 214podview L<Prima::VB::VBLoader> 215 216=head2 I want to use Prima inside CGI for loading and converting images only, without X11 display. 217 218 use Prima::noX11; # this prevents Prima from connecting to X11 display 219 use Prima; 220 my $i = Prima::Image-> load( ... ) 221 222Note that drawing on images will be severly limited - only pixel and put_image methods would work. 223 224=head2 How would I change several properties with a single call? 225 226 $widget-> set( 227 property1 => $value1, 228 property2 => $value2, 229 ... 230 ); 231 232=head2 I want Prima::Edit to have feature XXX 233 234If the feature is not governed by none of the C<Prima::Edit> properties, 235you've to overload C<::on_paint>. It is not that hard as you might think. 236 237If the feature is generic enough, you can send a patch in the list. 238 239=head2 Tk ( Wx, Qt, whatever ) has a feature Prima doesn't. 240 241Well, I'd probably love to see the feature in Prima as well, but I don't 242have a time to write it myself. Send in a patch, and I promise I'll check it out. 243 244=head2 I wrote a program and it looks ugly with another font size 245 246This would most certainly happen when you rely on your own screen properties. 247There are several ways to avoid this problem. 248 249First, if one programs a window where there are many widgets independent of each 250other size, one actually can supply coordinates for these widgets as they are 251positioned on a screen. Don't forget to set C<designScale> 252property of the parent window, which contains dimensions of the font used to design the 253window. One can get these by executing 254 255 perl -MPrima -MPrima::Application -le '$_=$::application->font; print $_->width, q( ), $_->height'; 256 257This way, the window and the widgets would get resized automatically under another font. 258 259Second, in case the widget layout is not that independent, one can position the 260widgets relatively to each other by explicitly calculating widget extension. For 261example, an C<InputLine> would have height relative to the font, and to have a 262widget placed exactly say 2 pixels above the input line, code something like 263 264 my $input = $owner-> insert( InputLine, ... ); 265 my $widget = $owner-> insert( Widget, bottom => $input-> top + 2 ); 266 267Of course one can change the font as well, but it is a bad idea since users 268would get annoyed by this. 269 270Third, one can use geometry managers, similar to the ones in Tk. See 271L<Prima::Widget::pack> and L<Prima::Widget::place>. 272 273Finally, check the widget layouts with L<Prima::Stress> written specifically for this 274purpose: 275 276 perl -MPrima::Stress myprogram 277 278=head2 How would I write a widget class myself? 279 280There are lots and lots of examples of this. Find a widget class similar to 281what you are about to write, and follow the idea. There are, though, some non-evident 282moments worth to enumerate. 283 284=over 285 286=item * 287 288Test your widget class with different default settings, such as colors, fonts, 289parent sizes, widget properties such as buffered and visible. 290 291=item * 292 293Try to avoid special properties for C<create>, where for example a particular property 294must always be supplied, or never supplied, or a particular combination of properties is 295expected. See if the DWIM principle can be applied instead. 296 297=item * 298 299Do not be afraid to define and re-define notification types. These have large number 300of options, to be programmed once and then used as a DWIM helper. Consider for which 301notifications user callback routines ( onXxxx ) would be best to be called first, or 302last, whether a notification should be of multiple or single callback type. 303 304If there is a functionality better off performed by the user-level code, consider 305creating an individual notification for this purpose. 306 307=item * 308 309Repaint only the changed areas, not the whole widget. 310 311If your widget has scrollable areas, use C<scroll> method. 312 313Inside C<on_paint> check whether the whole or only a part of the widget is 314about to be repainted. Simple optimizations here increase the speed. 315 316Avoid using pre-cooked data in C<on_paint>, such as when for example only a 317particular part of a widget was invalidated, and this fact is stored in an 318internal variable. This is because when the actual C<on_paint> call is 319executed, the invalid area may be larger than was invalidated by the class 320actions. If you must though, compare values of C<clipRect> property to see 321whether the invalid area is indeed the same as it is expected. 322 323Remember, that inside on_paint all coordinates are inclusive-inclusive, 324and outside inclusive-exclusive. 325 326Note, that C<buffered> property does not guarantee that the widget 327output would be actually buffered. 328 329=item * 330 331Write some documentation and example of use. 332 333=back 334 335=head2 How would I add my widget class to the VB palette? 336 337Check Prima/VB/examples/Widgety.pm . This file, if loaded through 338'Add widget' command in VB, adds example widget class and example 339VB property into the VB palette and Object Inspector. 340 341=head2 How would I use unicode/UTF8 in Prima? 342 343Basically, 344 345 $::application-> wantUnicodeInput(1) 346 347is enough to tell Prima to provide input in Unicode/UTF8. Note, that if the 348data received in that fashion are to be put through file I/O, the C<'utf8'> IO 349layer must be selected ( see L<open> ). 350 351Prima can input and output UTF8 text if the underlying system capabilities 352support that ( check Prima::Application::get_system_value, C<sv::CanUTF8_Input> 353and C<sv::CanUTF8_Output> ). Displaying UTF8 text is unproblematic, because Perl 354scalars can be unambiguously told whether the text they contain is in UTF8 or 355not. The text that comes from the user input 356- keyboard and clipboard - can be treated and reported to Prima 357either as UTF8 or plain text, depending on 358C<Prima::Application::wantUnicodeInput> property. 359 360The keyboard input is also easy, because a character key event comes with the character 361code, not the character itself, and conversion between these is done via 362standard perl's C<chr> and C<ord>. The clipboard input is more complicated, 363because the clipboard may contain both UTF8 and plain text data at once, and it 364must be decided by the programmer explicitly which one is desired. See more in 365L<Prima::Clipboard/Unicode>. 366 367=head2 Is there a way to display POD text that comes with my program / package ? 368 369 $::application-> open_help( "file://$0" ); 370 $::application-> open_help( 'My::Package/BUGS' ); 371 372=head2 How to implement parallel processing? 373 374Prima doesn't work if called from more than one thread, since Perl scalars 375cannot be shared between threads automatically, but only if explicitly told, 376by using L<thread::shared>. Prima does work in multithread environments though, 377but only given it runs within a dedicated thread. It is important not to 378call Prima methods from any other thread, because scalars that may be created 379inside these calls will be unavailable to the Prima core, which would result 380in strange errors. 381 382It is possible to run things in parallel by calling the event processing 383by hands: instead of entering the main loop with 384 385 run Prima; 386 387one can write 388 389 while ( 1) { 390 ... do some calculations .. 391 $::application->yield; 392 } 393 394That'll give Prima a chance to handle accumulated events, but that technique is 395only viable if calculations can be quantized into relatively short time frames. 396 397The generic solution would be harder to implement and debug, but it scales 398well. The idea is to fork a process, and communicate with it via its stdin 399and/or stdout ( see L<perlipc> how to do that), and use L<Prima::File> to 400asyncronously read data passed through a pipe or a socket. 401 402Note: Win32 runtime library does not support asynchronous pipes, only asyncronous sockets. 403Cygwin does support both asyncronous pipes and sockets. 404 405=head2 How do I use Prima with AnyEvent ? 406 407Prima works well with L<AnyEvent> but there are some minor differences in using 408Prima. L<AnyEvent> is a generic event processing library that supports various 409underlying event loop implementations such as L<EV>, L<Event>, L<POE> etc. 410Prima internally uses its own event loop to perform its event handling and 411L<AnyEvent> can support that by automatically selecting L<POE> to be the 412internal implementation when Prima is loaded. However, you may use L<AnyEvent> 413with any other internal event loop implementation such as L<EV> along with Prima 414with varying results depending on the event library used. There are a few points 415to note: 416 417=over 418 419=item * 420 421Prima has to be loaded before L<AnyEvent>. 422 423=item * 424 425If you want to use Prima's internal event loop system you have to install 426L<POE::Loop::Prima> and include it in your code before Prima is loaded like 427below: 428 use POE 'Loop::Prima'; 429 use Prima qw/Application/; 430 use AnyEvent; 431 432=item * 433 434You can call C<AnyEvent::detect> to check if the implementation is 435C<'AnyEvent::Impl::POE'> if you want to use Prima's event loop or it should be 436the event loop implementation you expect such as C<'AnyEvent::Impl::EV'>; 437 438=item * 439 440If you use L<POE::Loop::Prima> then you can continue to call C<run Prima> and 441should not call L<AnyEvent>'s condition variable C<recv> function. 442 443=item * 444 445If you want to use another event library implementation of L<AnyEvent>, you have 446to not call C<run Prima> but instead call L<AnyEvent>'s condition variable 447C<recv> function. 448 449=item * 450 451You have to use C<$::application-E<gt>yield> in an C<AnyEvent-E<gt>timer> object to 452allow for the Prima UI to update periodically, if you're not using 453L<POE::Loop::Prima>. 454 455=back 456 457See full example in F<examples/socket_anyevent.pl> and 458F<examples/socket_anyevent_poe.pl>. 459 460=head2 How do I post an asynchronous message? 461 462C<Prima::Component::post_message> method posts a message through the system event dispatcher 463and returns immediately; when the message is arrived, C<onPostMessage> notification is triggered: 464 465 466 use Prima qw(Application); 467 my $w = Prima::MainWindow-> create( onPostMessage => sub { shift; print "@_\n" }); 468 $w-> post_message(1,2); 469 print "3 4 "; 470 run Prima; 471 472 output: 3 4 1 2 473 474This technique is fine when all calls to the C<post_message> on the object are 475controlled. To multiplex callbacks one can use one of the two scalars passed 476to C<post_message> as callback identification. This is done by 477L<Prima::Utils/post>, that internally intercepts C<$::application>'s 478C<PostMessage> and provides the procedural interface to the same function: 479 480 use Prima qw(Application); 481 use Prima::Utils qw(post); 482 483 post( sub { print "@_\n" }, 'a'); 484 print "b"; 485 run Prima; 486 487 output: ba 488 489=head2 Now to address widgets inside TabbedNotebook / TabbedScrollNotebook ? 490 491The tabbed notebooks work as parent widgets for C<Prima::Notebook>, that 492doesn't have any interface elements on its own, and provides only page flipping 493function. The sub-widgets, therefore, are to be addressed as C<< 494$TabbedNotebook-> Notebook-> MyButton >>. 495 496=head2 How to compile a Prima-based module using XS? 497 498Take a look at L<Prima::IPA>, L<Prima::OpenGL>, L<Prima::Image::Magick>, L<PDL::PrimaImage>, 499and L<PDL::Drawing::Prima> . These modules compile against Prima dynamic module, 500start from there. Note - it's important to include PRIMA_VERSION_BOOTCHECK in the "BOOT:" 501section, to avoid binary incompatibilites, if there should be any. 502 503=head2 How do I generate Prima executables with PAR? 504 505You'll need some files that PAR cannot detect automatically. During the compilation 506phase Makefile.PL creates utils/par.txt file that contains these files. Include them with this 507command: 508 509 pp -A utils/par.txt -o a.out my_program 510 511=head1 AUTHOR 512 513Dmitry Karasik, E<lt>dmitry@karasik.eu.orgE<gt>. 514 515=head1 SEE ALSO 516 517L<Prima> 518