Scripting Tomboy

Tomboy is an open source GNOME desktop note-taking application which is written in C# and utilizing the Mono runtime, Gtk# and the GtkSpell spell-checker.

The actual release of Tomboy which comes with Fedora 10 is version 0.12.0.  This includes a comprehensive D-Bus interface which makes it possible to create, modify and display Tomcat notes from your shell scripts.  This post provides an overview of the available D-Bus methods and includes a number of examples for you to experiment with.  See my previous post on D-Bus scripting if you are unfamilar with the basic concepts of D-Bus scripting.

First we will list the available objects using qdbus.

$ qdbus org.gnome.Tomboy
/
/org
/org/gnome
/org/gnome/Tomboy
/org/gnome/Tomboy/RemoteControl

Next, we list all the available signals and methods for RemoteControl.

$ qdbus org.gnome.Tomboy /org/gnome/Tomboy/RemoteControl
method QString org.freedesktop.DBus.Introspectable.Introspect()
method bool org.gnome.Tomboy.RemoteControl.AddTagToNote(QString uri, QString tag_name)
method QString org.gnome.Tomboy.RemoteControl.CreateNamedNote(QString linked_title)
method QString org.gnome.Tomboy.RemoteControl.CreateNote()
method bool org.gnome.Tomboy.RemoteControl.DeleteNote(QString uri)
method bool org.gnome.Tomboy.RemoteControl.DisplayNote(QString uri)
method bool org.gnome.Tomboy.RemoteControl.DisplayNoteWithSearch(QString uri, QString search)
method void org.gnome.Tomboy.RemoteControl.DisplaySearch()
method void org.gnome.Tomboy.RemoteControl.DisplaySearchWithText(QString search_text)
method QString org.gnome.Tomboy.RemoteControl.FindNote(QString linked_title)
method QString org.gnome.Tomboy.RemoteControl.FindStartHereNote()
method QStringList org.gnome.Tomboy.RemoteControl.GetAllNotesWithTag(QString tag_name)
method qlonglong org.gnome.Tomboy.RemoteControl.GetNoteChangeDate(QString uri)
method QString org.gnome.Tomboy.RemoteControl.GetNoteCompleteXml(QString uri)
method QString org.gnome.Tomboy.RemoteControl.GetNoteContents(QString uri)
method QString org.gnome.Tomboy.RemoteControl.GetNoteContentsXml(QString uri)
method qlonglong org.gnome.Tomboy.RemoteControl.GetNoteCreateDate(QString uri)
method QString org.gnome.Tomboy.RemoteControl.GetNoteTitle(QString uri)
method QStringList org.gnome.Tomboy.RemoteControl.GetTagsForNote(QString uri)
method bool org.gnome.Tomboy.RemoteControl.HideNote(QString uri)
method QStringList org.gnome.Tomboy.RemoteControl.ListAllNotes()
signal void org.gnome.Tomboy.RemoteControl.NoteAdded(QString uri)
signal void org.gnome.Tomboy.RemoteControl.NoteDeleted(QString uri, QString title)
method bool org.gnome.Tomboy.RemoteControl.NoteExists(QString uri)
signal void org.gnome.Tomboy.RemoteControl.NoteSaved(QString uri)
method bool org.gnome.Tomboy.RemoteControl.RemoveTagFromNote(QString uri, QString tag_name)
method QStringList org.gnome.Tomboy.RemoteControl.SearchNotes(QString query, bool case_sensitive)
method bool org.gnome.Tomboy.RemoteControl.SetNoteCompleteXml(QString uri, QString xml_contents)
method bool org.gnome.Tomboy.RemoteControl.SetNoteContents(QString uri, QString text_contents)
method bool org.gnome.Tomboy.RemoteControl.SetNoteContentsXml(QString uri, QString xml_contents)
method QString org.gnome.Tomboy.RemoteControl.Version()

As a simple example of how to use a published method, we invoke the Version method to return the version of Tomboy that we are using.

$ qdbus org.gnome.Tomboy /org/gnome/Tomboy/RemoteControl org.gnome.Tomboy.RemoteControl.Version
0.12.0

We can use dbus-send instead of qdbus as shown below but, as you can, see qdbus syntax is more compact.  Also note that we have to use the session bus.

$ dbus-send --type=method_call --session --print-reply \
    --dest='org.gnome.Tomboy' /org/gnome/Tomboy/RemoteControl \
    org.gnome.Tomboy.RemoteControl.Version
0.12.0

In the following example, we create the equivalant of "Hello World" using a note, display it for 5 seconds and then delete the note.

#!/bin/bash
DPATH="/org/gnome/Tomboy/RemoteControl"
INTERFACE="org.gnome.Tomboy.RemoteControl"

TMP=`qdbus org.gnome.Tomboy ${DPATH} ${INTERFACE}.CreateNamedNote "My Note" 2>/dev/null`
RESULT=$?
if [[ $RESULT != 0 ]]
then
    exit 1
