Introduction

This tutorial will help you quickly get up to speed and build mainstream desktop graphical user interfaces with Tk, in particular, Tk 8.5 and 8.6. Tk 8.5 was a milestone release. It marked a significant departure from older versions of Tk that most people know and love recognize.

The downside is that unless you know one or two crucial things, it's actually not that significant a release. In fact, it will seem like nothing has changed at all. Due to backward compatibility, unless existing programs make a few simple changes, they won't look any different. (Imagine if you just moved into a rustic and quirky historical home. You'd want someone to point out where they've hidden the light switches and power outlets, wouldn't you?)

If you're new to Tk or creating a new program, this tutorial will ensure you get started the right way. If you've used Tk before, it will help you bring your knowledge right up to date. And if you're updating code that may have been written years ago, you'll see step-by-step how to bring it into the modern age. It's a cliche, but I can't believe how much I've learned in writing this tutorial, and I've been using Tk for over twenty-five years.

The general state of Tk documentation (outside the Tcl-oriented reference documentation, which is excellent) is unfortunately not at a high point these days. This is particularly true for developers using Tk from languages other than Tcl or working on multiple platforms.

So this tutorial will, as much as possible, target developers on the three main platforms (Windows, macOS, Linux), and also be language-neutral. Initially, the tutorial will cover Tcl, Ruby, Perl and Python. Over time, additional languages may be added. Even if your own language isn't included, the chances are you'll still benefit; since all the languages use the same underlying Tk library, there's obviously a lot of overlap.

It's also not a reference guide. It's not going to cover everything, just the essentials you need in 95% of applications. The rest you can find in reference documentation.

Who This Tutorial Is For

This tutorial is designed for developers building tools and applications in Tk. It's also concerned with fairly mainstream graphical user interfaces, with buttons, lists, checkboxes, rich text editing, 2D graphics, etc. So if you're either looking to hack on Tk's internal C code or build the next great 3D immersive game interface, this is probably not the material for you.

This tutorial also doesn't teach you the underlying programming language (Tcl, Ruby, Perl, Python, etc.), so you should have a basic grasp of that already. Similarly, you should have a basic familiarity with desktop applications in general. While you don't have to be a user interface designer, some appreciation of GUI design is always helpful.

Modern Best Practices

This tutorial is all about building modern user interfaces using the current tools Tk has to offer. It's all about the best practices you need to know to do this.

For most tools, you wouldn't think you'd have to say something like that. But for Tk, that's not the case. Tk has had a very long evolution (see Tk Backgrounder), and any evolution tends to leave you with a bit of cruft. Couple that with how much graphical user interface platforms and standards have evolved in that time. You can see where keeping something as large and complex as a GUI library up to date (and backward compatible) may be challenging.

Tk has, for most of its lifetime, gotten a bad rap, to put it mildly. Some of this has been well deserved, most of it not so much. Like any GUI tool, you can create absolutely terrible-looking and outdated user interfaces with it. It can also be used to develop spectacularly good ones with the proper care and attention. Most people know about the crappy ones; most of the good ones people don't even know are done in Tk. In this tutorial, we're going to focus on what you need to build good user interfaces. Thankfully, this isn't nearly as hard as it used to be before Tk 8.5.

So, to sum up: modern desktop graphical user interfaces, using modern conventions and design sense, using the modern tools provided by Tk 8.5 and 8.6.

Tk Extensions

When it comes to modern best practices, Tk extensions deserve a special word of note. Over the years, developers have created all kinds of add-ons to Tk, for example, adding new widgets not available in the core (or at least not at the time). Some well-known and quite popular Tk extensions include BLT, Tix, iWidgets, BWidgets; there are many, many others.

Many of these extensions were created decades ago. Because core Tk has always been highly backward compatible, these extensions generally keep working with newer versions. However, they may not reflect current platform conventions or styles. They may "work" but can make your application appear extremely dated or out of place. In many cases, the facilities they provide have been obsoleted by newer and more modern facilities recently built into Tk itself.

If you decide to use Tk extensions, it's highly recommended to investigate and review your choices carefully.

The Better Way Forward

Tk gives you a lot of choices. There are at least six different ways to layout widgets on the screen. Multiple widgets can be used to accomplish the same thing, and that's before considering any Tk extensions. Tk emphasized backward compatibility, which is a double-edged sword. Most of these old ways of doing things still keep working, year after year. That doesn't mean you should keep using some of them.

So there are many in Tk, but frankly, all that choice gets in the way. If you want to learn and use Tk, you don't need to know ten different ways to accomplish the same thing. You shouldn't need to do all the research, explore all the options, and make a choice yourself. You need to know the right way to do things today. That's what this tutorial will give you. Think of it as the documentation equivalent of opinionated software.

So we'll often use different ways of doing things than you'd find in other documentation or examples. Usually, it's because when those were written, the better ways didn't even exist yet. (Here's a litmus test for Tk documentation: does it use the archaic pack instead of the modern grid?) Later on, once you're an expert and encounter some wacky situation where the typical choice doesn't fit, you can go hunt around for alternatives.

How to Use

While the tutorial is designed to be used linearly, feel free to jump around as you see fit. We'll often provide links to information, whether links to other documentation on this site, such as our "widget roundup" providing usage info on each Tk widget, or to external documentation, such as the full reference for a particular command.

The tutorial also lets you select what language (Tcl, Ruby, Perl or Python) to show. You can change this by the "Show:" popup menu which is located in the sidebar, near the top right of each page in the tutorial. But it also lets you see how Tk is used by all the different languages, which can itself be quite interesting and useful.

Conventions

As is typically done, code listings, interpreter or shell commands, and responses will be indicated with a fixed-width font. When showing an interactive session with the interpreter, what you type will be in bold fixed-width.

When describing procedure or method calls, the literal parts (e.g., the method name) will be in a plain fixed-width font. Parameters, where you should fill in the actual value, will add italics, and optional parameters will be surrounded by '?', e.g., set variable ?value?.

In general, when referring to these procedures or method calls in the text, we'll omit punctuation (brackets, parentheses, commas, equals, semicolons, etc.) that may be required by a specific language binding. Method names that consist of multiple words, (e.g., selection_clear) may look slightly different in different languages (e.g., selection clear in Tcl). In the text, we'll generally use the former notation with the underscore. Language-specific code snippets show the complete syntax, of course.

You'll see some paragraphs that are separated from the main text. These are used for several different things. Each is identified with a different icon, as follows:

Spotted a mistake? Couldn't find what you were looking for? Suggestions? Let me know!
If you've found this tutorial useful, please check out Modern Tkinter.