Introduction

All right, this is just a little tutorial about working with text in pygame. Now, this isn’t the only way to work with text, there are many other methods to do this, in fact much of the time you’ll probably end up using images for interactive text. So this is mainly meant to serve as a informative guide to using the text features in PyGame, and how you might want to implement them.

The TextWidget object discussed in this tutorial can be used to make something that looks like this (but you’d probably want to use better looking colours):

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

So, in order to make this easy to use and very reusable we’re going to create a class called TextWidget in a file called TextWidget.py. The top of the file is full of the standard python initialization:

#! /usr/bin/env python

import pygame

TEXT_WIDGET_CLICK = pygame.locals.USEREVENT + 1

We import pygame and then we set a define TEXT_WIDGET_CLICK , which will be used later on as the event type when the TextWidget is clicked on.

The next thing to do is define the actual class:

class TextWidget(object):

Now the astute among you will recognize that this is a “new-style” python class (i.e. it’s base class is the object class) rather then a classic class. I did this for two reasons:

1. I wanted to be able to control what happens when people set values in the class. So, for example, if you set the size of the font to be something, I wanted the display to automatically adjust to reflect the new size.
2. I haven’t really used new-style classes before so I thought I’d try them out.

Note: If you are unfamiliar with properties or new-style classes you might want to give this a read:

• Unifying types and classes in Python 2.2
• Introduction To New-Style Classes In Python

As a result of number one above I’m going to use properties for those values that I want to perform some “automatic processing” when their values changes.

The properties that I am going to define are as follows:

