Writing a plugin for Diodon

The new plugin system for Diodon brings about an easy way to extend Diodon with any feature you might think of.

That could be a Ubuntu One integration, or clipboard actions, copying clipboard content to pastebin, and many many more…

With this post I try to explain you quickly how you go about writing your own plugin and will also point you to other documentation which might be helpful.

Before you start writing your own plugin, one thing is important to know. Diodon uses the library libpeas for its plugin system. Such is used for instance for Gedit or Totem.
There is a good blog post which describes how libpeas works.

You find some sample plugins code written in C, Vala or Python in the diodon bazaar branch plugin-sample.

You can check out and build it with following commands:

bzr branch lp:~diodon-team/diodon/plugin-sample
cd plugin-sample
./waf configure --libdir ~/.local/share/
./waf build
./waf install

For this you have to have Bazaar, valac and the package diodon-dev installed.

sudo apt-get install bzr diodon-dev valac

It is recommended to write your plugin in Vala. However C and Python is allowed as well.

As you can see the sample is using waf as a build system (which I personally prefer). However if you want to build your plugin with autotools, take at look at peas-demo of libpeas itself. There you find also some more code how a plugin can be written.

The object you can access in your plugin is the Diodon Controller.

Here is a list of events and methods which are provided:

public signal void on_select_item(IClipboardItem item)
public signal void on_add_item(IClipboardItem item)
public signal void on_remove_item(IClipboardItem item)
public signal void on_clear()
public void select_item(IClipboardItem item)
public void execute_paste(IClipboardItem item)
public void remove_item(IClipboardItem item)
public void add_item(IClipboardItem item)
public Gee.List get_items()
public ConfigurationModel get_configuration()
public void show_history()
public void show_preferences()
public void clear()
public Gtk.Menu get_menu()

Currently, there is no api documentation available. Therefore, for now, please refer to the the source code comments on the Controller.

When you miss a method or an event which you would need in your plugin, please let me know. Best just report a bug and mark it as wishlist. We can than see what we can do.

To test your plugin, there are two location where you can put your files. For simple testing you can add it to ~/.local/share/diodon/plugins. When providing the plugin in a package you should install it to /usr/lib/diodon/plugins.

In both cases you have to activate you plugin in the preferences dialog:

When you finally have finished your plugin, you can publish it as you prefer. However, we as a Diodon Team are intrested to include good plugins in the Diodon source.
Plugins written in Vala will be preferred, however for none-core plugins python and C is allowed as well.
For such a request please report a bug and mark it as Wishlist.

I’m looking forward to see with what idea you come up to extend Diodon.