QtScript: Exposing C++ classes (part two)

This is the second part of my QtScript walkthrough / tutorial. You can read the first part here.

As in the last tutorial, I must add the following disclaimer:

I'm writing these posts as I learn to use the QtScript module. As such, the solution I present here may not be the best / most elegant way of doing things. However, if I find a better solution, I'll certainly post back here in the future with corrections.

If there's any (QtScript-related) topic you'd like me to write about in the future, just leave a message and I'll endeavor to fulfill your request.

Background:

The last post was all about deferring some execution from a C++ class to an ECMAScript. The basic idea was that the C++ class could emit signals, zero or more of which were connected to functions in the script file. The script file set up these connections, so the the C++ code doesn't need to know which signals are being overridden, and which aren't.

This is all well and good, but you'll soon find that there's very little you can do in the script file, since the only functionality you have available is the builtin ECMASCript functions.What I'm going to look at today is how to make your own, and Qt classes available for use in the script file. In my example, I'm going to make the QMessageBox class available, but you can choose any other method you want.


Take 1:

First off, I want to be able to write "mb = new QMessageBox;" on my script, and have it work. This is actually pretty simple to achieve. The way I have chosen to do this is with a wrapper class. This wrapper derives from QMessageBox and QScriptable, and contains the magic "qscript_call" method. Here's the code:

// wrapper around QMessageBox:
class Wrapper_QMessageBox: public QMessageBox, protected QScriptable
{
 Q_OBJECT
 public:
 
 Wrapper_QMessageBox(QWidget *parent =0)
 : QMessageBox(parent) {}
 
 public slots:
  QScriptValue qscript_call(QWidget *parent = 0)
  {
   QMessageBox * const iface = new Wrapper_QMessageBox(parent);
   return engine()->newQObject(iface, QScriptEngine::AutoOwnership); 
  }
};

This is the complete wrapper so far. Note that normally I wouldn't write all this code inline, as I firmly believe that inline functions are evil, but for demonstration code I think this makes it more readable. As you can see, we inherit from QMessageBox and from QScriptable. Note the protected inheritance! QScriptable gives us the engine() call we need later on.

The constructor is pretty straight forward - no surprises there!

Then we have a special slot called "qscript_call". This seems to be an undocumented feature in Qt, (try searching for qscript_call on google and you get very few results). Essentially, this slot gets called when our wrapper class is called as a function. I guess this is similar to the meta-method "__call__" in python. All we do in this slot is make a new instance of the wrapper class (remember that our wrapper class is a QMessageBox as well), and return it.

Our wrapper class still isn't available in the scripts however. In order to do that, we need to add this one line of code:

 m_pEngine->globalObject().setProperty("QMessageBox", m_pEngine->newQObject(new Wrapper_QMessageBox, QScriptEngine::AutoOwnership));

This one line adds our wrapper class to the script global object. Once you've done this, you can no create QMessageBox instances from within a script file, like so:

 mb = new QMessageBox();
 mb.text = "Test!";
 mb.exec();

However, there are still a few issues left to resolve:

1. We can only use the default - empty constructor.
2. Only properties and slots of the QMessageBox are available from the script. For example, there's no way to set the window title text<> right now. If we could use the overloaded QMessageBox constructor that took the window title as a parameter then we could just specify it at creation time, but we'll need a way to export non-slot methods as well.
   

Let's tackle these issues one at a time:

Adding Overloaded Constructors:

This one's pretty simple. All you need to do is add another constructor that takes the additional parameters, and passes them up to the QMessageBox class. Then, you overload the qscript_call method in a similar fashion. Here's what my class looks like now:

// wrapper around QMessageBox:
class Wrapper_QMessageBox: public QMessageBox, protected QScriptable
{
 Q_OBJECT
 public:
 
 Wrapper_QMessageBox(QWidget *parent =0)
 : QMessageBox(parent) {}
 
 Wrapper_QMessageBox(Icon icon, const QString & title, const QString & text, StandardButtons buttons = NoButton, QWidget * parent = 0, Qt::WindowFlags f = Qt::Dialog | Qt::MSWindowsFixedSizeDialogHint)
 : QMessageBox(icon,title,text,buttons,parent,f) {}
 