• text – The string of text that the TextWidget will display.
• colour – The colour that the text will be rendered in.
• size – The size of the font.
• font_filename – The filename of the font to use for the text (probably something returned by pygame.font.get_fonts or pygame.font.match_font.
• highlight – A boolean, whether the font is highlighted or not. (i.e. whether the mouse is over the TextWidget.
• highlight_cursor – A boolean that controls whether or not to show a hand cursor when the TextWidget is in highlight mode. If the TextWidget is not supposed to be interactive you should set this to False.

There are also a few other important members of the class, but since they are not python properties I have listed them separately:

• __hand – A hand cursor, which can optionally by displayed when the cursor hovers over the text.
• dirty – A boolean, that lets the TextWidget know whether or not it needs to draw. If dirty = False it will not draw, if dirty = True it will draw.
• bold_rect – pygame.Rect – A rectangle that is equal to the size of the highlighted text. It is used so that when we move from highlighted to non-highlighted text all of the text is erased. Otherwise if we just drew updated the normal rectangle, all of the highlighted text that was outside of it would not be redrawn.
• rect – pygame.Rect – The Rectangle where the text will be drawn. Use this to position your text, but its height and width will always be controlled by the text and the font.
• highlight_increase – Boolean whether or not the text should increase in size when the cursor is over it. If the text is “non-interactive” then this should be False.
• tracking – Boolean whether or not the TextWidget is tracking a mouse click. Used so that we can tell whether or not a true “click” has occurred. A true click is one where both the mouse-down and mouse-up events occur on the TextWidget.

To hopefully make the functionality of the TextWidget a bit clearer here is some non-highlighted text and then some highlighted text:

The Code

Now we get to the heart of the actual python\PyGame code, where we actually create a working TextWidget object.

So we’ll start off at the top of the file and then work out way downwards in a linear manner.

class TextWidget(object):
    """This is a helper class for handling text in PyGame.  It performs 
    some basic highlighting and tells you when the text has been clicked.
    This is just one of the many ways to handle your text.
    This is a new-style class and I am somewhat new to them so hopefully it 
    all works.
    """
    #Hand Cursor
    __hand_cursor_string = (
    "     XX         ",
    "    X..X        ",
    "    X..X        ",
    "    X..X        ",
    "    X..XXXXX    ",
    "    X..X..X.XX  ",
    " XX X..X..X.X.X ",
    "X..XX.........X ",
    "X...X.........X ",
    " X.....X.X.X..X ",
    "  X....X.X.X..X ",
    "  X....X.X.X.X  ",
    "   X...X.X.X.X  ",
    "    X.......X   ",
    "     X....X.X   ",
    "     XXXXX XX   ")
    __hcurs, __hmask = pygame.cursors.compile(__hand_cursor_string, ".", "X")
    __hand = ((16, 16), (5, 1), __hcurs, __hmask)

The above code is where we create the hand cursor that we will use if the person turns on the highlight_cursor. We first define what the cursor will look like as explained in the PyGame cursor documentation.

The next step is to create all of our properties, now this code may seem a bit complicated, especially since it deals with functions that we have not created yet, but as I explain it, it could become clearer and clearer.

#Text
def __get_text(self):
    return self.__m_text
def __set_text(self, text):
    if (self.__m_text != text):
        self.__m_text = text
        self.update_surface()
text = property(__get_text, __set_text)

The above code creates the TextWidget.text property. The __get_text() function is used to get the text property which is represented by the __m_text variable, and the __set_text() function is the function that is called when you want to set the value of the text property.

What you will notice about the __set_text() function is that it first tests to see if the text that we are setting (text) is any different then the current text (__m_text) if it isn’t any different we don’t do anything.

However if it is different we set __m_text and we call update_surface(). update_surface() is a member function that I will explain in more detail later, but for now all you need to know is that it updates what the widget will display. So since we changed the text we want the widget to update and display the new text.

You can probably see why I wanted to use new-style classes and properties now.

#Colour
def __get_colour(self):
    return self.__m_colour
def __set_colour(self, colour):
    if (self.__m_colour != colour):
        self.__m_colour = colour
        self.update_surface()
colour = property(__get_colour, __set_colour)

Next is the colour property, as you can see it’s basically identical to the text property, so I won’t bother explaining it.

#Size
def __get_size(self):
    return self.__m_size
def __set_size(self, size):
    if (self.__m_size != size):
        self.__m_size = size
        self.create_font()
size = property(__get_size, __set_size)

The next property is the size property, which controls the size of the font. Now this is slightly different in that it calls the create_font() function rather then the update_surface() function that the text and the colour property did.

The reason for this is that the size property is used in the creation of the actual font object that is used to update the surface which is eventually drawn to the screen. As with the update_surface() function I will explain the create_font() function later. Properties that call create_font() do not have to call update_surface() because create_font() calls update_surface().

#Font Filename
def __get_font_filename(self):
    return self.__m_font_filename
def __set_font_filename(self, font_filename):
    if (self.__m_font_filename != font_filename):
        self.__m_font_filename = font_filename
        self.create_font()
font_filename = property(__get_font_filename, __set_font_filename)

Then we have the font_filename property that represents the full path to the font file. So if that changes we need to recreate the font in order to display the text using the correct font.

#Highlight
def __get_highlight(self):
    return self.__m_highlight
def __set_highlight(self, highlight):
    if (not(self.__m_highlight == highlight)):
        #Save the bold_rect
        if (self.__m_highlight):
            self.bold_rect = self.rect
        self.__m_highlight = highlight
        #update the cursor
        self.update_cursor()
        if (highlight):
            self.size += self.highlight_increase
        else:
            self.size -= self.highlight_increase
        if (self.highlight_increase == 0):
            self.create_font()
highlight = property(__get_highlight, __set_highlight)

Next we have the highlight property, the highlight property is a boolean property that controls whether or not the TextWidget should display “highlighted” or not. When a TextWidget is highlighted the font will be displayed in bold, have its size increased by a specific amount, and (if enabled) the hand cursor will be displayed.

So now since the __get_highlight() function is the same as all of the others, I’ll just explain the __set_highlight() function.

First we check to see that the new value is different then the old value. We do this so that we don’t waste time with useless font creations or extra draws.

Then we check to see if the current state of the TextWidget is highlighted, because if it is, we know that it is about to go back to normal (because of the first if.) If that is the case we save the current rect as bold_rect so that the next time we draw we will want bold_rect to be drawn so that all of the previous highlighted text is overwritten.

Then we set the internal highlight value and call the update_cursor() function which will decide whether or not the cursor should be a hand or the default arrow.

Then we set the size of the font depending on whether or not the highlight state has been turned on. If it is we increase the size, and if it is not we decrease the size back down to normal.

Since increasing or decreasing the size will call create_font() we only need to call create_font() if self.highlight_increase is equal to zero, since in that case the value of the size property will not change and the font will not be created.

#Show Highlight Cursor
def __get_highlight_cursor(self):
    return self.__m_highlight_cursor
def __set_highlight_cursor(self, highlight_cursor):
    if (self.__m_highlight_cursor != highlight_cursor):
        self.__m_highlight_cursor = highlight_cursor
        self.update_cursor()
highlight_cursor = property(__get_highlight_cursor, __set_highlight_cursor)

Lastly we have the highlight_cursor property, which is a boolean property that controls whether or not the highlight (hand) cursor should be displayed. If you have made it this far and have understood the rest of the properties then understanding this property shouldn’t be too difficult. Basically it simply checks to see if we should update the property, and if so it updates it and then calls update_cursor() just in case we need the cursor to update right now.

def __init__(self, text="", colour=(0,0,0), size=32
             , highlight_increase = 20, font_filename=None
             , show_highlight_cursor = True):
    """Initialize the TextWidget
    @param text = "" - string - The text for the text widget
    @param colour = (0,0,0) - The colour of the text
    @param size = 32 - number - The size of the text
    @param highlight_increate - number - How large do we want the
    text to grow when it is highlighted?
    @param font_filename = None - string the patht to the font file
    to use, None to use the default pygame font.
    @param show_highlight_cursor = True - boolean - Whether or not to change
    the cursor when the text is highlighted.  The cursor will turn into
    a hand if this is true.
    """
    
    #inits
    self.dirty = False
    self.bold_rect = None
    self.highlight_increase = highlight_increase
    self.tracking = False
    self.rect = None
    
    #property inits
    self.__m_text = None
    self.__m_colour = None
    self.__m_size = None
    self.__m_font_filename = None
    self.__m_highlight = False
    self.__m_font = None
    self.__m_highlight_cursor = False
    self.__m_rect = None
    
    self.text = text
    self.colour = colour
    self.size = size
    self.font_filename = font_filename
    self.highlight = False
    self.highlight_cursor = show_highlight_cursor
    
    self.create_font()

Now we actually start using the class the first thing we do is code the __init__() function in which we initialize all of our data members and properties, and then create the font at the end. This may result in the font being create twice sometimes but it will only happen once when the Widget is created, and it makes sure that the font is always created.

def update_cursor(self):
    if (self.highlight_cursor):
        if (self.highlight):
            pygame.mouse.set_cursor(*self.__hand)
        else:
            pygame.mouse.set_cursor(*pygame.cursors.arrow)

Here is the update_cursor() function, it’s pretty straight forward. First we check whether or not we are supposed to change the cursor at all. If we are then we check to see if we are highlighted or not. If we are highlighted then we use the hand cursor that we created above, and if we are not highlighted we use the built-in pygame arrow cursor.

Drawing and Fonts

Now we finally get to drawing and the font creation that we talked about earlier. The first thing to do is to create our font:

def create_font(self):
    """Create the internal font, using the current settings
    """
    if (self.size):
        self.__m_font = pygame.font.Font(self.font_filename
                                 , self.size)
        self.update_surface()

As you can see this function really is pretty simple, all we need to make sure that we have is a size for the font. Then we create the font using pygame.font.Font() We don’t care if self.font_filename is None since if it is None, then the default font will be loaded.

After the font has been created we call update_surface():

def update_surface(self):
    """Update the current surface, basically render the
    text using the current settings.
    """
    if (self.__m_font):
        self.__m_font.set_bold(self.highlight)
        self.image = self.__m_font.render(self.text
                                        , True
                                        , self.colour)
        self.dirty = True
        if (self.rect):
            # Used the current rects center point
            self.rect = self.image.get_rect(center=self.rect.center)
        else:
            self.rect = self.image.get_rect()

In update_surfacte() we first make sure that our font (__m_font) exists, since if it does not then there is no point in creating any surface. Then we set the font’s bold setting Font.set_bold() function and controlled by the highlight property.

Then we render the font onto a pygame.surface using the Font.render() function and our current text and colour. We also make sure that the font is anti-aliased by passing True as the second parameter.

Then we set self.Dirty to True to make sure that the next time through the draw loop the new surface gets displayed.

The last thing we do in the function is move our text into the correct location. If self.rect has been specified then we move the image into that position and set our rect, otherwise we initialize self.rect to be be surfaces rectangle.

self.rect must eventually be move into some position because Surface.get_rect() always returns a rectangle that starts at 0,0.

def draw(self, screen):
    """Draw yourself text widget
    @param screen - pygame.Surface - The surface that we will draw to
    @returns - pygame.rect - If drawing has occurred this is the 
    rect that we drew to.  None if no drawing has occurred."""
    
    rect_return = None
    if ((self.image)  and  (self.rect) and (self.dirty)):
        if (self.bold_rect):
            """We may need to overwrite the bold text size
            This gets rid of leftover text when moving from 
            bold text to non-bold text.
            """
            rect_return = pygame.Rect(self.bold_rect)
            """Set to None, since we only need to do this
            once."""
            self.bold_rect = None
        else:
            rect_return = self.rect
        #Draw the text
        screen.blit(self.image, self.rect)
        #Dirty no more
        self.dirty = False

    return rect_return

Finally we get to the draw code, and thankfully it’s pretty simple. The draw() function take a pygame.Surface as the only parameter, this is the surface that we will be drawing to, probably the main surface in your game or application. The draw function will also return a pygame.Rect object (or None) which represents the area of the surface that needs to be updated (or not).

The first thing we do in the function is make sure that we actually have something to draw. We check our rectangle (self.tect) and our surface (self.image) to make sure that everything has been initialized, and then we check self.dirty to see if we should draw anything.

Then we check to see if self.bold_rect is valid, if it is we return it as the rectangle to update and invalidate the bold_rect, since it only needed once, when moving from highlighted to non-highlighted). If self.bold_rect is not valid then we will return self.rect as the rectangle to update.

Then we blit our text to the screen (which is stored in self.image as a pygame.Surface object) and set self.dirty to False so that we do not needlessly draw in the future.

Events

If you remember way back at the beginning of this tutorial we create a define for a future event that would be fired when the TextWidget was clicked on:

TEXT_WIDGET_CLICK = pygame.locals.USEREVENT + 1

Now is where we use it and let the main class know when a TextWidget has been clicked.

def on_mouse_button_down(self, event):
    """Called by the main application when the
    MOUSEBUTTONDOWN event fires.
    @param event - Pygame Event object
    MOUSEBUTTONDOWN  pos, button
    """
    #Check for collision
    self.tracking = False
    if (self.rect.collidepoint(event.pos)):
        self.tracking = True

First we have the on_mouse_button_down() function, this should be called by your main application during the event loop. If you come across a MOUSEBUTTONDOWN event, then you should pass it to all of your TextWidget objects, or at least the TextWidgets that you want to be interactive.

All this function does is check to see if the mouse button down event occurred within the TextWidgets rect, if it did, self.Tracking is set to True to let the TextWidget know that it is “tracking” or listening for the MOUSEBUTTONUP event to complete the click.

def on_mouse_button_up(self, event):
    """Called by the main application when the
    MOUSEBUTTONDOWN event fires.
    @param event - Pygame Event object
    MOUSEBUTTONDOWN  pos, button
    """
    #Check for collision
    if ((self.tracking) and (self.rect.collidepoint(event.pos))):
        self.on_mouse_click(event)
    #Not Tracking anymore
    self.tracking = False

Next we have the on_mouse_button_up function which called by your main application for all of your interactive TextWidget objects when the MOUSEBUTTONDOWN event is found.

This function is very simple, it first checks to see if we are currently tracking, if we are then we check to see if the event has occurred within the TextWidget’s rect. If it has we call self.one_mouse_click() and pass it the event.

Then we set self.tracking to False, since whatever happened we are no longer tracking. Now if you don’t fully understand what the self.tracking boolean does, it simply makes sure that the TextWidget behaves like a standard button, which means that it only registers MOUSEBUTTONUP events as a “click” if the MOUSEBUTTONDOWN also occurred within the buttons rectangle.

def on_mouse_click(self, event):
    """Called by the main application when the
    MOUSEBUTTONDOWN event fires, and the text widget
    has been clicked on.  You can either let
    this post the event (default) or you can override this
    function call in your app.
    ie. myTextWidget.on_mouse_click = my_click_handler
    @param event - Pygame Event object
    MOUSEBUTTONDOWN  pos, button
    """
    #Create the TEXT_WIDGET_CLICK event
    event_attrib = {}
    event_attrib["button"] = event.button
    event_attrib["pos"] = event.pos
    event_attrib["text_widget"] = self
    e = pygame.event.Event(TEXT_WIDGET_CLICK, event_attrib)
    pygame.event.post(e)

Finally in our event handling we have the on_mouse_click() function. By default this function will post a TEXT_WIDGET_CLICK event to the PyGame event queue which you can handle in whichever manner you like.

The event has the following attributes:

• button – The button of the mouse that was used for the click. This is the same as the MOUSEBUTTONUP event’s button attribute.
• pos (x,y) – The position of the mouse cursor when the click occurred. The is the same as the MOUSEBUTTONUP event’s pos attribute.
• text_widget – The TextWidget object that was clicked on, so you know how to handle the event.

That is the default way that the on_mouse_click() function functions, in general it is probably easier to override the on_mouse_click() function in all of the TextWidget instances that you want to be interactive.

As an example, in your main application you might use the following for an Exit TextWidget:

self.exit_text.on_mouse_click = self.on_exit_clicked

Using the TextWidget

In order to make it easy to see how to use the TextWidget object (if it is not already) I whipped up a quick sample application, the short flash capture is to show you what it looks like without having to run it:

import os, sys
import pygame
from pygame.locals import *

import TextWidget

class PyGameText:
    """An example class used to illustrate possible ways to work
    with the TextWidget text in a pygame game.
    """
    
    def __init__(self, width=640, height=480):
        """Initialize
        @param width=640 - The width of the pygame window
        @param height=480 - The height of the pygame window.
        """
        
        pygame.init()
        #create the screen
        self.screen = pygame.display.set_mode((width, height), 0) 
        self.background = pygame.Surface(self.screen.get_size(), SWSURFACE)
        self.background = self.background.convert()
        image, rect = self.load_image("background.png")
        if (image):
            self.background.blit(image, (0,0))
        else:
            #Just fill with a solid colour
            self.background.fill((124,124,124))
        self.screen.blit(self.background, (0,0))
        
    def main_loop(self):
        """The main Python loop"""
        
        pygame.display.update()
        self.timer = pygame.time.Clock()
        
        # Text Widget list
        self.text_widgets = []
        #Create our Text WIdgets
        self.new_game_text = TextWidget.TextWidget("New Game", (200,200,200))
        #make this the biggest text
        self.new_game_text.size = 96
        self.new_game_text.rect.center = self.screen.get_rect().center
        self.new_game_text.rect.top = 0;
        self.text_widgets.append(self.new_game_text)
        
        self.high_score_text = TextWidget.TextWidget("High Scores", (255,0,0), 64)
        self.high_score_text.rect.center = self.screen.get_rect().center
        self.high_score_text.rect.top = self.new_game_text.rect.bottom + 30
        self.text_widgets.append(self.high_score_text)
        
        self.website_text = TextWidget.TextWidget("Website", (255,0,255), 64)
        self.website_text.rect.center = self.screen.get_rect().center
        self.website_text.rect.top = self.high_score_text.rect.bottom + 30
        self.text_widgets.append(self.website_text)
        
        # Different font for the last one, and let's make it increase
        # more
        self.exit_text = TextWidget.TextWidget("Exit", (0, 255,255)
                                , 64, 40
                                , pygame.font.match_font("sans", False, True))
        self.exit_text.rect.center = self.screen.get_rect().center
        self.exit_text.rect.top = self.website_text.rect.bottom + 30
        self.exit_text.on_mouse_click = self.on_exit_clicked
        self.text_widgets.append(self.exit_text)
           
        while 1: 
            #Tick of the timer
            self.timer.tick()
            
            self.event_loop()
            
            self.draw()
                
    def event_loop(self):
        """Perform the event loop."""
        
        for event in pygame.event.get():
            if (event.type == pygame.QUIT):
                pygame.quit()
                sys.exit()
            elif (event.type == ACTIVEEVENT):
                if (event.gain == 1):
                    for text in self.text_widgets:
                        text.dirty = True
                    self.draw()
                elif (event.state ==2): 
                    #We are hidden so wait for the next event
                    pygame.event.post(pygame.event.wait())             
            elif (event.type == pygame.MOUSEMOTION):
                for text in self.text_widgets:
                    text.highlight = text.rect.collidepoint(event.pos)
            elif (event.type == pygame.MOUSEBUTTONDOWN):
                for text in self.text_widgets:
                    text.on_mouse_button_down(event)
            elif (event.type == pygame.MOUSEBUTTONUP):
                for text in self.text_widgets:
                    text.on_mouse_button_up(event)
            elif (event.type == TextWidget.TEXT_WIDGET_CLICK):
                print event.text_widget             
    
    def draw(self):
        """Draw everything"""        
        rects = []
        rects.append(self.timer_update())
        for text in self.text_widgets:
            rect = text.draw(self.screen)
            if (rect):
                rects.append(rect)
        pygame.display.update(rects)        
        
    def timer_update(self):
        """Update the Timer
        returns - pygame.rect - The rect that the timer
        needs to be redrawn, or None on error"""
        
        rect_return = None
        
        if (pygame.font):     
            timer_string = "%.2f" % self.timer.get_fps()
            #basic font
            font = pygame.font.Font(None, 36)
            message = font.render(timer_string, 1, (147, 1, 16))
            if (message):
                rect_return = message.get_rect(left=0)
                rect_return.width += 25
                self.screen.blit(self.background, rect_return)
                self.screen.blit(message, rect_return) 
        
        return rect_return
    
    def load_image(self, name, colorkey=None):
        full_path = os.path.realpath(os.path.dirname(sys.argv[0]))
        full_path = os.path.join(full_path, name)
        try:
            image = pygame.image.load(full_path)
        except pygame.error, message:
            print 'Cannot load image:', full_path
            return None, None
        image = image.convert()
        if colorkey is not None:
            if colorkey is -1:
                colorkey = image.get_at((0,0))
            image.set_colorkey(colorkey, RLEACCEL)
        return image, image.get_rect()
    
    def on_exit_clicked(self, event):
        pygame.quit()
        sys.exit()

if __name__ == "__main__":
    text = PyGameText()
    text.main_loop()

Now most of the code isn’t that exciting and is a pretty basic example of a short PyGame application so I won’t explain every line of this code. I will highlight three portions:

Text Widget Creation

Here is how I created the four TextWidgets in the example application, each is slightly different so you might want to look at each and try to understand what it is doing:

# Text Widget list
self.text_widgets = []
#Create our Text WIdgets
self.new_game_text = TextWidget.TextWidget("New Game", (200,200,200))
#make this the biggest text
self.new_game_text.size = 96
self.new_game_text.rect.center = self.screen.get_rect().center
self.new_game_text.rect.top = 0;
self.text_widgets.append(self.new_game_text)

self.high_score_text = TextWidget.TextWidget("High Scores", (255,0,0), 64)
self.high_score_text.rect.center = self.screen.get_rect().center
self.high_score_text.rect.top = self.new_game_text.rect.bottom + 30;
self.text_widgets.append(self.high_score_text)

self.website_text = TextWidget.TextWidget("Website", (255,0,255), 64)
self.website_text.rect.center = self.screen.get_rect().center
self.website_text.rect.top = self.high_score_text.rect.bottom + 30;
self.text_widgets.append(self.website_text)

# Different font for the last one, and let's make it increase
# more
self.exit_text = TextWidget.TextWidget("Exit", (0, 255,255)
                        , 64, 40
                        , pygame.font.match_font("sans", False, True))
self.exit_text.rect.center = self.screen.get_rect().center
self.exit_text.rect.top = self.website_text.rect.bottom + 30;
# Override the on_mouse_click function
self.exit_text.on_mouse_click = self.on_exit_clicked
self.text_widgets.append(self.exit_text)

In general this code is pretty simple, it mostly involves creating our TextWidget objects, settings some of their properties and then adding them to a list. It really should be pretty self explanatory how this code works, one thing that I will point out is how the in the exit_text TextWidget the pygame.font.match_font() function is used to get the path to the font, and the on_mouse_click() function is overridden.

The Event Loop

def event_loop(self):
    """Perform the event loop."""

for event in pygame.event.get():
    if (event.type == pygame.QUIT):
        pygame.quit()
        sys.exit()
    elif (event.type == ACTIVEEVENT):
        if (event.gain == 1):
            for text in self.text_widgets:
                text.dirty = True
            self.draw()
        elif (event.state ==2): 
            #We are hidden so wait for the next event
            pygame.event.post(pygame.event.wait())             
    elif (event.type == pygame.MOUSEMOTION):
        for text in self.text_widgets:
            text.highlight = text.rect.collidepoint(event.pos)
    elif (event.type == pygame.MOUSEBUTTONDOWN):
        for text in self.text_widgets:
            text.on_mouse_button_down(event)
    elif (event.type == pygame.MOUSEBUTTONUP):
        for text in self.text_widgets:
            text.on_mouse_button_up(event)
    elif (event.type == TextWidget.TEXT_WIDGET_CLICK):
        print event.text_widget

The first thing you should notice is that we respond to the ACTIVEEVENT, we do this so that when the PyGame window gets focus back (after loosing it) we redraw all of the text widgets. We force the TextWidgets to redraw by setting the dirty member to True.

Next we set the TextWidget.highlight property by checking for a collision with each TextWidget rect when we get the MOUSEMOTION event.

If you want your TextWidgets to be responsive to a click whenever you get a MOUSEBUTTONDOWN or MOUSEBUTTONUP event you can simply pass it forward to the on_mouse_button_down() and on_mouse_button_up() functions in each widget, the TextWidget will take care of the rest of the processing.

The example also shows how to handle the TEXT_WIDGIT_CLICK event:

elif (event.type == TextWidget.TEXT_WIDGET_CLICK):
        print event.text_widget

In the example I simply print out the TextWidget, but you could do whatever you wanted to.

The Draw Loop

def draw(self):
    """Draw everything"""        
    rects = []
    rects.append(self.timer_update())
    for text in self.text_widgets:
        rect = text.draw(self.screen)
        if (rect):
            rects.append(rect)
    pygame.display.update(rects)

The draw loop is actually pretty simple. I use a list to keep track of rectangles that I want to update at the end of the draw using pygame.display.update() function.

In order to draw the TextWidget’s I simply loop through the list of them and call their draw() function. If the draw() function returns a rectangle, then I know that the TextWdiget has drawn so I add it to the list of rectangles that need to be updated.

If None is returned then I know that the TextWidget has not drawn and that it does not need to be drawn.

Conclusion

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

So that’s it for this tutorial, as I said early on I’m not saying that this is the best or only way to work with text, I’m simply presenting this as a possible way to work with text, or as an example that might help get you started with your own text processing.

If you have any suggestions, problems, or notice anything that is incorrect, as always, add a comment!

Feel free to use this in whatever manner you want (it’s licensed under the LGPL), but if you do end up using it, I would appreciate it if you sent me an email and let me know.

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)

