At some point in your Python experience, you might want to create a program with a graphical user interface or GUI (pronounced “gooey” by most). Many toolkits for Python exist to accomplish this, including Python’s own native GUI library, TkInter. Setting up GUIs in Tkinter isn't complicated, though in the end it depends on the complexity of your own design. Here we will look at of the commonly used parts of the Tkinter module through some simple GUI examples. Before getting into the examples, let’s briefly cover the commonly used widgets (building blocks of the GUI) the Tkinter library has to offer.

In a nutshell all of Tkinter’s widgets provide either simple input (user-input) to the GUI, output (graphical display of information) from the GUI, or a combination of the two. The following are two tables of the most commonly used widgets for input and output with brief descriptions.

Tkinter widgets commonly used for input:

Tkinter widgets commonly used for output:

Though the widgets above are grouped into “input” and “output” categories, in reality they all are dually for input and output, especially when callbacks (or event bindings) come into play. We’ll examine callbacks and event bindings more in a bit, for now we’ll look at some examples of some of the widgets listed above in applications.

To use the Tkinter module, we have to import it into our global namespace. This is often done with a statement like this:

• Python 3.x
• Python 2.x
• Python 3.x
• Python 2.x

This gives us access to the module without having to type out the full module name each time. You can see this when we reference it:

[python]
>>> tk
<module 'Tkinter' from 'C:\Python27\lib\lib-tk\Tkinter.pyc'>
[/python]

Alright, we're ready to make our GUI now—but before we do let's briefly visualize how we want it to look, and examine Tkinter GUI structure. We’ll keep our design simple for now, one output widget and one input widget - a Label widget and an Entry widget.

Every Tkinter widget is governed by or belongs to another widget called its "parent" (the widgets that belong to another are called that widget’s "children"). The one widget in a GUI that doesn't have a parent is the master (or root) window. All other widgets should be the root window's children. Also, a widget is usually physically located inside of their parent. This is the basic structure. Now let’s begin building ours. Step one is to create our root window:

[python]root1 = tk.Tk()[/python]

A Tkinter Tk object is our root window that we can stuff with children. The first is our Label.

[python]
label = tk.Label(root1, text='our label widget')
[/python]

Presto, we have a Label. The first argument we used was the name of the parent (root1). The second argument was a standard keyword option for Labels to set the text it will display, if any.

Next we initialize our input widget, the Entry:

[python]
entry = tk.Entry(root1)
[/python]

With the Label and Entry widgets initialized and options we want set, what’s left is to tell Tkinter to physically put them inside their parent on the screen. Though we set the parent and options, our widgets won't be displayed unless we specifically tell Tkinter to display them.

To handle this process smoothly, Tkinter provides some built-in graphical organizers called geometry managers. The following table has descriptions of each of the geometry managers available.

As we can see from the description of the third manager, the pack and grid managers are the ones used for regular common layouts, and we’ll be using pack for this GUI. We want our Label to be on top of the Entry, so we’ll pack it first and use an option to set it on top, then pack the Entry after that (it will automatically show below the Label):

[python]
label.pack(side=tk.TOP)
entry.pack()
[/python]

Done! Now our widgets will be seen. However, you’ll notice that if you’re in Python 2.7 IDLE, no GUI has shown up yet. Just as with any other widget, Tkinter must be told to display the root window, but for the root window instead of a geometry manager the main Tk loop has to be called, like so:

[python]
root1.mainloop()
[/python]

Now we should be able to see a new window that looks something like this...

It might differ depending on your settings/environment, but not by much. With the Entry box we can type as much text as we want into the window, though it won’t do anything but sit there since we haven’t made it to do anything else (even if we hit “Enter,” the same goes for the Label).

Let’s close this one and look at an example with more widgets. We’ll also take a quick look at event bindings and the grid manager. Note that after we close our GUI, our root window and all its children will become unusable, as you’ll discover if you try to start root1’s mainloop again, or try to change label’s configuration.

