Mark Mruss

Note: This article was first published the October 2007 issue of Python Magazine

XML is everywhere. It seems you can’t do much these days unless you utilize XML in one way or another. Fortunately, Python developers have a new tool in our standard arsenal: the ElementTree module. This article aims to introduce you to reading, writing, saving, and loading XML using the ElementTree module.

1. Introduction
2. Reading XML data
3. Listing 1
4. Listing 2
5. Reading XML Attributes
6. Writing XML
7. Listing 3
8. Writing XML Attributes
9. Reading XML Files
10. Writing XML Data to a File
11. Reading from the Web
12. Conclusion

Introduction

It seems like everyone needs to parse XML these days. They’re either saving their own information in XML or loading in someone else’s data. This is why I was glad to learn that as of Python 2.5, the ElementTree XML package has been added to the standard library in the XML module.

What I like about the ElementTree module is that it just seems to make sense. This might seem like a strange thing to say about an XML module, but I’ve had to parse enough XML in my time to know that if an XML module makes sense the first time you use it, it’s probably a keeper. The ElementTree module allows me to work with XML data in a way that is similar to how I think about XML data.

A subset of the full ElementTree module is available in the Python 2.5 standard library as xml.etree, but you don’t have to use Python 2.5 in order to use the ElementTree module. If you are still using an older version of Python (1.5.2 or later) you can simply download the module from its website and manually install it on your system. The website also has very easy to follow installation instructions, which you should consult to avoid issues while installing ElementTree.

In general, the ElementTree module treats XML data as a list of lists. All XML has a root element that will have zero or more subelements (or child elements). Each of those subelements may in turn have subelements of their own. The best way to think about this is with a brief example.

First let’s take a look at some sample XML data:

<root>
<child>One</child>
<child>Two</child>
</root>

Here we have a root element with two child elements. Each child element has some text associated with it seen here as “one” and “two”. If we examine the XML as a hierarchical list of lists we see that we have one element “root” in our root list. Within the “root” element we have a list containing two subelements “child” and “child”. The two “child” elements would then contain empty lists representing their lack of subelements. Not too complicated so far, is it?

Reading XML data

Now let’s use the ElementTree package to parse this XML and print the text data associated with each child element. To start, we’ll create a Python file with the contents shown in Listing 1.

Listing 1

#!/usr/bin/env python

def main():
	pass

if __name__ == "__main__":
	main()

This is basically a template that I use for many of my simple “*.py” files. It doesn’t actually do anything except set up the script so that when the file is run, the main method will be executed. Some people like to use the Python interactive interpreter for simple hacking like this. Personally, I prefer having my code stored in a handy file so I can make simple changes and re-run the entire script when I am just playing around.

The first thing that we need to do in our Python code is import the ElementTree module:

from xml.etree import ElementTree as ET

Note: If you are not using Python 2.5 and have installed the ElementTree module on your own, you should import the ElementTree module as follows:

from elementtree import ElementTree as ET

This will import the ElementTree section of the module into your program aliased as ET. However, you don’t have to import ElementTree using an alias; you can simply import it and access it as ElementTree. Using ET is demonstrated in the Python 2.5 “What’s new” documentation[1] and I think it’s a great way to eliminate some key strokes.

Now we’ll begin writing code in the main method. The first step is to load the XML data described above. Normally you will be working with a file or URL; for now we want to keep this simple and load the XML data directly from the text:

element = ET.XML(
       "<root><child>One</child><child>Two</child></root>")

The XML function is described in the ElementTree documentation as follows: “Parses an XML document from a string constant. This function can be used to embed “XML literals” in Python code”[2].

Be careful here! The XML function returns an Element object, and not an ElementTree object as one might expect. Element objects are used to represent XML elements, whereas the ElementTree object is used to represent the entire XML document. Element objects may represent the entire XML document if they are the root element but will not if they are a subelement. ElementTree objects also add “some extra support for serialization to and from standard XML.”[3] The Element object that is returned represents the element in our XML data.

Thankfully, the Element object is an iterator object so we can use a for loop to loop through all of its child elements:

for subelement in element:

This will give us all the child elements in the root element. As mentioned earlier, each element in the XML tree is represented as an Element object, so as we iterate through the root element’s child elements we are getting Element objects with which to work. Meaning that each loop though the for loop will give us the next child element in the form of an Element object until there are no more children left. In order to print out the text associated with an Element object we simply have to access the Element object’s text attribute:

for subelement in element:
       print subelement.text

To recap, have a look at the code in Listing 2.

Listing 2

#!/usr/bin/env python

from xml.etree import ElementTree as ET

def main():
	element = ET.XML("<root><child>One</child><child>Two</child></root>")
	for subelement in element:
		print subelement.text

if __name__ == "__main__":
	# Someone is launching this directly
	main()

Once you run the code you should get the following output:

One
Two

If an XML element does not have any text associated with it, like our root element, the Element object’s text attribute will be set to None. If you want to check if an element had any text associated with it, you can do the following:

if element.text is not None:
       print element.text

Reading XML Attributes

Let’s alter the XML that we are working with to add attributes to the elements and look at how we would parse that information.

If the XML uses attributes in addition to, or instead of, inner text they can be accessed using the Element object’s attrib attribute. The attrib attribute is a Python dictionary and is relatively easy to use:

def main():
       element = ET.XML(
               '<root><child val="One"/><child val="Two"/></root>')
       for subelement in element:
               print subelement.attrib

When you run the code you get the following output:

{'val': 'One'}
{'val': 'Two'}

These are the attributes for each child element stored in a dictionary. Being able to work with an XML element’s attributes as a Python dictionary is a great feature and fits well with the dynamic nature of XML attributes.

Writing XML

Now that we’ve tried our hand at reading XML, let’s try creating some. If you understand the reading process, you should have no trouble understanding the creation process because it works in much the same manner. What we are going to do in this example is recreate the XML data that we were working with above.

The first step is to create our element:

#create the root <root>
root_element = ET.Element("root")

After this code is executed, the variable root_element is an Element object, just like the Element objects that we used earlier to parse the XML.

The next step is to create the two child elements. There are two ways to do this.

In the first method, if you know exactly what you are creating, it’s easiest to use the SubElement method, which creates an Element object that is a subelement (or child) of another Element object:

#create the first child <child>One</child>
child = ET.SubElement(root_element, "child")

This will create a Element that is a child of root_element. We then need to set the text associated with that element. To do this we use the same text attribute that we used in the first parsing example. However, instead of simply reading the text attribute we set its value:

child.text = "One"

The second approach to creating a child element is to create an Element object separately (rather than a sub element) and append it to a parent Element object. The results are exactly the same – this is simply a different approach that may come in handy when creating your XML,or working with two sets of XML data.

First we create an Element object in the same way that we created the root element:

#create the second child <child>Two</child>
child = ET.Element("child")
child.text = "Two"

This creates the child Element object and sets its text to “Two”. We then append it to the root element:

#now append
root_element.append(child)

Pretty simple! Now, if we want to look at the contents of our root_element (or any other Element object for that matter) we can use the handy tostring function. It does exactly what it says that it does: it converts an Element object into a human readable string.

#Let's see the results
print ET.tostring(root_element)

Listing 3

#!/usr/bin/env python

from xml.etree import ElementTree as ET

def main():
	#create the root </root><root>
	root_element = ET.Element("root")
	#create the first child <child>One</child>
	child = ET.SubElement(root_element, "child")
	child.text = "One"
	#create the second child <child>Two</child>
	child = ET.Element("child")
	child.text = "Two"
	#now append
	root_element.append(child)
	#Let's see the results
	print ET.tostring(root_element)

if __name__ == "__main__":
	# Someone is launching this directly
	main()

To recap, have a look at the code in Listing 3. When you run this code you will get the following output:

</root><root><child>One</child><child>Two</child></root>

Writing XML Attributes

If you want to create the XML with attributes (as illustrated in the second reading example), you can use the Element object’s set method. To add the val attribute to the first element, use the following:

child.set("val","One")

You may also set attributes when you create Element objects:

child = ET.Element("child", val="One")

Reading XML Files

Most of the time you won’t be working with XML data that you explicitly create in your code, instead you will usually read the XML data in from a data source, work with it, and then save it back out when you are done. Fortunately, configuring ElementTree to work with different data sources is very easy. For example, let’s take the XML data that we first used and save it into a file named our.xml in the same location as our Python file.

There are a few methods that we can use to load XML data from a file. We are going to use the parse function. This function is nice because it will accept, as a parameter, the path to a file OR a “file-like” object. The term “file-like” is used on purpose because the object does not have to be a file object per se – it simply has to be an object that behaves in a file-like manner. A “file-like” object is an object that implements a “file-like” interface, meaning that it shares many (if not all) methods with the file object. If an object is “file-like” this fact will usually be prominently mentioned in its documentation.

The first thing that we need in order to load the XML data is determine the full path to the our.xml file. In order to calculate this, we determine the full path of our Python source file, strip the filename from it, and then append our.xml to the path. This is rather simple given that the __file__ attribute (available in Python 2.2 and later) is the relative path and filename of our Python source file. Although the __file__ attribute will be a relative path, we can use it to calculate the absolute path using the standard os module:

import os

We then call the abspath function to get the absolute path:

xml_file = os.path.abspath(__file__)

However, since we only want the directory name (not the full path and filename of our Python source file) we have to strip off the filename:

xml_file = os.path.dirname(xml_file)

Now that we have the directory in which the our.xml file resides, all we have to do is append the our.xml filename to the xml_file variable. However, instead of just doing something like:

xml_file += "/our.xml"

we will use the os module to join the two paths so that the resulting path is always correct regardless of what operating system our code is executed on:

xml_file = os.path.join(xml_file, "our.xml")

Note: If you have any trouble understanding what any of the code used to determine the path of our.xml is doing, try printing out xml_file after each of the above lines and it should become clear.

We now have the full path to the our.xml file. In order to load its XML data we simply pass the path to the parse function:

tree = ET.parse(xml_file)

We now have an ElementTree object instance that represents our XML file.

Since we are working with files, we should watch out for incorrect paths, I/O errors, or the parse function failing for any other reason. If you wish to be extra careful, you can wrap the parse function in a try/except block in order to catch any exceptions that may be thrown:

try:
       tree = ET.parse("sar")
except Exception, inst:
       print "Unexpected error opening %s: %s" % (xml_file, inst)
       return

In the except block, I catch the Exception base class so that I catch any and all exceptions that may be thrown (in the case of a missing file it will most likely be an IOError exception).

Writing XML Data to a File

Now that we know how to read in XML data, we should look at how one writes XML data out to a file. Let’s assume that after reading in the out.xml fiie we want to add another item to the XML file that we just read in:

child = ET.SubElement(tree.getroot(), "child")
child.text = "Three"

Notice that in order to add a child to the root element we used the ElementTree object’s getroot function. The getroot function simply returns the root Element object of the XML data.

Now that we have a third child element, let’s write the XML data back out to our.xml. Thanks to ElementTree this is a painless experience:

tree.write(xml_file)

That’s it!

If we want to be really careful when writing the XML data out to a file, we’ll watch out for exceptions. However most of the time the write method will succeed without throwing an exception; it is more important to be sure that the path used is correct. Often times, instead of getting the exception that you want, you end up with an XML file stored in some far off and strange location on your hard drive because your path was incorrect or you did not specify the full path. But, as is often the case when programming, better safe than sorry:

try:
       tree.write(xml_file)
except Exception, inst:
       print "Unexpected error writing to file %s: %s" % (xml_file, inst)
       return

To recap you can find all of the code from this section in Listing 4.

Listing 4

#!/usr/bin/env python

from xml.etree import ElementTree as ET
import os

def main():

	xml_file = os.path.abspath(__file__)
	xml_file = os.path.dirname(xml_file)
	xml_file = os.path.join(xml_file, "our.xml")

	try:
		tree = ET.parse(xml_file)
	except Exception, inst:
		print "Unexpected error opening %s: %s" % (xml_file, inst)
		return

	child = ET.SubElement(tree.getroot(), "child")
	child.text = "Three"

	try:
		tree.write(xml_file)
	except Exception, inst:
		print "Unexpected error writing to file %s: %s" % (xml_file, inst)
		return

if __name__ == "__main__":
	# Someone is launching this directly
	main()

When you run the code and take a look at the our.xml file you should see that the the third child element has been added:

<root>
<child>One</child>
<child>Two</child>
<child>Three</child>
</root>

Reading from the Web

Working with a local file is very useful, but you might also be in a situation where you will have to work with an XML file that is located on the Internet, perhaps an RSS feed. Fortunately, since the parse function explained above works with file-like elements, loading a URL is very easy.

First off, you need to import the urllib module; a standard module that allows you to open URLs in a method similar to opening local files:

import urllib

In order to open a URL we use:

feed = urllib.urlopen("http://pythonmagazine.com/c/news/atom")
tree = ET.parse(feed)

Conclusion