fi

# figure out note uri string which is of the form
# note://0xaf3356abcdefg
OID=${TMP#note:}

# set the contents of the note using the uid
qdbus org.gnome.Tomboy ${DPATH} ${INTERFACE}.SetNoteContents note:$OID "Hello World"
qdbus org.gnome.Tomboy ${DPATH} ${INTERFACE}.DisplayNote note:$OID
sleep 5
qdbus org.gnome.Tomboy ${DPATH} ${INTERFACE}.DeleteNote note:$OID

Here is a screenshot of the note created by this shell script.



Incidentally, if you create one or more notes by accident while experimenting and need to delete them, the following script will delete all notes.

#!/bin/bash
OJECT="org.gnome.Tomboy"
DPATH="/org/gnome/Tomboy/RemoteControl"
IFACE="org.gnome.Tomboy.RemoteControl"

qdbus ${OJECT} ${DPATH} ${IFACE}.ListAllNotes |
while read TMP
do
  echo "$TMP"
  OID=${TMP#note:}
  qdbus ${OJECT} ${DPATH} ${IFACE}.DeleteNote note:$OID
done

You can also add one or more tags to a note and extract comprehensive metadata in XML format as shown in the following example.

#!/bin/bash
OJECT="org.gnome.Tomboy"
DPATH="/org/gnome/Tomboy/RemoteControl"
IFACE="org.gnome.Tomboy.RemoteControl"

TMP=`qdbus ${OJECT} ${DPATH} ${IFACE}.CreateNamedNote "My Note" 2>/dev/null`
RESULT=$?
OID=${TMP#note:}

qdbus ${OJECT} ${DPATH} ${IFACE}.SetNoteContents note:$OID "Hello World"
qdbus ${OJECT} ${DPATH} ${IFACE}.AddTagToNote note:$OID "blog example"
qdbus ${OJECT} ${DPATH} ${IFACE}.DisplayNote note:$OID
sleep 4
qdbus ${OJECT} ${DPATH} ${IFACE}.GetNoteCompleteXml note:$OID
qdbus ${OJECT} ${DPATH} ${IFACE}.DeleteNote note:$OID

# this is the output from the GetNoteCompleteXml
<?xml version="1.0" encoding="utf-16"?>
<note version="0.3" xmlns:link="http://beatniksoftware.com/tomboy/link" xmlns:size="http://beatniksoftware.com/tomboy/size" xmlns="http://beatniksoftware.com/tomboy">
  <title>My Note</title>
  <text xml:space="preserve"><note-content version="0.1">Hello World</note-content></text>
  <last-change-date>2009-02-08T10:44:46.3741020-05:00</last-change-date>
  <last-metadata-change-date>2009-02-08T10:44:46.3940970-05:00</last-metadata-change-date>
  <create-date>2009-02-08T10:44:46.3441770-05:00</create-date>
  <cursor-position>37</cursor-position>
  <width>450</width>
  <height>360</height>
  <x>3</x>
  <y>48</y>
  <tags>
    <tag>blog example</tag>
  </tags>
  <open-on-startup>False</open-on-startup>
</note>

You can also create a note in a single call to dbus-send or qdbus by passing the appropriate XML formatted details to the SetNoteCompleteXml method.

#!/bin/bash
OJECT="org.gnome.Tomboy"
DPATH="/org/gnome/Tomboy/RemoteControl"
IFACE="org.gnome.Tomboy.RemoteControl"

TMP=`qdbus ${OJECT} ${DPATH} ${IFACE}.CreateNamedNote "My Note" 2>/dev/null`
RESULT=$?
OID=${TMP#note:}

qdbus ${OJECT} ${DPATH} ${IFACE}.SetNoteCompleteXml note:$OID \
"<?xml version='1.0' encoding='utf-16'?>
 <note version='0.3' xmlns:link='http://beatniksoftware.com/tomboy/link'
     xmlns:size='http://beatniksoftware.com/tomboy/size'
     xmlns='http://beatniksoftware.com/tomboy'>
  <title>My Note</title>
  <text xml:space='preserve'>
      <note-content version='0.1'>Hello World</note-content>
  </text>
  <tags>
    <tag>first tag</tag>
    <tag>second tag</tag>#!/bin/bash
  </tags>
  <open-on-startup>False</open-on-startup>
</note>"

qdbus ${OJECT} ${DPATH} ${IFACE}.DisplayNote note:$OID
sleep 4
qdbus ${OJECT} ${DPATH} ${IFACE}.DeleteNote note:$OID

Interestingly, for some reason or other you cannot set the position or size of the resulting note.  If anybody knows how to overcome this limitation, please let me know.

Well that is all for this particular post as I have to head off to the airport for another boring long flight to Europe.  In my next post I will show you how to handle D-Bus signals in your shell scripts.