What does the"wait_window" method do?

Question

It seems that the object that calls this method waits for the window passed as parameter to be destroyed before continue with its own loop...

From the doc strings of the Misc class, we can observe:

def wait_window(self, window=None):
    """Wait until a WIDGET is destroyed.
    If no parameter is given self is used."""

At first glance, it seems like this method can make a Toplevel modal, but this is not true. To make a Toplevel modal, we have to use the grab_set() method.

I have see around other explanations:

wait_window seems to not return until the given widget passed as parameter is not destroyed.

From another place:

wait_window(widget) - Creates a local event that waits for the given widget to be destroyed. This loop doesn't affect the application's mainloop.

From the effbot documentation, we have:

The wait_window enters a local event loop, and doesn’t return until the given window is destroyed (either via the destroy method, or explicitly via the window manager):

widget.wait_window(window)

What exactly means for a window to wait for window (itself)?

It seems that the code that comes after the call to wait_window is not executed until the window passed to the same method is not destroyed. In the following working example, we can see a proof on what just said:

from tkinter import *

def on_win_request(parent):
    dialog = Toplevel()
    parent.wait_window(dialog)
    # executed only when "dialog" is destroyed
    print("Mini-event loop finished!")

r = Tk()
b = Button(r, text='New Window', command=lambda: on_win_request(r))
b.pack()
b2 = Button(r, text='Hello!', command=lambda: print("hello"))
b2.pack()
r.mainloop()

"Mini-event loop finished!" will be printed only when the local Toplevel widget called dialog is destroyed.

So, in exactly what real circumstances should I use this method?

Answer 1

Like the documentation states, it waits until the given window is destroyed. It is mostly used for modal popups, though it doesn't itself make a window modal. The call to the function simply doesn't return until the target window is destroyed To make a modal window you have to do a grab as well.

The most common use is to create an instance of Toplevel, populate that window with widgets, then wait for the window to be dismissed before doing some other action. While it is waiting, tkinter is able to continue to process events as normal.

For instance, you can disable (or defer creation of) the main GUI, pop up a "terms of service" notice, and wait for the user to acknowledge the terms of service, copyright, license, etc. Once the window is destroyed you can then finish initialization, or enable some widgets, etc.

The standard file dialog is a perfect example: you pop up the dialog, then your code waits for the user to pick a file, then it uses the filename that was returned. Internally, the implementation of the dialog uses wait_window so that it doesn't return until the dialog is dismissed.