This is the third article in my series on writing Qt applications in ruby. I was planning to write about the declarative GUI system that I use in kaya, but a comment on one of my previous posts motivated me to take a small detour, and illustrate a very simple technique to extend a qtruby application with C++ code.

So, suppose you need to expose a C++ function like:

void applyEffect(QImage* img, float arg);

that takes a QImage, an argument, and applies a graphic effect, mutating the image in place.

Directly exposing this function to ruby using the extension API is not easy, because you need to extract a QImage pointer from the ruby object corresponding to the QImage, and that would require you to make assumptions on exactly how QObjects are wrapped by the ruby binding code, which is not ideal for a number of reasons.

Fortunately, there exists an elegant solution to this problem. First, you need to define your C++ function as a slot of some QObject. For example:

class Extensions : public QObject
{
Q_OBJECT
public slots:
  void applyEffect(QImage* img, float arg) const;
};

Then in your extension initialization function you can instantiate it with something like:

Extensions* ext = new Extensions(QCoreApplication::instance());
ext->setObjectName("__extensions__");

And finally access it from ruby code and wrap it in a nicer package:

$ext = $qApp.findChild(Qt::Object, "__extensions__");
class Qt::Image
  def apply_effect(arg)
    $ext.applyEffect(self, arg)
  end
end

This works because Qt allows you to call slots dynamically using runtime introspection of QObjects. It’s not as fast as a native function call, but in the context of a ruby method call, the additional cost should be pretty much negligible.

Of course, unless your extension is particularly large and complicated, you don’t need to create an Extension object for each of the functions you want to expose: you can add all of them as slots in a single Extension object, which is loaded at startup, and create a ruby-esque API for them directly in ruby code.