Advanced GUI Coding Techniques

If you read Chapter 8, you know that the code used to construct non-trivial GUIs can become large if we make each widget by hand. Not only do we have to manually link up all the widgets, but there are dozens of options to be set and remember. If we stick to this strategy, GUI programming often becomes an exercise in typing, or at least in cut-and-paste text editor operations.

9.2.1 GuiMixin: Shared Behavior in "Mixin" Classes

Rather than doing each step by hand, a better idea is to wrap or automate as much of the GUI construction process as possible. One approach is to code functions that provide typical widget configurations; for instance, we could define a button function to handle configuration details and support most of the buttons we draw.

Alternatively, we can implement common methods in a class and inherit them everywhere they are needed. Such classes are commonly called mixin classes, because their methods are "mixed in" with other classes. Mixins serve to package generally useful tools as methods. The concept is almost like importing a module, but mixin classes can access the subject instance, self, to utilize per-instance state and inherited methods. The script in Example 9-1 shows how.

Example 9-1. PP2EGuiToolsguimixin.py

######################################################## # a "mixin" class for other frames: common methods for # canned-dialogs, spawning programs, etc; must be mixed # with a class derived from Frame for its quit method ######################################################## from Tkinter import * from tkMessageBox import * from tkFileDialog import * from ScrolledText import ScrolledText from PP2E.launchmodes import PortableLauncher, System class GuiMixin: def infobox(self, title, text, *args): # use standard dialogs return showinfo(title, text) # *args for bkwd compat def errorbox(self, text): showerror('Error!', text) def question(self, title, text, *args): return askyesno(title, text) def notdone(self): showerror('Not implemented', 'Option not available') def quit(self): ans = self.question('Verify quit', 'Are you sure you want to quit?') if ans == 1: Frame.quit(self) # quit not recursive! def help(self): self.infobox('RTFM', 'See figure 1...') # override this better def selectOpenFile(self, file="", dir="."): # use standard dialogs return askopenfilename(initialdir=dir, initialfile=file) def selectSaveFile(self, file="", dir="."): return asksaveasfilename(initialfile=file, initialdir=dir) def clone(self): new = Toplevel( ) # make a new version of me myclass = self.__class__ # instance's (lowest) class object myclass(new) # attach/run instance to new window def spawn(self, pycmdline, wait=0): if not wait: PortableLauncher(pycmdline, pycmdline)( ) # run Python progam else: System(pycmdline, pycmdline)( ) # wait for it to exit def browser(self, filename): new = Toplevel( ) # make new window text = ScrolledText(new, height=30, width=90) # Text with scrollbar text.config(font=('courier', 10, 'normal')) # use fixed-width font text.pack( ) new.title("Text Viewer") # set window mgr attrs new.iconname("browser") text.insert('0.0', open(filename, 'r').read( ) ) # insert file's text if __name__ == '__main__': class TestMixin(GuiMixin, Frame): # stand-alone test def __init__(self, parent=None): Frame.__init__(self, parent) self.pack( ) Button(self, text='quit', command=self.quit).pack(fill=X) Button(self, text='help', command=self.help).pack(fill=X) Button(self, text='clone', command=self.clone).pack(fill=X) TestMixin().mainloop( )

Although Example 9-1 is geared towards GUIs, it's really about design concepts. The GuiMixin class implements common operations with standard interfaces that are immune to changes in implementation. In fact, the implementations of some of this class's method did change -- between the first and second editions of this book, old-style Dialog calls were replaced with the new Tk standard dialog calls. Because this class's interface hides such details, its clients did not have to be changed to use the new dialog techniques.

As is, GuiMixin provides methods for common dialogs, window cloning, program spawning, text file browsing, and so on. We can add more methods to such a mixin later if we find ourselves coding the same methods repeatedly; they will all become available immediately everywhere this class is imported and mixed. Moreover, GuiMixin's methods can be inherited and used as is, or they can be redefined in subclasses.

There are a few things to notice here:

• The quit method serves some of the same purpose as the reusable Quitter button we used in earlier chapters. Because mixin classes can define a large library of reusable methods, they can be a more powerful way to package reusable components than individual classes. If the mixin is packaged well, we can get a lot more from it than a single button's callback.
• The clone method makes a new copy of the most specific class that mixes in a GuiMixin, in a new top-level window (self.__class__ is the class object that the instance was created from). This opens a new independent copy of the window.
• The browser method opens the standard library's ScrolledText object in a new window and fills it with the text of a file to be viewed. We wrote our own ScrolledText in the last chapter; you might need to use it here instead, if the standard library's class ever becomes deprecated (please, no wagering).
• The spawn method launches a Python program command line as a new process, and waits for it to end or not (depending on the wait argument). This method is simple, though, because we wrapped launching details in the launchmodes module presented at the end of Chapter 3. GuiMixin both fosters and practices good code reuse habits.

The GuiMixin class is meant to be a library of reusable tool methods and is essentially useless by itself. In fact, it must generally be mixed with a Frame-based class to be used: quit assumes it's mixed with a Frame, and clone assumes it's mixed with a widget class. To satisfy such constraints this module's self-test code at the bottom combines GuiMixin with a Frame widget. Figure 9-1 shows the scene created by the self-test after pressing "clone" twice, and then "help" in one of the three copies.

Figure 9-1. GuiMixin self-test code in action

We'll see this class show up again as a mixin in later examples, too -- that's the whole point of code reuse, after all.

9.2.2 GuiMaker: Automating Menus and Toolbars

The last section's mixin class makes common tasks simpler, but it still doesn't address the complexity of linking up widgets like menus and toolbars. Of course, if we had access to a GUI layout tool that generated Python code, this would not be an issue. We'd design our widgets interactively, press a button, and fill in the callback handler blanks.

