Creating an ImageWidget

Example 1. 

#!/usr/bin/python

# Import the graphics toolkit and libraries
# for handling images as IO streams

import wx
import cStringIO

# Import the main ImageWidget library as well
# as one for handling errors. Also import some
# constant variables needed for an application
# specific About menu and dialogue and error
# reporting.

from ImageWidget.Widget    import ImageWidget
from ImageWidget.Error     import ImageWidgetError
from ImageWidget.Constants import IMAGEWIDGET_ID_ABOUT, IMAGEWIDGET_ERR_POLLING,IMAGEWIDGET_ERR_STREAMIFY

# Define some variables for use in our program
# I like to put this sort of thing in a separate
# package but that's your business. The important
# thing to note is that we are using Unicode objects
# for all our text. 

# The namespace variable is used for storing your
# application's configuration details alongside any
# defaults or plug-ins.

MYWIDGET_NAMESPACE   = u"http://www.example.com/mywidget#"
MYWIDGET_TITLE       = u"My First Widget"
MYWIDGET_ABOUT       = u"My First Widget\n\N{COPYRIGHT SIGN} 2005 Aaron Straup Cope"

MYWIDGET_ERR_PARSE   = u"failed to parse XML response"
MYWIDGET_ERR_FETCH   = u"failed to retrieve image"

# Python's default encoding, unless a user changes it
# in a global site preferences file is 'ascii'. You don't
# necessarily need to declare an encoding variable for
# your ImageWidget program but if you don't and accidentally
# pass it outside the expected range of charcters Bad Things
# will happen.

MYWIDGET_ENDPOINT_ENCODING = u"utf8"
MYWIDGET_ENDPOINT_XMLRPC   = u"http://example.com/mywidget/xml-rpc"
MYWIDGET_ENDPOINT_REST     = u"http://example.com/mywidget/rest"

# Create a new class for your widget and inherit from
# ImageWidget. ImageWidget itself inherits from wx.App

class MyWidget (ImageWidget) :
   

Example 2. 

    def Setup (self,name,uri) :

        # By default the Setup() method returns a wx.Frame
        # object which we grab right off the bat to use
        # for registering events specific to our application

	frame = ImageWidget.Setup(self,
				  MYWIDGET_TITLE,
				  MYWIDGET_NAMESPACE)

        # Tell the frame's main panel to use our local
        # KeyDown() method when it intercepts keyboard
        # events

	wx.EVT_KEY_DOWN(frame.Panel,
			self.KeyDown)

        # Likewise when a menu event with ID 'IMAGEWIDGET_ID_ABOUT'
        # is triggered, use our About() method rather than
        # the default

	wx.EVT_MENU(frame,
		    IMAGEWIDGET_ID_ABOUT,
		    self.About)

        # If we were going to register plugins or add
        # application-specific functionality we would
        # do it here. Since we're not in this example,
        # just return the original wx.Frame object.

	return frame;
   

Example 3. 

    def KeyDown (self,event) :

        # In this example, the only key we are concerned
        # with is the 'A' key which we will dispatch to
        # our local About method. Anything else we will
        # pass up the line.

        # By default, the GetKeyDown() method will only
        # return a value if the control (or command in OS
        # X) key is pressed.

	keyname = self.GetKeyDown(event)
        
	if keyname == "A":
            self.About(event)	    
	else :
	    return self.GetTopWindow().KeyDown(event)
   

Example 4. 

    def About (self,event) :

        # To be perfectly honest, I am still thinking
        # about abstracting this one out a bit more. I
        # haven't done that so we simply call the parent
        # object's About() method will localized values.

	ImageWidget.About(self,
			  event,
			  MYWIDGET_TITLE,
			  MYWIDGET_ABOUT)
   

Example 5. Fetching an image from an XML-RPC server

    def GetImage (self) :

        # In a more complicated application, you
        # might want to create a single 'api' object
        # in your '__init__' method and store it as
        # an attribute of 'self' but this works too.

        import xmlrpclib
        api = xmlrpclib.Server(MYWIDGET_ENDPOINT_XMLRPC)

        # Connect to the server and see what it
        # returns 

        try:
            res = api.image.Random()
        except Exception, e:
            raise ImageWidgetError(IMAGEWIDGET_ERR_POLLING,e);

	wx.SafeYield(self.GetTopWindow(),True);

        # Let's assume that the server returns the image
        # as a Base64 encoded string which our XML-RPC
        # library will decode. Take the result and create
        # a StringIO object which the app will use to
        # display the image.

        try:
            stream = cStringIO.StringIO(res["image"].data)         
        except Exception, e:
	    raise ImageWidgetError(IMAGEWIDGET_ERR_STREAMIFY,e);

	wx.SafeYield(self.GetTopWindow(),True);

        # Return a hash containing the StringIO object
        # and the other meta-data. At this point the
        # base class will take of displaying both.

	return {'image':stream,
		'title':unicode(res["title"],MYWIDGET_ENDPOINT_ENCODING),
		'description':unicode(res["description"],MYWIDGET_ENDPOINT_ENCODING),
		'location':unicode(res["location"],MYWIDGET_ENDPOINT_ENCODING),
		'date':unicode(res["date"],MYWIDGET_ENDPOINT_ENCODING),
		'url':unicode(res["url"],MYWIDGET_ENDPOINT_ENCODING),
		'uid':unicode(res["uid"],MYWIDGET_ENDPOINT_ENCODING),
		'license':unicode(res["license"],MYWIDGET_ENDPOINT_ENCODING),
		'creator':unicode(res["creator"],MYWIDGET_ENDPOINT_ENCODING)}
   

