Chapter 17

GUI Interfaces with Perl/Tk

CONTENTS

• Introduction to the Perl/Tk Package 
  • About the Authors of the Perl/Tk Package
• Where Do I Get and Build Perl/Tk?
• Documentation for Perl/Tk
• Writing Scripts in Perl/Tk
• Widgets as Building Blocks
• Configuring Widgets
  • Using CheckButton Widgets
  • Using RadioButton Widgets
  • Calling Subroutines When a Button Is Pressed
  • Arranging the Layout of Widgets
  • Using the Listbox and Scrollbar Widgets
  • Using Text Widgets
  • Specifying Fonts for Text and Other Widgets
  • Text Entry Widgets
• Handling the Keyboard with Key Bindings
• Displaying a Bitmap
• Displaying Images with Photo
• Menus
• The Canvas Widget
• Miscellaneous Topics
  • References with Subroutines
  • Changing the Cursor
  • Debugging Your Perl/Tk Scripts
  • More Than One Input File Handle
  • Eliminating and Hiding Windows
  • Creating More Than One Independent Window
• Summary

This chapter introduces you to using the Perl/Tk package to create graphical user interfaces (GUI) with Perl. After reading and working through the examples in this chapter, you should be able to create interactive user interfaces for your Perl scripts with very short design times.

Introduction to the Perl/Tk Package

The set of Tk modules attempts to tie the Tk widget toolkit with Perl 5. The set is referred to as Perl/Tk, pTk, or even ptk. The idea behind the merging of this set is to get the best features of both languages: Perl has very good text handling, regular expression support, dynamic memory, file and pipe I/O, and object-oriented capabilities for processing data; Tk gives you a quick and easy way to create GUI programs. Perl/Tk is most easily used on a UNIX computer platform running the X Window system. Perl/Tk does not require any of the lexical features of the Tcl scripting language. In other words, you do not have to be an expert at Tcl/Tk, but it will be in your best interest to have worked with the Tcl/Tk toolkit on its own to take the most advantage of the Perl/Tk package.This chapter will not make you a Tk expert. I assume you have a rudimentary working knowledge of Tcl/Tk programming. However, if you have never used Tcl/Tk before, now would be a good time to read the sample code for your Tcl/Tk package on your system. Here is a good starting reference book by the author of Tcl himself, Dr. John K. Ousterhout, professor at the University of California at Berkeley:

Tcl and the Tk Toolkit, John K. Ousterhout, ISBN 0-201-63337-X,
Addison-Wesley Publishing Company, 1994

There is one thing to remember when reading his book: You still have to translate the Tcl/Tk scripts to Perl.

The pTk library is a version of the Tk 4.0 toolkit. The library allows easier external linking and calling by Perl scripts and can be modularized. A number of composite widget extensions to the language have been written using Perl modules. Note that ptk does not necessarily refer to Perl/Tk, but could be taken to mean portable Tk; that is, portable to another language such as Perl, C, LISP, C++, and so on. It just so happens that our present work concentrates on Perl.

About the Authors of the Perl/Tk Package

The Perl/Tk package is still in beta phase and is being written primarily by Nick Ing-Simmons <Nick.Ing-Simmons@tiuk.ti.com> at Texas Instruments in Northampton, England. Mr. Nick was gracious enough to let us use his examples as the basis for the code samples in this chapter. He asked me to remind you that he is no way liable for how you use his package. He also requests that you give him credit for his authorship when you do use it. With regard to liability, he provides the following comments:

TkPerl was originally the name of a Perl 4 package that Mr. Malcolm Beattie, <mbeattie@sable.ox.ac.uk>, at Oxford University used to mesh the Tk toolkit with Perl. He also authored a Tcl module for Perl 5 with a Tcl::Tk module extension. That module allows the use of Tcl within a Perl script. You still must know both languages to get your widgets to work. I do not cover these libraries here.

A more extensive comparison of the differences between the Tkperl and the Perl/Tk code is given in the Tcl-perl.pod file that is distributed with the latest Perl/Tk package. The FAQs for Perl/Tk did provide some hints about getting the two packages to work together along with some friendly warnings about it not being very easy to do.

Where Do I Get and Build Perl/Tk?

