The scrollbar set operation takes two floating point values between zero and one, first and last, that indicate the relative position of the top and bottom (or left and right) of the widget's display. The scrollable widget adds these values when they use their yscrollcommand or xscrollcommand. For example, the text widget would issue the following command to indicate that the first quarter of the widget is displayed:

.yscroll set 0.0 0.25

If the two values are 0.0 and 1.0, it means that the widget's contents are fully visible, and a scrollbar is not necessary. You can monitor the protocol by using a Tcl wrapper, Scroll_Set, instead of the set operation directly. Scroll_Set waits for the scrollbar to be necessary before mapping it with a geometry manager command. It is not safe to unmap the scrollbar because that can change the size of the widget and create the need for a scrollbar. That leads to an infinite loop.

proc Scroll_Set {scrollbar geoCmd offset size} {
   if {$offset != 0.0 || $size != 1.0} {
      eval $geoCmd     ;# Make sure it is visible
   }
   $scrollbar set $offset $size
}

Scroll_Set takes a geometry management command as an argument, which it uses to make the scrollbar visible. Example 33-3 uses Scroll_Set with a listbox. Note that it does not grid the scrollbars directly. Instead, it lets Scroll_Set do the geometry command the first time it is necessary.

Example 33-3. Listbox with optional scrollbars

proc Scrolled_Listbox { f args } {
   frame $f
   listbox $f.list 
      -xscrollcommand [list Scroll_Set $f.xscroll 
         [list grid $f.xscroll -row 1 -column 0 -sticky we]] 
      -yscrollcommand [list Scroll_Set $f.yscroll 
         [list grid $f.yscroll -row 0 -column 1 -sticky ns]]
   eval {$f.list configure} $args
   scrollbar $f.xscroll -orient horizontal 
      -command [list $f.list xview]
   scrollbar $f.yscroll -orient vertical 
      -command [list $f.list yview]
   grid $f.list -sticky news
   grid rowconfigure $f 0 -weight 1
   grid columnconfigure $f 0 -weight 1
   return $f.list
}

set l [Scrolled_Listbox .f -listvariable fonts]
pack .f -expand yes -fill both
set fonts [lsort -dictionary [font families]]

Scrolled_Listbox takes optional parameters for the listbox. It uses eval to configure the listbox with these arguments. The style of using eval shown here is explained in Example 10-3 on page 136. Example 46-4 on page 686 associates two listboxes with one scrollbar.

The xview and yview operations are designed to be called from scrollbars, and they work the same for all scrollable widgets. You can use them to scroll the widgets for any reason, not just when the scrollbar is used. The following examples use a text widget named .text for illustration.

The xview and yview operations return the current first and last values that would be passed to a scrollbar set command:

.text yview
=> 0.2 0.55

When the user clicks on the arrows at either end of the scrollbar, the scrollbar adds scroll num units to its command, where num is positive to scroll down, and negative to scroll up. Scrolling up one line is indicated with this command:

.text yview scroll -1 units

When the user clicks above or below the elevator of the scrollbar, the scrollbar adds scroll num pages to its command. Scrolling down one page is indicated with this command:

.text yview scroll 1 pages

You can position a widget so that the top (or left) edge is at a particular offset from the beginning of the widget's contents. The offset is expressed as a floating point value between zero and one. To view the beginning of the contents:

.text yview moveto 0.0

If the offset is 1.0, the last part of the widget content's is displayed. The Tk widgets always keep the end of the widget contents at the bottom (or right) edge of the widget, unless the widget is larger than necessary to display all the contents. You can exploit this with the one-line entry widget to view the end of long strings:

.entry xview moveto 1.0

Table 33-1 lists the default bindings for scrollbars on UNIX. Button 1 and button 2 of the mouse have the same bindings. You must direct focus to a scrollbar explicitly for the key bindings like <Up> and <Down> to take effect.

Table 33-2 lists the scrollbar attributes. The table uses the resource name for the attribute, which has capitals at internal word boundaries. In Tcl commands, the attributes are specified with a dash and all lowercase.

There is no length attribute for a scrollbar. Instead, a scrollbar is designed to be packed next to another widget with a fill option that lets the scrollbar display grow to the right size. Only the relief of the active element can be set. The background color is used for the slider, the arrows, and the border. The slider and arrows are displayed in the activeBackground color when the mouse is over them. The trough is always displayed in the troughColor.

The scrollbar operations are primarily used by the default bindings. Table 33-3 lists the operations supported by the scrollbar. In the table, $w is a scrollbar widget.