I’ll start with the simplest of Tk’s buttons, the eponymously named button widget. Its syntax is:

button name ?args?

This command creates a button whose name is name with the attributes and command options specified by opts. Table 10.2 lists the arguments the button command supports.

Tk’s widget commands support two kinds of arguments: options and commands. Options are prefixed with a hyphen, and each option is usually followed by an argument. The -command option, for example, specifies a Tcl command to execute when the widget is executed, while the -height option specifies the widget’s height. Commands perform operations on the widget, such as the configure command, which modifies or queries the widget’s current configuration, and the flash command, which causes the widget to flash. Some commands accept no arguments, others accept a single argument, and still others accept multiple arguments.

In the case of the button command, you’ll usually want to modify the width or height, the command it executes, or click it programmatically by using the invoke command.

The following script, button.tcl in this chapter’s code directory, gets you started with buttons:

proc FlashButton {b} {
    # Save the original color
    set ocolor [$b cget -activebackground]    $b configure -activebackground red
$b flash    # Restore the original color
    $b configure -activebackground $ocolor
}

set lFlash [label .flash -width 20 -text "Flash Activate button"]
set lActivate [label .activate -width 20 -text "Activate Exit button"]

set bExit [button .e -width 8 -text "Exit" -state disabled 
    -command exit]
set bActivate [button .a -width 8 -text "Activate" 
    -command {$bExit configure -state normal}]
set bFlash [button .f -width 8 -text "Flash" 
    -command {FlashButton $bActivate}]

pack $lFlash
pack $bFlash -pady {0 20}
pack $lActivate
pack $bActivate -pady {0 20}
pack $bExit

When you execute this script, the initial screen should resemble Figure 10.7.

Figure 10.7. Basic Tk command buttons.

The FlashButton procedure accepts a single argument, the name of a button to flash (using the button widget’s flash command). Because the flash is so quick, I use the configure command to change the active background color to red (-activebackground red) before flashing the button. That way, when the button flashes, it is easier to see. After flashing the button, FlashButton restores the original background color, which is stored in the ocolor variable using the cget command at the beginning of the procedure.

Next, I create two labels to provide some descriptive text for their associated buttons. As a convention, I use an initial lowercase l (ell) to indicate that the variables (lFlash and lActivate) refer to label widgets. As with most coding conventions, it matters less what the convention is than it does that you choose and use one. This is mostly for your own sanity, but it helps other people who read your code to understand it, too. Similarly, for readability, I assigned easily recognized pathnames to the label widgets, .flash for the Flash button’s label and .activate for the Activate button’s label.

The next step is to create the buttons (I use an initial b for variables that refer to button widgets). The Exit button, a reference to what is stored in the bExit variable, is initially disabled (-state disabled), as you can see in Figure 10.7. When enabled and clicked, it executes the Tcl exit command to terminate the script.

The Activate button (accessed through the bActivate variable) comes next. When clicked, it changes the state of the Exit button to normal, meaning that the Exit button is enabled. I defined the Activate button after the Exit button because I needed to refer to $bExit when specifying $bActivate’s -command option. Similarly, the Flash button ($bFlash) had to be defined after $bActivate because $bFlash’s -command invokes the FlashButton procedure with an argument of $bActivate.

Click the Flash button to flash the Activate button. When you’re done amusing yourself with that, enable the Exit by clicking the Activate button. Finally, click the newly enabled Exit button, shown in Figure 10.8, to terminate the script.

Figure 10.8. One Tk button can modify another button’s state.

Okay, so it isn’t a mind-numbingly awesome program, but it does demonstrate some of the key features of Tk’s button widget.

Tk’s checkbutton widget is equivalent to what are known as option buttons in other windowing toolkits. Its syntax is identical to the button widget’s syntax:

checkbutton name ?args?

In addition to all the functionality of plain vanilla Tk buttons, checkbuttons also have a variable associated with them. When you select a checkbutton, the indicator is set (or “on”), and its linked variable’s value is set to 1 (the default) or the value specified by the -onvalue attribute. Deselecting or clearing a checkbutton clears or unsets the indicator and sets the variable’s value to 0 by default or the value specified by the -offvalue attribute. You can also use a checkbutton widget’s -command option to execute a Tcl command when the widget is clicked with the left mouse button.

