DESCRIPTION
===========

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. 

PREREQUISITES
=============

Prima can use several graphic libraries to handle image files.  Compiling Prima
with at least one library, preferably for GIF files is strongly recommended,
because internal library images are stored in GIFs. Support for the following
libraries can be compiled in on all platforms:

   - libXpm
   - libpng
   - libjpeg
   - libungif
   - libtiff
   - libX11  - support for native X11 bitmap files

For Win32 and OS/2 platforms, libprigraph library can be used instead.  The
library supports most of the popular image file formats, including BMP, PCX,
GIF, JPEG, TIFF, PNG, and is distributed in binary form for these platforms:

   - Win32, native : http://www.prima.eu.org/download/gbm-bin-win32.zip. 
   - Win32, cygwin : http://www.prima.eu.org/download/gbm-bin-cygwin.zip. 
   - OS/2          : http://www.prima.eu.org/download/gbm-bin-os2.zip. 

The zip files contain prigraph.dll and other DLL files if needed. The files are
to be put in PATH. The library files, .LIB or .A, are used when compiling Prima
from source and to be put in LIBPATH.

SOURCE DISTRIBUTION INSTALLATION
================================

Create a makefile by running Makefile.PL using perl and then run make ( or
gmake, or nmake for Win32 and OS/2):

    perl Makefile.PL
    make
    make test
    make install

If 'perl Makefile.PL' fails, the compilation history along with errors can be
found in makefile.log. 

If make fails with message

** No image codecs found

that means you don't have image libraries that Prima supports in your path.
See PREREQUISITES section.

If some of the required libraries or include files can not be found,
INCPATH+=/some/include and LIBPATH+=/some/lib semantics should be used to tell
Makefile.PL about these.

To install Prima into a non-default directory, for example your home
directory:

    perl Makefile.PL PREFIX=$HOME/lib/perl

If compilation process fails because Makefile contains invalid switches for
your compiler or linker, try changing these by specifying arguments to
Makefile.PL, where the most useful are:

   COMPILER - type of compiler ( gcc, emx, mscv32, bcc32, irixcc)
   CC       - compiler command
   CFLAGS   - compiler arguments
   LD       - linked command
   LDFLAGS  - linker arguments

Look in Makefile.PL for details.

BINARY DISTRIBUTION INSTALLATION
================================

Available only for MSWin32 and OS/2. Please use installation from source for
the other platforms.

To install the toolkit from the binary distribution run 

   perl ms_install.pl

You have to patch Prima::Config.pm manually if you need to compile
prima-dependent modules.

USAGE EXAMPLES
==============

Try running the toolkit examples, by default installed in
INSTALLSITEARCH/Prima/examples directory ( find it by running perl
-V:installsitearch ). All examples and programs included into the distribution
can be run either by their name or with perl as argument - for example,
..../generic or perl ..../generic .  ( perl ..../generic.bat for win32 )


Typical code starts with

   use Prima qw(Application);

and ends with
   
   run Prima;

which is an event loop call. Start from the following code:

   use Prima qw(Application Buttons);

   Prima::MainWindow-> create(
      text     => 'Hello world!',
      size     => [ 200, 200],
   )-> insert( Button =>
      centered => 1,
      text     => 'Hello world!',
      onClick  => sub { $::application-> close },
   );

   run Prima;

Or, alternatively, start the VB program, which is the toolkit visual builder. 

MORE INFORMATION
================

The toolkit contains set of POD files describing its features, and the
programming interfaces.  Run 'podview Prima' or 'perldoc Prima' command to
start with the main manual page.

Visit http://www.prima.eu.org/ for the recent versions of the toolkit. You can
use cvs update feature to keep in touch. The mailing list on the toolkit is
available, you can ask questions there. See the Prima homepage for details.

COPYRIGHT
=========

(c) 1997-2003 The Protein Laboratory, University of Copenhagen

AUTHORS
=======

Dmitry Karasik <dmitry@karasik.eu.org>
Anton Berezin  <tobez@tobez.org>
Vadim Belman   <voland@lflat.org>

CREDITS
=======

David Scott <DScott@dgt.com>