Provided by: libprima-perl_1.28-1.2_amd64 bug

NAME

       Prima::faq - Frequently asked questions about Prima

DESCRIPTION

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

COMMON

   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 and OS/2 PM.

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

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

   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.

INSTALLATION

   Where can I download Prima?
       <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.

   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 and os2 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 etc.

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

   What's about the graphic libraries?
       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.
       If Makefile.PL wouldn't find any of the supported graphic libraries, it would abort unless
       WANTNOCODECS=1 parameter was supplied to it.

       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

       Alternatively, on win32 and os2 there is a binary PRIGPARH library distributed together
       with the Prima binary distributions, which supports its own set of graphic files. The
       PRIGPARH is a modified GBM graphic library, which ( GBM ) is no longer supported, but
       nevertheless it is useful for Prima. The use of PRIGPARH is preferred on win32 and os2,
       and Makefile.PL would favor it before the other graphic libraries.  To compile and run
       Prima with PRIGPARH, library ( .lib or .a) and runtime ( .dll ) files must be present in
       the LIBPATH and PATH, correspondingly.

   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. Prima.pm must be in your perl
       directory, and Prima library file ( Prima.a or Prima.so for unix, Prima.dll for win32, and
       PrimaDI.dll for os2 ) 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 and os2 this usually happen when prigraph.dll ( and/or priz.dll
       on os2 ) are not found. If this is the case, try to copy these files into your PATH, for
       example in C:/WINNT .

   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've Xft and fontconfig installed. Prima benefits greatly from having been
       compiled with Xft/fontconfig. Read more in 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 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!
       Send the bug report into the mailing list.

PROGRAMMING

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

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

       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.

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

   How would I use unicode/UTF8 in Prima?
       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
       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 transparent, 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 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( $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, bu 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 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 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 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".

AUTHOR

       Dmitry Karasik, <dmitry@karasik.eu.org>.

SEE ALSO

       Prima