PracTCL Programming Tips

This month, we inaugurate a bimonthly column for Tcl/Tk programmers. Stephen Uhler will cover some useful but perhaps poorly-known or poorly-understood features of the Tcl language and the Tk windowing toolkit.

For those new to the Tcl language, the name of this column might be confusing: Tcl is pronounced “tickle”. This column will be mainly for those who already know Tcl and Tk and wish to learn how to improve their programming skills. For readers who would like to learn about Tcl and Tck, they are amply covered in John K. Ousterhout's book Tcl and the Tk Toolkit, and Linux Journal printed an introductory article in the December 1994 issue as well.

User interfaces are created in Tk with two steps. First, the user interface elements (called widgets) such as buttons or scollbars are created using the appropriate widget commands. Next, they are arranged on the display with a geometry manager.

Tk comes with several different geometry managers to choose from. The “packer” and “placer” are general purpose geometry managers, whereas the “text” (in tk4.0) and “canvas” widgets can also operate as geometry managers by positioning other widgets inside themselves. Additional geometry managers are available in some of the many extension packages, such as “blt_table” from the BLT extensions by George Howlett.

Traditionally, the “packer” is called upon as the primary geometry manager in Tk applications, because of the powerful constraint based layouts it supports, whereas the “placer” is reserved for beginners who have not yet mastered the packer's intricacies. John Ousterhout, in Tcl and the Tk Toolkit spends 15 pages describing the “packer”, but a single paragraph on “place”, suggesting “the placer is only used for a few special purposes”. In fact, the “placer” is an essential tool for the power user because it affords exact control over widget positioning. I'll demonstrate two example uses of the “placer” that hint at its true power.

How to be a Pane in Tk

For the first example, we'll write a special purpose geometry manager entirely in TCL, using the “placer”, to construct a Motif-like “pane” widget. The “pane” widget divides a window into two halves, or panes, and provides a handle the user can use to dynamically change the relative size of each half.

frame .top
frame .bottom
frame .handle -bd 2 -relief raised -bg red \
    -cursor sb_v_double_arrow

We'll start off by creating two frames, .top and .bottom, and a resize .handle to change the relative size of .top and .bottom. In this example, we'll put our “pane” widget in the top level ., but it could be used almost anywhere.

place .top -relwidth 1 -rely 0 -height -1 \
    -anchor nw
place .bottom -relwidth 1 -rely 1 -height -1 \
    -anchor sw
place .handle -relx 0.9 -width 10 -height 10 \
    -anchor e
. configure -bg black

These 3 widgets are arranged by the “placer” in two steps. First we specify the options to place that won't change. Both .top and .bottom will span the entire width of the window (-relwidth 1), with .top anchored to the top (-rely 0 -anchor nw) and .bottom anchored at the bottom (-rely 1 -anchor sw). The option -height -1 (a new Tk4.0 feature) decreases the height of .top and .bottom by 1 pixel, which leaves a “gap” between the windows, so the root window will show through as a black (.<\!s>configure -bg black) line between the 2 panes. Finally, we'll place .handle near the right edge.

bind . <Configure> {
    set H [winfo height .].0
    set Y0 [winfo rooty .]

To calculate the relative placement of .top and .bottom we'll need to know the position (Y0) and size (H) of the root window, which we'll compute any time either could change, by binding the computation to a <Configure> event. Since the height (H) will be used as a floating point number, we'll tack on a .0.

bind .handle <B1-Motion> {
    adjust [expr (%Y-$Y0)/$H]

When the user moves the handle by dragging it with the mouse, we'll compute the fraction of the way down the root window the mouse is, and call adjust to move the windows accordingly. We need to use %Y, the mouse position in “root” coordinates, because %y is relative to the handle and not the root window, ..

proc adjust {fract} {
    place .top -relheight $fract
    place .handle -rely $fract
    place .bottom -relheight [expr 1.0 - $fract]

The procedure adjust takes a fraction between 0 and 1, changes the the height of top and bottom windows, and updates the position of the handle. Only the place options that may have changed need to be updated. That's all there is to it.

proc stuff {root file} {
    text $root.text -yscrollcommand \
        "$root.scroll set"
    scrollbar $root.scroll -command \
        "$root.text yview"
    pack $root.scroll -side right -fill y
    pack $root.text  -fill both -expand 1
    $root.text insert 0.0 [exec cat $file]

To test it out, we need something to put in the top and bottom halves. We'll create a procedure stuff that displays the contents of a file in a text widget with a scroll bar.

adjust .5
stuff .bottom $env(HOME)/.login
stuff .top $env(HOME)/.cshrc

Now fill each pane, adjust the two halves, and off you go.