This chapter will introduce the basic structure all wxPerl programs share. Since this is the first step in wxPerl land, it will be very simple: it just opens a window.

# load wxPerl main module
use Wx;

Every wxPerl program must create an application object: it manages global state and processes events (we shall see this later).

# every application must create an application object
package MyApp;

use base 'Wx::App';

When an application object is created, wxPerl calls the OnInit method which is used to initialize global application data and usually creates one or more frames.

# this method is called automatically when an application object is
# first constructed, all application-level initialization is done here
sub OnInit {

The thing ALL OnInit methods do is creating one or more top level windows. The only thing to be noted is that wxWidgets requires every window to have an ID which is an integer number assigned at window creation time. In wxPerl most of the time you don't care about the value of the ID, so you should pass -1 to the window constructor to let wxWidgets generate an unique ID for you.

    # create a new frame (a frame is a top level window)
    my $frame = Wx::Frame->new( undef,           # parent window
                                -1,              # ID -1 means any
                                'wxPerl rules',  # title
                                [-1, -1],         # default position
                                [250, 150],       # size
                               );

Top level windows are not automatically shown by wxWidgets, hence you need to do it yourself.

    # show the frame
    $frame->Show( 1 );
}

This usually is all the code you ever need in your main package. It creates a new application instance thus calling OnInit, and starts the main application loop, which is responsible for dispatching GUI events to windows. The loop will not terminate until there are top level windows.

package main;

# create the application object, this will call OnInit
my $app = MyApp->new;
# process GUI events from the application this function will not
# return until the last frame is closed
$app->MainLoop;

And finally here is how this looks on screen.

Here you can see the program at a glance (it is suffixed .pl.txt so your browser will not try to execute it, but from Perl's point of view this makes no difference).