Tkinter GUI Programming by Example

Most of the time, you will not need to install Tkinter as long as you have Python installed. To check, open an instance of the interactive interpreter and type import tkinter (Python 3) or import Tkinter (Python 2). If you don't see an error, then Tkinter is already installed and you are ready to go! Some flavors of Linux will not come with Tkinter by default, and if you receive an error message while performing the previous step, search your distribution's package manager. On Debian-based distributions such as Ubuntu, the package should be called python3-tk. On RPM-based distributions, including Fedora, you may instead find a package called python3-tkinter.

Examples in this book will be written using Python 3.6.1 and Tkinter 8.6. I recommend you also use these versions, or as close to them as possible, when following along. To check your Tkinter version, open an interactive Python prompt and type the following:

>>> import tkinter
>>> tkinter.TkVersion

Once you've got Tkinter installed and ready, we can move on to a brief overview of how we will be structuring a Tkinter application and then dive in and write our first program.

Tkinter exposes many classes. These are known as widgets. A widget is typically any part of the application that needs to be drawn onto the screen, including the main window.

A Tkinter application always needs to have a main window. This is what will be drawn on the screen for the user to see. This is crucial for any GUI application, so much so that if you do not define one, Tkinter will try to create one for you (though you should never rely on this!). The widget that performs this job is called Tk.

The Tk widget exposes various window properties, such as the text within the top bar of the application, the size of the application, its position on screen, whether it can be resized, and even the icon which appears in the top right-hand corner (on Windows only).

Because of this feature exposure, it is very common for the main class of an application to inherit from the Tk widget, though any Tkinter widget can be subclassed to add program-specific functionality.

There is no set convention for what the subclass should be called. Some like to call it Root, some choose App, and others (such as myself) prefer to name it after the program itself. For example, a shopping list program would have a class called ShoppingList that inherits from Tk. Bear this in mind when looking through other sources of information on Tkinter.

Once you have a main window defined, you can begin adding other widgets into it. All other widgets must belong to a parent which has the ability to display them, such as a Tk or Frame. Each widget is only visible if its parent is. This allows us to group widgets into different screens and show or hide groups of them as need be.

Widgets are placed into their parents using special functions called geometry managers. There are three geometry managers available in Tkinter – pack, grid, and place. Let's take a look at each of them in detail.

Now that we have the basic understanding of the concept of widgets and how to add them into a window, it's time to put this into practice and make ourselves an application!

As with almost all programming examples, we will start with a Hello World application. Don't feel cheated though, it will have interactive aspects too! Let's begin with the most important step for any GUI application—showing a window. Start by opening your choice of text editor or IDE and putting in the following code:

import tkinter as tk

class Window(tk.Tk):
  def __init__(self):
    super().__init__()
    self.title("Hello Tkinter")

    label = tk.Label(self, text="Hello World!")
    label.pack(fill=tk.BOTH, expand=1, padx=100, pady=50)


if __name__ == "__main__":
  window = Window()
  window.mainloop()

Let's break this first step down. We begin by importing Tkinter and giving it the alias of tk for brevity. Every example in this book should include this line so that we have access to all of Tkinter's widgets, including the main window.

Speaking of widgets, we begin this example by subclassing Tkinter's main window widget—Tk. Doing so allows us to change various aspects of it, including the title which will display inside the window's top bar. We set the title to Hello Tkinter in this example.

Next, we want to display some text within our window. To do this, we use a Label widget. A Label widget is typically non-interactive and is used to display either text or an image.

When defining Tkinter widgets, the first argument is always the parent (sometimes called master) which will hold the widget. We use self to refer to our main window in this case. Afterward, we have a vast array of keyword arguments to use in order to change their properties. The text argument here will take a string which tells the label what to display. Our label will say Hello World!

Now that we have two widgets, we need to place the label inside of our main window (Tk) so that they both display. To do this with Tkinter, we utilize one of the geometry managers we covered earlier. For our first example, we will be using pack. Pack has been given the following arguments:

With that, our Hello World is ready to run. In order to tell the main window to show itself, we call the mainloop method. This is all enclosed within the (hopefully familiar) if __name__ == "__main__" block. Utilizing this block allows widgets from one file to be imported into another file for reuse without creating multiple main windows.

Execute the code via your preferred method and you should see a little window appear. Congratulations! You have now written your first GUI application with Tkinter!:

Our Hello World application

Of course, without any interactivity, this is just a message box. Let's add something for the user to do with our application. Bring the source code back up and change the __init__ method to look like this:

class Window(tk.Tk):
  def __init__(self):
    super().__init__()
    self.title("Hello Tkinter")

    self.label = tk.Label(self, text="Choose One")
    self.label.pack(fill=tk.BOTH, expand=1, padx=100, pady=30)

    hello_button = tk.Button(self, text="Say Hello", 
                             command=self.say_hello)
    hello_button.pack(side=tk.LEFT, padx=(20, 0), pady=(0, 20))

    goodbye_button = tk.Button(self, text="Say Goodbye",
                               command=self.say_goodbye)
    goodbye_button.pack(side=tk.RIGHT, padx=(0, 20), pady=(0, 20))

Our label has changed to say Choose one to indicate that the user can now interact with the application by selecting one of the two buttons to click. A button in Tkinter is created by adding an instance of the Button widget.

The Button widget is exactly what you would imagine; something the user can click on to execute a certain piece of code. The text displayed on a Button is set via the text attribute, much like with a Label, and the code to run when clicked is passed via the command argument.

Our two buttons are placed within our main window using pack. This time, we use the side keyword argument. This tells the geometry manager where to place the item inside the window. Our hello_button will go on the left, and our goodbye_button will go on the right.

We also use padx and pady to give some spacing around the buttons. When a single value is given to these arguments, that amount of space will go on both sides. When a tuple is passed instead, the format is (above, below) for pady and (left, right) for padx. You will see in our example that both buttons have 20 pixels of padding below them; our leftmost button has 20 pixels of padding to its left, and our rightmost has 20 pixels to its right. This serves to keep the buttons from touching the edge of the window.

We now need to define the functions which will run when each button is pressed. Our Say Hello button calls say_hello and our Say Goodbye button calls say_goodbye. These are both methods of our Window class and so are prefixed with self. Let's write the code for these two methods now:

def say_hello(self):
  self.label.configure(text="Hello World!")

def say_goodbye(self):
  self.label.configure(text="Goodbye! \n (Closing in 2 seconds)")
  self.after(2000, self.destroy)

In say_hello, we will update the text of our label widget to Hello World! as it was before. We can change attributes of Tkinter widgets using the configure method. This then takes a keyword argument and value, just like when we created them initially.

Our say_goodbye method will also update the label's text and then close the window after two seconds. We achieve this using the after method from our Tk widget (which we have subclassed into Window). This method will call a piece of code after a certain amount of time has elapsed (in milliseconds).

The destroy method can be called on any Tkinter widget, and will remove it from the application. Destroying the main window will cause your application to exit, so use it carefully.

Leave the if __name__ == "__main__" block as it was before and give this application a try. You should see now that both buttons will do something. It may not look like many lines of code, but we have now covered quite a lot of the things a GUI application will need to do. You may be getting the following output:

Our application now with two buttons

We have provided user interactivity with Button widgets and seen how to link a button press to a piece of code. We've also covered updating elements of the user interface by changing the text displayed in our Label widget. Performing actions outside of the main loop has also happened when we used the after method to close the window. This is an important aspect of GUI development, so we will revisit this later.

Instead of using configure to repeatedly change the text within our label, wouldn't it be better if we could assign a variable to it and just change this variable? The good news is you can! The bad news? Regular Python variables aren't perfectly compatible with Tkinter widgets. Shall we take a look?

