NAME
Prima::tutorial - introductory tutorial
DESCRIPTION
Programming graphic interfaces is often considered somewhat boring, and
not without a cause. It is a small pride in knowing that your buttons
and scrollbars work exactly as millions of others buttons and
scrollbars do, so whichever GUI toolkit is chosen, it is usually
regarded as a tool of small importance, and the less obtrusive, the
better. Given that, and trying to live up to the famous Perl ’making
easy things easy and hard things possible’ mantra, this manual page is
an introductory tutorial meant to show how to write easy things easy.
The hard things are explained in the other Prima manual pages ( see
Prima ).
Introduction - a "Hello world" program
Prima is written and is expected to be used in some traditions of Perl
coding, such as DWIM ( do what I mean ) or TMTOWTDI ( there are more
than one way to do it). Perl itself is language (arguably) most
effective in small programs, as the programmer doesn’t need to include
lines and lines of prerequisite code before even getting to the problem
itself. Prima can’t compete with that, but the introductory fee is low;
a minimal working ’Hello world’ can be written in three lines of code:
use Prima qw(Application);
Prima::MainWindow-> new( text => 'Hello world!');
run Prima;
Line 1 here is the invocation of modules Prima and Prima::Application.
Sure, one can explicitly invoke both "use Prima" and "use
Prima::Application" etc etc, but as module Prima doesn’t export method
names, the exemplified syntax is well-suited for such a compression.
Line 2 creates a window of Prima::MainWindow class, which is visualized
as a screen window, titled as ’Hello world’. The class terminates the
application when the window is closed; this is the only difference from
’Window’ windows, that do nothing after their closing. From here,
"Prima::" prefix in class names will be omitted, and will be used only
when necessary, such as in code examples.
Line 3 enters the Prima event loop. The loop is terminated when the
only instance of Application class, created by "use Prima::Application"
invocation and stored in $::application scalar, is destroyed.
Strictly speaking, a minimal ’hello world’ program can be written even
in two lines:
use Prima;
Prima::message('Hello world');
but it is not illustrative and not useful. "Prima::message" is rarely
used, and is one of few methods contained in "Prima::" namespace. To
display a message, the MsgBox module is often preferred, with its
control over message buttons and pre-defined icons. With its use, the
code above can be rewritten as
use Prima qw(Application MsgBox);
message('Hello world');
but where "Prima::message" accepts the only text scalar parameters,
"Prima::MsgBox::message" can do lot more. For example
use Prima qw(Application MsgBox);
message('Hello world', mb::OkCancel|mb::Information);
displays two buttons and an icon. A small achievement, but the
following is a bit more interesting:
use Prima qw(Application MsgBox);
message('Hello world', mb::OkCancel|mb::Information,
buttons => {
mb::Cancel => {
# there are predefined color constants to use
backColor => cl::LightGreen,
# but RGB integers are also o.k.
color => 0xFFFFFF,
},
mb::Ok => {
text => 'Indeed',
},
}
);
The definition of many object properties at once is a major feature of
Prima, and is seen throughout the toolkit. Returning back to the very
first example, we can demonstrate the manipulation of the window
properties in the same fashion:
use Prima qw(Application);
my $window = Prima::MainWindow-> new(
text => 'Hello world!',
backColor => cl::Yellow,
size => [ 200, 200],
);
run Prima;
Note that the "size" property is a two-integer array, and color
constant is registered in "cl::" namespace. In Prima there is a number
of such two- and three-letter namespaces, containing usually integer
constants for various purposes. The design reason for choosing such
syntax over string constants ( as in Perl-Tk, such as "color =>
'yellow'" ) is that the syntax is checked on the compilation stage,
thus narrowing the possibility of a bug.
There are over a hundred properties, such as color, text, or size,
defined on descendants of Widget class. These can be set in "new" (
alias "create" ) call, or referred later, either individually
$window-> size( 300, 150);
or in a group
$window-> set(
text => 'Hello again',
color => cl::Black,
);
In addition to these, there are also more than 30 events, called
whenever a certain action is performed; the events have syntax
identical to the properties. Changing the code again, we can catch a
mouse click on the window:
use Prima qw(Application MsgBox);
my $window = Prima::MainWindow-> new(
text => 'Hello world!',
size => [ 200, 200],
onMouseDown => sub {
my ( $self, $button, $mod, $x, $y) = @_;
message("Aww! You've clicked me right in $x:$y!");
},
);
run Prima;
While an interesting concept, it is not really practical if the only
thing you want is to catch a click, and this is the part where a
standard button is probably should be preferred:
use Prima qw(Application Buttons MsgBox);
my $window = Prima::MainWindow-> new(
text => 'Hello world!',
size => [ 200, 200],
);
$window-> insert( Button =>
text => 'Click me',
growMode => gm::Center,
onClick => sub { message("Hello!") }
);
run Prima;
For those who know Perl-Tk and prefer its ways to position a widget,
Prima provides pack and place interfaces. Here one can replace the line
growMode => gm::Center,
to
pack => { expand => 1 },
with exactly the same effect.
Widgets overview
Prima contains a set of standard ( in GUI terms ) widgets, such as
buttons, input lines, list boxes, scroll bars, etc etc. These are
diluted with the other more exotic widgets, such as POD viewer or
docking windows. Technically, these are collected in "Prima/*.pm"
modules and each contains its own manual page, but for informational
reasons here is the table of these, an excerpt of "Prima" manpage:
Prima::Buttons - buttons and button grouping widgets
Prima::Calendar - calendar widget
Prima::ComboBox - combo box widget
Prima::DetailedList - multi-column list viewer with controlling header
widget
Prima::DetailedOutline - a multi-column outline viewer with controlling
header widget
Prima::DockManager - advanced dockable widgets
Prima::Docks - dockable widgets
Prima::Edit - text editor widget
Prima::ExtLists - listbox with checkboxes
Prima::FrameSet - frameset widget class
Prima::Grids - grid widgets
Prima::Header - a multi-tabbed header widget
Prima::ImageViewer - bitmap viewer
Prima::InputLine - input line widget
Prima::Label - static text widget
Prima::Lists - user-selectable item list widgets
Prima::MDI - top-level windows emulation classes
Prima::Notebooks - multipage widgets
Prima::Outlines - tree view widgets
Prima::PodView - POD browser widget
Prima::ScrollBar - scroll bars
Prima::Sliders - sliding bars, spin buttons and input lines, dial
widget etc.
Prima::TextView - rich text browser widget
Building a menu
In Prima, a tree-like menu is built by passing a nested set of arrays,
where each array corresponds to a single menu entry. Such as, to modify
the hello-world program to contain a simple menu, it is enough to write
this:
use Prima qw(Application MsgBox);
my $window = Prima::MainWindow-> new(
text => 'Hello world!',
menuItems => [
[ '~File' => [
['~Open', 'Ctrl+O', '^O', sub { message('open!') }],
['~Save as...', sub { message('save as!') }],
[],
['~Exit', 'Alt+X', km::Alt | ord('X'), sub { shift-> close } ],
]],
],
);
run Prima;
Each of five arrays here in the example is written using different
semantics, to represent either a text menu item, a sub-menu entry, or a
menu separator. Strictly speaking, menus can also display images, but
that syntax is practically identical to the text item syntax.
The idea behind all this complexity is to be able to tell what exactly
the menu item is, just by looking at the number of items in each array.
So, zero or one items are treated as a menu separator:
[],
[ 'my_separator' ]
The one-item syntax is needed when the separator menu item need to be
later addressed explicitly. This means that each menu item after it is
created is assigned a (unique) identifier, and that identifier looks
like '#1', '#2', etc, unless it is given by the programmer. Here, for
example, it is possible to delete the separator, after the menu is
created:
$window-> menu-> remove('my_separator');
It is also possible to assign the identifier to any menu item, not just
to a separator. The other types (text,image,sub-menu) are discerned by
looking at the type of scalars they contain. Thus, a two-item array
with the last item an array reference (or, as before, three-item for
the explicit ID set), is clearly a sub-menu. The reference, as in the
example, may contain more menu items, in the recursive fashion:
menuItems => [
[ '~File' => [
[ '~Level1' => [
[ '~Level2' => [
[ '~Level3' => [
[]
]],
]],
]],
]],
],
Finally, text items, with the most complex syntax, can be constructed
with three to six items in the array. There can be set the left-aligned
text string for the item, the right-aligned text string for the display
of the hot key, if any, the definition of the hot hey itself, and the
action to be taken if the user has pressed either the menu item or the
hot key combination. Also, as in the previous cases, the explicit ID
can be set, and also an arbitrary data scalar, for generic needs. This
said, the text item combinations are:
Three items - [ ID, text, action ]
Four items - [ text, hot key text, hot key, action ]
Five items - [ ID, text, hot key text, hot key, action ]
Six items - [ ID, text, hot key text, hot key, action, data ]
Image items are fully analogous to the text items, except that instead
of the text string, an image object is supplied:
use Prima qw(Application MsgBox);
use Prima::Utils qw(find_image);
my $i = Prima::Image-> load( find_image( 'examples/Hand.gif'));
$i ||= 'No image found or can be loaded';
my $window = Prima::MainWindow-> new(
text => 'Hello world!',
menuItems => [
[ '~File' => [
[ $i, sub {} ],
]],
],
);
run Prima;
The action item of them menu description array points to the code
executed when the menu item is selected. It is either an anonymous
subroutine, as it is shown in all the examples above, or a string. The
latter case will cause the method of the menu owner ( in this example,
the window ) to be called. This can be useful when constructing a
generic class with menu actions that can be overridden:
use Prima qw(Application);
package MyWindow;
use vars qw(@ISA);
@ISA = qw(Prima::MainWindow);
sub action
{
my ( $self, $menu_item) = @_;
print "hey! $menu_item called me!\n"
}
my $window = MyWindow-> new(
menuItems => [
[ '~File' => [
['~Action', q(action) ],
]],
],
);
run Prima;
All actions are called with the menu item identifier passed in as a
string parameter.
Another trick is to define a hot key. While its description can be
arbitrary, and will be displayed as is, the hot key definition can be
constructed in two ways. It is either a literal such as "^A" for
Control+A, or @B for Alt+B, or "^@#F10" for Control+Alt+Shift+F10. Or,
alternatively, it is a combination of "km::" constants either with
ordinal of the character letter or the key code, where the key code is
one of "kb::" constants. The latter method produces a less readable
code, but is more explicit and powerful:
[ '~Reboot', 'Ctrl+Alt+Delete', km::Alt | km::Ctrl | kb::Delete, sub {
print "wow!\n";
}],
[ '~Or not reboot?', 'Ctrl+Alt+R', km::Alt | km::Ctrl | ord('R'), sub {}],
This concludes the short tutorial on menus. To read more, see
Prima::Menu .
AUTHOR
Dmitry Karasik, <dmitry@karasik.eu.org>.
SEE ALSO
Prima