Because GUIs are a major area, I want to say a few more words about this part of the book before we get started. To make them easier to absorb, GUI programming topics are split over the next five chapters:

Because GUIs are actually cross-domain tools, other GUI examples will also show up throughout the remainder of this book. For example, we’ll later see complete email GUIs and calculators, as well as a basic FTP client GUI; additional examples such as tree viewers and table browsers are available externally in the book examples package. Chapter 11 gives a list of forward pointers to other tkinter examples in this text.

After we explore GUIs, in Part IV we’ll also learn how to build basic user interfaces within a web browser using HTML and Python scripts that run on a server—a very different model with advantages and tradeoffs all its own that are important to understand. Newer technologies such as the RIAs described later in this chapter build on the web browser model to offer even more interface choices.

For now, though, our focus here is on more traditional GUIs—known as “desktop” applications to some, and as “standalone” GUIs to others. As we’ll see when we meet FTP and email client GUIs in the Internet part of this book, though, such programs often connect to a network to do their work as well.

One other point I’d like to make right away: most GUIs are dynamic and interactive interfaces, and the best I can do here is show static screenshots representing selected states in the interactions such programs implement. This really won’t do justice to most examples. If you are not working along with the examples already, I encourage you to run the GUI examples in this and later chapters on your own.

On Windows, the standard Python install comes with tkinter support built in, so all these examples should work immediately. Mac OS X comes bundled with a tkinter-aware Python as well. For other systems, Pythons with tkinter support are either provided with the system itself or are readily available (see the top-level README-PP4E.txt file in the book examples distribution for more details). Getting tkinter to work on your computer is worth whatever extra install details you may need to absorb, though; experimenting with these programs is a great way to learn about both GUI programming and Python itself.

Also see the description of book example portability in general in this book’s Preface. Although Python and tkinter are both largely platform neutral, you may run into some minor platform-specific issues if you try to run this book’s examples on platforms other than that used to develop this book. Mac OS X, for example, might pose subtle differences in some of the examples’ operation. Be sure to watch this book’s website for pointers and possible future patches for using the examples on other platforms.

Perhaps more to the point, though, there are pragmatic reasons that the Python world still gravitates to tkinter as its de facto standard portable GUI toolkit. Among them, tkinter’s accessibility, portability, availability, documentation, and extensions have made it the most widely used Python GUI solution for many years running:

Naturally, other factors such as documentation and extensions are important when using a GUI toolkit, too; let’s take a quick look at the story tkinter has to tell on these fronts as well.

This book explores tkinter fundamentals and most widgets tools, and it should be enough to get started with substantial GUI development in Python. On the other hand, it is not an exhaustive reference to the tkinter library or extensions to it. Happily, at least one book dedicated to using tkinter in Python is now commercially available as I write this paragraph, and others are on the way (search the Web for details). Besides books, you can also find tkinter documentation online; a complete set of tkinter manuals is currently maintained on the Web at http://www.pythonware.com/library.

In addition, because the underlying Tk toolkit used by tkinter is also a de facto standard in the open source scripting community at large, other documentation sources apply. For instance, because Tk has also been adopted by the Tcl and Perl programming languages, Tk-oriented books and documentation written for both of these are directly applicable to Python/tkinter as well (albeit, with some syntactic mapping).

Frankly, I learned tkinter by studying Tcl/Tk texts and references—just replace Tcl strings with Python objects and you have additional reference libraries at your disposal (see Table 7-2, the Tk-to-tkinter conversion guide, at the end of this chapter for help reading Tk documentation). For instance, the book Tcl/Tk Pocket Reference (O’Reilly) can serve as a nice supplement to the tkinter tutorial material in this part of the book. Moreover, since Tk concepts are familiar to a large body of programmers, Tk support is also readily available on the Net.

After you’ve learned the basics, examples can help, too. You can find tkinter demo programs, besides those you’ll study in this book, at various locations around the Web. Python itself includes a set of demo programs in the Demos kinter subdirectory of its source distribution package. The IDLE development GUI mentioned in the next section makes for an interesting code read as well.

Because tkinter is so widely used, programmers also have access to precoded Python extensions designed to work with or augment it. Some of these may not yet be available for Python 3.X as I write this but are expected to be soon. For instance:

If you plan to do any commercial-grade GUI development with tkinter, you’ll probably want to explore extensions such as Pmw, PIL, Tix, and ttk after learning tkinter basics in this text. They can save development time and add pizzazz to your GUIs. See the Python-related websites mentioned earlier for up-to-date details and links.

From a more nuts-and-bolts perspective, tkinter is an integration system that implies a somewhat unique program structure. We’ll see what this means in terms of code in a moment, but here is a brief introduction to some of the terms and concepts at the core of Python GUI programming.

The usual first example for GUI systems is to show how to display a “Hello World” message in a window. As coded in Example 7-1, it’s just four lines in Python.

from tkinter import Label                               # get a widget object
widget = Label(None, text='Hello GUI world!')           # make one
widget.pack()                                           # arrange it
widget.mainloop()                                       # start event loop

This is a complete Python tkinter GUI program. When this script is run, we get a simple window with a label in the middle; it looks like Figure 7-1 on my Windows 7 laptop (I stretched some windows in this book horizontally to reveal their window titles; your platform’s window system may vary).

Figure 7-1. “Hello World” (gui1) on Windows

This isn’t much to write home about yet, but notice that this is a completely functional, independent window on the computer’s display. It can be maximized to take up the entire screen, minimized to hide it in the system bar, and resized. Click on the window’s “X” box in the top right to kill the window and exit the program.

The script that builds this window is also fully portable. Run this script on your machine to see how it renders. When this same file is run on Linux it produces a similar window, but it behaves according to the underlying Linux window manager. Even on the same operating system, the same Python code might yields a different look-and-feel for different window systems (for instance, under KDE and Gnome on Linux). The same script file would look different still when run on Macintosh and other Unix-like window managers. On all platforms, though, its basic functional behavior will be the same.