class Window(tk.Tk):
    def __init__(self):
        super().__init__()
        self.title("Hello Tkinter")
        self.label_text = "Choose One"

        self.label = tk.Label(self, text=self.label_text)
        self.label.pack(fill=tk.BOTH, expand=1, padx=100, pady=30)

        hello_button = tk.Button(self, text="Say Hello", 
                                 command=self.say_hello)
        hello_button.pack(side=tk.LEFT, padx=(20, 0), pady=(0, 20))

        goodbye_button = tk.Button(self, text="Say Goodbye",
                                   command=self.say_goodbye)
        goodbye_button.pack(side=tk.RIGHT, padx=(0, 20), pady=(0, 20))

        def say_hello(self):
          self.label_text = "Hello World"

        def say_goodbye(self):
          self.label_text="Goodbye! \n (Closing in 2 seconds)"
          self.after(2000, self.destroy)


if __name__ == "__main__":
  window = Window()
  window.mainloop()

label_text = tk.StringVar()

>>> from tkinter import *
 >>> win = Tk()
 >>> sv = StringVar()
 >>> sv
 <tkinter.StringVar object at 0x05F82D50>
 >>> sv.get()
 ''
 >>> sv.set("Hello World!")
 >>> sv.get()
 'Hello World!'
 >>> sv.set(sv.get() + " How's it going?")
 >>> sv.get()
 "Hello World! How's it going?"

self.label_text = tk.StringVar()
self.label_text.set("Choose One")

def say_hello(self):
    self.label_text.set("Hello World")

def say_goodbye(self):
    self.label_text.set("Goodbye! \n (Closing in 2 seconds)")
    self.after(2000, self.destroy)

Often, a GUI application will need to tell the user something. Using what we have learned at the moment, we could make several Label widgets which update depending on the results of some other functions. This would get tedious and take up a lot of space within the application's window.

A much better way to achieve this is to use a pop-up window. These can be created manually, but Tkinter also comes with a few pre-built pop-ups which are already laid out and ready to display any message the programmer passes to them.

Let's adjust our Hello World application to utilize these windows to display the chosen message to the user.

Import the messagebox module with the following statement:

import tkinter.messagebox as msgbox

Now update the non-init methods to utilize this module:

def say_hello(self):
    msgbox.showinfo("Hello", "Hello World!")

def say_goodbye(self):
    self.label_text.set("Window will close in 2 seconds")
    msgbox.showinfo("Goodbye!", "Goodbye, it's been fun!")
    self.after(2000, self.destroy)

Run this version of our application and try out both buttons.

Showing information with showinfo

You should be able to see what the two arguments to showinfo do.

The first argument is the window's title bar text. If you didn't notice, click the Say Hello button again – you should see the word Hello inside the title bar of the pop-up window.

Clicking the Say Goodbye button will yield a pop-up message with Goodbye! in the title bar.

The second argument is a string containing the information which will be written inside the box.

The showinfo box contains just one button—an OK button. Clicking this button dismisses the window:

A showinfo box

While a messagebox window is displayed, the main window is effectively paused. The Say Goodbye button demonstrates this well. The line which tells the main window to close after 2 seconds does not get executed until the messagebox is dismissed.

Try clicking the Say Goodbye button and waiting for more than 2 seconds. You will see that the main window stays open until 2 seconds after you click OK to close the messagebox window. This is important to remember.

If, for example, you are processing a large list of items and you wish to alert the user to their status, it's best to wait until all of the items are processed before using showinfo. If you put a showinfo box after each item, the user will have to continually close them in order to allow the main window to continue processing.

Getting feedback from the user

Should you require something back from the user, Tkinter has four more message boxes for you:

• askquestion
• askyesno
• askokcancel
• askretrycancel

askquestion will allow any question to be passed in and provides Yes and No answers. These are returned to the program as the string literals "yes" and "no".

askyesno does the same, but will return 1 on Yes and nothing on No.

askokcancel provides OK and Cancel buttons to the user. OK returns 1 and Cancel nothing.

askretrycancel provides Retry and Cancel buttons. Retry returns 1 and Cancel nothing.

Despite the seemingly large number of choices, these all do pretty much the same thing. There doesn't seem to be much of a use case for askquestion over askyesno since they provide the same button choices, but askquestion will produce cleaner code thanks to the return values.

Let's see askyesno in action within our Hello World application.