For now, a programming-based approach can work just as well. What we'd like is to be able to inherit something that does all the grunt work of construction for us, given a template for the menus and toolbars in a window. Here's one way it can be done -- using trees of simple objects. The class in Example 9-2 interprets data structure representations of menus and toolbars, and builds all the widgets automatically.

Example 9-2. PP2EGuiToolsguimaker.py

############################################################################### # An extended Frame that makes window menus and tool-bars automatically. # Use GuiMakerFrameMenu for embedded components (makes frame-based menus). # Use GuiMakerWindowMenu for top-level windows (makes Tk8.0 window menus). # See the self-test code (and PyEdit) for an example layout tree format. ############################################################################### import sys from Tkinter import * # widget classes from types import * # type constants class GuiMaker(Frame): menuBar = [] # class defaults toolBar = [] # change per instance in subclasses helpButton = 1 # set these in start( ) if need self def __init__(self, parent=None): Frame.__init__(self, parent) self.pack(expand=YES, fill=BOTH) # make frame stretchable self.start( ) # for subclass: set menu/toolBar self.makeMenuBar( ) # done here: build menu-bar self.makeToolBar( ) # done here: build tool-bar self.makeWidgets( ) # for subclass: add middle part def makeMenuBar(self): """ make menu bar at the top (Tk8.0 menus below) expand=no, fill=x so same width on resize """ menubar = Frame(self, relief=RAISED, bd=2) menubar.pack(side=TOP, fill=X) for (name, key, items) in self.menuBar: mbutton = Menubutton(menubar, text=name, underline=key) mbutton.pack(side=LEFT) pulldown = Menu(mbutton) self.addMenuItems(pulldown, items) mbutton.config(menu=pulldown) if self.helpButton: Button(menubar, text = 'Help', cursor = 'gumby', relief = FLAT, command = self.help).pack(side=RIGHT) def addMenuItems(self, menu, items): for item in items: # scan nested items list if item == 'separator': # string: add separator menu.add_separator({}) elif type(item) == ListType: # list: disabled item list for num in item: menu.entryconfig(num, state=DISABLED) elif type(item[2]) != ListType: menu.add_command(label = item[0], # command: underline = item[1], # add command command = item[2]) # cmd=callable else: pullover = Menu(menu) self.addMenuItems(pullover, item[2]) # sublist: menu.add_cascade(label = item[0], # make submenu underline = item[1], # add cascade menu = pullover) def makeToolBar(self): """ make button bar at bottom, if any expand=no, fill=x so same width on resize """ if self.toolBar: toolbar = Frame(self, cursor='hand2', relief=SUNKEN, bd=2) toolbar.pack(side=BOTTOM, fill=X) for (name, action, where) in self.toolBar: Button(toolbar, text=name, command=action).pack(where) def makeWidgets(self): """ make 'middle' part last, so menu/toolbar is always on top/bottom and clipped last; override this default, pack middle any side; for grid: grid middle part in a packed frame """ name = Label(self, width=40, height=10, relief=SUNKEN, bg='white', text = self.__class__.__name__, cursor = 'crosshair') name.pack(expand=YES, fill=BOTH, side=TOP) def help(self): """ override me in subclass """ from tkMessageBox import showinfo showinfo('Help', 'Sorry, no help for ' + self.__class__.__name__) def start(self): pass # override me in subclass ############################################################################### # For Tk 8.0 main window menubar, instead of a frame ############################################################################### GuiMakerFrameMenu = GuiMaker # use this for embedded component menus class GuiMakerWindowMenu(GuiMaker): # use this for top-level window menus def makeMenuBar(self): menubar = Menu(self.master) self.master.config(menu=menubar) for (name, key, items) in self.menuBar: pulldown = Menu(menubar) self.addMenuItems(pulldown, items) menubar.add_cascade(label=name, underline=key, menu=pulldown) if self.helpButton: if sys.platform[:3] == 'win': menubar.add_command(label='Help', command=self.help) else: pulldown = Menu(menubar) # linux needs real pulldown pulldown.add_command(label='About', command=self.help) menubar.add_cascade(label='Help', menu=pulldown) ############################################################################### # Self test when file run stand-alone: 'python guimaker.py' ############################################################################### if __name__ == '__main__': from guimixin import GuiMixin # mixin a help method menuBar = [ ('File', 0, [('Open', 0, lambda:0), # lambda:0 is a no-op ('Quit', 0, sys.exit)]), # use sys, no self here ('Edit', 0, [('Cut', 0, lambda:0), ('Paste', 0, lambda:0)]) ] toolBar = [('Quit', sys.exit, {'side': LEFT})] class TestAppFrameMenu(GuiMixin, GuiMakerFrameMenu): def start(self): self.menuBar = menuBar self.toolBar = toolBar class TestAppWindowMenu(GuiMixin, GuiMakerWindowMenu): def start(self): self.menuBar = menuBar self.toolBar = toolBar class TestAppWindowMenuBasic(GuiMakerWindowMenu): def start(self): self.menuBar = menuBar self.toolBar = toolBar # guimaker help, not guimixin root = Tk( ) TestAppFrameMenu(Toplevel( )) TestAppWindowMenu(Toplevel( )) TestAppWindowMenuBasic(root) root.mainloop( )

To make sense of this module, you have to be familiar with the menu fundamentals introduced in the last chapter. If you are, though, it's straightforward -- the GuiMaker class simply traverses the menu and toolbar structures and builds menu and toolbar widgets along the way. This module's self-test code includes a simple example of the data structures used to lay out menus and toolbars:

Menubar templates

