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)

The function is relatively simple as it relies on many helper functions. The first thing that it does is show the category dialog. If a valid name is returned then we continue adding the category.

We call the get_category_selected() function which is a helper function that is used to get the currently selected category, the gtk.TreeIter representing the selection, and the model associated with our gtk.TreeView. The function wraps the gtk.TreeView.get_selection() and the gtk.TreeSelection.get_selected() functions ensuring that todoCategory is selected. This means that if a todoTask is selected then its parent category will be returned.

We then create the category based on the name and add it to the tree. If there is a parent category (returned by get_category_selected()) then we add it to its children, otherwise we add it to a new private member self.__categories. self.__categories is basically a list of all of the top level todoCategories, it is our representation of the data displayed in the tree. It is created in the __init__ function:

#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)
#No categories
self.__categories = []

The get_category_selected() looks like this:

def get_category_selected(self):
	"""This function is a wrapper for the
	gtk.TreeView.get_selection() function and the
	gtk.TreeSelection.get_selected() function. It returns
	the same as gtk.TreeSelection.get_selected(), but ensures
	that it is a category that is selected. So if a todoTask
	is selected then it's parent category will be returned.
	@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.
	"""
	#First get the object column
	todo_ob = None
	tcolumn, pos = self.find_todoColumn(COL_OBJECT)
	if (not tcolumn):
		return 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):
		#Something is selected so get the object
		todo_ob = model.get_value(selection_iter, tcolumn.pos)
		if ((todo_ob) and (todo_ob.type != todo.CATEGORY)):
			#Alright we need the parent, this is not a category
			selection_iter = model.iter_parent(selection_iter)
			todo_ob = model.get_value(selection_iter, tcolumn.pos)
	return model, selection_iter, todo_ob

It relies on another helper function find_todoColumn which basically loops through the self.__tree_columns list looking for the todoColumn with the matching ID. If is found it is returned, along with the position in the list that it was returned at. This is partly done because I am unsure whether the order in the list will matter after initialization or whether the objects in the list should keep track of their position. If it is the objects, then they could be moved into a dictionary later on (you’ll notice that one is already created) for faster access.

We use find_todoColum() so that we can get the column representing the Object. (We use the Object instead of the type since we may need to get the actual object later. If we just wanted the type we could have used COL_OBJECT_TYPE)

Then what we do is we get the current gtk.TreeSelection and then get what (if anything) is actually selected within it. If something is selected (selection_iter is not None) then we check to see if the selected item is a category or not. If it is not a category we get the parent of the selecton iter, which we know is a category since tasks cannot have children.

Then we simply return all of the values: the current model, the gtk.TreeIter representing the selection category (may be None) and the todoCategory object (may also be none).

find_todoColumn() should be self explanatory:

def find_todoColumn(self, column_ID):
	"""This function is used to search the __tree_columns
	list to find a specific todoColumn.
	@param column_ID - The ID of the column that we
	are looking for.
	@returns todoColumn, int - The column found and
	the position in the list. If todoColumn is None
	then the column was not found.
	"""
	count = 0
	columnReturn = None
	for item_column in self.__tree_columns:
		if (item_column.ID == column_ID):
			columnReturn = item_column
			break
	if (columnReturn == None):
		#Something is really wrong we did not match
		helper.show_error_dlg(_("Error column data appears corrupted"))
	#Return the results
	return columnReturn, count

After all that code, we are finally able to add things to our tree!

It may seem complicated or like a lot of work, but in reality it’s simply a large process broken up into smaller reusable bits that make more sense when looked at as a whole.

The Code: Removing Categories

Now that we can add categories let’s add some code so that we can remove them. We will do this in the on_remove_item() function which is triggered by the btnRemoveCategory button’s clicked signal:

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."""

	#Get the column of the object
	tcolumn, pos = self.find_todoColumn(COL_OBJECT)
	#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 (tcolumn)):
		"""All right we have something to remove and we have the
		column that represents the todo object, first
		let's get the object from the selection_iter"""
		todo_ob = model.get_value(selection_iter, tcolumn.pos)
		if (todo_ob):
			"""Allright everything worked, time to remove. Does
			this item have a parent"""
			todo_parent, iter = self.get_parent_category(
				selection_iter, tcolumn.pos)
			#Remove from the tree
			model.remove(selection_iter)
			#if there is a parent, remove from the parent
			if (todo_parent):
				todo_parent.remove_child(todo_ob)
			else:
				"""There is no parent so remove from
				base list"""
				self.__categories.remove(todo_ob)

If you understood how we added the columns, how we remove them should be pretty straight forward. First we get the object todoColumn and the gtk.TreeSelection. Then if they are both valid we get the object that is selected. If nothing is selected then we can return because there is nothing to remove.

If something is selected then we call the helper get_parent_category() which simply gets us the item’s parent category. We then remove the selected item from the tree, but since the object is still stored within our data tree (self.__categories) we need to remove it from there.

If the item has a parent (todo_parent) we remove the item from the parent by calling remove_child(). If the item did not have a parent it means that it is a top level category and needs to be removed directly from self.__categories.

Here is get_parent_category():

