What is Prima?

Yeah, right. So what is Prima again?

Why bother with the Yet Another thing, while there is Perl-Tk and plenty of others?

Interestingly enough, Prima still builds for OS/2 (as of July 2012), but its support was killed because noone needs it anyway.

Why Perl?

But I want to use Prima in another language.

Who wrote Prima?

What is the copyright?

I'd like to contribute.

Where can I download Prima?

What is better, source or binary?

How to install binary distribution?

To install, unpack the archive and type 'perl ms_install.pl'. The files will be copied into the perl tree.

How to compile Prima from source?

   perl Makefile.PL
   make
   make install

If the 'perl Makefile.PL' fails complaining to strange errors, you can check makefile.log to see if anything is wrong. A typical situation here is that Makefile.PL may report that is cannot find Perl library, for example, where there actually it invokes the compiler in a wrong way.

Note, that in order to get Prima working from sources, your system must contain graphic libraries, such as libgif or ligjpeg, for Prima to load graphic files.

What's about the graphic libraries?

On every supported platform Prima can make use of the following graphic libraries:

   libX11   - XBM bitmaps
   libXpm   - Xpm pixmaps
   libjpeg  - JPEG images
   libgif   - GIF images
   libpng   - PNG images
   libtiff  - tiff images
   libwebp,libwebpdemux,libwebpmux  - WebP images

Strawberry perl and Cygwin come with most of them, so on these installations Prima just compiles without any throuble. For other perl builds, use one of "Prima::codecs::" modules that contains the needed include and lib files. If you're installing Prima through CPAN, that gets done authomatically.

img/codec_XXX.c compile error

How'd I check what libraries are compiled in?

   perl -MPrima -e 'print map { $_->{name}.qq(\n) } @{Prima::Image->codecs};'

I have a graphic library installed, but Makefile.PL doesn't find it

Compile error

Prima doesn't run

First, check whether all main files are installed correctly. Prima.pm must be in your perl directory, and Prima library file ( Prima.a or Prima.so for unix, Prima.dll for win32 ) is copied in the correct location in the perl tree.

Second, try to run 'perl -MPrima -e 1' . If Prima.pm is not found, the error message would something like

  Can't locate Prima.pm in @INC

If Prima library or one of the libraries it depends on cannot be found, perl Dynaloader would complain. On win32 this usually happen when some dll files Prima needs are not found. If this is the case, try to copy these files into your PATH, for example in C:/WINNT .

Prima doesn't get installed using ppm (ActiveState)

  ppm install --force http://cpan.uwinnipeg.ca/PPMPackages/10xx/Prima.ppd

(Justin Allegakoen and Randy Kobes:thanks!)

Prima error: Can't open display

X11: my fonts are bad!

Where are the docs installed?

There is also a pdf file on the Prima web site www.prima.eu.org, which contains the same set of documentation but composed as a single book. Its sources are in utils/makedoc directory, somewhat rudimentary and require an installation of latex and dvips to produce one of tex, dvi, ps, or pdf targets.

I've found a bug!

How can I use .fm files of the Visual Builder inside my program?

I want to use Prima inside CGI for loading and converting images only, without X11 display.

   use Prima::noX11; # this prevents Prima from connecting to X11 display
   use Prima;
   my $i = Prima::Image-> load( ... )

Note that drawing on images will be severly limited - only pixel and put_image methods would work.

How would I change several properties with a single call?

   $widget-> set(
      property1 => $value1,
      property2 => $value2,
      ...
   );

I want Prima::Edit to have feature XXX

If the feature is generic enough, you can send a patch in the list.

Tk ( Wx, Qt, whatever ) has a feature Prima doesn't.

I wrote a program and it looks ugly with another font size

First, if one programs a window where there are many widgets independent of each other size, one actually can supply coordinates for these widgets as they are positioned on a screen. Don't forget to set "designScale" property of the parent window, which contains dimensions of the font used to design the window. One can get these by executing

    perl -MPrima -MPrima::Application -le '$_=$::application->font; print $_->width, q( ), $_->height';

This way, the window and the widgets would get resized automatically under another font.

Second, in case the widget layout is not that independent, one can position the widgets relatively to each other by explicitly calculating widget extension. For example, an "InputLine" would have height relative to the font, and to have a widget placed exactly say 2 pixels above the input line, code something like

    my $input = $owner-> insert( InputLine, ... );
    my $widget = $owner-> insert( Widget, bottom => $input-> top + 2 );

Of course one can change the font as well, but it is a bad idea since users would get annoyed by this.

Third, one can use geometry managers, similar to the ones in Tk. See Prima::Widget::pack and Prima::Widget::place.

Finally, check the widget layouts with Prima::Stress written specifically for this purpose:

    perl -MPrima::Stress myprogram

How would I write a widget class myself?