At the time this book was written, the latest version was Tk-b9.01. You'll need Perl 5.002b1 or later to be able to work with the Tk-b9.01 kit. If you are like me and are skipping chapters while reading a book, don't skip the installation of Perl 5.002. There are some patches to 5.001m, but the 5.002 code will already have these patches in there. You need Perl 5.002, so install it first.

You can get the toolkit from any CPAN site. Here are the sites where I found the latest versions:

ftp://ftp.cis.ufl.edu/pub/perl/CPAN/
ftp://ftp.uoknor.edu/mirrors/CPAN/
ftp://ftp.metronet.com/pub/perl
ftp://ftp.perl.com/CPAN

Several more sites are listed in the FAQ and via the search results in Netscape Navigator. Try to get the package from a site that's geographically nearest you.

Building the Perl/Tk package after you get it is going to take some time and effort on your part. If you get any errors, most of them will be due to the use of out-of-date libraries or the wrong version of Perl, or both. Read the following directions carefully before you begin the installation.

First, unpack perl/Tk in your home directory. This will be your Tk build directory and will not corrupt any existing Perl 5 tree should something go wrong. Unzip and untar the files in this test directory. Use these commands:

gunzip Tk-b9.01.tar.gz
tar -xvf Tk-b9.01.tar

Next, create the make files. First, change the directory to the Tk/build directory, and then run the following commands to get to the directory, create the Makefiles, and create the package, respectively:

cd Tk-b9.01    
perl Makefile.PL
make
make install          

After you have built the files, check to see if you had any errors.

It's not a good idea to take a coffee break while this builds because some error messages might not be fatal and you may have an incomplete build and not see the error messages fly by. Take note of any missing references to libraries or header files.

If there were any errors due to missing make files or references to some header files, check the cc command in the make files for the directory with the offending error. Chances are that you do not have any inclusions of the pTk subdirectory header files. To help this out, try including the $(Inc) variable in the $ccCMD statement in the GNUmakefile file. You may have to do this for all the subdirectories under the Tk directory. Most of the errors I got during the build process were correctable with this inclusion.

Now, test the demo programs in the ./Tk/demos directory. Not all of the demos worked on my Linux system. The major complaint concerns CreateArgs() in the Toplevel module causing too many recursive calls. You may fare better. Minor tweaking did not remove this error. Major surgery seemed too daunting a task at this stage. Basically, any demo involving dialog boxes did not work. Do not waste your time trying to get these demos to work. Here is the error message that showed this problem:

Deep recursion on subroutine "CreateArgs"
at /usr/lib/perl5/Tk/Toplevel.pm line 16.

Even with this annoying bug, you should be able to install and work with the rest of the
package.

If you use the most current versions of the C++ compiler and make files, circa 1994 or later, and X11R6, you should have no problems. In case of problems, please consult the FAQ, INSTALL, or README files for your specific system.

Documentation for Perl/Tk

The make install execution installs the pod files for you in nroff format. Check the perl5/Tk/ directory for the file UserGuide.pod. This file is editable and readable by humans. pod files have to be interpreted through a reformatting program such as pod2man, pod2html, or pod2latex, all of which should be in your Perl distribution.

The following commands provide you with information in HTML files or in man pages:

pod2man ~khusain/p5/Tk/UserGuide.pod | nroff -man | more
pod2html ~khusain/p5/Tk/UserGuide
perldoc Toplevel.pm

The most visually pleasing of the three methods is the pod2html method:

$ pod2html perl5/Tk/Dial.pm
Creating Dial.pm.html from Dial.pm

The output of this command is as follows (you can use Mosaic or Netscape to view the contents of this file):

<!-- $Id$ -->
<HTML><HEAD>
<CENTER><TITLE>Dial.pm</TITLE>
</HEAD>
<BODY></CENTER><p><hr>

<H1>
<A NAME="Dial.pm_name_0">
NAME</A>
</H1>
Dial - an alternative to the scale widget
<p><p><hr>

<H1>
<A NAME="Dial.pm_synopsis_0">
SYNOPSIS</A>
</H1>

<XMP>
 use Tk::Dial;
 $dial = $top->Dial(-margin =>  20,
                    -radius =>  48,
                    -min    =>   0,
                    -max    => 100,
                    -value  =>   0,
                    -format => '%d');
 margin - blank space to leave around dial
 radius - radius of dial
 min, max - range of possible values
 value  - current value
 format - printf-style format for displaying format

