10.46.3.4 Widget Creation

As has already been said, a widget is a window object that has state and behavior. In terms of Tcl/Tk a widget is created by calling a widget creation command. There is a specific widget creation for each type of widget.

The widget creation command is supplied with arguments. The first argument is always the name you want to give to the resulting widget; the other arguments set the initial state of the widget.

The immediate result of calling a widget creation command is that it returns the name of the new widget. A side effect is that the instance of the widget is created and its name is defined as in the Tcl interpreter as a procedure through which the widget state can be accessed and manipulated.

This needs an example. We will use the widget creator command button to make a button widget:

button .fred -text 'Fred' -background red

which creates an instance of a button widget named .fred that will display the text Fred on the button and will have a red background color. Evaluating this command returns the string .fred, the name of the newly created widget.

As a side effect, a Tcl procedure named .fred is created. A call to a widget instance has the following form:

widgetName method methodArgs

where widgetName is the name of the widget to be manipulated, method is the action to be performed on the widget, and methodArgs are the arguments passed to the method that is performed on the widget.

The two standard methods for widgets are configure and cget. configure - is used to change the state of a widget; for example:

.fred configure -background green -text 'Sid'

will change the background color of the widget .fred to green and the text displayed to Sid.

cget is used to get part of the state of a widget; for example:

.fred cget -text

will return Sid if the text on the button .fred is Sid.

In addition to these general methods, there are special methods for each widget type. For example, with button widgets you have the flash and invoke methods.

For example,

.fred invoke

can be called somewhere in the Tcl code to invoke button .fred as though it had been clicked on.

.fred flash

can be called somewhere in the Tcl code to cause the button to flash.

We will come across some of these special method when we discuss the widgets in detail. For a comprehensive list of widget methods, refer to entry for the appropriate widget creation command in the Tcl/Tk manual.

We now discuss the widget creation command for each widget type.

A label is a simple widget for displaying a single line of text. An example of creating an instance of a label is

label .l -text "Hello world!"

which simply creates the label named .l with the text ‘Hello world!’ displayed in it. Most widgets that display text can have a variable associated with them through the option -textvariable. When the value of the variable is changed the text changes in the associated label. For example,

label .l -text "Hello world!" -textvariable mytext

creates a text label called .l displaying the initial text ‘Hello world!’ and associated text variable mytext; mytext will start with the value ‘Hello world!’. However, if the following script is executed:

set mytext "Goodbye moon!"

then the text in the label will magically change to ‘Goodbye moon!’.

A message widget is similar to a label widget but for multi-line text. As its name suggests it is mostly used for creating popup message information boxes.

An example of a message widget is

message .msg -text "Your data is incorrect.\n\n \
              Please correct it and try again." \
    -justify center

which will create a message widget displaying the text shown, center justified. The width of the message box can be given through the -width switch. Any lines that exceed the width of the box are wrapped at word boundaries.

Calling the button command creates an instance of a button widget. An example is:

button .mybutton -text "hello" -command {puts "howdie!"}

which creates a button with name .mybutton that will display the text "hello" and will execute the Tcl script puts "howdie!" (that is print howdie! to the terminal) when clicked on.

Checkbuttons are buttons that have a fixed state that is either on or off. Clicking on the button toggles the state. To store the state, a checkbutton is associated with a variable. When the state of the checkbutton changes, so does that of the variable. An example is:

checkbutton .on_or_off -text "I like ice cream" -variable ice

which will create a checkbutton with name .on_or_off displaying the text ‘I like ice cream’ and associated with the variable ice. If the checkbutton is checked, then ice will have the value 1; if not checked, then it will have the value 0. The state of the checkbutton can also be changed by changing the state of the variable. For example, executing

set ice 0

will set the state of .on_or_off to not checked.

Radiobuttons are buttons that are grouped together to select one value among many. Each button has a value, but only one in the button group is active at any one time. In Tcl/Tk this is achieved by creating a series of radiobutton that share an associated variable. Each button has a value. When a radiobutton is clicked on, the variable has that value and all the other buttons in the group are put into the off state. Similarly, setting the value of the variable is reflected in the state of the button group. An example is:

radiobutton .first -value one -text one -variable count
radiobutton .second -value two -text two -variable count
radiobutton .third -value three -text three -variable count

which creates three radiobuttons that are linked through the variable count. If button .second is active, for example, then the other two buttons are in the inactive state and count has the value two. The following code sets the button group to make the button .third active and the rest inactive regardless of the current state:

set count three

If the value of count does not match any of the values of the radiobuttons, then they will all be off. For example executing the script

set count four

will turn all the radiobuttons off.

An entry widget allows input of a one line string. An example of an entry widget:

label .l -text "Enter your name"
entry .e -width 40 -textvariable your_name

