Part 1 - Foundations

Welcome to 'Mastering Perl Prima: A Step-by-Step Guide for Beginners'

1.1 Who This Tutorial Is For

This tutorial is for those familiar with Perl who want to explore graphical user interface (GUI) development using Perl Prima. If you already know Perl, this guide will help you leverage that knowledge to build interactive, user-friendly applications with Prima.

1.2 What You Should Already Know

To start with Prima, you should be comfortable with Perl basics:

• Variables and Data Types: using scalars ($var), arrays (@array), and hashes (%hash).
• Control Structures: writing loops (for, while) and conditional statements (if-else).
• Subroutines: defining and calling functions to organize your code.
• File Handling: reading from and writing to files.

If you're new to Perl, review these basics first. Once you're comfortable with these concepts, you'll be ready to build interactive GUI applications! Visit my website for additional tips, examples, and resources: https://reiniermaliepaard.nl/perl/

1.3 What You Will Learn

This tutorial covers essential concepts, including:

• Creating windows: learn how to initialize and configure your main application window.
• Managing widgets: discover how to work with various interface elements such as buttons, labels, and input fields.
• Handling events: understand how to respond to user interactions and system events effectively.
• Customizing behavior: explore how to personalize your application with custom actions and behaviors.

By the end, you'll have the skills to build and customize your own Perl Prima applications with interactive and responsive interfaces.

1.4 How to Use This Tutorial

You can use this tutorial in two ways:

On this website:

• Code examples can be copied and run directly without formatting issues.
• All images used in the examples can be downloaded here.
• The code has been tested on Linux; visual results may differ between Linux distributions, themes, and operating systems such as Windows.
• This website also includes a search function, which make it easy to quickly find topics, commands, or examples.

1.5 License

This tutorial is licensed under Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0). You are free to share and adapt this material for any purpose, as long as you give appropriate credit and distribute any derivative works under the same license. For more information, visit creativecommons.org/licenses/by-sa/4.0/

2. Why I wrote this tutorial on GUI Perl Prima

2.1 Making Perl Prima accessible

Perl Prima is a robust and versatile toolkit for building graphical user interfaces (GUIs) in Perl. Over the years, I've developed a variety of Windows applications - ranging from educational and math tools to music and data visualization software. Now that I've fully transitioned to Linux, I wanted to continue creating GUI tools, and Perl Prima has proven to be the ideal choice.

The official documentation, while comprehensive, can feel overwhelming for beginners because of its technical depth and specialized terminology. This tutorial aims to bridge that gap by presenting Prima in a clear, approachable way.

2.2 My journey and motivation

When I first started with Perl Prima, I was excited but quickly ran into challenges. The documentation, while thorough, often lacked a beginner-friendly approach with practical examples and clear explanations.

This inspired me to create a tutorial that breaks complex concepts into simple, actionable steps. My goal is to help you avoid the difficulties I encountered and make your learning journey smooth and enjoyable.

3. What Makes Prima Special

3.1 Cross-Platform Desktop GUI from One Codebase

Prima works seamlessly across Linux, Windows, and UNIX/X11 (including FreeBSD, IRIX, SunOS, Solaris, and more).

3.2 Modern User Interface Capabilities

Prima is a modern cross-platform GUI toolkit featuring a sleek, flat design that integrates well with contemporary desktop environments.

3.3 Visual Builder (RAD Tool)

Prima includes a RAD-style Visual Builder, a WYSIWYG tool for designing and testing GUIs quickly and intuitively.

3.4 Online Documentation and Learning Resources

• Online Documentation: Metacpan -Prima
• Documentation (PDF): Prima.pdf
• The package includes several useful examples, though some may be complex for beginners.

3.5 Maintenance and long-term support

Prima is actively maintained by its original developer, Dmitry Karasik, ensuring stability and long-term reliability.

4. Getting Started

4.1 Installing Prima

See Appendix B to learn how to install Perl Prima.

4.2 Your First Prima Script: Startup, Run Loop, Shutdown

Before exploring Prima in detail, let's create a small working program so you can see how a graphical application behaves. Let's make a compact version of a Prima application: a window (200x200) with a title and a centered button with text 'Exit!' and closes the application when the button is clicked. All in a few lines of code!

#!/usr/bin/perl
use strict;
use warnings;

use Prima qw(Application Buttons);

Prima::MainWindow->new(

    text => 'Your first Prima script', 
    size => [200, 200]

)->insert(Button =>

    centered => 1, 
    text => 'Exit!', 
    onClick => sub { $::application->close }

);

Prima->run;

Listing 4.1: Example of a Compact Prima Application

Don't worry if the code seems complicated. Everything will become clear later on.

How to run it?

1. Save the code in a file named my_script.pl
2. Open a terminal or command prompt.
3. Run the script with Perl: perl my_script.pl

4.3 The Essential Boilerplate Explained

To save space, the following essential code will be omitted from the examples but should be included at the start of every script -see the complete listing files for reference:

#!/usr/bin/perl
use strict;
use warnings;

4.4 Naming Conventions

Although I don’t always follow the naming conventions in this tutorial, readers are encouraged to do so.
See Appendix A: Naming Conventions for the complete set of rules.

Key points to keep in mind:

• Variables: use descriptive names with camelCase (e.g., $mainWindow, $colorDialog).
• Widgets: prefix widget variables with the widget type (e.g., $btnSubmit, $lblStatus).

4.5 Clarity Over Brevity

While conciseness is often celebrated in programming, clarity should never be sacrificed for the sake of brevity. Redundancy, in this context, is not a flaw - it’s a deliberate choice to make the code self-documenting and easy to understand at a glance. "Don’t make me think" is a guiding principle here. Code should be immediately comprehensible, without mental parsing of clever shortcuts.