</XMP>
<p>Values shown above are defaults.
<p><p><hr>

<H1>
<A NAME="Dial.pm_description_0">
DESCRIPTION</A>
</H1>
A dial looks like a speedometer: a 3/4 circle with a needle indicating the current value.  Below the graphical dial is an entry that displays the current value, and which can be used to enter a value by hand. <p>The needle is moved by pressing button 1 in the canvas and dragging. The needle will follow the mouse, even if the mouse leaves the canvas, which allows for high precision. Alternatively, the user can enter a value in the entry space and press Return to set the value; the needle will be set accordingly.
<p><p><hr>

<H1>
<A NAME="Dial.pm_to_0">
TO DO</A>
</H1>

<XMP>
 Configure
 Tick marks
 Step size

</XMP>
<p><p><hr>

<H1>
<A NAME="Dial.pm_authors_0">
AUTHORS</A>
</H1>
Roy Johnson, <A HREF="MAILTO:rjohnson@shell.com">rjohnson@shell.com</A>
<p>Based on a similar widget in XV, a program by John Bradley,
<A HREF="MAILTO:bradley@cis.upenn.edu">bradley@cis.upenn.edu</A>
<p><p><hr>

<H1>
<A NAME="Dial.pm_history_0">
HISTORY </A>
</H1>

<XMP>

August 1995: Released for critique by pTk mailing list

</XMP>
<p>
</BODY>
</HTML>

Also in the Tk-b9.01/doc directory are some .ht files which are copyrighted HTML pages of the documentation for the package.

Writing Scripts in Perl/Tk

The idea behind writing the Perl/Tk script using the modules for the package is to make life easier. The scripts have to include the Tk package with the use Tk; statement. You might want to consider using the warning switch (-w) and, if you are paranoid, use the use strict; statement to do extra syntax checking.

Look at the simple "Hello, world" script shown in Listing 17.1.

Listing 17.1. A simple "Hello, world" script.

 1  #!/usr/bin/perl -w
 2  #
 3  # Simple Tk script to create a button that prints "Hello, world".
 4  #
 5  use Tk;
 6  $mw = MainWindow->new;
 7  $hello = $mw->Button(-text => 'Hello, world',
    Â -command => sub {print STDOUT "Hello, world\n"; });
 8  $greet = $mw->Button(-text => 'Greetings',
    Â -command => sub {print STDOUT "Greetings\n"; exit;});
 9  $hello->pack;
10 $greet->pack(-side => "left");
11 MainLoop;

The first line in the file starts Perl with the -w switch for warnings to be issued, if necessary. Line 5 imports the Tk objects into the application. The statement in line 6 creates the main window. The "Hello, world" and Greetings buttons are created in lines 7 and 8. In line 9, the Hello button is added to the main window. In line 10, the Greetings button is pack-ed into the main window on the left side of the Hello button. (I cover pack-ing later throughout this chapter.) Line 11 starts the main user interface loop for this application. The output is shown in Figure 17.1.

Figure 17.1 :Sample "Hello, world" application.

The MainLoop; statement is the main widget event handler loop and is required in all Perl/Tk scripts. This event handler statement is usually near the end of the main procedure after the widgets have been created and are ready to be displayed.

In Listing 17.1, note that the Greet button defines an anonymous function (at line 8) with a call to the exit function. In line 7, the hello world function does not call the exit function.

The objects in this application are added one object at a time in a hierarchical order. This
involves the use of the -> infix dereference operator; for example, the $mw->Button(...) call forces the button to be created with the $mw object as the parent. Almost all objects and parameters in calls to Perl/Tk routines are passed by reference.

Please note the use of the => operator, which is simply a synonym for the comma operator. The program in Listing 17.1 could be rewritten as shown in Listings 17.2 and 17.3.

Listing 17.2. The "Hello, world" application using commas.

 1 #!/usr/bin/perl -w
 2 #
 3 # Using commas instead of =>.
 4 #
 5
 6 use Tk;
 7 $mw = MainWindow->new;
 8 $hello = $mw->Button(-text , 'Hello, world',
   Â-command , sub {print STDOUT "Hello, world\n"; });
 9 $greet = $mw->Button(-text , 'Greetings',
   Â-command , sub {print STDOUT "Greetings\n"; exit;});