And that’s that! This concludes our brief introduction to XML parsing using the ElementTree module. Hopefully throughout this article you have seen how easy it is to create and manipulate XML using ElementTree …and I’ve only scratched the surface. For more information take a look at the official Python documentation and some of the great examples on the effbot website. I’m sure you’ll be an XML wizard in no time.

[1] http://docs.python.org/whatsnew/modules.html#SECTION0001420000000000000000
[2] http://effbot.org/zone/pythondoc-elementtree-ElementTree.htm#elementtree.ElementTree.XML-function
[3] http://effbot.org/zone/pythondoc-elementtree-ElementTree.htm#elementtree.ElementTree.ElementTree-class

PyLan Four

Hello welcome to the fourth installment of the PyLan tutorial. This will be a quick tutorial to introduce one feature: context (or popup) menus. I’ve had many questions regarding this so I thought I would take a quick stab at it.

If you want to follow along with the code in detail, and have not done so already, you should read part one, part two and part three of this series.

You can download the full source to this tutorial here.

This tutorial is organized into the following sections:

1. Adding the menu in Glade
2. Showing the menu in Python

Adding the menu in Glade

So let’s startup glade and create a new popup menu item. Add the following four items to the menu:

1. New Category. Name – “new_category_menu” Handler – “on_add_category”
2. New Task. Name – “new_task_menu” Handler – “on_add_task”
3. _Edit. Name – “edit_context_menu” Handler – “on_edit_object”
4. _Remove. Name – “remove_context_menu” Handler – “on_remove_item”

Call the menu itself: contextMenu

That’s it for glade.

Showing the menu in Python

The first thing that we need to do is get the menu widget in our initialize_widgets() function:

#load the menu from the glade file
wTree = gtk.glade.XML(self.gladefile, "contextMenu")
#connect the menu with the signals
wTree.signal_autoconnect(self)
#Get the menu dialog widget
self.context_menu = wTree.get_widget("contextMenu")

Now that we have the widget we need to actually show it when people right-click on our TreeView. We didn’t have to add a button press handler to our TreeView because we added one in the last tutorial, but we will have to edit it.

Here is the original function:

def on_todoTree_button_press_event(self, widget, event):
	"""There has been a button press on the TodoTree
	for now we use this as a quick hack to remove
	the selection.  Perhaps there is a better way?
	@param widget - gtk.TreeView - The Tree View
	@param event - gtk.gdk.event - Event information
	"""
	#Get the path at the specific mouse position
	path = widget.get_path_at_pos(int(event.x), int(event.y))
	if (path == None):
		"""If we didn't get apath then we don't want anything
		to be selected."""
		selection = widget.get_selection()
		selection.unselect_all()

We will have to change this function to show our menu widget, which is a pretty simple addition to the end of the function:

if (event.button == 3):
	#This is a right-click
	self.context_menu.popup( None, None, None
		, event.button, event.time)

So far so good, you’ll notice that since the menu handlers are the same as our toolbar handlers everything already works! The only problem is that the sensitive state of the menu items does not match the sensitive state of the toolbar buttons.

Thankfully since we added this feature to the buttons in the last tutorial doing this is pretty easy.

The first thing that we need to do is get the menu items and disable them in the same way that we do the buttons in the initialize_widgets() function:

#Get the menu widgets
self.new_category_menu = wTree.get_widget("new_category_menu")
self.new_task_menu = wTree.get_widget("new_task_menu")
self.edit_context_menu = wTree.get_widget("edit_context_menu")
self.remove_context_menu = wTree.get_widget("remove_context_menu")

#disable them like the buttons
self.new_task_menu.set_sensitive(False)
self.edit_context_menu.set_sensitive(False)
self.remove_context_menu.set_sensitive(False)

Then in the on_tree_selection_changed() function we need to update the menu items sensitive state:

self.new_task_menu.set_sensitive((selection_iter != None))
self.edit_context_menu.set_sensitive((selection_iter != None))
self.remove_context_menu.set_sensitive((selection_iter != None))

Now we have nice context menus!

You can download the full source to this tutorial here.

This tutorial assumes that you have a passing understanding of Silverlight and Microsoft’s .NET technologies. If you do you should have no trouble understanding everything in this code, and chances are you will understand some of it more then I do!

But to start it off here is a little bit of information straight from Microsoft’s website:

Silverlight is a new Web presentation technology that is created to run on a variety of platforms. It enables the creation of rich, visually stunning and interactive experiences that can run everywhere: within browsers and on multiple devices and desktop operating systems (such as the Apple Macintosh). In consistency with WPF (Windows Presentation Foundation), the presentation technology in Microsoft .NET Framework 3.0 (the Windows programming infrastructure), XAML (eXtensible Application Markup Language) is the foundation of the Silverlight presentation capability.
This white paper will step you through the basics of Silverlight and how you can use the Microsoft stack of tools, including Microsoft Expression Blend, Microsoft Visual Studio 2005, and XAML to build rich graphical sites. First, let’s take a primer on the background leading up to Silverlight and where it stands on the development landscape.

What we are going to do is create a simple game with falling targets that they user has to click on in order to “hit” them. Each time they hit a target they will get a point and another target will be created.

You can try the “finished” product out here: http://www.learningpython.com/silverpy/index.htm

This first step is to download and install Silverlight 1.1 from here: http://msdn2.microsoft.com/en-us/silverlight/bb419317.aspx

Sadly at this point there is no plugin available for Linux, however the people over at the mono project are working on moonlight so we should see some movement in that direction soon.

The next step is to download the SilverLight 1.1 SDK from: http://go.microsoft.com/fwlink/?LinkID=89145&clcid=0×409

Once you have done that you should create a folder somewhere on your hard drive where you want to store your files. I created a folder called SilverPy.

Then browse to the DLR console sample located in this directory:

...Silverlight1.1SDK\Silverlight 1.1 Alpha Samples\DLRConsole\python

Note: The DLR sample appears to have gone missing in recent SDK releases, but it can be found on the samples page.

Then copy all of the files from that folder into your SilverPy folder. Now rename the DLRConsole.xaml to SilverPy.xaml and you can get rid of the DLRConsole.py, in its place create a SilverPy.py file. This will be the file that will contain our python code.

So once you are done you should be left with the following:

Now we want to edit the index.html so that it doesn’t say that it’s the DLR sample. Edit the html code to look something like:

<html xmlns="http://www.w3.org/1999/xhtml" >
<head>
    <title>SilverPy</title>
   <script src="silverlight.js" type="text/javascript" ></script>
   <script src="CreateSilverlight.js" type="text/javascript" ></script>
</head>
<body>
    <div id="WpfeControl1Host">
    <script type="text/javascript">
				var pe = document.getElementById("WpfeControl1Host");
				createSilverlight();
    </script>
    </div>
</body>
</html>

Now since we changed the name of our xaml file we need to edit the CreateSilverlight.js file:

function createSilverlight()
{
Sys.Silverlight.createObject("SilverPy.xaml", pe, "wpf",
{width:"100%", height:"100%",
inplaceInstallPrompt:false, background:'white', isWindowless:'true',
framerate:'30', version:'0.95'},
{onError:null, onLoad:null},
null);
}

We simply changed the first parameter to the createObject function to be “SilverPy.xaml” so that the correct file gets loaded. CreateSilverlight.js calls Silverlight.createObject to instantiate Silverlight and tell it to load our “Silver.xaml” file, it also controls other a few other option. I don’t want to explain this in too much detail since Microsoft has already done this for me:

CreateSilverlight.js:

Defines the CreateSilverlight method, which invokes either the CreateObject or CreateObjectEx method, which are defined in the Silverlight.js file.

Silverlight.js:

Defines the CreateObject and CreateObjectEx methods, which provide version checking support and generate the

If you want more information on the nitty gritty of these these two files and the html file please read the Microsoft website.

The next step is to edit our XAML file, this is going to be pretty simple but I will explain it later:

This is our XAML file, it’s used to create our “GUI”. The first step is to create the Canvas element:

<canvas x:Name="root_canvas"  Width="500" Height="300"
 xmlns="http://schemas.microsoft.com/client/2007"
 xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
 Background="Purple"
>
  <x :Code Source="Silver.py" Type="text/python" />
  <canvas x:Name="game_canvas"
         Loaded="on_canvas_loaded"
          Width="500" Height="300"/>
  <textblock Name="Score" Text="Targets Hit: 0"  FontSize="10" Canvas.Left="400" Canvas.Top="305"/>
</canvas>

Defines an area within which you can explicitly position child elements by using coordinates relative to the Canvas area.

So this where we will create all of our visible objects, you can think of it like the canvas that a painter uses. You can see in the XML that we give our canvas object a name: “root_canvas”, a height, a width, and a background colour: “purple”.

The next element that you see is an x:Code element which we use to load the “Silver.py” python file. Here we could load as many code files as we wanted.

The next element is another Canvas element named “game_canvas”, which serves no purpose except to provide us with the . The value that we assign to the loaded attribute is the name of the function in our python file that will be called when this canvas has been loaded.

The next element is a TextBlock element that is used to display (yes you guessed it) text. We use this TextBlock to display the user’s score as they play our little game.

Now it’s time to work on our python code.

If you load the index.html file into Internet Explorer (you have to use Internet Explorer as there currently are some issues with loading external python modules when running local files, I’ve read that it will be fixed soon) you will get an obscure error. This is because we have not created the on_canvas_loaded function that we described in our xaml.

So let’s add this to our Silver.py file:

def on_canvas_loaded(sender, e):
	pass

The first thing that you will notice about out Loaded event handler is that it has two parameters, which is common will all event handlers. Sender is the object that fired the event, and e is the event arguments associated with the event. What is contained in the event arguments changes depending on what event is being caught.

Now if you load index.html into Internet Explorer you should see the following:

So far so good! So now lets get into some serious python coding, now most of this code is simply Python/IronPython so if you are familiar with both you shouldn’t have any problem.

The fist step is to import all of the stuff that we are going to need:

from System import *
import _random
import wpf
from wpf import *
import clr
clr.AddReference('agclr')
clr.AddReference('System.Silverlight')

Now we are going to work with two classes in our game, one class that will be the target that we are going to aim at and the other that will serve as out main game.

def __init__(self, game_canvas):
    """Init the Target Game
    @param game_canvas - The canvas for the game.
    """
    #Create a random object
    self.random = _random.Random()
    #Save the game canvas
    self.game_canvas = game_canvas
    #The score
    self.score = 0
    #The list of targets that we have
    self.targets = []
    #Make sure that we have the minimum number of targets
    self.ensure_targets()
    #hook into the keydown event
    self.game_canvas.KeyDown += EventHandler(self.on_key_down)
    #Not done yet
    self.done = False

Now the first thing that we do is we create a random object that we will use in the future to position our Target sprites. The next step is to save the game_canvas that was passed in to the __init__ function, game_canvas corresponds to a canvas object. Then we initialize our score to zero, this will be the number of canvas sprites that our user hits. Then we create an empty list, which will store references to the targets that are currently on the screen.

Finally we hook up our member function on_key_down to the game canvas objects KeyDown event and set our done flag to False, since we aren’t done.

def on_key_down(self, sender, e):
    """Check to see if they hit escape"""

    if (e.Key == 8):
        self.game_over()