def get_parent_category(self, selection_iter, object_pos = None):
	"""Get the parent category of the selection_item
	@param selection_iter - gtk.TreeIter - A iter whose
	parent you want to get.
	@param object_pos - number - The index of the object
	column.  If None this will be calculated.
	@returns - todoCategory, gtk.TreeIter - The parent category of the
	iter on success, or None on failure. The parent gtk.TreeIter
	"""
	if (object_pos == None):
		tcolumn, pos = self.find_todoColumn(COL_OBJECT)
		if (tcolumn):
			object_pos = tcolumn.pos
		else:
			#Column Data Error
			return None, None
			
	todo_parent = None
	selection_parent = None
	#Get the Model
	model = self.todoTreeView.get_model()
	#Get the current selection in the gtk.TreeView
	selection = self.todoTreeView.get_selection()
	if ((model) and (selection)):
		selection_parent = model.iter_parent(selection_iter)
		if (selection_parent):
			todo_parent = model.get_value(selection_parent, object_pos)

	return todo_parent, selection_parent

The Code: Saving and Loading with cPickle

Now that we can add and remove categories, the next thing that we want to do is be able to save and load our data to and from files. This code is very similar to the method used in my Extending our PyGTK Application so I will gloss over the repeated code and only explain the new stuff.

You probably remember the helper module mention above and used a little bit in some of the previously mentioned code. It’s simply a helper module that I have started to use so that I don’t always have to recode the same functions. The file’s name is “helper.py” and it looks like this:

#!/usr/bin/env python

try:
 	import pygtk
  	pygtk.require("2.0")
except:
  	pass
try:
	import os
	import gtk
except ImportError, e:
	print "Import error in helper:", e
	sys.exit(1)

def file_browse(dialog_action, filters, file_extension="", file_name=""):
	"""This function is used to browse for a file.
	It can be either a save or open dialog depending on
	what dialog_action is.
	The path to the file will be returned if the user
	selects one, however a blank string will be returned
	if they cancel or do not select one.
	dialog_action - The open or save mode for the dialog either
	gtk.FILE_CHOOSER_ACTION_OPEN, gtk.FILE_CHOOSER_ACTION_SAVE
	@param filters - list - list of  gtk.FileFilter() objects
	that will be added to the dialog.
	@param file_extension - string - The file extension that will be
	added to the filename when saving
	@param file_name - Default name when doing a save
	@returns - File Name, or None on cancel.
	"""

	if (dialog_action==gtk.FILE_CHOOSER_ACTION_OPEN):
		dialog_buttons = (gtk.STOCK_CANCEL
			, gtk.RESPONSE_CANCEL
			, gtk.STOCK_OPEN
			, gtk.RESPONSE_OK)
		dlg_title = _("Open File")
	else:
		dialog_buttons = (gtk.STOCK_CANCEL
			, gtk.RESPONSE_CANCEL
			, gtk.STOCK_SAVE
			, gtk.RESPONSE_OK)
		dlg_title = _("Save File")

	file_dialog = gtk.FileChooserDialog(title=dlg_title
		, action=dialog_action
		, buttons=dialog_buttons)
	"""set the filename if we are saving"""
	if (dialog_action==gtk.FILE_CHOOSER_ACTION_SAVE):
		file_dialog.set_current_name(file_name)
	#Add filters
	for filter in filters:
		file_dialog.add_filter(filter)
	if (dialog_action==gtk.FILE_CHOOSER_ACTION_OPEN):
		"""Create and add the 'all files' filter"""
		filter = gtk.FileFilter()
		filter.set_name(_("All files"))
		filter.add_pattern("*")
		file_dialog.add_filter(filter)

	"""Init the return value"""
	result = None
	if file_dialog.run() == gtk.RESPONSE_OK:
		result = file_dialog.get_filename()
		if (dialog_action==gtk.FILE_CHOOSER_ACTION_SAVE):
			result, extension = os.path.splitext(result)
			result = result + "." + file_extension
	file_dialog.destroy()

	return result

def show_error_dlg(error_string):
	"""This Function is used to show an error dialog when
	an error occurs.
	error_string - The error string that will be displayed
	on the dialog.
	"""
	error_dlg = gtk.MessageDialog(type=gtk.MESSAGE_ERROR
				, message_format=error_string
				, buttons=gtk.BUTTONS_OK)
	error_dlg.run()
	error_dlg.destroy()

These are both old functions (changed slightly) so I won’t go over them.

The same is true for the File menu signal handers:

def on_file_new(self, widget):
	"""File | New - Start a new project file, blank out
	the currnet project and start from scratch"""
	self.__categories = []
	self.todo_file = None
	self.set_window_title_from_file(self.todo_file)
	self.reload_from_data()


def on_file_open(self, widget):
	"""Function called to open a todo file"""
	todo_file = helper.file_browse(gtk.FILE_CHOOSER_ACTION_OPEN
		, self.get_browse_filter_list()
		, FILE_EXT)
	#If we have a file
	if (todo_file):
		if (self.load_from_file(todo_file)):
			"""Allright it all worked! save the current file and
			set the title."""
			self.todo_file = todo_file
			self.set_window_title_from_file(self.todo_file)

def on_file_save(self, widget):
	"""File | Save function - Save the Todo file"""
	# Let the user browse for the save location and name
	if (self.todo_file == None):
		self.todo_file = helper.file_browse(gtk.FILE_CHOOSER_ACTION_SAVE
		, self.get_browse_filter_list()
		, FILE_EXT)
	#If we have a todo file
	if (self.todo_file):
		if (self.save_to_file(self.todo_file)):
			#Allright it all worked! Set the Title
			self.set_window_title_from_file(self.todo_file)

def on_file_save_as(self, widget):
	"""File | Save As function - Save the todo file"""
	todo_file = _("Untitled")
	if (self.todo_file != None):
		todo_file = os.path.basename(self.todo_file)

	todo_file = helper.file_browse(gtk.FILE_CHOOSER_ACTION_SAVE
		, self.get_browse_filter_list()
		, FILE_EXT)
	#If we have a xml_file
	if (todo_file):
		if (self.save_to_file(todo_file)):
			"""Allright it all worked! save the current file and
			set the title."""
			self.todo_file = todo_file
			self.set_window_title_from_file(self.todo_file)