After all this is set and done we end up with an xml file that looks similar to this although not spaced as nicely:

<wordpy>
	<post>
		<title>My Blog Post</title>
		<text>Here is my text</text>
	</post>
	<settings>
		<url>	http://www.myblog.com/wordpress/xmlrpc.php</url>
		<username>user</username>
		<password>password</password>
	</settings>
</wordpy>

Now that you see how we can save a file in response to the File | Save menu command you can probably imagine how we will respond to the File | Save As command:

def on_file_save_as(self, widget):
	"""Let the user save the current file to a new location."""

	xml_file = "Untitled"
	if (self.xml_file != None):
		xml_file = os.path.basename(self.xml_file)

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

You’ll notice that it’s very similar to the on_file_save() function except that we always browse for a file and we pass the name of the current file (if it exists) to the file_browse() function so that the use has a starting point for their save as action.

So that’s it for saving the next step is opening a saved file.

Opening an save file

Opening one of our xml files is very similar to saving them except instead of creating the xml document and each node, we need to loop through an existing document and load each node into our specific variables. The first thing that we need to do is respond to the File | Open menu command:

def on_file_open(self, widget):

	xml_file = self.file_browse(gtk.FILE_CHOOSER_ACTION_OPEN)
	#If we have a xml_file
	if (xml_file):
		if (self.xml_load_from_file(xml_file)):
			"""Allright it all worked! save the current file and
			set the title."""
			self.xml_file = xml_file
			self.set_window_title_from_file(self.xml_file)