The gui1 script is a trivial example, but it illustrates steps common to most tkinter programs. This Python code does the following:

The mainloop method called last puts the label on the screen and enters a tkinter wait state, which watches for user-generated GUI events. Within the mainloop function, tkinter internally monitors things such as the keyboard and mouse to detect user-generated events. In fact, the tkinter mainloop function is similar in spirit to the following pseudo-Python code:

def mainloop():
    while the main window has not been closed:
        if an event has occurred:
            run the associated event handler function

Because of this model, the mainloop call in Example 7-1 never returns to our script while the GUI is displayed on-screen.^[25] When we write larger scripts, the only way we can get anything done after calling mainloop is to register callback handlers to respond to events.

This is called event-driven programming, and it is perhaps one of the most unusual aspects of GUIs. GUI programs take the form of a set of event handlers that share saved information rather than of a single main control flow. We’ll see how this looks in terms of real code in later examples.

Note that for code in a script file, you really need to do steps 3 and 4 in the preceding list to open this script’s GUI. To display a GUI’s window at all, you need to call mainloop; to display widgets within the window, they must be packed (or otherwise arranged) so that the tkinter geometry manager knows about them. In fact, if you call either mainloop or pack without calling the other, your window won’t show up as expected: a mainloop without a pack shows an empty window, and a pack without a mainloop in a script shows nothing since the script never enters an event wait state (try it). The mainloop call is sometimes optional when you’re coding interactively, but you shouldn’t rely on this in general.

Since the concepts illustrated by this simple script are at the core of most tkinter programs, let’s take a deeper look at some of them before moving on.

When widgets are constructed in tkinter, we can specify how they should be configured. The gui1 script passes two arguments to the Label class constructor:

As we’ll see, the parent-widget argument is the hook we use to build up complex GUIs as widget trees. tkinter works on a “what-you-build-is-what-you-get” principle—we construct widget object trees as models of what we want to see on the screen, and then ask the tree to display itself by calling mainloop.

The pack widget method called by the gui1 script invokes the packer geometry manager, one of three ways to control how widgets are arranged in a window. tkinter geometry managers simply arrange one or more widgets within a container (sometimes called a parent or master). Both top-level windows and frames (a special kind of widget we’ll meet later) can serve as containers, and containers may be nested inside other containers to build hierarchical displays.

The packer geometry manager uses constraint option settings to automatically position widgets in a window. Scripts supply higher-level instructions (e.g., “attach this widget to the top of its container, and stretch it to fill its space vertically”), not absolute pixel coordinates. Because such constraints are so abstract, the packer provides a powerful and easy-to-use layout system. In fact, you don’t even have to specify constraints. If you don’t pass any arguments to pack, you get default packing, which attaches the widget to the top side of its container.

We’ll visit the packer repeatedly in this chapter and use it in many of the examples in this book. In Chapter 9, we will also meet an alternative grid geometry manager—a layout system that arranges widgets within a container in tabular form (i.e., by rows and columns) and works well for input forms. A third alternative, called the placer geometry manager system, is described in Tk documentation but not in this book; it’s less popular than the pack and grid managers and can be difficult to use for larger GUIs coded by hand.

Like all Python code, the module in Example 7-1 can be started in a number of ways—by running it as a top-level program file:

C:...PP4EGuiIntro> python gui1.py

by importing it from a Python session or another module file:

>>> import gui1

by running it as a Unix executable if we add the special #! line at the top:

% gui1.py &

and in any other way Python programs can be launched on your platform. For instance, the script can also be run by clicking on the file’s name in a Windows file explorer, and its code can be typed interactively at the >>> prompt.^[26] It can even be run from a C program by calling the appropriate embedding API function (see Chapter 20 for details on C integration).

In other words, there are really no special rules to follow when launching GUI Python code. The tkinter interface (and Tk itself) is linked into the Python interpreter. When a Python program calls GUI functions, they’re simply passed to the embedded GUI system behind the scenes. That makes it easy to write command-line tools that pop up windows; they are run the same way as the purely text-based scripts we studied in the prior part of this book.

...same as gui1.py...

Top-level windows, such as the one built by all of the coding variants we have seen thus far, can normally be resized by the user; simply drag out the window with your mouse. Figure 7-2 shows how our window looks when it is expanded.

Figure 7-2. Expanding gui1

This isn’t very good—the label stays attached to the top of the parent window instead of staying in the middle on expansion—but it’s easy to improve on this with a pair of pack options, demonstrated in Example 7-6.

from tkinter import *
Label(text='Hello GUI world!').pack(expand=YES, fill=BOTH)
mainloop()

When widgets are packed, we can specify whether a widget should expand to take up all available space, and if so, how it should stretch to fill that space. By default, widgets are not expanded when their parent is. But in this script, the names YES and BOTH (imported from the tkinter module) specify that the label should grow along with its parent, the main window. It does so in Figure 7-3.

Figure 7-3. gui1e with widget resizing

Technically, the packer geometry manager assigns a size to each widget in a display based on what it contains (text string lengths, etc.). By default, a widget can occupy only its allocated space and is no bigger than its assigned size. The expand and fill options let us be more specific about such things:

Combinations of these two options produce different layout and resizing effects, some of which become meaningful only when there are multiple widgets in a window. For example, using expand without fill centers the widget in the expanded space, and the fill option can specify vertical stretching only (fill=Y), horizontal stretching only (fill=X), or both (fill=BOTH). By providing these constraints and attachment sides for all widgets in a GUI, along with packing order, we can control the layout in fairly precise terms. In later chapters, we’ll find that the grid geometry manager uses a different resizing protocol entirely, but it provides similar control when needed.

All of this can be confusing the first time you hear it, and we’ll return to this later. But if you’re not sure what an expand and fill combination will do, simply try it out—this is Python, after all. For now, remember that the combination of expand=YES and fill=BOTH is perhaps the most common setting; it means “expand my space allocation to occupy all available space on my side, and stretch me to fill the expanded space in both directions.” For our “Hello World” example, the net result is that the label grows as the window is expanded, and so is always centered.