Lists and nested sublists of (label, underline, handler) triples. If a handler is a sublist instead of a function or method, it is assumed to be a cascading submenu.

Toolbar templates

List of (label, handler, pack-options) triples. pack-options is coded as a dictionary of options passed on to the widget pack method (it accepts dictionaries, but we could also transform the dictionary into keyword arguments by passing it as a third argument to apply).

9.2.2.1 Subclass protocols

In addition to menu and toolbar layouts, clients of this class can also tap into and customize the method and geometry protocols it implements:

Template attributes

Clients of this class are expected to set menuBar and toolBar attributes somewhere in the inheritance chain by the time the start method has finished.

Initialization

The start method can be overridden to construct menu and toolbar templates dynamically (since self is then available); start is also where general initializations should be performed -- GuiMixin's __init__ constructor must be run, not overridden.

Adding widgets

The makeWidgets method can be redefined to construct the middle part of the window -- the application portion between the menubar and toolbar. By default, makeWidgets adds a label in the middle with the name of the most specific class, but this method is expected to be specialized.

Packing protocol

In a specialized makeWidgets method, clients may attach their middle portion's widgets to any side of "self" (a Frame), since the menu and toolbars have already claimed the container's top and bottom by the time makeWidgets is run. The middle part does not need to be a nested frame if its parts are packed. The menu and toolbars are also automatically packed first so that they are clipped last if the window shrinks.

Gridding protocol

The middle part can contain a grid layout, as long as it is gridded in a nested Frame that is itself packed within the self parent. (Remember, that each container level may use grid or pack, not both, and self is a Frame with already-packed bars by the time makeWidgets is called.) Because the GuiMaker Frame packs itself within its parent, it is not directly embeddable in a container with widgets arranged in a grid for similar reasons -- add an intermediate gridded Frame to use it in this context.

9.2.2.2 GuiMaker classes

In return for conforming to GuiMaker protocols and templates, client subclasses get a Frame that knows how to automatically build up its own menus and toolbars from template data structures. If you read the last chapter's menu examples, you probably know that this is a big win in terms of reduced coding requirements. GuiMaker is also clever enough to export interfaces for both menu styles that we met in the last chapter:

• GuiMakerWindowMenu implements Tk 8.0-style top-level window menus, useful for menus associated with standalone programs and pop-ups.
• GuiMakerFrameMenu implements alternative Frame/Menubutton-based menus, useful for menus on objects embedded as components of a larger GUI.

Both classes build toolbars, export the same protocols, and expect to find the same template structures; they differ only in the way they process menu templates. In fact, one is simply a subclass of the other with a specialized menu maker method -- only top-level menu processing differs between the two styles (a Menu with Menu cascades, instead of a Frame with Menubuttons).

9.2.2.3 GuiMaker self-test

Like GuiMixin, when we run Example 9-2 as a top-level program, we trigger the self-test logic at the bottom; Figure 9-2 shows the windows we get. Three windows come up, representing each of the self-test code's TestApp classes. All three have a menu and toolbar with the options specified in the template data structures created in the self-test code: File and Edit menu pull-downs, plus a Quit toolbar button, and a standard Help menu button. In the screen shot, one window's File menu has been torn off, and the Edit menu of another is being pulled down.

Figure 9-2. GuiMaker self-test at work

Because of the superclass relationships coded, two of the three windows get their help callback handler from GuiMixin; TestAppWindowMenuBasic gets GuiMaker's instead. Notice that the order in which these two classes are mixed can be important: because both GuiMixin and Frame define a quit method, we need to list the class we want to get it from first in the mixed class's header line due to the left-to-right search rule of multiple inheritance. To select GuiMixin's methods, it should usually be listed before a superclass derived from real widgets.

We'll put GuiMaker to more practical use in examples such as PyEdit later in this chapter. The next module shows another way to use GuiMaker's templates to build up a sophisticated interface.

9.2.3 BigGui: A Client Demo Program

Let's look at a program that makes better use of the two automation classes we just wrote. In the module in Example 9-3, the Hello class inherits from both GuiMixin and GuiMaker. GuiMaker provides the link to the Frame widget, plus the menu/toolbar construction logic. GuiMixin provides extra common-behavior methods. Really, Hello is another kind of extended Frame widget because it is derived from GuiMaker. To get a menu and toolbar for free, it simply follows the protocols defined by GuiMaker -- it sets the menuBar and toolBar attributes in its start method, and overrides makeWidgets to put a label in the middle.

Example 9-3. PP2EGuiToolsBigGuiig_gui.py

