live.gnome.org

Addendum to this tutorial explaining how to create the following Tomboy addin in MonoDevelop

Note

Before Tomboy 0.7.2, Tomboy used another plugin system, which is incompatible with the current. Therefore, if your version of Tomboy is older than this, you should upgrade before you try to develop any addins.

Overview

In this HowTo we will develop a simple plugin for Tomboy using C#. The plugin will insert the current date and time at the cursor position, much like the Insert Date/Time plugin in gedit. The complete plugin can be downloaded from here: InsertDateTime.cs and InsertDateTime.addin.xml

The plugin file

Let's start with creating the plugin file called InsertDateTime.cs with the following content:

using Tomboy;

namespace Tomboy.InsertDateTime
{
        public class InsertDateTimeAddin : NoteAddin
        {
                public override void Initialize ()
                {
                }

                public override void Shutdown ()
                {
                }

                public override void OnNoteOpened ()
                {
                }
        }
}

The first thing you should notice is that our plugin extends the NoteAddin class. The name NoteAddin reveals how plugins are handled in Tomboy: an instance of the plugin is created per note. From within the plugin you have access to the associated note, its window and other stuff useful for a plugin.

A plugin must implement three abstract methods: Initialize, Shutdown and OnNoteOpened. Initialize is called at startup, when the plugin instances are created for each note, or when the plugin is activated in the preferences dialog. Respectively Shutdown is called when the plugin is deactivated. OnNoteOpened will be executed when the note window is opened for the first time.

The metadata file

We also need to create a metadata XML-file called InsertDateTime.addin.xml with the following content:

<Addin id="DateTimeAddin"
    namespace="Tomboy"
    name="Insert Date/Time"
    author="Tomboy Project"
    description="Inserts current date and time at the cursor position."
    category="Tools"
    defaultEnabled="false"
    version="0.1">

    <Runtime>
        <Import assembly="InsertDateTime.dll" />
    </Runtime>

    <Dependencies>
        <Addin id="Tomboy" version="0.7" />
    </Dependencies>

    <Extension path="/Tomboy/NoteAddins">
        <NoteAddin type="Tomboy.InsertDateTime.InsertDateTimeAddin" />
    </Extension>
</Addin>

This information is displayed on Tomboy's preferences dialog, and is what makes the addin system understand that this is a plugin.

Adding the menu item

using System;
using Mono.Unix;
using Gtk;
using Tomboy;

namespace Tomboy.InsertDateTime
{
        public class InsertDateTimeAddin : NoteAddin
        {
                Gtk.MenuItem item;

                public override void Initialize ()
                {
                        item = new Gtk.MenuItem (Catalog.GetString ("Insert date and time"));
                        item.Activated += OnMenuItemActivated;
                        item.Show ();
                        AddPluginMenuItem (item);
                }

                public override void Shutdown ()
                {
                        item.Activated -= OnMenuItemActivated;
                }

                public override void OnNoteOpened ()
                {
                }

                void OnMenuItemActivated (object sender, EventArgs args)
                {
                        Logger.Log ("Activated 'Insert date and time' menu item");
                }
        }
}

For inserting the date, our plugin will need an item in the menu. We create the entry in Initialize and store it in an instance variable for later usage. It should be possible to translate its text, that's why we get it from Catalog. The item is added to the menu via the helper method AddPluginMenuItem which is defined in the plugin's base class NoteAddin. When the item is activated, the callback method OnMenuItemActivated is called, which only writes a log message at the moment (Tomboy has its own logger class and does not use Console.WriteLine). The Shutdown method should do the clean up work, in our case, we have to remove the registered callback.

Sometimes it is necessary to do some initialisation work only once and not for every note. An example how to do that can be found in Tomboy's NoteOfTheDay plugin.

Inserting the date

Our last step is inserting the date at the cursor position. To achive this, we can use some stuff already used in Tomboy: the date format and the tag that defines the date's appearance. We get the buffer, which is a Gtk.TextBuffer, from the note that belongs to the plugin and insert the formatted date using the datetime tag.

void OnMenuItemActivated (object sender, EventArgs args)
{
        string format = Catalog.GetString ("dddd, MMMM d, h:mm tt");
        string text = DateTime.Now.ToString (format);

        NoteBuffer buffer = Note.Buffer;
        Gtk.TextIter cursor = buffer.GetIterAtMark (buffer.InsertMark);
        buffer.InsertWithTagsByName (ref cursor, text, "datetime");
}

Compiling

Compiling using Mono's gmcs is as simple as:

gmcs -debug -out:InsertDateTime.dll -target:library -pkg:tomboy-addins -r:Mono.Posix InsertDateTime.cs -resource:InsertDateTime.addin.xml

Testing

The easiest way to test is copying the generated .dll to .tomboy/addins/ inside your home directory ($HOME). After that restart tomboy and the plugin should be automatically loaded, but not yet enabled. To enable it, go to the Addins tab in the configuration window.

It its also useful to run tomboy from command line to check its log messages.