This is intended for developers hoping to create plugins for AWN. Please feel free to add helpful hints to other developers! However, developers are expected to have a firm grasp of DBus before beginning.

Writing Plugins through DBus:

If you want to write a plugin for your favorite applications, you'll first need to connect to AWN's DBus object. In Python, that would look like the following:

bus = dbus.SessionBus()
obj = bus.get_object("com.google.code.Awn", "/com/google/code/Awn")
awn = dbus.Interface(obj, "com.google.code.Awn")

Which will get you the basic AWN object, which you will use to control various properties, such as an application's icon.

Getting to an application:

There are two main ways to get the application, orwindow, that you want:

1. The name of the application (as a string).
   This works best for single-instance applications.
2. By the xid (as a long), which is best for multi-instance apps , as it will only effect the icon for that window.
   One way to get the xid is by calling GDK_WINDOW_XID(window->window).

Support for using the PID to reference your application is planned.

Setting Icons

To set the icon for a task, you need to call either SetTaskIconByName or SetTaskIconByXid. In Python, that would be:

awn.SetTaskIconByName ("rhythmbox", "/tmp/rhythmbox-album-art.png")

or

awn.SetTaskIconByXid (long(xid), "/tmp/rhythmbox-album-art.png")

The second argument of either has to be a local path. Using /tmp is the best idea, as it will get wiped when you restart.
You have to call awn.SetTaskIconByName/Xid every time you want to update, even if you are using the same file name (recommended as to avoid unneccessary junk in /tmp). If you need to unset the icon, use :

awn.UnsetTaskIconByName ("rhythmbox")

or

awn.UnsetTaskIconByXid (xid)

The name may not always match, however, though Neil is working on this;be patient if your favorite application does not work.

Setting Information:

Setting information is easy:

awn.SetInfoByName ("evolution", "23")

or

awn.SetInfoByXid (xid, "23")

And so is unsetting:

awn.UnsetInfoByName ("evolution")

or

awn.UnsetInfoByXid (xid)

Setting Progress:

This, too, is very easy:

awn.SetProgressByName ("firefox", 60)

or

awn.SetProgressByXid (xid, 60)

While there is no 'unset' function, setting the progress to 100% will clear the icon of the progress meter.

DBus links

• Python Tutorial
• DbusSharp (mono)
• Main DBus tutorial