For our second GUI we’ll have a Label and 3 Radiobuttons. We’ll start as we did before with the root window, then initializing the Label:

[python]
root2 = tk.Tk()
label2 = tk.Label(root2, text='Choose a button')
[/python]

We have our root window and Label now, but before initializing the Radiobuttons we’ll create a Tkinter variable object to keep track of the values that each Radiobutton holds:

[python]
# Object of the Tkinter StringVar class
buttonstr = tk.StringVar()
[/python]

Now we’ll create the three Radiobuttons and connect their values to our buttonstr variable:

[python]
buttonA = tk.Radiobutton(root2, text='Button A', variable=buttonstr, value='ButtonA string')
buttonB = tk.Radiobutton(root2, text='Button B', variable=buttonstr, value='ButtonB string')
buttonC = tk.Radiobutton(root2, text='Button C', variable=buttonstr, value='ButtonC string')
[/python]

With our Radiobuttons created, we’ll now examine what happens when we use callbacks to connect methods to each of them. Callbacks are used to tell the GUI to perform some command or action when a widget becomes active. We’ll use callbacks to print the value for each Radiobutton when it’s selected:

[python]
def showstr(event=None):
print(buttonstr.get())
[/python]

This function we just defined does nothing more than print the value of our StringVar accessed using its get() method. We can now reference this function as a callback in our Radiobuttons by using the command options:

[python]
buttonA.config(command=showstr)
buttonB.config(command=showstr)
buttonC.config(command=showstr)
[/python]

Alright now that all of our widgets are initialized we’ll set them up for display with the grid manager:

[python]
label2.grid(column=0, row=0)
buttonA.grid(column=0, row=1)
buttonB.grid(column=0, row=2)
buttonC.grid(column=0, row=3)
[/python]

We used the options column and row to tell grid exactly where to place the widgets, but if we didn’t grid would display them in the default order (column is zero). Without further ado, we’ll now run our GUI.

[python]
root2.mainloop()
[/python]

It should look like this:

Note: before we have selected one it appears that all of the Radiobuttons are selected—this is simply because we did not select a default Radiobutton with the select() method. If we had used this method on the first button, it would display like so:

[python]
buttonA.select()
root2.mainloop()
[/python]

Now if we select any of the radio-buttons (for example, A then C then B), then we should see the results of the callbacks for each of them:

[python]
>>> root2.mainloop()
ButtonA string
ButtonC string
ButtonB string
[/python]

In addition to callbacks which are used to link functions to the command options of widgets, event bindings can be used to link certain user “events” (e.g. keystrokes and mouse clicks) to widgets that lack a command option. Let’s try this with our first GUI example. With all other settings the same, right after packing the Entry box and before starting root1’s mainloop we’ll set an event binding for the “Enter” key so that if it’s pressed, the text in the Entry box will be printed to the IDLE window. We’ll need a method to do this first:

[python]
# Prints the entry text
def showentry(event):
print(entry.get())
[/python]

Now that we have the method to display entry’s text, we have to bind the event (when the user hits the “Enter” key with the entry box in focus):

[python]
>>> entry.bind('<Return>', showentry)
'29748480showentry'
[/python]

With this line we used the bind method (available to every widget) to connect our keyboard event (the first argument) to our method (the second argument). Also note that our event name is for the return key, and NOT as this marks a completely different kind of event in Tkinter. The short string of numbers followed by our function name that was returned can be ignored, it doesn’t mean anything special to us.

If we now run the mainloop of the root window, type some text into our Entry box, and hit the Enter key, Python will display what we typed (try it!). This same functionality can be used with any widget in your Tkinter GUI, and also multiple widgets can be bound simultaneously with the bind_all and bind_class methods. In the same way unbound with the unbind, unbind_all, and unbind_class methods.

That wraps up our introduction to the Python Tkinter library—the tools it provides are basic compared to some of the other third-party packages available out there, but don’t be afraid to get creative with it!