Introducing Tk

Learning Tk Widget Basics

Now that you have been exposed to Tcl, you can begin writing Tk scripts. What you need to know are the Tk commands used to create and configure widgets.

As you create a widget, you can specify many of its characteristics as arguments of the command. You can, for example, create a blue button with a red label (test) and display the button by using the following commands:

button .b -text test -fg red -bg blue
pack .b

The pack command does not create a widget; rather, it positions a widget in relation to others. Table 25-5 lists all the widget-manipulation commands.

Defining Widget Hierarchies in Tk

From the example that creates a label and a button, you may have guessed that the argument that follows the widget-creation command is the widget's name. If you are wondering why all the names start with a period, which is required at the beginning of a widget's name, it is because widgets are organized in a hierarchy.

Suppose that you have a main window that contains a menu bar, a text area, and a scroll bar. The menu bar has two buttons, labeled File and Help. Figure 25-4 shows this widget hierarchy as it appears onscreen; it also shows how the widget names relate to this hierarchy.

Figure 25-4: Relationship between Widget Names and the Widget Hierarchy.

Configuring Widgets

Tk treats each widget name as a command name. You can perform operations on a specific widget by using that widget's name, followed by arguments that make sense for that widget. If you have a button named .b, for example, use the following command to set that button's background to blue:

.b config -fg blue

You can change the button's label to Goodbye! by using the following command:

.b config -text Goodbye!

The arguments -fg blue and -text Goodbye! specify the attributes of a widget. Each attribute name begins with a hyphen (-), as in -text. The next argument is that attribute's value.

Displaying Widgets

Tk does not display a widget, until you use a command to position the widget in the main window. To display the widgets, you have to use a geometry manager-a Tk procedure that arranges one or more child widgets in a parent widget.

Using the pack Command

The pack command is the most commonly used geometry-management command in Tk. As some of the simple examples in this chapter show, to make a button named .btn1 appear, use pack as follows:

pack .btn1

You can specify several widget names on the same pack command line. To display the buttons .btn1, .btn2, and .btn3, arranged in a vertical line in that order, use the following:

pack .btn1 .btn2 .btn3

On a menu bar, for instance, this type of pack command makes the most efficient use of the available space.

Table 25-6 summarizes the pack command's syntax. As Table 25-6 shows, you can use the pack command to position widgets and get information about the widget hierarchy.

Using the place Command

The place command is a simpler way to specify the placement of widgets as compared to the pack command, but you have to position all the windows yourself. It is simpler than pack because the place command gives you direct control of the widget positions. On the other hand, direct control of widget placement is fine for a few windows, but it can get tedious in a hurry when you have many widgets in a user interface.

Using place, you can position a widget at a specific location. For example, to place .btn1 at the coordinate (100, 50) in its parent widget, use the following command:

place .btn1 -x 100 -y 50

A good use of place is to center a widget within its parent widget. For this purpose, use the -relx and -rely options of place. If .f is a frame widget (a widget that contains other widgets), you can display it at the center of the parent window by using the following commands:

frame .f
button .f.b1 -text Configure
button .f.b2 -text Quit
pack .f.b1 .f.b2 -side left
place .f -relx 0.5 -rely 0.5 -anchor center

As the code fragment shows, the buttons inside the frame are packed with the pack command. Only the frame, .f, is positioned with the place command. The -relx and -rely options enable you to specify the relative positions in terms of a fraction of the containing widget's size. A zero value for -relx means the left edge; 1 is the right edge; and 0.5 means the middle.

Like pack, the place command has several forms, listed in Table 25-8.

Binding Actions to Events

When you write a program that has a graphical user interface, various program actions are initiated by events, such as the user clicking a button in the user interface. In a Tk script, you indicate what the program does by associating actions with events. In this case, an action is simply a Tcl script that performs some task. In the case of a Quit button, for example, a logical action is the Tcl command exit, which ends the Tk script.

For buttons, a click of the button is a simple way to form this association. Use the command option of the button command to specify a Tcl command to be executed when the user clicks the button. The exit command is associated with the Quit button as follows:

button .b -text Quit -command { exit }

bind widgetName <eventSpecification> TclCommand