• Test your widget class with different default settings, such as colors, fonts, parent sizes, widget properties such as buffered and visible.
• Try to avoid special properties for "create", where for example a particular property must always be supplied, or never supplied, or a particular combination of properties is expected. See if the DWIM principle can be applied instead.
• Do not be afraid to define and re-define notification types. These have large number of options, to be programmed once and then used as a DWIM helper. Consider for which notifications user callback routines ( onXxxx ) would be best to be called first, or last, whether a notification should be of multiple or single callback type.

  If there is a functionality better off performed by the user-level code, consider creating an individual notification for this purpose.

• Repaint only the changed areas, not the whole widget.

  If your widget has scrollable areas, use "scroll" method.

  Inside "on_paint" check whether the whole or only a part of the widget is about to be repainted. Simple optimizations here increase the speed.

  Avoid using pre-cooked data in "on_paint", such as when for example only a particular part of a widget was invalidated, and this fact is stored in an internal variable. This is because when the actual "on_paint" call is executed, the invalid area may be larger than was invalidated by the class actions. If you must though, compare values of "clipRect" property to see whether the invalid area is indeed the same as it is expected.

  Remember, that inside on_paint all coordinates are inclusive-inclusive, and outside inclusive-exclusive.

  Note, that "buffered" property does not guarantee that the widget output would be actually buffered.

• Write some documentation and example of use.

How would I add my widget class to the VB palette?

How would I use unicode/UTF8 in Prima?

   $::application-> wantUnicodeInput(1)

is enough to tell Prima to provide input in Unicode/UTF8. Note, that if the data received in that fashion are to be put through file I/O, the 'utf8' IO layer must be selected ( see open ).

Prima can input and output UTF8 text if the underlying system capabilities support that ( check Prima::Application::get_system_value, "sv::CanUTF8_Input" and "sv::CanUTF8_Output" ). Displaying UTF8 text is unproblematic, because Perl scalars can be unambiguously told whether the text they contain is in UTF8 or not. The text that comes from the user input - keyboard and clipboard - can be treated and reported to Prima either as UTF8 or plain text, depending on "Prima::Application::wantUnicodeInput" property.

The keyboard input is also easy, because a character key event comes with the character code, not the character itself, and conversion between these is done via standard perl's "chr" and "ord". The clipboard input is more complicated, because the clipboard may contain both UTF8 and plain text data at once, and it must be decided by the programmer explicitly which one is desired. See more in "Unicode" in Prima::Clipboard.

Is there a way to display POD text that comes with my program / package ?

   $::application-> open_help( "file://$0" );
   $::application-> open_help( 'My::Package/BUGS' );

How to implement parallel processing?

It is possible to run things in parallel by calling the event processing by hands: instead of entering the main loop with

   run Prima;

one can write

   while ( 1) {
      ... do some calculations ..
      $::application->yield;
   }

That'll give Prima a chance to handle accumulated events, but that technique is only viable if calculations can be quantized into relatively short time frames.

The generic solution would be harder to implement and debug, but it scales well. The idea is to fork a process, and communicate with it via its stdin and/or stdout ( see perlipc how to do that), and use Prima::File to asyncronously read data passed through a pipe or a socket.

Note: Win32 runtime library does not support asynchronous pipes, only asyncronous sockets. Cygwin does support both asyncronous pipes and sockets.

How do I use Prima with AnyEvent ?

• Prima has to be loaded before AnyEvent.
• If you want to use Prima's internal event loop system you have to install POE::Loop::Prima and include it in your code before Prima is loaded like below: use POE 'Loop::Prima'; use Prima qw/Application/; use AnyEvent;
• You can call "AnyEvent::detect" to check if the implementation is 'AnyEvent::Impl::POE' if you want to use Prima's event loop or it should be the event loop implementation you expect such as 'AnyEvent::Impl::EV';
• If you use POE::Loop::Prima then you can continue to call "run Prima" and should not call AnyEvent's condition variable "recv" function.
• If you want to use another event library implementation of AnyEvent, you have to not call "run Prima" but instead call AnyEvent's condition variable "recv" function.
• You have to use "$::application->yield" in an "AnyEvent->timer" object to allow for the Prima UI to update periodically, if you're not using POE::Loop::Prima.

See full example in examples/socket_anyevent.pl and examples/socket_anyevent_poe.pl.

How do I post an asynchronous message?

   use Prima qw(Application);
   my $w = Prima::MainWindow-> create( onPostMessage => sub { shift; print "@_\n" });
   $w-> post_message(1,2);
   print "3 4 ";
   run Prima;

   output: 3 4 1 2

This technique is fine when all calls to the "post_message" on the object are controlled. To multiplex callbacks one can use one of the two scalars passed to "post_message" as callback identification. This is done by "post" in Prima::Utils, that internally intercepts $::application's "PostMessage" and provides the procedural interface to the same function:

   use Prima qw(Application);
   use Prima::Utils qw(post);

   post( sub { print "@_\n" }, 'a');
   print "b";
   run Prima;

   output: ba

Now to address widgets inside TabbedNotebook / TabbedScrollNotebook ?

How to compile a Prima-based module using XS?

How do I generate Prima executables with PAR?

   pp -A utils/par.txt -o a.out my_program