Note: This article was first published the April 2008 issue of Python Magazine

By: Mark Mruss

GUI programming, like many other types of programming, can sometimes prove exhausting because you must repeat yourself over and over again. AVC is one tool available to Python GUI programmers that attempts to simplify things by synchronizing application data and GUI widgets.

Introduction

Every once in a while I find myself browsing the Internet trying to find out what’s new and exciting in the Python world. Sometimes I browse to find topics for this article; other times mere curiosity draws me across the web. While I was browsing the other day, I stumbled across AVC: the Application View Controller [1]. I was immediately intrigued by it because its’ name is so similar to the Model View Controller (MVC) pattern. Being familiar with the Model View Controller pattern, and admittedly having struggles with it in the past, I decided to check out AVC to determine if it might be a viable alternative.

After reading about AVC I was intrigued for several reasons. The main reason was the promise of “a multiplatform, fully automatic, live connection among graphical interface widgets and application variables.” [2] This means that graphical widgets can be connected to variables and automatically synchronized. One of the (many?) problems with Graphical User Interface (GUI) programming is that you often find yourself doing the same thing over and over again. One of the things that you end of doing over and over again is setting the contents of a widget based on the value of a variable, and then subsequently, setting that variable’s value based on the current state of the widget. Whenever someone promises me an automatic connection between GUI widgets and my variables, I’m interested.

The other reason for investigating AVC is my past struggles with the Model View Controller pattern. I like the decoupling that the MVC pattern seems to provide, but I often feel as though I am needlessly duplicating code in order to stick with the pattern. I looked into AVC hoping to find a simple framework that will avoid this and guide the separation of my application data from my GUI logic. However in the end, I realized that AVC (in its current state), does not appear to achieve this across all widget toolkits. It does allow you to separate your application from much of the GUI logic that one would normally need, but it does not appear to allow you to fully separate the data from the GUI.

AVC is being developed by Fabrizio Pollastri, and is released under version 3 of the GPL. I was unable to find much information about the project’s future or design objectives. But judging by the release notes, it is still being actively developed. The project is only at version 0.5 so don’t be surprised if the API (Application Programming Interface) or some of the goals change. Although relatively new, AVC bears further investigation because it already simplifies your GUI programming and contains the potential to do much more. In this article, I will introduce some of the main concepts behind AVC, and provide a small, working example using AVC and PyGTK.

Installing AVC

AVC is a “Python module written in pure python” [3]. This means that AVC is easy to install and does not have any dependencies aside from Python 2.2 or greater. You can download the current version (0.5.0) from the website or, if you are a lucky Linux user like me, you can install via your handy package manger. If you download the source, you can install it after extraction, using the following command:

python setup.py install

Depending on which widget toolkit you plan on using, the following requirements must also be met:

• GTK+: PyGTK 2.8 – 2.10
• Qt: PyQt or PyQt4v3 – v4
• Tk: Tkinter 2.4
• wxWidgets: wxPython 2.6

You can easily install any of the above toolkits using your favourite package manager, a source archive, or a binary installer found on each toolkit’s main website. Once AVC is installed, you can test the installation by importing the avc module from the interactive interpreter. If all goes well you will see something similar to the following:

$ python
Python 2.4.4 (#2, Jan  3 2008, 13:36:28)
[GCC 4.2.3 20071123 (prerelease) (Debian 4.2.2-4)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import avc
>>>

Widget Support

In its current state, AVC does not support all widgets available across all toolkits. It does currently support the following widgets:

• Button
• Check Box
• Combo Box (Not supported in Tk)
• Entry
• Label
• Radio Button
• Slider
• Spin Button
• Status Bar (Only supported by GTK+ and wxWidgets)
• Text View
• Toggle Button.

The support of each of these widget types is then handled by specific widgets in each toolkit.

Name-Matching

In order to automatically synchronize variables and GUI widgets, AVC uses a name-matching technique. AVC supports two methods of name matching. The first method requires that the variable and the widget have the same name. For example, if you have a variable named my_data it will match with a widget also named my_data. In other words, if a variable and a widget have the same name they will be connected and their values synchronized.

The second name-matching technique allows you to connect variables to one or more widgets. Widgets can only be connected to one variable, but variables can be connected to any number of widgets. Using the second name-matching technique, you have a match if the widget name contains a double-underscore (__), and the portion before the double-underscore matches the variable name. For example, if you have variable named my_numeric_value and you want to match it with a Label widget and an Entry widget, you do this by naming the widgets as follows:

my_numeric_value__label
my_numeric_value__entry

Again, the text before the “__” must match the variable name, and the text after the “__” can be whatever you want to differentiate your widgets or ensure uniqueness (if the toolkit requires it).

A GTK+, PyGTK, and AVC Example

For this AVC example, I will use the GTK+ widget toolkit and PyGTK. PyGTK a “is a set of bindings to the GTK+ user interface toolkit for the Python language” [4]. This means that it lets us write GUI applications in Python using the GTK+ widget toolkit. To avoid any flame wars: I did not choose GTK+ because it is the best toolkit but because it is the toolkit with which I am the most familiar. In order to run this example you will need to have PyGTK 2.8 or later installed. You can get the latest version of PyGTK from the PyGTK website. [5]

As I mentioned earlier, AVC works with many different widgets types. It also has many different features. I won’t be covering all of the features or widgets types in this column; if you are interesting in learning about some of these features or how to work with different widgets types, please see the AVC documentation. [6]

This example is relatively simple, but it should illustrate some of the basic features of AVC. The example application asks for a person’s name and then displays that name in pop-up dialog. It will have the following features:

1. A gtk.TextView widget to display the person’s name and allow the name to be edited. The gtk.TextView widget will be synchronised with a variable.
2. A gtkButton that will pop-up a gtk.MessageDialog to show the person’s name.
3. A gtk.Button that will reset the name to the name with which the application was initialized.

To begin we need to import all of the modules necessary:

import gtk
import avc.avcgtk

Note: I am using a gtk.TextView widget instead of a gtk.Entry widget. In its current state, AVC does not propagate changes in gtk.Entry widgets back to the connected variable. I’m not sure if this is a current limitation or part of the design.

The above code imports the PyGTK module necessary to work with GTK+. It also imports the avcgtk module, which is used to link our “application variables” with our GTK+ GUI. Depending on what widget toolkit you use, you will have to use different modules. For example, if you are working with Qt4, you will import:

import avc.avcqt4

The next step is to create the “application” class. This will be the class that contains the data. In this example it will also create the GUI:

class gtkAVC(avc.avcgtk.AVC):

Notice that we derive our application from the avcgtk module’s AVC class. This is the GTK+ specific AVC class with which we will work. We will also create an __init__ method in the gtkAVC class. This is where we will initialize the data that will be connected to the GUI and create the GUI via the init_gui method:

def __init__(self, name=""):
    #set the variable and save the initial name
    self.initial_name = name
    self.name = name
    #setup GUI
    self.init_gui()

What we have here is pretty simple. We have the optional parameter name that we store as the current name and as the initial name. We then call the init_gui method that will create the GUI. The contents of the init_gui method can be seen in Listing 1. I won’t explain most of this code since the majority of it is PyGTK specific. However I will make note of several relevant segments below.

Listing 1

def init_gui(self):

    #Setup the window and the layout manager
    self.window = gtk.Window()
    self.window.connect("destroy", gtk.main_quit)

    self.h_layout = gtk.HBox()
    self.window.add(self.h_layout)

    #create the widgets
    self.text_label = gtk.Label("Say hello:")
    self.h_layout.add(self.text_label)

    self.frame = gtk.Frame()
    self.h_layout.add(self.frame)
    self.scrolled_window = gtk.ScrolledWindow()
    self.frame.add(self.scrolled_window)

    self.text_view = gtk.TextView()
    self.text_view.set_name("name__text_view")
    self.scrolled_window.add(self.text_view)

    self.hello_button = gtk.Button("Hello!")
    self.hello_button.connect("clicked", self.on_hello_clicked)
    self.h_layout.add(self.hello_button)

    self.reset_button = gtk.Button("Reset")
    self.reset_button.connect("clicked", self.on_reset_clicked)
    self.h_layout.add(self.reset_button)

    self.window.show_all()

The only AVC specific code segment in the init_gui function is where we set the name of the gtk.TextView widget:

self.text_view.set_name("name__text_view")

This is all the code that we need to connect the gtk.TextView widget with the name variable that we created at the beginning of the __init__ function. (Now, how’s that for simple?) Notice that the name section of the “name__text_view” string will match with the self.name variable. It is also important to note that the variable and the widget are not yet connected. They will become connected when the avc_init method is called.

The other non-AVC related code of note is the connection of both gtk.Button widgets’ clicked signals with signal handlers. We connect the “hello” button to the on_hello_clicked method and the “reset” button to the on_reset_clicked method.

That’s it for the init_gui function, now let’s look at the two signal handlers. The on_hello_clicked method, shown in Listing 2, simply displays the name in a gtk.MessageDialog. What should be interesting to GUI programmers about this function is that instead of reading the data from the gtk.TextView widget, we simply reference self.name for the dialog’s text. We can do this because self.name and the gtk.TextView widget are connected and their values are always the same.

Listing 2

def on_hello_clicked(self, widget):
    def close(dialog, response):
        #Close the dialog on ok
        dialog.destroy()
    message_dlg = gtk.MessageDialog(self.window
        , 0
        , gtk.MESSAGE_INFO
        , gtk.BUTTONS_OK
        , ("Hello: %s" % self.name))
    message_dlg.connect("response", close)
    message_dlg.run()

The on_reset_clicked function is also very simple and straightforward. We simply reset the name to the initial name:

def on_reset_clicked(self, widget):
    #Reset the name to the initial name
    self.name = self.initial_name

Again, notice that we don’t have to worry about doing anything to the gtk.TextView widget that displays the current name. By simply modifying the data, what is displayed in the GUI will automatically be updated by AVC.

The next and final step in our test application is to create our class instances and actually show the GUI:

if (__name__ == "__main__"):
    gtk_avc = gtkAVC("Mark Mruss")
    gtk_avc.avc_init()
    gtk.main()

Since I am working in a Python file, I perform a simple test to make sure that the file is being launched directly instead of being imported as a module. I then create an instance of the gtkAVC class setting the name to be my name. The avc_init method is then called (which is a member of the avc.avcgtk.AVC class). The avc_init method is where all of the magic happens. It is where AVC goes through an application’s variables and connects them to the GUI widgets based upon the name matching technique explained earlier. avc_init must be called after all of the data in the “application” and the widgets have been created.

The final step in this example, is to run the gtk.main function. This is the “main loop” of our PyGTK based application and is standard when working with PyGTK.

The entire code can be seen in Listing 3. When you run the code you will be greeted with something similar to Figure 1. It may not seem like much, but what we have here is a fully functional AVC “application”. This simple “application” illustrates how easy it is to create an automatic connection between your data and your GUI.

Figure1

Listing 3

#! /usr/bin/env python
import gtk
import avc.avcgtk

class gtkAVC(avc.avcgtk.AVC):

    def __init__(self, name=""):
        #set the variable and save the initial name
        self.initial_name = name
        self.name = name
        #setup GUI
        self.init_gui()

    def init_gui(self):

        #Setup the window and the layout manager
        self.window = gtk.Window()
        self.window.connect("destroy", gtk.main_quit)

        self.h_layout = gtk.HBox()
        self.window.add(self.h_layout)

        #create the widgets
        self.text_label = gtk.Label("Say hello:")
        self.h_layout.add(self.text_label)

        self.frame = gtk.Frame()
        self.h_layout.add(self.frame)
        self.scrolled_window = gtk.ScrolledWindow()
        self.frame.add(self.scrolled_window)

        self.text_view = gtk.TextView()
        self.text_view.set_name("name__text_view")
        self.scrolled_window.add(self.text_view)

        self.hello_button = gtk.Button("Hello!")
        self.hello_button.connect("clicked", self.on_hello_clicked)
        self.h_layout.add(self.hello_button)

        self.reset_button = gtk.Button("Reset")
        self.reset_button.connect("clicked", self.on_reset_clicked)
        self.h_layout.add(self.reset_button)

        self.window.show_all()

    def on_hello_clicked(self, widget):
        def close(dialog, response):
            #Close the dialog on ok
            dialog.destroy()
        message_dlg = gtk.MessageDialog(self.window
            , 0
            , gtk.MESSAGE_INFO
            , gtk.BUTTONS_OK
            , ("Hello: %s" % self.name))
        message_dlg.connect("response", close)
        message_dlg.run()

    def on_reset_clicked(self, widget):
        #Reset the name to the initial name
        self.name = self.initial_name

if (__name__ == "__main__"):
    gtk_avc = gtkAVC("Mark Mruss")
    gtk_avc.avc_init()
    gtk.main()

Benefits and Limitations

For a project that is little more than one year old (the first release was in January 2007) AVC appears quite stable and ready to be used. This is not to say that AVC is perfect. I did encounter a few issues.

The most notable issue that I encountered is the tightly coupled structure that AVC seems to impose on your application. For a module that tries to simplify the relationship between application data and GUI’s, this feels like a bit of an issue because. For example, when testing using PyGTK I was able to easily separate the GUI and the “application” into separate classes. But when I tried to do the same thing using PyQt4, I encountered an error because the avc_timer function in the avc.avcqt4.AVC module expects that the “application” class is itself a QObject (namely the actual QApplication). I find this counterintuitive since being able to separate the data from the GUI-logic seems to be a goal of AVC and similar tools. If you are able to separate the “application” fully from the GUI, you can easily connect your “application” to different GUI’s, and (by changing the AVC base class) even different widget toolkits.

I would also be interested in the ability to connect more types of data to more types of widgets. For example, I am interested in synchronizing Python lists with the contents of List boxes and Combo boxes. This is in addition to the current ability to synchronize the selection in the two widgets with integers.

Of course AVC also has a lot going for it. For one, I really like that AVC works with different widget toolkits. I have not seen this very often. It is a real benefit, especially when it comes to people adopting AVC. Hopefully in the future AVC will allow for further separation of the data and the GUI, truly enabling us to use different GUI’s and different widget toolkits with our data.

What I like most about AVC is its simplicity. I have played around with similar solutions and AVC is one of the leaders in terms of ease of use. I was able to get create a simple AVC based application in almost no time at all. (The time that it did take was spent trying to remember PyGTK.) Much of this has to do with the streamlined nature of AVC. There is very little to configure regardless of what widget toolkit you use. While this simplicity limits what AVC can currently achieve compared to other solutions, it also makes the barrier to entry low and the usage trivial. User friendliness is certainly a good thing in a package that aims to make GUI application development easier.

Conclusion

While the data that we worked with in the earlier example wasn’t that complicated (a simple string), I hope that it illustrates how helpful AVC is if you are working with a large amount of data or data that could be updated by an external source. Instead of having to worry about what widgets or toolkits the data was being displayed in, AVC lets us work with the data and GUI transparently, leaving the synchronization to AVC.

If what AVC offers sounds interesting to you, download it from the AVC website and try it out. Although it it’s not there just yet with enough attention, usage, and contributions from the Python community, AVC should reach full-feature status in no time.

[1] http://avc.inrim.it/html/
[2] http://avc.inrim.it/html/
[3] http://avc.inrim.it/html/
[4] http://faq.pygtk.org/index.py?req=all#1.1
[5] http://www.pygtk.org/downloads.html
[6] http://avc.inrim.it/doc/user_manual.pdf

Note: If you haven’t already, please check out my Python version poll.

After working with PyGTK and Glade for my first tutorial, I decided to write another more complex tutorial but I couldn’t think of a topic (Note: If you have any suggestions for any tutorials or posts I’d love to hear them) so I decided to work on creating a simple application and hopefully useful topics would arise from there.

The idea I came up with (which will hopefully be simple) is to create a program that will allow me to keep track of the different types of wine that I drink and how much I like them. It’s something I’ve wanted to write for a while so I thought it would be good to combine learning PyGTK and doing it.

I’m going to call the project PyWine. The full source and Glade file for this tutorial can be found here

The first thing to do is start a new Glade project in the projects directory called PyWine. Create a new Window, call it “mainWindow,” and set the title to be “PyWine”. Then add a handler to the destroy signal just like in the first tutorial.

Next I add a Vertical Box to the Window with 4 rows, (from top to bottom) one row for a Menu bar, one row for a Toolbar, one row for a Tree or List View, and the final row for a Status Bar. Name the Tree View “wineView”

The Tree or List View that we added to the window will be used to display the wines information to the user. So the first thing that we are going to want to do is allow the user to add a wine to the dialog. To do this we are going to use a menu command and a Toolbar button.

The first thing to add is a toolbar button. To do this simply select the toolbar button in the Pallet and click on the toolbar that we added to the window. This should add a strange looking button to your toolbar. Now we are going to edit the toolbar buttons properties on the Widget tab. We’ll set its name to be “tbAddWine”, its label to be “Add Wine”, and it’s icon to be the stock add icon.

Note: A user Thomas Says: “With glade 3 the toolbar buttons aren’t available in the palette. You have to add buttons to the toolbar by right clicking in the toolbar, selecting add and then add the toolbar button.”

Now we’ll add a handler for the tbAddWine button’s click event but this time instead of calling it the default “on_tbAddWine_clicked” we’ll call the handler “on_AddWine”.

Adding to the Menu Bar

Now we are going to work on the menu, since we want people to be able to add items from the taskbar button or from the Menu Bar. So click on the Menu Bar in the window and go to the Widget tab in the properties window. Then click on the “Edit Menus…” button to edit the Menu Bar.

Now click the Add button to add a new top level menu item, and sets it’s label to be “_Add”. Then select the Add item in the menu list and click the “Add Child” button, this will create a sub-menu within the Add menu. Set the new items label to be “_Wine” and set it’s handler to be: “on_AddWine”.

You’ll notice that the handled for the Add toolbar button clicked event and the Add | Wine menu activation are the same. This is because both of those two widgets will be performing the exact same task, adding a wine to our wine list.

So what’s going to happen when the user clicks on the Add Wine button or selects Add | Wine from the menu, is a dialog will pop up allowing them to enter in details about the wine. If they choose the “Ok” button to end the dialog the wine information that they entered will be added to the ListView.

Creating a dialog

So the next thing that we need to do is create the dialog that the user will use to add a new wine. For this example we’ll keep things pretty simple and let the user enter the wine name, the winery, the year it was bottled, and the grape variety.

So to create a new dialog simply click the Dialog button on the Glade Palette window. This should bring up the New Dialog window, in it choose the “Standard button layout” option with Cancel and Ok as the buttons. Now set the dialogs name to be “wineDlg” and it’s window title to be “Add Wine”.

Next we will use a table to lay things out in our wineDlg, add the table to your dialog (in the normal way that you add widgets to a window) and set the number or rows to be 4 and the number of columns to be 2. Then we’ll fill in the spaces of the table with Label and Text Entry widgets until the dialog looks something like this:

I added three pixels of spacing between the rows of the table, this setting can be found on the widget tab of the table’s properties. If you are having trouble selecting the table you can select View | Show Widget Tree from the menu in the main Glade window and select the table in the widget tree. Or you can hold down the SHIFT key and left click on the widgets in the table, this will allow you to cycle through the widgets on the dialog.

Now we are going to have to name all of the edit fields on the dialog, name then: enWine, enWinery, enGrape, and enYear.

The Python Code

Now we are going to take that code and get it working, we’ll call our python file pywine.py and create it in our /projects/PyWine directory (the same directory where we created our glade files). The following is the basic code that we will use (most of it taken form the first PyGTk/Glade tutorial):

#!/usr/bin/env python

import sys
try:
import pygtk
pygtk.require("2.0")
except:
pass
try:
import gtk
import gtk.glade
except:
sys.exit(1)

class pyWine:
"""This is the PyWine application"""

def __init__(self):

#Set the Glade file
self.gladefile = "pywine.glade"
self.wTree = gtk.glade.XML(self.gladefile, "mainWindow")

#Create our dictionay and connect it
dic = {"on_mainWindow_destroy" : gtk.main_quit
, "on_AddWine" : self.OnAddWine}
self.wTree.signal_autoconnect(dic)

def OnAddWine(self, widget):
"""Called when the use wants to add a wine"""

print "OnAddWine"

if __name__ == "__main__":
wine = pyWine()
gtk.main()

There are a few new additions to this code, one is the handler for the on_AddWine signal, if you run this code you’ll notice that “OnAddWine” will be printed out when you click the Add Wine button and when you select Add | Wine from the menu. The other new addition to the code is that we pass the name of the main window to gtk.glade.XML. This lets us load only that window and it’s children.

The next thing that we are going to create is a Wine class that we will use to store the wines information:

class Wine:
"""This class represents all the wine information"""

def __init__(self, wine="", winery="", grape="", year=""):

self.wine = wine
self.winery = winery
self.grape = grape
self.year = year

Pretty simple, the next thing that we are going to create is a class that we’ll use for our wineDlg dialog, we’ll call it wineDialog:

class wineDialog:
"""This class is used to show wineDlg"""

def __init__(self, wine="", winery="", grape="", year=""):

#setup the glade file
self.gladefile = "pywine.glade"
#setup the wine that we will return
self.wine = Wine(wine,winery,grape,year)

The next thing we need to do is add a function to our wineDialog class that will load the wineDialog widget from the glade file and show it. We will also want this function to return the result of the dialog, this will be a gtk.RESPONSE, you can read more about these at the PyGTK website.

Here is the run function:

def run(self):
"""This function will show the wineDlg"""

#load the dialog from the glade file
self.wTree = gtk.glade.XML(self.gladefile, "wineDlg")
#Get the actual dialog widget
self.dlg = self.wTree.get_widget("wineDlg")
#Get all of the Entry Widgets and set their text
self.enWine = self.wTree.get_widget("enWine")
self.enWine.set_text(self.wine.wine)
self.enWinery = self.wTree.get_widget("enWinery")
self.enWinery.set_text(self.wine.winery)
self.enGrape = self.wTree.get_widget("enGrape")
self.enGrape.set_text(self.wine.grape)
self.enYear = self.wTree.get_widget("enYear")
self.enYear.set_text(self.wine.year)

#run the dialog and store the response
self.result = self.dlg.run()
#get the value of the entry fields
self.wine.wine = self.enWine.get_text()
self.wine.winery = self.enWinery.get_text()
self.wine.grape = self.enGrape.get_text()
self.wine.year = self.enYear.get_text()

#we are done with the dialog, destroy it
self.dlg.destroy()

#return the result and the wine
return self.result,self.wine

You’ll notice that we load the dialog form the glade file in the same way that we load the main window. We call gtk.glade.XML() and pass it the name of the widget that we want to load. This will automatically show the Dialog (in the same way that it does our main window) but that’s not good enough for us, we want the run function to wait until the user has exited the dialog before we return to the caller. To do that we call get the dialog widget from the widget tree (self.dlg = self.wTree.get_widget("wineDlg")) and we call the GTkDialogs run function. I’ll let the PyGTk documentation describe what this function does:

The run() method blocks in a recursive main loop until the dialog either emits the “response” signal, or is destroyed. If the dialog is destroyed, the run() method returns gtk.RESPONSE_NONE; otherwise, it returns the response ID from the “response” signal emission. Before entering the recursive main loop, the run() method calls the gtk.Widget.show() on the dialog for you. Note that you still need to show any children of the dialog yourself.

During the run() method, the default behavior of “delete_event” is disabled; if the dialog receives a “delete_event”, it will not be destroyed as windows usually are, and the run() method will return gtk.RESPONSE_DELETE_EVENT. Also, during the run() method the dialog will be modal. You can force the run() method to return at any time by calling response() to emit the “response” signal. Destroying the dialog during the run() method is a very bad idea, because your post-run code won’t know whether the dialog was destroyed or not.

After the run() method returns, you are responsible for hiding or destroying the dialog as needed.

The Ok button will return gtk.RESPONSE_OK and the Cancel button will return gtk.RESPONSE_CANCEL, for the most part we only care about the wine that is returned by this dialog if the user clicks the Ok button.

You can also see that we get the GTKEntry widgets from the dialog in order to get and set their text. All-in-all this function is pretty simple.

Tree Views and List Stores

Now that we have the wine the the user wanted to add to the list we need actually add it to the gtk.TreeView.

The main feature of GTKTreeViews is that they display their data in whatever way their model tells them to. They can use a gkt.ListStore, gtk.TreeStore, gtk.TreeModelSort, or a gtk.GenericTreeModel. For this example we’re going to be using a gtk.ListStore.

The relationships between Tree View’s and Models is a bit complicated but once you start using it you’ll begin to understand why they did it this way. In a very basic form the Model represents the Data, and the Tree View is simply a way to display the data. So you can have multiple views display the same data (model) in totally different ways. From the GTk+ reference manual:

To create a tree or list in GTK+, use the GtkTreeModel interface in conjunction with the GtkTreeView widget. This widget is designed around a Model/View/Controller design and consists of four major parts:
The tree view widget (GtkTreeView)
The view column (GtkTreeViewColumn)
The cell renderers (GtkCellRenderer etc.)
The model interface (GtkTreeModel)

The View is composed of the first three objects, while the last is the Model. One of the prime benefits of the MVC design is that multiple views can be created of a single model. For example, a model mapping the file system could be created for a file manager. Many views could be created to display various parts of the file system, but only one copy need be kept in memory.

The first thing we need to do is add some code to the __init__ function of the pyWine class right after we auto-connect the dictionary to the widget tree:

#Here are some variables that can be reused later
self.cWine = 0
self.cWinery = 1
self.cGrape = 2
self.cYear = 3

self.sWine = "Wine"
self.sWinery = "Winery"
self.sGrape = "Grape"
self.sYear = "Year"

#Get the treeView from the widget Tree
self.wineView = self.wTree.get_widget("wineView")
#Add all of the List Columns to the wineView
self.AddWineListColumn(self.sWine, self.cWine)
self.AddWineListColumn(self.sWinery, self.cWinery)
self.AddWineListColumn(self.sGrape, self.cGrape)
self.AddWineListColumn(self.sYear, self.cYear)

This code is pretty straight forward, first we create a few variables that act as defines for us (so that we can easily change things around later) then we get our gtk.TreeView from the widget tree. After that we call a new function to add the columns that we need in the list. AddWineListColumn just a quick function that stops us from having to replicate the column create code each time:

def AddWineListColumn(self, title, columnId):
"""This function adds a column to the list view.
First it create the gtk.TreeViewColumn and then set
some needed properties"""

column = gtk.TreeViewColumn(title, gtk.CellRendererText()
, text=columnId)
column.set_resizable(True)
column.set_sort_column_id(columnId)
self.wineView.append_column(column)

This code is a bit more complicated, first we create a new gtk.TreeViewColumn that uses a gtk.CellRendererText as it’s gtk.CellRenderer. Here is a bit more general information from the GTK+ reference manual:

Once the GtkTreeView widget has a model, it will need to know how to display the model. It does this with columns and cell renderers.

Cell renderers are used to draw the data in the tree model in a way. There are a number of cell renderers that come with GTK+ 2.x, including the GtkCellRendererText, GtkCellRendererPixbuf and the GtkCellRendererToggle. It is relatively easy to write a custom renderer.

A GtkTreeViewColumn is the object that GtkTreeView uses to organize the vertical columns in the tree view. It needs to know the name of the column to label for the user, what type of cell renderer to use, and which piece of data to retrieve from the model for a given row.

So basically what we are doing is creating a column with a specific title, specifying that it will use the gtk.CellRendererText (to display simply text), and telling it which item in the model it is attached to. The we make it resizable and allow the user to sort the list by clicking on a columns header. After that all we do is add the column to the View.

Now that that’s done we need to create our Model, we’ll do this back in the __init__ function of the pyWine class:

#Create the listStore Model to use with the wineView
self.wineList = gtk.ListStore(str, str, str, str)
#Attatch the model to the treeView
self.wineView.set_model(self.wineList)

Basically we simply create a gtk.ListStore and tell it that it will have four items, all of which will be strings. Then we attach the model to the view and that’s all the initialization that we need to do for out gtk.TreeView.

Putting it all Together

The last thing that we need to do is write the OnAddWine function (called from the menu or the toolbar button) in the pyWine class. It’s a pretty simple function:

def OnAddWine(self, widget):
"""Called when the use wants to add a wine"""
#Create the dialog, show it, and store the results
wineDlg = wineDialog();
result,newWine = wineDlg.run()

if (result == gtk.RESPONSE_OK):
"""The user clicked Ok, so let's add this
wine to the wine list"""
self.wineList.append(newWine.getList())

So we create an instance of our wineDialog and then we run it storing the result and the wine information that the user entered. Then we check to see if the result was gtk.RESPONSE_OK (the user clicked on the Ok button) and if it is we then add the wine information to our gtk.ListStore which will automatically be displayed in our gtk.TreeView since the two are connected.

We make use of the simple getList function in our wine class to make this slightly easier to read:

def getList(self):
"""This function returns a list made up of the
wine information.  It is used to add a wine to the
wineList easily"""
return [self.wine, self.winery, self.grape, self.year]

That’s about it for this sample application, granted it doesn’t save any of the information or anything like that yet, but it does outline some of the initial steps to creating a full pyGTk application.

The full source and Glade file can be found here you can also browse the full source below:

#!/usr/bin/env python

import sys
try:
import pygtk
pygtk.require("2.0")
except:
pass
try:
import gtk
import gtk.glade
except:
sys.exit(1)

class pyWine:
"""This is an PyWine application"""

def __init__(self):

#Set the Glade file
self.gladefile = "pywine.glade"
self.wTree = gtk.glade.XML(self.gladefile, "mainWindow")

#Create our dictionay and connect it
dic = {"on_mainWindow_destroy" : gtk.main_quit
, "on_AddWine" : self.OnAddWine}
self.wTree.signal_autoconnect(dic)

#Here are some variables that can be reused later
self.cWine = 0
self.cWinery = 1
self.cGrape = 2
self.cYear = 3

self.sWine = "Wine"
self.sWinery = "Winery"
self.sGrape = "Grape"
self.sYear = "Year"

#Get the treeView from the widget Tree
self.wineView = self.wTree.get_widget("wineView")
#Add all of the List Columns to the wineView
self.AddWineListColumn(self.sWine, self.cWine)
self.AddWineListColumn(self.sWinery, self.cWinery)
self.AddWineListColumn(self.sGrape, self.cGrape)
self.AddWineListColumn(self.sYear, self.cYear)

#Create the listStore Model to use with the wineView
self.wineList = gtk.ListStore(str, str, str, str)
#Attache the model to the treeView
self.wineView.set_model(self.wineList)

def AddWineListColumn(self, title, columnId):
"""This function adds a column to the list view.
First it create the gtk.TreeViewColumn and then set
some needed properties"""

column = gtk.TreeViewColumn(title, gtk.CellRendererText()
, text=columnId)
column.set_resizable(True)
column.set_sort_column_id(columnId)
self.wineView.append_column(column)

def OnAddWine(self, widget):
"""Called when the use wants to add a wine"""
#Cteate the dialog, show it, and store the results
wineDlg = wineDialog();
result,newWine = wineDlg.run()

if (result == gtk.RESPONSE_OK):
"""The user clicked Ok, so let's add this
wine to the wine list"""
self.wineList.append(newWine.getList())

class wineDialog:
"""This class is used to show wineDlg"""

def __init__(self, wine="", winery="", grape="", year=""):

#setup the glade file
self.gladefile = "pywine.glade"
#setup the wine that we will return
self.wine = Wine(wine,winery,grape,year)

def run(self):
"""This function will show the wineDlg"""

#load the dialog from the glade file
self.wTree = gtk.glade.XML(self.gladefile, "wineDlg")
#Get the actual dialog widget
self.dlg = self.wTree.get_widget("wineDlg")
#Get all of the Entry Widgets and set their text
self.enWine = self.wTree.get_widget("enWine")
self.enWine.set_text(self.wine.wine)
self.enWinery = self.wTree.get_widget("enWinery")
self.enWinery.set_text(self.wine.winery)
self.enGrape = self.wTree.get_widget("enGrape")
self.enGrape.set_text(self.wine.grape)
self.enYear = self.wTree.get_widget("enYear")
self.enYear.set_text(self.wine.year)

#run the dialog and store the response
self.result = self.dlg.run()
#get the value of the entry fields
self.wine.wine = self.enWine.get_text()
self.wine.winery = self.enWinery.get_text()
self.wine.grape = self.enGrape.get_text()
self.wine.year = self.enYear.get_text()

#we are done with the dialog, destory it
self.dlg.destroy()

#return the result and the wine
return self.result,self.wine

class Wine:
"""This class represents all the wine information"""

def __init__(self, wine="", winery="", grape="", year=""):

self.wine = wine
self.winery = winery
self.grape = grape
self.year = year

def getList(self):
"""This function returns a list made up of the
wine information.  It is used to add a wine to the
wineList easily"""
return [self.wine, self.winery, self.grape, self.year]

if __name__ == "__main__":
wine = pyWine()
gtk.main()

The next installment of the PyWine tutorial: Extending our PyGTK Application is available.