To see a more detailed example of how to bind an action to an event, consider this scenario. You may have noticed that many Microsoft Windows applications, as well as GNOME and KDE applications, sport a toolbar-essentially, a collection of buttons, each of which is meant to perform a specific task. Typically, each button bears an icon that indicates its purpose. To help users learn the meaning of a button quickly, many Windows applications have a feature called tool help. If you place the mouse pointer on a button, a small window pops up, displaying a short help message that tells you what the button does.

You can use Tk to implement a similar tool-help feature. Follow these steps:

1. Create the button.

2. Prepare the help message as a label (preferably with a bright background, such as yellow).

3. When the mouse pointer enters a button, an Enter event occurs. Bind the Enter event to a command that makes the help label visible. Use the place command to position the label relative to the button, so that the tool help label always appears near the associated button. The following example shows how bind is used to associate the place command (shown within braces) with the Enter event:

   bind .f.q <Enter> { place .bh -in .f.q -relx 0.5 -rely 1.0 }

4. When the mouse pointer leaves the button, a Leave event occurs. Bind the Leave event to the place forget command to hide the help message, as follows:

   bind .f.q <Leave> { place forget .bh }

The following sample toolhelp script demonstrates how to implement tool help in Tk:

#!/usr/bin/wish -f
# Demonstrates a "tool help" window that appears when you
# place the mouse pointer inside the Quit button.
wm geometry . 180x60
frame .f
button .f.b -text File
label .bh -text "Quit program"
.bh config -bg yellow
button .f.q -text Quit -command { exit }
bind .f.q <Enter> { place .bh -in .f.q -relx 0.5 -rely 1.0 }
bind .f.q <Leave> { place forget .bh }
pack .f.b .f.q -side left
pack .f -fill x

Make the toolhelp script file executable by using the chmod +x toolhelp command. Then run that script by typing ./toolhelp at the shell prompt in a terminal window. Figure 25-5 shows the window that results after you place the mouse pointer on the Quit button.

Figure 25-5: A Tk Script That Demonstrates How to Implement toolhelp Messages.

When you use bind to associate a Tcl script with an event, you need to know how to specify the event. Most are either keyboard events or mouse events. A smaller number of events are related to the state of a widget's window. <Map> and <Unmap> events, for example, occur when a widget is managed or unmanaged (when you use pack forget or place forget).

Understanding Keyboard Events

There are two keyboard events:

• <KeyPress> occurs when you press a key.

• <KeyRelease> occurs when you release a key.

You can specify a keyboard event for a specific key by appending that key's keysym (which is the X Window system's standard name for a key) to the string KeyPress- and enclosing everything in angle brackets. The event associated with pressing the q key, for example, is specified by <Keypress-q>. Tk provides a shorter format for keyboard events. You can simply place the keysym inside angle brackets, as follows:

<q>

For most key presses, the event specification is straightforward. If you want to exit when the user presses Ctrl-C inside a widget named .text, use the bind command as follows:

bind .text <Control-c> exit

Table 25-10 shows some other commonly used keysyms.

# Assume .text1 is a text widget
bind .text1 <KeyPress> {
    if { "%A" != "{}"} { %W insert insert %A}
}

Understanding Mouse Events

Use <ButtonPress> and <ButtonRelease> to denote mouse-button click and release events, respectively. You have to append the button number to make the event specific. Thus, clicking the left mouse button (which is button 1 in X terminology) is denoted by <ButtonPress-1>. A shorthand notation for button presses is to omit Press; thus, you can write <Button-1> to denote the event generated by clicking the left mouse button.

bind .text1 <Button-1> { puts "Click at (%x, %y) on widget: %W"}

Understanding Window Events

In addition to keyboard and mouse events, X includes many events that occur when a window is manipulated. The X server generates <Map> and <Unmap> events, for example, when a widget is displayed or hidden (by the pack or place command).

A <Configure> event occurs when the user resizes a window. Thus, you can bind a <Configure> event to a redisplay procedure that redraws the contents of a widget based on the new size.

A <Destroy> event occurs when a window is about to be destroyed. Bind a procedure to the <Destroy> event, and intercept requests to delete a window.