PracTCL Programming Tips

Putting Widgets in their Place

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.

by Stephen Uhler

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

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

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

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

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

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]
}

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

What a Drag

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

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]]
}

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]
}

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
}

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.

Stephen Uhler is a researcher at Sun Microsystems Laboratories, where he works with John Ousterhout improving Tcl and Tk. Stephen is the author of the MGR window system and of PhoneStation, a TCL-based personal telephony environment. He may be reached via email at Stephen.Uhler@Eng.Sun.COM.