Moving from QSA to Qt Script

Making QObjects Accessible from Scripts

There are two different ways of making QObjects accessible from scripts in QSA. The first method is via the QSInterpreter::addTransientObject() and QSProject::addObject() functions. In this case objects are added to the global namespace of the interpreter using their object names as the names of the variables.

 QPushButton *button = new QPushButton();
 button->setObjectName("button");
 interpreter->addTransientObject(button);

The code above adds the button to the global namespace under the name "button". One obvious limitation here is that there is potential for either unnamed QObjects or objects whose names conflict. Qt Script provides a more flexible way of adding QObjects to the scripting environment.

 QPushButton *button = new QPushButton();
 QScriptValue scriptButton = engine.newQObject(button);
 engine.globalObject().setProperty("button", scriptButton);

In the code above we create a QPushButton and wrap it in a script value using the function, QScriptEngine::newQObject(). This gives us a script value that we put into the global object using the name "button". The concept of objects and properties discussed above is quite visible here in the public C++ API as well. We have no dependency on the object's name and we can also resolve name conflicts more gracefully. Here, we operate directly on QScriptValue objects. This is the actual object that is being passed around inside the script engine, so we actually have low-level access to the internal script data structures, far beyond that which is possible in QSA. Properties, signals and slots of the QObject are accessible to the scripter in Qt Script, just like in QSA.

The other way to expose QObjects in QSA was to create a QSObjectFactory that made it possible to instantiate QObjects from scripts.

Below is listed some code from the filter example in the QSA package.

 ModuleFactory::ModuleFactory()
 {
     registerClass( "ImageSource", &ImgSource::staticMetaObject);
     ...
 }

 QObject *ModuleFactory::create( const QString &type,
                                 const QVariantList &,
                                 QObject * )
 {
     if ( type == "ImageSource" )
         return new ImgSource();
     ...
 }

 ...

 interpreter.addObjectFactory(new ModuleFactory());

The equivalent in Qt Script is written in much the same way as constructors are written in scripts. We register a callback C++ function under the name "ImageSource" in the global namespace and return the QObject from this function:

 QScriptValue construct_QPushButton(QScriptContext *, QScriptEngine *engine) {
     return engine->newQObject(new QPushButton());
 }

 ...

 QScriptValue constructor = engine.newFunction(construct_QPushButton);
 QScriptValue value =
     engine.newQMetaObject(&QPushButton::staticMetaObject,
                           constructor);
 engine.globalObject().setProperty("QPushButton", value);

In the Qt Script case we use the same approach that we use to expose a QObject, namely via QScriptEngine::newQObject(). This function also has the benefit that it is possible to specify if the QObject should expose properties and slots of its base class. It is also possible to specify custom ownership rules.

The reader might question why we don't add the constructor function directly into the namespace, but create a meta-object script value for it in addition. The plain function would certainly be good enough, but by creating a QMetaObject based constructor we get the enums on QPushButton for free in the QPushButton function object. Exposing enums in QSA is rather painful in comparison.

If we want to add more "static" data to the QPushButton type in Qt Script, we're free to add properties, similar to how we did for the script. It is also possible to add custom functions to a Qt Script QPushButton instance by setting more properties on it, such as making the setText() C++ function available. It is also possible to acheive this by installing a custom prototype, and be memory efficient, as discussed in the script example above.