Top level windows

The main window of a Perl/Tk program is created by use of MainWindow, as below.

use Tk;
use strict;
my $mw = MainWindow->new;
# insert widgets into $mw
MainLoop;
# place any subroutines here

Widgets are the various components of the Tk program that interact with the user; the basic types of widgets - buttons, labels, checkbuttons, radiobuttons, scales, entries, text entries, scrollable widgets, menubuttons, menus, and dialogue boxes - we will describe in the next chapter. To give a flavour for the syntax, though, we give a simple example of the use of a ``Button'' widget:

#!perl
# file mw.pl
use Tk;
use strict;
use warnings;
my $mw = MainWindow->new;
$mw->title('Button');
my $exit = $mw->Button(-text => 'Exit',
                       -command => [$mw => 'destroy']);
$exit->pack;
MainLoop;

A screenshot of this window appears below.

Figure 2.2: A simple Perl/Tk program

In this example, we begin by creating the main window, with a title via the title method. The button widget, represented by the variable $exit, is created from a call to the Button method. Two options are passed to this call - one, the text option, passes along the string to be used as a label for the button, and the other, the command option, specifies the action to be taken when the button is pressed (in this case, simply exit the program). The pack method, which will be discussed later in this chapter, places the widget in the window.

MainWindow is in fact a special kind of Toplevel widget, of which a given program may have several (for example, a help window may be invoked when a particular button is pressed within the main window). A Toplevel window is created via the following syntax:

my $toplevel = $mw->Toplevel( [ option => value ]);

The various options available, as described in the Tk documentation, are listed below.

• -background
  This is the same as the standard background option except that its value may also be specified as undefined. In this case, the widget will display no background or border, and no colors will be consumed from its colormap for its background and border.
• -colormap
  This specifies a colormap to use for the window. The value may be either new, in which case a new colormap is created for the window and its children, or the name of another window (which must be on the same screen and have the same visual as $widget), in which case the new window will use the colormap from the specified window. If the colormap option is not specified, the new window uses the default colormap of its screen. This option may not be changed with the configure method.
• -container
  The value must be a boolean. If true, it means that this window will be used as a container in which some other application will be embedded (for example, a Tk toplevel can be embedded using the -use option). The window will support the appropriate window manager protocols for things like geometry requests. The window should not have any children of its own in this application. This option may not be changed with the configure method.
• -height This specifies the desired height for the window in any of the forms acceptable to Tk_GetPixels. If this option is less than or equal to zero then the window will not request any size at all.
• -menu
  This specifies a menu widget to be used as a menubar. On the Macintosh, the menubar will be displayed across the top of the main monitor. On Microsoft Windows and all UNIX platforms, the menu will appear across the toplevel window as part of the window dressing maintained by the window manager.
• -screen
  This specifies the screen on which to place the new window. Any valid screen name may be used, even one associated with a different display. It defaults to the same screen as its parent. This option is special in that it may not be specified via the option database, and it may not be modified with the configure method.
• -use
  This option is used for embedding. If the value isn't an empty string, it must be the the window identifier of a container window, specified as a hexadecimal string like the ones returned by the winfo id command. The toplevel widget will be created as a child of the given container instead of the root window for the screen. If the container window is in a Tk application, it must be a frame or toplevel widget for which the -container option was specified. This option may not be changed with the configure method.
• -visual
  This specifies visual information for the new window in any of the forms accepted by Tk_GetVisual. If this option is not specified, the new window will use the default visual for its screen. The visual option may not be modified with the configure method.
• -width
  This specifies the desired width for the window in any of the forms acceptable to Tk_GetPixels. If this option is less than or equal to zero then the window will not request any size at all.

There is also a title method, used as

$mw->title('Window title');

which may be used to set the title of the window.

As an example of creating a new top level window, consider the following program:

#!perl
# file tl.pl
use Tk;
use strict;
use warnings;
my $tl;
my $mw = MainWindow->new;
$mw->title('File preview');
my $button = $mw->Button(-text => 'Help',
                         -command => \&do_top);
my $exit = $mw->Button(-text => 'Exit',
                       -command => [$mw => 'destroy']);
$button->pack;
$exit->pack;
MainLoop;

sub do_top {
  if (! Exists($tl)) {
    $tl = $mw->Toplevel;
    $tl->title('Help');
    $tl->Button(-text => 'Close',
                -command => sub {$tl->withdraw })->pack;
  }
  else {
    $tl->deiconify;
    $tl->raise;
  }
}

For now don't worry about the use of Button widget - this will be discussed in the next Chapter. What happens in this example is that when the user presses the Help button a new top level window will be created, if it doesn't already exist. This window will be withdrawn when the Close button is pressed within that window. The main window is closed (and the program terminates) when the Exit button is pressed. A screen shot of this program with the new top level window created appears below.

Figure 2.3: Example of creating a top level window