 public slots:
  QScriptValue qscript_call(QWidget *parent = 0)
  {
   QMessageBox * const iface = new Wrapper_QMessageBox(parent);
   return engine()->newQObject(iface, QScriptEngine::AutoOwnership); 
  }
  QScriptValue qscript_call( Icon icon, const QString & title, const QString & text, StandardButtons buttons = NoButton, QWidget * parent = 0, Qt::WindowFlags f = Qt::Dialog | Qt::MSWindowsFixedSizeDialogHint )
  {
   QMessageBox * const iface = new Wrapper_QMessageBox(icon,title,text,buttons,parent,f);
   return engine()->newQObject(iface, QScriptEngine::AutoOwnership);
  }
};

You can now call this new constructor straight from your script file, just as you could earlier!

Exposing Additional Methods:

Finally, we need a way to expose arbitrary methods that are not slots in our base class. This is pretty simple. We make our own method with the same name, and call into the base class method with the parameters passed to us. Consider my wrapper class, now that I have exposed the setWindowTitle method:

// wrapper around QMessageBox:
class Wrapper_QMessageBox: public QMessageBox, protected QScriptable
{
 Q_OBJECT
 public:
 
 Wrapper_QMessageBox(QWidget *parent =0)
 : QMessageBox(parent) {}
 
 Wrapper_QMessageBox(Icon icon, const QString & title, const QString & text, StandardButtons buttons = NoButton, QWidget * parent = 0, Qt::WindowFlags f = Qt::Dialog | Qt::MSWindowsFixedSizeDialogHint)
 : QMessageBox(icon,title,text,buttons,parent,f) {}
 
 public slots:
  QScriptValue qscript_call(QWidget *parent = 0)
  {
   QMessageBox * const iface = new Wrapper_QMessageBox(parent);
   return engine()->newQObject(iface, QScriptEngine::AutoOwnership); 
  }
  QScriptValue qscript_call( Icon icon, const QString & title, const QString & text, StandardButtons buttons = NoButton, QWidget * parent = 0, Qt::WindowFlags f = Qt::Dialog | Qt::MSWindowsFixedSizeDialogHint )
  {
   QMessageBox * const iface = new Wrapper_QMessageBox(icon,title,text,buttons,parent,f);
   return engine()->newQObject(iface, QScriptEngine::AutoOwnership);
  }
  void setWindowTitle ( const QString & title )
  {
   QMessageBox::setWindowTitle(title);
  }
};

Simple!

Conclusion:

Combined with my earlier post, this should be all you need to make a Qt application extensible through ECMAScript files. I'm doing all this work to write a small game, but the techniques covered should work for all types of projects. If / When I find anything that requires updating, I will endeavour to update these posts. Since I'm still learning QtScript myself, I'm sure these pages will be filled with innacuracies.

How to make C++ classes available in QtScript

It's been a while since I posted here. What have I been doing? Mostly working, and in my spare time trying to get my head around QtScript. What follows is a short introduction into QtScript. I'm sure that there are points of inaccuracy in this post - this is only to be expected, since I'm just starting out.

What I need for my game, is a single C++ class that can defer some of it's processing to a script, thereby changing the behavior of the class. For example, I want a "GameObject" class, that takes a script filename as a constructor parameter, and defers certain parts of the processing to the script. In the case of the game object, I may want to defer the following functionality to a script:

• Graphics loading (so different game objects look different).
• AI processing.
• Generic event handling.

However, not all scripts will do all of the above - some may only customize a very small amount.

The easiest way to do this is to have signals in the C++ class, that the script can choose to connect to (or not, as the case may be). As the C++ class is executed, it can emit these signals, and the corresponding slots in the script file can be called.

The Code

The C++ code is relatively simple. Consider the following header file:

#ifndef TESTSCRIPTOBJECT_H
#define TESTSCRIPTOBJECT_H
//
#include <qobject>
#include <qscriptvalue>
#include <qscriptable>
#include <qscriptengine>
#include <qmessagebox>
//

class QScriptEngine;


//
// Test script object class - used to demonstrate the fundamentals of QtScript.
//
class testScriptObject : public QObject
{
Q_OBJECT
public:
 // ctor for this class - pass in the script engine to bind to.
 testScriptObject( QScriptEngine *pEngine, QObject *parent =0);

 // attach ourselves to a script file - this could be done inside the ctor. I
 // have chosen to use a separate method instead.
 void runScript(const QString &strProgram);
 
