Programming Python (56 page)

Example 8-3. PP4E\Gui\Tour\toplevel0.py

import sys
from tkinter import Toplevel, Button, Label
win1 = Toplevel()                  # two independent windows
win2 = Toplevel()                  # but part of same process
Button(win1, text='Spam', command=sys.exit).pack()
Button(win2, text='SPAM', command=sys.exit).pack()
Label(text='Popups').pack()        # on default Tk() root window
win1.mainloop()

A
Toplevel
is roughly like a
Frame
that is split off into its own
window and has additional methods that allow you to deal with top-level
window properties. The
Tk
widget is roughly
like a
Toplevel
, but it is used to
represent the application root window.
Top
level
windows have parents, but
Tk
windows do not—they are the true roots of
the widget hierarchies we build when making tkinter GUIs.

We got a
Tk
root for free in
Example 8-3
because the
Label
had a default parent,
designated by not having a widget in the first argument of its
constructor call:

Label(text='Popups').pack()              # on default Tk() root window

Passing
None
to a widget
constructor’s first argument (or to its
master
keyword argument) has the same
default-parent effect. In other scripts, we’ve made the
Tk
root more explicit by creating it directly,
like this:

root = Tk()
Label(root, text='Popups').pack()        # on explicit Tk() root window
root.mainloop()

In fact, because tkinter GUIs are a hierarchy, by default you
always
get at least one
Tk
root window, whether it is named
explicitly, as here, or not. Though not typical, there may be more than
one
Tk
root if you make them
manually, and a program ends if all its
Tk
windows are closed. The first
Tk
top-level window created—whether explicitly
by your code, or automatically by Python when needed—is used as the
default parent window of widgets and other windows if no parent is
provided.

You should generally use the
Tk
root window to display top-level information of some sort. If you don’t
attach widgets to the root, it may show up as an odd empty window when
you run your script (often because you used the default parent
unintentionally in your code by omitting a widget’s parent and didn’t
pack widgets attached to it). Technically, you can suppress the default
root creation logic and make multiple root windows with the
Tk
widget, as in
Example 8-4
.

import tkinter
from tkinter import Tk, Button
tkinter.NoDefaultRoot()
win1 = Tk()         # two independent root windows
win2 = Tk()
Button(win1, text='Spam', command=win1.destroy).pack()
Button(win2, text='SPAM', command=win2.destroy).pack()
win1.mainloop()

When run, this script displays the two pop-up windows of the
screenshot in
Figure 8-3
only (there is no third root window). But it’s more common to use the
Tk
root as a main window and create
Toplevel
widgets for an application’s
pop-up windows. Notice how this GUI’s windows use a window’s
destroy
method to close just one window,
instead of
sys.exit
to shut down the
entire program; to see how this method really does its work, let’s move
on to window protocols.

Both
Tk
and
Toplevel
widgets
export extra methods and features tailored for their
top-level role, as illustrated in
Example 8-5
.

"""
pop up three new windows, with style
destroy() kills one window, quit() kills all windows and app (ends mainloop);
top-level windows have title, icon, iconify/deiconify and protocol for wm events;
there always is an application root window, whether by default or created as an
explicit Tk() object; all top-level windows are containers, but they are never
packed/gridded; Toplevel is like Frame, but a new window, and can have a menu;
"""
from tkinter import *
root = Tk()                                                     # explicit root
trees = [('The Larch!',         'light blue'),
('The Pine!',          'light green'),
('The Giant Redwood!', 'red')]
for (tree, color) in trees:
win = Toplevel(root)                                        # new window
win.title('Sing...')                                        # set border
win.protocol('WM_DELETE_WINDOW', lambda:None)               # ignore close
win.iconbitmap('py-blue-trans-out.ico')                     # not red Tk
msg = Button(win, text=tree, command=win.destroy)           # kills one win
msg.pack(expand=YES, fill=BOTH)
msg.config(padx=10, pady=10, bd=10, relief=RAISED)
msg.config(bg='black', fg=color, font=('times', 30, 'bold italic'))
root.title('Lumberjack demo')
Label(root, text='Main window', width=30).pack()
Button(root, text='Quit All', command=root.quit).pack()         # kills all app
root.mainloop()

This program adds widgets to the
Tk
root window, immediately pops up three
Top
level
windows with attached buttons, and
uses special top-level protocols. When run, it generates the scene
captured in living black-and-white in
Figure 8-4
(the buttons’ text
shows up blue, green, and red on a color display).

Figure 8-4. Three Toplevel windows with configurations

There are a few operational details worth noticing here, all of
which are more obvious if you run this script on your machine:

In addition, top-level window widgets support other kinds of
protocols that we will utilize later on in this tour:

Most top-level window-manager-related methods can also be named
with a “wm_” at the front; for instance,
state
and
protocol
can also be called
wm_state
and
wm_protocol
.

Notice that the script in
Example 8-3
passes its
Toplevel
constructor calls an explicit parent
widget—the
Tk
root window (that is,
Toplevel(root)
).
Toplevel
s can be associated with a parent just
as other widgets can, even though they are not visually embedded in
their parents. I coded the script this way to avoid what seems like an
odd feature; if coded instead like this:

win = Toplevel()                                    # new window

and if no
Tk
root yet exists,
this call actually generates a default
Tk
root window to serve as the
Toplevel
’s parent, just like any other widget
call without a parent argument. The problem is that this makes the
position of the following line crucial:

root = Tk()                                         # explicit root

If this line shows up above the
Toplevel
calls, it creates the single root
window as expected. But if you move this line below the
Toplevel
calls, tkinter creates a default
Tk
root window that is different from
the one created by the script’s explicit
Tk
call. You wind up with two
Tk
roots just as in
Example 8-4
. Move the
Tk
call below the
Top
level
calls and rerun it to see what I
mean. You’ll get a fourth window that is completely empty! As a rule of
thumb, to avoid such oddities, make your
Tk
root windows early on and make them
explicit.

All of the top-level protocol interfaces are available only on
top-level window widgets, but you can often access them by going through
other widgets’
master
attributes—links to the widget parents. For example, to set the title of
a window in which a frame is contained, say something like this:

theframe.master.title('Spam demo')    # master is the container window

Naturally, you should do so only if you’re sure that the frame
will be used in only one kind of window. General-purpose attachable
components coded as classes, for instance, should leave window property
settings to their client applications.

Top-level widgets have additional tools, some of which we may not
meet in this book. For instance, under Unix window managers, you can
also set the name used on the window’s icon (
iconname
). Because some icon options may be
useful when scripts run on Unix only, see other Tk and tkinter resources
for more details on this topic. For now, the next scheduled stop on this
tour explores one of the more common uses of top-level
windows.