This article covers the Tkinter Toplevel widget

Tkinter works with a hierarchical system, where there is one root window from where all other widgets and windows expand from. Calling the Tk() function initializes the whole Tkinter application.

Often while creating a GUI, you wish to have more than just one window. Instead of calling the Tk() function again (which is the incorrect way) you should use the Tkinter Toplevel widget instead.


Calling the Tk() function creates a whole Tkinter instance, while calling the Toplevel() function only creates a window under the root Tkinter instance.

Destroying the Tk() function instance will destroy the whole GUI, whereas destroying the Toplevel() function only destroys that window and it’s child widgets, but not the whole program.

Toplevel syntax

window = Toplevel(options.....)

Toplevel Options

List of all relevant options available for the Toplevel widget.

1bgBackground color for the area around the widget.
2bdSize of the border around the widget. Default value is 2 pixels.
3cursor When the mouse is hovering over this widget, it can be changed to a special cursor type like an arrow or dot.
4font The type of font to be used for this widget.
5fg The color for the text.
6heightThe height of the widget in terms of text lines.
7reliefIt specifies the type of the border. Default is Flat, other options include RAISED and SUNKEN.
8widthWidth of the Checkbutton.

Toplevel Example

This is a simple Toplevel function example simply to demonstrate how it works.

from tkinter import *

root = Tk()
window = Toplevel()

Tkinter Toplevel
Tkinter Toplevel

This isn’t a very practical approach though, so we’ll discuss a more real life scenario in the next example.

Toplevel Example 2

In this example we’ll show you another way calling a new window. In most software, you start off with one window and can spawn multiple windows such as a “Settings Window”. This is in contrast to the previous example where we started directly with 2 windows.

The code below creates a button, that when clicked calls a function that creates a new Toplevel window with a widget in it. You might find this approach more suitable for your GUI.

from tkinter import *

def NewWindow():
    window = Toplevel()
    newlabel = Label(window, text = "Settings Window")

root = Tk()

myframe = Frame(root)

mybutton = Button(myframe, text = "Settings", command = NewWindow)
mybutton.pack(pady = 10)

Tkinter Toplevel

Only use multiple windows when it makes sense to have more than one. It makes sense to have a separate window dedicated to settings, especially when it’s a large software when dozens of different settings.

Toplevel Methods

Another benefit of using Toplevel is the dozen different methods available to it that provide extra functionality.

Amongst the most useful these methods are withdraw() and deiconify() which can be used to withdraw and display the window respectively. Useful if you want to make the window disappear without destroying it. And also the resizable, maxsize(), minsize() and title methods. Explanations mentioned below in the table.

Most of these methods are self-explanatory enough that you shouldn’t require any explanation beyond what is written here. The rest will be covered in another article soon, or you can always google it if you ever need it.

1deiconify()Used to display the Toplevel window. Only use after using either the withdraw() or iconify() methods.
2frame()Returns a system-specific window identifier.
3group(window) Two windows are involved here. The window passed into the group() gets added to the group in which the window on which the method was used, is.
4iconify() Turns the window into an icon. Sort of like minimizing.
5protocol(name, function) Links a function to a name, which can be used to call it.
6state()Used to get the current state of the window. Possible values are normal, iconic, withdrawn, and icon.
7resizable(width, height) Controls whether, or how much the toplevel window can be resized.
8withdraw()Withdraws the function (causing it to disappear) without actually destroying it, or any of the widgets in it.
9title(string)Defines a title for the toplevel window.

This marks the end of the Python Tkinter Toplevel article. Any suggestions or contributions for CodersLegacy are more than welcome. Relevant questions regarding the article material can be asked in the comments section below.

To learn about other awesome widgets in Tkinter, follow this link!