IviSimulator QML Type

The global object for parsing simulation data inside a QIviSimulationEngine. More...

Import Statement: import

Properties

Methods

Detailed Description

The IviSimulator global object provides access to the simulation data of a QIviSimulationEngine and provides helper functions for parsing and checking boundaries.

Note: This object is only available inside a QIviSimulationEngine and cannot be accessed outside of it.

Data Format

The IviSimulator expects its data already in a parsed form. Usually this is done by the QIviSimulationEngine::loadSimulationData() function, which expects the file to be in the JSON format.

Interfaces

Because a simulation QML file can use multiple interfaces, the simulation data supports multiple data sets as well. These are identified by the interface name in a reverse DNS notation:

{
  "QIviClimateControl": {
    ...
  },
  "org.qt-project.QIviWindowControl": {
    ...
  }
}

The findData() method can be used to find the data for a specific interface.

Properties

The settings (e.g. boundaries) for every property of the interface are defined inside a data set.

{
  "QIviClimateControl": {
    "airConditioningEnabled": {
      "default": true
    },
    "steeringWheelHeater": {
      "minimum": 0,
      "default": 0
    },
    "fanSpeed": {
      "range": [0, 5]
    }
  }
}

For the interface named QIviClimateControl, there are settings defined for the properties airConditioningEnabled, steeringWheelHeater and fanSpeed.

The settings object can store multiple constraints which are called domains. The following domains are currently supported:

default Holds the default value the property should have when the frontend is connected.

minimum Every newly set value needs to be bigger than this value

maximum Every newly set value needs to be smaller than this value

range Every newly set value needs to be between the two values in this list

Note: The values in range always override the minimum and maximum domains

domain Every newly set value needs to be part of this list

unsupported Changing the property is not possible and will show an "unsupported" error message

The value for a specific domain can be loaded using the parseDomainValue() function or using defaultValue() when only the default domain is of interest.

Structures and Enums

As JSON is not typesafe, structures and enums need to be stored in a special format. An enum can be stored like this:

{
  "QIviClimateControl": {
    "recirculationMode": {
      "default": {
        "type": "enum",
        "value": "QtIviVehicleFunctionsModule::RecirculationOff"
      }
    }
  }
}

Structures can be stored in a similar fashion using the name of the structure as type:

{
  "AddressBook": {
    "contactList": {
      "default": [
        {
          "type": "Contact",
          "value": [
            "foo",
            23,
            true
          ]
        },
        {
          "type": "Contact",
          "value": [
            "bar",
            12,
            false
          ]
        }
      ]
    }
  },
  }
}

To correctly initialize the structure with these values, the structure needs to provide a constructor taking a QVariant as argument. For the given contact example this constructor can look like this:

Contact::Contact(const QVariant &variant)
    : Contact()
{
    QVariant value = qtivi_convertFromJSON(variant);
    // First try to convert the values to a Map or a List
    // This is needed as it could also store a QStringList or a Hash
    if (value.canConvert(QVariant::Map))
        value.convert(QVariant::Map);
    if (value.canConvert(QVariant::List))
        value.convert(QVariant::List);

    if (value.type() == QVariant::Map) {
        QVariantMap map = value.toMap();
        if (map.contains(QStringLiteral("name")))
            d->m_name = map.value(QStringLiteral("name")).value<QString>();
        if (map.contains(QStringLiteral("age")))
            d->m_age = map.value(QStringLiteral("age")).value<int>();
        if (map.contains(QStringLiteral("isMarried")))
            d->m_isMarried = map.value(QStringLiteral("isMarried")).value<bool>();
    } else if (value.type() == QVariant::List) {
        QVariantList values = value.toList();
        d->m_name = values.value(0).value<QString>();
        d->m_age = values.value(1).value<int>();
        d->m_isMarried = values.value(2).value<bool>();
    }
}

Zones

For zoned interfaces, the supported zones are usually stored as list in the zones property:

{
  "QIviClimateControl": {
    "zones": [
      "FrontLeft",
      "FrontRight",
      "Rear"
    ]
  }
}

For every supported domain it is also possible to provide zone specific values e.g.:

{
  "QIviClimateControl": {
    "targetTemperature": {
      "maximum": 30.0,
      "default": {
        "FrontLeft": 21.0,
        "FrontRight": 22.5,
        "=": 0.0
      }
    }
  }
}

This defines that the maximum value for the targetTemperature property is 30, the default value is zone specific and is 21.5 for the FrontLeft zone, while it is 22.5 for the FrontRight zone. The unzoned targetTemperature temperature is initialized with 0.0.

Property Documentation

simulationData : object

Provides the simulation data parsed in QIviSimulationEngine::loadSimulationData()


Method Documentation

checkSettings(data, var value, string zone)

Searches for all boundary settings in data for the given zone and returns whether the provided value meets this constraint.

To show meaningful error messages when the value is not within the boundaries, the constraint() function can be used.

See also constraint().


constraint(data, string zone)

Searches for all boundary settings in data for the given zone and returns the constraint (which is enforced for newly set values) in a human readable form.

This is useful for error messages in connection with checkSettings().

See also checkSettings().


defaultValue(data, string zone)

Provides the default value stored in data for the given zone. If zone is undefined or the data doesn't provide a default value for the given zone, it returns the unzoned default value if available.

This is just a convenience function calling parseDomainValue() with the domain default.


findData(data, string interface)

Searches for the key interface within data and returns the stored values. Returns undefined if no data was found for this interface.

If interface is a reverse NDS name, it first searches for the full string. If no key was found, it starts to search again with a reduced name until it finds a key with this name.

E.g. for the interface org.qt-project.ClimateControl it searches for keys in the following order:

  1. org.qt-project.ClimateControl
  2. qt-project.ClimateControl
  3. ClimateControl

initializeDefault(data, QObject*object)

Applies the default values read from data to object.

If object supports zoneing, the default value is only applied to the correct zone.


parseDomainValue(data, string domain, string zone)

Search for the domain in data for the given zone. If zone is undefined or the data doesn't provide this domain for the given zone, it returns the unzoned domain value if available.


© 2020 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.