This is an unofficial mirror of Tkinter reference documentation (based on Python 2.7 and Tk 8.5) created by the late John Shipman.
It was last updated in 2013 and is unmaintained. [More info]
A number of widgets, such as listboxes and canvases, can act like sliding windows into a larger virtual area. You can connect scrollbar widgets to them to give the user a way to slide the view around relative to the contents. Here's a screen shot of an entry widget with an associated scrollbar widget:
Scrollbars can be horizontal, like the one shown above, or vertical. A widget that has two scrollable dimensions, such as a canvas or listbox, can have both a horizontal and a vertical scrollbar.
The slider, or scroll thumb, is the raised-looking rectangle that shows the current scroll position.
The two triangular arrowheads at
each end are used for moving the position by small
steps. The one on the left or top is called
arrow1, and the one on the right or bottom is
The trough is the sunken-looking
area visible behind the arrowheads and slider. The
trough is divided into two areas named
trough1 (above or to the left of the slider)
trough2 (below or to the right of
The slider's size and position, relative to the length of the entire widget, show the size and position of the view relative to its total size. For example, if a vertical scrollbar is associated with a listbox, and its slider extends from 50% to 75% of the height of the scrollbar, that means that the visible part of the listbox shows that portion of the overall list starting at the halfway mark and ending at the three-quarter mark.
In a horizontal scrollbar, clicking B1 (button 1) on the left arrowhead moves the view by a small amount to the left. Clicking B1 on the right arrowhead moves the view by that amount to the right. For a vertical scrollbar, clicking the upward- and downward-pointing arrowheads moves the view small amounts up or down. Refer to the discussion of the associated widget to find out the exact amount that these actions move the view.
The user can drag the slider with B1 or B2 (the middle button) to move the view.
For a horizontal scrollbar, clicking B1 in the trough to the left of the slider moves the view left by a page, and clicking B1 in the trough to the right of the slider moves the view a page to the right. For a vertical scrollbar, the corresponding actions move the view a page up or down.
Clicking B2 anywhere along the trough moves the slider so that its left or top end is at the mouse, or as close to it as possible.
The normalized position of the scrollbar refers to a number in the closed interval [0.0, 1.0] that defines the slider's position. For vertical scrollbars, position 0.0 is at the top and 1.0 at the bottom; for horizontal scrollbars, position 0.0 is at the left end and 1.0 at the right.
To create a new
Scrollbar widget as the
child of a root window or frame
The constructor returns the new
widget. Options for scrollbars include:
Scrollbar widget options
||The color of the slider and arrowheads when the mouse is over them. See Section 5.3, “Colors”.|
By default, the slider is shown with the |
||The color of the slider and arrowheads when the mouse is not over them.|
||The width of the 3-d borders around the entire perimeter of the trough, and also the width of the 3-d effects on the arrowheads and slider. Default is no border around the trough, and a two-pixel border around the arrowheads and slider. For possible values, see Section 5.1, “Dimensions”.|
A procedure to be called whenever the scrollbar is
moved. For a discussion of the calling sequence,
see Section 22.1, “The |
||The cursor that appears when the mouse is over the scrollbar. See Section 5.8, “Cursors”.|
The width of the borders around the arrowheads and
slider. The default is |
||The color of the focus highlight when the scrollbar does not have focus. See Section 53, “Focus: routing keyboard input”.|
||The color of the focus highlight when the scrollbar has the focus.|
The thickness of the focus highlight. Default is
This option controls what happens when a user drags
the slider. Normally (|
Controls the relief
style of the widget; the default style is
This option controls how long button 1 has to be
held down in the trough before the slider starts
moving in that direction repeatedly. Default is
This option controls how often slider movement will
repeat when button 1 is held down in the trough.
Default is |
Normally, you can tab the focus through a scrollbar
widget; see Section 53, “Focus: routing keyboard input”. Set |
||The color of the trough.|
||Width of the scrollbar (its y dimension if horizontal, and its x dimension if vertical). Default is 16. For possible values, see Section 5.1, “Dimensions”.|
Methods on scrollbar objects include:
If no argument is provided, this method returns one
of the strings
'', depending on where the mouse is. For
example, the method returns
if the mouse is on the slider. The empty string is
returned if the mouse is not currently on any of these
To highlight one of the controls (using its
activerelief relief style and its
activebackground color), call this method
and pass a string identifying the control you want to
highlight, one of
Given a mouse movement of
( in pixels, this method returns the
value that should be added to the current slider position
to achieve that same movement. The value must be in the
closed interval [-1.0, 1.0].
Given a pixel location
(, this method returns the corresponding
normalized slider position in the interval [0.0, 1.0]
that is closest to that location.
Returns two numbers (
) describing the
current position of the slider. The
value gives the
position of the left or top edge of the slider, for
horizontal and vertical scrollbars respectively; the
gives the position of the right or bottom edge. Each
value is in the interval [0.0, 1.0] where 0.0 is the
leftmost or top position and 1.0 is the rightmost or
bottom position. For example, if the slider extends
from halfway to three-quarters of the way along the
trough, you might get back the tuple (0.5,0.75).
This method returns a string indicating which (if
any) of the components of the scrollbar are under the
The return value is one of
the empty string
'' if that location
is not on any of the scrollbar components.
To connect a scrollbar to another widget
yscrollcommand to the scrollbar's
.set method. The arguments have the same
meaning as the values returned by the
.get() method. Please note that moving the
scrollbar's slider does not move
the corresponding widget.