10 $hello->pack;
11 $greet->pack(-side , "left");
12 MainLoop;

Listing 17.3. The "Hello, world" application using hashes.

 1 #!/usr/bin/perl -w
 2 #
 3 # Using Hashes instead of dereferencing using ->
 4 #
 5
 6 use Tk;
 7 $mw = MainWindow->new;
 8 my %hello = ('-text' , 'Hello, world',
   Â'-command' , sub {print STDOUT "Hello, world\n"; });
 9 my %greet = ('-text' , 'Greetings',
   Â'-command' , sub {print STDOUT "Greetings\n"; exit;});
10 $mw->Button(%hello)->pack;
11 $mw->Button(%greet)->pack('-side', "left");
12 MainLoop;

As you can see, you have a lot of flexibility in how you write your application. If you need more information on references, please refer to Chapter 3, "References," to see why Listing 17.3 works.

Widgets as Building Blocks

Basically, a widget can be "created" by simply calling the new method of the class name. For example, to create a new window, you use the following statement:

my $main = new MainWindow;
  ... code here to add widgets ...
MainLoop;

This statement sets aside the necessary system memory, and so on for a new MainWindow widget. The MainLoop; call causes it to appear. The object "created" then can be called via the variable $main.

It's a good idea to hang on to each object as it's created in the hierarchy. This way you can refer to the object explicitly should you need to change its parameters. Thus, the return values of most of your calls to create items are assigned to a variable:

$mybutton = $main->Button();

Now you can use $mybutton to refer to this Button object.

Configuring Widgets

Widgets are configurable to show different types of viewing styles. You can provide a number of configuration parameters via calls to the configure() function. Configuration parameters also can be sent in when the widget is created. For example, these two statements are equivalent:

my $button = $main->Button();
$button->configure(-text => 'Hello!');

and

my $button = new $main->Button(-text => 'Hello');

The "Hello, world" application is simple enough to demonstrate the use of Button widgets in Perl/Tk. You do have access to more widgets that you can use to create your own widgets. Check the subdirectories under the Tk-b9.01 tree to see what the widgets are. The Canvas widget is in the Canvas subdirectory.

The following Tk widgets are available under perl/Tk:

Each of these widgets comes with its own set of configurable parameters. As you work with these widgets you'll become familiar with the parameters associated with them. The best way to know which parameters are configurable is to check the Perl/Tk reference manuals to see what parameters are available for each type of widget.

The MainWindow widget is required for your applications. This widget serves as the main window for your Perl/Tk applications. Several functions exist for use as methods for this MainWindow object. For example, to set the title in the window, use the following command:

$main->title(" A sample window");

I cover some of these methods in the next few sections. Let's first see how we can place widgets on the main window.

Using CheckButton Widgets

Using check buttons is relatively easy. See Listing 17.4. The output is shown in Figure 17.2. The three buttons are shown side-by-side in the same window. If the parameters specifying the sides on the left are removed, the buttons appear as shown in Figure 17.3. You get this output by uncommenting the lines that create the buttons in Listing 17.4.

Figure 17.2 :Using Check buttons.

Figure 17.3 :Using check buttons without packing.

Listing 17.4. Using check buttons.

 1 #!/usr/bin/perl
 2
 3 use Tk;
 4
 5         #
 6         # Using Checkbuttons.
 7         #
 8
 9 my $main = new MainWindow;
10
11 $main->Checkbutton(-text => 'One'  )->pack;
12 $main->Checkbutton(-text => 'Two'  )->pack;
13 $main->Checkbutton(-text => 'Three' )->pack;
14
15 #
16 # Uncomment these lines to get the buttons to be side by side.
17 #
18 # $main->Checkbutton(-text => 'One')->pack(-side => 'left');
19 # $main->Checkbutton(-text => 'Two')->pack(-side => 'left');
20 # $main->Checkbutton(-text => 'Three ')->pack(-side => 'left');
21
22 MainLoop;

Using RadioButton Widgets