Pretty standard stuff, we let the user browse for an xml file, and if they don’t cancel the operation we then load the xml file. If that is successful we save the path to the xml file and then set the windows title. Not much happening here as most of the work is done in xml_load_from_file():

def xml_load_from_file(self, xml_file):
	"""Load a post from an xml file
	@param xml_file - string - path to file that
	we will load.
	@returns boolean - True success. False failure
	"""
	#Init return value
	success = False

	#Load the xml_file to a document
	try:
		xml_document = minidom.parse(xml_file)
		if (xml_document):
			success = ((self.xml_load(xml_document))
					and (self.BlogSettings.xml_load(xml_document)))
	except IOError, (errno, strerror):
		self.show_error_dlg(
			"Error loading post file(%s): %s" % (errno, strerror))
	except:
		self.show_error_dlg("Error loading post file.")
	return success

In this function we create our xml.minidom.Document object by telling the minidom mdule to parse the xml file that was passed to the function. If that does not succeed we catch the appropriate exceptions and show our error dialog top the user. If the parsing the file does succeed we load the post and the blog settings from the XML document. WordPy.xml_load() loads the post from the xml document:

def xml_load(self, xml_document):
	"""Load the current blog post from an xml document.
	@param xml_document - xml.dom.minidom.Document object -
	The xml document that we will load the post from.
	@returns boolean True - success.  False - Failure."""

	title_loaded = False
	text_loaded = False

	#Loop through all child nodes of the root.
	for node in xml_document.documentElement.childNodes:
		#We are looking for the post Node
		if (node.nodeName == self._xml_tags[POST_TAG]):
			# Now loop through the post nodes children
			for item_node in node.childNodes:
				if (item_node.nodeName == self._xml_tags[TITLE_TAG]):
					"""Set the title, the firstChild in this case is
					the actual title text that we saved."""

					#Make sure it's not a blank string
					if (item_node.firstChild):
						self.enTitle.set_text(item_node.firstChild.nodeValue)
					else:
						self.enTitle.set_text("")
					title_loaded = True
				elif (item_node.nodeName == self._xml_tags[TEXT_TAG]):
					"""Set the text, the firstChild in this case is
					the actual text that we saved."""
					#Make sure it's not a blank string
					if (item_node.firstChild):
						self.set_post_text(item_node.firstChild.nodeValue)
					else:
						self.set_post_text("")
					text_loaded = True
			#Break out of the topmost for loop
			break

	return (title_loaded and text_loaded)