This handler is pretty simple, it gets called when there is a key down event on the game_canvas, if the key is the Escape key (e.Key == then we called self.game_over() to end the game. I added this so that someone could quit the game at any time.

The game_over function is as follows:

def game_over(self):
    """Called when the game should end"""
    self.game_over_text = TextBlock()
    self.game_over_text.FontSize = 50
    self.game_over_text.Text = "GAME OVER"
    self.game_canvas.Children.Add(self.game_over_text)
    wpf.SetPosition(self.game_over_text
        , 100
        , 100)
    #We are done
    self.done = True

The first think that we do is create a TextBlock object, set some of its properties, and add it to the game_canvas’s children making the object visible. Then we use a helper function in the wpf module to set the position of the TextBlock object. Finally we set done to True, done is simply a boolean flag that we use to know if the game is done or not.

The wpf modules SetPosition function is actually pretty simple and we could have done this ourselves:

def SetPosition(o, x, y):
    SetIntValue(o, Canvas.TopProperty, y)
    SetIntValue(o, Canvas.LeftProperty, x)

Another function that we called way back when in the __inti__ function is:

def ensure_targets(self):
    #Make sure that we have enough targets
    while (len(self.targets) < NUM_TARGETS):
        self.targets.append(self.create_target())

Pretty simply stuff, while the number of targets stored in our list is less then NUM_TARGETS we create and add targets to our list. NUM_TARGETS is defined as follows at the beginning of the source code:

NUM_TARGETS = 10

The ensure_targets function uses the create_target function to create new targets:

def create_target(self):
    #Create a new target and return it
    
    #Init to random size and position
    x = int(self.random.random()*400)
    width = int(self.random.random()*30) + 20
    height = int(self.random.random()*30) + 20
    y = 0 - height
    """Init the velocity to a random number based off of the 
    score so that more targets are hit, the game gets harder."""
    velocity = int(self.random.random()*(int(self.score / 15)+1))
    #The minimum velocity is 1
    if (velocity<=0):
        velocity = 1

    return TargetSprite(self.on_target_event
            , self.game_canvas, x, y,width, height
            , velocity)

This might seem slightly confusing, but basically what we are doing is using our random object to randomly position and size our new target sprite. We set the x position to be a random number between 0 and 400, the width and height a random number between 20 and 50. Then the Y position to be 0 – height, this is simply done to start the target off of the screen.

Next we set the velocity of the Target sprite to be between 1 and the current score divided by 15. This makes it so that the game increases in difficulty as the more targets are hit.

Finally we return the TargetSprite that we create.

Now that we have looked at how we create TargetSprites in the TargetGame class lets look at our TargetSprite object, here is the __init__ function from the Target Sprite class, notice that in create_target we pass the function self.on_target_event as the first parameter:

def __init__(self, notify_function, game_canvas, x, y, width, height, velocity=1):
    """Initialize the target sprite.
    @param notify_function - function - The function to call when an event happens.
    @param game_canvas - Canvas object - The canvas that the 
    TargetSprite will be added to.
    @param x - int - X position
    @param y - int - Y position
    @param width - int - The width
    @param height - int - The height
    @param velocity = 1 - int - How fast we are going to move down.
    """
    self.notify_function = notify_function
    self.game_canvas = game_canvas
    self.x = x
    self.y = y
    self.width = width
    self.height = height
    self.velocity = velocity
            
    self.add_to_canvas()

This function is pretty easy to understand, we save a reference to each parameter and then we add ourself to the canvas that was passed in. add_to_canvas is where we actually create the ellipse that will be displayed on the screen as our target:

def add_to_canvas(self):
    """Add yourself to the canvas"""
    
    #Create the Ellipse
    self.ellipse = System.Windows.XamlReader.Load('<Ellipse Stroke="Black" StrokeThickness="2" Fill="SlateBlue"/>')
    #Height, Width, and position
    self.ellipse.Height = self.height
    self.ellipse.Width = self.width
    #Add to canvase
    self.game_canvas.Children.Add(self.ellipse)
    #Set the position
    wpf.SetPosition(self.ellipse, self.x, self.y)
    """Connect out click event handler with the Let button down
    event."""
    self.ellipse.MouseLeftButtonDown += MouseEventHandler(self.on_ellipse_click)

Now here we do something interesting, we create an ellipse object using some in-line XAML code instead of creating the object directly like we did with the “game over” text.

After the ellipse has been created, we set the Height and Width, and then we add it to the canvas objects children. Then we use the SetPosition helper function in the wpf module to set the position of our ellipse.

Then we add a handler to the ellipse’s MouseLeftButtonDown event. We do this so that we know that the user has “hit” a target.

Our MouseLeftButtonDown function is pretty simple as well, we simply call the notify function that we were initialized with and tell them what happened:

def on_ellipse_click(self, sender, e):
    """We have been clicked on, call the notify function
    and tell them."""
    self.notify_function(TARGET_HIT, self)

Target hit is defined at the start of the program along with GAME_OVER like so:

TARGET_HIT = 0
GAME_OVER = 1

These are simply defines that we use to pass into the notify function in order to tell it what event has happened.

Now we switch back to the TargetGame clasas and the notify function that we passed to the TargetSprite():

def on_target_event(self, event, target_sprite):
    """Called when an event is sent from the target
    sprite
    @param event - number - What has happened?
    @param target_sprite -TargetSprite - The sprite that
    has sent this event"""
    
    if (self.done==True):
        #We are already done don't bother
        return
    
    if (event == GAME_OVER):
        #The game is over!
        self.game_over()
    elif (event == TARGET_HIT):
        """A target has been hit
        Remove the hit target from the list and from
        the canvass"""
        self.targets.remove(target_sprite)
        self.game_canvas.Children.Remove(target_sprite.ellipse)
        #Update the score and the score text
        self.score += 1
        Score.Text = "Targets Hit: %d" % (self.score)
        #Now make sure that we have enough targets
        self.ensure_targets()

Now I hope you can see what is happening, we don’t have any game play just yet, but we have started working on the interaction between our sprites and the main game object. This function is pretty straight forward, if we got the GAME_OVER event then we call the game_over function and everything finishes.

If the event is a TARGET_HIT event then we need to remove the target that was hit from the targets list and the game_canvas. Then we need to update the score and the score text. Now this is the first time that we have referenced our TextBlock object. If you remember the XAML you’ll remember that we created a TextBlock object in order to display the score:

[code lang=”xml”]

[/code]

So in order to set the text, we simply reference the object by it’s name and set its text property:

Score.Text = "Targets Hit: %d" % (self.score)

Which I think is some pretty cool and intuitive interaction between our xaml and our python code.

Now we have most of the game “architecture” in place, but we still need to create our game loop, and a way for outside callers to start the actual game, enter the run function:

def run(self):
    """Start the game."""
    #initialize the elements
    self.done = False
    self.score = 0
    #Our storyboard timer
    self.gameLoop = Storyboard()
   #Set the name property for the 1.1 refresh
    self.gameLoop.SetValue[System.String](self.gameLoop.NameProperty, "GameLoop")
    #Add to the canvas
    self.game_canvas.Resources.Add(self.gameLoop)
    #Add the completed event handler
    self.gameLoop.Completed += EventHandler(self.on_game_timer)
    #Start the game loop
    self.gameLoop.Begin()

Now because of the way that Silverlight works we cannot simply use a normal game loop, instead we use a Storyboard object which is generally used for animations. What we do is tell the storyboard object to Begin its set of animations, but since there are no animations set up, it promptly quits and the Completed event fires, which we handle with the self.on_game_timer function.

def on_game_timer(self, sender, e):
        """This is the main game loop that we are going to be
        using."""

        #Update the sprites
        for sprite in self.targets:
            sprite.update()
        #If we are not done, start the timer again    
        if (not self.done):
            self.gameLoop.Begin()

What we do when our Storyboard ends is we update all of our targets, then if the game has not finished we restart the Storyboard, and the game loops.

The update function in the TargetSprite pretty simple, it updates the position of the Target and if the target has hit the bottom of the canvas then it fires the GAME_OVER event:

def update(self):
    """This is called when the sprite is supposed to update
    itself."""
    self.y += self.velocity
    wpf.SetPosition(self.ellipse, self.x, self.y)
    
    if ((self.y + self.height) >= self.game_canvas.Height):
        #We have hit the bottom! Game over!
        self.notify_function(GAME_OVER, self)

Now all we need is to do is start the game when the page loads, to do that we go back to our trusty on_canvas_loaded function:

def on_canvas_loaded(sender, e):
    target_game = TargetGame(root_canvas)
    target_game.run()

Now if you’ve made it this far in the code there shouldn’t be anything surprising about this, we basically initialise our TargetGame using the root_canvas, and then we tell that game to run, that’s it.

So that’s it, you can go play the game here if you want: http://www.learningpython.com/silverpy/index.htm my highest score is 93.

Here is all of the code:

from System import *
import _random
import wpf
from wpf import *
import clr
clr.AddReference('agclr')
clr.AddReference('System.Silverlight')

TARGET_HIT = 0
GAME_OVER = 1
NUM_TARGETS = 10

class TargetSprite(object):
    """The Target to hit"""
    
    def __init__(self, notify_function, game_canvas, x, y, width, height, velocity=1):
        """Initialize the target sprite.
        @param notify_function - function - The function to call when an event happens.
        @param game_canvas - Canvas object - The canvas that the 
        TargetSprite will be added to.
        @param x - int - X position
        @param y - int - Y position
        @param width - int - The width
        @param height - int - The height
        @param velocity = 1 - int - How fast we are going to move down.
        """
        self.notify_function = notify_function
        self.game_canvas = game_canvas
        self.x = x
        self.y = y
        self.width = width
        self.height = height
        self.velocity = velocity
                
        self.add_to_canvas()
        
    def add_to_canvas(self):
        """Add yourself to the canvas"""
        
        #Create the Ellipse
        self.ellipse = System.Windows.XamlReader.Load('<ellipse Stroke="Black" StrokeThickness="2" Fill="SlateBlue"/>')
        #Height, Width, and position
        self.ellipse.Height = self.height
        self.ellipse.Width = self.width
        #Add to canvase
        self.game_canvas.Children.Add(self.ellipse)
        #Set the position
        wpf.SetPosition(self.ellipse, self.x, self.y)
        """Connect out click event handler with the Let button down
        event."""
        self.ellipse.MouseLeftButtonDown += MouseEventHandler(self.on_ellipse_click)
        
    def on_ellipse_click(self, sender, e):
        """We have been clicked on, call the notify function
        and tell them."""
        self.notify_function(TARGET_HIT, self)
    
    def update(self):
        """This is called when the sprite is supposed to update
        itself."""
        self.y += self.velocity
        wpf.SetPosition(self.ellipse, self.x, self.y)
        
        if ((self.y + self.height) >= self.game_canvas.Height):
            #We have hit the bottom! Game over!
            self.notify_function(GAME_OVER, self)
    
class TargetGame(Object):
    """A Quick Target game"""
    
    def __init__(self, game_canvas):
        """Init the Target Game
        @param game_canvas - The canvas for the game.
        """
        #Create a random object
        self.random = _random.Random()
        #Save the game canvas
        self.game_canvas = game_canvas
        #The score
        self.score = 0
        #The list of targets that we have
        self.targets = []
        #Make sure that we have the minimum number of targets
        self.ensure_targets()
        #hook into the keydown event
        self.game_canvas.KeyDown += EventHandler(self.on_key_down)
        #Not done yet
        self.done = False
    
    def on_key_down(self, sender, e):
        """Check to see if they hit escape"""

        if (e.Key == 8):
            self.game_over()
    
    def game_over(self):
        """Called when the game should end"""
        self.game_over_text = TextBlock()
        self.game_over_text.FontSize = 50
        self.game_over_text.Text = "GAME OVER"
        self.game_canvas.Children.Add(self.game_over_text)
        wpf.SetPosition(self.game_over_text
            , 100
            , 100)
        #We are done
        self.done = True
            
    def ensure_targets(self):
        #Make sure that we have enough targets
        while (len(self.targets) < NUM_TARGETS):
            self.targets.append(self.create_target())
            
    def create_target(self):
        #Create a new target and return it
        
        #Init to random size and position
        x = int(self.random.random()*400)
        width = int(self.random.random()*30) + 20
        height = int(self.random.random()*30) + 20
        y = 0 - height
        """Init the velocity to a random number based off of the 
        score so that more targets are hit, the game gets harder."""
        velocity = int(self.random.random()*(int(self.score / 15)+1))
        #The minimum velocity is 1
        if (velocity<=0):
            velocity = 1
    
        return TargetSprite(self.on_target_event
                , self.game_canvas, x, y,width, height
                , velocity)
                
    def on_target_event(self, event, target_sprite):
        """Called when an event is sent from the target
        sprite
        @param event - number - What has happened?
        @param target_sprite -TargetSprite - The sprite that
        has sent this event"""
        
        if (self.done==True):
            #We are already done don't bother
            return
        
        if (event == GAME_OVER):
            #The game is over!
            self.game_over()
        elif (event == TARGET_HIT):
            """A target has been hit
            Remove the hit target from the list and from
            the canvass"""
            self.targets.remove(target_sprite)
            self.game_canvas.Children.Remove(target_sprite.ellipse)
            #Update the score and the score text
            self.score += 1
            Score.Text = "Targets Hit: %d" % (self.score)
            #Now make sure that we have enough targets
            self.ensure_targets()
            
    def run(self):
        """Start the game."""
        #initialize the elements
        self.done = False
        self.score = 0
        #Our storyboard timer
        self.gameLoop = wpf.Storyboard()
        #Set the name property for the 1.1 refresh
        self.gameLoop.SetValue[System.String](self.gameLoop.NameProperty, "GameLoop")
        #Add to the canvas
        self.game_canvas.Resources.Add(self.gameLoop)
        #Add the completed event handler
        self.gameLoop.Completed += EventHandler(self.on_game_timer)
        #Start the game loop
        self.gameLoop.Begin()
        
    def on_game_timer(self, sender, e):
        """This is the main game loop that we are going to be
        using."""

        #Update the sprites
        for sprite in self.targets:
            sprite.update()
        #If we are not done, start the timer again    
        if (not self.done):
            self.gameLoop.Begin()
            
def on_canvas_loaded(sender, e):
    target_game = TargetGame(root_canvas)
    target_game.run()

All in all it’s pretty simple to create something like this using Silverlight and python. Hopefully this tutorial provides enough information so that all of you can create your own game or application, if you do drop me a line I’d love to check it out.

As always if you have any questions, comments, or spot a problem with the tutorial, add a comment below.

PyLan three

Hello welcome to the long-time-coming third article in this tutorial. I apologize to everyone (anyone?) that was waiting for it. I have been very busy as of late and have had much of my time taken up by a few other python projects, that I hope to be able to show you all soon.

If you want to follow along with the code in detail, and have not done so already, you should read part one and part two of this series.

You can download the full source to this tutorial here.

This tutorial will teach you the following things:

1. How to construct a simple theme engine, or at least how I would, hopefully it will give you some ideas!
2. How to display icons in a gtk.TreeView
3. How to catch the selection event in a gtk.TreeView.
4. How to enable or disable widgets.
5. How to remove the selection from a gtk.TreeView if the user clicks on the gtk.TreeView but not on a tree item.

This tutorial is organized into the following sections:

1. A Simple Theme Engine
2. Showing Icons
3. Enabling and Disabling Widgets
4. Removing Unwanted Selection
5. Conclusion

As with other tutorial in this series this will not go into all details and changes that were made in the code, instead it will deal with a few main subjects that will hopefully provide ideas and sample code to others interested in python and PyGtk programming.

A Simple Theme Engine

Now a while back I had an interesting idea that I would like to create a simple theme engine for the PyLan application. I thought that it would be easy and let me (or other people) change the icons or colours that are used.

So my idea was to use a dictionary object indexed by constant keys, whose values would be “theme objects.”

I thought that this would be a simple enough idea that I could implement quickly and then expand in the future to have more features like the ability to save and load the theme from xml.

So to start we create a file called theme.py and filled it with all of the basics and some imports and some constants:

try:
	import gtk
	import helper
except:
  	print _("import Error")
  	
PIXMAP = 0
COLOUR = 1

Next we create our Theme object that will serve as the applications theme. In this version the Theme object is still very simple, here is it in its entirety:

class Theme(dict):
	"""This object represents all of the necessary information needed
	to properly present information in a pyLan application...or any
	application
	"""

	def __init__(self, theme_dict = None):
		"""initialize the theme
		@param theme_dict - dictionary of values.  If None it is
		ignored, if not none, it's values will be stored in the internal
		theme_dictionary."""

		self.load_from_dictionary(theme_dict)

	def load_from_dictionary(self, theme_dict, initialize = False):
		"""This function loads all of the theme values
		from the theme_dict into the internal theme dictionary.
		@param theme_dict - dictionary - A theme dictionary that
		describes theme items.
		@param initialize = False - boolean, do we want to blank
		out the internal dictionary before we load the items?
		"""
		#Make sure that the dict is not None
		if (not theme_dict):
			return
		#clear yourself out
		dict.clear(self)

		for key,value in theme_dict.iteritems():
			self[key] = value

So what is happening here? Not that much, the Theme object uses the dict object as a base class and then lets you initialize the Theme using a dictionary, which is done using a helper function. This was put for future usage and is not used yet.

The next item in the Theme setup is the ThemeItem object. This is the object that will be used as the value for each item in our Theme dictionary.

class ThemeItem(object):
	"""An item in the theme.  This is used to store all of the
	necessary theme information.
	"""

	"""Type property - Cannot be set, only set in the
	initializer."""
	def __get_type(self):
		return self._m_type
	type = property(__get_type)

	"""Data Property"""
	def __get_data(self):
		return self._m_data
	data = property(__get_data)

	def __init__(self, type):
		"""Initialize yourself.
		@param type - number - The type of theme item.
		"""
		self._m_type = type
		self._m_data = None
		#now load the data
		self.load_data()

	def load_data(self):
		"""This function is call when the Theme item
		should load any data that it needs. i.e. if it
		is a pixmap it should load the image file.
		it should create the data.
		"""
		pass

First you can see that there are two date members in the ThemeItem base class, the _m_type and _m_data. The _m_type is simply used to let interested parties know what the type of theme object is. I’m not sure if the _m_type is still needed, originally I was using it but after changing a few things it doesn’t really do much (anything?) anymore.

The next data member is that _m_data item that is meant to be private and accessed through the data property. As you can see the data property cannot be set it can only be read. This was done this way so that only the ThemeItem would be able to set its data.

Now the data member can be anything, it could be an image, a colour, whatever you want it to be. The data member will generally be set by a subclass of the ThemeItem. You’ll also notice that the data is “loaded” in the __init__ function. By default the load_data() function does nothing, and should be overridden in the base class.

The only type that I have in use so far is the ThemePixmap object. This is a ThemeItem that sets its data to be a gtk.gdk.pixbuf:

class ThemePixmap(ThemeItem):
	"""A Them item that represents a pixmap to be displayed."""

	def __init__(self, file_name = ""):
		"""Initialize the pixmap theme item.
		@param file_name - string - the path to the
		pixmap file.
		"""
		self.file_name = file_name
		ThemeItem.__init__(self, PIXMAP)

	def load_data(self):
		"""This is where we load the pixmap based on the file name"""
		try:
			self._m_data = gtk.gdk.pixbuf_new_from_file(self.file_name)
		except gerror, e:
			helper.show_error_dlg(_("Error loading pixmap %s = %s")
				% (self.file_name, e))
			self._m_data = None

Pretty straightforward here, a simple subclass of the ThemeItem object that overrides the load_data() function and adds a new class member. The load_data function simply loads a pixmap into the data using the gtk.gdk.pixbuf_new_from_file function.

Now how do we use this?

In the main pyLan.py file I added the following function to initalize the theme, it is called from the __init__ function and could theoretically be called from other locations:

def initialize_theme(self):
	"""This function is used to initialise the
	theme."""
	self.app_theme = theme.Theme()
	self.app_theme[CATEGORY_ICON] = theme.ThemePixmap(
		os.path.join(self.pixmaps, "stock_book_blue.png"))
	self.app_theme[TASK_ICON] = theme.ThemePixmap(
		os.path.join(self.pixmaps, "stock_task.png"))

So this is how I use the theme in the main PyLan application, I’m using it to determine what icon to display for tasks and what icon to use for categories.

As you can see I simply create a theme member in the PyLan class and the add two ThemePixmap items to the Theme, each index by constants that will be used to identify them later. In the future I hope to use this function to load the information from a file.

The constants used in the function are defined as follows:

CATEGORY_ICON 			= 1
TASK_ICON				= 2

I will show you how the theme is used in the next section.

Showing Icons

So now that we have a simple theme engine that load graphics for us we need to figure out how to show images in our gtk.TreeView.

What we will do is we will use the gtk.CellRendererPixbuf to render our image. We will also pack the image into the same column as the Title column. We do this so that the icon isn’t in a column of it’s own, which would seem quite strange.

Basically what we will do is create the gtk.TreeViewColumn in our normal way, using the gtk.CellRenberPixbuf, then when we use the gtk.TreeViewColumn.pack_start function to add the gtk.CellRendererText (representing the Title Text) to add the text to column. This means that we will have two cell renderers in the same column.

The actual code to accomplish this in the pyLan program is quite complicated as I attempted to use the todoColumn object as a generic way to order the columns. This worked fine before but now it has become a more complicated and slightly hackish now that we want to be able to pack items into the same column.

Sufficed to say I accomplished this by adding a new share_column member to the totoColum that allows you to Pack Widgets.

We also have to update the get_column_list() function in the todo.Task and todo.Category items so that they returns the pixbuf from the theme. This also means that we need to add a new member to the todo.todoBase object:

def __init__(self, type, app_theme):
	"""The only way to set the type is through the
	initialization"""
	self.__m_type = type
	self.app_theme = app_theme

Where app_theme is an instance of our Theme object described in the previous section.

Then in the get_column_list() the todo.Category objects need to add the following:

elif (item_column.ID == pyLan.COL_ICON):
	lst_return.append(self.app_theme[pyLan.CATEGORY_ICON].data)

and the todo.Theme object needs to add the following:

elif (item_column.ID == pyLan.COL_ICON):
	lst_return.append(self.app_theme[pyLan.TASK_ICON].data)

Pretty simple, all we do is we get that Theme item in the applications theme and then return its data. If this seems strange or you cannot understand it, please take a look at the previous tutorial and you you will be able to understand what the get_column_list() function does.

Enabling and Disabling Widgets

One of the things that has been bothering me about the PyLan application was that all of the buttons on the toolbar were always enabled even when they cannot perform their function.

Now I’m used to the Enable/Disabled terminology except in GTK the terms sensitive and insensitive are used, so I will try to use them from now on, but if an enabled or a disabled slips in there please forgive me.

The first thing that we need to add is an initialize_widgets() function to the PyLan class, this function will gather widgets that we need and will set their default state. This needs to be called early in the __init__ function before initialize_todo_tree() is called. The function is as follows:

def initialize_widgets(self):
	"""Initialize any widgets that we want.  Basically
	grab widgets that you want to have access to later
	on in the program.
	"""
	#Get the widgets
	self.edit_button = self.wTree.get_widget("btnEdit")
	self.delete_button = self.wTree.get_widget("btnRemoveCategory")
	self.add_task_button = self.wTree.get_widget("btnAddTask")
	#disable them
	self.edit_button.set_sensitive(False)
	self.delete_button.set_sensitive(False)
	self.add_task_button.set_sensitive(False)

The code is pretty simple, we grab the widgets from the widget tree, and then we simply call the set_sensitive function and tell them to be insensitive by passing False to the function.

The next step is to connect the application to the “changed” signal that is emitted by the gtk.TreeSelection that is associated with our gtk.TreeView. To do so we need to add the following code to the initialize_todo_tree() function:

#Enable the selection callback
selection = self.todoTreeView.get_selection()
selection.connect('changed', self.on_tree_selection_changed)

Pretty simple, we get the gtk.TreeSelection from the gtk.TreeView and then we connect the on_tree_selection_changed() function with the changed signal.

The on_tree_selection_changed() function is relatively simple as well:

def on_tree_selection_changed(self, selection):
	"""Called when the selection has changed in the
	tree.
	@param selection - gtk.TreeSelection - The selection
	object associated with the gtk.TreeView.
	"""
	model, selection_iter = selection.get_selected()
	#If there is a selection then enable these
	self.edit_button.set_sensitive((selection_iter != None))
	self.delete_button.set_sensitive((selection_iter != None))
	self.add_task_button.set_sensitive((selection_iter != None))

First we get the selection_iter from the gtk.TreeSelection and then we enable the edit, delete, and add_task buttons based on whether or not there is a selection in the gtk.TreeView. If nothing is selected then we make the buttons insensitive.

Removing Unwanted Selection

One feature that I wanted to implement in the application was the ability to remove selection from the tree by clicking on an empty space in the tree. As far as I can tell there is no simple method to enable a feature like this in PyGTK, which I found quite surprising.

As a result what I needed to do was connect to the gtk.TreeView’s button-press-event. Then we use the location where the user clicked and see if they clicked on an item in the tree. If they did not click on an item in the tree then we remove the selection from the tree. If they did click on something then we leave the selection as is.

def on_todoTree_button_press_event(self, widget, event):
	"""There has been a button press on the TodoTree
	for now we use this as a quick hack to remove
	the selection.  Perhaps there is a better way?
	@param widget - gtk.TreeView - The Tree View
	@param event - gtk.gdk.event - Event information
	"""
	#Get the path at the specific mouse position
	path = widget.get_path_at_pos(int(event.x), int(event.y))
	if (path == None):
		"""If we didn't get apath then we don't want anything
		to be selected."""
		selection = widget.get_selection()
		selection.unselect_all()

As you can see, we take position of the cursor where the button was pressed and then call the get_path_at_pos() function in the gtk.TreeView which returns a tuple containing information if an item in the tree can be found at the specified x,y position, and None if nothing in the tree was hit.

It’s not pretty but it works!

You can download the full source to this tutorial here.

Conclusion

Now one of the problems that I had writing this tutorial is that it’s getting very hard to detail all of the changes that are made to the project. So I have tried to leave out as much extraneous detail as I possibly could, but then I start to wonder how much use anyone could get out of these articles if the details are left out.

Hopefully there is still enough in there so that people can get ideas and at least some hints as to how things work in some of the slightly more advanced areas of PyGTK.

I’m not sure if I am going to continue detailing everything in this test application, I might skip a few phases since detailing everything is getting to be more of a problem. But what I really want to focus on soon is working with things like Preferences and distributions. Sadly time is always a factor!

If you have any questions please ask away as always!

PyLan two

This is part two of the PyLan tutorial series, if you want to follow along with the code in detail, and have not done so already, you should read part one of this series.

In this tutorial I will go over the following items:

• Showing a popup window
• Working with a gtk.Calendar widget
• Working with gtk.ComboBox widgets
• Working with Pango markup in a gtk.TreeView
• Working with gtk.CheckButton widgets
• Working with the DateTime python module.

This tutorial is organized into the following sections:

1. The GUI
2. The todo.Task Object
3. Adding a todo.Task object
4. Showing the Calendar window
5. Editing todo.Category and todo.Task items
6. Pango markup in the gtk.TreeView
7. Conclusion

You can download the full source to this tutorial here.

The GUI

I will be working with the same glade project as last time, except I will be adding a some new dialogs and buttons. I will not go over all of the changes in the GUI since many of them are very simple changes, similar to changes that have been made in previous tutorials.

For example I decided to get rid of the Dropdown menu for adding the Categories and the tasks, instead I decided to create separate buttons to do the two separate tasks. I won’t describe the switch here, since adding toolbar buttons is pretty straightforward. For anyone interested in why I decided to make this switch, the answer is pretty simple, I didn’t like using the drop down menu as much as I thought that I would. Instead I found it confusing and prone to error. As a result I made the switch to the separate buttons.

So here is a non-comprehensive list of the changes that I made to the GUI in case you were interested in seeing how something was done.

The Task dialog

This dialog is used to add or edit a todo.Task object.

• Create a Dialog with an Ok and a Cancel button. Sets it’s name to be “taskItemDialog”, and its title to be “Task Item”. Give it a width of 300 and a height of 225.
• Add a Vertical Box to the dialog with 2 rows. In the second row add a Check Button with the label “Completed” and the name “checkCompleted”.
• In the first row add a table with two columns and four rows. To the following to the table, adding vertical padding of 3 pixels to each space in the second column:
  • Add a label with the label “Title” in [0, 0].
  • Add a Text Entry in [0, 1] and call it enTitle
  • Add a label with the label “Details” in [1, 0], give it three pixel of horizontal padding.
  • Add a Text View in [1, 1] and call it tvDetails. In the scrolled window’s properties set the H Policy to “Never” and the V Policy to “Automatic”. This means that there will never be a horizontal scrollbar, and that there will be a vertical scrollbar only when one is necessary.
  • Add a label in [2, 0] with the Label “Due:”.
  • Add a horizontal box with three columns in [2, 1]. In the first add an entry labelled enDueDate, in the second add a button named btnDue add a clicked signal handler, and in the third add a combobox and give it the name “cmbTime”. Add time entries to the combobox in the form: “”(blank),12:00AM, 12:30AM, 01:00AM…11:30PM. Then right-click on the button and select it in the menu and then select “Remove Button Contents”. Then add an arrow to the button and set its direction to down. The button will be used to display a Calendar so that the people can select the due date.
  • Add a label in 3,0 and set its label to “Priority:
  • Add a Combo Box in 3,1 and set its name to “cmbPriority”. Set its items to “High”, “Medium”, and “Low”.

The Calendar Window

This is a popup window that we will us to let the user select the due date for their tasks.

• Add another window, and call it “calendarWindow”. Set its border width to 1, its title to “”, its type to “popup”, modal to “yes”, resizeable to “no”, and skip taskbar to “yes”.
• Add a vertical box to the window with two rows.
• In the first row ad a calendar widget and call it “calendarWidget”
• In the second row add a button with the name “btnNoDate”. Set the label to be “No Date” and the icon to be gtk-no. Add a clicked signal handler.

The todo.Task object

The todo.Task object is used to represent the task item in the same way that the todo.Category object represents a category item. The astute among you will notice that I renamed the category object, I just thought that todo.Category looked so much better then todo.todoCategory.

Since we will be using the datetime and time python modules to represent the due date for tasks we need to import them in the todo file:

import datetime
import time

The todo.Task class is relatively simple, if you’ve read the first tutorial it should be very easy to understand this code:

class Task(todoBase):
	"""This is a task in the todoTree.  It represents
	something that needs to be done.
	"""

	#Name property
	def __get_name(self):
		return self.__m_name
	def __set_name(self, name):
		self.__m_name = name
	name = property(__get_name, __set_name)

	#Due date property
	def __get_due_date(self):
		return self.__m_due_date
	def __set_due_date(self, due_date):
		self.__m_due_date = due_date
	due_date = property(__get_due_date, __set_due_date)

	#Due time property
	def __get_due_time(self):
		return self.__m_due_time
	def __set_due_time(self, due_time):
		self.__m_due_time = due_time
	due_time = property(__get_due_time, __set_due_time)

	#priority property
	def __get_priority(self):
		return self.__m_priority
	def __set_priority(self, priority):
		self.__m_priority = priority
	priority = property(__get_priority, __set_priority)

	def __init__(self, name):

		#init variables
		self.__m_name = ""
		self.__m_due_date = None
		self.__m_due_time = None
		self.__m_priority = ""

		self.completed = False
		self.details = ""

		#set properties
		self.name = name
		#init base
		todoBase.__init__(self, TASK)

		"""Format strings so that the date and time
		formats returns can easily be changed."""
		self.date_format = "%Y-%m-%d"
		self.time_format = "%I:%M%p"

	def __str__(self):
		return _("todo .Task object: name = %s") % (self.name)

	def get_column_list(self, todoColumnList):
		"""This function is used to get the display list
		for the todoTree. The todoCOlumnList controls the
		order that the list will be returned in.
		@param todoColumnList - list - A list of todoColumn items.
		Their type member should use used to determine the order
		of the returned list.
		@returns list - A list for the todoTree.
		"""

		lst_return = []
		# Loop through the columns and create the return list
		for item_column in todoColumnList:
			if (item_column.ID == pyLan.COL_OBJECT):
				lst_return.append(self)
			elif (item_column.ID == pyLan.COL_OBJECT_TYPE):
				lst_return.append(self.type)
			elif (item_column.ID == pyLan.COL_TITLE):
				lst_return.append(self.name)
			elif (item_column.ID == pyLan.COL_DETAILS):
				lst_return.append(self.details)
			elif (item_column.ID == pyLan.COL_DUE):
				lst_return.append(self.get_datetime_string())
			elif (item_column.ID == pyLan.COL_PRIORITY):
				lst_return.append(self.priority)
			elif (item_column.ID == pyLan.COL_COMPLETED):
				if (self.completed):
					lst_return.append(_("True"))
				else:
					lst_return.append(_("False"))
			else:
				helper.show_error_dlg(_("Error unknown column ID: %d" % item_column.ID))
				lst_return.append("")

		return lst_return

	def get_date_string(self):
		"""This function is used to get the Date string. It will
		be returned in the format of self.date_format.
		@returns - string - The current Due date or "" if nothing
		has been set yet.
		"""

		date_string = ""
		if (self.due_date):
			date_string = self.due_date.strftime(self.date_format)
		return date_string

	def get_time_string(self):
		"""This function is used to get the time string. It will
		be returned in the format of self.time_format.
		@returns - string - The current Due time or "" if nothing
		has been set yet.
		"""

		date_string = ""
		if (self.due_time):
			date_string = self.due_time.strftime(self.time_format)
		return date_string

	def get_datetime_string(self):
		"""Used to get the date and the time in their
		specified formats.
		@returns - string - the date and the time.
		"""

		date_string = self.get_date_string()
		time_string = self.get_time_string()
		if (len(time_string)>0):
			date_string = "%s %s" % (date_string, time_string)

		return date_string

One thing that you may notice is how we use the datetime and time modules. You should notice that we have two member variables:

self.date_format = "%Y-%m-%d"
self.time_format = "%I:%M%p"

These variable store the date and time format that we will use to display the date and time in the tree. We will pass the format strings to thestrftime function (from the python docs):

date, datetime, and time objects all support a strftime(format) method, to create a string representing the time under the control of an explicit format string. Broadly speaking, d.strftime(fmt) acts like the time module’s time.strftime(fmt, d.timetuple()) although not all objects support a timetuple() method.

We define them as members of the class so that they can be changed easily and even pickled with the object itself.

I won’t go into too much other detail about this class since it’s pretty much just a data holder for now, and is very similar to the todo.Category object explained in tutorial one except that it has a few more data members.

Adding a todo.Task object

For this we are going to have to use the task dialog that we created in the GUI stage. We are going to encapsulate the handling of displaying the dialog in a class. It made sense to me to do this since this dialog is far more complicated then many that we have used before.

The class is called TaskDialog and I created it in the todo.py file:

class TaskDialog(object):
	"""This is a class that is used to show a taskDialog.  It
	can be used to create or edit a todo.Task.  To create one
	simply initialize the class and do not pass a totoTask.  If you
	want to edit an object initialize with the object that
	you want to edit."""

	def __init__(self, glade_file, task = None):
		"""Initialize the task dialog.
		@param glade_file - string - the glade file for this
		dialog.
		@param task - todo.Task - None to create a new
		todo.Task object, or the object that you wish to
		edit.
		"""
		self.glade_file = glade_file
		self.task = task

		#Get the widget tree
		self.wTree = gtk.glade.XML(self.glade_file, "taskDialog")
		#Connect with yourself
		self.wTree.signal_autoconnect(self)
		self.dialog = self.wTree.get_widget("taskDialog")
		#get the widgets from the dlg
		self.en_title = self.wTree.get_widget("enTitle")
		self.tv_details = self.wTree.get_widget("tvDetails")
		self.en_due = self.wTree.get_widget("enDue")
		self.btn_due = self.wTree.get_widget("btnDue")
		self.cmb_Time = self.wTree.get_widget("cmbTime")
		self.cmb_priority = self.wTree.get_widget("cmbPriority")
		self.check_completed = self.wTree.get_widget("checkCompleted")
		#select the items in the combo boxes
		self.cmb_Time.set_active(0)
		self.cmb_priority.set_active(2)

		wTreeDue = gtk.glade.XML(self.glade_file, "calendarWindow")
		self.calendar_window = wTreeDue.get_widget("calendarWindow")
		wTreeDue.signal_autoconnect(self)

		self.update_dialog_from_object()

As you can see what happens here is the TaskDialog is initialized with the path to the glade file that contains the taskDialog, and an optional todo.Task object. If the todo.Task is not specified (or None) when creating the TaskDialog then the TaskDialog instance is in “add” mode, which means that it will create a todo.Task object with the settings specified on the dialog if the user presses the Ok button.

If an instance of a todo.Task object is used when constructing the TaskDialog then the dialog is in “edit” mode, and it will modify the object that was passed if the user presses the Ok button.

So not much happens in the __init__ function except we load the dialog and the calendar window from the glade file (the calendar window must be set not to be initially visible in the glade file! Otherwise it will be shown when it is loaded.) and we auto connect the signals from the dialog and the window with the TaskDialog class.

Then we get access to all of the important widgets on the task dialog. You’ll also notice that we set the active item in both the time and priority gtk.ComboBox’s using the set_active() function.

We do this so that the first item is selected in the time gtk.ComboBox (the blank) and we select the third item in the priority gtk.ComboBox so that the low priority item is selected.

At the end of the function we call the update_dialog_from_object() function, this function is used to update what is displayed on the dialog based on the contents of the todo.Task. There is a sister function named save_data_to_object() that is used to update the todo.Task item with the contents of the dialog:

def update_dialog_from_object(self):
	"""Used to update the settings on the dialog"""

	if (self.task):
		#Title
		self.en_title.set_text(self.task.name)
		#Details
		self.set_details(self.task.details)
		#Due Date
		self.en_due.set_text(self.task.get_date_string())
		#Due Time
		found_iter = self.find_text_in_combo(self.cmb_Time
						, self.task.get_time_string())
		if (found_iter):
			self.cmb_Time.set_active_iter(found_iter)
		#priority
		found_iter = self.find_text_in_combo(self.cmb_priority
									, self.task.priority)
		if (found_iter):
			self.cmb_priority.set_active_iter(found_iter)
		#completed
		self.check_completed.set_active(self.task.completed)


def save_data_to_object(self):
	"""This function is used to read the data from the dialog
	and then store it in the todo.Task object.
	"""
	if (self.task == None):
		self.task = Task(self.en_title.get_text())
	else:
		self.task.name = self.en_title.get_text()

	self.task.details = self.get_details()

	self.task.set_due_date_from_string(self.en_due.get_text())
	self.task.set_due_time_from_string(self.cmb_Time.get_active_text())
	self.task.priority = self.cmb_priority.get_active_text()
	self.task.completed = self.check_completed.get_active()

Over all these two functions are pretty straightforward, they simply marshal the date between the dialog and the todo.Task. You’ll see that there are some helper functions that are used in both functions in order to make saving and loading the data from the object to the dialog easier. For example to set the text in the gtk.TextView we use the set_details() function, and then to get the text we use the get_details() function:

def get_details(self):
	"""This function gets the details from the TextView
	@returns string - The text in the gtk.TextView
	"""
	txtBuffer = self.tv_details.get_buffer()
	return txtBuffer.get_text(*txtBuffer.get_bounds())

def set_details(self, details):
	"""This function sets the text in the defails gtk.TextView
	@param details - string - The text that will be
	put into the gtk.TextView.
	"""
	txtBuffer = self.tv_details.get_buffer()
	txtBuffer.set_text(details)

These two function are very simple, we get the gkt.TextBuffer associated with the gtk.TextView and then we use the get_text() and set_text() functions to get and set the text.

The next helper that we use is the find_text_in_combo() function:

def find_text_in_combo(self, combobox, text):
	"""This is a helper function use to find text in
	a gtk.ComboBox.
	@param conbobox gtk.ComboBox - This should contain
	text.
	@param text - string - the text that we are looking
	to find.
	@returns - gtk.TreeIter - The iter at the found
	position or None if nothing was found.
	"""
	found_iter = None #The Iter where text is found
	#Get the gtk.TreeModel associated with the combo
	combo_model = combobox.get_model()
	if (combo_model):
		#Get the first iter in the model
		search_iter = combo_model.get_iter_first()
		"""Now loop through the model checking for
		matches until one is found.  Or until
		we have ran out of iters."""
		while ((found_iter == None)
			and (search_iter)):
			if (text == combo_model[search_iter][0]):
				#Found!
				found_iter = search_iter
			else:
				search_iter = combo_model.iter_next(search_iter)
	return found_iter

This function takes a gtk.ComboBox and a string as parameters and searches the gtk.TreeModel associated with the gtk.ComboBox for the text. If the text is found then the gtk.TreeIter associated with that item is returned, otherwise None is returned. The function is pretty simple, but I was slightly disappointed that there was no built in way to do this…perhaps I missed something or perhaps this will be addressed in a future release.

Then once we have the gtk.TreeIter we can use the set_active_iter() to set that item as the current item in the gtk.ComboBox.

To get the date and time we use the todo.Task.get_time_string() and todo.Task.get_date_string() functions that we have already touched on. The setting of the due date and due time however is slightly more complicated and I have not gone over it yet. What we need to do is generate datetime.date and datetime.time instances from strings.

The following two functions in the todo.Task are used to accomplish this:

def set_due_date_from_string(self, date_string):
	"""This function is used to set the due_date based
	on a string. We will try to parse the string.  We will try
	to parse the following formats: YYYY-MM-DD
	, MM-DD-YYYY, or DD-MM-YYYY
	@param date_string - string - The string that we will
	turn into our datetime.date object.
	@returns boolean - success or failure"""
	success = False
	#Switch chars
	date_string = date_string.replace("/","-")
	date_string = date_string.replace("\\","-")
	date_string = date_string.replace(" ","")
	#All the possible formats
	lst_formats = [
		"%Y-%m-%d"
		, "%m-%d-%Y"
		, "%d-%m-%Y"]
	#Now loop through the formats and try to find a match
	date = None
	for format in lst_formats:
		try:
			date = datetime.datetime(*time.strptime(date_string
						, format)[0:3])
			#We found a matching format
			self.due_date = date
			#Save the format
			self.date_format = format
			break
		except:
			#failed
			pass
	return success

def set_due_time_from_string(self, time_string):
	"""This function is used to set the due_time based
	on a string. We will try to parse the string.  We will try
	to parse some formats.
	@param time_string - string - A string representing the
	time.
	@returns - boolean success or failer
	"""
	success = False
	#strip whitespace
	time_string = time_string.replace(" ","")
	#All the possible formats
	lst_formats = [
		"%I:%M%p"
		, "%H:%M%p"]
	#Now loop through the formats and try to find a match
	due_time = None
	for format in lst_formats:
		try:
			time_struct = time.strptime(time_string
						, format)
			due_time = datetime.time(time_struct.tm_hour
						, time_struct.tm_min)
			#Save the time
			self.due_time = due_time
			#Save the format that was used
			self.time_format = format
			success = True
			break
		except:
			#failed
			pass
	return success

The functions are slightly difficult to understand I will take a little bit of time to explain how they work. The general idea of the functions is to loop through a list of possible formats and try to create either a datetime.date or datetime.time instance using the current format.

If the creation throws an exception then it has failed, if it does not then it has succeeded and we need to save the format that we used (it becomes the format that we display things in, so if you type in the date in a certain way it will be displayed in that way,) and save the actual instance.

We use the time modules strptime function to create a struct_time, which we then use to create the date or time instance (from the python documentation):

Parse a string representing a time according to a format. The return value is a struct_time as returned by gmtime() or localtime(). The format parameter uses the same directives as those used by strftime(); it defaults to “%a %b %d %H:%M:%S %Y” which matches the formatting returned by ctime(). If string cannot be parsed according to format, ValueError is raised. If the string to be parsed has excess data after parsing, ValueError is raised. The default values used to fill in any missing data when more accurate values cannot be inferred are (1900, 1, 1, 0, 0, 0, 0, 1, -1) .

Support for the %Z directive is based on the values contained in tzname and whether daylight is true. Because of this, it is platform-specific except for recognizing UTC and GMT which are always known (and are considered to be non-daylight savings timezones).

struct_time is simply a sequence of 9 integers that we can then use to create our date or time instances. The only real difference between the two is that instead of always being able to use the first three numbers in the struct_time sequence when creating the date instance we need to reference the specific time members when creating the time object.

So the code is a bit complicated, but when you look the overview of what it’s doing it’s actually pretty simple.

The next thing we have to do is actually show do the dialog:

def run(self):
	"""Show the dialog"""

	break_out = False
	while (not break_out):
		result = self.dialog.run()
		if (result==gtk.RESPONSE_OK):
			"""Save the date to the object becuase the use pressed
			ok."""
			self.save_data_to_object()
			break_out = True
			#Validate here eventually
		else:
			break_out = True

	self.dialog.hide()

	return result;

Another simple function (I seem to say that a lot don’t I?) we’re just showing the dialog, and if the users clicks on the OK button we save the data to our todo.Task object and then we leave. You might wonder why this is done in a loop, the reason is so that in the future we will be able to validate what the user has entered.

So when if the user clicks on the OK button and the validation fails, then we would not set break_out to True, and the dialog would be shown again. This is just an easy way to set up the dialog for future validation.

The last thing that we need to do is actually use the dialog! We do this in the on_add_task() function in our main PyLan class:

def on_add_task(self, widget):
	"""Called when we want to add a task."""

	model, selection_iter, todo_cat = self.get_category_selected()
	#Make sure that a category is selected
	if ((model) and (selection_iter) and (todo_cat)):
		task_dialog = todo.TaskDialog(self.gladefile)
		if (task_dialog.run() == gtk.RESPONSE_OK):
			#Append to the tree
			task_dialog.task.add_to_tree(model
				, selection_iter
				, self.__tree_columns)
			#Add to the Category
			todo_cat.add_child(task_dialog.task)

Pretty simple stuff here again (I’m like a broken record!) we get the selected category, if all of the variables come through then we create the todo.TaskDialog in “add” mode and then we run it. If the response is gtk.RESPONSE_OK we add the task to the tree, and then add the task to the category.

If you are wondering about the last two steps there, then you should check out the first tutorial where those helpers are explained.

Showing the Calendar window

This next step took me a long time to figure out even though the actual code is very short. This step is getting the calendar window, that we created in our glade project, to display when the user clicks on the Due Date “dropdown” button.

So here is the code:

def on_btnDue_clicked(self, widget):
	"""Called when the due button is clicked."""
	rect = widget.get_allocation()
	x, y = widget.window.get_origin()
	cal_width, cal_height = self.calendar_window.get_size()

	self.calendar_window.move((x + rect.x - cal_width + rect.width)
		, (y + rect.y + rect.height))

	self.calendar_window.show()

	"""Because some window managers ignore move before
	you show a window."""
	self.calendar_window.move((x + rect.x - cal_width + rect.width)
		, (y + rect.y + rect.height))

So the first thing we do is use the gtk.Widget.get_allocation() function to get the gtk.gdk.Rectangle representing the size of the btnDue button.

Then we get the X and Y screen coordinates of the gtk.gdk.Window (the window where the widget is actually drawn) using the get_origin() function. This is in root window coordinates instead of being relative to the parent window. So this is actually the top left corner of the TaskDialog.

Then we get the height and width of the calendar window, and finally move it into position so that the top right corner of the calendar window lines up with the bottom right corner of the btnDue widget.

So, we take the top left corner of the dialog, and then add onto it the x,y coordinates of the btnDue (which are relative to the top left cornet of the TaskDialog) and then we add to it the height and the width of the btnDue so that we get the X and Y of the bottom right corder of the btnDue. Then we subtract the width of the calendar window, so that the right side of the calendar window lines up with the right side of the btnDue.

If this seems a bit confusing try playing with the numbers a little bit, commenting out parts of the equation, and then see where the calendar window shows up. After playing with it a little bit it should be pretty straight forward.

So what happens when then calendar window is displayed? Well it will stay visible until the user double-clicks on a date, or clicks on the “No Date” button.

So we need to add two signal handlers:

def on_btnNoDate_clicked(self, widget):
	"""Called when the now date widget is
	clicked.  This means that they do not want
	a due date."""
	#Hide the calendar window
	self.calendar_window.hide()
	self.en_due.set_text("")

def on_calendarWidget_day_selected_double_click(self, widget):
	"""Called when the used has double-clicked on a date
	in the calendar widget"""
	#Hide the calendar window
	self.calendar_window.hide()

	year, month, day = widget.get_date()
	month +=1 #since it's 0 based
	self.en_due.set_text("%d-%02d-%02d" % (year, month, day))

Pretty simple stuff here, if the “No Date” button is clicked then we blank out the due date edit field, and if a date is double clicked on, we get the date from the gtk.Calendar using the get_date() function. Then we set the date in the edit fields based on those values.

For now we use a standard format, but in the future we could easily work with the date_format stored in the todo.Task object.

Editing todo.Category and todo.Task items

The next step is letting the user edit a todo.Category or todo.Task item that they have already added to the list. Fortunately the way that we have shown both the Category and Task dialogs makes this step very easy.

The first thing that we need to do is add an “edit” event handler in the PyLan class. This function can be triggered from a menu item, or from the edit button in the main toolbar:

def on_edit_object(self, widget):
	"""Called when we want to edit the selected item"""

	# Get the selected object
	model, selection_iter, todo_ob = self.get_selected_object()
	if ((selection_iter) and (model) and (todo_ob)):
		"""All right something and we have all the needed data"""
		self.edit_object(todo_ob, model, selection_iter)

Pretty simple, we call a helper function get_selected_object() which does exactly that, gets the selected object, the gtk.TreeIter associated with it, and the gtk.TreeModel that it is displayed in. Then we call edit object with those parameters.

get_selected_object() is a lot like the get_selected_category() function:

def get_selected_object(self):
	"""Just a helper function that will give you the
	selected object, whether it is a todoItem or
	a todoTask.
	@returns A 3-tuple containing a reference to the
	gtk.TreeModel and a gtk.TreeIter pointing to the
	currently selected node. Just like
	gtk.TreeSelection.get_selected but with the todoObject
	being returned as well."""

	todo_ob = None
	tcolumn, pos = self.find_todoColumn(COL_OBJECT)
	if (not tcolumn):
		return None,None,None

	#Get the current selection in the gtk.TreeView
	selection = self.todoTreeView.get_selection()
	# Get the selection iter
	model, selection_iter = selection.get_selected()
	if (selection_iter and model):
		#Something is selected so get the object
		todo_ob = model.get_value(selection_iter, tcolumn.pos)
	return model, selection_iter, todo_ob

The edit_object() function is equally as easy:

def edit_object(self, todo_object, model, object_iter):
	"""Helper function used to edit an object in the tree.
	@param todo_object - todoBase - The object that we
	are editing.
	@param model - gtk.TreeModel - The model for the tree.
	@param object_iter - gtk.TreeIter representing the
	todo_object's position in the tree.
	"""
	#Just make sure that they are all correct
	if ((todo_object) and (model) and (object_iter)):
		if (todo_object.type == todo.CATEGORY):
			#Edit category
			name = self.show_category_dialog(todo_object.name)
			if (name):
				todo_object.name = name
				todo_object.set_tree_values(model
					, object_iter
					, self.__tree_columns)
		else:
			#Edit task
			task_dialog = todo.TaskDialog(self.gladefile, todo_object)
			if (task_dialog.run() == gtk.RESPONSE_OK):
				todo_object.set_tree_values(model
					, object_iter
					, self.__tree_columns)

So what we do is ensure that the parameters passed in are valid, then we check the type of the object, and then show the correct dialog. If the user presses the Ok button then we update the data that is stored in the model by calling a new function set_tree_values():

def set_tree_values(self, tree_model, iter, todoColumnList):
	"""This is used to set the values in a tree.
	For whatever reason you cannot use the same list that you
	use to append items into the tree?  I don't know why.
	@param tree - gtk.TreeStore - The tree store that we will be
	setting the values in
	@param iter - gtk.TreeIter - The item in the tree
	@param todoColumnList - list - A list of todoColumn items.
	Their type member should use used to determine the order
	of the returned list."""
	lst_values = self.get_column_list(todoColumnList)
	count = 0
	for value in lst_values:
		tree_model.set_value(iter, count, value)
		count += 1

This function is defined in the todo.todoBase class, which is the base class for both the todo.Task and todo.Caegory. It can be overwritten by either if they want to perform some special processing, but by default it does everything that we need. It gets the list of values to display in the tree, and then loops through that list setting each value in the model.

So that’s basically editing items, not too difficult. The only other feature that I added was allowing you to edit an item when you double-click on in the gtk.TreeView. I was slightly surprised to find out that there was no “double-click” signal for the gtk.TreeView instead one has to handle the row-activated signal:

The “row-activated” signal is emitted when the row_activated() method is called or the user double clicks a treeview row. “row-activated” is also emitted when a non-editable row is selected and one of the keys: Space, Shift+Space, Return or Enter is pressed.

So we can handle the “row-activated” signal like this:

def on_todoTree_row_activated(self, tree_view, path, tree_column):
	"""This is called when a row is "activated" in the tree
	view.  It happens when the user double clicks on an item
	in the tree.  We will use it to edit the item.
	@param tree_view gtk.TreeView - The Tree
	@param path - string - The path string
	@param tree_column - gtk.TreeViewColumn - The column that
	was clicked on.
	"""
	#Get the column of the object
	tcolumn, pos = self.find_todoColumn(COL_OBJECT)
	model = tree_view.get_model()
	if ((tcolumn) and (model)):
		#Now get the selection iter from the path
		selection_iter = model.get_iter(path)
		if (selection_iter):
			#Now that we have the selection let's get the object
			todo_ob = model.get_value(selection_iter, tcolumn.pos)
			#Now lets edit the object
			self.edit_object(todo_ob, model, selection_iter)

First we get the model and the object column. Then we use the path that was passed to the signal handler to get the gtk.TreeIter that matches it. Then we get the todo object and we edit it.

Pretty simple, and now instead of having to find the edit button in the toolbar you can simple double-click on an item in order to edit it.

Pango markup in the gtk.TreeView

Since you currently cannot tell the difference between a category and a task I decided to make the category titles bold so that you can quickly tell the difference.

This is actually quite easy to do once you know what you need to do. It took me a little while to find information on how to do this, but once I was able to find the information implementing it was pretty simple.

The first thing that we need to do is update the todoColumn object to have a new member variable: markup. This lets us know that this column will display markup instead of simple text.

So now the create_column() function in the todoColumn class, which was added to handle the creating of columns, looks like this:

def create_column(self):

	column = None
	if (self.visible):
		if (self.markup):
			column = gtk.TreeViewColumn(self.name
					, self.cellrenderer
					, text = self.pos)
		else:
			column = gtk.TreeViewColumn(self.name
					, self.cellrenderer
					, markup = self.pos)

	return column

So if the member variable markup is set to True, then instead of getting the text from the specified position in the model, the column gets the markup from that position.

Then when the todo.Category populates the tree with it’s values in the get_coloumn_list() it returns the title with markup:

def get_column_list(self, todoColumnList):
	"""This function is used to get the display list
	for the todoTree. The todoCOlumnList controls the
	order that the list will be returned in.
	@param todoColumnList - list - A list of todoColumn items.
	Their type member should use used to determine the order
	of the returned list.
	@returns list - A list for the todoTree.
	"""

	lst_return = []
	# Loop through the columns and create the return list
	for item_column in todoColumnList:
		if (item_column.ID == pyLan.COL_OBJECT):
			lst_return.append(self)
		elif (item_column.ID == pyLan.COL_OBJECT_TYPE):
			lst_return.append(self.type)
		elif (item_column.ID == pyLan.COL_TITLE):
			lst_return.append("<b>%s</b>" % self.name)
		else:
			lst_return.append("")
	return lst_return

So pretty simple, we wrap the title in the bold tags and then it displays as bold.

Conclusion

You can download the full source to this tutorial here.

So that’s it for this one, not as long or drawn out as the last one, but I think some interesting ground is covered. Again this isn’t necessarily to teach you how to do everything that I’m doing, but to provide examples of how one might do things.

If you’re ever wanting to program something that you have never done before, I always think it’s nice to see examples of how other people do it. Even if you don’t do it in the exact same manner, you will at least have an idea of how to approach the task. Something that I really couldn’t find for a few features. For example the drop-down gtk.Calendar, which, come to think of it, would make a really nice custom widget if anyone was thinking of creating one.

As always if you find any errors or have any questions feel free to leave a comment. If however you have a general question about python or PyGTK I would appreciate it if you ask it in the LearningPython forums so that a possible solution to someone elses problem will not get buried in an unrelated area.

Introduction

All right, many of you have probably heard of, or read, David Allen’s book Getting Things Done if not it’s a pretty interesting book about how to organize the things in your life.

As I was reading it I thought that a simple todo list could be created using Python and PyGTK pretty easily, so I decided to create the application and write a tutorial surrounding it. Since the actual application is quite large I have decided to break it up into a series of tutorials, each highlighting a few specific tasks. The full goal of this series is to show everything that is required when creating a python/PyGTK based application, for the GUI setup all the way to distribution.

These tutorials assume that you have a basic knowledge of python and PyGTK. If you have not already done so it is recommended that you take a look at some of my previous PyGTK based tutorials as I will be glossing over much of that which is explained there:

• Creating a GUI using PyGTK and Glade
• Building an Application with PyGTK and Glade
• Extending our PyGTK Application
• Translating your Python/PyGTK application
• Writing a Custom Widget Using PyGTK
• WordPy offline blogging tool
• WordPy 0.2 – Using XML to Save and Load Data

PyLan – part one

So the application that we will be creating will be called PyLan, pronounced: plan. In brief it will be used to create a tree of tasks that can be organized into categories and subcategories.

You can download the full source to this tutorial here.

Part one of this tutorial will introduce you to the idea of the application and create the basic shell for it. It will outline the following:

• Creating the basic GUI in Glade
• Working with a gtk.TreeView
• Working with a gtk.TreeStore
• Saving and loading the data from the tree using cPickle.
• Using a gtk.MenuToolButton

The tutorial is organized into the following sections:

1. The GUI
2. The Code: Setting it all up
3. The Code: Initializing the tree
4. The Code: todo items
5. The Code: Adding Categories
6. The Code: Removing Categories
7. The Code: Saving and Loading with cPickle
8. The Code: Connecting our menu with the gtk.MenuToolButton
9. Conclusion

The GUI

The GUI will be created using Glade, it will be a relatively simple especially in this first part. Since the glade project file is available I won’t go into too much detail about how to create this GUI, however I will outline the major steps that one could follow in case they would like to create their own GUI, or model a GUI after this one.

The main window:

1. Create a new Glade Project and save it as pylan a folder named PyLan that you have created.
2. Create a window, and call it “mainWindow”, set its title to be PyLan. If you are using Glade3 make sure that you set your window to be visible. Add the GObject destroy signal handler like usual. On the common tab set the width to be 400 and the height to be 300.
3. Add a vertical box to the window and give it 4 rows.
4. In the first row add a menu, call it “mainMenu”. Make the Quit menu item’s menu handler the same as the Main Windows destroy signal handler. For the rest of the File menu items, give them signal handlers using the following format: “on_file_new”, “on_file_open”, and so on.
5. In the second row add a tool bar with two items.
6. In the first spot add a GtkMenuToolButton, and set its name to “btnAdd”. Make it a stock gtk-add button, and add a clicked signal handler with the name “on_add_category”.
7. In the second spot at a GtkToolButton with the name “btnRemoveCategory”, being a stock gtk-remove button. Set its clicked signal hander to be “on_remove_item”.
8. In the fourth row add a Status Bar.
9. In the Third row add a Tree View, set its name to be “todoTree”

The category dialog

1. Now create a Dialog with an Ok and a Cancel button. Sets it’s name to be “categoryDialog”, and its title to be
2. “Category”. Give it a default width and a width of 300. Set its named icon to be: “stock_post-message”.
3. Add a GTKHBox to the dialog with two columns.
4. In the fist column add a GtkLabel with the label “Name:”. Give it an X Pad of 3 pixels.
5. In the second column add a GtkEntry with the name: “enName”

The Menu for the Add button

Since we used a GtkMenuToolButton, we need to create the menu that we are going to associate with that button. To do that we will use a GtkMenu.

1. Create a GtkMenu and call it: “addMenu”
2. Add one Menu item to the menu with the label “Add _Category”. Set the menu items handler “on_add_category”

After all of that you should be left with something like this:

The Code: Setting it all up

Much of this initial code is taken from previous pyGTK tutorials, so if you are confused about any of this starting code, I suggest you take a look at the previous PyGTK tutorials where it is explained in depth. Create this in a file called pyLan.py in the same directory where you saved your glade project.

#!/usr/bin/env python

# PyLan - Python + PyGTK todo list
# Copyright (C) 2007 Mark Mruss <selsine @gmail.com>
# http://www.learningpython.com
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU Library General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
#
# If you find any bugs or have any suggestions email: selsine@gmail.com
# URL: http://www.learningpython.com

__author__ = "Mark Mruss </selsine><selsine @gmail.com>"
__version__ = "0.1"
__date__ = "Date: 2007/02/17"
__copyright__ = "Copyright (c) 2007 Mark Mruss"
__license__ = "GPL"

_ = lambda x : x
try:
 	import pygtk
  	pygtk.require("2.0")
except:
  	pass
try:
	import sys
	import gtk
	import gtk.glade
	import gobject
	import os
	import locale
	import gettext
	import cPickle
	import helper
	import todo
except ImportError, e:
	print "Import error pyLan cannot start:", e
	sys.exit(1)

FILE_EXT = "pylan"
APP_NAME = "pyLan"


class pyLan(object):
	"""A simple python based GTD todo list"""

	def __init__(self):

		#Get the local path
		self.local_path = os.path.realpath(os.path.dirname(sys.argv[0]))
		#Translation stuff
		self.initialize_translation()
		#Set the Glade file
		self.gladefile = os.path.join(self.local_path, "pylan.glade")
		#Get the Main Widget Tree
		self.wTree = gtk.glade.XML(self.gladefile, "mainWindow")
		#Connect with yourself
		self.wTree.signal_autoconnect(self)

		#init todo file
		self.todo_file = None
		#Get the Main Window
		self.main_window = self.wTree.get_widget("mainWindow")
		self.set_window_title_from_file(self.todo_file)

	""""
	************************************************************
	* Initialize
	************************************************************
	"""

	def initialize_translation(self):
		"""This function initializes the possible translations"""
		# Init the list of languages to support
		langs = []
		#Check the default locale
		lc, encoding = locale.getdefaultlocale()
		if (lc):
			#If we have a default, it's the first in the list
			langs = [lc]
		# Now lets get all of the supported languages on the system
		language = os.environ.get('LANGUAGE', None)
		if (language):
			"""language comes back something like en_CA:en_US:en_GB:en
			on linuxy systems, on Win32 it's nothing, so we need to
			split it up into a list"""
			langs += language.split(":")
		"""Now add on to the back of the list the translations that we
		know that we have, our defaults"""
		langs += ["en_CA", "en_US"]

		"""Now langs is a list of all of the languages that we are going
		to try to use.  First we check the default, then what the system
		told us, and finally the 'known' list"""

		gettext.bindtextdomain(APP_NAME, self.local_path)
		gettext.textdomain(APP_NAME)
		# Get the language to use
		self.lang = gettext.translation(APP_NAME, self.local_path
			, languages=langs, fallback = True)
		"""Install the language, map _() (which we marked our
		strings to translate with) to self.lang.gettext() which will
		translate them."""
		gettext.install(APP_NAME, self.local_path)

	""""
	********************************************************
	* Simple Helpers
	********************************************************
	"""

	def set_window_title_from_file(self, todo_file):
		"""Set the windows title, take it from todo_file.
		@param todo_file - string - The todo file name that we will
		base the window title off of
		"""
		if (todo_file):
			self.main_window.set_title("PyLan - %s"
				% (os.path.basename(todo_file)))
		else:
			self.main_window.set_title(_("PyLan - Untitled"))


	"""
	************************************************************
	* Signal Handlers
	************************************************************
	"""
	def on_mainWindow_destroy(self, widget):
		"""Called when the application is going to quit"""
		gtk.main_quit()

	def on_add_category(self, widget):
		"""Called when the Add Category button is clicked.
		Can also be generally used to add a category"""
		pass

	def on_remove_item(self, widget):
		"""called then the remove category button is clicked.
		Can also be generally used to remove a category or
		item."""
		pass

	def on_file_new(self, widget):
		"""File | New - Start a new project file, blank out
		the current project and start from scratch"""
		pass


	def on_file_open(self, widget):
		"""Function called to open a todo file"""
		pass

	def on_file_save(self, widget):
		"""File | Save function - Save the Todo file"""
		pass

	def on_file_save_as(self, widget):
		"""File | Save As function - Save the todo file"""
		pass

if __name__ == "__main__":
	plan = pyLan()
	gtk.main()

If you run the code you should be greeted with the following:

If you are familiar with my other tutorials none of this code should be very surprising to you. The only exception is perhaps the way that we connect our functions with the signal handlers:

self.wTree.signal_autoconnect(self)

So instead of creating a dict with our functions and then passing it to the signal_autoconnect() function we simply pass our class to the function, and then any of our functions that match the signal handlers in the widget tree will be connected. A very slick way to handle this if you ask me.

The Code: Initializing the tree

The next thing that we have to do is initialize our tree, i.e. set up the columns, create the model for the gtk.TreeView, and so on. I struggled with how to set up the columns for a while since I knew that I wanted them to be dynamic and for the application to function properly no matter what order the columns were in.

As a result I decided to use a simple class and a list of those objects to define what columns are available and what is in each column. I’m still not sure if this is the best way to handle it, but it meets most of my requirements and was relatively simple to implement.

The first thing that we need to do is create some “constants” near the top of our code right underneath out APP_NAME define:

"""Column IDs"""
COL_OBJECT = 0
COL_OBJECT_TYPE = 1
COL_TITLE = 2
COL_DETAILS = 3
COL_DUE = 4
COL_PRIORITY = 5
COL_COMPLETED = 6

These are the IDs of the columns that we will have in our list. For this tutorial most of these will remain unused, but as we progress more and more will be used. The IDs are used to let us know what each column is. So COL_OBJECT will be the column that holds the actual python object (as we did in the PyWine tutorial). COL_OBJECT_TYPE will hold the objects type, and so on.

Then we need a simple class that will contain this information:

class todoColumn(object):
	"""This is a class that represents a column in the todo tree.
	It is simply a helper class that makes it easier to inialize the
	tree."""

	def __init__(self, ID, type, name, pos, visible=False, cellrenderer = None):
		"""
		@param ID - int - The Columns ID
		@param type - int  - A gobject.TYPE_ for the gtk.TreeStore
		@param name - string - The name of the column
		@param pos - int - The index of the column.
		@param visible - boolean - Is the column visible or not?
		@param cellrenderer - gtk.CellRenderer - a constructor function
		for the column
		"""
		self.ID = ID
		self.type = type
		self.name = name
		self.pos = pos
		self.visible = visible
		self.cellrenderer = cellrenderer
		self.colour = 0

	def __str__(self):
		return "<todocolumn object: ID = %s type = %s name = %s pos = %d visible = %s cellrenderer = %s>" % (self.ID, self.type, self.name, self.pos, self.visible, self.cellrenderer)

This class should be created before the PyLan class. Then at the beginning of the PyLan class we will create a hidden member at the beginnig of the __init__() function:

"""The colum list, at one point this could be saved and loaded
		from a file."""
self.__tree_columns = [
			todoColumn(COL_OBJECT, gobject.TYPE_PYOBJECT, "object", 0)
			, todoColumn(COL_OBJECT_TYPE, gobject.TYPE_INT, "object_type", 1)
			, todoColumn(COL_TITLE, gobject.TYPE_STRING, _("Title"), 2, True, gtk.CellRendererText())
			, todoColumn(COL_DETAILS, gobject.TYPE_STRING, _("Details"), 3, True, gtk.CellRendererText())
			, todoColumn(COL_DUE, gobject.TYPE_STRING, _("Due"), 4, True, gtk.CellRendererText())
			, todoColumn(COL_PRIORITY, gobject.TYPE_STRING, _("Priority"), 5, True, gtk.CellRendererText())
			, todoColumn(COL_COMPLETED, gobject.TYPE_STRING, _("Completed"), 6, True, gtk.CellRendererText())
				]

So what we are doing is creating a list that defines the columns that will be added to our Tree. As you can see when we create each todoColumn instance we specify everything that is needed to create that column in the tree.

Next we’ll add a function that we will use to initialize our tree. This function will be called from our __init__() function:

#Connect with yourself
self.wTree.signal_autoconnect(self)

#Initialize the todo Tree
self.initialize_todo_tree()

def initialize_todo_tree(self):
		"""Called when we want to initialize the tree.
		"""
		tree_type_list = [] #For creating the TreeStore
		self.__column_dict = {} #For easy access later on

		#Get the treeView from the widget Tree
		self.todoTreeView = self.wTree.get_widget("todoTree")
		#Make it so that the colours of each row can alternate
		self.todoTreeView.set_rules_hint(True)

		# Loop through the columns and initialize the Tree
		for item_column in self.__tree_columns:
			#Add the column to the column dict
			self.__column_dict[item_column.ID] = item_column
			#Save the type for gtk.TreeStore creation
			tree_type_list.append(item_column.type)
			#is it visible?
			if (item_column.visible):
				#Create the Column
				column = gtk.TreeViewColumn(item_column.name
					, item_column.cellrenderer
					, text=item_column.pos)

				column.set_resizable(True)
				column.set_sort_column_id(item_column.pos)
				self.todoTreeView.append_column(column)

		#Create the gtk.TreeStore Model to use with the todoTree
		self.todoTree = gtk.TreeStore(*tree_type_list)
		#Attache the model to the treeView
		self.todoTreeView.set_model(self.todoTree)

So what we do in this function is first get our gtk.TreeView widget from our widget tree. Then we loop through the column list that we created, and add the column’s type to the tree_type_list, which will be used to create our gtk.TreeStore. If the todoColum is visible we need to create a gtk.TreeViewColum and then add it to the gtk.TreeView.

After we have looped through the column list we create the gtk.TreeStore (our model for the gtk.TreeView) based on all the types in our column list. Then we set that model as the model for our gtk.TreeView.

This may seem a bit confusing and if you have any problems understanding take a look at the Building an Application with PyGTK and Glade tutorial where the relationship between gtk.TreeViews, gtk.TreeViewColumns, gtk.CellRenderers (which we define in our todoColumn), and gtk.TreeModels is described. Basically the model (the gtk.TreeStore in this case) is the data. The View (gtk.TreeView, gtk.TreeViewColumn, gtk.CellRenderer) is what is used to display the data.

This means that you could have multiple views for the same data. We’re not doing that in this application so far, but the idea is quite powerful. We could, for example, use it to create a “simple” and “advanced” view for our data, or other “filtered” views.

Now if we run the code we get the following:

It’s the same as it was before, except now we have columns in our gtk.TreeView.

The Code: todo items

Now that we have our tree defined, we need to create the objects that will store the data. The data will be divided into two types (for now) a category and an task.

A Category is simply a container for other categories or items. An task is an actual task that you need to do.

So a category could be “Work” and in that category you might add another category called “Project X” and in “Project X” you may add the task “Implement feature y.” For this tutorial we will not be working with tasks, we will simply be working with categories.

We will create a new file in the same directory where we created our pyLan.py file. The file will be named todo.py. We will start off be defining the todoBase class which we will use as the base class for both the Category and Task classes:

#!/usr/bin/env python

import pyLan
import helper

CATEGORY = 0
TASK= 1

class todoBase(object):
	"""This is the base class for the todoCategory and
	the todoTask.
	"""

	#Type property
	def __get_type(self):
		return self.__m_type
	type = property(__get_type)

	def __init__(self, type):
		"""The only way to set the type is through the
		initialization"""
		self.__m_type = type

	def get_column_list(self, todoColumnList):
		"""This function is used to get the display list
		for the todoTree. The todoCOlumnList controls the
		order that the list will be returned in. Used as the
		second param in the gtk.TreeStore.append function.
		@param todoColumnList - list - A list of todoColumn items.
		Their type member should use used to determine the order
		of the returned list.
		@returns list - A list for the todoTree.
		"""
		pass

	def add_to_tree(self, tree, parent, todoColumnList):
		"""This function is used to add an item to a
		gtk.TreeStore, usually when loading.  All
		children will be added as well
		@param tree - gtk.TreeStore - The tree store that
		we wil be adding to.
		@param parent gtk.TreeIter - The parent of this
		item.
		@param todoColumnList - list - A list of todoColumn items.
		Their type member should use used to determine the order
		of the returned list.
		"""
		tree.append(parent, self.get_column_list(todoColumnList))

So the todoBase is simply a class with a type property (either CATEGORY, or TASK) that can only be set in the constructor and two functions get_column_list() and add_to_tree().

get_column_list() is used to create the second parameter for the gtk.TreeStore.append() function “a tuple or list containing ordered column values to be set in the new row.”

add_to_tree() is used to add the todo item to the actual tree. For the category class that we are going to create this is used to ensure that any children (i.e. categories or tasks) will also be added to the tree at the same time.

The todoCategory class is defined as follows:

class todoCategory(todoBase):
	"""This is a category in the todoTree.  It can have child categories
	or child tasks."""

	#Name property
	def __get_name(self):
		return self.__m_name
	def __set_name(self, name):
		self.__m_name = name
	name = property(__get_name, __set_name)

	def __init__(self, name):

		#init variables
		self.__m_name = ""
		self.name = name
		#children
		self.__m_children = []
		#init base
		todoBase.__init__(self, CATEGORY)

	def __str__(self):
		return _("<todocategory object: name = %s num_children = %d>") % (self.name, len(self.__m_children))

	def add_child(self, todo_object):
		"""Add a child to the category.
		@param todo_object - Either a todoCategory or a
		todoTask.  This will be a child of the category.
		"""
		self.__m_children.append(todo_object)

	def remove_child(self, todo_object):
		"""Removes a child from the category.
		@param todo_object - Either a todoCategory or a
		todoTask.  This will be a removed.
		"""
		try:
			self.__m_children.remove(todo_object)
		except ValueError, e:
			helper.show_error_dlg(_("Error removing child %s = %s") % (todo_object, e))


	def get_column_list(self, todoColumnList):
		"""This function is used to get the display list
		for the todoTree. The todoCOlumnList controls the
		order that the list will be returned in.
		@param todoColumnList - list - A list of todoColumn items.
		Their type member should use used to determine the order
		of the returned list.
		@returns list - A list for the todoTree.
		"""

		lst_return = []
		# Loop through the columns and create the return list
		for item_column in todoColumnList:
			if (item_column.ID == pyLan.COL_OBJECT):
				lst_return.append(self)
			elif (item_column.ID == pyLan.COL_OBJECT_TYPE):
				lst_return.append(self.type)
			elif (item_column.ID == pyLan.COL_TITLE):
				lst_return.append(self.name)
			else:
				lst_return.append("")
		return lst_return

	def add_to_tree(self, tree, parent, todoColumnList):
		"""This function is used to add an item to a
		gtk.TreeStore, usually when loading.  All
		children will be added as well
		@param tree - gtk.TreeStore - The tree store that
		we will be adding to.
		@param parent gtk.TreeIter - The parent of this
		item.
		@param todoColumnList - list - A list of todoColumn items.
		Their type member should use used to determine the order
		of the returned list.
		"""
		insert_iter = tree.append(parent, self.get_column_list(todoColumnList))
		if (insert_iter):
			for child in self.__m_children:
				child.add_to_tree(tree, insert_iter, todoColumnList)
		else:
			helper.show_error_dlg(_("Error loading category: %s" % self))

You can see that it sets its type by initializing the base class and passing it the CATEGORY constant. It also has some additional members, the name property and the private member __m_children. Name is the name of the category and __m_children is a list of todoBase objects that are the children of this category.

It implements two functions add_child() and remove_child() that are pretty self explanatory, and it overrides the get_column_list() and add_to_tree() functions from the todoBase.

You can see that in the get_column_list() function that the todoCategory only specifies three columns, for the rest is passes empty strings. It should be pretty obvious what the function is doing.

add_to_tree() is also overridden. What it does is add itself to the tree, if that succeeds it then loops through all of its children and then adds them to the tree as well. If that fails it calls the show_error_dlg() function from the helper module that has not been explained yet. All you need to know is that show_error_dlg() pops up a simple error dialog.

The Code: Adding Categories

Now that we have our category classes defined we need to work on adding them to the actual tree. To do that we will want to use our categoryDialog. We will show that to the user and let them set the name of the category. We will create a function called show_category_dialog() to do this for us:

def show_category_dialog(self, name):
	"""This function shows the category dialog.
	@param name - string - The name to display in
	category dialog by default.
	@returns - If OK is pressed the name typed on the
	dialog. If Cancel is pressed None is returned.
	"""

	#init to cancel
	name_return = None

	#load the dialog from the glade file
	wTree = gtk.glade.XML(self.gladefile, "categoryDialog")
	#Get the actual dialog widget
	dlg = wTree.get_widget("categoryDialog")
	#Get all of the Entry Widgets and set their text
	enName = wTree.get_widget("enName")
	enName.set_text(name)

	#run the dialog and store the response
	result = dlg.run()
	if (result==gtk.RESPONSE_OK):
		#get the value of the entry fields
		name_return = enName.get_text()
	#we are done with the dialog, destroy it
	dlg.destroy()

	#return the result
	return name_return

This function simply shows the dialog and returns the name that the person typed or None if they cancelled.

We will call this function from the on_add_category() function in the PyLan class. The on_add_category() function is called when you want to add a category to the Tree. It is called from either the addButton or from a menu item on the menu that the addButton can display. Here is the function:

def on_add_category(self, widget):
	"""Called when the Add Category button is clicked.
	Can also be generally used to add a category"""

	name = self.show_category_dialog("")
	if (name):
		# Get the selection category iter
		model, selection_iter, todo_cat = self.get_category_selected()
		#Create the new Category
		category = todo.todoCategory(name)
		#Append to the tree
		category.add_to_tree(self.todoTree
			, selection_iter
			, self.__tree_columns)
		if (todo_cat):
			"""something was selected so add the new category
			to the old category"""
			todo_cat.add_child(category)
		else:
			"""Nothing selected so add to the current project
			data"""
			self.__categories.append(category)