Radio buttons let you select one of many options, whereas check buttons allow you to select as many as possible. When using check buttons, you can press more than one button at a time. With radio buttons, you are showing several alternatives to an option. The value of the option is only one of several presented.

You have to specify the variable option on each radio button. The value of the -variable option is the escaped global Perl variable that will be assigned the value. All related radio buttons have to be assigned the same variable. Pressing each radio button causes the value of the variable to be set. Thus, each radio button has to set the value of the variable, too, with the -value configuration parameter. See Listing 17.5 for a sample script. The output is shown in Figure 17.4.

Figure 17.4 :Using radio buttons in Perl/TK scripts.

Listing 17.5. Using radio buttons.

 1  #!/usr/bin/perl
 2
 3  use Tk;
 4              #
 5              # Using RadioButtons.
 6              #
 7  my $main = new MainWindow;
 8  $main->title("Select Delicacy");
 9  #
10 # Declare the global variable
11 #
12 $animal = 'anything';
13 $main->Radiobutton(-text => 'Yak', -variable => \$animal,
14             -value => "Yak",
15             -command => sub {print "$animal \n"; } ,
16 )->pack(-side => 'left');
17 $main->Radiobutton(-text => 'Camel', -variable => \$animal,
18             -value => "Camel",
19             -command => sub {print "$animal \n"; } ,
20 )->pack(-side => 'left');
21 $main->Radiobutton(-text => 'Llama', -variable => \$animal,
22             -value => "Llama",
23             -command => sub {print "$animal \n"; }
24             )->pack(-side => 'left');
25 MainLoop;

Let's examine the new lines of code in Listing 17.5 in detail. Line 8 sets the title of the application window to Select Delicacy. Line 12 declares and sets the value of the global variable $animal to anything.

Lines 13 through 16 specify the first Radiobutton with the title Yak. The variable whose value will be set when this button is pressed is specified in the -variable parameter value. Note the escaped dollar sign for the name of the variable $animal. The -command configuration parameter specifies the anonymous subroutine to call when the button is pressed. The subroutine simply prints the value of the variable. You can add your code here.

In lines 17 through 20 and lines 21 through 24, two more radio buttons are specified that set the values of $animal to 'Camel' and 'Llama', respectively.

Calling Subroutines When a Button Is Pressed

You can add subroutines to call when a button is pressed. The examples in Listing 17.1 and 17.5 are two examples of this. You may specify the -command option in the call to create and pack the button (in Listing 17.5, this was done with lines 15, 19, and 23):

-command => sub {print "$animal \n"; } ,

You can refer to a subroutine by using the escaped ampersand with the name of the subroutine. Any parameters that have to be passed to the subroutine have to be specified with the -command parameters as one list. For example, consider the following function which creates a button with a caption of Stats, and calls the subroutine do_print when the button is pressed:

$main->Button(-text => 'Stats',
              -command => [ \&do_print , $inputfile, $outputfile ]
             )->pack;

Note the backslash in front of \&do_print. This causes Perl to generate a reference to sub do_print rather than call it. The input variables, $inputfile and $outputfile, are passed by reference not by value, into the do_print subroutine.

Arranging the Layout of Widgets

Widgets are laid out on a window using the -pack, -padding, -fill, -expand, and -anchor options of a widget. Windows also use a program called a geometry manager in Tk.

A geometry manager controls the arrangement of widgets in a window. The most common geometry manager used in pTk is pack. You have seen the use of the -pack function to place buttons on a window in earlier sections of this chapter. The pack function is also known informally as the "packer." You can invoke pack at the time of widget creation via calls like

$widget->pack;

where widget can be any of the Perl/Tk widget primitives. The pack function is often used in conjunction with the Frame container widget to arrange your widgets much like a hierarchically arranged set of window panes. See Listing 17.6 and Figure 17.5.

Figure 17.5 :The output from Listing 17.6.

Listing 17.6. Packing using frames.

 1 #!/usr/bin/perl
 2 use Tk;
 3
 4 $main = MainWindow->new;
 5
 6     my $row1 = $main->Frame;
 7     $row1->pack(-side => 'top');
 8     my $row2 = $main->Frame;
 9     $row2->pack(-side => 'bottom');
