Example Aux Windows

Introduction

The Aux_Window (AW) interface allows users with some familiarity with python and gtk to produce fpdb extensions. AWs have full access to fpdb data and can refresh data in a thread that does not block the gui. Therefore, AWs can run long-running database queries or calculations without freezing the HUD. The AW interface is outlined in another wiki page—it is assumed that the reader is familiar with the concepts in that wiki page and has, at some, familiarity with python and gtk. These examples are also in the Hello.py file in the fpdb distribution (version 0.11 and later). The code in Hello.py is heavily commented, and may touch on issues not discussed here.

Hello, A Trivial AW

The simplest AW that I could think of displays a window on your screen that looks like this:

The code simply defines a class named "Hello" (line 1) and supplies a create() method (line 3) that creates a window (line 4), creates a label and adds it to the window (line 5) and shows the window (line 6). It looks like this:

class Hello(Aux_Window):
    """A 'Hello World' Aux_Window demo."""
    def create(self):
        self.container = gtk.Window()
        self.container.add(gtk.Label("Hello World"))
        self.container.show_all()

Since it is never updated it does not require update_data() or update_gui() methods. This AW also just uses the default init() method supplied by fpdb in the Aux_Window class.

Hello_plus, A Simple AW

Here is a slight more complex AW:

It knows your screen name, the site you are playing on and how many hands you have played. It counts the number of hands played after every hand.

class Hello_plus(Aux_Window):
    """A slightly more complex 'Hello World' demo."""
    def __init__(self, hud, config, params):
        """Initialize a new aux_window object."""
        self.hud        = hud
        self.config     = config
        self.params     = params
 
        self.hands_played = 0     # initialize the hands played counter
 
        self.site = hud.site      # get the site we are playing from the HUD
        print "site =", hud.site  # print it to the terminal, to make sure
 
        try:
            site_params = self.config.get_site_parameters(self.hud.site)
            self.hero = site_params['screen_name']
        except:
            self.hero = 'YOUR NAME HERE'
        print "hero =", self.hero
 
    def create(self):
        """Creates the gui."""
        self.container = gtk.Window()               # create a gtk window for our container
        self.label = gtk.Label("")                  # create a blank label to write in update_gui
        self.container.add(self.label)              # add it to our container
        self.container.show_all()                   # show the container and its contents
 
    def update_data(self, new_hand_id, db_connection):
        """Increment the hands.played attribute."""
        self.hands_played = self.hands_played + 1   # our long-running calculation :)
 
    def update_gui(self, new_hand_id):
        """Update the aux_window gui."""
        self.label.set_text("Hello %s\nYou have played %d hands\n on %s." % (self.hero, self.hands_played, self.site))

init() Method

The init in this example is very simple and starts, as usual, with the normal capture of hud, config, and params for later use. Then the hands_played counter is set to 0 and we retrieve the current site name from the hud data. The site name is printed, just for a demonstration. Finally, we retreive the hero's screen name. This is wrapped in a try/except structure to demonstrate how to handle possible exceptions. If an exception occours in the try paragraph, then self.hero will be set to a safe default. It is a good idea to plan for unplanned events.

create() Method

The create() method simply creates a gtk window and sticks a blank label in it.

update_data() Method

The update_data() method just increments the hands_played counter for use in the update_gui() method.

update_gui() Method

Finally, we update the text in the label from the create() method.

Boilerplate

The previous examples just show the AW classes required to create those AWs. If you place your AW code in an existing file, Mucked.py, for example, all you need is what is shown above. If, on the other hand, you are putting your code in a new file (a module, in python lingo), you will need to add some more information. Here is what I added to make the examples work in Hello.py. You really only need to edit lines 3, 5, and 7 to update your file name, description and your name.

A note on copyright and license: That bit is entirely optional and up to you. If you are publishing/distributing your code you really should consider doing this, it lets users know what their rights are and protects your rights.

#!/usr/bin/env python
"""
Hello.py
 
Hello World demostration for Aux_Window.
"""
#    Copyright 2009, Ray E. Barker
#
#    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 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
 
########################################################################
 
#    to do
#    nothing, this module is perfect
 
#    Standard Library modules
import sys
 
#    pyGTK modules
import pygtk
import gtk
import gobject
 
#    FreePokerTools modules
from Mucked import Aux_Window