Prima - a perl graphic toolkit

NAME

Prima - a perl graphic toolkit

SYNOPSIS

  use Prima qw(Application Buttons);

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

  run Prima;

DESCRIPTION

The toolkit is combined from two basic set of classes - core and external. The core classes are coded in C and form a base line for every Prima object written in perl. The usage of C is possible together with the toolkit; however, its full power is revealed in the perl domain. The external classes present easily expandable set of widgets, written completely in perl and communicating with the system using Prima library calls.

The core classes form an hierarchy, which is displayed below:

    Prima::Object
        Prima::Component
                Prima::AbstractMenu
                        Prima::AccelTable
                        Prima::Menu
                        Prima::Popup
                Prima::Clipboard
                Prima::Drawable
                        Prima::DeviceBitmap
                        Prima::Printer
                        Prima::Image
                                Prima::Icon
                Prima::File
                Prima::Timer
                Prima::Widget
                        Prima::Application
                        Prima::Window

The external classes are derived from these; the list of widget classes can be found below in SEE ALSO.

BASIC PROGRAM

The very basic code shown in SYNOPSIS is explained here. The code creates a window with 'Hello, world' title and a centered button with the same text. The program terminates after the button is pressed.

A basic construct for a program written with Prima obviously requires

  use Prima;

code; however, the effective programming requires usage of the other modules, for example, Prima::Buttons, which contains set of button widgets. Prima.pm module can be invoked with a list of such modules, which makes the construction

  use Prima;
  use Prima::Application;
  use Prima::Buttons;


shorter by using the following scheme:

  use Prima qw(Application Buttons);

Another basic issue is the event loop, which is called by

   run Prima;

sentence and requires a Prima::Application object to be created beforehand. Invoking Prima::Application standard module is one of the possible ways to create an application object. The program usually terminates after the event loop is finished.

The window is created by invoking

  Prima::Window-> create()

code with the additional parameters. Actually, all Prima objects are created by such a scheme. The class name is passed as the first parameter, and a custom set of parameters is passed afterwards. These parameters are usually represented in a hash syntax, although actually passed as an array. The hash syntax is preferred for the code readability:

   $new_object = Class-> create(
     parameter => value,
     parameter => value,
     ...
   );

Here, parameters are the class properties names, and differ from class to class. Classes often have common properties, primarily due to the object inheritance.

In the example, the following properties are set :

   Window::text
   Window::size
   Button::text
   Button::centered
   Button::onClick

Property values can be of any type, given that they are scalar. As depicted here, ::text property accepts a string, ::size - an anonymous array of two integers and onClick - a sub.

onXxxx are special properties that form a class of events, which share the create syntax, and are additive when the regular properties are substitutive (read more in the Prima::Object manpage). Events are called in the object context when a specific condition occurs. The onClick event here, for example, is called when the user presses (or otherwise activates) the button.

API

This section describes miscellaneous methods, registered in Prima:: namespace.

find_image PATH: Converts PATH from perl module notation into a file path, and searches for the file in @INC paths set. If a file is found, its full filename is returned; otherwise undef is returned.
message TEXT: Displays a system message box with TEXT.
path [ FILE ]: If called with no parameters, returns path to a directory, usually ~/.prima, that can be used to contain the user settings of a toolkit module or a program. If FILE is specified, appends it to the path and returns the full file name. In the latter case the path is automatically created by File::Path::mkpath unless it already exists.
run: Enters the program event loop. The loop is ended when Prima::Application's destroy or close method is called.
want_unicode_input [ BOOLEAN ]: Selects if the system is allowed to generate key codes in unicode. Returns the effective state of the unicode input flag, which cannot be changed if perl or system do not support UTF8.

COPYRIGHT

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHORS

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

Prima - a perl graphic toolkit