16.2 Widget Fundamentals
The
Tkinter module supplies many kinds of widgets, and
most of them have several things in common. All widgets are instances
of classes that inherit from class Widget. Class
Widget itself is abstract;
that is, you never instantiate Widget itself. You
only instantiate concrete subclasses corresponding to specific kinds
of widgets. Class Widget's
functionality is common to all the widgets you
instantiate.
To instantiate any kind of widget, call the widget's
class. The first argument is the parent window of the widget, also
known as the widget's master.
If you omit this positional argument, the widget's
master is the application's main window. All other
arguments are in named form,
option=value.
You can also set or change options on an existing widget
w by calling
w.config(option=value).
You can get an option of w by calling
w.cget('option'),
which returns the option's value. Each widget
w is a mapping, so you can also get an
option as
w['option']
and set or change it with
w['option']=value.
16.2.1 Common Widget Options
Many widgets
accept some common options. Some options affect a
widget's colors, others affect lengths (normally in
pixels), and there are various other kinds. This section details the
most commonly used options.
16.2.1.1 Color options
Tkinter represents colors with
strings. The string can be a color name, such as
'red' or 'orange', or it may be
of the form
'#RRGGBB',
where each of R,
G, and B is a
hexadecimal digit, to represent a color by the values of red, green,
and blue components on a scale of 0 to
255. Don't worry; if your screen
can't display millions of different colors, as
implied by this scheme; Tkinter maps any requested color to the
closest color that your screen can display. The common color options
are:
- activebackground
-
Background color for the widget when the widget is
active, meaning that the mouse is over the
widget and clicking on it makes something happen
- activeforeground
-
Foreground color for the widget when the widget is active
- background (also bg)
-
Background color for the widget
- disabledforeground
-
Foreground color for the widget when the widget is
disabled, meaning that clicking on the widget is
ignored
- foreground (also fg)
-
Foreground color for the widget
- highlightbackground
-
Background color of the highlight region when the widget has focus
- highlightcolor
-
Foreground color of the highlight region when the widget has focus
- selectbackground
-
Background color for the selected items of the widget, for widgets
that have selectable items, such as Listbox
- selectforeground
-
Foreground color for the selected items of the widget
16.2.1.2 Length options
Tkinter normally expresses a length as
an integer number of pixels; other units of measure are possible, but
rarely used. The common length options are:
- borderwidth
-
Width of the border (if any), giving a 3D look to the widget
- highlightthickness
-
Width of the highlight rectangle when the widget has focus (when
0, the widget does not draw a highlight rectangle)
- padx, pady
-
Extra space the widget requests from its geometry manager beyond the
minimum the widget needs to display its contents, in the
x and y directions
- selectborderwidth
-
Width of the 3D border (if any) around selected items of the widget
- wraplength
-
Maximum line length for widgets that perform word wrapping (when less
than or equal to 0, no wrapping: the widget breaks
lines of text only at '\n')
16.2.1.3 Options expressing numbers of characters
Some options indicate a widget's requested geometry
not in pixels, but rather as a number of characters, using average
width or height of the widget's fonts:
- height
-
Desired height of the widget; must be greater than or equal to
1
- underline
-
Index of the character to underline in the widget's
text (0 is the first character,
1 the second one, and so on). The underlined
character also determines what shortcut key reaches or activates the
widget.
- width
-
Desired width of the widget (when less than or equal to
0, desired width is just enough to hold the
widget's current contents)
16.2.1.4 Other common options
Other options accepted by many kinds of widgets are a mixed bag,
dealing with both behavior and presentation issues.
- anchor
-
Where the information in the widget is displayed; must be
N, NE, E,
SE, S, SW,
W, NW, or
CENTER (all except CENTER are
compass directions)
- command
-
Callable without arguments; executes when the user clicks on the
widget (only for widgets Button,
Checkbutton, and Radiobutton)
- font
-
Font for the text in this widget (see
Section 16.6.6 later in this chapter)
- image
-
An image to display in the widget instead of text; the value must be
a Tkinter image object (see
Section 16.2.4 later in this
chapter)
- justify
-
How lines are justified when a widget shows more than a line of text;
must be LEFT, CENTER, or
RIGHT
- relief
-
The 3D effect that indicates how the interior of the widget appears
relative to the exterior; must be RAISED,
SUNKEN, FLAT,
RIDGE, SOLID, or
GROOVE
- state
-
Widget look and behavior on mouse and keyboard clicks; must be
NORMAL, ACTIVE, or
DISABLED
- takefocus
-
If true, the widget accepts focus when the user navigates among
widgets by pressing the Tab or Shift-Tab keys
- text
-
The text string displayed by the widget
- textvariable
-
The Tkinter variable object associated with the
widget (see Section 16.2.3 later in this chapter)
16.2.2 Common Widget Methods
A widget w supplies many methods. Besides
event-related methods, mentioned in
Section 16.9 later in this chapter,
commonly used widget methods are the following.
Returns the value configured in
w for option.
w
.config( ), without
arguments, returns a dictionary where each possible option of
w is mapped to a tuple that describes it.
Called with one or more named arguments, config
sets those options in w's
configuration.
Sets focus to w, so that all keyboard
events for the application are sent to w.
w.grab_set( )
w.grab_release( )
|
|
grab_set ensures that all of the
application's events are sent to
w until a corresponding call to
grab_release.
Enters a Tkinter event loop. Event
loops may be nested; each call to mainloop enters
one further-nested level of the event loop.
Quits a Tkinter event loop. When event
loops are nested; each call to quit exits one
nested level of the event loop.
Handles all pending events. Never call this
while handling an event!
Handles those pending events that would normally be handled only when
the event loop is idle (such as layout-manager updates and widget
redrawing) but does not perform any callbacks. You can safely call
this method at any time.
v must be a Tkinter
variable object (covered in the next section).
wait_variable returns only when the value of
v changes. Meanwhile, other parts of the
application remain active.
w1 must be a widget.
wait_visibility returns only when
w1 becomes visible. Meanwhile, other parts
of the application remain active.
w1 must be a widget.
wait_window returns only when
w1 is destroyed. Meanwhile, other parts of
the application remain active.
Returns w's height in
pixels.
Returns w's width in
pixels.
w supplies many other methods whose names
start with winfo_, but the two above are the most
often called, typically after calling
w.update_idletasks.
They let you ascertain a widget's dimensions after
the user has resized a window, causing the layout manager to
rearrange the widgets' geometry.
16.2.3 Tkinter Variable Objects
The Tkinter module
supplies classes whose instances represent variables. Each class
deals with a specific data type: DoubleVar for
float, IntVar for
int, StringVar for
str. You can instantiate any of these classes
without arguments to obtain an instance x,
also known in Tkinter as a
variable object. Then,
x.set(datum)
sets x's value to the
given value, and x.get(
) returns x's
current value.
You can pass x as the
textvariable or variable
configuration option for a widget. Once you do this, the
widget's text changes to track any change to
x's value, and
x's value, in turn,
tracks changes to the widget (for some kinds of widgets). Further, a
single Tkinter variable can control more than one
widget. Tkinter variables let you control widget
contents more transparently, and sometimes more conveniently, than
explicitly querying and setting widget properties. The following
example shows how to use a StringVar to connect an
Entry widget and a Label widget
automatically:
import Tkinter
root = Tkinter.Tk( )
tv = Tkinter.StringVar( )
Tkinter.Label(textvariable=tv).pack( )
Tkinter.Entry(textvariable=tv).pack( )
tv.set('Welcome!')
Tkinter.Button(text="Exit", command=root.quit).pack( )
Tkinter.mainloop( )
print tv.get( )
As you edit the Entry, you'll see
the Label change automatically. This example
instantiates the Tkinter main window explicitly,
binds it to name root, and then sets as
the Button's command the bound
method root.quit, which
quits Tkinter's main loop but
does not terminate the Python application. Thus, the example ends
with a print statement, to show on standard output
the final value of variable object tv.
16.2.4 Tkinter Images
The Tkinter class
PhotoImage supports Graphical Interchange Format
(GIF) and Portable PixMap (PPM) images. You instantiate class
PhotoImage with a keyword argument
file=path to load the
image's data from the image file at the given
path and get an instance
x.
You can set x as the
image configuration option for one or more
widgets. When you do this, the widget displays the image rather than
text. If you need image processing functionality and support for many
image formats (including JPEG, PNG, and TIFF), use PIL, the Python
Imaging Library (http://www.pythonware.com/products/pil/),
designed to work with Tkinter. I do not cover PIL
further in this book.
Tkinter also supplies class
BitmapImage, whose instances are usable wherever
instances of PhotoImage are.
BitmapImage supports some file formats known as
bitmaps. I do not cover BitmapImage further in
this book.
Being set as the image configuration option of a
widget does not suffice to keep instances of
PhotoImage and BitmapImage
alive. Be sure to hold such instances in a Python container object,
typically a list or dictionary, to ensure that the instances are not
garbage-collected. The following example shows how to display GIF
images:
import os
import Tkinter
root = Tkinter.Tk( )
L = Tkinter.Listbox(selectmode=Tkinter.SINGLE)
gifsdict = { }
dirpath = 'imgs'
for gifname in os.listdir(dirpath):
if not gifname[0].isdigit( ): continue
gifpath = os.path.join(dirpath, gifname)
gif = Tkinter.PhotoImage(file=gifpath)
gifsdict[gifname] = gif
L.insert(Tkinter.END, gifname)
L.pack( )
img = Tkinter.Label( )
img.pack( )
def list_entry_clicked(*ignore):
imgname = L.get(L.curselection( )[0])
img.config(image=gifsdict[imgname])
L.bind('<ButtonRelease-1>', list_entry_clicked)
root.mainloop( )
Assuming you have in some directory ('imgs' in the
example) several GIF files whose filenames start with digits, the
example loads the images into memory, shows the filenames in a
Listbox instance, and shows in a
Label instance the GIF whose filename you click
on. Note that for simplicity, the example does not give the
Listbox widget a Scrollbar
(we'll see how to equip a Listbox
with a Scrollbar shortly).
|