They are all taken almost verbatim from previous tutorials so I won’t explaining them in detail. The do rely on one helper function: get_browse_filter_list() that simply creates a list of gtk.FileFilters to use when browsing:

def get_browse_filter_list(self):
	"""Used to get the list of gtk.FileFilter objects
	to use when browsing for a file.
	@returns - list - List of gtk.FileFilter objects
	"""
	filter = gtk.FileFilter()
	filter.set_name(_("Todo file"))
	filter.add_pattern("*." + FILE_EXT)
	return [filter]

The actual work of saving and loading the data happens in the save_to_file(), load_from_file(), and reload_from_data() functions. We’ll go over the save_to_file() function first:

def save_to_file(self, filename):
		"""Save the current todoproject to a filename
		@param filename - string - the file name to save
		the file too.
		@returns boolean - success or failure
		"""
		try:
			todo_file = open(filename, "w")
			cPickle.dump(self.__categories, todo_file, cPickle.HIGHEST_PROTOCOL)
			todo_file.close()
			return True
		except cPickle.PicklingError, e:
			helper.show_error_dlg(_("Error saving file: %s\r\n%s") % (filename, e))
			return False
		except:
			helper.show_error_dlg(_("Error saving file: %s" % filename))
			return False

Besides the exception handling, the actual code in this function is very simple:

todo_file = open(filename, "w")
cPickle.dump(self.__categories, todo_file, cPickle.HIGHEST_PROTOCOL)
todo_file.close()
return True

First we open the file for writing, then we use cPickle to dump our __categories tree into the file, and then we close the file. That’s it.

Loading the data is equally as simple:

def load_from_file(self, filename):
	"""Try to a todo project from a
	specific file.
	@param filename - string - the file name to load
	from
	@returns boolean - success or failure
	"""
	try:
		todo_file = open(filename, "rb")
		self.__categories = cPickle.load(todo_file)
		todo_file.close()
		self.reload_from_data()
		return True
	except cPickle.UnpicklingError, e:
		helper.show_error_dlg(_("Error opening file: %s\r\n%s") % (filename, e))
		return False
	except:
		helper.show_error_dlg(_("Error opening file: %s" % filename))
		return False

First we open the file for reading and in binary mode (as instructed by the Pickle documentation) and then we load the file into our self.__categories tree. After that we close the files and reload the tree from self.__categories using the reload_from_data() function.

def reload_from_data(self):
	"""Called when we want to reset everything based
	on internal data.  Probably called when a file has
	been loaded."""
	self.todoTree.clear()
	if (self.__categories):
		for todo_ob in self.__categories:
			todo_ob.add_to_tree(self.todoTree, None, self.__tree_columns)
	else:
		self.__categories = []

reload_from_data simply clears the gtk.TreeStore using the gtk.TreeStore.clear() function. Then it loops through all of the toplevel categories in self.__categories and adds each category to the tree by calling the add_to_tree() function. If self.__categories is None for some reason (perhaps a bad file?) we simply reset it to a blank list.

If you remember the add_to_tree() function you’ll remember that it will also add all children of the category (and their children recursively) to the tree.

The Code: Connecting our menu with the gtk.MenuToolButton

Well we’re almost done here, all we have to do is connect our gtk.MenuToolButton with the menu that we created way back in the GUI section. Up until now you may have noticed that the arrow beside the Add button has been greyed out or disabled, this is because we have not attached a menu to the button yet using the gtk.MenuToolButton.set_menu() function. We will connect the menu to the button in a function called initialize_menus() that will be called in the __init__ function:

#Initialize the todo Tree
self.initialize_todo_tree()
#initialize menus
self.initialize_menus()

def initialize_menus(self):
	"""Called to initialize the menus"""

	add_button = self.wTree.get_widget("btnAdd")
	#load the menu from the glade file
	wTree = gtk.glade.XML(self.gladefile, "addMenu")
	#connect the menu with the signals
	wTree.signal_autoconnect(self)
	#Get the menu dialog widget
	menu = wTree.get_widget("addMenu")
	if ((add_button) and (menu)):
		add_button.set_menu(menu)