So far, we’ve been telling tkinter what to display on our label by passing its text as a keyword argument in label constructor calls. It turns out that there are two other ways to specify widget configuration options. In Example 7-7, the text option of the label is set after it is constructed, by assigning to the widget’s text key. Widget objects overload (intercept) index operations such that options are also available as mapping keys, much like a dictionary.

from tkinter import *
widget = Label()
widget['text'] = 'Hello GUI world!'
widget.pack(side=TOP)
mainloop()

More commonly, widget options can be set after construction by calling the widget config method, as in Example 7-8.

from tkinter import *
root = Tk()
widget = Label(root)
widget.config(text='Hello GUI world!')
widget.pack(side=TOP, expand=YES, fill=BOTH)
root.title('gui1g.py')
root.mainloop()

The config method (which can also be called by its synonym, configure) can be called at any time after construction to change the appearance of a widget on the fly. For instance, we could call this label’s config method again later in the script to change the text that it displays; watch for such dynamic reconfigurations in later examples in this part of the book.

Notice that this version also calls a root.title method; this call sets the label that appears at the top of the window, as pictured in Figure 7-4. In general terms, top-level windows like the Tk root here export window-manager interfaces—i.e., things that have to do with the border around the window, not its contents.

Figure 7-4. gui1g with expansion and a window title

Just for fun, this version also centers the label upon resizes by setting the expand and fill pack options. In fact, this version makes just about everything explicit and is more representative of how labels are often coded in full-blown interfaces; their parents, expansion policies, and attachments are usually spelled out rather than defaulted.

Finally, if you are a minimalist and you’re nostalgic for old Python coding styles, you can also program this “Hello World” example as in Example 7-9.

from tkinter import *
Label(None, {'text': 'Hello GUI world!', Pack: {'side': 'top'}}).mainloop()

This makes the window in just two lines, albeit arguably gruesome ones! This scheme relies on an old coding style that was widely used until Python 1.3, which passed configuration options in a dictionary instead of keyword arguments.^[28] In this scheme, packer options can be sent as values of the key Pack (a class in the tkinter module).

The dictionary call scheme still works and you may see it in old Python code, but it’s probably best to not do this in code you type. Use keywords to pass options, and use explicit pack method calls in your tkinter scripts instead. In fact, the only reason I didn’t cut this example completely is that dictionaries can still be useful if you want to compute and pass a set of options dynamically.

On the other hand, the func(*pargs, **kargs) syntax now also allows you to pass an explicit dictionary of keyword arguments in its third argument slot:

options = {'text': 'Hello GUI world!'}
layout  = {'side': 'top'}
Label(None, **options).pack(**layout)        # keyword must be strings

Even in dynamic scenarios where widget options are determined at run time, there’s no compelling reason to ever use the pre-1.3 tkinter dictionary call form.

In gui1c.py (shown in Example 7-4), I started packing labels without assigning them to names. This works, and it is an entirely valid coding style, but because it tends to confuse beginners at first glance, I need to explain why it works in more detail here.

In tkinter, Python class objects correspond to real objects displayed on a screen; we make the Python object to make a screen object, and we call the Python object’s methods to configure that screen object. Because of this correspondence, the lifetime of the Python object must generally correspond to the lifetime of the corresponding object on the screen.

Luckily, Python scripts don’t usually have to care about managing object lifetimes. In fact, they do not normally need to maintain a reference to widget objects created along the way at all unless they plan to reconfigure those objects later. For instance, it’s common in tkinter programming to pack a widget immediately after creating it if no further reference to the widget is required:

Label(text='hi').pack()                        # OK

This expression is evaluated left to right, as usual. It creates a new label and then immediately calls the new object’s pack method to arrange it in the display. Notice, though, that the Python Label object is temporary in this expression; because it is not assigned to a name, it would normally be garbage collected (destroyed and reclaimed) by Python immediately after running its pack method.

However, because tkinter emits Tk calls when objects are constructed, the label will be drawn on the display as expected, even though we haven’t held onto the corresponding Python object in our script. In fact, tkinter internally cross-links widget objects into a long-lived tree used to represent the display, so the Label object made during this statement actually is retained, even if not by our code.^[29]

In other words, your scripts don’t generally have to care about widget object lifetimes, and it’s OK to make widgets and pack them immediately in the same statement without maintaining a reference to them explicitly in your code.

But that does not mean that it’s OK to say something like this:

widget = Label(text='hi').pack()               # wrong!
...use widget...

This statement almost seems like it should assign a newly packed label to widget, but it does not do this. In fact, it’s really a notorious tkinter beginner’s mistake. The widget pack method packs the widget but does not return the widget thus packed. Really, pack returns the Python object None; after such a statement, widget will be a reference to None, and any further widget operations through that name will fail. For instance, the following fails, too, for the same reason:

Label(text='hi').pack().mainloop()             # wrong!

Since pack returns None, asking for its mainloop attribute generates an exception (as it should). If you really want to both pack a widget and retain a reference to it, say this instead:

widget = Label(text='hi')                      # OK too
widget.pack()
...use widget...

This form is a bit more verbose but is less tricky than packing a widget in the same statement that creates it, and it allows you to hold onto the widget for later processing. It’s probably more common in realistic scripts that perform more complex widget configuration and layouts.

On the other hand, scripts that compose layouts often add some widgets once and for all when they are created and never need to reconfigure them later; assigning to long-lived names in such programs is pointless and unnecessary.

Even with a GUI this simple, there are many ways to lay out its appearance with tkinter’s constraint-based pack geometry manager. For example, to center the button in its window, add an expand=YES option to the button’s pack method call in Example 7-11. The line of changed code looks like this:

Button(root, text='press', command=root.quit).pack(side=LEFT, expand=YES)

