Tutorial: Write an Evolution Plugin

Evolution Plugin

This tutorial will show you how to write a mumbles plugin for Evolution that sends a notification when new mail is received.

Plugin Files

If you want to save yourself some typing (or indenting!) time, or just want to grab the plugin, the files for the tutorial are available here.

Requirements for this tutorial

  • mumbles version 0.4
  • dbus-monitor
  • Evoultion

The DBus

As mumbles makes use of DBus, the first step in writing a plugin for mumbles is to look for the DBus signals, to which, we are able to connect. I like a simple command line application called dbus-monitor for this.

So, let’s watch what happens on the DBus while running Evolution. First in a terminal type:


              
dbus-monitor

              

Next start Evolution.

In the output of dbus-monitor you should see (among other things) a few lines that look similar to:


              
signal sender=:1.62 -> dest=(null destination) path=/org/gnome/evolution/mail/newmail; interface=org.gnome.evolution.mail.dbus.Signal; member=MessageReading string “Inbox”

              

Here, we see a DBus signal named ‘MessageReading’. In our example, we’re interested in what happens when new mail is received. So send your self a test message and click Send/Receive. You should then see, when your message arrives, in dbus-monitor something like:


              
signal sender=:1.62 -> dest=(null destination) path=/org/gnome/evolution/mail/newmail; interface=org.gnome.evolution.mail.dbus.Signal; member=Newmail string “mbox:/home/dot_j/.evolution/mail/local#Inbox” string “Inbox”

              

We see that when, new mail arrives, a signal is sent to the DBus called ‘NewMail’. A few other things we’ll need to note are:

  • The signal name (member): NewMail
  • The path: /org/gnome/evolution/mail/newmail
  • The interface: org.gnome.evolution.mail.dbus.Signal
  • And the two paramaters that are sent to the signal:
    • “mbox:/home/dot_j/.evolution/mail/local#Inbox”
    • “Inbox

Writing the plugin

We’ll make use of those shortly in the code for the plugin. We got what we needed from dbus-monitor, so go ahead and close it and create a new directory in your home directory for our plugin:


              
mkdir ~/evolution_plugin

              

If you have mumbles installed locally and have dug around in the directories, you may have seen the structure of a mumbles plugin. Each plugin has a file named


              
setup.py

              

and a directory named


              
src

              

The src directory contains another python file called


              
__init__.py

              

setup.py is just that - a setup file for our plugin and __init__.py in the src directory is the source file for our plugin.

Now let’s get down to business. Let’s setup that structure in a new directory for our plugin:


              
mkdir ~/evolution_plugin/src

              

Next, create setup.py in your favorite editor:


              
gedit ~/evolution_plugin/setup.py

              

And enter:


              
#———————————————————————— # A Mumbles Plugin for Evolution #   Copyright (c) 2007 dot_j <dot_j[at]mumbles-project[dot]org> #   Lisenced under the GPL #———————————————————————— from setuptools import setup import sys, os from shutil import copy __author__ = ‘dot_j[AT]mumbles-project[DOT]org’ __doc__ = ‘An Evolution plugin for mumbles’ __version__ = ‘0.1′ setup(     name=‘EvolutionMumbles’,     version=__version__,     description=__doc__,     author=__author__,     packages=[‘evolution’],     package_dir={‘evolution’:’src’},     entry_points=‘     [mumbles.plugins]     Evolution = evolution:EvolutionMumbles     ‘ )

And save setup.py

Pretty straight forward setup here. We define our author, documentation and plugin version tags and add what we need in order to build our python egg (plugin). For more information about eggs and setuptools see here.

Now create our plugin source file


              
gedit ~/evolution_plugin/src/__init__.py

              

