16.3 Commonly Used Simple Widgets

The Tkinter module provides a number of simple widgets that cover most needs of basic GUI applications. This section documents the Button, Checkbutton, Entry, Label, Listbox, Radiobutton, Scale, and Scrollbar widgets.

16.3.1 Button

Class Button implements a pushbutton, which the user clicks to execute an action. Instantiate Button with option text=somestring to let the button show text, or image=imageobject to let the button show an image. You normally use option command=callable to have callable execute without arguments when the user clicks the button. callable can be a function, a bound method of an object, an instance of a class with a _ _call_ _ method, or a lambda.

Besides methods common to all widgets, an instance b of class Button supplies two button-specific methods.

b.flash(  )

Draws the user's attention to button b by redrawing b a few times, alternatively in normal and active states.

b.invoke(  )

Calls without arguments the callable object that is b's command option, just like b.cget('command')( ). This can be handy when, within some other action, you want the program to act just as if the button had been clicked.

16.3.2 Checkbutton

Class Checkbutton implements a checkbox, which is a little box, optionally displaying a checkmark, that the user clicks to toggle on or off. You normally instantiate Checkbutton with exactly one of the two options text=somestring, to label the box with text, or image=imageobject, to label the box with an image. Optionally, use option command=callable to have callable execute without arguments when the user clicks the box. callable can be a function, a bound method of an object, an instance of a class with a _ _call_ _ method, or a lambda.

An instance c of Checkbutton must be associated with a Tkinter variable object v, using configuration option variable=v of c. Normally, v is an instance of IntVar, and v's value is 0 when the box is unchecked, and 1 when the box is checked. The value of v changes when the box is checked or unchecked (either by the user clicking on it, or by your code calling c's methods deselect, select, toggle). Vice versa, when the value of v changes, c shows or hides the checkmark as appropriate.

Besides methods common to all widgets, an instance c of class Checkbutton supplies five checkbox-specific methods.

c.deselect(  )

Removes c's checkmark, like c.cget('variable').set(0).

c.flash(  )

Draws the user's attention to checkbox c by redrawing c a few times, alternately in normal and active states.

c.invoke(  )

Calls without arguments the callable object that is c's command option, just like c.cget('command')( ).

c.select(  )

Shows c's checkmark, like c.cget('variable').set(1).

c.deselect(  )

Toggles the state of c's checkmark, as if the user had clicked on c.

16.3.3 Entry

Class Entry implements a text entry field (i.e., a widget in which the user can input and edit a line of text). An instance e of Entry supplies several methods and configuration options allowing fine-grained control of widget operation and contents, but in most GUI p rograms you can get by with just three Entry-specific idioms:

e.delete(0, END)           # clear the widget's contents
e.insert(END, somestring)  # append somestring to the widget's contents
somestring = e.get(  )     # get the widget's contents

An Entry instance with state=DISABLED is a good way to display a line of text while letting the user copy it to the clipboard. To display more than one line of text, use an instance of class Text, covered later in this chapter. DISABLED stops your program, as well as the user, from altering e's contents. To perform any alteration, temporarily set state=NORMAL:

e.config(state=NORMAL)     # allow alteration of e's contents
# call e.delete and/or e.insert as needed
e.config(state=DISABLED)   # make e's contents inalterable again

16.3.4 Label

Class Label implements a widget that just displays text or an image without interacting with user input. Instantiate Label either with option text=somestring to let the widget display text, or image=imageobject to let the widget display an image.

An instance L of class Label does not let the user copy text from L to the clipboard. L is therefore not the right widget to use when you show text that the user may want to copy, say in order to paste it into an email or some other document. Instead, use an instance e of class Entry, with option state=DISABLED to avoid alteration of e's contents, as discussed in the previous section.

16.3.5 Listbox

Class Listbox displays textual items and lets the user select one or more items. To set the text items for an instance L of class Listbox, in most GUI programs you can get by with just two Listbox-specific idioms:

L.delete(0, END)           # clear the listbox's items
L.insert(END, somestring)  # add somestring to the listbox's items

To get the text item at index idx, call L.get(idx). To get a list of all text items between indices idx1 and idx2, call L.get(idx1,idx2). To get the list of all text items, call L.get(0,END).

Option selectmode defines the selection mode of a Listbox instance L. The selection mode indicates how many items the user can select at once: only one in modes SINGLE and BROWSE, more than one in modes MULTIPLE and EXTENDED. Secondarily, selectmode also defines the details of what user actions cause items to be selected or unselected. BROWSE mode is the default; it differs from SINGLE mode in that the user may change the one selected item by moving up and down while holding down the left mouse button. In MULTIPLE mode, each click on a list item selects or deselects the item without affecting the selection state of other items. In EXTENDED mode, a normal click on a list item selects that item and deselects all other items; however, clicking while holding down a Ctrl key selects an item without deselecting others, and clicking while holding down a Shift key selects a contiguous range of items.

An instance L of class Listbox supplies three selection-related methods.

L.curselection(  )