This makes the packer allocate all available space to the button but does not stretch the button to fill that space. The result is the window captured in Figure 7-7.

Figure 7-7. pack(side=LEFT, expand=YES)

If you want the button to be given all available space and to stretch to fill all of its assigned space horizontally, add expand=YES and fill=X keyword arguments to the pack call. This will create the scene in Figure 7-8.

Figure 7-8. pack(side=LEFT, expand=YES, fill=X)

This makes the button fill the whole window initially (its allocation is expanded, and it is stretched to fill that allocation). It also makes the button grow as the parent window is resized. As shown in Figure 7-9, the button in this window does expand when its parent expands, but only along the X horizontal axis.

Figure 7-9. Resizing with expand=YES, fill=X

To make the button grow in both directions, specify both expand=YES and fill=BOTH in the pack call; now resizing the window makes the button grow in general, as shown in Figure 7-10. In fact, for more fun, maximize this window to fill the entire screen; you’ll get one very big tkinter button indeed.

Figure 7-10. Resizing with expand=YES, fill=BOTH

In more complex displays, such a button will expand only if all of the widgets it is contained by are set to expand too. Here, the button’s only parent is the Tk root window of the program, so parent expandability isn’t yet an issue; in later examples, we’ll need to make enclosing Frame widgets expandable too. We will revisit the packer geometry manager when we meet multiple-widget displays that use such devices later in this tutorial, and again when we study the alternative grid call in Chapter 9.

Recall that the Python lambda expression generates a new, unnamed function object when run. If we need extra data passed in to the handler function, we can register lambda expressions to defer the call to the real handler function, and specify the extra data it needs.

Later in this part of the book, we’ll see how this can be more useful, but to illustrate the basic idea, Example 7-13 shows what Example 7-12 looks like when recoded to use a lambda instead of a def.

import sys
from tkinter import *                        # lambda generates a function

widget = Button(None,                        # but contains just an expression
             text='Hello event world',
             command=(lambda: print('Hello lambda world') or sys.exit()) )

widget.pack()
widget.mainloop()

This code is a bit tricky because lambdas can contain only an expression; to emulate the original script, this version uses an or operator to force two expressions to be run ( print works as the first, because it’s a function call in Python 3.X—we don’t need to resort to using sys.stdout directly).

More typically, lambdas are used to provide an indirection layer that passes along extra data to a callback handler (I omit pack and mainloop calls in the following snippets for simplicity):

def handler(A, B):              # would normally be called with no args
    ...use A and B...

X = 42
Button(text='ni', command=(lambda: handler(X, 'spam')))      # lambda adds arguments

Although tkinter invokes command callbacks with no arguments, such a lambda can be used to provide an indirect anonymous function that wraps the real handler call and passes along information that existed when the GUI was first constructed. The call to the real handler is, in effect, deferred, so we can add the extra arguments it requires. Here, the value of global variable X and string 'spam' will be passed to arguments A and B, even though tkinter itself runs callbacks with no arguments. The net effect is that the lambda serves to map a no-argument function call to one with arguments supplied by the lambda.

If lambda syntax confuses you, remember that a lambda expression such as the one in the preceding code can usually be coded as a simple def statement instead, nested or otherwise. In the following code, the second function does exactly the same work as the prior lambda—by referencing it in the button creation call, it effectively defers invocation of the actual callback handler so that extra arguments can be passed:

def handler(A, B):              # would normally be called with no args
    ...use A and B...

X = 42
def func():                     # indirection layer to add arguments
    handler(X, 'spam')

Button(text='ni', command=func)

To make the need for deferrals more obvious, notice what happens if you code a handler call in the button creation call itself without a lambda or other intermediate function—the callback runs immediately when the button is created, not when it is later clicked. That’s why we need to wrap the call in an intermediate function to defer its invocation:

def handler(name):
    print(name)

Button(command=handler('spam'))              # BAD: runs the callback now!

Using either a lambda or a callable reference serves to defer callback invocation until the event later occurs. For example, using a lambda to pass extra data with an inline function definition that defers the call:

def handler(name):
    print(name)

Button(command=(lambda: handler('spam')))    # OK: wrap in a lambda to defer

is always equivalent to the longer, and to some observers less convenient, double-function form:

def handler(name):
    print(name)

def temp():
    handler('spam')

Button(command=temp)                         # OK: refence but do not call

We need only the zero-argument lambda or the zero-argument callable reference, though, not both—it makes no sense to code a lambda which simply calls a function if no extra data must be passed in and only adds an extra pointless call:

def handler(name):
    print(name)

def temp():
    handler('spam')

Button(command=(lambda: temp()))             # BAD: this adds a pointless call!

As we’ll see later, this includes references to other callables like bound methods and callable instances which retain state in themselves—if they take zero arguments when called, we can simply name them at widget construction time, and we don’t need to wrap them in a superfluous lambda.

Although the prior section’s lambda and intermediate function techniques defer calls and allow extra data to be passed in, they also raise some scoping issues that may seem subtle at first glance. This is core language territory, but it comes up often in practice in conjunction with GUI.

def handler(A):                           # X is in my global scope, implicitly
    ...use global X and argument A...

X = 42
Button(text='ni', command=(lambda: handler('spam')))

def handler(A, B):
    ...use A and B...

def makegui():
    X = 42
    Button(text='ni', command=(lambda: handler(X, 'spam')))       # remembers X

makegui()
mainloop()   # makegui's scope is gone by this point

def handler(A, B):              # older Pythons: defaults save state
    ...use A and B...

def makegui():
    X = 42
    Button(text='ni', command=(lambda X=X: handler(X, 'spam')))

def makegui():
    X = 42                                                    # X is retained auto
    Button(text='ni', command=(lambda: handler(X, 'spam')))   # no need for defaults

class Gui:
    def handler(self, A, B):
        ...use self, A and B...
    def makegui(self):
        X = 42
        Button(text='ni', command=(lambda: self.handler(X, 'spam')))

Gui().makegui()
mainloop()

