AWNLib Tutorial Part 2

From AWN Wiki

[edit] About This Tutorial

This tutorial is for anyone who wants to write applets for AWN. It'll teach you how to write applets using the AWNLib framework - the framework is very nice and makes it much easier to get up and running with an applet. Most of this part, and to a lesser degree the next few parts, will also be of use to the AWN Applet developer who doesn't use AWNLib (or even Python). Something also tells me you may want to have read the previous tutorial.

[edit] Where we are now

So far, we've downloaded all of the necessary materials and files. We've set up our desktop file, and we've even linked it to the AWN Applet folder so that its easy to work with. Now lets pick up where we left off. In particular, most of the AWNLib-specific things will happen in this part of the tutorial.

[edit] Legal Stuff

Right now, what we want to do is to create the Python file that makes our applet actually do something. When we do this, keep in mind the Applet Development Guidelines. If you want to create a good applet, follow them as closely as you can.

Following these guidelines, let's begin by inserting the GNU GPL Header into the top of our file. In particular, you'll want to add the following to the top of slashdot.py:

#!/usr/bin/python
#
#       slashdot.py Version 1.0
#
#       Copyright 2008 My Name <my@name.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 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., 51 Franklin Street, Fifth Floor, Boston,
#       MA 02110-1301, USA.

Of course, you'll need to modify the copyright line there to reflect yourself. By the way, if you really want, you can refuse to use the GPL in your code (maybe you like the BSD license), or switch to the GPLv3. However, this is strongly discouraged and makes it harder to include your applet into AWN-Extras. Unless you have really big reasons, just license under the GPL2.

[edit] Anatomy of an AWNLib Applet

Now that we've got the legal stuff out of the way, let's begin to make a working applet. Here's the base code you need for any AWN applet with AWNLib:

import AWNLib
import gtk

applet = AWNLib.initiate({"name": "Slashdot Applet", "short": "slashdot"})

# ... Program logic

AWNLib.start(applet)

Here are few things of interest:

• We're importing both AWNLib and GTK. We need AWNLib to use AWNLib, and we'll need GTK later on to create the GUI for our applet.
• Next, we're calling the special initiate function in AWNLib. This function takes a single argument, which is a dictionary of metadata about your applet. For now, the only known keys are "name" and "short", the second being the shortened form of your applet's name. Make sure these don't conflict with another applet.
• We do some yet unspecified program logic
• And then we finally tell AWNLib that we're done and that our applet should be started. This does important things like starting the gtk mainloop and putting the applet icon on the AWN bar. Remember that getting to this point should take as little time as possible. Only when we call AWNLib.start do we actually have the applet show up on the AWN bar.

[edit] Making the Applet Useful

As you've probably heard, its best to wrap code into a separate class. So let's do that. We also want to set the title of our applet and show the cool icon we made before. So let's add the following class to our Python file right after the imports:

feedparser = None

class SlashdotApplet:
    def __init__(self, awnlib):
        self.awn = awnlib
        self.awn.icon.set(self.awn.icon.getFile("slashdot.svg"))
        # Title set automatically to the "name" we gave AWNLib.initiate

        self.awn.module.get("feedparser", {"Ubuntu": "python-feedparser"}, \
            self.init2)

    def init2(self, module):
        global feedparser
        feedparser = module

Note that "feedparser =" line. Also, in place of the commented out program logic from before put:

slashdotapplet = SlashdotApplet(applet)

Make sure the other two lines are still there.

Let's look at what we did:

• First we created a global variable "feedparser". Since we're going to eventually use feedparser to parse the Slashdot RSS feed, we'd like this variable to eventually be filled with the feedparser module. However, if we just straight import it, users who don't have it will just get a crashing applet and a console error. AWNLib has a better way. More later.
• We've created a separate class to house our applet. The constructor (the __init__ method) takes the AWNLib Applet the we created earlier (AWNLib.initiate returns it, and we stored it as the global "applet" variable) as a parameter. We store this object-level (we need it to interact with AWNLib later on).
• We set the applet icon. The file name is relative, as you'd expect.
• Lastly, we call AWNLib's module.get. This takes three argument:
  • The module we want to import
  • A dictionary of distros and the associated packages
  • The function to pass the module to. This has to be the only required argument of the function (except self)
• We also create a new function called init2 which takes the module we just imported and stores it into the global variable defined before.
• Lastly (back at the end of the code), we also created a SlashdotApplet object from the applet. Note that this isn't passed to AWNLib.start. You can actually not store the return value anywhere. All interaction with AWNLib is done internally in the object.

[edit] Setting up the Skeleton

To be added...