Returns a sequence of zero or more indices, from 0 upwards, of selected items. Depending on the underlying release of Tk, curselection may return string representations of the integer indices, rather than the integers themselves. To remove this uncertainty, you can use:

indices = [ int(x) for x in L.curselection(  ) ]

However, [L.get(x) for x in L.curselection( )] is always the list of the zero or more text items that are selected, no matter what form of indices curselection returns. Therefore, if you're interested in selected text items rather than selected indices, the uncertainty may not be an issue.

L.select_clear(i,j=None)

Deselects the i item (all items from the i to the j, if j is not None).

L.select_set(i,j=None)

Selects the i item (all items from the i to the j, if j is not None). select_set does not automatically deselect other items, even if L's selection mode is SINGLE or BROWSE.

16.3.6 Radiobutton

Class Radiobutton implements a little box that is optionally checked. The user clicks the radiobutton to toggle it on or off. Radiobuttons come in groups: checking a radiobutton automatically unchecks all other radiobuttons of the same group. Instantiate Radiobutton with option text=somestring to label the button with text, or image=imageobject to label the button with an image. Optionally, use option command=callable to have callable execute without arguments when the user clicks the radiobutton. callable can be a function, a bound method of an object, an instance of a class with a _ _call_ _ method, or a lambda.

An instance r of Radiobutton must be associated with a Tkinter variable object v, using configuration option variable=v of r, and with a designated value X, using option value=X of r. Most often, v is an instance of IntVar. The value of v changes to X when r is checked, either by the user clicking on r or by your code calling r.select( ). Vice versa, when the value of v changes, r is checked if, and only if, v.get( )= =X. Several instances of Radiobutton form a group if they have the same variable and different values; selecting an instance changes the variable's value, and therefore automatically unchecks whichever other instance was previously checked.

Note that Radiobutton instances form a group if, and only if, they share the same value for the variable option. There is no special container to use to make Radiobutton instances into a group, nor is it even necessary for the Radiobutton instances to be children of the same widget. However, it would be confusing to the user if you dispersed a group of Radiobutton instances among several disparate locations.

Besides methods common to all widgets, an instance r of class Radiobutton supplies four radiobutton-specific methods.

r.deselect(  )

Unchecks r and sets the associated variable object to an empty string, like r.cget('variable').set('').

c.flash(  )

Draws the user's attention to r by redrawing r a few times, alternately in normal and active states.

c.invoke(  )

Calls without arguments the callable object that is r's command option, just like r.cget('command')( ).

r.select(  )

Checks r and sets the associated variable object to r's value, like r.cget('variable').set(r.cget('value')).

16.3.7 Scale

Class Scale implements a widget in which the user can input a value by sliding a cursor along a line. Scale supports configuration options to control the widget's looks and the value's range, but in most GUI programs the only option you specify is orient=HORIZONTAL when you want the line to be horizontal (by default, the line is vertical).

Besides methods common to all widgets, an instance s of class Scale supplies two scale-specific methods.

s.get(  )

Returns the current position of s's cursor, normally on a scale of 0 to 100.

s.set(p)

Sets the current position of s's cursor, normally on a scale of 0 to 100.

16.3.8 Scrollbar

Class Scrollbar implements a widget similar to class Scale, almost always used to scroll another widget (most often a Listbox, covered earlier, or a Text or Canvas, covered later) rather than to let the user input a value.

A Scrollbar instance s is connected to the widget that s controls (e.g., a Listbox instance L) through one configuration option on each of s and L. Exactly for this purpose, the widgets most often associated with a scrollbar supply a method named yview and a configuration option named yscrollcommand for vertical scrolling. (For horizontal scrolling, widgets such as Text, Canvas, and Entry supply a method named xview and a configuration option named xscrollcommand.) For vertical scrolling, use s's option command=L.yview so that user actions on s call L's bound method yview to control L's scrolling, and also use L's option yscrollcommand=s.set so that changes to L's scrolling, in turn, adjust the way s displays by calling s's bound method set. The following example uses a Scrollbar to control vertical scrolling of a Listbox:

import Tkinter
s = Tkinter.Scrollbar(  )
L = Tkinter.Listbox(  )
s.pack(side=Tkinter.RIGHT, fill=Tkinter.Y)
L.pack(side=Tkinter.LEFT, fill=Tkinter.Y)
s.config(command=L.yview)
L.config(yscrollcommand=s.set)
for i in range(30): L.insert(Tkinter.END, str(i)*3)
Tkinter.mainloop(  )

Since s and L need to refer to each other, we cannot set their respective options on construction in both cases, so for uniformity we call their config methods to set the options later for both. Clearly, in this example we do need to bind names to the widgets in order to be able to call pack and config methods of the widgets, use the widgets' bound methods, and populate the Listbox. Note that L=Tkinter.Listbox( ).pack( ) does not bind L to the Listbox, but rather to the result of method pack (i.e., None). Therefore, code this in two statements instead (as shown in the previous example):

L = Tkinter.Listbox(  )
L.pack(  )