2.6 scrollbar

scrollbar \- Create and manipulate scrollbar widgets

Synopsis

scrollbar pathName ?options?

Standard Options

activeForeground       cursor           relief               
background             foreground       repeatDelay          
borderWidth            orient           repeatInterval       

See options, for more information.

Arguments for Scrollbar

:command

Name="command" Class="Command"

Specifies the prefix of a Tcl command to invoke to change the view in the widget associated with the scrollbar. When a user requests a view change by manipulating the scrollbar, a Tcl command is invoked. The actual command consists of this option followed by a space and a number. The number indicates the logical unit that should appear at the top of the associated window.

:width

Name="width" Class="Width"

Specifies the desired narrow dimension of the scrollbar window, not including 3-D border, if any. For vertical scrollbars this will be the width and for horizontal scrollbars this will be the height. The value may have any of the forms acceptable to Tk_GetPixels.

Description

The scrollbar command creates a new window (given by the pathName argument) and makes it into a scrollbar widget. Additional options, described above, may be specified on the command line or in the option database to configure aspects of the scrollbar such as its colors, orientation, and relief. The scrollbar command returns its pathName argument. At the time this command is invoked, there must not exist a window named pathName, but pathName’s parent must exist.

A scrollbar is a widget that displays two arrows, one at each end of the scrollbar, and a slider in the middle portion of the scrollbar. A scrollbar is used to provide information about what is visible in an associated window that displays an object of some sort (such as a file being edited or a drawing). The position and size of the slider indicate which portion of the object is visible in the associated window. For example, if the slider in a vertical scrollbar covers the top third of the area between the two arrows, it means that the associated window displays the top third of its object.

Scrollbars can be used to adjust the view in the associated window by clicking or dragging with the mouse. See the BINDINGS section below for details.

A Scrollbar Widget’s Arguments

The scrollbar command creates a new Tcl command whose name is pathName. This command may be used to invoke various operations on the widget. It has the following general form:

pathName option ?arg arg ...?

Option and the args determine the exact behavior of the command. The following commands are possible for scrollbar widgets:

pathName :configure ?option? ?value option value ...?

Query or modify the configuration options of the widget. If no option is specified, returns a list describing all of the available options for pathName (see Tk_ConfigureInfo for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option:value pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. Option may have any of the values accepted by the scrollbar command.

pathName :get

Returns a Tcl list containing four decimal values, which are the current totalUnits, widnowUnits, firstUnit, and lastUnit values for the scrollbar. These are the values from the most recent set widget command on the scrollbar.

pathName :set totalUnits windowUnits firstUnit lastUnit

This command is invoked to give the scrollbar information about the widget associated with the scrollbar. TotalUnits is an integer value giving the total size of the object being displayed in the associated widget. The meaning of one unit depends on the associated widget; for example, in a text editor widget units might correspond to lines of text. WindowUnits indicates the total number of units that can fit in the associated window at one time. FirstUnit and lastUnit give the indices of the first and last units currently visible in the associated window (zero corresponds to the first unit of the object). This command should be invoked by the associated widget whenever its object or window changes size and whenever it changes the view in its window.

Bindings

The description below assumes a vertically-oriented scrollbar. For a horizontally-oriented scrollbar replace the words “up”, “down”, “top”, and “bottom” with “left”, “right”, “left”, and “right”, respectively

A scrollbar widget is divided into five distinct areas. From top to bottom, they are: the top arrow, the top gap (the empty space between the arrow and the slider), the slider, the bottom gap, and the bottom arrow. Pressing mouse button 1 in each area has a different effect:

top arrow

Causes the view in the associated window to shift up by one unit (i.e. the object appears to move down one unit in its window). If the button is held down the action will auto-repeat.

top gap

Causes the view in the associated window to shift up by one less than the number of units in the window (i.e. the portion of the object that used to appear at the very top of the window will now appear at the very bottom). If the button is held down the action will auto-repeat.

slider

Pressing button 1 in this area has no immediate effect except to cause the slider to appear sunken rather than raised. However, if the mouse is moved with the button down then the slider will be dragged, adjusting the view as the mouse is moved.

bottom gap

Causes the view in the associated window to shift down by one less than the number of units in the window (i.e. the portion of the object that used to appear at the very bottom of the window will now appear at the very top). If the button is held down the action will auto-repeat.

bottom arrow

Causes the view in the associated window to shift down by one unit (i.e. the object appears to move up one unit in its window). If the button is held down the action will auto-repeat.

Note: none of the actions described above has an immediate impact on the position of the slider in the scrollbar. It simply invokes the command specified in the command option to notify the associated widget that a change in view is desired. If the view is actually changed then the associated widget must invoke the scrollbar’s set widget command to change what is displayed in the scrollbar.

Keywords

scrollbar, widget