The first thing that we do is get the our gtk.MenuToolButton “btnAdd” from the widget tree. Then we get the widget tree that represents the “addMenu”. We then auto connect that widget tree with ourselves (this connects the “Add Category” menu item with our on_add_category() function. Then we get the actual gtk.Menu from the menu’s widget tree.

If all of the widgets have been returned properly we then connect the two using the gtk.MenuToolButton.set_menu() function.

Now when you run the application you will be able to use the menu to add categories!

Conclusion

You can download the full source to this tutorial here.

Whew! That was a lot of code and a lot of text to get through. Hopefully you were able to understand and follow along with all of it, and hopefully the next parts won’t be as long! The only reason that this part was so long was that it had so much ground to cover and because so much of it had been covered before. Future tutorials should cover smaller and more discrete tasks.

You will also notice that none of the translation files are included with the source, this was simply left out for now since there will be more text added in the future. There are also some extra dialogs in the glade project that will be used in future tutorials, if you want you could start implementing them.

Of course you will probably never find yourself creating an application that is identical to this pyLan application, but the idea is that you may find yourself creating an application that is similar or that requires similar elements. In those situations hopefully you will be able to re-use or re-factor that code found in this, and future, tutorials.

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.

Time for a some food!

In this tutorial we will go over the (very) basic steps that you can use in order to translate (localize or internationalize) your PyGTK application. For this tutorial we are going to use the PyWine application that we have been working with in two previous tutorials:

• Building an Application with PyGTK and Glade
• Extending our PyGTK Application

The full source and necessary files for this tutorial can be downloaded here.

Creating our Portable Object Files

In order to translate our text we are going to use the gettext module. The gettext module is basically a wrapper for the GNU gettext utility whose documentation can be found here.

The first step is to edit our python file (pywine.py)and “mark” all of the strings that we want to translate in our python code. To do this we will use the _(”xxx”) standard that most people use to mark strings that need to be translated. Otherwise in situations like the following:

#Get the treeView from the widget Tree
self.wineView = self.wTree.get_widget("wineView")

“wineView” might be thought of as a string to be translated when it clearly should not be. So we need to go through the .py file and wrap each of my English strings in _(). Here are all of the strings that need to be marked in their marked form:

self.sWine = _("Wine")
self.sWinery = _("Winery")
self.sGrape = _("Grape")
self.sYear = _("Year")
self.show_error_dlg(_("Error opening file"))
self.show_error_dlg(_("Error opening file"))
file_dialog = gtk.FileChooserDialog(title=_("Select Project")
filter.set_name(_("pyWine database"))
filter.set_name(_("All files"))

The next step is to generate the Portable Object Template file using the command line gettext utility. If you are using Linux or OS X this should be no problem and gettext will probably already be installed. If you are using Windows the tools are available as .exe files from the GNU gettext FTP or this gettext for Win32 sourceforge project.

To create the PO Template you need to pass the gettext utility some information. The first thing is that the file being scanned is a python source file:

--language=Python

The second is that we only want to translate our marked strings:

--keyword=_

The third is that we want to create a .pot (PO template) file:

--output=pywine.pot

And the final argument is the file that we want to get the strings from:

pywine.py

So to put it all together it will look something like this:

xgettext --language=Python --keyword=_ --output=pywine.pot pywine.py

That would be all that we would have to use, but since we used Glade for our GUI we also have to extract and translate the strings from our Glade project. To do so the following line is used (taken from the great PyGTK FAQ entry: How do I internationalize a PyGTK and libglade program?):

intltool-extract --type=gettext/glade pywine.glade

That will create the file pywine.glade.h which contains the following:

char *s = N_("Add Wine");
char *s = N_("Edit Wine");
char *s = N_("Grape Variety: ");
char *s = N_("PyWine");
char *s = N_("Wine");
char *s = N_("Wine:");
char *s = N_("Winery: ");
char *s = N_("Year Produced: ");
char *s = N_("_About");
char *s = N_("_Add");
char *s = N_("_Edit");
char *s = N_("_File");
char *s = N_("_Help");
char *s = N_("_View");

You’ll notice that the strings are marked with the N_() mark. So when we create our PO template file we will want to take into account the pywine.py file, the pywine.glad.h file, the _() mark, and the N_() mark. To do so we will use the following command line:

xgettext --language=Python --keyword=_ --keyword=N_ --output=pywine.pot pywine.py pywine.glade.h

This will create a file named pywine.pot that contains the following:

# SOME DESCRIPTIVE TITLE.
# Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
# This file is distributed under the same license as the PACKAGE package.
# FIRST AUTHOR , YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2006-12-01 23:59-0500\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME \n"
"Language-Team: LANGUAGE \n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=CHARSET\n"
"Content-Transfer-Encoding: 8bit\n"

#: pywine.py:77 pywine.glade.h:5
msgid "Wine"
msgstr ""

#: pywine.py:78
msgid "Winery"
msgstr ""

#: pywine.py:79
msgid "Grape"
msgstr ""

#: pywine.py:80
msgid "Year"
msgstr ""

#: pywine.py:176 pywine.py:178
msgid "Error opening file"
msgstr ""

#: pywine.py:229
msgid "Select Project"
msgstr ""

#: pywine.py:237
msgid "pyWine database"
msgstr ""

#: pywine.py:242
msgid "All files"
msgstr ""

#: pywine.glade.h:1
msgid "Add Wine"
msgstr ""

#: pywine.glade.h:2
msgid "Edit Wine"
msgstr ""

#: pywine.glade.h:3
msgid "Grape Variety: "
msgstr ""

#: pywine.glade.h:4
msgid "PyWine"
msgstr ""

#: pywine.glade.h:6
msgid "Wine:"
msgstr ""

#: pywine.glade.h:7
msgid "Winery: "
msgstr ""

#: pywine.glade.h:8
msgid "Year Produced: "
msgstr ""

#: pywine.glade.h:9
msgid "_About"
msgstr ""

#: pywine.glade.h:10
msgid "_Add"
msgstr ""

#: pywine.glade.h:11
msgid "_Edit"
msgstr ""

#: pywine.glade.h:12
msgid "_File"
msgstr ""

#: pywine.glade.h:13
msgid "_Help"
msgstr ""

#: pywine.glade.h:14
msgid "_View"
msgstr ""

As you can see it contains both the translatable strings from the pywine.py file and the pywine.glade.h file. The next thing that we need to do is create a .PO (Portable Object) file. Each .PO file represents a specific translation to use. To create our PO file we will use the PO template file that we just created. We will use the msginit command line utility.

When running msginit we need to tell it what the input file is:

--input=pywine.pot

And what our current locale is. For me since I am an English speaking Canadian mine would be en_CA, which is language_COUNTRY. If I spoke Quebecois fluently (French Canadian) I might use fr_CA. You specify the locale as follows:

--locale=en_CA

If you want to see what locale you are, enter locale -a on the command line on a Unix-like operating system.

The command line to enter is as follows to create an English Canadian file:

msginit --input=pywine.pot --locale=en_CA

Let’s create an English US file as well

msginit --input=pywine.pot --locale=en_US

You may be asked for your email address so that someone can email you about your translation. If you entered the above you should see: en_CA.po and a en_US.po created in your pywine directory. Let’s edit this two files so that they are slightly different:

en_CA.po:

#: pywine.py:77 pywine.glade.h:5
msgid "Wine"
msgstr "Wine Canadian Style"

en_US.po:

#: pywine.py:77 pywine.glade.h:5
msgid "Wine"
msgstr "Wine US Style"

The next thing that we need to do is create the .mo file, which is the file that the gettext module will use for translation. The .mo files are simply binary versions of the ACSII .po files.

We first have to create the correct directory for the .mo files. Which is explained in bindtextdomain function for the Python gettext module:

bindtextdomain( domain[, localedir])
Bind the domain to the locale directory localedir. More concretely, gettext will look for binary .mo files for the given domain using the path (on Unix): localedir/language/LC_MESSAGES/domain.mo, where languages is searched for in the environment variables LANGUAGE, LC_ALL, LC_MESSAGES, and LANG respectively.

So for the above example we need to create the following directories:

en_CA/LC_MESSAGES
en_US/LC_MESSAGES

Which can be done using the following command:

mkdir -p en_CA/LC_MESSAGES
mkdir -p en_US/LC_MESSAGES

Now we use the msgfmt command line program to create our .mo files in the correct directory:

msgfmt --output-file=en_CA/LC_MESSAGES/pywine.mo en_CA.po
msgfmt --output-file=en_US/LC_MESSAGES/pywine.mo en_US.po

The Python Code

Now that we have our translation files ready we need to actually implement some python code in order to use them. Fortunately there really isn’t that much code for us to write, but I found a real lack of examples or information on the correct way to do this, and the code to be somewhat confusing.

The first step is to import the gettext and locale modules that we will use.

import locale
import gettext

The next step is to create a simple define for the domain of our translations, which is generally just the application name. The gettext module will use the domain name to look for .mo files. So if you domain is set to “12345″ gettext will look for 12345.mo files. You’ll notice that we created our .mo files are pywine.mo above so we are going to use “pywine” as our domain:

APP_NAME = "pywine"

Now, in general on a Unix like operating system you would install your .mo files into the correct locations in the /usr/lshare/locale directory. But since we are not installing this application and we want it to be easily portable to other operating systems, we will be storing the translations in the local directory.

Here is all of the code that we need to add to the __init__() function of the pywine class. It is quite complicated but hopefully the comments and my explanation after will make it easier to understand:

#Translation stuff

#Get the local directory since we are not installing anything
self.local_path = os.path.realpath(os.path.dirname(sys.argv[0]))
# 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):
	"""langage 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."""
_ = self.lang.gettext

Now I will explain the code in smaller pieces so that it is easier to understand what is happening. The first step is to get the path to the python file that is running, it’s pretty straight forward so I won’t explain it her.

The first real step is get get a list of languages, or locales that we want to support. This list will be used to determine both the order in which we search for .mo files and what .mo files we look for.

The first locale we get is default locale, we use the locale module to get this:

# 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]

The next step is to get the list of languages supported from the operating system environment. The string that is returned by this needs to be parsed up into a list so we will also handle that. On Win32 and OS X this value is not set, so we need to make sure we check if it is None:

# Now lets get all of the supported languages on the system
language = os.environ.get('LANGUAGE', None)
if (language):
	"""langage 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(":")

The final step in building our locale (or language) list is to add on the locales that we know we support, i.e. the .mo files that we have. We can add these to the list in whatever order we want, or if we are sure that they are all installed we could just add what we consider to be the default locale since we are sure that it will be found.

"""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 the reason that we add these last, is so that we can let the user’s language settings control what .mo file is actually used to for the translations. We add our own just in case nothing is found.

The next step is to bind our domain (pywine) to a specific folder (the local folder) and then to set the current domain, this will be used when we perform the search for .mo files:

gettext.bindtextdomain(APP_NAME, self.local_path)
gettext.textdomain(APP_NAME)

Here are the explanations for both functions from the python documentation:

bindtextdomain( domain[, localedir])
Bind the domain to the locale directory localedir. More concretely, gettext will look for binary .mo files for the given domain using the path (on Unix): localedir/language/LC_MESSAGES/domain.mo, where languages is searched for in the environment variables LANGUAGE, LC_ALL, LC_MESSAGES, and LANG respectively.
If localedir is omitted or None, then the current binding for domain is returned.

textdomain( [domain])
Change or query the current global domain. If domain is None, then the current global domain is returned, otherwise the global domain is set to domain, which is returned.

The next step is to get the actual translation that we want to use and connect the getttext with the .mo file:

# Get the language to use
self.lang = gettext.translation(APP_NAME, self.local_path
	, languages=langs, fallback = True)

The gettext.translation() function is explained as follows:

translation( domain[, localedir[, languages[, class_[, fallback[, codeset]]]]])
Return a Translations instance based on the domain, localedir, and languages, which are first passed to find() to get a list of the associated .mo file paths. Instances with identical .mo file names are cached. The actual class instantiated is either class_ if provided, otherwise GNUTranslations. The class’s constructor must take a single file object argument. If provided, codeset will change the charset used to encode translated strings.
If multiple files are found, later files are used as fallbacks for earlier ones. To allow setting the fallback, copy.copy is used to clone each translation object from the cache; the actual instance data is still shared with the cache.
If no .mo file is found, this function raises IOError if fallback is false (which is the default), and returns a NullTranslations instance if fallback is true.

So the function will search for .mo files to each of the languages in langs in order and then returns a GNUTranslations object on success or a NullTranslations object on fail (since we set fallback to True.)

We then bind the object returned by translation’s gettext function to the _. So when you call _(”xxx”) you are really calling self.lang.gettext(”xxx”). Calling _(”XXX”) is just a convenient shorthand and somewhat of a standard way to “mark” strings for translation, as we saw above.

"""Install the language, map _() (which we marked our
strings to translate with) to self.lang.gettext() which will
translate them."""
_ = self.lang.gettext

So that’s really all you have to do. Now if you execute py wine using the following:

PyWine$ LANG=en_CA python pywine.py

You will get the “Wine Canadian Style” header, then if you execute it as follows (on a Unix like OS):

PyWine$ LANG=en_CA python pywine.py

You will get the “Wine US Style” header. Then if you execute it with French from France (on a Unix like OS):

PyWine$ LANG=fr_FR python pywine.py

The results depends on how your system is configured, and you will either get the Canadian text or the USA text.

The full source and necessary files for this tutorial can be downloaded here.

Conclusion

So that it for translation, using this method should work on all available operating systems with no problem. I wanted to include a language file for totally different language (i.e. a French, or Spanish, or whatever .mo file) but my skills in multiple spoken languages are not that strong.

So if anyone wants to perform a simple translation on the pywine.pot file and sent it to me that would be very much appreciated. Then we could start getting people to test this on systems with different language settings.

While researching this tutorial I came across some really good information from these sites:

• Python, wxPython and internationalization (i18n)
• How do I internationalize a PyGTK and libglade program?

As always if you come across any bugs or find any problems in the code please let me know!

Hi everyone just a quick post to let you know that I probably won’t be posting much during this month as I have decided to participate in nanowrimo which leaves me almost no time to come up with tutorials.

I as mentioned in the past Satoshi Tanabe over at satolog has translated a few of my tutorials over into Japanese, which is very cool. It also turns out that someone over at blog.chinaunix.net has also translated one of my tutorials (Building an application with PyGTK and Glade) into Chinese, again very cool! Thanks a lot for the translations guys.

I’ve also been working on some pyGame in my spare time over the last few months, I’ve been working on a level editor and a widget set:

Of course that doesn’t show very much but it show show my scrollbars! The problem with building the level editor is that y you always have to keep working on the smallest details (like a scrollable area0 before you can get to the real heart of the problem. Oh well it’s till fun!

Talk to you all soon!

All right, so we have our base WordPy application running, so let’s try to extend it a bit more by letting you load and save blog posts to and from an xml file. Please note that this tutorial simply shows one method of saving and loading data using xml, there are many different methods and this method was chosen for its simplicity.

If you are unfamiliar with the first WordPy tutorial you should probably read it fist in order to have a better understanding of some of what happens in this tutorial.

You can download the complete code for this tutorial here.

The GUI

The first thing we need to-do is open up the wordpy glade project and make some changes:

1. We’ll start off by adding another item to our VBox in Glade. You can do this by holding down shift and clicking on the WordPy window until you see the GTKVBox come up in the properties window. Then simply change it’s size value from 4 to 5.
2. In the empty space add a menu bar. Then on the Packing tab of the menu bar’s properties set the position to be zero, so that the menu is at the top of the window.
3. Then edit the menu so that only the File, Edit, and Help menu’s remain.
4. Add handlers to each of the files menu items: on_file_new, on_file_open, on_file_save, on_file_save_as

The Code

That’s it for editing the GUI, now we have to go and edit the code. The first step is to connect all of the menu events with our code:

dic = {"on_wndMain_destroy" : self.quit
		, "on_btnBold_clicked" : self.on_btnBold_clicked
		, "on_btnItalic_clicked" : self.on_btnItalic_clicked
		, "on_btnLink_clicked" : self.on_btnLink_clicked
		, "on_btnBlockQuote_clicked" : self.on_btnBlockQuote_clicked
		, "on_btnDel_clicked" : self.on_btnDel_clicked
		, "on_btnIns_clicked" : self.on_btnIns_clicked
		, "on_btnImage_clicked" : self.on_btnImage_clicked
		, "on_btnUnorderedList_clicked" : self.on_btnUnorderedList_clicked
		, "on_btnOrderedList_clicked" : self.on_btnOrderedList_clicked
		, "on_btnListItem_clicked" : self.on_btnListItem_clicked
		, "on_btnCode_clicked" : self.on_btnCode_clicked
		, "on_btnMore_clicked" : self.on_btnMore_clicked
		, "on_btnSettings_clicked" : self.on_btnSettings_clicked
		, "on_btnpost_clicked" : self.on_btnpost_clicked
		, "on_file_new" : self.on_file_new
		, "on_file_open" : self.on_file_open
		, "on_file_save" : self.on_file_save
		, "on_file_save_as": self.on_file_save_as}
self.wTree.signal_autoconnect(dic)

def on_file_new(self, widget):

def on_file_open(self, widget):

def on_file_save(self, widget):

def on_file_save_as(self. widget):

Now when we save and load the post we will need to use the same xml tags, so instead of typing them twice (or in case we want to change them) I decided to save them as a dictionary in the WordPy class:

MAIN_TAG = 0
POST_TAG = 1
TITLE_TAG = 2
TEXT_TAG = 3
SETTINGS_TAG = 4
URL_TAG = 5
USERNAME_TAG = 6
PASSWORD_TAG = 7

class WordPy:
	"""This is the Wordpy application.  It is a simple PyGTK
	application that interacts with the WorPress Python library."""

	_xml_tags = {
			MAIN_TAG : "WordPy"
			, POST_TAG : "Post"
			, TITLE_TAG : "Title"
			, TEXT_TAG : "Text"
			, URL_TAG : "URL"
			, SETTINGS_TAG : "Settings"
			, USERNAME_TAG : "Username"
			, PASSWORD_TAG : "password"
	}

Now when we save and load we can get the username xml tag like so:

self._xml_tags[USERNAME_TAG]

And if someone wants to import WordPy into their own Python project, they could get at the tags (if they didn’t have a WordPy object instantiated) like so:

WordPy._xml_tags[USERNAME_TAG]

We also need to add a new element in the __init__() function:

self.xml_file = None

This will be the full path to the xml file that is represents the current post, it starts off as None, since when we first start WordPy the blank post is not associated with any xml file.

We will also need to do some file browsing for the save, open, and save as events so we’ll borrow the file_browse() function from the Extending our PyGTK application tutorial (to learn more about the function and how it works please read the tutorial):

# Borrowed from the PyWine project
def file_browse(self, dialog_action, file_name=""):
	"""This function is used to browse for a pyWine file.
	It can be either a save or open dialog depending on
	what dialog_action is.
	The path to the file will be returned if the user
	selects one, however a blank string will be returned
	if they cancel or do not select one.
	dialog_action - The open or save mode for the dialog either
	gtk.FILE_CHOOSER_ACTION_OPEN, gtk.FILE_CHOOSER_ACTION_SAVE
	@param file_name - Default name when doing a save
	@returns - File Name, or None on cancel.
	"""

	if (dialog_action==gtk.FILE_CHOOSER_ACTION_OPEN):
		dialog_buttons = (gtk.STOCK_CANCEL
			, gtk.RESPONSE_CANCEL
			, gtk.STOCK_OPEN
			, gtk.RESPONSE_OK)
		dlg_title = "Open Post"
	else:
		dialog_buttons = (gtk.STOCK_CANCEL
			, gtk.RESPONSE_CANCEL
			, gtk.STOCK_SAVE
			, gtk.RESPONSE_OK)
		dlg_title = "Save Post"

	file_dialog = gtk.FileChooserDialog(title=dlg_title
		, action=dialog_action
		, buttons=dialog_buttons)
	"""set the filename if we are saving"""
	if (dialog_action==gtk.FILE_CHOOSER_ACTION_SAVE):
		file_dialog.set_current_name(file_name)
	"""Create and add the pywine filter"""
	filter = gtk.FileFilter()
	filter.set_name("WordPy Post")
	filter.add_pattern("*." + FILE_EXT)
	file_dialog.add_filter(filter)
	if (dialog_action==gtk.FILE_CHOOSER_ACTION_OPEN):
		"""Create and add the 'all files' filter"""
		filter = gtk.FileFilter()
		filter.set_name("All files")
		filter.add_pattern("*")
		file_dialog.add_filter(filter)

	"""Init the return value"""
	result = None
	if file_dialog.run() == gtk.RESPONSE_OK:
		result = file_dialog.get_filename()
		if (dialog_action==gtk.FILE_CHOOSER_ACTION_SAVE):
			result, extension = os.path.splitext(result)
			result = result + "." + FILE_EXT
	file_dialog.destroy()

	return result

Note that this function is somewhat different then the original in that it returns None if the users cancels the operation rather then returning a blank string.

I set FILE_EXT to “wpx”, which stands for WordPy xml, at the beginning of the WordPy.py file near the top:

FILE_EXT = "wpx"

Another helper function that I added is the set_post_text function:

def set_post_text(self, text):
	"""Simple Helper function that sets the text
	in the text View.
	@param text - The text that will be put into
	the text view.
	"""
	#select all of the text
	start, end = self.txtBuffer.get_bounds()
	self.txtBuffer.select_range(end,start)
	#insert over the selection i.e. replace all the text
	self.insert_text(text)
	#put the selection at the end.
	start, end = self.txtBuffer.get_bounds()
	self.txtBuffer.select_range(end,end)

It’s a simple helper function that sets the post text. It does this by selecting all of the text in the gtk.TextView and then calls the insert_text() function (detailed in the previous tutorial) which will overwrite what is selected in the gtk.TextView (in this case everything) with the text that it is passed. After that we simply move the cursor caret to the end of the text.

Saving the post

Now that we have all of the base code in place we can start work on actually saving our file to xml, to do that we will use the xml.dom.minidom module. The reason that I decided to use the xml.dom.minidom object as opposed to the xml.dom object is because the:

xml.dom.minidom is a light-weight implementation of the Document Object Model interface. It is intended to be simpler than the full DOM and also significantly smaller.

This is perfect for us since we for saving and loading we do not need to perform any exceedingly difficult xml tasks.

The first function we are going to implement is the on_file_save() function:

def on_file_save(self, widget):
	"""This function saves the current post as an XML file"""

	# Let the user browse for the save location and name
	if (self.xml_file == None):
		self.xml_file = self.file_browse(gtk.FILE_CHOOSER_ACTION_SAVE)
	#If we have a xml_file
	if (self.xml_file):
		if (self.xml_save_to_file(self.xml_file)):
			#Allright it all worked! Set the Title
			self.set_window_title_from_file(self.xml_file)

This function is pretty simple since it relies on many other functions, this was done so that a lot of the code could be re-used by the on_file_save_as() function. The first thing we do is check to see if self.xml_name has been set, if it hasn’t we pop up a save dialog and let the user select the location where their file will be saved. Then if they chose a filename rather then cancelling we will actually start saving our data to xml.

The two main functions we use to accomplish this are xml_save_to_file() and set_window_title_file(). set_window_title_file() is a very simple function that sets the main windows title based upon a file path:

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

The more complicated function is the xml_save_to_file() function:

def xml_save_to_file(self, xml_file):
	"""Save the current post to xml_file
	@param xml_file - string - path to file that
	we will save the xml to.
	@returns boolean - True success. False failure
	"""
	#Init return value
	success = False

	#Get the available DOM Implementation
	impl = minidom.getDOMImplementation()
	#Create the document, with wordpy as to base node
	xml_document = impl.createDocument(None, self._xml_tags[MAIN_TAG], None)
	#Save the post settings into the xml
	self.xml_save(xml_document)
	#Save the Blog settings into the XML
	self.BlogSettings.xml_save(xml_document)
	#Now actually try to save the file
	try:
		save_file = open(xml_file, 'w')
		#write the xml document to disc
		xml_document.documentElement.writexml(save_file)
		save_file.close()
	except IOError, (errno, strerror):
		self.show_error_dlg(
			"Error saving post(%s): %s" % (errno, strerror))
	else:
		#Allright it all worked! Set the return value
		success = True

	return success

The code is a bit complicated so I will take a little bit of time trying to explain each part in it. The first thing that we do (after initializing the return value) is call minidom.GetDomImplementation() to get a suitable DOM implementation. You can read more about the Document Object Model in the python documentation here. We then use that DOM implementation to create our xml document using self._xml_tags[MAIN_TAG] as the main tag for our xml document. Basically this creates:

<WordPy></WordPy>

Then we call two functions self.xml_save() and self.BlogSettings.xml_save() which are functions that will actually save our data into the xml document. Then we try to open our self.xml_file and write the xml document into that file using the writexml function:

writexml( writer[,indent=""[,addindent=""[,newl=""]]])
Write XML to the writer object. The writer should have a write() method which matches that of the file object interface. The indent parameter is the indentation of the current node. The addindent parameter is the incremental indentation to use for subnodes of the current one. The newl parameter specifies the string to use to terminate newlines.

After that we simply set the windows title based on self.xml_file so that the user knows which file they are currently working with.

The next function to look at is the WordPy.xml_save() function which actually looks more complicated then it really is:

def xml_save(self, xml_document):
	"""Save the current blog post to an xml document.
	@param xml_document - xml.dom.minidom.Document object -
	The xml document that we will save the post to."""

	#First create the "post" xml element
	post_element = xml_document.createElement(self._xml_tags[POST_TAG])  # creates <post></post>
	#Title
	title = self.enTitle.get_text()
	#Text
	start, end = self.txtBuffer.get_bounds()
	text = self.txtBuffer.get_text(start, end)
	# creates <title></title>
	title_element = xml_document.createElement(self._xml_tags[TITLE_TAG])
	#Create <title>title text</title>
	title_element.appendChild(xml_document.createTextNode(title))
	# creates <text></text>
	text_element = xml_document.createElement(self._xml_tags[TEXT_TAG])
	# creates <text>text</text>
	text_element.appendChild(xml_document.createTextNode(text))
	#Now create <post><title>title text</title><text>text</text></post>
	post_element.appendChild(title_element)
	post_element.appendChild(text_element)
	#Now add to the xml docuemnt
	xml_document.documentElement.appendChild(post_element)

Basically it’s quite simple, we call xml_document.createElement() to create an xml element (see this page for more information on functions available to our Document object.) Then if we want we create a text node (and xml node that contains a text string) using xml_document.createTextNode() and add that to our newly created xml element.

So the first thing we do is create the post element, and then we create the title and text elements and add those to the post element. Then we add the post element to the root of our xml document using documentElement which always represents the root element of our xml document. It’s really quite simple, hopefully the comments in the code will help to explain each basic step.

The other xml_save function we have is the WordPressBlogSettings.xml_save() function which is very similar to the other xml_save() function:

def xml_save(self, xml_document):
	"""Save the current blog post to an xml document.
	@param xml_document - xml.dom.minidom.Document object -
	The xml document that we will save the post to."""

	#First create the "settings" xml element
	settings_element = xml_document.createElement(WordPy._xml_tags[SETTINGS_TAG])
	#Creates <url></url>
	URL_element = xml_document.createElement(WordPy._xml_tags[URL_TAG])
	#Create <url>URL</url>
	URL_element.appendChild(xml_document.createTextNode(self.URL))
	#Creates <username></username>
	username_element = xml_document.createElement(WordPy._xml_tags[USERNAME_TAG])
	#Creates <username>Username</username>
	username_element.appendChild(xml_document.createTextNode(self.Username))
	#Creates <password></password>
	password_element = xml_document.createElement(WordPy._xml_tags[PASSWORD_TAG])
	#Creates <password>Password</password>
	password_element.appendChild(xml_document.createTextNode(self.Password))
	"""Now create:
	<post>
		<url>URL</url>
		<username>Username</username>
		<password>Password</password>
	</post>
	"""
	settings_element.appendChild(URL_element)
	settings_element.appendChild(username_element)
	settings_element.appendChild(password_element)
	#Now add to the xml docuemnt
	xml_document.documentElement.appendChild(settings_element)