Python has included the Tk interface module (tkinter) since versions 2.7 and 3.1. The module is a binding to version 8.5 of the Tk GUI suite for making windowing applications. My first installed version of Python was 2.7, so I’ve been aware of the module for over ten years but never explored it.

At the beginning of this month, I decided to dive in. It led to an intense two-week bout of 12+ hour days, but I emerged with working apps (and my sanity). This post and ones to come document and share what I’ve learned.

This first post is intended for those with no experience doing this, so we’ll start as simply as possible by creating a window. For these first few examples, you’ll need to open IDLE (Integrated Development & Learning Environment; from the standard Python install) and enter the lines by hand.

In fact, these first examples won’t work unless you do. IDLE has some special handling especially for using the tkinter module.

To begin with the simplest possible window — a literal one-liner (except for the import line) — enter the following code:

You can type this into the editor window, save it to a file, and then run it, or you can just type the lines in the shell window and execute them directly. Either way, the second line makes a small unadorned Tk window pop up:

Close it by clicking the ⌧ in the upper-right corner.

Congrats! You just created your first window. Note that if you run your code fragment outside of IDLE, it just runs and exits and no window appears. You must do these examples in IDLE (we’ll get away from that soon enough).

The first example makes clear that calling the Tk function is what creates the window. In some cases, the next step is to hide the window until it’s ready to be shown, but that isn’t necessary for these simple examples.

We want to do things with the window we created, like add a menu bar and various widgets that comprise our app, so we need to save the return value of the call to Tk. Canonically, we save this in a variable named root:

Running this (or typing it into the shell window) opens the same window as before. Be sure to close it before continuing. Note that closing the shell window will also close the window.

This next example illustrates why we need the root variable:

Now the window looks a little different:

We set the window’s title with the call to root.title and window’s size and location on screen with the call to root.geometry. One common technique we’ll use a lot is calling for a new object and then setting parameters on the returned object.

Before we continue, we should up our game and get away from the dependence on IDLE. From here on, these examples can be run as you would run any Python script. this requires adding a call to the root.mainloop method:

The open_the_window function (lines #3 to #12) takes ttl (title) and geo (geometry) parameters, creates essentially the same window as did the previous example (but parameterized), and returns the root object (the window itself).

The key change in this code is on line #21, the call to root.mainloop. This is what enables the script to create its window when run as a regular Python script. (There is a wrinkle about using pythonw.exe rather than python.exe, but we’ll get to that down the road.)

For our next step, we’ll start to make this more like a real app by first adding a menu bar and then a command on that menu bar to close the window the “official” way (rather than using the ⌧ in the upper right):

I’ll warn you now that these apps tend to get long. Not complicated, but lots of lines of code needed to do things. You can see the line-count growing already, and we’ve hardly begun.

We’ve added the window_close function (lines #9 to #13) and three lines that build a simple menu bar with one item. Line #16 creates a new menu. Line #19 adds a menu item labeled “Exit” to that menu. It also sets the binds the item to the window_close function. Line #22 sets the root window’s menu property to be the menu we just created. This appears in the app window as its menu bar.

The window_close function calls root.destroy, which closes the app window and exits from the root.mainloop call in line #34. The “main loop” is essentially an event loop that manages the window.

When run, we get this window:

Clicking Exit on the menu bar closes the window.

We can expand on this a little and introduce a new tool:

Here we add the about function (lines #14 to #16) and an “About” item to the menu bar (line #22). The about function calls the showinfo function (from the tkinter.messagebox submodule) to pop up a simple “About” box.

For simple apps, a simple menu bar may be sufficient, but often you’ll want the usual sort of menu bar with dropdown submenus and various options. Here’s a template for the standard Windows app menu bar:

(I warned you these get long!). To organize things, I moved all menu-building code to its own function, build_menubar (lines #19 to #47). The change here is creating new menus (lines #24, #33, and #38) for dropdown submenus. We add command items to those. Separators make them menu look better.

Note that we’ve bound all the menu command items (except Exit and About) to the new function menu_command, which lets us know it was called by printing “Menu Choice”. When you run the code and make menu selections in the window, each one prints a line in the shell window:

Menu Choice.
Menu Choice.
Menu Choice.
Menu Choice.
Menu Choice.
Menu Choice.

We add the submenus to the menu bar in lines #42 to #44 using the add_cascade method and add the menu bar itself to the window in line #47 (same as before). Now we have the usual sort of Windows menus:

For Windows-style menus, be sure to use the tearoff keyword argument and set it to 0. Otherwise, each submenu will have a dashed line across the top that allows the user to “tear off” the menu and place it somewhere else on the screen:

In fact, tearing a menu off turns it into a window of its own. One that can be resized., so probably not what’s desired in most apps.

The window-creation code begins on line #49 and calls the build_menu function on line #56. Note that we’ve added something new in line #53 — a binding between the user pressing the [Esc] (escape) key and the window_close function. This lets the user close the window by pressing the escape key.

Every menu selection (besides Exit and About) calls the menu_command function, but that function has no way to know who called it. If we’re going to use a single function to handle multiple menu selections, we need a way to know which menu selection the user made. There are two solutions.

The first is, as with the Exit and About menu selections, bind each menu item to a separate function. Which, in most applications, is the best technique because it keeps separate functions separate. The downside is function bloat; this requires lots of functions. The canonical names I use are file_new, file_open, file_save, file_saveas, file_exit, edit_copy, edit_paste, help_about, and whatever else needed to handle menu selections.

(Note that file_exit and help_about replace the window_close and about functions in this list.)

The second, also useful in many situations, has the problem that when we bind a menu item (or button) to a command, the Tk engine calls the bound function with no parameters identifying the caller. But we can use a simple coding trick to put an identifying “proxy” between Tk and the function:

Note the proxy function (lines #22 to #24). It takes a parameter, menu_id, and returns a (lambda) function that takes no parameters, and which invokes the menu_command function and passes it the menu_id value. This is called a closure, and it’s a very handy trick. The created lambda function “remembers” the menu_id passed to proxy.

So, each menu item ends up with its own unique (identifying!) lambda function bound to it, and all those lambda functions invoke the menu_command function. When you run the app now, the printout is:

Menu Choice: New
Menu Choice: Open
Menu Choice: Save
Menu Choice: SaveAs
Menu Choice: Copy
Menu Choice: Paste

Depending on your needs and preferences, for handling menu selections, button clicks, and other user inputs, you can either create lots of specific functions or use proxies to invoke general handlers.

Truth is, usually a general handler ends up dispatching to some set of functions, so the general technique is mostly useful when each menu selection or button click does something similar enough to be handled by the same function. One example might be a set of command buttons that all invoke similar commands (e.g. they all launch a browser window but to different a site). The handler function would be the same except for the site.

The next step may be something of a personal preference, but I think there’s a strong argument that using classes is more aligned with both Python and Tk. Regardless, I prefer it, so let’s switch from functions to classes:

There isn’t anything new here. This is just a refactoring of the code into a class. For one, this makes the code more reusable and extendable.

The only difference in operation is that the menu id strings now have the form “M:<command>”. The reason for this becomes apparent in next example. I wanted this example to focus on the shift from functions to classes.

We’ll come back to menus in the future, but now lets’ move on to actually putting something in our window:

This is essentially the same as the previous example except for the addition of the _widgets method (lines #38 to #79). This method creates a Frame (line #40), two Labels (lines #43 and #57), and five Buttons (lines #61 to #65).

The app window looks like this:

When run, and menu selections are made and buttons are clicked, the printout is:

<SimpleWindowApp @2cc91fe2900>
Command: M:New
Command: M:Open
Command: M:Save
Command: M:SaveAs
Command: M:Copy
Command: M:Paste
Command: B:#1
Command: B:#2
Command: B:#3
Command: B:#4
Command: B:Exit
Exit App

I used the Exit button to exit the app in the example above. This is apparent from the “B:” prefix on the id sent to the command method (lines #23 to #27). Had I used the menu selection to exit, it would have printed “M:Exit”. This allows different controls to activate the same command but still differentiate.

The command method can use cmd_id[2:] on its input to skip the prefix or, in this case on line #26, see if the string endswith a particular target string.

Note that with widgets we have three distinct stages: create the widget; configure its appearance; place, pack, or grid it to “map” it into the window. It’s the last action that makes the widget visible.

To get some sense of this, let’s return to IDLE and put the following into the editor window (you can type it into the shell window if you really want to, but we’ll be making changes, so I recommend the editor):

The first part (lines #3 to #6) is old hat. Lines #8 through #16 create a new button widget (line #9), configure its text and command callback (lines #12 and #13), and then pack it into the window using the anchor parameter set to ‘nw’ (northwest).

Run this to get this window:

Note there are two other ways to configure widgets. This code accomplishes the same thing:

But sets the text directly when creating the button and uses the config method to set the command callback function. The three techniques have the same effect. There are, by the way, many other properties of widgets that you can configure.

There are also different methods for mapping widgets into windows. Above we used the pack method; there is also a grid method:

This produces the same window. The grid method is choice for when you want to align your widgets in neat rows and columns.

Lastly, you can place your widget:

I haven’t used the place method in my own code yet, so won’t say more about it. Judging by tk.Place.place.__doc__, it has more capability than pack or grid.

We’ll end today with an important trick. Run the previous code in IDLE and notice you can still type things in the shell. Click the button a few times to see it print “Click!” to the shell window, then click the shell window, press [Enter] to get a prompt, and then type the following:

================= RESTART: fragment.py =================
>>> Click!
    Click!
    Click!

>>> 
>>> root
    <tkinter.Tk object .>
>>> btn
    <tkinter.Button object .!button>
>>> 
>>> root.geometry()
    '480x240+300+100'
>>> root.title('Custom Title')
    ''
>>> 
>>> btn['text'] = 'New Button Text'
>>> btn['fg'] = 'red'
>>> btn['fg'] = '#009900'
>>> btn['font'] = ('Arial', 12, 'bold')
>>> btn.config(fg='#000000', padx=20)
>>> 

Because we did not include a call to mainloop, the app is running but accessible to us from the shell window. We can interact with the window and its widgets (or the menu). This is explicitly designed into IDLE for Tk development and debugging. It’s a great way to find out how things work and what effect various tweaks have.

Notice what happens to the window when you give it a new title. Or how the button changes when you give it new text, foreground color, or font. The last line uses the config method but accomplishes the same thing. It’s handy for setting multiple properties at once.

Notice also the way many methods, such as geometry, if given no parameters return the current value.

That should be enough to get you started. Future posts will dive deeper into details and create some working apps. As an example, here’s a hex dump utility I made my intense dive into tkinter:

Which takes me back to the first Simple Tricks post.

That’s all for this time.

Link: Zip file containing all code fragments used in this post.

∅