Check buttons are often used in windows or tabs that set multiple options for program behavior. Unlike radio buttons, discussed in the next section, multiple checkbutton widgets can be set at once (radio buttons are linked together and only one can be set at a time). When used in this way, script code interrogates the value of the associated variable and sets the program’s behavior based on that value.

Tk’s checkbutton widget supports a wider array of options than does the plain button widget, as you can see in Table 10.3.

The following listing, ckbutton.tcl in this chapter’s code directory, shows how you can use checkbuttons and regular buttons together:

proc DoButton {action ckbuttons} {
    foreach ckbutton $ckbuttons {
        switch $action 
            toggle { $ckbutton toggle } 
            clear { $ckbutton deselect } 
            set { $ckbutton select }    }
}

proc ShowStatus {ckbuttons} {
    foreach ckbutton $ckbuttons {
        set var [$ckbutton cget -variable]      global $var      set val
[set $var]        puts "$var = $val"    }
}

set ckTop [checkbutton .cktop -text "Top checkbutton" 
    -command {ShowStatus .cktop}]
set ckMid [checkbutton .ckmid -text "Middle checkbutton" 
    -command {ShowStatus .ckmid}]
set ckBot [checkbutton .ckbot -text "Bottom checkbutton" 
    -offvalue "OFF" -onvalue "ON" -command {ShowStatus .ckbot}]

set ckbuttons [list $ckTop $ckMid $ckBot]

set bExit [button .eb -width 8 -text "Exit" 
    -command exit]
set bToggle [button .toggle -width 8 -text "Toggle All" 
    -command {DoButton toggle $ckbuttons}]
set bClear [button .clear -width 8 -text "Clear All" 
    -command {DoButton clear $ckbuttons}]
set bSet [button .set -width 8 -text "Set All" 
    -command {DoButton set $ckbuttons}]
set bShow [button .show -width 8 -text "Show All" 
    -command {ShowStatus $ckbuttons}]

pack $ckTop $ckMid $ckBot -anchor w
pack $bToggle -pady 5 -padx 5 -side
left pack $bClear $bSet $bShow $bExt -pady 5 -padx {0 5} -side left

The first procedure, DoButton, takes two arguments: an action to perform and a list of checkbuttons on which to perform the requested action. action corresponds to one of three command buttons: toggle (for the Toggle All button), clear (for the Clear All button), and set (for the Set All button). Toggling the checkbuttons means reversing their selected status; clearing them means calling each checkbutton’s deselect command; setting them means invoking their select command. I use a foreach loop to iterate through each button and perform the requested operation.

The second procedure, ShowStatus, displays the value of each checkbutton’s associated variable. It accepts a single argument, a list of checkbuttons over which to iterate. Again, using a foreach loop, I iterate over each checkbutton, performing the following steps:

Step 3, fetching the value of the widget’s linked variable, is a bit of a trick. Recall that the set command called with just a variable name (for example, set $var) returns the value of that variable. So the code set val [set $var] evaluates the nested command [set $var] and assigns the result of that command, the value of $var, to the variable $val. Although this might seem a bit obscure, you will appreciate being able to build a variable name and extract its value this way as you progress in your Tcl-writing avocation.

Notice that ShowStatus uses the puts command, which displays its output to stdout. I just want to be clear that even in a GUI program, you still have access to stdout and that the puts command does not scribble on the GUI, but on a plain old terminal session. If you start ckbutton.tcl from an icon without an underlying terminal session, the output generated by puts would be lost (unless you puts it to a file, of course).

The next section of code creates three checkbutton widgets. Nothing really extraordinary in this code block, but do notice that I give each widget a -command option, {ShowStatus name}. When you click the corresponding checkbutton, it will display its value after the click. For example, if you click the top checkbutton (see Figure 10.9), that click first selects the widget, setting its linked variable to its -onvalue (which defaults to 1), and then executes ShowStatus .cktop, which displays the new value. As a final twist, I define alternative values for the bottom checkbutton ($ckBot) selected and unselected states, OFF and ON, respectively, to demonstrate that you aren’t limited to using simple numeric values.

Figure 10.9. Tk checkbuttons.

Note: Don’t Forget about Grouping!

The -command option expects a single string argument, so you have to use braces to group arguments that include embedded spaces.

The last bit of setup code involves defining the command buttons that provide most of the application’s functionality. There are five buttons: an Exit button ($bExit); a Toggle All button ($bToggle) that invokes each checkbutton’s toggle command; a Clear All ($bClear) button that deselects each checkbutton; a Set All button ($bSet) that selects each checkbutton; and a Show All button ($bShow) that displays each checkbutton’s current selection status.