And enter:


              
#———————————————————————— # A Mumbles Plugin for Evolution #   Copyright (c) 2007 dot_j <dot_j[at]mumbles-project[dot]org> #   Lisenced under the GPL #———————————————————————— # We’ll extend the MumblesPlugin class to create our Evolution plugin from MumblesPlugin import * class EvolutionMumbles(MumblesPlugin):     # Give our plugin a name (using the same name we used in setup.py).     plugin_name = “EvolutionMumbles”     # Use the dbus interface we saw in dbus-notify     dbus_interface = “org.gnome.evolution.mail.dbus.Signal”     # Use the dbus path we saw in dbus-notify     dbus_path = “/org/gnome/evolution/mail/newmail”     # Configure our plugin icon     icons = {‘evolution’ : ‘evolution.png’}     # setup the __init__ function where we define     # the dbus signal(s), to which, we are connecting.     # Note this function takes 2 parameters (mumbles_notify and     # session_bus) that we will hand off to our     # MumblesPlugin parent class     def __init__(self, mumbles_notify, session_bus):         # Here, we tell our plugin to connect the dbus signal         # ‘Newmail’ to our plugin class’s ‘NewMail’ function         self.signal_config = {             “Newmail”: self.NewMail         }         # and hand off our mumbles_notify and session_bus objects to our parent         MumblesPlugin.__init__(self, mumbles_notify, session_bus)     # NewMail function     # This will get called when a NewMail signal is received on the DBus from Evolution     # Note the function takes 2 parameters (the two we saw in the dbus-monitor activity)     def NewMail(self, mbox_path, folder_name):         # Get our icon using the key we used above when configuring our icons dictionary         icon = self.get_icon(‘evolution’)         # Define what we want to send in our notification:         # Send a simple title         title = ‘Evolution: New Mail!’         # Let’s send our folder name as our notification message         message = folder_name         # If you want to try an advanced version of the plugin,         # see if you can use the supplied mbox_path to get more information         # about the message that just arrived! And be sure to let us know         # about your efforts.         # Finally, using our mumbles_notification object, send the notification         self.mumbles_notify.alert(self.plugin_name, title, message, icon)

And just 60 lines of code (with comments!) - not too bad, right? And we’re almost there. But first, we need to create that icon we used and put it where our plugin can find it.

So, create a plugins directory in your hidden .mumbles directory in your home folder. If you have run mumbles already, you will already have a directory called ~/.mumbles. If not, create that first, then create the plugin and plugin/icons directories there.


              
mkdir ~/.mumbles (if you need to, but you shouldn’t) mkdir ~/.mumbles/plugins mkdir ~/.mumbles/plugins/icons

              

The default themes that come with mumbles will support an image around 20×20 pixels. So for this example, I used the Evolution icon I had in in /usr/share/icons/hicolor/22×22/apps/evolution.png


              
cp /usr/share/icons/hicolor/22×22/apps/evolution.png ~/.mumbles/plugins/icons

              

Build and install the plugin


              
cd ~/evolution_plugin (if you’re not already there) python setup.py bdist_egg

              

This will use our setup.py file to create our plugin. After it runs, you should see a file named


              
EvolutionMumbles-0.1-py2.5.egg

              

in the dist directory that was created by the build process. Here the -py2.5 part of the filename refers to what version of python you are using (it may vary, but if you are able to start mumbles, should not matter).

The .egg file is our plugin, so the only thing left to do is copy that to the mumbles plugin directory.


              
cp dist/EvolutionMumbles-0.1-py2.5.egg ~/.mumbles/plugins

              

Try it

That’s it! Now run mumbles and send yourself another email. You should see your new mail notification!

Thanks for following along. I hope you found this tutorial both helpful and interesting. And I hope it inspired you to write a plugin of your own. If you expand on this example, or write a new plugin for your favorite application be sure to let us know!

Files

Download tutorial files here.

One Comment to 'Tutorial: Write an Evolution Plugin'

Subscribe to comments with RSS or TrackBack to 'Tutorial: Write an Evolution Plugin'.

    :: Trackbacks/Pingbacks ::

    1. Pingback by mumbles-project.org » New Plugin: Amarok Track Change Notifications - on September 5th, 2007 at 8:39 pm

    Leave a Reply