def simple():
    spam = 'ni'
    def action():
        print(spam)         # name maps to enclosing function
    return action

act = simple()              # make and return nested function
act()                       # then call it: prints 'ni'

def normal():
    def action():
        return spam         # really, looked up when used
    spam = 'ni'
    return action

act = normal()
print(act())                # also prints 'ni'

def weird():
    spam = 42
    return (lambda: spam * 2)       # remembers spam in enclosing scope

act = weird()
print(act())                        # prints 84

def weird():
    tmp = (lambda: spam * 2)        # remembers spam
    spam = 42                       # even though not set till here
    return tmp

act = weird()
print(act())                        # prints 84

def weird():
    spam = 42
    handler = (lambda: spam * 2)     # func doesn't save 42 now
    spam = 50
    print(handler())                 # prints 100: spam looked up now
    spam = 60
    print(handler())                 # prints 120: spam looked up again now

weird()

def odd():
    funcs = []
    for c in 'abcdefg':
       funcs.append((lambda: c))      # c will be looked up later
    return funcs                      # does not remember current c

for func in odd():
    print(func(), end=' ')            # OOPS: print 7 g's, not a,b,c,... !

def odd():
    funcs = []
    for c in 'abcdefg':
       funcs.append((lambda c=c: c))    # force to remember c now
    return funcs                        # defaults eval now

for func in odd():
    print(func(), end=' ')              # OK: now prints a,b,c,...

funcs = []                              # enclosing scope is module
for c in 'abcdefg':                     # force to remember c now
   funcs.append((lambda c=c: c))        # else prints 7 g's again

for func in funcs:
    print(func(), end=' ')              # OK: prints a,b,c,...

Let’s get back to coding GUIs. Although functions and lambdas suffice in many cases, bound methods of class instances work particularly well as callback handlers in GUIs—they record both an instance to send the event to and an associated method to call. For instance, Example 7-14 shows Examples 7-12 and 7-13 rewritten to register a bound class method rather than a function or lambda result.

import sys
from tkinter import *

class HelloClass:
    def __init__(self):
        widget = Button(None, text='Hello event world', command=self.quit)
        widget.pack()

    def quit(self):
        print('Hello class method world')   # self.quit is a bound method
        sys.exit()                          # retains the self+quit pair

HelloClass()
mainloop()

On a button press, tkinter calls this class’s quit method with no arguments, as usual. But really, it does receive one argument—the original self object—even though tkinter doesn’t pass it explicitly. Because the self.quit bound method retains both self and quit, it’s compatible with a simple function call; Python automatically passes the self argument along to the method function. Conversely, registering an unbound instance method that expects an argument, such as HelloClass.quit, won’t work, because there is no self object to pass along when the event later occurs.

Later, we’ll see that class callback handler coding schemes provide a natural place to remember information for use on events—simply assign the information to self instance attributes:

class someGuiClass:
    def __init__(self):
        self.X = 42
        self.Y = 'spam'
        Button(text='Hi', command=self.handler)
    def handler(self):
        ...use self.X, self.Y...

Because the event will be dispatched to this class’s method with a reference to the original instance object, self gives access to attributes that retain original data. In effect, the instance’s attributes retain state information to be used when events occur. Especially in larger GUIs, this is a much more flexible technique than global variables or extra arguments added by lambdas.

Because Python class instance objects can also be called if they inherit a __call__ method to intercept the operation, we can pass one of these to serve as a callback handler too. Example 7-15 shows a class that provides the required function-like interface.

import sys
from tkinter import *

class HelloCallable:
    def __init__(self):                        # __init__ run on object creation
        self.msg = 'Hello __call__ world'

    def __call__(self):
        print(self.msg)                        # __call__ run later when called
        sys.exit()                             # class object looks like a function

widget = Button(None, text='Hello event world', command=HelloCallable())
widget.pack()
widget.mainloop()

Here, the HelloCallable instance registered with command can be called like a normal function; Python invokes its __call__ method to handle the call operation made in tkinter on the button press. In effect, the general __call__ method replaces a specific bound method in this case. Notice how self.msg is used to retain information for use on events here; self is the original instance when the special __call__ method is automatically invoked.

All four gui3 variants create the same sort of GUI window (Figure 7-11), but print different messages to stdout when their button is pressed:

C:...PP4EGuiIntro> python gui3.py
Hello, I must be going...

C:...PP4EGuiIntro> python gui3b.py
Hello lambda world

C:...PP4EGuiIntro> python gui3c.py
Hello class method world

C:...PP4EGuiIntro> python gui3d.py
Hello __call__ world

There are good reasons for each callback coding scheme (function, lambda, class method, callable class), but we need to move on to larger examples in order to uncover them in less theoretical terms.

For future reference, also keep in mind that using command options to intercept user-generated button press events is just one way to register callbacks in tkinter. In fact, there are a variety of ways for tkinter scripts to catch events:

Of all the options listed in the prior section, bind is the most general, but also perhaps the most complex. We’ll study it in more detail later, but to let you sample its flavor now, Example 7-16 rewrites the prior section’s GUI again to use bind, not the command keyword, to catch button presses.

import sys
from tkinter import *

def hello(event):
    print('Press twice to exit')             # on single-left click

def quit(event):                             # on double-left click
    print('Hello, I must be going...')       # event gives widget, x/y, etc.
    sys.exit()

widget = Button(None, text='Hello event world')
widget.pack()
widget.bind('<Button-1>', hello)             # bind left mouse clicks
widget.bind('<Double-1>', quit)              # bind double-left clicks
widget.mainloop()

In fact, this version doesn’t specify a command option for the button at all. Instead, it binds lower-level callback handlers for both left mouse clicks (<Button-1>) and double-left mouse clicks (<Double-1>) within the button’s display area. The bind method accepts a large set of such event identifiers in a variety of formats, which we’ll meet in Chapter 8.