Basically what we do when loading our values is loop through the all of the child nodes of the root node looking for nodes that match whatever criteria we are looking for. So in the xml example file:

<wordpy>
	<post>
		<title>My Blog Post</title>
		<text>Here is my text</text>
	</post>
	<settings>
		<url>http://www.myblog.com/wordpress/xmlrpc.php</url>
		<username>user</username>
		<password>password</password>
	</settings>
</wordpy>

The root node or the documentElement item, is the <wordpy> element. So if we were to loop through its child nodes the first node that we would encounter would be the <post> node and then next node would be the <settings> node. Then if we looped through he <post> elements children we would encounter the <title> and the <text> node. The sole child node of either of those two nodes happens to be their actual text.

After explaining that it should be pretty obvious what is happening in the WordPy.xml_load() function. Basically we loop through all the children of the root node looking for the <post> node. Once we find it we then loop through all of the <post> node’s children looking for the <title> and the <text> node. When we encounter either the <title> node or the <text> node we get the the nodeValue of the firstChild, if it exists. The firstChild of either of those two nodes happens to be the actual text node that we want to load. The nodeValue of the text nodes is their actual text. If firstChild did not exist it means that a blank string was saved into the text file.

For me the xml metaphoer built up by the xml.dom slightly of falls apart when then actual text is considered another node, but the implementation is simple and works well enough so I shouldn’t complain. (Plus there is probably a very good reason for this)