Example 6. Fetching an image using a REST-based service

    def GetImage (self) :

        # You don't have to use xmltramp; there are lots of
        # other XML parsing tools for Python but this one is
        # simple and mostly just "Does What I Mean"

        import urllib
        import xmltramp

        # Let's assume that the server will return an XML
        # string containing metadata elements including one
        # ('url') which we contain a pointer to an actual
        # image to fetch.

	try :
	    xml = urllib.urlopen(MYWIDGET_ENDPOINT_REST).read()
	except Exception, e:
	    raise ImageWidgetError(IMAGEWIDGET_ERR_POLLING,e);

	wx.SafeYield(self.GetTopWindow(),True);

        # Parse the XML

        try :
            res = xmltramp.parse(xml)
        except Exception, e
            raise ImageWidgetError(MYWIDGET_ERR_PARSE,e)

	wx.SafeYield(self.GetTopWindow(),True);

        # Retrieve the actual image from the interweb
        # and create a StringIO object as discussed above.

	try :
	    data = urllib.urlopen(res['url']).read();
	except Exception, e :
	    raise ImageWidgetError(MYWIDGET_ERR_FETCH,e)

	wx.SafeYield(self.GetTopWindow(),True);

	try :
	    stream = cStringIO.StringIO(data);
	except Exception, e :
	    raise WidgetError(IMAGEWIDGET_ERR_STREAMIFY,e);

        # Return a hash containing the StringIO object
        # and the other meta-data. At this point the
        # base class will take of displaying both.

        # xmltramp's __str__ method returns UTF-8
        # encoded Unicode objects
 
	wx.SafeYield(self.GetTopWindow(),True);

        return {'image':stream,
		'title':res.title.__str__(),
		'description':res.description.__str__(),
		'location':res.location.__str__(),
		'date':res.date.__str__(),
		'url':res.url.__str__(),
		'uid':res.uid.__str__(),
		'license':res.license.__str__(),
		'creator':res.creator.__str__()}
   

Example 7. 

if __name__ == "__main__" :
   widget = MyWidget ()
   widget.MainLoop()
   

Example 8. The minimum you need to do to use DeliciousTool

# Make sure to load the DeliciousTool package

from ImageWidgetDeliciousTool.Tool import DeliciousTool

# Make sure to include it in your application's
# inheritance tree

class MyWidget (ImageWidget,DeliciousTool) :

    # The Setup() method is exactly the same as described
    # above except that we also call the DeliciousTool Setup()
    # method passing both the current object and it's main
    # frame

    def Setup (self,name,uri) :

	frame = ImageWidget.Setup(self,
				  MYWIDGET_TITLE,
				  MYWIDGET_NAMESPACE)
	
	wx.EVT_MENU(frame,
		    IMAGEWIDGET_ID_ABOUT,
		    self.About)

	wx.EVT_KEY_DOWN(frame.Panel,
			self.KeyDown)

	DeliciousTool.Setup(self,frame)

	return frame;

    # Again, like above we intercept the 'A' key but
    # instead of automatically handing anything else
    # of to the parent ImageWidget classes we check
    # to see if DeliciousTool wants to do anything with
    # it

    # DeliciousTool
    def KeyDown (self,event) :

	keyname = self.GetKeyDown(event)

	if keyname == "A":
            self.About(event)	    
	elif self.DeliciousKeyDown(keyname) :
	    return self.DeliciousKeyDown(keyname,event)
	else :
	    return self.GetTopWindow().KeyDown(event)
   

Example 9. DeliciousTool methods

    # By default returns an empty string

    def DeliciousTags (self) :
	return u"foo bar baz"

    # The first item in the format string is
    # the value assigned to the 'creator' key
    # in the hash returned by the GetImage()
    # method; the second is the value assigned
    # to the 'title' key.

    # The default formatting string is "[%s] %s"

    def PostToDelicious (self,event) :
	fmt = u"My First Widget - %s, %s"
	DeliciousTool.PostToDelicious(self,event,fmt)