Making Applications Scriptable

Defining Classes in a Prototype-Based Universe

In QtScript, a class is not defined explicitly; there is no class keyword. Instead, you define a new class in two steps:

1. Define a constructor function that will initialize new objects.
2. Set up a prototype object that defines the class interface, and assign this object to the public prototype property of the constructor function.

With this arrangement, the constructor's public prototype property will automatically be set as the prototype of objects created by applying the new operator to your constructor function; e.g., the prototype of an object created by new Foo() will be the value of Foo.prototype.

Functions that don't operate on the this object ("static" methods) are typically stored as properties of the constructor function, not as properties of the prototype object. The same is true for constants, such as enum values.

The following code defines a simple constructor function for a class called Person:

 function Person(name)
 {
   this.name = name;
 }

Next, you want to set up Person.prototype as your prototype object; i.e., define the interface that should be common to all Person objects. QtScript automatically creates a default prototype object (by the expression new Object()) for every script function; you can add properties to this object, or you can assign your own custom object. (Generally speaking, any QtScript object can act as prototype for any other object.)

Here's an example of how you might want to override the toString() function that Person.prototype inherits from Object.prototype, to give your Person objects a more appropriate string representation:

 Person.prototype.toString = function() { return "Person(name: " + this.name + ")"; }

This resembles the process of reimplementing a virtual function in C++. Henceforth, when the property named toString is looked up in a Person object, it will be resolved in Person.prototype, not in Object.prototype as before:

 var p1 = new Person("John Doe");
 var p2 = new Person("G.I. Jane");
 print(p1); // "Person(name: John Doe)"
 print(p2); // "Person(name: G.I. Jane)"

There are also some other interesting things we can learn about a Person object:

 print(p1.hasOwnProperty('name')); // 'name' is an instance variable, so this returns true
 print(p1.hasOwnProperty('toString')); // returns false; inherited from prototype
 print(p1 instanceof Person); // true
 print(p1 instanceof Object); // true

The hasOwnProperty() function is not inherited from Person.prototype, but rather from Object.prototype, which is the prototype of Person.prototype itself; i.e., the prototype chain of Person objects is Person.prototype followed by Object.prototype. This prototype chain establishes a class hierarchy, as demonstrated by applying the instanceof operator; instanceof checks if the value of the public prototype property of the constructor function on the right-hand side is reached by following the prototype chain of the object on the left-hand side.

When defining subclasses, there's a general pattern you can use. The following example shows how one can create a subclass of Person called Employee:

 function Employee(name, salary)
 {
   Person.call(this, name); // call base constructor

   this.salary = salary;
 }

 // set the prototype to be an instance of the base class
 Employee.prototype = new Person();

 // initialize prototype
 Employee.prototype.toString = function() { ... }

Again, you can use the instanceof to verify that the class relationship between Employee and Person has been correctly established:

 var e = new Employee("Johnny Bravo", 5000000);
 print(e instanceof Employee); // true
 print(e instanceof Person);   // true
 print(e instanceof Object);   // true
 print(e instanceof Array);    // false