We also set boolean values to True to make sure that we know whether or not all of the proper elements were loaded. This is an optional step as you might not care if everything was loaded properly..

The BlogSettings.xml_load() function does the exact same thing except that it looks for different nodes, as a result I will show it but I won’t bother explaining it.

def xml_load(self, xml_document):
	"""Load the current blog post from an xml document.
	@param xml_document - xml.dom.minidom.Document object -
	The xml document that we will load the post from.
	@returns boolean True - success.  False - Failure."""

	URL_loaded = False
	username_loaded = False
	password_loaded = False

	#Loop through all child nodes of the root.
	for node in xml_document.documentElement.childNodes:
		#We are looking for the post Node
		if (node.nodeName == WordPy._xml_tags[SETTINGS_TAG]):
			# Now loop through the post nodes children
			for item_node in node.childNodes:
				if (item_node.nodeName == WordPy._xml_tags[URL_TAG]):
					"""Set the URL"""
					#Make sure it's not a blank string
					if (item_node.firstChild):
						self.URL = item_node.firstChild.nodeValue
					else:
						self.URL = ""
					URL_loaded = True
				elif (item_node.nodeName == WordPy._xml_tags[USERNAME_TAG]):
					"""Set the username"""
					#Make sure it's not a blank string
					if (item_node.firstChild):
						self.Username = item_node.firstChild.nodeValue
					else:
						self.Username = ""
					username_loaded = True
				elif (item_node.nodeName == WordPy._xml_tags[PASSWORD_TAG]):
					"""Set the pasword"""
					#Make sure it's not a blank string
					if (item_node.firstChild):
						self.Password = item_node.firstChild.nodeValue
					else:
						self.Password = ""
					password_loaded = True
		#Break out of the topmost for loop
		break

	return (URL_loaded and username_loaded and password_loaded)