#!/usr/bin/python ######################################################### # gui implementation - combines maker, mixin, and this ######################################################### import sys, os, string from Tkinter import * # widget classes from PP2E.Gui.Tools.guimixin import * # mix-in methods from PP2E.Gui.Tools.guimaker import * # frame, plus menu/toolbar builder from find_demo_dir import findDemoDir # Python demos search class Hello(GuiMixin, GuiMakerWindowMenu): # or GuiMakerFrameMenu def start(self): self.hellos = 0 self.master.title("GuiMaker Demo") self.master.iconname("GuiMaker") self.menuBar = [ # a tree: 3 pulldowns ('File', 0, # (pull-down) [('New...', 0, self.notdone), # [menu items list] ('Open...', 0, self.fileOpen), ('Quit', 0, self.quit)] # label,underline,action ), ('Edit', 0, [('Cut', -1, self.notdone), # no underline|action ('Paste',-1, self.notdone), # lambda:0 works too 'separator', # add a separator ('Stuff', -1, [('Clone', -1, self.clone), # cascaded submenu ('More', -1, self.more)] ), ('Delete', -1, lambda:0), [5]] # disable 'delete' ), ('Play', 0, [('Hello', 0, self.greeting), ('Popup...', 0, self.dialog), ('Demos', 0, [('Hanoi', 0, lambda x=self: x.spawn(findDemoDir( ) + 'guidohanoi.py', wait=0)), ('Pong', 0, lambda x=self: x.spawn(findDemoDir( ) + 'mattpong-demo-1.py', wait=0)), ('Other...', -1, self.pickDemo)] )] )] self.toolBar = [ ('Quit', self.quit, {'side': RIGHT}), # add 3 buttons ('Hello', self.greeting, {'side': LEFT}), ('Popup', self.dialog, {'side': LEFT, 'expand':YES}) ] def makeWidgets(self): # override default middle = Label(self, text='Hello maker world!', width=40, height=10, cursor='pencil', bg='white', relief=SUNKEN) middle.pack(expand=YES, fill=BOTH) def greeting(self): self.hellos = self.hellos + 1 if self.hellos % 3: print "hi" else: self.infobox("Three", 'HELLO!') # on every third press def dialog(self): button = self.question('OOPS!', 'You typed "rm*" ... continue?', 'questhead', ('yes', 'no', 'help')) [lambda:0, self.quit, self.help][button]( ) def fileOpen(self): pick = self.selectOpenFile(file='big_gui.py') if pick: self.browser(pick) # browse my source file, or other def more(self): new = Toplevel( ) Label(new, text='A new non-modal window').pack( ) Button(new, text='Quit', command=self.quit).pack(side=LEFT) Button(new, text='More', command=self.more).pack(side=RIGHT) def pickDemo(self): pick = self.selectOpenFile(dir=findDemoDir( )+'guido') if pick: self.spawn(pick, wait=0) # spawn any python program if __name__ == '__main__': Hello().mainloop( ) # make one, run one

This script lays out a fairly large menu and toolbar structure that we'll see in moment. It also adds callback methods of its own that print stdout messages, pop up text file browsers and new windows, and run other programs. Many of the callbacks don't do much more than run the notDone method inherited from GuiMixin, though; this code is intended mostly as a GuiMaker and GuiMixin demo.

