path: root/src/ivicore/doc/src/examples-qface-ivi-climate.qdoc

/****************************************************************************
**
** Copyright (C) 2019 Luxoft Sweden AB
** Copyright (C) 2018 Pelagicore AG
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the QtIvi module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL-QTAS$
** Commercial License Usage
** Licensees holding valid commercial Qt Automotive Suite licenses may use
** this file in accordance with the commercial license agreement provided
** with the Software or, alternatively, in accordance with the terms
** contained in a written agreement between you and The Qt Company.  For
** licensing terms and conditions see https://www.qt.io/terms-conditions.
** For further information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
\example ivicore/qface-ivi-climate
\brief This Example shows how to use the Qt IVI Generator.
\ingroup qtivicore-examples
\title Qt IVI Generator Climate Example
\image examples_qface_ivi_climate.png

\section1 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:

\list
    \li a shared library with the frontend code
    \li a backend simulator plugin
    \li a demo application that shows the values in the current module
\endlist

\section1 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:

\code
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
}
\endcode

\section2 Walkthrough

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

\code
module Example.IVI.Climate 1.0;
\endcode

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

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

In this case, we define an \c interface named \b 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 \l {QFace IDL syntax}. The last two properties
are special as they use custom types, that are defined after the \c interface definition.

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

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

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

\section2 Comments and Annotations

Compared to the minimal IDL we saw in the previous section, the full
\fileLink {examples/ivicore/qface-ivi-climate/example-ivi-climate.qface}{IDL file} contains a lot of comments
and annotations.

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

\section3 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:

\table
    \header
        \li Annotation
        \li Description
    \row
        \li \code
                @config: {zoned: true}
            \endcode
        \li Specifies that the interface supports different zones.
    \row
        \li \code
                @config: {qml_type: "UiClimateControl"}
            \endcode
        \li Specifies the component name when used from QML.
    \row
        \li \code
                @config: {id: "example.qtivi.ClimateControl/1.0"}
            \endcode
        \li Specifies the ID used to match backend plugins.
    \row
        \li \code
                @config_simulator: { range:[0, 50] }
            \endcode
        \li Specifies a range of valid values for numerical properties.
            \note The \c {range} annotation used here is a shortcut to specify both minimum and
            maximum values.
    \row
        \li
            \code
                @config_simulator: { minimum: 0; maximum: 50 }
            \endcode
        \li Specifies the minimum and maximum values for numerical properties.

    \row
        \li \code
                @config_simulator: { domain: ["cold", "mild", "warm" ] }
            \endcode
        \li Specifies a list of valid values for properties.
    \row
        \li \code
                @config: {interfaceBuilder: "echoInterfaceBuilder"}
            \endcode
        \li Specifies that the plugin should use a custom function to generate the backend
            instances.
\endtable

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:

\table
    \row
        \li
            \code
            Example.IVI.Climate.ClimateControl:
                config_simulator:
                    zones: { left : FrontLeft, right : FrontRight, rear: Rear }
            \endcode
        \li Defines the names for the supported zones.
    \row
        \li
            \code
            Example.IVI.Climate.ClimateControl#recirculationMode:
                config_simulator:
                    default: RecirculationMode.RecirculationOff
            \endcode
        \li Specifies the default value assigned to a property in the simulator backend plugin.
\endtable


\section1 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 \c frontend template, that generates a class derived from
\c {QIviAbstractZonedFeature} including all the specified properties. The generated library uses
the \l {Dynamic Backend System} from QtIviCore, providing an easy way to change the behavior
implementations. For more details, see \l {Backend Simulator Plugin}.

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

\snippet ../../../../examples/ivicore/qface-ivi-climate/frontend/frontend.pro 1

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

However, activating the qmake feature using the \c 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:

\snippet ../../../../examples/ivicore/qface-ivi-climate/frontend/frontend.pro 0

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

\section1 Backend Simulator Plugin

Since the \c frontend library uses the \l {Dynamic Backend System}, we need a corresponding
\c 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 \c backend_simulator template from
the same IDL file as the \c frontend library. The qmake integration works in the same way, but it
uses the \c QFACE_FORMAT variable to tell the \c ivigenerator to use a different generation
template.

\snippet ../../../../examples/ivicore/qface-ivi-climate/backend_simulator/backend_simulator.pro 2

As we want to generate a plugin instead of a plain library, we need to instruct qmake to do so by
adding \c plugin to the \c 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:

\snippet ../../../../examples/ivicore/qface-ivi-climate/backend_simulator/backend_simulator.pro 1

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

Using the \c 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
\l {Climate Control QML Example}.

\section1 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 \c {ClimateModule::registerTypes} and \c {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.

\snippet ../../../../examples/ivicore/qface-ivi-climate/demo/main.qml 0
\dots 0

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 \b 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 \b qtivi sub-folder.

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

\snippet ../../../../examples/ivicore/qface-ivi-climate/backend_simulator/backend_simulator.pro 0

*/