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]
The purpose of a listbox widget is to display a set of
lines of text. Generally they are intended to allow the
user to select one or more items from a list. All the
lines of text use the same font. If you need something
more like a text editor, see Section 24, “The Text
widget”.
To create a new listbox widget inside a root window or
frame
:
parent
w
= tk.Listbox(parent
,option
, ...)
This constructor returns the new Listbox
widget. Options:
Table 22. Listbox
widget options
activestyle
|
This option specifies the appearance of the active line. It may have any of these values:
|
bg or background
| The background color in the listbox. |
bd or borderwidth
| The width of the border around the listbox. Default is two pixels. For possible values, see Section 5.1, “Dimensions”. |
cursor
| The cursor that appears when the mouse is over the listbox. See Section 5.8, “Cursors”. |
disabledforeground
|
The color of the text
in the listbox when its state is
tk.DISABLED .
|
exportselection
|
By default, the user may select text with the
mouse, and the selected text will be exported to
the clipboard. To disable this behavior, use exportselection=0 .
|
font
| The font used for the text in the listbox. See Section 5.4, “Type fonts”. |
fg or foreground
| The color used for the text in the listbox. See Section 5.3, “Colors”. |
height
| Number of lines (not pixels!) shown in the listbox. Default is 10. |
highlightbackground
| Color of the focus highlight when the widget does not have focus. See Section 53, “Focus: routing keyboard input”. |
highlightcolor
| Color shown in the focus highlight when the widget has the focus. |
highlightthickness
| Thickness of the focus highlight. |
listvariable
|
A
If you call the
To change the entire set of lines in the listbox
at once, call
For example, if listCon.set('ant bee cicada')
This call would return the string listCon.get()
|
relief
|
Selects three-dimensional border shading effects.
The default is tk.SUNKEN . For other
values, see Section 5.6, “Relief styles”.
|
selectbackground
| The background color to use displaying selected text. |
selectborderwidth
|
The width of the border to use around selected
text. The default is that the selected item is
shown in a solid block of color selectbackground ; if you increase the
selectborderwidth , the entries are
moved farther apart and the selected entry shows
tk.RAISED relief (see Section 5.6, “Relief styles”).
|
selectforeground
| The foreground color to use displaying selected text. |
selectmode
|
Determines how many items can be selected, and how
mouse drags affect the selection:
|
state
|
By default, a listbox is in the tk.NORMAL state. To make the listbox unresponsive to mouse
events, set this option to tk.DISABLED .
|
takefocus
| Normally, the focus will tab through listbox widgets. Set this option to 0 to take the widget out of the sequence. See Section 53, “Focus: routing keyboard input”. |
width
| The width of the widget in characters (not pixels!). The width is based on an average character, so some strings of this length in proportional fonts may not fit. The default is 20. |
xscrollcommand
|
If you want to allow the user to scroll the listbox
horizontally, you can link your listbox widget to a
horizontal scrollbar. Set this option to the .set method of the scrollbar. See Section 14.1, “Scrolling a Listbox widget” for more on
scrollable listbox widgets.
|
yscrollcommand
|
If you want to allow the user to scroll the listbox
vertically, you can link your listbox widget to a
vertical scrollbar. Set this option to the .set method of the scrollbar. See Section 14.1, “Scrolling a Listbox widget”.
|
A special set of index forms is used for many of the methods on listbox objects:
If you specify an index as an integer, it refers to the line in the listbox with that index, counting from 0.
Index tk.END
refers to the last line in the
listbox.
Index tk.ACTIVE
refers to the selected
line. If the listbox allows multiple selections, it
refers to the line that was last selected.
An index string of the form '@
refers to the line closest to
coordinate (x
,y
'
,x
) relative
to the widget's upper left corner.
y
Methods on Listbox
objects include:
.activate(index
)
Selects the line specifies by the given
.
index
.bbox(index
)
Returns the bounding box of the line specified by
as
a 4-tuple index
(
, where the upper left
pixel of the box is at xoffset
, yoffset
, width
, height
)(
and the xoffset
, yoffset
)
and width
are
given in pixels. The returned height
value includes only the
part of the line occupied by text.
width
If the line specified by the
argument is not
visible, this method returns index
None
. If
it is partially visible, the returned bounding box
may extend outside the visible area.
.curselection()
Returns a tuple containing the line numbers of the selected element or elements, counting from 0. If nothing is selected, returns an empty tuple.
.delete(first
,
last
=None)
Deletes the lines whose indices are in the range
[
,
first
],
inclusive
(contrary to the usual Python idiom, where deletion
stops short of the last index), counting from 0. If
the second argument is omitted, the single line with
index last
is deleted.
first
.get(first
,
last
=None)
Returns a tuple containing the text of the lines with
indices from
to first
, inclusive.
If the second argument is omitted, returns the text
of the line closest to last
.
first
.index(i
)
If possible, positions the visible part of the
listbox so that the line containing index
is at the top
of the widget.
i
.insert(index
,
*elements
)
Insert one or more new lines into the listbox before
the line specified by
. Use index
tk.END
as the first argument if you want to add
new lines to the end of the listbox.
.itemcget(index
,
option
)
Retrieves one of the option values for a specific
line in the listbox. For option values, see itemconfig
below. If the given option has
not been set for the given line, the returned value
will be an empty string.
.itemconfig(index
,
option
=value
, ...)
Change a configuration option for the line specified
by
.
Option names include:
index
.nearest(y
)
Return the index of the visible line closest to the
y-coordinate y
relative to
the listbox widget.
.scan_dragto(x
,
y
)
See scan_mark
below.
.scan_mark(x
,
y
)
Use this method to implement scanning—fast
steady scrolling—of a listbox. To get this
feature, bind some mouse button event to a handler
that calls scan_mark
with the current
mouse position. Then bind the <Motion>
event to a handler that calls
scan_dragto
with the current mouse
position, and the listbox will be scrolled at a rate
proportional to the distance between the position
recorded by scan_mark
and the current
position.
.see(index
)
Adjust the position of the listbox so that the line
referred to by
is visible.
index
.selection_anchor(index
)
Place the “selection anchor” on the
line selected by the
argument. Once this
anchor has been placed, you can refer to it with the
special index form index
tk.ANCHOR
.
For example, for a listbox named lbox
,
this sequence would select lines 3, 4, and 5:
lbox.selection_anchor(3) lbox.selection_set(tk.ANCHOR,5)
.selection_clear(first
, last
=None)
Unselects all of the lines between indices
and first
, inclusive.
If the second argument is omitted, unselects the line
with index last
.
first
.selection_includes(index
)
Returns 1 if the line with the given
is
selected, else returns 0.
index
.selection_set(first
, last
=None)
Selects all of the lines between indices
and first
, inclusive.
If the second argument is omitted, selects the line
with index last
.
first
.size()
Returns the number of lines in the listbox.
.xview()
To make the listbox horizontally scrollable, set the
command
option of the associated
horizontal scrollbar to this method. See Section 14.1, “Scrolling a Listbox
widget”.
.xview_moveto(fraction
)
Scroll the listbox so that the leftmost
of the
width of its longest line is outside the left side of
the listbox. Fraction is in the range [0,1].
fraction
.xview_scroll(number
, what
)
Scrolls the listbox horizontally. For the
argument,
use either what
tk.UNITS
to scroll by
characters, or tk.PAGES
to scroll by
pages, that is, by the width of the listbox. The
argument tells how many to scroll; negative values
move the text to the right within the listbox,
positive values leftward.
number
.yview()
To make the listbox vertically scrollable, set the
option of the associated vertical scrollbar to this
method. See Section 14.1, “Scrolling a command
Listbox
widget”.
.yview_moveto(fraction
)
Scroll the listbox so that the top
of the
width of its longest line is outside the left side of
the listbox. Fraction is in the range [0,1].
fraction
.yview_scroll(number
, what
)
Scrolls the listbox vertically. For the
argument,
use either what
tk.UNITS
to scroll by lines,
or tk.PAGES
to scroll by pages, that is,
by the height of the listbox. The
argument
tells how many to scroll; negative values move the
text downward inside the listbox, and positive values
move the text up.
number