Finally, I’m ready to arrange and display the widgets. The first pack command arranges the three checkbuttons in the upper-lefthand corner of the window. I use the anchor w option to fix the checkbuttons against the “west” or left edge of the window. All of the buttons are laid out relative to the left side of the window using the -side left attribute. First, I place $bToggle with five pixels of padding on all sides. Next, I place $bClear, $bSet, $bShow, and $bExit with five pixels of padding on the top and bottom, zero padding on the left side, and five pixels of padding on the right. I don’t pad the left side of these four buttons because the padding on the right side of the previous button provides the spacing I need.

Figure 10.9 shows this script in action. Play around with the buttons while looking at the associated code so you can see how all the parts connect and interact.

Figure 10.9 shows the ckbutton.tcl script and the output created by clicking the Show All button. I ran this ckbutton.tcl from a terminal so you could see the output when you click the Show All button or one of the checkbuttons.

Unlike checkbuttons, radio buttons are usually used to select one item from a set of mutually exclusive set of items. Suppose that you want to allow users to select a color scheme, often called themes or skins, for your application. You can only apply a single color scheme at a time, so it makes sense to use radio buttons for the scheme selection interface. When a user selects one color scheme, the other color scheme radio buttons will be automatically unselected. The nice thing about Tk’s radiobutton widget is that it monitors the value of its associated variable and when the value of that variable changes, the widget automatically updates its selection status to reflect the current value of the linked variable. If, for example, the radiobutton for the Raspberry Red color scheme is selected and the user, in a fickle moment, selects the Passionate Purple radiobutton, the radiobutton for the Raspberry Red scheme automatically unselects itself. You’ll see this in action in just a moment.

Table 10.4 shows the arguments that Tk’s radiobutton widget supports.

The following script, radio.tcl in this chapter’s code directory, uses Tk’s radio buttons to implement a simple color section interface (you’ll learn more about Tk’s color handling later in this chapter):

proc SetColor {newColor} {
    . configure -background $newColor

    global lColor    $lColor configure -background $newColor

    global radButtons    foreach w $radButtons {
        $w configure -background $newColor 
            -activebackground $newColor 
            -highlightbackground $newColor    }
}

set rRed [radiobutton .rred -text "Red" -value red]
set rBlue [radiobutton .rblue -text "Blue" -value blue]
set rGreen [radiobutton .rgreen -text "Green" -value green]
set rYellow [radiobutton .ryellow -text "Yellow" -value yellow]
set rPurple [radiobutton .rpurple -text "Purple" -value purple]

set radButtons [list $rRed $rBlue $rGreen $rYellow $rPurple]

set lColor [label .lcolor -text "Select color scheme"]

set bSet [button .bset -width 8 -text "Set Color" 
   -command {SetColor $selectedButton}]
set bExit [button .bexit -width 8 -text "Exit" -command exit]

$rPurple select
$bSet invoke

pack $lColor -anchor w
pack $rRed $rBlue $rGreen $rYellow $rPurple -pady 0 -padx {2 0} -anchor w
pack $bSet -pady {10 2} -padx 5
pack $bExit -pady {2 10} -padx 5

radio.tcl uses five Tk radiobutton widgets from which you can select a color. When you click the Set button, the background color of the main window, the label, and the buttons change to the color you selected. Figure 10.10 (in black and white, so the color change is difficult to see) illustrates how it looks.

Figure 10-10. Using radiobutton widgets.

The SetColor procedure takes a single argument: the new color for the main window, the label, and the buttons. The first command sets the background color of the main window. After declaring the lColor global variable, I set its background color. I use a foreach loop to set the background color for each of the radiobutton widgets. Rather than passing in a list of widgets like I did in ckbutton.tcl, I declare the $radButtons variable as a global. I set three background attributes for each radiobutton to ensure that the color is correct, regardless of its state. The -background attribute covers the normal state, enabled but not active. It will come as no surprise that -activebackground covers the state when the radiobutton is active, that is, when the mouse is hovering over the button and clicking (selecting, in this case) the button. The -highlightbackground attribute colors the rectangle that appears around a widget when it is active.

