Previous section   Next section

Practical Programming in Tcl & Tk, Third Edition
By Brent B. Welch

Table of Contents
Chapter 30.  Scrollbars

The Scrollbar Widget

Tk 8.0 uses native scrollbar widgets on Macintosh and Windows. While the use of scrollbars with other widgets is identical on all platforms, the interpretation of the attributes and the details of the bindings vary across platforms. This section describes the Tk scrollbar on UNIX. The default bindings and attributes are fine on all platforms, so the differences should not be important.

The scrollbar is made up of five components: arrow1, trough1, slider, trough2, and arrow2. The arrows are on either end, with arrow1 being the arrow to the left for horizontal scrollbars, or the arrow on top for vertical scrollbars. The slider represents the relative position of the information displayed in the associated widget, and the size of the slider represents the relative amount of the information displayed. The two trough regions are the areas between the slider and the arrows. If the slider covers all of the trough area, you can see all the information in the associated widget.

Scrollbar Bindings

Table 30-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 30-1. Bindings for the scrollbar widget.
<Button-1> <Button-2>Clicking on the arrows scrolls by one unit. Clicking on the trough moves by one screenful.
<B1-Motion> <B2-Motion>Dragging the slider scrolls dynamically.
<Control-Button-1> <Control-Button-2>Clicking on the trough or arrow scrolls all the way to the beginning (end) of the widget.
<Up> <Down>Scrolls up (down) by one unit.
<Control-Up> <Control-Down>Scrolls up (down) by one screenful.
<Left> <Right>Scrolls left (right) by one unit.
<Control-Left> <Control-Right>Scrolls left (right) by one screenful.
<Prior> <Next>Scrolls back (forward) by one screenful.
<Home>Scrolls all the way to the left (top).
<End>Scrolls all the way to the right (bottom).

Scrollbar Attributes

Table 30-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.

Table 30-2. Attributes for the scrollbar widget.
activeBackgroundColor when the mouse is over the slider or arrows.
activeReliefRelief of slider and arrows when mouse is over them.
backgroundThe background color (also bg in commands).
borderWidthExtra space around the edge of the scrollbar.
commandPrefix of the command to invoke when the scrollbar changes. Typically this is a xview or yview operation.
cursorCursor to display when mouse is over the widget.
elementBorderWidthBorder width of arrow and slider elements.
highlightBackgroundFocus highlight color when widget does not have focus.
highlightColorFocus highlight color when widget has focus.
highlightThicknessThickness of focus highlight rectangle.
elementBorderWidthWidth of 3D border on arrows and slider.
jumpIf true, dragging the elevator does not scroll dynamically. Instead, the display jumps to the new position.
orientOrientation: horizontal or vertical.
repeatDelayMilliseconds before auto-repeat starts. Auto-repeat is used when pressing <Button-1> on the trough or arrows.
repeatIntervalMilliseconds between auto-repeat events.
troughColorThe color of the bar on which the slider sits.
widthWidth of the narrow dimension of the scrollbar.

Programming Scrollbars

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

Table 30-3. Operations on the scrollbar widget.
$w activate ?element?Queries or sets the active element, which can be arrow1, arrow2, or slider.
$w cget optionReturns the value of the configuration option.
$w configure ...Queries or modifies the widget configuration.
$w delta dx dyReturns the change in the first argument to set required to move the scrollbar slider by dx or dy.
$w fraction x yReturns a number between 0 and 1 that indicates the relative location of the point in the trough.
$s getReturns first and last from the set operation.
$w identify x yReturns arrow1, trough1, slider, trough2, or arrow2, to indicate what is under the point.
$w set first lastSets the scrollbar parameters. first is the relative position of the top (left) of the display. last is the relative position of the bottom (right) of the display.

      Previous section   Next section