Change the say_goodbye method to the following:

def say_goodbye(self):
    if msgbox.askyesno("Close Window?", "Would you like to 
                        close this window?"):
        self.label_text.set("Window will close in 2 seconds")
        self.after(2000, self.destroy)
    else:
        msgbox.showinfo("Not Closing", "Great! This window 
                         will stay open.")

Run this application and try clicking the Say Goodbye button. You will now be asked whether you want to close the window. Give both No and Yes a try:

Our askyesno box

From the code for this function, you should see that the askyesno method can be treated like a Boolean statement. If you don't like doing this in one go, you could always use a variable such as the following:

close = msgbox.askyesno("Close Window?", "Would you like to close this window?") 
if close: 
    self.close()

We now know how to get Boolean information from our user, but what if we want to get something more detailed, such as text?

Tkinter provides us with the perfect widget to do just this – Entry.

An Entry widget is a one-line text entry box which is put into a parent widget just like a Label or Button. The special Tkinter variables can be attached to an Entry to make getting the value out a breeze.

Why don't we add some personalization to our Hello World application? Grab your code and adjust it to the following:

class Window(tk.Tk):
    def __init__(self):
        super().__init__()
        self.title("Hello Tkinter")
        self.label_text = tk.StringVar()
        self.label_text.set("My Name Is: ")

        self.name_text = tk.StringVar()

        self.label = tk.Label(self, textvar=self.label_text)
        self.label.pack(fill=tk.BOTH, expand=1, padx=100, pady=10)

        self.name_entry = tk.Entry(self, textvar=self.name_text)
        self.name_entry.pack(fill=tk.BOTH, expand=1, padx=20, pady=20)

        hello_button = tk.Button(self, text="Say Hello", 
                                 command=self.say_hello)
        hello_button.pack(side=tk.LEFT, padx=(20, 0), pady=(0, 20))

       goodbye_button = tk.Button(self, text="Say Goodbye",
                                  command=self.say_goodbye)
       goodbye_button.pack(side=tk.RIGHT, padx=(0, 20), pady=(0, 20))

If you run this version of the code, you will now see a text box in which to enter your name. As we enter our name in the Entry widget, its value is automatically assigned to the name_text StringVar thanks to the textvar keyword argument:

Our application now with an Entry widget

The buttons will still function the same, however, so let's do something about that:

def say_hello(self):
    message = "Hello there " + self.name_entry.get()
    msgbox.showinfo("Hello", message)

def say_goodbye(self):
    if msgbox.askyesno("Close Window?", "Would you like to 
                        close this window?"):
        message = "Window will close in 2 seconds - goodybye " + self.name_text.get()
        self.label_text.set(message)
        self.after(2000, self.destroy)
    else:
        msgbox.showinfo("Not Closing", "Great! This window 
                         will stay open.")

These functions demonstrate both of the ways we can now grab the value back out of our Entry widget. We can either call the get method of the Entry itself, or grab the value out of our StringVar (also with the get method).

If the Entry box itself is the only part of your application which will need to use its value, I would recommend just grabbing it directly via .get() and foregoing the use of a StringVar. If, however, its value will be needed by other parts of your application, using a StringVar is probably the best way. This allows you to use the set method to adjust its value programmatically.

With this, our Hello World application has taught us all we should need to know with regard to basic GUI functionality. We have learned how to spawn a window containing various GUI elements by utilizing Tkinter's built-in widgets. We can place these widgets into the window using special functions called geometry managers, of which we have three to choose from.

The messagebox module allows us to easily convey information to the user without having to use any widgets within our main window, and can also be used to get feedback from a user and control how our window will behave.

We've added three simple, but effective widgets to our arsenal (not including the main window): the Label, for displaying static information; the Button, which allows a user to execute functions by clicking on it; and the Entry, which gathers textual information and allows for its use by our applications.

Next on our agenda is something a little different—a game of blackjack! By writing this game, we will also cover a very common starting point among programmers interested in GUI development: having a command-line application which could be improved by becoming a graphical one. In order to do this, we will briefly step back to the world of the CLI.