9.3. Top-Level WindowsTkinter GUIs always have a root window, whether you get it by default or create it explicitly by calling the Tk object constructor. This main root window is the one that opens when your program runs, and it is where you generally pack your most important widgets. In addition, Tkinter scripts can create any number of independent windows, generated and popped up on demand, by creating Toplevel widget objects. Each Toplevel object created produces a new window on the display and automatically adds it to the program's GUI event-loop processing stream (you don't need to call the mainloop method of new windows to activate them). Example 9-3 builds a root and two pop-up windows. Example 9-3. PP3E\Gui\Tour\toplevel0.py
The toplevel0 script gets a root window by default (that's what the Label is attached to, since it doesn't specify a real parent), but it also creates two standalone Toplevel windows that appear and function independently of the root window, as seen in Figure 9-3. Figure 9-3. Two Toplevel windows and a root windowThe two Toplevel windows on the right are full-fledged windows; they can be independently iconified, maximized, and so on. Toplevels are typically used to implement multiple-window displays and pop-up modal and nonmodal dialogs (more on dialogs in the next section). They stay up until they are explicitly destroyed or until the application that created them exits. It's important to know that although Toplevels are independently active windows, they are not separate processes; if your program exits, all of its windows are erased, including all Toplevel windows it may have created. We'll learn how to work around this rule later by launching independent GUI programs. 9.3.1. Toplevel and Tk WidgetsA Toplevel is roughly like a Frame that is split off into its own window, and has additional methods that allow you to deal with top-level window properties. The Tk widget is roughly like a Toplevel, but it is used to represent the application root window. We got one for free in Example 9-3 because the Label had a default parent; in other scripts, we've made the Tk root more explicit by creating it directly, like this: root = Tk( ) Label(root, text='Popups').pack() # on explicit Tk( ) root window root.mainloop( ) In fact, because Tkinter GUIs are built as a hierarchy, you always get a root window by default, whether it is named explicitly, as here, or not. You should generally use the root to display top-level information of some sort; if you don't attach widgets to the root, it shows up as an odd empty window when you run your script. Technically, you can suppress the default root creation logic and make multiple root windows with the Tk widget, as in Example 9-4. Example 9-4. PP3E\Gui\Tour\toplevel1.py
When run, this script displays the two pop-up windows of the screenshot in Figure 9-3 only (there is no third root window). But it's more common to use the Tk root as a main window and create Toplevel widgets for an application's pop-up windows. 9.3.2. Top-Level Window ProtocolsBoth Tk and Toplevel widgets export extra methods and features tailored for their top-level role, as illustrated in Example 9-5. Example 9-5. PP3E\Gui\Tour\toplevel2.py
This program adds widgets to the Tk root window, immediately pops up three Toplevel windows with attached buttons, and uses special top-level protocols. When run, it generates the scene captured in living black-and-white in Figure 9-4 (the buttons' text shows up blue, green, and red on a color display). Figure 9-4. Three Toplevel windows with configurationsThere are a few operational details worth noticing here, all of which are more obvious if you run this script on your machine:
In addition, top-level window widgets support other kinds of protocols that we will utilize later on in this tour:
Most top-level window-manager-related methods can also be named with a "wm_" at the front; for instance, state and protocol can also be called wm_state and wm_protocol. Notice that the script in Example 9-3 passes its Toplevel constructor calls an explicit parent widgetthe Tk root window (that is, Toplevel(root)). Toplevels can be associated with a parent just as other widgets can, even though they are not visually embedded in their parents. I coded the script this way to avoid what seems like an odd feature; if coded instead like this: win = Toplevel( ) # new window and if no Tk root yet exists, this call actually generates a default Tk root window to serve as the Toplevel's parent, just like any other widget call without a parent argument. The problem is that this makes the position of the following line crucial: root = Tk( ) # explicit root If this line shows up above the Toplevel calls, it creates the single root window as expected. But if you move this line below the Toplevel calls, Tkinter creates a default Tk root window that is different from the one created by the script's explicit Tk call. You wind up with two Tk roots just as in Example 9-5. Move the Tk call below the Toplevel calls and rerun it to see what I mean. You'll get a fourth window that is completely empty! As a rule of thumb, to avoid such oddities, make your Tk root windows early on and make them explicit. All of the top-level protocol interfaces are available only on top-level window widgets, but you can often access them by going through other widgets' master attributeslinks to the widget parents. For example, to set the title of a window in which a frame is contained, say something like this: theframe.master.title('Spam demo') # master is the container window Naturally, you should do so only if you're sure that the frame will be used in only one kind of window. General-purpose attachable components coded as classes, for instance, should leave window property settings to their client applications. Top-level widgets have additional tools, some of which we may not meet in this book. For instance, under Unix window managers, you can also set the name used on the window's icon (iconname). Because some icon options may be useful when scripts run on Unix only, see other Tk and Tkinter resources for more details on this topic. For now, the next scheduled stop on this tour explores one of the more common uses of top-level windows. |