would display a label widget named .l showing the string ‘Enter your name’ and an entry widget named .e of width 40 characters. The value of variable your_name will reflect the string in the entry widget: as the entry widget string is updated, so is the value of the variable. Similarly, changing the value of your_name in a Tcl script will change the string displayed in the entry field.

A scale widget is for displaying an adjustable slider. As the slider is moved its value, which is displayed next to the slider, changes. To specify a scale, it must have -from and -to attributes, which is the range of the scale. It can have a -command option, which is set to a script to evaluate when the value of the slider changes.

An example of a scale widget is:

scale .s -from 0 -to 100

which creates a scale widget with name .s that will slide over a range of integers from 0 to 100.

There are several other options that scales can have. For example it is possible to display tick marks along the length of the scale through the -tickinterval attribute, and it is possible to specify both vertically and horizontally displayed scales through the -orient attribute.

A listbox is a widget that displays a list of single line strings. One or more of the strings may be selected through using the mouse. Initializing and manipulating the contents of a listbox is done through invoking methods on the instance of the listbox. As examples, the insert method is used to insert a string into a listbox, delete to delete one, and get to retrieve a particular entry. Also the currently selected list items can be retrieved through the selection command.

Here is an example of a listbox that is filled with entries of the form entry N:

listbox .l
for { set i 0 } { $i<10 } { incr i } {
    .l insert end "entry $i"
}

A listbox may be given a height and/or width attribute, in which case it is likely that not all of the strings in the list are visible at the same time. There are a number of methods for affecting the display of such a listbox.

The see method causes the listbox display to change so that a particular list element is in view. For example,

.l see 5

will make sure that the sixth list item is visible. (List elements are counted from element 0.)

A scrollbar widget is intended to be used with any widget that is likely to be able to display only part of its contents at one time. Examples are listboxes, canvases, text widgets, and frames, amongst others.

A scrollbar widget is displayed as a movable slider between two arrows. Clicking on either arrow moves the slider in the direction of the arrow. The slider can be moved by dragging it with the cursor.

The scollbar and the widget it scrolls are connected through Tcl script calls. A scrollable widgets will have a scrollcommand attribute that is set to a Tcl script to call when the widget changes its view. When the view changes the command is called, and the command is usually set to change the state of its associated scrollbar.

Similarly, the scrollbar will have a command attribute that is another script that is called when an action is performed on the scrollbar, like moving the slider or clicking on one of its arrows. That action will be to update the display of the associated scrollable widget (which redraws itself and then invokes its scrollcommand, which causes the scrollbar to be redrawn).

How this is all done is best shown through an example:

listbox .l -yscrollcommand ".s set" -height 10
scrollbar .s -command ".l yview"
for { set i 0 } { $i < 50 } { incr i } {
    .l insert end "entry $i"
}

creates a listbox named .l and a scrollbar named .s. Fifty strings of the form entry N are inserted into the listbox. The clever part is the way the scrollbar and listbox are linked. The listbox has its -yscrollcommand attribute set to the script ".s set". What happens is that if the view of .l is changed, this script is called with 4 arguments attached: the number of entries in the listbox, the size of the listbox window, the index of the first entry currently visible, and the index of the last entry currently visible. This is exactly enough information for the scrollbar to work out how to redisplay itself. For example, changing the display of the above listbox could result in the following -yscrollcommand script being called:

.s set 50 10 5 15

which says that the listbox contains 50 elements, it can display 10 at one time, the first element displayed has index 5 and the last one on display has index 15. This call invokes the set method of the scrollbar widget .s, which causes it to redraw itself appropriately.

If, instead, the user interacts with the scrollbar, then the scrollbar will invoke its -command script, which in this example is ".l yview". Before invoking the script, the scrollbar widget calculates which element should the first displayed in its associated widget and appends its index to the call. For example, if element with index 20 should be the first to be displayed, then the following call will be made:

.l yview 20

which invokes the yview method of the listbox .l. This causes .l to be updated (which then causes its -yscrollcommand to be called, which updates the scrollbar).

A frame widget does not do anything by itself except reserve an area of the display. Although this does not seem to have much purpose, it is a very important widget. It is a container widget; that is, it is used to group together collections of other widgets into logical groups. For example, a row of buttons may be grouped into a frame, then as the frame is manipulated so will the widgets displayed inside it. A frame widget can also be used to create large areas of color inside another container widget (such as another frame widget or a toplevel widget).

An example of the use of a frame widget as a container:

canvas .c -background red
frame .f
button .b1 -text button1
button .b2 -text button2
button .b3 -text button3
button .b4 -text button4
button .b5 -text button5
pack .b1 .b2 .b3 .b4 .b5 -in .f -side left
pack .c -side top -fill both -expand 1
pack .f -side bottom

