Prima::faq - Frequently asked questions about Prima |
Prima::faq - Frequently asked questions about Prima
The FAQ covers various topics around Prima, such as distribution, compilation, installation, and programming.
Prima is a general purpose extensible graphical user interface toolkit with a rich set of standard widgets and an emphasis on 2D image processing tasks. A Perl program using PRIMA looks and behaves identically on X, Win32.
Ok. A Yet Another Perl GUI.
Prima was started on OS/2, where Tk didn't really run. We have had two options - either port Tk, or write something on our own, probably better than the existing tools. We believe that we've succeeded.
Interestingly enough, Prima still builds for OS/2 (as of July 2012), but its support was killed because noone needs it anyway.
Why not? Perl is great. The high-level GUI logic fits badly into C, C++, or the like, so a scripting language is probably the way to go here.
Unless your language has runtime binding with perl, you cannot.
Dmitry Karasik implemented the majority of the toolkit, after the original idea by Anton Berezin. The latter and set of contributors helped the development of the toolkit since then.
The copyright is a modified BSD license, where only two first paragraphs remain out of the original four. The text of copyright is present is almost all files of the toolkit.
You can do this is several ways. The project would probably best benefit from the advocacy, because not many people use it. Of course, you can send in new widgets, patches, suggestions, or even donations. Also, documentation is the thing that needs a particular attention, since my native language is not English, so if there are volunteers for polishing of the Prima docs, you are very welcome.
http://www.prima.eu.org contains links to source and binary download resources, instructions on how to subscribe to the Prima mailing list, documentation, and some other useful info.
Depends where your are and what are your goals. On unix, the best is to use the source. On win32 the binaries probably are preferred. If you happen to use cygwin you probably still better off using the source.
First, check if you've downloaded Prima binary for the correct version of Perl. For win32 ActiveState builds, difference in the minor digits of the Perl version shouldn't be a problem, for example, binary distribution for Perl build #805 should work with Perl build #808, etc etc.
To install, unpack the archive and type 'perl ms_install.pl'. The files will be copied into the perl tree.
Type the following:
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 libungif or ligjpeg, for Prima to load graphic files.
To load and save images, Prima employs graphic libraries. Such as, to load GIF files, libungif library is used, etc. Makefile.PL finds available libraries and links Prima against these. It is possible to compile Prima without any, but this is not really useful.
On every supported platform Prima can make use of the following graphic libraries:
libX11 - XBM bitmaps libXpm - Xpm pixmaps libjpeg - JPEG images libungif - GIF images libpng - PNG images libtiff - tiff 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
files are C sources for support of the graphic libraries. In
case a particular codec does not compile, the ultimate fix is to remove the
file and re-run Makefile.PL . This way, the problem can be avoided easily,
although at cost of a lacking support for a graphic format.
perl -MPrima -e 'print map { $_->{name}.qq(\n) } @{Prima::Image->codecs};'
The library is probably located in a weird directory so Makefile.PL must be told to use it by adding LIBPATH+=/some/weird/lib, and possibly INCPATH+=/some/weird/include in the command line. Check makefile.log created by Makefile.PL for the actual errors reported when it tries to use the library.
There are various reasons why a compilation may fail. The best would be to copy the output together with outputs of env and perl -V and send these into the Prima mailing list.
Again, there are reasons for Prima to fail during the start.
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 uses a non-conventional build process, which is not picked up by automated ActiveState ppm builder. So if you run ``ppm install Prima'' and it succeeds but installs nothing, try this:
ppm install --force http://cpan.uwinnipeg.ca/PPMPackages/10xx/Prima.ppd
(Justin Allegakoen and Randy Kobes:thanks!)
This error happens when you've compiled Prima for X11, and no connection to X11
display can be established. Check your DISPLAY environment variable, or use
--display parameter when running Prima. If you do not want Prima to connect to
the display, for example, to use it inside of a CGI script, either use --no-x11
parameter or include use Prima::noX11
statement in your program.
Check whether you have Xft and fontconfig installed. Prima benefits greatly from having been compiled with Xft/fontconfig. Read more in the Prima::X11 manpage .
Prima documentation comes in .pm and .pod files. These, when installed, are copied under perl tree, and under man tree in unix. So, 'perldoc Prima' should be sufficient to invoke the main page of the Prima documentation. Other pages can be invoked as 'perldoc Prima::Buttons', say, or, for the graphical pod reader, 'podview Prima::Buttons'. podview is the Prima doc viewer, which is also capable of displaying any POD page.
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.
Send the bug report into the mailing list or to CPAN RT.
podview the Prima::VB::VBLoader manpage
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.
$widget-> set( property1 => $value1, property2 => $value2, ... );
If the feature is not governed by none of the Prima::Edit
properties,
you've to overload ::on_paint
. It is not that hard as you might think.
If the feature is generic enough, you can send a patch in the list.
Well, I'd probably love to see the feature in Prima as well, but I don't have a time to write it myself. Send in a patch, and I promise I'll check it out.
This would most certainly happen when you rely on your own screen properties. There are several ways to avoid this problem.
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 the Prima::Widget::pack manpage and the Prima::Widget::place manpage.
Finally, check the widget layouts with the Prima::Stress manpage written specifically for this purpose:
perl -MPrima::Stress myprogram
There are lots and lots of examples of this. Find a widget class similar to what you are about to write, and follow the idea. There are, though, some non-evident moments worth to enumerate.
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.
Check Prima/VB/examples/Widgety.pm . This file, if loaded through 'Add widget' command in VB, adds example widget class and example VB property into the VB palette and Object Inspector.
Basically,
$::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 the open manpage ).
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 the Prima::Clipboard manpage.
$::application-> open_help( $0 ); $::application-> open_help( 'My::Package/BUGS' );
Prima doesn't work if called from more than one thread, since Perl scalars cannot be shared between threads automatically, but only if explicitly told, by using the thread::shared manpage. Prima does work in multithread environments though, but only given it runs within a dedicated thread. It is important not to call Prima methods from any other thread, because scalars that may be created inside these calls will be unavailable to the Prima core, which would result in strange errors.
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 the perlipc manpage how to do that), and use the Prima::File manpage 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.
Prima works well with AnyEvent but there are some minor differences in using Prima. AnyEvent is a generic event processing library that supports various underlying event loop implementations such as EV, Event, POE etc. Prima internally uses its own event loop to perform its event handling and AnyEvent can support that by automatically selecting POE to be the internal implementation when Prima is loaded. However, you may use AnyEvent with any other internal event loop implementation such as EV along with Prima with varying results depending on the event library used. There are a few points to note:
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 the POE::Loop::Prima manpage 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
the POE::Loop::Prima manpage.
See full example in examples/socket_anyevent.pl and examples/socket_anyevent_poe.pl.
Prima::Component::post_message
method posts a message through the system event dispatcher
and returns immediately; when the message is arrived, onPostMessage
notification is triggered:
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 the Prima::Utils manpage, 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
The tabbed notebooks work as parent widgets for Prima::Notebook
, that
doesn't have any interface elements on its own, and provides only page flipping
function. The sub-widgets, therefore, are to be addressed as <
$TabbedNotebook-
Notebook-> MyButton >>.
Take a look at IPA, the Prima::OpenGL manpage, the Prima::Image::Magick manpage, the PDL::PrimaImage manpage, and the PDL::Drawing::Prima manpage . These modules compile against Prima dynamic module, start from there. Note - it's important to include PRIMA_VERSION_BOOTCHECK in the ``BOOT:'' section, to avoid binary incompatibilites, if there should be any.
Dmitry Karasik, <dmitry@karasik.eu.org>.
Prima
Prima::faq - Frequently asked questions about Prima |