Starting a new file

All that’s left now is to handle the File | New menu command:

def on_file_new(self, widget):
	self.enTitle.set_text("")
	self.set_post_text("")
	self.xml_file = None
	self.set_window_title_from_file(self.xml_file)

It doesn’t really do much except blank out the title and text, make it so that there is no xml file, and sets the window title to “Wordpy – Untitled” (which is what set_window_title will do when passed None as the xml file.)

Since this is a good way to initialize WordPy I call it in the __init__ function:

#initialize to new
self.on_file_new(None)

The End

You can download the complete code for this tutorial here.

Well that’s it for this lesson on saving and loading data from an xml file, there are still many more things that need to be done to WordPy, like figuring out what the best way to handle the blog settings are since I’ve never been happy with the way that they were handled in the previous tutorial. For example should they be separate from the post’s when you save them? Should there be a list of blog settings? Should you have to log into your blog first? I’m not sure yet but those will be left for another post since this one was simply designed to show one method for saving and loading data from xml files using python.

As always if you have any questions or notice any problems please leave a comment!

Up until now we’ve focused on python applications that only run in the command line. For a lot of tasks this is great, but in order to be really impressive we’re going to want to create a GUI for some of our python applications.

There are a lot of python GUI toolkits out there, but for our first application we are going to use Tkinter, which is considered somewhat of a standard right now and is installed when pyhon is installed. Another nice thing about the Tkinter GUI is that it is cross platform and offers a native look and feel on *nix, Windows, and OS X.

Tkinter Example One

So lets start off with a simply “Hello World” GUI app:

#! /usr/bin/env python
from Tkinter import *

class GUIFramework(Frame):
    """This is the GUI"""
    
    def __init__(self,master=None):
        """Initialize"""
        
        """Initialize the base class"""
        Frame.__init__(self,master)
        
        """Display the main window"""
        self.grid()
        
        """Create the Text"""
        self.HelloLabel = Label(master, text="Hello World!")
        self.HelloLabel.grid()
                
if __name__ == "__main__":
    guiFrame = GUIFramework()
    guiFrame.mainloop()