which specifies that there are two main widgets a canvas named .c and a frame named .f. There are also 5 buttons, .b1 through .b5. The buttons are displayed inside the frame. Then the canvas is displayed at the top of the main window and the frame is displayed at the bottom. As the frame is displayed at the bottom, then so will the buttons because they are displayed inside the frame.

(The pack command causes the widgets to be handled for display by the packer geometry manager. The -fill and -expand 1 options to pack for .c tell the display manager that if the window is resized, then the canvas is to expand to fill most of the window. You will learn about geometry managers later in the Geometry Managers section.)

A toplevel widget is a new toplevel window. It is a container widget inside which other widgets are displayed. The root toplevel widget has path . — i.e. dot on its own. Subsequent toplevel widgets must have a name that is lower down the path tree just like any other widget.

An example of creating a toplevel widget is:

toplevel .t

All the widgets displayed inside .t must also have .t as the root of their path. For example, to create a button widget for display inside the .t toplevel the following would work:

button .t.b -text "Inside 't'"

(Attributes, such as size and title, of toplevel widgets can be changed through the wm command, which we will not cover in this tutorial. The reader is referred to the Tk manual.)

Yet another kind of container is a menu widget. It contains a list of widgets to display inside itself, as a pulldown menu. A simple entry in a menu widget is a command widget, displayed as an option in the menu widget, which if chosen executes a Tcl command. Other types of widgets allowed inside a menu widget are radiobuttons and checkboxes. A special kind of menu item is a separator that is used to group together menu items within a menu. (It should be noted that the widgets inside a menu widget are special to that menu widget and do not have an independent existence, and so do not have their own Tk name.)

A menu widget is built by first creating an instance of a menu widget (the container) and then invoking the add method to make entries into the menu. An example of a menu widget is as follows:

menu .m
.m add command -label "Open file" -command "open_file"
.m add command -label "Open directory" -command "open_directory"
.m add command -label "Save buffer" -command "save_buffer"
.m add command -label "Save buffer as…" -command "save_buffer_as"
.m add separator
.m add command -label "Make new frame" -command "new_frame"
.m add command -label "Open new display" -command "new_display"
.m add command -label "Delete frame" -command "delete_frame"

which creates a menu widget called .m, which contains eight menu items, the first four of which are commands, then comes a separator widget, then the final three command entries. (Some of you will notice that this menu is a small part of the Files menu from the menubar of the Emacs text editor.)

An example of a checkbox and some radiobutton widget entries:

.m add checkbox -label "Inverse video" -variable inv_vid
.m add radiobutton -label "black" -variable color
.m add radiobutton -label "blue" -variable color
.m add radiobutton -label "red" -variable color

which gives a checkbox displaying ‘Inverse video’, keeping its state in the variable inv_vid, and three radiobuttons linked through the variable color.

Another menu item variant is the cascade variant, which is used to make cascadable menus, i.e. menus that have submenus. An example of a cascade entry is the following:

.m add cascade -label "I cascade" -menu .m.c

which adds a cascade entry to the menu .m that displays the text ‘I cascade’. If the ‘I cascade’ option is chosen from the .m menu, then the menu .m.c will be displayed.

The cascade option is also used to make menubars at the top of an application window. A menu bar is simply a menu each element of which is a cascade entry, (for example). The menubar menu is attached to the application window through a special configuration option for toplevel widgets, the -menu option. Then a menu is defined for each of the cascade entry in the menubar menu.

There are a large number of other variants to menu widgets: menu items can display bitmaps instead of text; menus can be specified as tear-off menus; accelerator keys can be defined for menu items; and so on.

A menubutton widget displays like a button, but when activated a menu pops up. The menu of the menubutton is defined through the menu command and is attached to the menubutton. An example of a menu button:

menubutton .mb -menu .mb.m -text "mymenu"
menu .mb.m
.mb.m add command -label hello
.mb.m add command -label goodbye

which crates a menubutton widget named .mb with attached menu .mb.m and displays the text ‘mymenu’. Menu .mb.m is defined as two command options, one labeled hello and the other labeled goodbye. When the menubutton .mb is clicked on, the menu .mb.m will popup and its options can be chosen.

A canvas widget is a container widget that is used to manage the drawing of complex shapes; for example, squares, circles, ovals, and polygons. (It can also handle bitmaps, text and most of the Tk widgets too.) The shapes may have borders, filled in, be clicked on, moved around, and manipulated.

We will not cover the working of the canvas widget here. It is enough to know that there is a powerful widget in the Tk toolkit that can handle all manner of graphical objects. The interested reader is referred to the Tk manual.

A text widget is another powerful container widget that handles multi-line texts. The textwidget can display texts with varying font styles, sizes, and colors in the same text, and can also handle other Tk widgets embedded in the text.

The text widget is a rich and complicated widget and will not be covered here. The interested reader is referred to the Tk manual.