Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
pod::Prima::faq(3)    User Contributed Perl Documentation   pod::Prima::faq(3)

       Prima::faq - Frequently asked questions about Prima

       The FAQ covers various topics around Prima, such	as distribution,
       compilation, installation, and programming.

   What	is Prima?
       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.

   Yeah, right.	So what	is Prima again?
       Ok. A Yet Another Perl GUI.

   Why bother with the Yet Another thing, while	there is Perl-Tk and plenty of
       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 Perl?
       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

   But I want to use Prima in another language.
       Unless your language has	runtime	binding	with perl, you cannot.

   Who wrote Prima?
       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.

   What	is the copyright?
       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.

   I'd like to contribute.
       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.

   Where can I download	Prima?
       <> contains links	to source and binary download
       resources, instructions on how to subscribe to the Prima	mailing	list,
       documentation, and some other useful info.

   What	is better, source or binary?
       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.

   How to install binary distribution?
       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

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

   How to compile Prima	from source?
       Type the	following:

	  perl Makefile.PL
	  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

       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?
       To load and save	images,	Prima employs graphic libraries. Such as, to
       load GIF	files, libgif 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

	  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
       "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.

   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
       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.

   Compile error
       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.

   Prima doesn't run
       Again, there are	reasons	for Prima to fail during the start.

       First, check whether all	main files are installed correctly.
       must be in your perl directory, and Prima library file (	Prima.a	or	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 is not found, the
       error message would something like

	 Can't locate 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)
       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

       (Justin Allegakoen and Randy Kobes:thanks!)

   Prima error:	Can't open display
       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.

   X11:	my fonts are bad!
       Check whether you have Xft and fontconfig installed. Prima benefits
       greatly from having been	compiled with Xft/fontconfig.
       Prima::X11 .

   Where are the docs installed?
       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,	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!
       Send the	bug report into	the mailing list or to CPAN RT.

   How can I use .fm files of the Visual Builder inside	my program?
       podview Prima::VB::VBLoader

   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 not governed by none of the "Prima::Edit" properties,
       you've to overload "::on_paint".	It is not that hard as you might

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

   Tk (	Wx, Qt,	whatever ) has a feature Prima doesn't.
       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.

   I wrote a program and it looks ugly with another font size
       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
       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?
       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.

       o   Test	your widget class with different default settings, such	as
	   colors, fonts, parent sizes,	widget properties such as buffered and

       o   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.

       o   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

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

       o   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.

       o   Write some documentation and	example	of use.

   How would I add my widget class to the VB palette?
       Check Prima/VB/examples/ . 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.

   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

   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?
       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 thread::shared. 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

       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 ..

       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

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

   How do I use	Prima with AnyEvent ?
       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:

       o   Prima has to	be loaded before AnyEvent.

       o   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;

       o   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

       o   If you use POE::Loop::Prima then you	can continue to	call "run
	   Prima" and should not call AnyEvent's condition variable "recv"

       o   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.

       o   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/ and

   How do I post an asynchronous message?
       "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 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 ?
       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".

   How to compile a Prima-based	module using XS?
       Take a look at Prima::IPA, Prima::OpenGL, Prima::Image::Magick,
       PDL::PrimaImage,	and PDL::Drawing::Prima	. 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.

   How do I generate Prima executables with PAR?
       You'll need some	files that PAR cannot detect automatically. During the
       compilation phase Makefile.PL creates utils/par.txt file	that contains
       these files. Include them with this command:

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

       Dmitry Karasik, <>.


perl v5.32.1			  2019-03-13		    pod::Prima::faq(3)


Want to link to this manual page? Use this URL:

home | help