10     $row1->Label(-text => 'Left',
       Â-relief => 'sunken' )->pack(-side => 'left');
11     $row1->Label(-text => 'Right',
       Â-relief => 'sunken' )->pack(-side => 'right');
12     $row2->Label(-text => 'Left 2',
       Â-relief => 'ridge' )->pack(-side => 'left');
13     $row2->Label(-text => 'Right 2',
       Â-relief => 'ridge' )->pack(-side => 'right');
14     MainLoop;

In Listing 17.6, we used two frames: one on the top and the other on the bottom. These frames are called $row1 and $row2 and are created in lines 6 through 9. Then lines 10 and 11 create the two labels in $row1, and in lines 12 and 13, two more labels are created on the second frame. In this fashion we have packed labels on frames, and the frames are then packed onto the main window. You can think of this as building a Mayan temple of sorts with widgets being placed one on top of the other.

Note that pack itself is given parameters in this example. The default behavior of pack is to have -side => 'top', that is, align everything using the top edge. You can override this behavior by specifying a different packing style such as "left", "right", or "bottom".

The Tk* distribution has a file called popup that uses the -anchor option to configure the layout of the Radiobutton widgets. The output of this demo is shown in Figure 17.6. Run the following program to get the listing with line numbers for reference.

Figure 17.6 :Using the -anchor widget option.

$ nl popup | more

There is also the -anchor configuration option for widgets. There are introductions to the nine possible -anchor values, eight corresponding to the points on a compass and the ninth as the center position. The nine possible values are set around line 22 with list:

foreach $r ([qw(nw n ne)],[qw(w c e)],[qw(sw s se)])

In the beginning of the file, we create a small popup window to show when a button is clicked. Rather than create this window every time, a button is created but is not shown immediately. Around lines 13 through 17, the subroutine Show shows this window and requests it to be invisible after one second.

In the subroutine Anchor, a master frame is created (see line 21) with a ridge around it. Then three frames are placed on it, each with three buttons showing the anchor positions (see lines 25 through 29). The positions and the labels for the buttons are shown in line 22.

When setting lots of uneven widgets on the same frame, you can make their borders the same size by using -fill => 'style'. The style can be none | x | y | both. See the modified version of the radio button application and contrast the code in Listing 17.7 with the code in Listing 17.4. The output is shown in Figure 17.7, which you can compare with Figure 17.3 to see how the buttons with their borders are now shown and resized.

Figure 17.7 :Using the -fill option.

Listing 17.7. Using the -fill option.

 1 #!/usr/bin/perl
 2
 3 use Tk;
 4
 5 #
 6 # Using Checkbuttons and the -fill option.
 7 #
 8
 9 my $main = new MainWindow;
10 $main->title("fill");
11
12 $main->Checkbutton(-text => 'One',
13       -relief => 'ridge',
14       -command => sub {print "One \n"; } )->pack(-fill => 'x');
15 $main->Checkbutton(-text => 'Two',
16       -relief => 'sunken',
17       -command => sub {print "Two \n"; } )->pack(-fill => 'x');
18 $main->Checkbutton(-text => 'Three',
19       -relief => 'groove',
20       -command => sub {print "Three \n"; } )->pack(-fill => 'x');
20
21 MainLoop;

When laying out your widgets, look at their behavior with multiple resize operations. The -expand option of either pack or the widget itself can be used to set whether the widget expands or shrinks with its parent. Add the statement for packing the buttons in Listing 17.8; the buttons will shrink or expand as the main window is resized.

Listing 17.8. Using the Expand button.

1 $main->Checkbutton(-text => 'One',
2        -relief => 'ridge',
3        -command => sub {print "One \n"; } )->pack(-fill => 'x', -expand => '1');
4 $main->Checkbutton(-text => 'Two',
5        -relief => 'sunken',
6        -command => sub {print "Two \n"; } )->pack(-fill => 'x', -expand => '1');
7 $main->Checkbutton(-text => 'Three',
8        -relief => 'groove',
9        -command => sub {print "Three \n"; } )->pack(-fill => 'x', -expand => '1');

The output of this change to Listing 17.7 is shown in Figure 17.8. Remember to make this change to all the pack calls for the buttons.

Figure 17.8 :Using the option.

Using the Listbox and Scrollbar Widgets