When run, this script makes the same window as before (see Figure 7-11). Clicking on the button once prints a message but doesn’t exit; you need to double-click on the button now to exit as before. Here is the output after clicking twice and double-clicking once (a double-click fires the single-click callback first):

C:...PP4EGuiIntro> python gui3e.py
Press twice to exit
Press twice to exit
Press twice to exit
Hello, I must be going...

Although this script intercepts button clicks manually, the end result is roughly the same; widget-specific protocols such as button command options are really just higher-level interfaces to events you can also catch with bind.

We’ll meet bind and all of the other tkinter event callback handler hooks again in more detail later in this book. First, though, let’s focus on building GUIs that are larger than a single button and explore a few other ways to use classes in GUI work.

Earlier, we saw how to make widgets expand along with their parent window, by passing expand and fill options to the pack geometry manager. Now that we have a window with more than one widget, I can let you in on one of the more useful secrets in the packer. As a rule, widgets packed first are clipped last when a window is shrunk. That is, the order in which you pack items determines which items will be cut out of the display if it is made too small. Widgets packed later are cut out first. For example, Figure 7-13 shows what happens when the gui4 window is shrunk interactively.

Figure 7-13. gui4 gets small

Try reordering the label and button lines in the script and see what happens when the window shrinks; the first one packed is always the last to go away. For instance, if the label is packed last, Figure 7-14 shows that it is clipped first, even though it is attached to the top: side attachments and packing order both impact the overall layout, but only packing order matters when windows shrink. Here are the changed lines:

Button(win, text='Hello', command=greeting).pack(side=LEFT)
Button(win, text='Quit',  command=win.quit).pack(side=RIGHT)
Label(win,  text='Hello container world').pack(side=TOP)

Figure 7-14. Label packed last, clipped first

tkinter keeps track of the packing order internally to make this work. Scripts can plan ahead for shrinkage by calling pack methods of more important widgets first. For instance, on the upcoming tkinter tour, we’ll meet code that builds menus and toolbars at the top and bottom of the window; to make sure these are lost last as a window is shrunk, they are packed first, before the application components in the middle. Similarly, displays that include scroll bars normally pack them before the items they scroll (e.g., text, lists) so that the scroll bars remain as the window shrinks.

In larger terms, the critical innovation in this example is its use of frames: Frame widgets are just containers for other widgets, and so give rise to the notion of GUIs as widget hierarchies, or trees. Here, win serves as an enclosing window for the other three widgets. In general, though, by attaching widgets to frames, and frames to other frames, we can build up arbitrary GUI layouts. Simply divide the user interface into a set of increasingly smaller rectangles, implement each as a tkinter Frame, and attach basic widgets to the frame in the desired screen position.

In this script, when you specify win in the first argument to the Label and Button constructors, tkinter attaches them to the Frame (they become children of the win parent). win itself is attached to the default top-level window, since we didn’t pass a parent to the Frame constructor. When we ask win to run itself (by calling mainloop), tkinter draws all the widgets in the tree we’ve built.

The three child widgets also provide pack options now: the side arguments tell which part of the containing frame (i.e., win) to attach the new widget to. The label hooks onto the top, and the buttons attach to the sides. TOP, LEFT, and RIGHT are all preassigned string variables imported from tkinter. Arranging widgets is a bit subtler than simply giving a side, though, but we need to take a quick detour into packer geometry management details to see why.

When a widget tree is displayed, child widgets appear inside their parents and are arranged according to their order of packing and their packing options. Because of this, the order in which widgets are packed not only gives their clipping order, but also determines how their side settings play out in the generated display.

Here’s how the packer’s layout system works:

For instance, if you recode the gui4 child widget creation logic like this:

Button(win, text='Hello', command=greeting).pack(side=LEFT)
Label(win,  text='Hello container world').pack(side=TOP)
Button(win, text='Quit',  command=win.quit).pack(side=RIGHT)

you will wind up with the very different display shown in Figure 7-15, even though you’ve moved the label code only one line down in the source file (contrast with Figure 7-12).

Figure 7-15. Packing the label second

Despite its side setting, the label does not get the entire top of the window now, and you have to think in terms of shrinking cavities to understand why. Because the Hello button is packed first, it is given the entire LEFT side of the Frame. Next, the label is given the entire TOP side of what is left. Finally, the Quit button gets the RIGHT side of the remainder—a rectangle to the right of the Hello button and under the label. When this window shrinks, widgets are clipped in reverse order of their packing: the Quit button disappears first, followed by the label.^[30]

In the original version of this example (Figure 7-12), the label spans the entire top side just because it is the first one packed, not because of its side option. In fact, if you look at Figure 7-14 closely, you’ll see that it illustrates the same point—the label appeared between the buttons, because they had already carved off the entire left and right sides.

Beyond the effects of packing order, the fill option we met earlier can be used to stretch the widget to occupy all the space in the cavity side it has been given, and any cavity space left after all packing is evenly allocated among widgets with the expand=YES we saw before. For example, coding this way creates the window in Figure 7-16 (compare this to Figure 7-15):

Button(win, text='Hello', command=greeting).pack(side=LEFT,fill=Y)
Label(win,  text='Hello container world').pack(side=TOP)
Button(win, text='Quit', command=win.quit).pack(side=RIGHT, expand=YES, fill=X)

Figure 7-16. Packing with expand and fill options

To make all of these grow along with their window, though, we also need to make the container frame expandable; widgets expand beyond their initial packer arrangement only if all of their parents expand, too. Here are the changes in gui4.py:

win = Frame()
win.pack(side=TOP, expand=YES, fill=BOTH)
Button(win, text='Hello', command=greeting).pack(side=LEFT, fill=Y)
Label(win,  text='Hello container world').pack(side=TOP)
Button(win, text='Quit', command=win.quit).pack(side=RIGHT, expand=YES,fill=X)

When this code runs, the Frame is assigned the entire top side of its parent as before (that is, the top parcel of the root window); but because it is now marked to expand into unused space in its parent and to fill that space both ways, it and all of its attached children expand along with the window. Figure 7-17 shows how.