So I like:

push (@checked_options, $chk_lisp->text) if $chk_lisp->checked;
push (@checked_options, substr($chk_perl->text, 1)) if $chk_perl->checked;
push (@checked_options, $chk_python->text) if $chk_python->checked;

above

my @checked_options = map {
    $_->checked ? ( $_ == $chk_perl ? substr($_->text, 1) : $_->text ) : ()
} ($chk_lisp, $chk_perl, $chk_python);

5. Object-Oriented Programming (OOP) Refresher

In the previous chapter we created our first Prima program. You may have noticed syntax such as Prima::MainWindow and the -> operator. These are part of Perl’s object-oriented programming model. Because Prima is heavily object-oriented, it is useful to briefly review the core OOP concepts before we continue (how OOP is specifically used in Prima will not be covered here).

We’ll first introduce general OOP concepts, and in later chapters, we’ll show how they are implemented in Perl - the language on which Prima is built.

5.1 Classes and Objects

Prima is designed in an object-oriented style, which involves key concepts like classes, objects, properties, methods, and inheritance.

• Class: a blueprint that defines the structure and behavior of objects.
• Object (Instance): a concrete entity created from a class blueprint.

In short, a class defines what an object can do and contain, while an object is a real instance of that class.

This concept will be reflected in Perl using packages (classes) and bless (object creation). More on this in Section 5.5.

5.2 Properties and Methods

Objects are characterized by properties and methods:

• Properties: attributes or data that define the state of an object.
• Methods: functions or subroutines that manipulate the object’s properties or perform actions.

In Perl, properties are usually stored in a hash reference, and methods are subroutines defined in the package representing the class.

5.3 Events and Event Handlers

In event-driven programming, applications respond to user or system actions (e.g., button clicks, mouse movements).

• Event Handlers: methods attached to objects that automatically execute when an event occurs.

Prima, being a GUI framework, heavily uses events, so understanding this concept helps when connecting Perl objects to interface actions.

5.4 Inheritance in Prima

Inheritance allows a class (subclass) to reuse attributes and methods from another class (superclass).

• This promotes code reuse and allows you to extend functionality without rewriting existing logic.
• In Perl, inheritance is implemented using the @ISA array or use base.

These concepts - classes, objects, methods, properties, and inheritance - will now be translated into Perl’s OOP style, which is flexible and minimalistic.

5.5 OOP in Perl

Perl does not have a built-in class keyword like Java. Instead, it achieves OOP behavior using packages and references. Below is a concise guide to the key Perl OOP concepts.

5.5.1 Classes via package

• A Perl class is a package (namespace).
• Methods are subroutines defined inside the package.

  package Animal;
  package Dog;

5.5.2 Objects via bless

• Objects are typically references (often hash references) holding the object’s data:

  my $data = {};  # regular hash reference

• Use bless to associate the reference with a class:

  my $object = bless($data, 'Dog');  # $object is now a Dog object

• Methods are called with the arrow operator:

  $object->speak();  # calls Dog::speak if defined

bless does not alter the data; it simply tells Perl which package’s methods to use.

5.5.3 Constructor (new method)

• Constructors are usually named new.
• They create and bless a data structure into the class.

  my $d = Dog->new();

new is a regular method, not a keyword.

5.5.4 The $self variable

• Inside object methods, the first argument is the object itself.
• $self is the conventional name for this argument:

sub speak {
    my $self = shift;
    print "Dog says: Woof!\n";
}

5.5.5 Inheritance

• Perl supports single and multiple inheritance.
• To inherit from a parent class:

  # Option 1: direct @ISA assignment
  our @ISA = ('Animal');

  # Option 2: use base
  use base 'Animal';

• Subclasses inherit parent methods unless explicitly overridden:

  package Dog;
  use base 'Animal';

  sub speak {
      my $self = shift;
      print "Dog says: Woof!\n";
  }

5.5.6 An Example

# --- Base Class: Animal ---
{
    package Animal;
    sub new {
        my $class = shift;
        my $self = {};
        bless($self, $class);
        return $self;
    }
    sub speak {
        my $self = shift;
        print "Animal makes a sound\n";
    }
}

# --- Subclass: Dog ---
{
    package Dog;
    use base 'Animal';
    sub speak {
        my $self = shift;
        print "Dog says: Woof!\n";
    }
}

# --- Subclass: Cat ---
{
    package Cat;
    use base 'Animal';  # inherits speak
}

# --- Main Script ---
{
    my $a = Animal->new();
    my $d = Dog->new();
    my $c = Cat->new();

    $a->speak();  # Animal makes a sound
    $d->speak();  # Dog says: Woof!
    $c->speak();  # Animal makes a sound
}

To separate classes into files: place them in Animal.pm, Dog.pm, Cat.pm and load them in main.pl using use Animal; use Dog; use Cat;. Each .pm must end with 1;.

5.5.7 Extending a Subclass

package Cat;
use base 'Animal';

sub new {
    my $class = shift;
    my $self = $class->SUPER::new();  # delegate to parent constructor
    $self->{color} = shift || 'black';
    return $self;
}

my $c = Cat->new('white');
print "Color cat: " . $c->{color} . "\n";  # Color cat: white

Using SUPER::new() avoids duplicating initialization logic and ensures a consistent object structure.

Closing words

GUI development in Perl Prima isn’t just writing code; it’s learning to put together windows, buttons, and event handlers so your program can interact with users. Take your time, try things out, and keep in mind that every application - no matter how refined - began with a simple first step.