Section 17.3. Commonly Used Simple Widgets

17.3. Commonly Used Simple Widgets

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

17.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 also use 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.

flash	b.flash( ) Draws the user's attention to button b by redrawing b a few times, alternatively in normal and active states.
invoke	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.

17.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. 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 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 gets checked or unchecked (either by the user clicking on it or by your code calling c's methods deselect, select, and 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.

deselect	c.deselect( ) Removes c's checkmark, like c.cget('variable').set(0).
flash	c.flash( ) Draws the user's attention to checkbox c by redrawing c a few times, alternately in normal and active states.
invoke	c.invoke( ) Calls without arguments the callable object that is c's command option, just like c.cget('command')( ).
select	c.select( ) Shows c's checkmark, like c.cget('variable').set(1).
toggle	c.toggle( ) Toggles the state of c's checkmark, as if the user had clicked on c.

17.3.3. Entry

Class EnTRy implements a text entry field (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 that allow fine-grained control of widget operation and contents, but, in most GUI programs, 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 displays a line of text and lets the user copy it to the clipboard. To display more than one line of text, use class Text, covered in "The Text Widget" on page 426. 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 

17.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 and paste into an email or other document. Use an instance e of class EnTRy, with option state=DISABLED to avoid changes to e, as discussed in the previous section.

17.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: one in modes SINGLE and BROWSE; more in modes MULTIPLE and EXTENDED. selectmode also defines which user actions cause items to be selected or unselected. BROWSE is the default; it differs from SINGLE 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 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 range of items.

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

curselection	L.curselection( ) Returns a sequence of zero or more indices, from 0 upward, of selected items. Depending on the underlying release of Tk, curselection may return string representations of the int indices rather than ints. To remove this uncertainty, use: indices = [ int(x) for x in L.curselection( ) ] [L.get(x) for x in L.curselection( )] is always the list of the zero or more text items selected, no matter what form of indices curselection returns. So, if you care about selected text items rather than selected indices, the uncertainty is not an issue.
select_clear	L.select_clear(i,j=None) Deselects item i (all items from i to j, included, if j is not None).
select_set	L.select_set(i,j=None) Selects item i (all items from i to j if j is not None). select_set does not automatically deselect other items, even if L's selection mode is SINGLE or BROWSE.

17.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. Call Radiobutton with text=somestring to label the button with text, or image=imageobject to label the button with an image. Optionally, use 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, and only if, they have the same variable and different values; selecting an instance changes the variable's value, which automatically unchecks whichever other instance was previously checked. 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 spread a group of Radiobutton instances in disparate locations.

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

deselect	r.deselect( ) Unchecks r and sets the associated variable object to an empty string, like r.cget('variable').set('').
flash	c.flash( ) Draws the user's attention to r by redrawing r a few times, alternately in normal and active states.
invoke	c.invoke( ) Calls without arguments the callable object that is r's command option, just like r.cget('command')( ).
select	r.select( ) Checks r and sets the associated variable object to r's value, like r.cget('variable').set(r.cget('value')).

17.3.7. Scale

Class Scale implements a widget that lets the user input a value by sliding a cursor along a line. Scale sports 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.

get	s.get( ) Returns the current position of s's cursor, normally on a scale of 0 to 100.
set	s.set(p) Sets the current position of s's cursor, normally on a scale of 0 to 100.

17.3.8. Scrollbar

Class Scrollbar implements a widget similar to class Scale, which is used to scroll another widget (most often a Listbox, covered in "Listbox" on page 417; a Text, covered in "The Text Widget" on page 426 [see also "The ScrolledText Module" on page 426]; or a Canvas, covered in "The Canvas Widget" on page 436) 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 a configuration option on each of s and L. For this purpose, widgets 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 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 refer to each other, we cannot set their respective options on construction in both cases; for uniformity, we call their config methods to set the options later. In this example, we need to bind names to the widgets to be able to call pack and config methods of the widgets, use the widgets' bound methods, and populate the Listbox. L=Tkinter.Listbox( ).pack( ) would not bind L to the Listbox but rather to the result of pack (i.e., None). Code this in two statements (as in the previous example):

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