After I define the SetColor helper procedure, I start laying out the widgets. First, I define five radiobutton widgets, one each for red, blue, green, yellow, and purple and a list of radiobutton widgets ($radButtons). For each button, I use the -value color attribute. This attribute sets the value that is assigned to the linked variable when the radiobutton is selected. You’ll no doubt notice that I don’t specify the name of the linked variable. If no variable name is specified (using -variable varname), the name defaults to selectedButton. While one could argue that it would be better to use a special variable name for uniqueness and easy identification, this script is short enough that using the default name is acceptable.

I then create a label, $lColor, to give users a hint what the radio buttons do, followed by two buttons, $bset and $bExit, to set the selected color or exit the script, respectively. The Exit button needs no comment. The Set Color button simply invokes the SetColor procedures, passing the $selectedButton variable to the procedure. Be careful here! Although the variable’s name is $selectedButton, the value it holds is the name of the color that will be set. It is precisely this potential confusion that makes defining my own variable instead of using the default variable a good idea. I kept the default name for a pedagogical reason (not to mention plain laziness), namely, I wanted you to know that radiobutton widgets have a default variable and what it is named.

Before displaying the widgets, I set a bit of initial state. The $rPurple select command sets the state of the purple radiobutton to be selected, which means that $buttonSelected has the value purple. $bSet invoke programmatically clicks the Set Color button to set the color to the one I just selected, which is purple. Bear in mind that the results of these commands won’t be visible until I explicitly draw the window with pack.

To display my GUI masterpiece, I first draw the label, anchoring it to the left side of the window. Next, I stack the five radiobutton widgets one on top of the other, again, anchoring them to the left side of the parent window. When I pack the Set Color button, I use a large amount of vertical padding to visually separate it from the radio buttons above it. For a similar but inverse reason, I pack the Exit button with very little vertical padding between it and the Set Color button. The purpose of this visual grouping is to relate the two command buttons to each other and to distinguish them from the radio buttons.

The following script, basic_menu.tcl in this chapter’s code directory, shows the steps you need to follow to add a menu to your application:

set mainMenu [menu .mainmenu]

. configure -menu $mainMenu

set mFile [menu $mainMenu.mFile -tearoff 0]
$mainMenu add cascade -label "File" -menu $mFile

$mFile add command -label "Open" -command {DoCmd Open}
$mFile add command -label "Close" -command {DoCmd Close}
$mFile add command -label "Save as" -command {DoCmd "Save as"}
$mFile add command -label "Save" -command {DoCmd Save}
$mFile add separator
$mFile add command -label "Exit" -command exit

proc DoCmd {cmd} {
tk_messageBox -icon info -type ok -message $cmd
}

The resulting window should resemble Figure 10.11.

Figure 10.11. With a minimal amount of Tk code, you can create a functional menu.

If you click the File item on the menu, the figure you see should look like Figure 10.12.

Figure 10.12. Clicking the File item opens the associated menu.

The first command, set mainMenu [menu .mainmenu], creates a menu entry. It doesn’t have any content, but I’ll take care of that in a moment. The next command, . configure -menu $mainMenu, associates the menu I just created with the root window, meaning that the menu entry referenced by $mainMenu is the menu bar for the root window. The next two lines of code add an item to the menu bar. In this case, I’m creating a “File” menu. First, I create a second menu entry named $mainMenu.mFile, which establishes the widget mFile as a child of the main menu—this relationship is necessary so that the mFile menu will display properly when users click the File item on the menu bar. The attribute -tearoff 0, tells Tk that this menu cannot be detached from the menu bar (the default value is -tearoff 1, which permits detaching, or tearing off the menu, to create a new top-level window). The second command, $mainMenu add cascade -label "File" -menu $mFile, adds an item named File to the menu bar (add cascade -label "File"), which, when clicked, opens the menu specified by $mFile (-menu $mFile).

The next block of code adds items to the newly created File menu. Specifically, I add an Open command, a Close command, a Save as command, a Save command, a separator, and an Exit command. The separator is merely a visual aid. Each of the command entries consists of a label and an associated command to carry out the requested operation. In this case, the command is DoCmd label, where label is the text. DoCmd itself is a simple procedure that uses the tk_messageBox procedure to pop up a window that displays the text passed to DoCmd. The exception is the Exit item, which invokes Tcl’s exit command to terminate the script.

To add another menu item, say, Edit, to the menu bar, you would create a second menu item and populate it with commands, for example:

set mEdit [menu $mainMenu.mEdit -tearoff 0]
$mainMenu add cascade -label "Edit" -menu $mEdit

$mEdit add command -label "Copy" -command {DoCmd "Copy"}
$mEdit add command -label "Paste" -command {DoCmd "Paste"}
$mEdit add command -label "Cut" -command {DoCmd "Cut"}
$mEdit add command -label "Search" -command {DoCmd "Search"}
$mEdit add command -label "Replace" -command {DoCmd "Replace"}

Figure 10.13 shows what the resulting menu would look like.

Figure 10.13. Use the code in basic_menu.tcl as a template for creating your own menus.

As you can see, creating a Tk menu isn’t difficult at all.

As usual, most of the code appears in the procedure definitions that make up Block 1 at the top of the file. The first procedure, SelectButton, selects a button at random from a list of buttons passed to it in the argument buttons and returns the name of that button to the calling procedure.

FlashButtons flashes each button in the list of buttons passed to it as an argument in buttons. The count argument indicates how many buttons to flash. The for loop creates the list of buttons to flash by calling SelectButtons $count times and appending the button name to the $flashList variable. The foreach loop iterates through $flashList, flashing each button twice and then pausing 1000 milliseconds (after 1000), or one second, to create a delay before flashing the next button. After flashing all of the buttons, FlashButton terminates, returning the list of flashed buttons to the calling procedure.

The next procedure, Score, compares the list of buttons the computer generated, passed in flashedButtons, to the list of buttons the player pressed, passed in pressedButtons. First, I disable the Score button to prevent the user from pressing it multiple times and to give the player a visual cue that the game is almost over. I perform two comparisons. If the length of the two lists is different, I know the lists don’t match and can terminate the procedure without needing to compare each button. If the lengths match, the second if statement compares the lists of buttons in their entirety. If the strings returned by the two lindex statements don’t match, the procedure terminates. Otherwise, the two lists match, and the player has won. In all cases, I update a label in the game window showing the player whether she won or lost.

Block 2 consists of the PlayGame procedure, which handles the bulk of the gameplay. It starts by disabling the Play button, then calls the FlashButtons procedure, passing it the list of buttons that was passed to PlayGame and the number of buttons to flash. I save the list of buttons returned by FlashButtons in the $flashedButtons variable so I can return that list to the main game loop. After all of the buttons are flashed, I enable the Score button and then instruct the player to try to replicate the sequence of button presses.

In Block 3, I start creating the game board. First, I create five colored buttons. Their -command attributes create entries in the list of buttons pressed by the user (stored in pressedButtons). Each button’s background color is a darker shade of its active background color. When pressed, this arrangement of colors makes the button noticeably easier to distinguish in its flashing state. I create a list of these game buttons to pass to the various procedures.

The command buttons, naturally, do the work in the program. The Play button, $bPlay, invokes the PlayGame procedure when pressed. The Score button, $bScore, starts out in the disabled state. As described earlier, it will be enabled after the buttons are flashed. This is largely a visual cue to the player to facilitate gameplay, but also serves to prevent unpleasant events if the player presses the Score button while the game buttons are being flashed. $bScore calls the Score procedure, passing the two lists of buttons to Score for evaluation. The Exit button is nothing new and enables the player to exit the game at any time. The instruction label, $lInfo, just provides an area where I can display text telling the player how to proceed.

The final lines of code lay out the widgets on the screen. I pack the red button first, to set a more aesthetically pleasing distance between the top of the button and the top edge of the window. Next, I pack the rest of the buttons and the information label in below the red button. The attributes -expand true -fill x cause the widgets to expand horizontally to fill their parcels in the window. I pack the Play, Score, and Exit buttons across the window with sizable padding between the instruction label and the tops of the command buttons. While this is partly an aesthetic preference on my part—I don’t like windows with widgets jammed together—it is also yet another visual hint to the player that separates the elements of the game to suggest that they have different functions.

With just a few widgets, you can write a reasonably complete Tk application. buttons, radiobuttons, and checkbuttons are common UI elements that enable users to invoke actions and make choices. Knowing how to set and modify colors in a user interface is important because humans use colors as visual cues. Nonetheless, no matter how visually rich and widget-packed you make your user interface, the core of any Tk application is still the Tcl code that ties UI elements to commands and procedures and that provides the logic that makes the application work.

Here are some exercises you can try to practice what you learned in this chapter: