Laying Out Controls Using Sizers

The first in a series of wxPerl Manual topics, Sizers and Layout covers the basics of using sizers to control the layout of your windows in wxPerl.

Hello World

This is the first in a series of basic wxPerl examples showing how to get started with wxPerl. This example simply opens a window with the title 'Hello World'.

The examples are meant to provide a basic guide; they try to assume only a no prior knowledge of wxWidgets API; for a detailed API description you need to refer to the wxWidgets manuals. The key thing you need to keep in mind while browsing wxWidgets documentation is that, if a wxPerl class is called, say, Wx::Frame, you should search for wxFrame in wxWidgets documentation.

Every Perl script should start by using the strict and warnings pragmas. Here we load the Wx module too.

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

Every wxPerl program must create an application object: it manages global state and processes events.

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.

# The OnInit method is called automatically when an
# application object is first constructed.
# Application level initialization can be done here.

sub OnInit {
    my( $self ) = @_;
    # create a new frame (a frame is a top level window)
    my $frame = Wx::Frame->new(
        undef,           # parent window
        -1,              # ID -1 means any
        'Hello World',   # title
        [-1, -1],        # default position
        [250, 150],      # size
    );

    # show the frame
    $frame->Show( 1 );
    
    # The OnInit sub must return a true value or the wxApp
    # will not start. Although an explicit return is not
    # necessary as the $frame->Show line will return
    # a true value, we'll include an explicit line
    # in this example.
    
    return 1;
}

Note 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 or the constant wxID_ANY to the window constructor to let wxWidgets generate an unique ID for you.

Top level windows are not automatically shown by wxWidgets, hence you need to do it yourself as in the example with $frame->Show(1);

This following is all the code you may 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
# before the constructor returns.

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.

The full text of the script is contained in helloworld.pl.txt  (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).