title: What does the"wait_window" method do?
body: <p>It seems that the object that calls this method <em>waits for the window passed as parameter to be destroyed before continue with its own loop</em>... </p>
  
  <p>From the doc strings of the <code>Misc</code> class, we can observe:</p>
  
  <blockquote>
  <pre><code>def wait_window(self, window=None):
      """Wait until a WIDGET is destroyed.
      If no parameter is given self is used."""
  </code></pre>
  </blockquote>
  
  <p>At first glance, it seems like this method can make a <code>Toplevel</code> modal, but this is not true. To make a <code>Toplevel</code> modal, we have to use the <code>grab_set()</code> method.</p>
  
  <p>I have see around other explanations:</p>
  
  <blockquote>
    <p><code>wait_window</code> seems to not return until the given widget passed as parameter
    is not destroyed.</p>
  </blockquote>
  
  <p>From another place:</p>
  
  <blockquote>
    <p><code>wait_window(widget)</code> - Creates a local event that waits for the given
    widget to be destroyed. This loop doesn't affect the application's
    mainloop.</p>
  </blockquote>
  
  <p>From the <a href="http://effbot.org/tkinterbook/tkinter-dialog-windows.htm" rel="noreferrer">effbot</a> documentation, we have:</p>
  
  <blockquote>
    <p><em>The <code>wait_window</code> 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):</em></p>
  
  <pre><code>widget.wait_window(window)
  </code></pre>
  </blockquote>
  
  <p>What exactly means for a <code>window</code> to wait for <code>window</code> (itself)?</p>
  
  <p>It seems that the code that comes after the call to <code>wait_window</code> 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:</p>
  
  <pre><code>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()
  </code></pre>
  
  <p><code>"Mini-event loop finished!"</code> will be printed only when the local <code>Toplevel</code> widget called <code>dialog</code> is destroyed.</p>
  
  <p>So, in exactly what real circumstances should I use this method?</p>