The big_gui script is almost a complete program, but not quite: it relies on a utility module to search for canned demo programs that come packaged with the Python full source distribution. (These demos are not part of this book's example collection.) The Python source distribution might be unpacked anywhere on the host machine.

Because of that, it's impossible to know where the demo directory is located (if it is present at all). But rather than expecting beginners to change the source code of this script to hardcode a path, the guessLocation tool in the Launcher module we met at the end of Chapter 4 is used to hunt for the demo directory (see Example 9-4). Flip back if you've forgotten how this works (though the beauty of code reuse is that it's often okay to forget).

Example 9-4. PP2EGuiToolsBigGuifind_demo_dir.py

######################################################### # search for demos shipped in Python source distribution; # PATH and PP2EHOME won't help here, because these demos # are not part of the standard install or the book's tree ######################################################### import os, string, PP2E.Launcher demoDir = None myTryDir = '' #sourceDir = r'C:StuffEtcPython-ddj-cddistributions' #myTryDir = sourceDir + r'Python-1.5.2Demo kinter' def findDemoDir( ): global demoDir if not demoDir: # only searches on first call if os.path.exists(myTryDir): # use hard-coded dir, or search demoDir = myTryDir # save in global for next call else: print 'Searching for standard demos on your machine...' path = PP2E.Launcher.guessLocation('hanoi.py') if path: demoDir = string.join(string.split(path, os.sep)[:-2], os.sep) print 'Using demo dir:', demoDir assert demoDir, 'Where is your demo directory?' return demoDir

When big_gui is run as a top-level program, it creates a window with four menu pull-downs on top, and a three-button toolbar on the bottom, shown in Figure 9-3 along with some of the pop-up windows its callbacks create. The menus have separators, disabled entries, and cascading submenus, all as defined by the menuBar template.

Figure 9-3. big_gui with various pop-ups

Figure 9-4 shows this script's window again, after its Play pull-down has been used to launch two independently running instances of the hanoi.py demo script that is shipped in the Python source distribution and coded by Python creator Guido van Rossum. This demo shows a simple animation of solutions to the "Towers of Hanoi" puzzle -- a classic recursive problem popular on computer science quizzes (if you never heard of it, I'll spare you the gory details here).

Figure 9-4. big_gui with spawned hanoi demos on the move

To find this demo, the script searches directory trees on your machine rooted at common places; it was found on mine only by a last-resort traversal of my entire C: hard drive:

C:...PP2EGuiToolsBigGui>python big_gui.py Searching for standard demos on your machine... Searching for hanoi.py in C:Program FilesPython Searching for hanoi.py in C:PP2ndEdexamplesPP2EGuiToolsBigGui Searching for hanoi.py in C:Program Files Searching for hanoi.py in C: Using demo dir: C:PP2ndEdcdromPython1.5.2SourceDistributionUnpackedPython- 1.5.2Demo kinter C:PP2ndEdcdromPython1.5.2SourceDistributionUnpackedPython-1.5.2Demo kint erguidohanoi.py

This search takes about 20 seconds on my 650 MHz Windows laptop, but is done only the first time you select one of these demos -- after a successful search, the find_demo_dir module caches away the directory name in a global variable for immediate retrieval the next time you start a demo. If you want to run demos from other directories (e.g., one of the book demos in the PP2E tree), select the Play menu's Other option to pop up a standard file selection dialog instead and navigate to the desired program's file.

Finally, I should note that GuiMaker can be redesigned to use trees of embedded class instances that know how to apply themselves to the Tkinter widget tree being constructed, instead of branching on the types of items in template data structures. In the interest of space, though, we'll banish that extension to the land of suggested exercises in this edition.

9.2.4 ShellGui: Adding GUIs to Command-Line Tools

To better show how things like the GuiMixin class can be of practical use, we need a more realistic application. Here's one: in Chapter 4, we saw simple scripts for packing and unpacking text files (see Section 4.5). The packapp.py script we met there, you'll recall, concatenates multiple text files into a single file, and unpackapp.py extracts the original files from the combined file.

We ran these scripts in that chapter with manually typed command lines that weren't the most complex ever devised, but were complicated enough to be easily forgotten. Rather than requiring users of such tools to type cryptic commands at a shell, why not also provide an easy-to-use Tkinter GUI interface for running such programs? While we're at it, why not generalize the whole notion of running command-line tools from a GUI, to make it easy to support future tools, too?

9.2.4.1 A generic shell-tools display

Examples Example 9-5 through Example 9-8 are one concrete implementation of these artificially rhetorical musings. Because I wanted this to be a general-purpose tool that could run any command-line program, its design is factored into modules that become more application-specific as we go lower in the software hierarchy. At the top, things are about as generic as they can be, as shown in Example 9-5.

Example 9-5. PP2EGuiShellGuishellgui.py.py

#!/usr/local/bin/python ##################################################################### # tools launcher; uses guimaker templates, guimixin std quit dialog; # I am just a class library: run mytools script to display the gui; ##################################################################### from Tkinter import * # get widgets from PP2E.Gui.Tools.guimixin import GuiMixin # get quit, not done from PP2E.Gui.Tools.guimaker import * # menu/toolbar builder class ShellGui(GuiMixin, GuiMakerWindowMenu): # a frame + maker + mixins def start(self): # use GuiMaker if component self.setMenuBar( ) self.setToolBar( ) self.master.title("Shell Tools Listbox") self.master.iconname("Shell Tools") def handleList(self, event): # on listbox double-click label = self.listbox.get(ACTIVE) # fetch selection text self.runCommand(label) # and call action here def makeWidgets(self): # add listbox in middle sbar = Scrollbar(self) # cross link sbar, list list = Listbox(self, bg='white') # or use Tour.ScrolledList sbar.config(command=list.yview) list.config(yscrollcommand=sbar.set) sbar.pack(side=RIGHT, fill=Y) # pack 1st=clip last list.pack(side=LEFT, expand=YES, fill=BOTH) # list clipped first for (label, action) in self.fetchCommands( ): # add to list-box list.insert(END, label) # and menu/toolbars list.bind('', self.handleList) # set event handler self.listbox = list def forToolBar(self, label): # put on toolbar? return 1 # default = all def setToolBar(self): self.toolBar = [] for (label, action) in self.fetchCommands( ): if self.forToolBar(label): self.toolBar.append((label, action, {'side': LEFT})) self.toolBar.append(('Quit', self.quit, {'side': RIGHT})) def setMenuBar(self): toolEntries = [] self.menuBar = [ ('File', 0, [('Quit', -1, self.quit)]), # pull-down name ('Tools', 0, toolEntries) # menu items list ] # label,underline,action for (label, action) in self.fetchCommands( ): toolEntries.append((label, -1, action)) # add app items to menu ################################################### # delegate to template type-specific subclasses # which delegate to app toolset-specific subclasses ################################################### class ListMenuGui(ShellGui): def fetchCommands(self): # subclass: set 'myMenu' return self.myMenu # list of (label, callback) def runCommand(self, cmd): for (label, action) in self.myMenu: if label == cmd: action( ) class DictMenuGui(ShellGui): def fetchCommands(self): return self.myMenu.items( ) def runCommand(self, cmd): self.myMenu[cmd]( )

The ShellGui class in this module knows how to use the GuiMaker and GuiMix interfaces to construct a selection window that displays tool names in menus, a scrolled list, and a toolbar. It also provides an overridable forToolBar method that allows subclasses to specify which tools should and should not be added to the window's toolbar (the toolbar can get crowded in a hurry). However, it is deliberately ignorant about both the names of tools that should be displayed in those places, and the actions to be run when tool names are selected.

Instead, ShellGui relies on the ListMenuGui and DictMenuGui subclasses in this file to provide a list of tool names from a fetchCommands method and dispatch actions by name in a runCommand method. These two subclasses really just serve to interface to application-specific tool sets laid out as lists or dictionaries, though; they are still naive about what tool names really go up on the GUI. That's by design, too -- because the tool sets displayed are defined by lower subclasses, we can use ShellGui to display a variety of different tool sets.

9.2.4.2 Application-specific tool set classes

To get to the actual tool sets, we need to go one level down. The module in Example 9-6 defines subclasses of the two type-specific ShellGui classes, to provide sets of available tools in both list and dictionary format (you would normally need only one, but this module is meant for illustration). This is also the module that is actually run to kick off the GUI -- the shellgui module is a class library only.

Example 9-6. PP2EGuiShellGuimytools.py

#!/usr/local/bin/python from shellgui import * # type-specific shell interfaces from packdlg import runPackDialog # dialogs for data entry from unpkdlg import runUnpackDialog # they both run app classes class TextPak1(ListMenuGui): def __init__(self): self.myMenu = [('Pack', runPackDialog), ('Unpack', runUnpackDialog), # simple functions ('Mtool', self.notdone)] # method from guimixin ListMenuGui.__init__(self) def forToolBar(self, label): return label in ['Pack', 'Unpack'] class TextPak2(DictMenuGui): def __init__(self): self.myMenu = {'Pack': runPackDialog, # or use input here... 'Unpack': runUnpackDialog, # instead of in dialogs 'Mtool': self.notdone} DictMenuGui.__init__(self) if __name__ == '__main__': # self-test code... from sys import argv # 'menugui.py list|^' if len(argv) > 1 and argv[1] == 'list': print 'list test' TextPak1().mainloop( ) else: print 'dict test' TextPak2().mainloop( )

The classes in this module are specific to a particular tools set; to display a different set of tool names, simply code and run a new subclass. By separating out application logic into distinct subclasses and modules like this, software can become widely reusable.

Figure 9-5 shows the main ShellGui window created when the mytools script is run with its dictionary-based menu layout class on Windows, along with menu tear-offs so you can see what they contain. This window's menu and toolbar are built by GuiMaker, and its Quit and Help buttons and menu selections trigger quit and help methods inherited from GuiMixin through the ShellGui module's superclasses. Are you starting to see why this book preaches code reuse so often?

Figure 9-5. mytools items in a ShellGui window

9.2.4.3 Adding GUI frontends to command lines

The callback actions named within the prior module's classes, though, should normally do something GUI-oriented. Because the original file packing and unpacking scripts live in the world of text-based streams, we need to code wrappers around them that accept input parameters from more GUI-minded users.

The module in Example 9-7 uses the custom modal dialog techniques we studied in Chapter 7, to pop up an input display to collect pack script parameters. Its runPackDialog function is the actual callback handler invoked when tool names are selected in the main ShellGui window.

Example 9-7. PP2EGuiShellGuipackdlg.py.

# added file select dialogs, empties test; could use grids import string from glob import glob # filename expansion from Tkinter import * # gui widget stuff from tkFileDialog import * # file selector dialog from PP2E.System.App.Clients.packapp import PackApp # use pack class def runPackDialog( ): s1, s2 = StringVar(), StringVar( ) # run class like a function PackDialog(s1, s2) # pop-up dialog: sets s1/s2 output, patterns = s1.get(), s2.get( ) # whether 'ok' or wm-destroy if output != "" and patterns != "": patterns = string.split(patterns) filenames = [] for sublist in map(glob, patterns): # do expansion manually filenames = filenames + sublist # Unix does auto on command-line print 'PackApp:', output, filenames app = PackApp(ofile=output) # run with redirected output app.args = filenames # reset cmdline args list app.main( ) # should show msgs in gui too class PackDialog(Toplevel): def __init__(self, target1, target2): Toplevel.__init__(self) # a new top-level window self.title('Enter Pack Parameters') # 2 frames plus a button f1 = Frame(self) l1 = Label(f1, text='Output file?', relief=RIDGE, width=15) e1 = Entry(f1, relief=SUNKEN) b1 = Button(f1, text='browse...') f1.pack(fill=X) l1.pack(side=LEFT) e1.pack(side=LEFT, expand=YES, fill=X) b1.pack(side=RIGHT) b1.config(command= (lambda x=target1: x.set(askopenfilename( ))) ) f2 = Frame(self) l2 = Label(f2, text='Files to pack?', relief=RIDGE, width=15) e2 = Entry(f2, relief=SUNKEN) b2 = Button(f2, text='browse...') f2.pack(fill=X) l2.pack(side=LEFT) e2.pack(side=LEFT, expand=YES, fill=X) b2.pack(side=RIGHT) b2.config(command= (lambda x=target2: x.set(x.get() +' '+ askopenfilename( ))) ) Button(self, text='OK', command=self.destroy).pack( ) e1.config(textvariable=target1) e2.config(textvariable=target2) self.grab_set( ) # make myself modal: self.focus_set( ) # mouse grab, keyboard focus, wait... self.wait_window( ) # till destroy; else returns to caller now if __name__ == '__main__': root = Tk( ) Button(root, text='pop', command=runPackDialog).pack(fill=X) Button(root, text='bye', command=root.quit).pack(fill=X) root.mainloop( )

When run, this script makes the input form shown in Figure 9-6. Users may either type input and output filenames into the entry fields, or press the "browse..." buttons to pop up standard file selection dialogs. They can also enter filename patterns -- the manual glob.glob call in this script expands filename patterns to match names and filters out nonexistent input filenames. The Unix command line does this pattern expansion automatically when running PackApp from a shell, but Windows does not (see Chapter 2, for more details).

Figure 9-6. The packdlg input form

When the form is filled in and submitted with its OK button, parameters are finally passed to an instance of the PackApp class we wrote in Chapter 4 to do file concatenations. The GUI interface to the unpacking script is simpler, because there is only one input field -- the name of the packed file to scan. The script in Example 9-8 generated the input form window shown in Figure 9-7.

Example 9-8. PP2EGuiShellGuiunpkdlg.py

# added file select dialog, handles cancel better from Tkinter import * # widget classes from tkFileDialog import * # file open dialog from PP2E.System.App.Clients.unpackapp import UnpackApp # use unpack class def runUnpackDialog( ): input = UnpackDialog( ).input # get input from GUI if input != '': # do non-gui file stuff print 'UnpackApp:', input app = UnpackApp(ifile=input) # run with input from file app.main( ) # execute app class class UnpackDialog(Toplevel): def __init__(self): # a function would work too Toplevel.__init__(self) # resizable root box self.input = '' # a label and an entry self.title('Enter Unpack Parameters') Label(self, text='input file?', relief=RIDGE, width=11).pack(side=LEFT) e = Entry(self, relief=SUNKEN) b = Button(self, text='browse...') e.bind('', self.gotit) b.config(command=(lambda x=e: x.insert(0, askopenfilename( )))) b.pack(side=RIGHT) e.pack(side=LEFT, expand=YES, fill=X) self.entry = e self.grab_set( ) # make myself modal self.focus_set( ) self.wait_window( ) # till I'm destroyed on return->gotit def gotit(self, event): # on return key: event.widget==Entry self.input = self.entry.get( ) # fetch text, save in self self.destroy( ) # kill window, but instance lives on if __name__ == "__main__": Button(None, text='pop', command=runUnpackDialog).pack( ) mainloop( )

The "browse..." button in Figure 9-7 pops up a file selection dialog just like the packdlg form. Rather than an OK button, this dialog binds the enter key-press event to kill the window and end the modal wait state pause; on submission, the name of the file is passed to an instance of the UnpackApp class shown in Chapter 4 to perform the actual file scan process.

Figure 9-7. The unpkdlg input form

This all works as advertised -- by making command-line tools available in graphical form like this, they become much more attractive to users accustomed to the GUI way of life. Still, there are two aspects of this design that seem prime for improvement.

First of all, both of the input dialogs use custom code to render a unique appearance, but we could probably simplify them substantially by importing a common form-builder module instead. We met generalized form builder code in Chapter 7 and Chapter 8, and we'll meet more later; see the form.py module in Chapter 10, for pointers on genericizing form construction, too.

Secondly, at the point where the user submits input data in either form dialog, we've lost the GUI trail -- PackApp and UnpackApp messages still show up in the stdout console window:

C:...PP2EGuiShellGui est>python ..mytools.py dict test PackApp: packed.all ['spam.txt', 'eggs.txt', 'ham.txt'] packing: spam.txt packing: eggs.txt packing: ham.txt UnpackApp: packed.all creating: spam.txt creating: eggs.txt creating: ham.txt

We can do better here, by redirecting stdout to an object that throws text up in a GUI window as it is received. You'll have to read the next section to see how.

9.2.5 GuiStreams: Redirecting Streams to GUI Widgets

The script in Example 9-9 arranges to map input and output sources to pop-up windows in a GUI application, much as we did with strings in the stream redirection topics in Chapter 2. Although this module is really just a first-cut prototype and needs improvement itself (e.g., each input line request pops up a new input dialog), it demonstrates the concepts in general.

Its GuiOutput and GuiInput objects define methods that allow them to masquerade as files in any interface that expects a file. As we learned earlier in Chapter 2, this includes standard stream processing tools like print, raw_input, and explicit read and write calls. The redirectedGuiFunc function in this module uses this plug-and-play compatibility to run a function with its standard input and output streams mapped completely to pop-up windows instead of the console window (or wherever streams would otherwise be mapped).

Example 9-9. PP2EGuiToolsguiStreams.py

############################################################################## # first-cut implementation of file-like classes that can be used to redirect # input and output streams to GUI displays; as is, input comes from a common # dialog popup (a single output+input interface or a persistent Entry field # for input would be better); this also does not properly span lines for read # requests with a byte count > len(line); see guiStreamsTools.py for more; ############################################################################## from Tkinter import * from ScrolledText import ScrolledText from tkSimpleDialog import askstring class GuiOutput: def __init__(self, parent=None): self.text = None if parent: self.popupnow(parent) # popup now or on first write def popupnow(self, parent=None): # in parent now, Toplevel later if self.text: return self.text = ScrolledText(parent or Toplevel( )) self.text.config(font=('courier', 9, 'normal')) self.text.pack( ) def write(self, text): self.popupnow( ) self.text.insert(END, str(text)) self.text.see(END) self.text.update( ) def writelines(self, lines): # lines already have ' ' for line in lines: self.write(line) # or map(self.write, lines) class GuiInput: def __init__(self): self.buff = '' def inputLine(self): line = askstring('GuiInput', 'Enter input line + (cancel=eof)') if line == None: return '' # popup dialog for each line else: # cancel button means eof return line + ' ' # else add end-line marker def read(self, bytes=None): if not self.buff: self.buff = self.inputLine( ) if bytes: # read by byte count text = self.buff[:bytes] # doesn't span lines self.buff = self.buff[bytes:] else: text = '' # read all till eof line = self.buff while line: text = text + line line = self.inputLine( ) # until cancel=eof='' return text def readline(self): text = self.buff or self.inputLine( ) # emulate file read methods self.buff = '' return text def readlines(self): lines = [] # read all lines while 1: next = self.readline( ) if not next: break lines.append(next) return lines def redirectedGuiFunc(func, *pargs, **kargs): import sys saveStreams = sys.stdin, sys.stdout # map func streams to popups sys.stdin = GuiInput( ) # pops up dialog as needed sys.stdout = GuiOutput( ) # new output window per call sys.stderr = sys.stdout result = apply(func, pargs, kargs) # this is a blocking func call sys.stdin, sys.stdout = saveStreams return result def redirectedGuiShellCmd(command): import os input = os.popen(command, 'r') output = GuiOutput( ) def reader(input, output): # show a shell command's while 1: # standard output in a new line = input.readline( ) # popup text box widget if not line: break output.write(line) reader(input, output) if __name__ == '__main__': import string def makeUpper( ): # use standard streams while 1: try: line = raw_input('Line? ') except: break print string.upper(line) print 'end of file' def makeLower(input, output): # use explicit files while 1: line = input.readline( ) if not line: break output.write(string.lower(line)) print 'end of file' root = Tk( ) Button(root, text='test streams', command=lambda: redirectedGuiFunc(makeUpper)).pack(fill=X) Button(root, text='test files ', command=lambda: makeLower(GuiInput(), GuiOutput( )) ).pack(fill=X) Button(root, text='test popen ', command=lambda: redirectedGuiShellCmd('dir *')).pack(fill=X) root.mainloop( )

As coded here, GuiOutput either attaches a ScrolledText to a parent container, or pops up a new top-level window to serve as the container on the first write call. GuiInput pops up a new standard input dialog every time a read request requires a new line of input. Neither one of these policies is ideal for all scenarios (input would be better mapped to a more long-lived widget), but they prove the general point. Figure 9-8 shows the scene generated by this script's self-test code, after capturing the output of a shell dir listing command (on the left), and two interactive loop tests (the one with "Line?" prompts and uppercase letters represents the makeUpper streams test). An input dialog has just popped up for a new makeLower files test.

Figure 9-8. guiStreams routing streams to pop-up windows

9.2.5.1 Using redirection for the packing scripts

Now, to use such redirection tools to map command-line script output back to a GUI, simply run calls and command lines with the two redirected functions in this module. Example 9-10 shows one way to wrap the packing operation to force its printed output to appear in a pop-up window when generated, instead of the console.

Example 9-10. PP2EGuiShellGuipackdlg-redirect.py

# wrap command-line script in GUI redirection tool to popup its output from Tkinter import * from packdlg import runPackDialog from PP2E.Gui.Tools.guiStreams import redirectedGuiFunc def runPackDialog_Wrapped( ): redirectedGuiFunc(runPackDialog) # wrap entire callback handler if __name__ == '__main__': root = Tk( ) Button(root, text='pop', command=runPackDialog_Wrapped).pack(fill=X) root.mainloop( )

You can run this script directly to test its effect, without bringing up the ShellGui window. Figure 9-9 shows the resulting stdout window after the pack input dialog is dismissed. This window pops up as soon as script output is generated, and is a bit more GUI user-friendly than hunting for messages in a console. You can similarly code the unpack parameters dialog to route its output to a pop-up too.[2] In fact, you can use this technique to route the output of any function call or command line to a pop-up window; as usual, the notion of compatible object interfaces are at the heart of much of Python's flexibility.

[2] These two scripts are something of a unique case; because the App superclass they employ saves away standard streams in its own attributes at object creation time, you must kick off the GUI redirection wrapper calls as soon as possible so that App finds the redirected GUI streams in sys when saving them locally. Most other scripts aren't quite as tricky when it comes to internal stream redirections.

Figure 9-9. Routing script outputs to GUI pop-ups

9.2.6 Reloading GUI Callback Handlers Dynamically

One last GUI programming technique merits a quick look here. The Python reload function lets you dynamically change and reload a program's modules without stopping the program. For instance, you can bring up a text editor window to change the source code of selected parts of a system while it is running and see those changes show up immediately after reloading the changed module.

This is a powerful feature, especially for developing programs that take a long time to restart. Programs that connect to databases or network servers, initialize large objects, or travel through a long series of steps to retrigger a callback are prime candidates for reload. It can shave substantial time from the development cycle.

The catch for GUIs, though, is that because callback handlers are registered as object references instead of module and object names, reloads of callback handler functions are ineffective after the callback has been registered. The Python reload operation works by changing a module object's contents in place. Because Tkinter stores a pointer to the registered handler object directly, though, it is oblivious to any reloads of the module that the handler came from. That is, Tkinter will still reference a module's old objects even after the module is reloaded and changed.

This is a subtle thing, but you really only need to remember that you must do something special to reload callback handler functions dynamically. Not only do you need to explicitly request reloading of the modules that you change, but you must also generally provide an indirection layer that routes callbacks from registered objects to modules, so that reloads have impact.

For example, the script in Example 9-11 goes the extra mile to indirectly dispatch callbacks to functions in an explicitly reloaded module. The callback handlers registered with Tkinter are method objects that do nothing but reload and dispatch again. Because the true callback handler functions are fetched through a module object, reloading that module makes the latest versions of the functions accessible.

Example 9-11. PP2EGuiToolsReload ad.py

from Tkinter import * import actions # get initial callback handlers class Hello(Frame): def __init__(self, master=None): Frame.__init__(self, master) self.pack( ) self.make_widgets( ) def make_widgets(self): Button(self, text='message1', command=self.message1).pack(side=LEFT) Button(self, text='message2', command=self.message2).pack(side=RIGHT) def message1(self): reload(actions) # need to reload actions module before calling actions.message1( ) # now new version triggered by pressing button def message2(self): reload(actions) # changes to actions.py picked up by reload actions.message2(self) # call the most recent version; pass self def method1(self): print 'exposed method...' # called from actions function Hello().mainloop( )

When run, this script makes a two-button window that triggers the message1 and message2 methods. Example 9-12 contains the actual callback handlers' code. Its functions receive a self argument that gives access back to the Hello class object, as though these were real methods. You can change this file any number of times while the rad script's GUI is active; each time you do so, you'll change the behavior of the GUI when a button press occurs.

Example 9-12. PP2EGuiToolsReloadactions.py

# callback handlers: reloaded each time triggered def message1( ): # change me print 'spamSpamSPAM' # could build a dialog... def message2(self): print 'Ni! Ni!' # change me self.method1( ) # access the 'Hello' instance...

Try running rad and editing the messages printed by actions in another window; you should see your new messages printed in the stdout console window each time the GUI's buttons are pressed. This example is deliberately simple to illustrate the concept, but the actions reloaded like this in practice might build pop-up dialogs, new top-level windows, and so on. Reloading the code that creates such windows would also let us dynamically change their appearances.

There are other ways to change a GUI while it's running. For instance, we saw in Chapter 8 that appearances can be altered at any time by calling the widget config method, and widgets can be added and deleted from a display dynamically with methods like pack_forget and pack (and their grid manager relatives). Furthermore, passing a new command=action option setting to a widget's config method might reset a callback handler to a new action object on the fly; with enough support code, this may be a viable alternative to the indirection scheme used above to make reloads more effective in GUIs.