Detailed Description

This class is an extended QQmlApplicationEngine which can be used to load QML files. It is made especially for simulation backends to script the behavior of a simulation backend from QML. An overview of the functionality is also provided here.

In contrast to a normal QQmlEngine the QIviSimulationEngine provides an extra template function called registerSimulationInstance(). Using this function it is possible to register an class instance as a QML type. Inside a QML file this QML type can be used to define the behavior for function calls, update properties or emit signals.

Registering an instance

Any instance of a class derived from QObject can be registered to the QIviSimulationEngine by calling the registerSimulationInstance function. Similar to qmlRegisterTypes, the provided uri, version and name is used for importing the type from within QML.

class MyClass : public QObject
{
    Q_OBJECT
    Q_PROPERTY(int currentTemperature READ currentTemperature WRITE setCurrentTemperature NOTIFY currentTemperatureChanged)

    ...
}

An instance of this simple class can be registered like this:

QIviSimulationEngine engine;
MyClass myClass;
engine.registerSimulationInstance<MyClass>(&myClass, "Test", 1, 0, "MyClass");
engine.loadSimulation("simulation.qml")

The registered instance has the same constraints as other C++ classes exposed to QML and needs to use Q_PROPERTY, Q_INVOKABLE or slots to make the functionality available to QML.

Using the type from QML

Once an instance is registered to the engine, the type can be used like any other QML element in a declarative form:

import QtQuick 2.0
import Test 1.0

Item {
    MyClass {
        id: myClass

        Component.onCompleted: currentTemperature = 10;
    }

    Timer {
        running: true
        repeat: true
        interval: 1000
        onTriggered: myClass.currentTemperature++;
    }
}

This QML file will initialize the currentTemperature of myClass with a value of 10 and increase it every second.

In the same way values can be updated from the C++ side and the QML side can react to the change. E.g. the following QML prints the currentTemperature whenever it changed:

import QtQuick 2.0
import Test 1.0

MyClass {
    onCurrentTemperatureChanged: print(currentTemperature)
}

The slot will be called once the myClass variable is updated:

QIviSimulationEngine engine;
MyClass myClass;
engine.registerSimulationInstance<MyClass>(&myClass, "Test", 1, 0, "MyClass");
engine.loadSimulation("simulation.qml")
...
myClass.setCurrentTemperature(100);

Forwarding calls from the instance to the engine

Providing the behavior for invokable functions in QML can be done as well, but for this the exposed class needs to be extended.

E.g. by adding the following line to the setCurrentTemperature setter:

void MyClass::setCurrentTemperature(int currentTemperature)
{
    QIVI_SIMULATION_TRY_CALL(MyClass, "setCurrentTemperature", void, currentTemperature);

    if (m_currentTemperature == currentTemperature)
        return;
    m_currentTemperature = currentTemperature;
    emit currentTemperatureChanged(m_currentTemperature);
}

Calling the setCurrentTemperature() function will now try to forward the call to the QML instance if a function matching the signature is defined in QML and when successful, use its returned value and skip the execution of the original C++ function.

By using the following QML snippet the execution of the C++ setter is skipped and only an error is emitted on the console:

import QtQuick 2.0
import Test 1.0

MyClass {
    function setCurrentTemperature(temperature) {
        print("Updating the temperature is not possible")
    }
}

Reusing existing behavior in the instance

Replacing the C++ functionality with a QML behavior is not always what is desired. Because of this, it is also possible to call the original C++ behavior from QML. For this the original C++ function needs to be a Q_INVOKABLE or a slot and the functionality works like function overriding in C++. In the C++ world the functionality of the overridden function can be accessed by calling <BaseClass>::<function>. In the exposed QML type this is possible by calling the function in the Base object.

import QtQuick 2.0
import Test 1.0

MyClass {
    function setCurrentTemperature(temperature) {
        print("Updating the temperature: " + temperature )
        Base.setCurrentTemperature(temperature)
    }
}

This QML code overrides the setCurrentTemperature behavior in QML and prints an debug message for the new value. The original C++ behavior is called by using Base.setCurrentTemperature(temperature).

Multiple QML instances

The registered instance is exposed as a normal QML type. This makes it possible to have multiple declarations in QML and by that have multiple QML instances linked to the same C++ instance. Updating and reacting to property changes and signal emissions is possible in all instances, but should be used with care as this can result in property update loops and other issues.

Forwarding C++ function calls to QML is limited. Every call is forwarded to only one QML instance as the return value is used from this call. If multiple QML instances define the same method, the C++ call is always forwarded to the first registered QML instance.

Runtime overriding

Every QIviSimulationEngine can take an extra identifier which can be used to override the simulation QML file or the simulation data file at runtime. The environment variables need to be in the following format:

QTIVI_SIMULATION_OVERRIDE=<identifier>=<file>[;<identifier>=<file>]
QTIVI_SIMULATION_DATA_OVERRIDE=<identifier>=<file>[;<identifier>=<file>]