Introduction

This example shows you how you can use the Qt IVI Generator to build a new component. Based on a single QFace IDL file, the example generates:

• a shared library with the frontend code
• a backend simulator plugin
• a demo application that shows the values in the current module

The IDL File

The IDL file used in this example represents a simplified climate control interface that contains a single interface and some enumerated types.

Let's take a look at a minimal version of the same QFace IDL file:

module Example.IVI.Climate 1.0;

interface ClimateControl {
    bool airConditioning;
    int fanSpeedLevel;
    RecirculationMode recirculationMode;
    AirflowDirection airflowDirections;
}

enum RecirculationMode {
    RecirculationOff = 0x0,
    RecirculationOn = 0x1,
    AutoRecirculation = 0x2
}

flag AirflowDirection {
    Windshield = 1,
    Dashboard = 2,
    Floor = 4
}

Walkthrough

First, we need to define which module we want to describe. The module acts as a namespace, because the IDL file can contain multiple interfaces.

module Example.IVI.Climate 1.0;

The most important part of the module is its interface definition.

interface ClimateControl {
    bool airConditioning;
    int fanSpeedLevel;
    RecirculationMode recirculationMode;
    AirflowDirection airflowDirections;
}

In this case, we define an interface named ClimateControl consisting of a few properties it should offer. Each property definition must contain at least a type and a name. Most of the basic types are built-in and can be found in the QFace IDL syntax. The last two properties are special as they use custom types, that are defined after the interface definition.

enum RecirculationMode {
    RecirculationOff = 0x0,
    RecirculationOn = 0x1,
    AutoRecirculation = 0x2
}

flag AirflowDirection {
    Windshield = 1,
    Dashboard = 2,
    Floor = 4
}

The first definition is an enum with all the values it supports, including the numeric value of each individual item. The second definition is similar, but using the flag type.

Comments and Annotations

Compared to the minimal IDL we saw in the previous section, the full IDL file contains a lot of comments and annotations.

Comments starting with /** define documentation statements and can be converted into documentation markup like QDoc or Doxygen, by the generation template.

Annotations

Annotations are used to add additional information to the IDL statements. They are YAML fragments that provide a key-value store. The generation template defines the supported annotations.

Here's an overview of all the annotations used in this example and what they do:

@config: {zoned: true}

@config: {qml_type: "UiClimateControl"}

@config: {id: "example.qtivi.ClimateControl/1.0"}

@config_simulator: { range:[0, 50] }

@config_simulator: { minimum: 0; maximum: 50 }

@config_simulator: { domain: ["cold", "mild", "warm" ] }

@config: {interfaceBuilder: "echoInterfaceBuilder"}

In addition to the IDL file, a YAML file with the same basename is used to add extra configurations. These configurations may also be added directly into the IDL file, but we choose to keep them separate for readability.

Some of these extra configurations are highlighted below:

Example.IVI.Climate.ClimateControl:
    config_simulator:
        zones: { left : FrontLeft, right : FrontRight, rear: Rear }

Example.IVI.Climate.ClimateControl#recirculationMode:
    config_simulator:
        default: RecirculationMode.RecirculationOff

Frontend Library

Now we want to use the IVI Generator to generate a shared library that contains a C++ implementation of our module and its interface.

In this case, we use the frontend template, that generates a class derived from QIviAbstractZonedFeature including all the specified properties. The generated library uses the Dynamic Backend System from QtIviCore, providing an easy way to change the behavior implementations. For more details, see Backend Simulator Plugin.

To call the autogenerator for our shared library, the qmake project file needs to use the ivigenerator qmake feature. The snippet below shows how to do this:

CONFIG += ivigenerator
QFACE_SOURCES = ../example-ivi-climate.qface

By adding ivigenerator to the CONFIG variable, the ivigenerator feature file is loaded and interprets the QFACE_SOURCES variable just like the SOURCES variable in normal qmake projects.

However, activating the qmake feature using the CONFIG variable has one disadvantage: it doesn't report any errors if this feature is not available. But, you can use the following additional code to report errors:

QT_FOR_CONFIG += ivicore
!qtConfig(ivigenerator): error("No ivigenerator available")

The other part of the project file is a normal library setup which should work on Linux, macOS, and Windows.

Backend Simulator Plugin

Since the frontend library uses the Dynamic Backend System, we need a corresponding backend plugin, for the library to provide some functionality. To generate a mock version of the backend plugin called "Simulator Backend", you can use the backend_simulator template from the same IDL file as the frontend library. The qmake integration works in the same way, but it uses the QFACE_FORMAT variable to tell the ivigenerator to use a different generation template.

CONFIG += ivigenerator plugin
QFACE_FORMAT = backend_simulator
QFACE_SOURCES = ../example-ivi-climate.qface
PLUGIN_TYPE = qtivi
PLUGIN_CLASS_NAME = ClimateSimulatorPlugin

As we want to generate a plugin instead of a plain library, we need to instruct qmake to do so by adding plugin to the CONFIG variable. For the plugin to compile correctly it needs to get the backend interface header from the previously created library. However, this header is not part of our source tree but the build tree, because it is also generated. We provide this header by adding it to the include path using the following construct:

INCLUDEPATH += $$OUT_PWD/../frontend

The backend_simulator template makes use of the @config_simulator annotations explained above. This means that the generated backend provides the default values defined in the annotations and checks the boundaries of new values using the minimum/maximum or range annotations.

Using the zones annotations, the generated backend provides individual values for every zone and communicates the available zones to the frontend library. For more information, see the Climate Control QML Example.

Demo Application

The demo application presents a simple QML interface with all the properties of the generated interface.

Since we do not provide a QML plugin, the application needs to link to the generated frontend library and call the ClimateModule::registerTypes and ClimateModule::registerQmlTypes methods that are generated in the module singleton to register all autogenerated interfaces and types with the QML engine.

In our QML application, we still need to import the module using the same module URI used in the IDL file. Afterwards, the interface can be instantiated like a regular QML item.

import Example.IVI.Climate 1.0

Window {

    visible: true
    width: 640
    height: 480
    title: qsTr("QtIVI Climate")

    UiClimateControl {
        id: climateCtrl
    }

    Column {
        anchors.fill: parent
        anchors.margins: 5

        Text {
            text: "Air Conditioning: " + climateCtrl.airConditioning
        }
...

Our application doesn't know about our backend plugin, so, we need to put this plugin in the folder where our application looks for plugins. By default, Qt looks in the plugins folder within its installation directory or in the application's current working directory. For QtIvi plugins to be found, they need to be placed within a qtivi sub-folder.

To make sure this is done automatically, we add the following line to our backend project file:

DESTDIR = ../qtivi

Example project @ code.qt.io