Running this on OS X results in the following:

And running it in Windows Xp gives you:

As you can see the code used to create the GUI is pretty simple and easy to understand, but it is actually more complicated then need be because it uses classes. But since I’ll be using classes whenever building a GUI I thought that this was the best starting point. We start off by importing the Tkinter library into our program using this following:

from Tkinter import *

After that we create a class called GUIFramework, which is the class that will be used to great the GUI elements in Tkinter and uses the Tkinter frame class as its base. For now all the work that we do is done in the __init__ function.

There we first initialize the base class (which will initialize Tkinter) and then tell ourselves to be visible:

"""Initialise the base class"""
Frame.__init__(self,master)

"""Display the main window"""
self.grid()

To display ourselves we use the grid geometry manager, the grid geometry manager is a straight forward way to display widgets and position them. Since we have no other widgets in this example the defaults are fine, take a look at example two for for information on widget placement using the grid function.

Next is the process of creating the HelloWorld label widget, which is a member of the GUIFramework class, and setting it to be visible. It’s a good idea to make your widgets members of the class in case you need to access them later, but if you’re sure that you’ll never have to access them later, you can just create them locally.

self.HelloLabel = Label(master, text="Hello World!")
self.HelloLabel.grid()

After that all the other processing is done in the “main” section of our code where we initialize our class and tell it to enter the “mainloop”. The “mainloop” is basically the application responding to events:

if __name__ == "__main__":
    guiFrame = GUIFramework()
    guiFrame.mainloop()

Tkinter Example Two

Next I’ll show you a more complicated example, I won’t go into specifics with this one since it’s still pretty simple. But if you have any questions about the following code feel free to ask via a comment.

#! /usr/bin/env python
from Tkinter import *
import tkMessageBox

class GUIFramework(Frame):
    """This is the GUI"""
    
    def __init__(self,master=None):
        """Initialize yourself"""
        
        """Initialise the base class"""
        Frame.__init__(self,master)
        
        """Set the Window Title"""
        self.master.title("Type Some Text")
        
        """Display the main window"
        with a little bit of padding"""
        self.grid(padx=10,pady=10)
        self.CreateWidgets()
       
    def CreateWidgets(self):
        """Create all the widgets that we need"""
                
        """Create the Text"""
        self.lbText = Label(self, text="Enter Text:")
        self.lbText.grid(row=0, column=0)
        
        """Create the Entry, set it to be a bit wider"""
        self.enText = Entry(self)
        self.enText.grid(row=0, column=1, columnspan=3)
        
        """Create the Button, set the text and the 
        command that will be called when the button is clicked"""
        self.btnDisplay = Button(self, text="Display!", command=self.Display)
        self.btnDisplay.grid(row=0, column=4)
        
    def Display(self):
        """Called when btnDisplay is clicked, displays the contents of self.enText"""
        tkMessageBox.showinfo("Text", "You typed: %s" % self.enText.get())    
                
if __name__ == "__main__":
    guiFrame = GUIFramework()
    guiFrame.mainloop()

This creates the following window:

That shows this dialog when the button is pressed:

Links that helped me get through this post:

• http://www.pythonware.com/library/tkinter/introduction/
• http://infohost.nmt.edu/tcc/help/pubs/tkinter/

If you like this post remember to digg it.

If you are familiar with Object Oriented programming you probably already know what classes are. If you are unfamiliar with the idea of classes in programming I suggest you give the class topic a read over at wikipedia, it should familiarize you with the idea of a class.

Once you know what a class is you should read the tutorial over a python.org’s section on classes in Python. I’ll hi-light some of the main points here, but for an in-depth understanding of the way that classes work in Python, it’s a must read.

First off we’ll take a look at the syntax of a class:

class classname:

The term class starts the definition of a class and is then followed by the name of the class. If the class is derived from another class the syntax is as following:

class classname(baseclass1, baseclass1, ..., baseclassN):

Classes can have data members and function members:

class TestClass:
    i = 10;
    def PrintI(self):
        print self.i

One of the things you’ll notice about the function definition PrintI within the above class is the strange use of the self variable. What self is, is actually a reference to the class itself, which is why you see that in order to reference the variable i in the PrintI function, self.i is used rather then simply i. If i was simply used then i would become a local variable in the function.

You can use any term as the first parameters in functions within classes, it does not have to be self, however self has become somewhat of a standard so it’s recommended that use it.

So now you can reference the above class in the following way:

"""Create an Instance of the class"""
tc = TestClass();
"""Print out the value of the i variable"""
print tc.i
"""Call the PrintI function to print out the 
value of the i variable"""
tc.PrintI()

The above code would result in (as you might have guessed) the value 10 being written out twice. There are many situations where you will want to construct your class with some default settings, or set some values. This is done using the __init__ function, which is automatically called ever time you construct, or create an instance of, a class. Sin instead of setting i, the way that we did above, we should probably do something like:

class TestClass:
    def __init__(self,value):
        self.i = value
    def PrintI(self):
        print self.i

Where value is an extra parameter was pass to the construction of TestClass:

"""Create an Instance of the class"""
tc = TestClass(23);

Classes also support docstrings in the same way that functions do. The docstring can be references in code using the __doc__ attribute.

That’s about it for basic work with classes, for more information I really recommend reading the section on classes in the Python tutorial or any othe the lings below: