SCROLLBAR(9)SCROLLBAR(9)NAMEscrollbar - Create and manipulate scrollbar widgets
SYNOPSISscrollbar pathName ?options?
STANDARD OPTIONS-activebackground -borderwidth -orient
-background-jump-relief
WIDGET-SPECIFIC OPTIONS
-activerelief relief
Specifies the relief to use when displaying the element that is
active, if any. Elements other than the active element are
always displayed with a raised relief.
-command command
Specifies the prefix of a Tk 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 Tk com‐
mand is invoked. The actual command consists of this option
followed by additional information as described later. This
option almost always has a value such as .t xview or .t yview,
consisting of the name of a widget and either xview (if the
scrollbar is for horizontal scrolling) or yview (for vertical
scrolling). All scrollable widgets have xview and yview com‐
mands that take exactly the additional arguments appended by the
scrollbar as described in SCROLLING COMMANDS below.
-height dist
Specifies a desired height for the scrollbar. If this option
isn't specified, a suitable default height is chosen.
-width dist
Specifies a desired width for the scrollbar. If this option
isn't specified, a suitable default width is chosen.
DESCRIPTION
The scrollbar command creates a new window (given by the pathName argu‐
ment) and makes it into a scrollbar widget. Additional options,
described above, may be specified on the command line to configure
aspects of the scrollbar such as its colours, 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.
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. It
provides information about what is visible in an associated window that
displays a document of some sort (such as a file being edited or a
drawing). The position and size of the slider indicate which portion
of the document 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 document.
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.
ELEMENTS
A scrollbar displays five elements, which are referred to in the widget
commands for the scrollbar:
arrow1 The top or left arrow in the scrollbar.
trough1 The region between the slider and arrow1.
slider The rectangle that indicates what is visible in the associ‐
ated widget.
trough2 The region between the slider and arrow2.
arrow2 The bottom or right arrow in the scrollbar.
WIDGET COMMAND
The scrollbar command creates a new Tk 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 behaviour of the command. The
following commands are possible for scrollbar widgets:
pathName activate ?element?
Marks the element indicated by element as active, which causes
it to be displayed as specified by the activebackground option.
The only element values understood by this command are arrow1,
slider, or arrow2. If any other value is specified then no ele‐
ment of the scrollbar will be active. If element is not speci‐
fied, the command returns the name of the element that is cur‐
rently active, or an empty string if no element is active.
pathName cget option
Returns the current value of the configuration option given by
option. Option may have any of the values accepted by the
scrollbar command.
pathName configure ?option? ?value option value ...?
Query or modify the configuration options of the widget. If no
option is specified, returns a list of all of the available
options for pathName. 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 delta deltaX deltaY
Returns a real number indicating the fractional change in the
scrollbar setting that corresponds to a given change in slider
position. For example, if the scrollbar is horizontal, the
result indicates how much the scrollbar setting must change to
move the slider deltaX pixels to the right (deltaY is ignored in
this case). If the scrollbar is vertical, the result indicates
how much the scrollbar setting must change to move the slider
deltaY pixels down. The arguments and the result may be zero or
negative.
pathName fraction x y
Returns a real number between 0 and 1 indicating where the point
given by x and y lies in the trough area of the scrollbar. The
value 0 corresponds to the top or left of the trough, the value
1 corresponds to the bottom or right, 0.5 corresponds to the
middle, and so on. X and y must be pixel coordinates relative
to the scrollbar widget. If x and y refer to a point outside
the trough, the closest point in the trough is used.
pathName get
Returns the scrollbar settings in the form of a list whose ele‐
ments are the arguments to the most recent set widget command.
pathName identify x y
Returns the name of the element under the point given by x and y
(such as arrow1), or an empty string if the point does not lie
in any element of the scrollbar. X and y must be pixel coordi‐
nates relative to the scrollbar widget.
pathName set first last
This command is invoked by the scrollbar's associated widget to
tell the scrollbar about the current view in the widget. The
command takes two arguments, each of which is a real fraction
between 0 and 1. The fractions describe the range of the docu‐
ment that is visible in the associated widget. For example, if
first is 0.2 and last is 0.4, it means that the first part of
the document visible in the window is 20% of the way through the
document, and the last visible part is 40% of the way through.
SCROLLING COMMANDS
When the user interacts with the scrollbar, for example by dragging the
slider, the scrollbar notifies the associated widget that it must
change its view. The scrollbar makes the notification by evaluating a
Tk command generated from the scrollbar's -command option. The command
may take any of the following forms. In each case, prefix is the con‐
tents of the -command option, which usually has a form like .t yview
prefix moveto fraction
Fraction is a real number between 0 and 1. The widget should
adjust its view so that the point given by fraction appears at
the beginning of the widget. If fraction is 0 it refers to the
beginning of the document. 1.0 refers to the end of the docu‐
ment, 0.333 refers to a point one-third of the way through the
document, and so on.
prefix scroll number unit
The widget should adjust its view by number units. The units
are defined in whatever way makes sense for the widget, such as
characters or lines in a text widget. Number is either 1, which
means one unit should scroll off the top or left of the window,
or -1, which means that one unit should scroll off the bottom or
right of the window.
prefix scroll number page
The widget should adjust its view by number pages. It is up to
the widget to define the meaning of a page; typically it is
slightly less than what fits in the window, so that there is a
slight overlap between the old and new views. Number is either
1, which means the next page should become visible, or -1, which
means that the previous page should become visible.
BINDINGS
Tk automatically creates bindings for scrollbars that give them the
following default behaviour. If the behaviour is different for verti‐
cal and horizontal scrollbars, the horizontal behaviour is described in
parentheses.
[1] Pressing button 1 over arrow1 causes the view in the associated
widget to shift up (left) by one unit so that the document
appears to move down (right) one unit. If the button is held
down, the action auto-repeats.
[2] Pressing button 1 over trough1 causes the view in the associated
widget to shift up (left) by one screenful so that the document
appears to move down (right) one screenful.
[3] Pressing button 1 over the slider and dragging causes the view
to drag with the slider. If the jump option is true, then the
view doesn't drag along with the slider; it changes only when
the mouse button is released.
[4] Pressing button 1 over trough2 causes the view in the associated
widget to shift down (right) by one screenful so that the docu‐
ment appears to move up (left) one screenful.
[5] Pressing button 1 over arrow2 causes the view in the associated
widget to shift down (right) by one unit so that the document
appears to move up (left) one unit. If the button is held down,
the action auto-repeats.
[6] If button 2 is pressed over the trough or the slider, it sets
the view to correspond to the mouse position; dragging the
mouse with button 2 down causes the view to drag with the mouse.
If button 2 is pressed over one of the arrows, it causes the
same behaviour as pressing button 1.
SEE ALSOoptions(9), types(9)SCROLLBAR(9)