 signals:
 // test signal - we can emit this, and have some QtScript code run.
 void signal1();
 
public slots:
 // test slot - just displays a message box. 
 void slot1();
 // second test slot - displays the string in a combo box.
 void displayMsg(QString strMsg);
 
private:
 // store a pointer to the script engine.
 QScriptEngine *m_pEngine;
 
 // store the "this" object, so we can manually call script functions if we need to.
 QScriptValue m_thisObject;
};

This should all be fairly easy stuff. If it's not, you should probably look at the Qt tutorials before going any further.

Before we can use this class in any sensible manner, we need to do two things:

1. Create a QScriptValue object that represents the "this" pointer. We do this so that we can call a script function, and pass it the C++ class object as "this" (we'll see this later).
2. Open a script file and execute a "create" function, the contents of which will set up any signal / slot connections we require.

Let's dive into the C++ code, and take a look at the constructor for the above class:

testScriptObject::testScriptObject(  QScriptEngine *pEngine, QObject *parent) 
 : QObject(parent),
 m_pEngine(pEngine)
{
 // create this object in the scripting land:
 m_thisObject = m_pEngine->newQObject(this);
 
}

This is also pretty simple - the only line of any significance is the one where we create "m_thisObject".

Now on to step 2 - running the script file. Let's take a look at the runScript method:

void testScriptObject::runScript(const QString &strAppName)
{
 QFile file(strAppName + ".js");
 
 if (! file.exists())
 {
  QMessageBox::critical(0, "Error", "Could not find program file!");
  return;
 }
 
 if (! file.open(QIODevice::ReadOnly | QIODevice::Text))
 {
  QMessageBox::critical(0, "Error", "Could not open program file!");
  return;
 }
 
 QString strProgram = file.readAll();
 
 // do static check so far of code:
 if (! m_pEngine->canEvaluate(strProgram) )
 {
  QMessageBox::critical(0, "Error", "canEvaluate returned false!");
  return;
 }
 
 // actually do the eval:
 m_pEngine->evaluate(strProgram);
 
 // uncaught exception?
 if (m_pEngine->hasUncaughtException())
 {
  QScriptValue exception = m_pEngine->uncaughtException();
  QMessageBox::critical(0, "Script error", QString("Script threw an uncaught exception: ") + exception.toString());
  return;
 }
 
 QScriptValue createFunc = m_pEngine->evaluate("create");
 
 if (m_pEngine->hasUncaughtException())
 {
  QScriptValue exception = m_pEngine->uncaughtException();
  QMessageBox::critical(0, "Script error", QString("Script threw an uncaught exception while looking for create func: ") + exception.toString());
  return;
 }
 
 if (!createFunc.isFunction())
 {
  QMessageBox::critical(0, "Script Error", "createFunc is not a function!");
 }
 
 createFunc.call(m_thisObject);
 
 if (m_pEngine->hasUncaughtException())
 {
  QScriptValue exception = m_pEngine->uncaughtException();
  QMessageBox::critical(0, "Script error", QString("Script threw an uncaught exception while looking for create func: ") + exception.toString());
  return;
 }
 // now emit our test signal:
 emit signal1();
}

Again, this is all pretty simple stuff. This method does the following:

• Looks for, and opens the script file specified.
• Does a static check of the code (makes sure that it's syntactically correct, but does not ensure that the script will run without error).
• Evaluates the script file.
• Retrieves the function named "create" from the script file.
• Executes this function, passing our previously created "m_thisObject" as the "this" object for the script to use. This function then binds our signals to slots in the script file.
• Finally, we emit our test signal.
  

Finally, let's look at the ECMAScript file I'm using:

// set up the game object - the 'this' object will be an actual QObject 
// derived class passed in from the application.
function create()
{
 // test 1 - call a slot in the class:
 this.slot1();
 
 this.signal1.connect(this, testSlot);
}

// create our own slot:
function testSlot()
{
 this.displayMsg("Testing testing.. 123");
}

...and that's it! The "create" method will first call the "test2" slot in our C++ class, then connect our test signal to a scripted function. When we emit the signal in our C++ class, the "testSlot" function will be called.


This is just a starting point. The more I use the QtScript module, the more I marvel at the possibilities created with this tool. I shall post follow-up articles with more information and techniques as I see fit. In the meantime, go add scripting extension support to your faviourite project. With tools this easy to use, there's no excuse not to!