Figure 7-17. gui4 gets big with an expandable frame

And as if that isn’t flexible enough, the packer also allows widgets to be positioned within their allocated space with an anchor option, instead of filling that space with a fill. The anchor option accepts tkinter constants identifying all eight points of the compass (N, NE, NW, S, etc.) and CENTER as its value (e.g., anchor=NW). It instructs the packer to position the widget at the desired position within its allocated space, if the space allocated for the widget is larger than the space needed to display the widget.

The default anchor is CENTER, so widgets show up in the middle of their space (the cavity side they were given) unless they are positioned with anchor or stretched with fill. To demonstrate, change gui4 to use this sort of code:

Button(win, text='Hello', command=greeting).pack(side=LEFT, anchor=N)
Label(win,  text='Hello container world').pack(side=TOP)
Button(win, text='Quit',  command=win.quit).pack(side=RIGHT)

The only thing new here is that the Hello button is anchored to the north side of its space allocation. Because this button was packed first, it got the entire left side of the parent frame. This is more space than is needed to show the button, so it shows up in the middle of that side by default, as in Figure 7-15 (i.e., anchored to the center). Setting the anchor to N moves it to the top of its side, as shown in Figure 7-18.

Figure 7-18. Anchoring a button to the north

Keep in mind that fill and anchor are applied after a widget has been allocated cavity side space by its side, packing order, and expand extra space request. By playing with packing orders, sides, fills, and anchors, you can generate lots of layout and clipping effects, and you should take a few moments to experiment with alternatives if you haven’t already. In the original version of this example, for instance, the label spans the entire top side just because it is the first packed.

As we’ll see later, frames can be nested in other frames, too, in order to make more complex layouts. In fact, because each parent container is a distinct space cavity, this provides a sort of escape mechanism for the packer cavity algorithm: to better control where a set of widgets show up, simply pack them within a nested subframe and attach the frame as a package to a larger container. A row of push buttons, for example, might be easier laid out in a frame of its own than if mixed with other widgets in the display directly.

Finally, also keep in mind that the widget tree created by these examples is really an implicit one; tkinter internally records the relationships implied by passed parent widget arguments. In OOP terms, this is a composition relationship—the Frame contains a Label and Buttons. Let’s look at inheritance relationships next.

So what’s the point of subclassing widgets like this? In short, it allows sets of widgets made from the customized classes to look and act the same. When coded well, we get both “for free” from Python’s OOP model. This can be a powerful technique in larger programs.

from gui5 import HelloButton

class MyButton(HelloButton):        # subclass HelloButton
    def callback(self):             # redefine press-handler method
        print("Ignoring press!...")

if __name__ == '__main__':
    MyButton(None, text='Hello subclass world').mainloop()

C:...PP4EGuiIntro> python gui5b.py
Ignoring press!...
Ignoring press!...
Ignoring press!...
Ignoring press!...

class ThemedButton(Button):                             # config my style too
    def __init__(self, parent=None, **configs):         # used for each instance
        Button.__init__(self, parent, **configs)        # see chapter 8 for options
        self.pack()
        self.config(fg='red', bg='black', font=('courier', 12), relief=RAISED, bd=5)

B1 = ThemedButton(text='spam', command=onSpam)  # normal button widget objects
B2 = ThemedButton(text='eggs')                  # but same appearance by inheritance
B2.pack(expand=YES, fill=BOTH)

from user_preferences import bcolor, bfont, bsize   # get user settings

class ThemedButton(Button):
    def __init__(self, parent=None, **configs):
        Button.__init__(self, parent, **configs)
        self.pack()
        self.config(bg=bcolor, font=(bfont, bsize))

ThemedButton(text='spam', command=onSpam)  # normal button widget objects
ThemedButton(text='eggs', command=onEggs)  # all inherit user preferences

class MyButton(ThemedButton):              # subclasses inherit prefs too
    def __init__(self, parent=None, **configs):
        ThemedButton.__init__(self, parent,  **configs)
        self.config(text='subclass')

MyButton(command=onSpam)

Perhaps more importantly, subclasses of Frame are true widgets: they can be further extended and customized by subclassing and can be attached to enclosing widgets. For instance, to attach the entire package of widgets that a class builds to something else, simply create an instance of the class with a real parent widget passed in. To illustrate, running the script in Example 7-21 creates the window shown in Figure 7-21.

from sys import exit
from tkinter import *                    # get Tk widget classes
from gui6 import Hello                   # get the subframe class

parent = Frame(None)                     # make a container widget
parent.pack()
Hello(parent).pack(side=RIGHT)           # attach Hello instead of running it

Button(parent, text='Attach', command=exit).pack(side=LEFT)
parent.mainloop()

Figure 7-21. An attached class component on the right

This script just adds Hello’s button to the right side of parent—a container Frame. In fact, the button on the right in this window represents an embedded component: its button really represents an attached Python class object. Pressing the embedded class’s button on the right prints a message as before; pressing the new button exits the GUI by a sys.exit call:

C:...PP4EGuiIntro> python gui6b.py
Hello frame world 43!
Hello frame world 44!
Hello frame world 45!
Hello frame world 46!

In more complex GUIs, we might instead attach large Frame subclasses to other container components and develop each independently. For instance, Example 7-22 is yet another specialized Frame itself, but it attaches an instance of the original Hello class in a more object-oriented fashion. When run as a top-level program, it creates a window identical to the one shown in Figure 7-21.

from tkinter import *                    # get Tk widget classes
from gui6 import Hello                   # get the subframe class

class HelloContainer(Frame):
    def __init__(self, parent=None):
        Frame.__init__(self, parent)
        self.pack()
        self.makeWidgets()

    def makeWidgets(self):
        Hello(self).pack(side=RIGHT)     # attach a Hello to me
        Button(self, text='Attach', command=self.quit).pack(side=LEFT)

if __name__ == '__main__': HelloContainer().mainloop()