This shows that the prototype chain of Employee objects is the same as that of Person objects, but with Employee.prototype added to the front of the chain.

 QScriptValue Person_ctor(QScriptContext *context, QScriptEngine *engine)
 {
   QString name = context->argument(0).toString();
   context->thisObject().setProperty("name", name);
   return engine->undefinedValue();
 }

 QScriptValue Person_prototype_toString(QScriptContext *context, QScriptEngine *engine)
 {
   QString name = context->thisObject().property("name").toString();
   QString result = QString::fromLatin1("Person(name: %0)").arg(name);
   return result;
 }

 QScriptEngine engine;
 QScriptValue ctor = engine.newFunction(Person_ctor);
 ctor.property("prototype").setProperty("toString", engine.newFunction(Person_prototype_toString));
 QScriptValue global = engine.globalObject();
 global.setProperty("Person", ctor);

 QScriptValue Employee_ctor(QScriptContext *context, QScriptEngine *engine)
 {
   QScriptValue super = context->callee().property("prototype").property("constructor");
   super.call(context->thisObject(), QScriptValueList() << context->argument(0));
   context->thisObject().setProperty("salary", context->argument(1));
   return engine->undefinedValue();
 }

 QScriptValue empCtor = engine.newFunction(Employee_ctor);
 empCtor.setProperty("prototype", global.property("Person").construct());
 global.setProperty("Employee", empCtor);

 Q_DECLARE_METATYPE(QPointF)
 Q_DECLARE_METATYPE(QPointF*)

 QScriptValue QPointF_prototype_x(QScriptContext *context, QScriptEngine *engine)
 {
   // Since the point is not to be modified, it's OK to cast to a value here
     QPointF point = qscriptvalue_cast<QPointF>(context->thisObject());
     return point.x();
 }

 QScriptValue QPointF_prototype_setX(QScriptContext *context, QScriptEngine *engine)
 {
     // Cast to a pointer to be able to modify the underlying C++ value
     QPointF *point = qscriptvalue_cast<QPointF*>(context->thisObject());
     if (!point)
         return context->throwError(QScriptContext::TypeError, "QPointF.prototype.setX: this object is not a QPointF");
     point->setX(context->argument(0).toNumber());
     return engine->undefinedValue();
 }

 QScriptValue QPoint_ctor(QScriptContext *context, QScriptEngine *engine)
 {
     int x = context->argument(0).toInt32();
     int y = context->argument(1).toInt32();
     return engine->toScriptValue(QPoint(x, y));
 }

 ...

 engine.globalObject().setProperty("QPoint", engine.newFunction(QPoint_ctor));

 typedef QSharedPointer<QXmlStreamReader> XmlStreamReaderPointer;

 Q_DECLARE_METATYPE(XmlStreamReaderPointer)

 QScriptValue constructXmlStreamReader(QScriptContext *context, QScriptEngine *engine)
 {
     if (!context->isCalledAsConstructor())
         return context->throwError(QScriptContext::SyntaxError, "please use the 'new' operator");

     QIODevice *device = qobject_cast<QIODevice*>(context->argument(0).toQObject());
     if (!device)
         return context->throwError(QScriptContext::TypeError, "please supply a QIODevice as first argument");

     // Create the C++ object
     QXmlStreamReader *reader = new QXmlStreamReader(device);

     XmlStreamReaderPointer pointer(reader);

     // store the shared pointer in the script object that we are constructing
     return engine->newVariant(context->thisObject(), qVariantFromValue(pointer));
 }

 QScriptValue xmlStreamReader_atEnd(QScriptContext *context, QScriptEngine *)
 {
     XmlStreamReaderPointer reader = qscriptvalue_cast<XmlStreamReaderPointer>(context->thisObject());
     if (!reader)
         return context->throwError(QScriptContext::TypeError, "this object is not an XmlStreamReader");
     return reader->atEnd();
 }

     QScriptEngine engine;
     QScriptValue xmlStreamReaderProto = engine.newObject();
     xmlStreamReaderProto.setProperty("atEnd", engine.newFunction(xmlStreamReader_atEnd));

     QScriptValue xmlStreamReaderCtor = engine.newFunction(constructXmlStreamReader, xmlStreamReaderProto);
     engine.globalObject().setProperty("XmlStreamReader", xmlStreamReaderCtor);

 QScriptValue myPrintFunction(QScriptContext *context, QScriptEngine *engine)
 {
     QString result;
     for (int i = 0; i < context->argumentCount(); ++i) {
         if (i > 0)
             result.append(" ");
         result.append(context->argument(i).toString());
     }

     QScriptValue calleeData = context->callee().data();
     QPlainTextEdit *edit = qobject_cast<QPlainTextEdit*>(calleeData.toQObject());
     edit->appendPlainText(result);

     return engine->undefinedValue();
 }

 int main(int argc, char **argv)
 {
     QApplication app(argc, argv);

     QScriptEngine eng;
     QPlainTextEdit edit;

     QScriptValue fun = eng.newFunction(myPrintFunction);
     fun.setData(eng.newQObject(&edit));
     eng.globalObject().setProperty("print", fun);

     eng.evaluate("print('hello', 'world')");

     edit.show();
     return app.exec();
 }

 myButton.text = qsTr("Hello world!");

 myButton.text = qsTranslate("MyAwesomeScript", "Hello world!");

 FriendlyConversation.prototype.greeting = function(type)
 {
     if (FriendlyConversation['greeting_strings'] == undefined) {
         FriendlyConversation['greeting_strings'] = [
             QT_TR_NOOP("Hello"),
             QT_TR_NOOP("Goodbye")
         ];
     }
     return qsTr(FriendlyConversation.greeting_strings[type]);
 }

 FriendlyConversation.prototype.greeting = function(type)
 {
     if (FriendlyConversation['greeting_strings'] == undefined) {
         FriendlyConversation['greeting_strings'] = [
             QT_TRANSLATE_NOOP("FriendlyConversation", "Hello"),
             QT_TRANSLATE_NOOP("FriendlyConversation", "Goodbye")
         ];
     }
     return qsTranslate("FriendlyConversation", FriendlyConversation.greeting_strings[type]);
 }

 FileCopier.prototype.showProgress = function(done, total, currentFileName)
 {
     this.label.text = qsTr("%1 of %2 files copied.\nCopying: %3")
                       .arg(done)
                       .arg(total)
                       .arg(currentFileName));
 }

 lupdate myscript.qs -ts myscript_la.ts

 lupdate -extensions qs scripts/ -ts scripts_la.ts

 lrelease myscript_la.ts