PracTCL Programming Tips

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.

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.

For our second example, we’ll use the placer to permit a user to interactively “drag and drop” a widget within a window. When the user selects a widget, by clicking on it with the mouse, we’ll lift it up so it hovers over the window, and casts a shadow as we drag it around. Releasing the mouse drops the widget in its new location.

label .label -text "drag me"\
  -borderwidth 3 -relief raised
frame .shadow -bg black
lower .shadow .label
place .label -x 50 -y 50
set hover 5

We’ll start by creating a widget to drag, .label, and its shadow .shadow. We’ll use lower to make sure the shadow is always “below” the widget, and we’ll start .label in an arbitrary location, 50 pixels from the top left corner of .. The variable hover controls how high we’ll lift the widget above its window as we drag it.

bind .label <1> {
    array set data [place info .label]
    place .label -x [expr $data(-x) - $hover]\
                 -y [expr $data(-y) - $hover]
    place .shadow -in .label -x $hover -y $hover \
                  -relx 0 -rely 0 -relwidth 1 \
                  -relheight 1 -width -2 -height -2 \
                  -bordermode outside
    set Rootx [expr %X - [winfo x %W]]
    set Rooty [expr %Y - [winfo y %W]]
}

When we first click on .label, we need to lift it up, add its shadow, and compute where it is relative to the root window so we can figure out how to move it. The array set command (new in tcl7.4), takes name-value pairs and creates an array from them. Fortunately, the place info command happens to report the current place options in the form of name-value pairs, permitting us to access and modify individual place options using array accesses. The first place command simply moves the widget up and to the left $hover pixels as we first press the mouse. I think the second place command, which positions the shadow, uses every available place option!

The -in option, which would more accurately be described as “relative to”, causes all locations specified in .shadow to be relative to .label, instead of ., which would be the default. The -x and -y options, when added to -relx and -rely, position the shadow where .label was before we $hovered it. The -relwidth and -relheight options make .shadow the same size as .label, and then the -width and -height options make the shadow a little smaller, so it will appear farther away. Finally, the -bordermode option instructs the placer to include the border of .label when computing the sizes for -relwidth and -relheight.

Finally, we compute the location of the mouse cursor, in pixels, relative to the top left corner of the root window (Rootx, Rooty), so it will be easier to figure out how to track .label with the mouse.

bind .label <B1-Motion> {
    place .label -x [expr %X - $Rootx] \
                 -y [expr %Y - $Rooty]
}

As the mouse moves, we reposition the widget to follow along. Because we “placed” the shadow relative to the widget (using the -in option), it tags along all by itself.

bind .label <ButtonRelease-1> {
    array set data [place info .label]
    place .label -x [expr $data(-x) + $hover] \
                 -y [expr $data(-y) + $hover]
    place forget .shadow
}

When we release the mouse button, the same array set trick as before is used to “drop” the widget back on the window, then remove the shadow.

As you can hopefully see from these two simple examples, the “placer” can be a powerful tool for the dynamic placement of widgets in Tk.