This looks and works exactly like gui6b but registers the added button’s callback handler as self.quit, which is just the standard quit widget method this class inherits from Frame. The window this time represents two Python classes at work—the embedded component’s widgets on the right (the original Hello button) and the container’s widgets on the left.

Naturally, this is a simple example (we attached only a single button here, after all). But in more practical user interfaces, the set of widget class objects attached in this way can be much larger. If you imagine replacing the Hello call in this script with a call to attach an already coded and fully debugged calculator object, you’ll begin to better understand the power of this paradigm. If we code all of our GUI components as classes, they automatically become a library of reusable widgets, which we can combine in other applications as often as we like.

When GUIs are built with classes, there are a variety of ways to reuse their code in other displays. To extend Hello instead of attaching it, we just override some of its methods in a new subclass (which itself becomes a specialized Frame widget). This technique is shown in Example 7-23.

from tkinter import *
from gui6 import Hello

class HelloExtender(Hello):
    def make_widgets(self):                       # extend method here
        Hello.make_widgets(self)
        Button(self, text='Extend', command=self.quit).pack(side=RIGHT)

    def message(self):
        print('hello', self.data)                 # redefine method here

if __name__ == '__main__': HelloExtender().mainloop()

This subclass’s make_widgets method here first builds the superclass’s widgets and then adds a second Extend button on the right, as shown in Figure 7-22.

Figure 7-22. A customized class’s widgets, on the left

Because it redefines the message method, pressing the original superclass’s button on the left now prints a different string to stdout (when searching up from self, the message attribute is found first in this subclass, not in the superclass):

C:...PP4EGuiIntro> python gui6d.py
hello 42
hello 42
hello 42
hello 42

But pressing the new Extend button on the right, which is added by this subclass, exits immediately, since the quit method (inherited from Hello, which inherits it from Frame) is the added button’s callback handler. The net effect is that this class customizes the original to add a new button and change message’s behavior.

Although this example is simple, it demonstrates a technique that can be powerful in practice: to change a GUI’s behavior, we can write a new class that customizes its parts rather than changing the existing GUI code in place. The main code need be debugged only once and can be customized with subclasses as unique needs arise.

The moral of this story is that tkinter GUIs can be coded without ever writing a single new class, but using classes to structure your GUI code makes it much more reusable in the long run. If done well, you can both attach already debugged components to new interfaces and specialize their behavior in new external subclasses as needed for custom requirements. Either way, the initial upfront investment to use classes is bound to save coding time in the end.

Before we move on, I want to point out that it’s possible to reap most of the class-based component benefits previously mentioned by creating standalone classes not derived from tkinter Frames or other widgets. For instance, the class in Example 7-24 generates the window shown in Figure 7-23.

from tkinter import *

class HelloPackage:                            # not a widget subbclass
    def __init__(self, parent=None):
        self.top = Frame(parent)               # embed a Frame
        self.top.pack()
        self.data = 0
        self.make_widgets()                    # attach widgets to self.top

    def make_widgets(self):
        Button(self.top, text='Bye', command=self.top.quit).pack(side=LEFT)
        Button(self.top, text='Hye', command=self.message).pack(side=RIGHT)

    def message(self):
        self.data += 1
        print('Hello number', self.data)

if __name__ == '__main__': HelloPackage().top.mainloop()

Figure 7-23. A standalone class package in action

When run, the Hye button here prints to stdout and the Bye button closes and exits the GUI, much as before:

C:...PP4EGuiIntro> python gui7.py
Hello number 1
Hello number 2
Hello number 3
Hello number 4

Also as before, self.data retains state between events, and callbacks are routed to the self.message method within this class. Unlike before, the HelloPackage class is not itself a kind of Frame widget. In fact, it’s not a kind of anything—it serves only as a generator of namespaces for storing away real widget objects and state. Because of that, widgets are attached to a self.top (an embedded Frame), not to self. Moreover, all references to the object as a widget must descend to the embedded frame, as in the top.mainloop call to start the GUI at the end of the script.

This makes for a bit more coding within the class, but it avoids potential name clashes with both attributes added to self by the tkinter framework and existing tkinter widget methods. For instance, if you define a config method in your class, it will hide the config call exported by tkinter. With the standalone class package in this example, you get only the methods and instance attributes that your class defines.

In practice, tkinter doesn’t use very many names, so this is not generally a big concern.^[31] It can happen, of course; but frankly, I’ve never seen a real tkinter name clash in widget subclasses in some 18 years of Python coding. Moreover, using standalone classes is not without other downsides. Although they can generally be attached and subclassed as before, they are not quite plug-and-play compatible with real widget objects. For instance, the configuration calls made in Example 7-21 for the Frame subclass fail in Example 7-25.

from tkinter import *
from gui7 import HelloPackage      # or get from gui7c--__getattr__ added

frm = Frame()
frm.pack()
Label(frm, text='hello').pack()

part = HelloPackage(frm)
part.pack(side=RIGHT)              # FAILS!--need part.top.pack(side=RIGHT)
frm.mainloop()

This won’t quite work, because part isn’t really a widget. To treat it as such, you must descend to part.top before making GUI configurations and hope that the name top is never changed by the class’s developer. In other words, it exposes some of the class’s internals. The class could make this better by defining a method that always routes unknown attribute fetches to the embedded Frame, as in Example 7-26.

import gui7
from tkinter import *

class HelloPackage(gui7.HelloPackage):
    def __getattr__(self, name):
        return getattr(self.top, name)                  # pass off to a real widget

if __name__ == '__main__': HelloPackage().mainloop()    # invokes __getattr__!

As is, this script simply creates Figure 7-23 again; changing Example 7-25 to import this extended HelloPackage from gui7c, though, produces the correctly-working window in Figure 7-24.

Figure 7-24. A standalone class package in action

Routing attribute fetches to nested widgets works this way, but that then requires even more extra coding in standalone package classes. As usual, though, the significance of all these trade-offs varies per application.