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

Table 33-2. Attributes for the scrollbar widget

activeBackground	Color when the mouse is over the slider or arrows.
activeRelief	Relief of slider and arrows when mouse is over them.
background	The background color (also bg in commands).
borderWidth	Extra space around the edge of the scrollbar.
command	Prefix of the command to invoke when the scrollbar changes. Typically this is a xview or yview operation.
cursor	Cursor to display when mouse is over the widget.
elementBorderWidth	Border width of arrow and slider elements.
highlightBackground	Focus highlight color when widget does not have focus.
highlightColor	Focus highlight color when widget has focus.
highlightThickness	Thickness of focus highlight rectangle.
elementBorderWidth	Width of 3D border on arrows and slider.
jump	If true, dragging the elevator does not scroll dynamically. Instead, the display jumps to the new position.
orient	Orientation: horizontal or vertical.
repeatDelay	Milliseconds before auto-repeat starts. Auto-repeat is used when pressing <Button-1> on the trough or arrows.
repeatInterval	Milliseconds between auto-repeat events.
troughColor	The color of the bar on which the slider sits.
width	Width of the narrow dimension of the scrollbar.

Programming Scrollbars

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.

Table 33-3. Operations on the scrollbar widget

$w activate ?element?	Queries or sets the active element, which can be arrow1, arrow2, or slider.
$w cget option	Returns the value of the configuration option.
$w configure ...	Queries or modifies the widget configuration.
$w delta dx dy	Returns the change in the first argument to set required to move the scrollbar slider by dx or dy.
$w fraction x y	Returns a number between 0 and 1 that indicates the relative location of the point in the trough.
$s get	Returns first and last from the set operation.
$w identify x y	Returns arrow1, trough1, slider, trough2, or arrow2, to indicate what is under the point.
$w set first last	Sets 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.