diff options
Diffstat (limited to 'src/ivicore')
39 files changed, 3335 insertions, 45 deletions
diff --git a/src/ivicore/doc/QtIviDoc b/src/ivicore/doc/QtIviDoc new file mode 100644 index 0000000..aa17a4c --- /dev/null +++ b/src/ivicore/doc/QtIviDoc @@ -0,0 +1,3 @@ +#include <QtIviCore/QtIviCore> +#include <QtIviVehicleFunctions/QtIviVehicleFunctions> +#include <QtIviMedia/QtIviMedia> diff --git a/src/ivicore/doc/images/backendtypes.jpg b/src/ivicore/doc/images/backendtypes.jpg Binary files differnew file mode 100644 index 0000000..b06681d --- /dev/null +++ b/src/ivicore/doc/images/backendtypes.jpg diff --git a/src/ivicore/doc/images/feature_backend.jpg b/src/ivicore/doc/images/feature_backend.jpg Binary files differnew file mode 100644 index 0000000..98e3fca --- /dev/null +++ b/src/ivicore/doc/images/feature_backend.jpg diff --git a/src/ivicore/doc/images/qtivi-codesample.png b/src/ivicore/doc/images/qtivi-codesample.png Binary files differnew file mode 100644 index 0000000..cfecb6a --- /dev/null +++ b/src/ivicore/doc/images/qtivi-codesample.png diff --git a/src/ivicore/doc/online/qtivi.qdocconf b/src/ivicore/doc/online/qtivi.qdocconf new file mode 100644 index 0000000..9cc98ed --- /dev/null +++ b/src/ivicore/doc/online/qtivi.qdocconf @@ -0,0 +1,10 @@ +include($QT_INSTALL_DOCS/global/qt-module-defaults-online.qdocconf) + +# Add an .html file with sidebar content, used in the online style +# HTML.stylesheets += style/qt5-sidebar.html + +# override defaults for Qt module documentation +HTML.nosubdirs = "false" +HTML.outputsubdir = "qtivi" + +include(../qtivi-project.qdocconf) diff --git a/src/ivicore/doc/qtivi-project.qdocconf b/src/ivicore/doc/qtivi-project.qdocconf new file mode 100644 index 0000000..3e84cdc --- /dev/null +++ b/src/ivicore/doc/qtivi-project.qdocconf @@ -0,0 +1,68 @@ +project = QtIvi +description = QtIvi Reference Documentation +version = $QT_VERSION +url = http://doc.qt.io/QtIVI + +moduleheader = QtIviDoc +includepaths = -I . + +headerdirs += . \ + .. \ + ../../imports/core + +sourcedirs += . \ + .. \ + ../../imports/core +imagedirs += images +exampledirs += ../../../examples +examples.fileextensions += *.qface *.yaml + +include(../../ivivehiclefunctions/doc/qtivivehiclefunctions.qdocconf) +include(../../ivimedia/doc/qtivimedia.qdocconf) + +# include the backend plugins documentation +include(../../plugins/ivimedia/doc/qtivimedia_plugins.qdocconf) +include(../../plugins/ivivehiclefunctions/doc/qtivivehiclefunctions_plugins.qdocconf) + +# include extra image to qhp (referred to in the generated examples-manifest.xml) +HTML.extraimages += images/qtivi-codesample.png +qhp.QtIvi.extraFiles += images/qtivi-codesample.png + +qhp.projects = QtIvi + +qhp.QtIvi.file = qtivi.qhp +qhp.QtIvi.namespace = org.qt-project.qtivi.$QT_VERSION_TAG +qhp.QtIvi.virtualFolder = qtivi +qhp.QtIvi.indexTitle = Qt IVI +qhp.QtIvi.indexRoot = + +qhp.QtIvi.filterAttributes = qtivi $QT_VERSION qtrefdoc +qhp.QtIvi.customFilters.Qt.name = QtIvi $QT_VERSION +qhp.QtIvi.customFilters.Qt.filterAttributes = qtivi $QT_VERSION + +qhp.QtIvi.subprojects = classes qml examples + +qhp.QtIvi.subprojects.classes.title = C++ Classes +qhp.QtIvi.subprojects.classes.indexTitle = Qt IVI C++ Classes +qhp.QtIvi.subprojects.classes.selectors = class fake:headerfile +qhp.QtIvi.subprojects.classes.sortPages = true + +qhp.QtIvi.subprojects.qml.title = QML Types +qhp.QtIvi.subprojects.qml.indexTitle = Qt IVI QML Types +qhp.QtIvi.subprojects.qml.selectors = qmlclass +qhp.QtIvi.subprojects.qml.sortPages = true + +qhp.QtIvi.subprojects.examples.title = Examples +qhp.QtIvi.subprojects.examples.indexTitle = Qt IVI Examples +qhp.QtIvi.subprojects.examples.selectors = fake:example +qhp.QtIvi.subprojects.examples.sortPages = true + +tagfile = qtivi.tags + +depends += qtcore qtwidgets qtdoc qtquick qtqml qtautomotivesuite qtsimulator qtremoteobjects + +navigation.homepage = "Qt Automotive Suite" +navigation.landingpage = "Qt IVI" +navigation.cppclassespage = "Qt IVI C++ Classes" +navigation.qmltypespage = "Qt IVI QML Types" +buildversion = "Qt IVI $QT_VERSION" diff --git a/src/ivicore/doc/qtivi.qdocconf b/src/ivicore/doc/qtivi.qdocconf new file mode 100644 index 0000000..1a65d24 --- /dev/null +++ b/src/ivicore/doc/qtivi.qdocconf @@ -0,0 +1,2 @@ +include($QT_INSTALL_DOCS/global/qt-module-defaults-offline.qdocconf) +include(qtivi-project.qdocconf) diff --git a/src/ivicore/doc/qtivicore.qdocconf b/src/ivicore/doc/qtivicore.qdocconf deleted file mode 100644 index 4d84660..0000000 --- a/src/ivicore/doc/qtivicore.qdocconf +++ /dev/null @@ -1,11 +0,0 @@ -headerdirs += .. \ - ../../imports/core - -sourcedirs += .. \ - ../../imports/core - -imagedirs += images - -macro.qmlqtiviproperty = "\\qmlpropertygroup \2 \n\\qmlproperty bool \2.available\n \\qmlproperty \1 \2.maximumValue\n \\qmlproperty \1 \2.minimumValue\n \\qmlproperty list<\1> \2.availableValues\n \\qmlproperty \1 \2.value\n \\include src/qmlqtiviproperty.qdocinc" -macro.qmlqtivipropertyBool = "\\qmlpropertygroup \1 \n\\qmlproperty bool \1.available\n \\qmlproperty bool \1.value\n \\include src/qmlqtiviproperty.qdocinc" -macro.qmlqtivipropertyEnum = "\\qmlpropertygroup \1 \n\\qmlproperty bool \1.available\n \\qmlproperty list<enumeration> \1.availableValues\n \\qmlproperty enumeration \1.value\n \\include src/qmlqtiviproperty.qdocinc" diff --git a/src/ivicore/doc/src/JINJA_LICENSE b/src/ivicore/doc/src/JINJA_LICENSE new file mode 100644 index 0000000..31bf900 --- /dev/null +++ b/src/ivicore/doc/src/JINJA_LICENSE @@ -0,0 +1,31 @@ +Copyright (c) 2009 by the Jinja Team, see AUTHORS for more details. + +Some rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + + * Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + + * Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials provided + with the distribution. + + * The names of the contributors may not be used to endorse or + promote products derived from this software without specific + prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/src/ivicore/doc/src/attribute-system.qdoc b/src/ivicore/doc/src/attribute-system.qdoc new file mode 100644 index 0000000..f0aff4f --- /dev/null +++ b/src/ivicore/doc/src/attribute-system.qdoc @@ -0,0 +1,232 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page attribute-system.html +\title The Qt IVI Attribute System +\keyword AttributeSystem +\previouspage Dynamic Backend System +\nextpage Models +\contentspage Concepts + +\note This page is deprecated and is only left here for reference + +In the IVI world a system often needs to support a lot of different car configurations. These +configurations could vary in display sizes and resolutions are used or the actual hardware changes +to a e.g. less powerful cpu and less memory to software configurations where certain features are +disabled, as well as simply disabling features via software. + +Most of the configurations are actually hardware related, while the ECU and UI software still stay +the same. Something along these lines would be an example on what configurations an IVI system may +need to support: + +\section1 Example Configurations + +\section2 Low + +\list +\li Display Resolution: 1280x768 +\li CPU: Single-Core 1 GB memory +\li Other Hardware: +\li 2 Zone Climate Control +\li Air conditioning system +\li Bluetooth Media Streaming +\endlist + +\section2 Medium + +\list +\li Display Resolution: 1920x1080 +\li CPU: Dual-Core 1 GB memory +\li Other Hardware: +\li 3 Zone Climate Control +\li Electric Window Opener +\li Automatic Air conditioning system +\li Bluetooth Media Streaming +\li Wifi (client) +\endlist + +\section2 High + +\list +\li Display Resolution: 1920x1080 +\li CPU: Quad-Core 2 GB memory +\li Other Hardware: +\li Massage Seats +\li 5 Zone Climate Control +\li Electric Window Opener +\li Window Heater +\li Window Sun Blinds +\li 2 RSE systems +\li Automatic Air conditioning system +\li Automatic Air Quality System +\li Bluetooth Media Streaming +\li Wifi (host and client) +\li Companion App +\endlist + +QtIVI tries to provide an API which can cope with the all these configurations, thus requiring a +lot of flexibility. This is the reason the Attribute System was created: the Attribute System is +mainly used for Vehicle Function APIs as there is no common ground in this area and whether a +specific feature is supported or not varies a lot. + +The heart of the attribute system is the QIviProperty. This class defines a special property of a +given type, which can be controlled using a QIviPropertyAttribute. The QIviPropertyAttribute +defines whether the property is available in the current configuration as well as its value +boundaries. Such an attribute can support the following scenarios: + +\list +\li The property is not available. +\li The property is available and the values can be between a minimum and a maximum value. +\li The property is available and only specific values from a given list are supported. +\endlist + +The QIviPropertyAttribute is mainly used by the backend implementation to inform the QIvi Feature +about the availability of a certain property, its underlying functionality and its expected value +range. Usually the range doesn't change between different car configurations but different OEM +backend implementations may even result in range changes. + +In QIviClimateControl attributes are used for every property. The backend can do the following to +state its capabilities: + +\code +// The zone synchronization is not supported +zoneSynchronizationAttribute = QIviPropertyAttribute<bool>(false); + +// The air recirculation is off +airRecirculation = false; +// The air recirculation is supported by the system. No minimum and maximum values are needed for an bool +airRecirculationAttribute = QIviPropertyAttribute<bool>(true); + +// The seat cooler is set to the intensity 10 +seatCooler = 10; +// The seat cooler is supported by the system and the minimum and maximum values are set to 0 and 10 +seatCoolerAttribute = QIviPropertyAttribute<int>(0, 10); + +// The current air flow direction is to the Floor +airflowDirection = QIviClimateControl::Floor; +// The system supports multiple air flows and all valid configurations are passed +QVector<QIviClimateControl::AirflowDirections> airflow { (QIviClimateControl::Floor | QIviClimateControl::Dashboard), QIviClimateControl::Floor, QIviClimateControl::Dashboard }; +airflowDirectionAttribute = QIviPropertyAttribute<QIviClimateControl::AirflowDirections>(airflow)); +\endcode + +Because the actual value for each property is changed more often than its attribute, these two +values are separated from each other. To make this still convenient to use within Qt's meta-type +system the QIviProperty class was created: QIviProperty is a convenience class which lets you +access the value and the attribute in an easy and type-safe way. The following snippet shows how a +QIviProperty is used within a class. + +\code +class SimpleControl : public QObject +{ + Q_OBJECT + Q_PROPERTY(QIviProperty *temperature READ temperatureProperty CONSTANT) + + SimpleControl(QObject *parent = nullptr); + ~SimpleControl(); + + int temperature() const; + QIviPropertyAttribute<int> temperatureAttribute() const; + QIviProperty *temperatureProperty() const; + +public slots: + void setTemperature(int temperature); + +signals: + void temperatureChanged(int temperature); + void temperatureAttributeChanged(const QIviPropertyAttribute<int> &attribute); +} +\endcode + +SimpleControl has a property to get and set the temperature. The setter and getter for the property +work like any other setter/getter in C++ and also have a corresponding changed signal. In addition +a QIviPropertyAttribute for the property is also provided with a getter and a changed signal. +Usually the attribute is defined by the backend and thus no setter is available. To use the +features of the QIviProperty, it is registered as a constant Qt property using the Q_PROPERTY and +in addition a getter function is provided. + +This split makes it possible to use the class from C++ without any hurdles: + +\code +SimpleControl *control = new SimpleControl(); +// Create a SpinBox and enable it only if the system supports reading/writing the temperature +QSpinBox *spinBox = new QSpinBox(); +spinBox->setEnabled(control->temperatureAttribute()->isAvailable()); +// Also setup the minimum and maximum of the SpinBox according to the values defined by the backend +spinBox->setMinimum(control->temperatureAttribute()->minimumValue()); +spinBox->setMaximum(control->temperatureAttribute()->maximumValue()); +connect(spinBox, &QSpinBox::valueChanged, control, &SimpleControl::setTemperature); +\endcode + +See the climate_widget example for a complete example. + +From QML this is done using the QIviProperty directly: + +\qml +import QtQuick 2.0 +import QtQuick.Controls 1.4 + +Item { + width: 200 + height: 200 + + SimpleControl { + id: simpleControl + } + + SpinBox { + value: simpleControl.temperature.value + minimumValue: simpleControl.temperature.minimumValue + maximumValue: simpleControl.temperature.maximumValue + enabled: simpleControl.temperature.available + onValueChanged: { + simpleControl.temperature.value = value + } + } +} +\endqml + +The SpinBox is connected to the value property of temperature using a binding. The binding +will be updated once the value changes. This is handled by the QIviProperty property by telling it +which signal to relay. For the temperature property, the SimpleControl::temperatureChanged signal +is forwarded to temperature.valueChanged. See the climate_qml example for a complete example. + +In the implementation of the SimpleControl class, the QIviProperty needs to be setup correctly. The +QIviProperty doesn't store any values and is simply forwarding the function calls and signal +emissions to the corresponding functionality of the SimpleControl class. + +\code +TemperatureProperty = QIviPropertyFactory<int>::create(q, + &SimpleControl::temperatureAttribute, + &SimpleControl::temperatureAttributeChanged, + &SimpleControl::temperature, + &SimpleControl::temperatureChanged, + &SimpleControl::setTemperature); +\endcode + +Read-only properties are supported as well, by simply not providing the last argument (pointer to +the setter function). +*/ diff --git a/src/ivicore/doc/src/backend-system.qdoc b/src/ivicore/doc/src/backend-system.qdoc new file mode 100644 index 0000000..5ed6597 --- /dev/null +++ b/src/ivicore/doc/src/backend-system.qdoc @@ -0,0 +1,139 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page backend-system.html +\title Dynamic Backend System +\nextpage Models +\contentspage Concepts + +\section1 What's a Feature + +Modern automotive systems are very complex and are developed in a tight timeframe. Because of that, +it often makes sense to reuse parts of previously developed systems. At the same time, the main +development is done by independent companies (tier-1). To make it possible to reuse code from +previous project, but at the same time also make it possible to use parts the tier-1 can offer, it +makes sense to split the APIs into two layers: a frontend and a backend. In QtIvi, the frontend API +is called a \b feature, as usually a specific class is responsible for a specific feature area, +e.g. QIviClimateControl, for controlling the climate feature area. + +\section1 What's a Backend + +To function correctly, every feature needs to have a connected backend. This backend needs to +implement the corresponding feature backend interface. Only then a valid connection between the +feature and its backend can be created. + +Usually every feature has exactly one backend interface class, which needs to be implemented by the +backend for this feature to work. Every backend interface is derived from QIviFeatureInterface, +which provides generic functions and signals needed by every feature, e.g. for error handling. + +The backend implementations are grouped together and are implemented inside a Qt plugin. This makes +it easy to provide multiple backends at the same time and switch the backend at runtime. Those +backend plugins are loaded through \l{qtivicore - the Glue}{qtivicore}. A plugin can provide +implementations for multiple features. There is no need to create a separate plugin for every +feature. QtIvi also distinguishes between two types of backends: production and simulation. While +on a production system, you only want to have production backends running. But during the +development phase, it might be useful to have a simulation backend available, which can be used for +frontend development until the backend services are in an usable state. QtIvi uses a simple naming +scheme to identify whether a plugin provides simulation or production backends. Every simulation +plugin needs to have either "simulation" or "simulator" in its name. In addition it is also supported +to set the "simulation" key in the plugin metadata. This is especially useful for static +plugins. Please see \l {How to Create Qt Plugins} for more details about Qt's plugin system. + +\image backendtypes.jpg "Backend types" + +\section1 ServiceObjects + +To keep the features very flexible and to make it possible to change the backends at runtime, we +introduced a concept called ServiceObject. A QIviServiceObject is a handle, which is used by the +feature to connect to the correct backend interface. It provides methods to query the available +backend interfaces that the ServiceObject is implementing. Plugins are automatically wrapped by +ServiceObjects. This makes it possible to share the ServiceObject between multiple features and to +explicltly select which backend should be used for your feature instance. + +\section1 qtivicore - the Glue + +The qtivicore module provides all the classes that are needed to glue the parts together. In +addition to providing the base classes like QIviAbstractFeature or QIviServiceObject, it also +provides the QIviServiceManager, responsible for loading the needed backend plugins. + +\image feature_backend.jpg "Feature backend relation" + +\section1 QIviServiceManager + +The QIviServiceManager is the central part of qtivicore, keeping book on all the available backends +and their exported interfaces. For this, the manager scans through all available plugins and their +accompanying metadata. This gives the QIviServiceManager the ability to only load the plugins, +which are actually needed by a Feature in order to reduce the startup time. All these information +is collected in the manager in form of a model, which enables the user to pick and choose the +plugin he wants to use. + +\section1 How a Feature Finds its Backend + +Usually every Feature is using the so called auto discovery mode. From QML, you can set the +QIviAbstractFeature::discoveryMode property; from the C++ side, this can be started using +QIviAbstractFeature::startAutoDiscovery(). This will ask the QIviServiceManager for all the +available backends implementing the required interface for your feature. The manager will then +choose the first matching backend and will connect the feature to it. QIviAbstractFeature will +first ask for production backends and only if none are available, fall back to a simulation +backend. This behavior can be controlled using the QIviAbstractFeature::discoveryMode (defaults to +QIviAbstractFeature::AutoDiscovery). The resulting backend type can be retrieved via +QIviAbstractFeature::discoveryResult. After the feature has successfully loaded a backend, the +QIviAbstractFeature::serviceObject property holds the loaded ServiceObject and +QIviAbstractFeature::isValid returns \c true. + +\section2 Manual Assignment + +If a feature does not want not use the auto discovery mechanism, it can simply set the +discoveryMode to QIviAbstractFeature::NoAutoDiscovery. After that, the feature won't search for a +backend itself anymore, so the user needs to assign a ServiceObject manually. + +\section2 DiscoveryModels + +For features like QIviClimateControl the auto discovery is fitting, as there is usually a 1:1 +mapping between a feature and a backend providing the implementation for the feature. For more +generic interfaces like a media player, this might not be sufficient: you could control a built-in +media player backend with this, but you might also want to control the media player running on your +mobile phone over bluetooth. For this to work, you first would need to discovery the available +devices and then pass the ServiceObject of the selected device to the media player interface. The +discovery of the available mobile phones can be done using a DiscoveryModel. This provides you with +a ServiceObject for every device found. The concept of a discovery model is not limited to mobile +phones, it can be used for all backends that are not hard-wired to the system, like internet +services or controlling multiple rearseat systems. + +\section2 Detailed connection order + +\list 1 + \li A ClimateControl element is created in QML. + \li ClimateControl will call QIviAbstractFeature::startAutoDiscovery on its completion. + \li QIviAbstractFeature::startAutoDiscovery will ask QIviServiceManager for all backends. + \li QIviServiceManager searches for all available plugins and the interfaces they are implementing + (this happens only once). + \li QIviAbstractFeature will accept the first QIviServiceObject and connect to the + corresponding interface. + \li The ClimateControl element is ready to be used. +\endlist +*/ diff --git a/src/ivicore/doc/src/concepts.qdoc b/src/ivicore/doc/src/concepts.qdoc new file mode 100644 index 0000000..94f6ebd --- /dev/null +++ b/src/ivicore/doc/src/concepts.qdoc @@ -0,0 +1,40 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page concepts.html +\title Concepts + +All Qt IVI feature APIs depend on a set of key concepts. These are explained in the +following sections. + +\list + \li \l {Dynamic Backend System} + \li \l {The Qt IVI Autogenerator} + \li \l {Models} + \li \l {The Qt IVI Query Language} +\endlist +*/ diff --git a/src/ivicore/doc/src/configuration.qdoc b/src/ivicore/doc/src/configuration.qdoc new file mode 100644 index 0000000..c5d4425 --- /dev/null +++ b/src/ivicore/doc/src/configuration.qdoc @@ -0,0 +1,135 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page configuration.html +\title Configuration + +The QtIvi module provides the following configuration options + +\section1 Configure Options and Features + +The following table shows the available features of the module. Just like with other modules, the +available features are auto-detected and displayed after the configuration step in the "Configure +summary". + +\table +\header + \li Feature + \li Dependency + \li Description +\row + \li IVI Generator + \keyword feature-ivigenerator + \li python3 + python3-virtualenv + \li The IVI Generator provides tooling to generate source code out of IDL files. The IVI + Generator comes with a set of templates for specific generation use-cases. +\row + \li QtSimulator Support + \keyword feature-qtsimulator + \li QtSimulator module + \li The QtSimulator Support is needed for the communication between the simulation backends and + their control panel (controller). It enhances the built-in templates by also generating + the needed code for the simulation backends to communicate over QtSimulator. In addition, + it also provides a new template to generate a controller application to communicate with + the simulation backend. +\row + \li QtRemoteObjects Support + \keyword feature-qtremoteobjects + \li QtRemoteObjects module + \li The QtRemoteObjects Support is needed to generate qtivi backends, using QtRemoteObjects as + it's IPC. It also provides templates to generate the server part of this IPC. +\endtable + +Additional command-line options to tailor the build-system to your needs: + +\table +\header + \li Command-line option + \li Description +\row + \li --host-tools-only + \li Only compiles the tools needed on the host in order to cross-compile for another target. + E.g. the \e {IVI Generator} +\row + \li --ivigenerator <no|qt|system> + \li \value no + Disables the \e {IVI Generator} feature completely. + \value qt + Enables the \e {IVI Generator} feature: will build and package the needed files. + \value system + Enables the \e {IVI Generator} feature, but is using the \e {IVI Generator} files + already available on the system. (e.g. from the native-qtivi package when + cross-compiling inside Yocto). +\endtable + +These command-line options can be passed to qmake using the \c QMAKE_EXTRA_ARGS environment variable + +\code + QMAKE_EXTRA_ARGS="--host-tools-only" qmake <qtivi-src>/qtivi.pro +\endcode + +\section2 Only build what is needed + +By default all QtIvi modules are configured to be built, depending on whether all needed dependencies +are available for the respective module or not. Similar to other Qt Features, every module can be +requested to be built or skipped explicitly using the "--[no-]feature-<modulename>" arguments when +invoking \c qmake. + +E.g. to disable building QtIvi Media: +\code + QMAKE_EXTRA_ARGS="--no-feature-ivimedia" qmake <qtivi-src>/qtivi.pro +\endcode + +Selecting the needed module explicitly has the advantage to show an error at configuration time +if not all dependencies are met. + +\section1 Runtime Configuration + +The following environment variables are supported for runtime configurations: + +\table +\header + \li Environment variable + \li Description +\row + \li SIMULATOR_HOSTNAME + \li Specifies where the QtSimulator server is running - e.g. the autogenerated control panel + binaries. + \note This is only available when the \l {feature-qtsimulator} {QtSimulator Support} is + enabled. +\endtable + +Also see the documentation about the \l {QtIvi Backends} {backend plugins} for more runtime configuration options. + +\section2 Logging + +The \e qt.ivi.servicemanagement Logging Category can be used to get more information on which +backends were considered, when searching for the correct backend for a feature and also why it was +chosen. +*/ + diff --git a/src/ivicore/doc/src/extending-qtivi.qdoc b/src/ivicore/doc/src/extending-qtivi.qdoc new file mode 100644 index 0000000..7dd82f8 --- /dev/null +++ b/src/ivicore/doc/src/extending-qtivi.qdoc @@ -0,0 +1,151 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page extending-qtivi.html +\title Extending Qt IVI + +\section1 Introduction + +Qt IVI provides a pattern for extending Qt with more features in a way that suites the +automotive use-case. + +A key aspect is the separation between the frontend that defines the API, from the +backend that implements the functionality. This separation makes it possible to have +multiple implementations of the same API which can be used to interface various hardware +configurations, but also to provide stubbed or simulated implementations for early +development and testing purposes. + +\section1 The Big Picture + +Qt IVI consists of three types of building blocks. The core module provides base classes +and common code for all the more specific modules and API definitions like a climate API +or a mediaplayer API. Each of these APIs is the second building block called \e Feature, +which defines the API used by the application developers. The last block consists of a +backend interface and one or more \e Backends implementing it to either connect to the +underlying vehicle or do a simulation of it. + +\section2 Features + +A feature is a set of classes for working with a specific function. It defines the interface +towards application developers, but it does not implement the complete functionality. Instead, it +defines a backend interface to be implemented by a backend providing the actual function. + +For easy deployment, Qt IVI extensions should be built as Qt modules. This makes it easy to +install and find headers, shared libraries, and plugin modules from app projects. + +By using the module system the developer can easily enable the inclusion of his +module in the following way: + +\code +QT += <module> +\endcode + +In addition, your module is properly set up to work with cmake, qdoc, and auto test." + +\code +make tests +\endcode + +When creating a new Qt IVI module, it is recommended that you pick a name such as +\e {OemFeatureName}, where \e {Oem} is the name of the car maker or platform owner, and +\e {FeatureName} is the name of the feature(s) of the module. In addition to the name, a reverse +domain name prefix is needed for prefixing backend interface names, for example \e {com.example} + +Features are based on the QIviAbstractFeature base class, or QIviAbstractZonedFeature for +zoned features. These classes provide the basic functions expected by users, e.g. backend +loading. + +Features define the backend interface to be implemented by the backends providing the +functionality. The backend interface is commonly based on the QObject class. It is important +to keep this API as unbiased as possible, as there might be multiple backend implementations +relying on different technological solutions. + +Some key rules to keep in mind are: + +\list +\li Keep everything asynchronous to avoid blocking the main loop. +\li Avoid call-to-signal sequences and try to keep signals independent from calls, For example, +when a value change is signalled, it must not be due to a call to change the value from +the feature (and visa versa). In other words a call to change a value is not required to always +result in a value changed signal. +\li Avoid stateful APIs whenever possible as the backend may be replaced at any time. +\endlist + +It is common to provide a stubbed backend implementation and a testing backend with each +feature. + +\section2 Backends + +A backend class is derived from the (commonly QObject-derived) backend interface class specified +by a feature. Instances of the backend class are called \e {service objects}. + +Backends are implemented as an ordinary Qt C++ plugin project that depends on +\l {QtIviCore}{Qt IVI Core} and the corresponding feature module. + +The backends are loaded by Qt IVI Core when the features request them. Each backend has to provide +a Qt IVI plugin that exposes a \e factory to the Core. This is what is used to load and create +backends. The plugin interface is called QIviServiceInterface. + +\section2 Service Manager + +In most cases, the backend loading is handed over to the Qt IVI Core, however, QIviServiceManager +can be used in this case to manually search for plugins with a specific BackendInterface. The +discovery and loading of the backends takes place in this class. + +The QIviServiceManager class can also be used to register backends which are part of the same +application and shouldn’t go into a plugin. This is especially useful for autotest as you need +to control the backend and the feature at the same time. + +\section1 Common Practices + +The reference APIs provided as a part of Qt IVI introduce some common concepts. If +implementing the same functionality, it is recommended to use these already defined patterns and +it is encouraged to add API additions back to the Qt IVI repository to create more common ground +for future APIs. + +\section2 Zones + +Zones is a standard way to provide a single API for multiple points in the vehicle. +For instance, climate control commonly has a driver and passenger zones, and might also have +a rear seat zone. The same goes for wheels, doors, mirrors, windows and more. + +A common pattern is to combine zones with property attributes to handle small differences in +capabilities between zones; for example, no steering wheel heater for the passenger side of the +car. + +Technically, a zoned feature consists of two interfaces, one top level interface derived +from QIviAbstractZonedFeature, and one zone specific API derived from QObject. + +The top level interface can provide vehicle wide settings. For example, whether recirculation +is to be used in a climate control API, while the zoned interface provides per-zone functions +(for example, the desired temperature). + +Building a zoned feature requires the backend interface to be derived from +QIviZonedFeatureInterface. This provides the backend an interface for enumerating the +available zones. This interface also includes the necessary +QIviZonedFeatureInterface::initialize method to initialize any properties. +*/ diff --git a/src/ivicore/doc/src/external-resources.qdoc b/src/ivicore/doc/src/external-resources.qdoc new file mode 100644 index 0000000..c48930b --- /dev/null +++ b/src/ivicore/doc/src/external-resources.qdoc @@ -0,0 +1,31 @@ +/**************************************************************************** +** +** Copyright (C) 2017 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Automotive Suite. +** +** $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$ +** +****************************************************************************/ + +/*! + \externalpage https://doc.qt.io/QtAutomotiveSuite/index.html + \title Qt Automotive Suite +*/ diff --git a/src/ivicore/doc/src/ivigenerator/filter-reference.qdoc b/src/ivicore/doc/src/ivigenerator/filter-reference.qdoc new file mode 100644 index 0000000..c330fff --- /dev/null +++ b/src/ivicore/doc/src/ivigenerator/filter-reference.qdoc @@ -0,0 +1,196 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page filter-reference.html +\title Filter Reference +\previouspage Autogenerator Usage +\nextpage Qmake Integration + +In addition to the built-in Jinja filters listed \l +{http://jinja.pocoo.org/docs/2.9/templates/#list-of-builtin-filters} {here}, the following +additional features are implemented in the ivigenerator. + +\target return_type(symbol) +\target return_type() +\section1 return_type(symbol) + +Returns the C++ type for the passed symbol. + +E.g. QString for a symbol of type "string". + +\target parameter_type(symbol) +\section1 parameter_type(symbol) + +Return the C++ type for the passed symbol. This returns the same type as return_type(), but already +prepared to be used as a parameter for methods. + +E.g. "const QString &<name>" for a symbol of type "string" + +\target getter_name(symbol) +\section1 getter_name(symbol) + +Returns the getter name of the property, if defined by the \c @getter_name annotation. Otherwise +retuns the passed symbol. + +\target setter_name(symbol) +\section1 setter_name(symbol) + +Returns the setter name of the property, if defined by the \c @setter_name annotation. Otherwise +retuns the passed symbol. + +\target default_type_value(symbol) +\section1 default_type_value(symbol) + +Returns the default value for the passed symbol. Models are initialized as \c nullptr + +\target default_value(symbol, zone="=") +\section1 default_value(symbol, zone="=") + +Returns the default value for the passed symbol set by the \c @default annotation. If not set uses +\c default_type_value instead. + +The zone parameter is used to identify different default values per zone. + +\target model_type(symbol) +\section1 model_type(symbol) + +Returns the C++ class name for this model. + +\target flag_type(symbol) +\section1 flag_type(symbol) + +Returns the name defined by the \c @type annotation for the passed flag. If this is not set, tries to +pluralize the passed name by adding an 's' at the end. + +\target parse_doc(string) +\section1 parse_doc(string) + +Parses the passed comment string and adds every javadoc command into its own group. Sentences +without tag are put into the 'description' group. + +\badcode +{% with doc = comments|parse_doc -%} +{% if doc.brief %} \brief {{doc.brief}} +{% endif %} + +{% if doc.description %} + {{doc.description}} +{% endif %} +{% endwith %} +\endcode + +\target lowerfirst(string) +\section1 lowerfirst(string) + +Only lowers the first character of the given string. + +\target range_low(property) +\section1 range_low(property) + +Returns the minimum value for the passed property using the \c @range or \c @minimum annotations. + +\target range_high(property) +\section1 range_high(property) + +Returns the maximum value for the passed property using the \c @range or \c @maximum annotations. + +\target strip_QT(string) +\section1 strip_QT(string) + +Removes the 'QT' at the beginning, if the string starts with it. + +\target domain_values(symbol) +\section1 domain_values(symbol) + +Returns the domain values for the passed property using the \c @domain annotation. + +\target enum_value(value, module_name) +\section1 enum_value(value, module_name) + +Returns the fully qualified C++ name of the given value. The passed module_name is used as C++ class +name containing the enum. + +Also supports passing '|' connected values. + +\target tag_by_path(symbol, path, default_value=False) +\section1 tag_by_path(symbol, path, default_value=False) + +Find the tag given by its full path in the object hierarchy, like +\c property.config_sim.zones.right. If some parts of the path are missing, return \c None. + +\target conf_sim_tag(symbol, path, default_value=False) +\section1 conf_sim_tag(symbol, path, default_value=False) + +Find the tag, given by its path, located under the "config_simulator" sub-object. Returns \c None, +if parts of the path are missing. + +\target jsonify(obj) +\section1 jsonify(obj) + +Returns a JSON representation of the given obj. + +\target has_domains(properties) +\section1 has_domains(properties) + +Returns \c true if any of the given properties has \c @range or \c @domain annotations. + +\target json_domain(properties) +\section1 json_domain(properties) + +Returns the property domains for the given properties formated in JSON. + +\target qml_type(interface) +\section1 qml_type(interface) + +Returns the name of the interface for use in QML. This name is defined by the \c @qml_type +annotation. This annotation is optional: if not provided, the interface name is used. + +\target qml_control(symbol, backend_obj) +\section1 qml_control(symbol, backend_obj) + +Returns the QML code for the control (or group of controls) to represent the editing UI for the +passed symbol. + +\target qml_binding_property(symbol) +\section1 qml_binding_property(symbol) + +Returns the name of the property of the QML control to be bound with. + +E.g. "value" for a Slider and "checked" for a CheckBox. + +\target qml_control_signal_parameters(symbol) +\section1 qml_control_signal_parameters(symbol) + +Returns the parameters for calling the signal using the values from the UI controls. + +\target struct_includes(symbol) +\section1 struct_includes(symbol) + +Returns the includes for the structs that the interface or a struct depends on. The returned +strings are complete and in format #include "struct.h". +*/ + diff --git a/src/ivicore/doc/src/ivigenerator/generator-usage.qdoc b/src/ivicore/doc/src/ivigenerator/generator-usage.qdoc new file mode 100644 index 0000000..688633b --- /dev/null +++ b/src/ivicore/doc/src/ivigenerator/generator-usage.qdoc @@ -0,0 +1,427 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page generator-usage.html +\title Autogenerator usage +\previouspage Jinja template syntax +\nextpage Filter Reference + +This page is about the usage of the QtIVI auto-generator. + +\section1 Introduction + +The Generator is a Python script that can be run manually or using the \l {QMake Integration}. +This script uses QFace as the autogenerator framework which parses the IDL +file, generates the domain-model (similar to AST) and then feeds it to the actual generator. +Depending on the type of the generated project, different \e{formats} are specified. + +\section1 Command line parameters +The generation is run using the following command: +\code +$$[QT_HOST_BINS]/ivigenerator/generate.py --format=backend_simulator interface.qface out_dir +\endcode + +The options and parameters are: +\table + \row + \li --reload / --no-reload [optional] + \li specifies whether the generator should keep track of the changes in the IDL file + and update output on the fly (--no-reload by default) + \row + \li -f, --format [frontend|backend_simulator|control_panel|backend_qtro|server_qtro|<folder>] + \li see below + \row + \li --help + \li Show options and exit. + \row + \li source + \li Path or paths to the IDL source files. In case of multiple entries present, each one + will be handled. In case a directory path is provided, it will be scanned for all the IDL + files. + \row + \li outputdir + \li Generation destination folder +\endtable + +At the moment the generator is able to generate 5 kinds of projects given an interface IDL file +based on the \e {--format} option value. +These are: +\table + \row + \li \l {frontend} + \target frontend-template + \li Generates a developer facing API using base classes from qtivicore and the \l {Dynamic + Backend System} + \row + \li \l {Backend Simulator} {backend_simulator} + \target backend-simulator-template + \li Generates a simulation backend for the API generated by the "frontend" option. This + backend serves as a mock implementation. + \row + \li \l {Control Panel} {control_panel} + \target control-panel-template + \li Generates a controller application, consisting of an UI and a C++ plugin, which communicates + to the simulation backend generated from the same qface file using QtSimulator. + \row + \li \l {QtRemoteObjects Backend} {backend_qtro} + \target backend-qtro-template + \li Generates a QtRemoteObjects based backend client for the API generated by the "frontend" option. + This backend connects to a backend server. + \row + \li \l {QtRemoteObjects Server} {server_qtro} + \target server-qtro-template + \li Generates a QtRemoteObjects based backend server stub for the API generated by the "frontend" option. + \row + \li folder path + \li Uses templates inside the folder. A YAML file with the same name as the folder (and .yaml + extension) should provide a list of template files in the folder (see YAML format specification below). +\endtable + +\section1 YAML configuration + +The Python script is responsible for parsing the input files and for the creation of a domain +model. This domain model is passed as a context to the Jinja template engine. To control which +files are generated, the "Generation YAML" can be used. In addition, an "Annotations YAML" can be +used to add more information to the IDL file, which are generator specific. + +\section2 Generation YAML + +After the domain model tree has been created, this tree is traversed and each leaf of the domain +model object tree (module, interface, structure, etc) is passed to a specific Jinja template +defined by the configuration file. This file must be in YAML format and for every particular +generation format its name is defined in the script. This file must have the following structure: + +\code +generate_rules: + module_rules: + - dest_file: "{{module.module_name|lower}}plugin.h" + template_file: "plugin.h.tpl" + interface_rules: + - dest_file: '{{interface|lower}}backend.h' + template_file: 'backend.h.tpl' + struct_rules: +\endcode + +For every entity there is a list of templates needed to be called when traversing this entity +in the domain model tree. Here, \e{dest_file} is a name of the file need to be created specified in +the \l {Jinja template syntax}{Jinja template language} format: the value of the object property +used in the name template will be processed and substituted into the template, thus forming the +final name of the file to create. \e{dest_file} is a name of the template to be used. For the IVI +generator, rules for three kinds of entities need to be specified: modules, interfaces and +structures. + +\section2 Annotations YAML + +At the moment not all aspects of the interface description cannot be expressed using the IDL +itself. For instance there is no language construct to define default value for the property or +values the property can take on. Still this can be achieved via a mechanism called \l +{annotations_reference} {Annotations}. Annotations allow great freedom and flexibility of +expressing any concepts and constructs. + +Below is an example of using annotations in the IDL. Here it's defined that interface is zoned and +its identifier is specified. + +\code +@config: {zoned: true, id: "org.qt-project.qtivi.ClimateControl/1.2" } +\endcode + +Not all of the annotations make sense to be put in the main IDL file either. For instance, one may +need to define some aspects of generation of the auto-testing code. Such annotations can be put in +the YAML file accompanying the main IDL file and named after it. During the parse phase +QFace picks this file up automatically and merges annotation specified in this YAML file with those +defined in the IDL file. + +For QtIvi there are following annotations used for the IDL definition: + +\table + \header + \li Tag + \li Where + \li Object type + \li Purpose + \row + \li @config(interfaceBuilder: "FunctionName") + \li Main IDL file + \li Module + \li Declares a function which will be called in the plugin to generate the instances for every interface. + The function takes a pointer to the plugin instance and returns a \c {QVector<QIviFeatureInterface *>}. + Interfaces should be generated in the same order as defined by \c {Plugin::interfaces()}. + + This can be used to instanciate classes derived from the generated plugin interfaces classes. + \row + \li @config(zoned) + \li Main IDL file + \li Interface + \li tells the generator whether the interface is zoned or not. This allows to define + whether the backend feature interface is derived from QIviZonedFeatureInterface or from + QIviFeatureInterface + \row + \li @config(id=org.qt.project.qtivi.ClimateControl.1.0) + \li Main IDL file + \li Interface + \li defines the interface id. The id is a string used by the QtIvi service manager to glue + frontend interface and backend implementation together. See \l {Dynamic Backend System} + for more details. + \row + \li @config(getter_name) + \li Main IDL file + \li Property + \li Overrides the default getter method name. Useful for boolean properties (for example, getter + for property 'enabled', should be 'isEnabled' rather than the default). + \row + \li @config(setter_name) + \li Main IDL file + \li Property + \li Overrides the default setter method name. + \row + \li @config(qml_name) + \li Main IDL file + \li Module, Interface + \li Defines the name this interface/module should be using in QML. For interfaces, it is the + name which is used to export the interface to QML. For modules it defines the uri of the + complete module. +\endtable + +The annotations that are not logically part of the interface description but rather the ones used +for specifying additional information are put in the accompanying YAML file. Here is the list of +annotations used for defining various aspects of the generation of the backend-simulator: + +\table + \header + \li Tag + \li Where + \li Object type + \li Purpose + \row + \li + \code + config_simulator: + zones: { left : FrontLeft, right : FrontRight, rear: Rear } + \endcode + \li Accompanying YAML file + \li Interface + \li For the backend simulator defines a list of zones supported by the simulation code + with their names + \row + \li \code + config_simulator: + default: AirflowDirection.Floor | AirflowDirection.Dashboard + \endcode + \li Accompanying YAML file + \li Property + \li Defines the initial values for the property returned by the simulator backend. + + For zoned properties a mapping from a zone to a default value can be used. The default key of the map is "=". + \code + config_simulator: + default: { left: 21.0, right: 22.5, =: 0.0 } + \endcode + \row + \li \code + config_simulator: + minimum: 10 + \endcode + \li Accompanying YAML file + \li Property + \li Defines the minimum value for integer and real properties, generated code in the simulator backend will check for validity. + \row + \li \code + config_simulator: + maximum: 10 + \endcode + \li Accompanying YAML file + \li Property + \li Defines the maximum value for integer and real properties, generated code in the simulator backend will check for validity. + \row + \li \code + config_simulator: + range: [10, 20] + \endcode + \li Accompanying YAML file + \li Property + \li Defines the range value for integer and real properties, generated code in the simulator backend will check for validity. + \row + \li \code + config_simulator: + domain: {10, 20, 30} + \endcode + \li Accompanying YAML file + \li Property + \li Defines the possible values for the property, generated code in the simulator backend will check for validity. +\endtable + + +\section1 Generated projects structure + +In the generator output directory first a new subfolder with the name of the module id will be +created. All the generated files will be put in this folder. The following files will be generated: + +\section2 Frontend +\table + \header + \li File name + \li Purpose + \row + \li "{{module.module_name|lower}}global.h" + \li Standard file with global EXPORT defines + \row + \li "{{module.module_name|lower}}module.h/cpp" + \li Files defining a module class used for module global variables and types. + \row + \li "{{module|lower|replace('.', '-')}}.pri" + \li Standard Qt .pri file, containing all the generated files that can be used for + including the autogenerated files into a qmake project. + \row + \li "{{interface|lower}}backendinterface.h/cpp" + \li Files defining the interface need to be implemented by the backend implementation of + the feature + \row + \li "{{interface|lower}}.h/cpp" + \li Front end implementation of the feature, ready to be used from QML. + \row + \li "{{interface|lower}}_p.h" + \li Private part of the frontend implementation +\endtable + +\section2 Backend simulator + +\table + \header + \li File name + \li Purpose + \row + \li "{{module.module_name|lower}}plugin.h/cpp" + \li Files defining implementation of QtIvi backend plugin implementing + QIviServiceInterface + \row + \li "{{module.module_name|lower}}.json" + \li File containing identifiers of the exposed feature interfaces needed by the Qt plugin + system. + \row + \li "{{module|lower|replace('.', '-')}}.pri" + \li Standard Qt .pri file, containing all the generated files that can be used for + including the autogenerated files into a qmake project. + \row + \li "{{interface|lower}}backend.h/cpp" + \li Files containing the implementation of the simulation backend. +\endtable + +\section2 Control Panel + +The control_panel template is only available if the QtSimulator module was found. Please see the \l{feature-qtsimulator}{Configuration Page} +for more information. + +\table + \header + \li File name + \li Purpose + \row + \li "main.cpp" + \li Launcher code loading the QML code and exporting the C++ interface. + \row + \li "main.qml" + \li Main QML file containing the code to load the Control UIs for every interface. + \row + \li "qml.qrc" + \li QRC file for all QML code. + \row + \li "FlagControl.qml" + \li UI Element to control a flag inside a interface. + \row + \li "EnumControl.qml" + \li UI Element to control a enum inside a interface. + \row + \li "{{module|lower|replace('.', '-')}}.pri" + \li Standard Qt .pri file, containing all the generated files that can be used for + including the autogenerated files into a qmake project. + \row + \li "{{module.module_name|lower}}global.h" + \li Standard file with global EXPORT defines + \row + \li "{{module.module_name|lower}}module.h/cpp" + \li Files defining a module class used for module global variables and types. + \row + \li "{{interface|lower}}.h/cpp" + \li C++ code retrieving and forwarding the state using QtSimulator. + \row + \li "{{module.module_name|lower}}ControlUi.qml" + \li Control UI for this interface. Contains a interface to control every + property and method and log calls to signals. +\endtable + +\section2 QtRemoteObjects Backend + +The backend_qtro template is only available if the QtRemoteObjects module was found. +Despite the name, the remote object backend is not the location for the implementation of the actual backend logic, but just a client for connecting to the remote backend server. + +\table + \header + \li File name + \li Purpose + \row + \li "{{module.module_name|lower}}plugin.h/cpp" + \li Files defining implementation of QtIvi backend plugin implementing + QIviServiceInterface + \row + \li "{{module.module_name|lower}}.json" + \li File containing identifiers of the exposed feature interfaces needed by the Qt plugin + system. + \row + \li "{{module|lower|replace('.', '-')}}.pri" + \li Standard Qt .pri file, containing all the generated files that can be used for + including the autogenerated files into a qmake project. Also adds the .rep file + to the project and calls the remote object compiler. + \row + \li "{{interface|lower}}backend.h/cpp" + \li Files containing the implementation of the remote object backend. + Establishes the connection and initializes the remote object replica. + \row + \li "{{interface|lower}}.rep" + \li The input file for Qt’s \l [QtRemoteObjects] {Qt Remote Objects Compiler} {replica compiler} for producing the replica class code. +\endtable + +\section2 QtRemoteObjects server + +The server_qtro template is only available if the QtRemoteObjects module was found. The produced code contains merely the source classes to inherit and code for establishing the connection. It is up to the developer to implement the actual backend logic. + +\table + \header + \li File name + \li Purpose + \row + \li "core.h/cpp" + \li Code for establishing the connection and starting the remoting for the source objects. + \row + \li "{{srcBase|lower}}.pri" + \li Standard Qt .pri file, containing all the generated files that can be used for + including the autogenerated files into a qmake project. Also includes the .rep file + to the project and calls the remote object compiler. + \row + \li "{{interface|lower}}.rep" + \li The input file for the Qt’s \l [QtRemoteObjects] {Qt Remote Objects Compiler} {replica compiler} for producing the source class code. +\endtable +*/ diff --git a/src/ivicore/doc/src/ivigenerator/getting-started.qdoc b/src/ivicore/doc/src/ivigenerator/getting-started.qdoc new file mode 100644 index 0000000..0249f2c --- /dev/null +++ b/src/ivicore/doc/src/ivigenerator/getting-started.qdoc @@ -0,0 +1,77 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page gettingstartedivigenerator.html +\title Getting Started Using the Qt IVI Generator + +This guide explains how to get started with the Qt IVI Generator. +The generator is used to generate source code from an IDL file. It supports +multiple templates to select what kind of code should be generated. + +The Qt IVI Generator can be found inside the \c bin folder of your Qt installation. +If it is not available, please make sure all prerequisites listed in the qmake +configuration summary are met. See \l {Configuration} for more information on how +Qt IVI can be configured. + +\section1 Basics + +The generator takes an IDL file as input for generating its source code. The +following code shows a minimal IDL file: + +\code +module my.idl 1.0 + +interface MyInterface { + property int value; + void increment(); + signal valueIncremented(int newValue); +} +\endcode + +The IDL pretty much self-explanatory: it defines a new module (namespace) +\e my.idl in version \e 1.0. Inside there should be an interface called \e MyInterface. +The interface provides a property storing a value and a function to increment and notify +the user. The \l {QFace IDL syntax} page provides a more detailed documentation about the IDL. + +Using the previously defined IDL file, the \l {frontend-template}{frontend} template can be used to generate +a library providing an implementation of \e MyInterface. The generated class will use the +\l {Dynamic backend System} provided by Qt IVI for an abstraction of \e frontend and \e backend code. + +The actual implementation of the class behavior is done inside a \e backend plugin. A very basic +backend plugin can be generated by using the \l {backend-simulator-template}{backend_simulator} template. For more information +how Qt locates and loads its plugins, please see \l {How to Create Qt Plugins} {here}. + +For more in-depth information, the \l {Qt IVI Generator Example} comes with a step by step documentation. +*/ + +/* +This provides ideas on how this page should be extended in the future. + +\section1 Generating a complete qt module +\section1 Extending the autogenerator +\section1 Android Deployment +*/ diff --git a/src/ivicore/doc/src/ivigenerator/idl-syntax.qdoc b/src/ivicore/doc/src/ivigenerator/idl-syntax.qdoc new file mode 100644 index 0000000..f44eee1 --- /dev/null +++ b/src/ivicore/doc/src/ivigenerator/idl-syntax.qdoc @@ -0,0 +1,318 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/* + NOTE: Some content in this file was copied from the QFace Documentation +*/ +/*! +\page idl-syntax.html +\title QFace IDL syntax +\nextpage Jinja template syntax +\keyword IDL + +This page explains the basic usage of the QFace IDL. A more detailed description of the library +can be found on its \l {https://pelagicore.github.io/qface/}{page} + +QFace (Qt interface language) is an Interface Description Languge (IDL). While it is primarily +designed to define an interface between Qt, QML and C++, it is intended to be flexible enough also +to be used in other contexts. + + +\section1 The IDL + +The IDL uses common API concepts such as modules, interfaces, properties, structs and enums/flags. +Additionally it knows about lists and \l {Model/View Programming}{models}. +A list is an array of primitive or complex types. A model is an indicator for large data sets +which are typical used via a defined API (e.g. pagination). + +\code +module org.example 1.0 + +interface Echo { + string message; + void echo(string message); + signal broadcast(string message); + Status status; +} + +enum Status { + Null, Loading, Ready, Error +} +\endcode + +The data types provided by QFace can be divided into primitive and complex types: + +\b {Primitive Types} +\list + \li bool + \li int + \li real + \li string + \li var +\endlist + +\b {Complex Types} +\list + \li Interface + \li Struct + \li Enum + \li Flag + \li Array + \li Model +\endlist + +The language as such does not provide any support for maps or dictionaries. The reason for not +providing a map container type is that keys in dictionaries requires a hash which can not always +be guaranteed to be available in complex types. + +\section1 Grammar +The grammar of QFace is well defined and is based on the concepts of modules as a larger +collection of information. + +A module can have several interfaces, structs and/or enums/flags. + +\code +module <module> <version> +import <module> <version> + +interface <Identifier> { + [readonly] <type> <identifier> + <type> <operation>(<parameter>*) + signal <signal>(<parameter>*) +} + +struct <Identifier> { + <type> <identifier>; +} + +enum <Identifier> { + <name> = <value>, +} + +flag <Identifier> { + <name> = <value>, +} +\endcode + +A QFace document always describes one module. Each document can contain one or more interfaces, +structs, flags or enums. Each document can import other modules using the import statement. + +\section1 Module + +A module is identified by its name. The name should normally be a URI where all parts are +lowercase (e.g. \e {entertainment.tuner}). A module may import other modules with the primary +purpose being to ensure that dependencies are declared inside the QFace file. + +\code +// org.example.qface +module org.example 1.0 + +import org.common 1.0 +\endcode + +\section1 Interface + +An interface is a collection of properties, operation and signals. Properties carry data, whereas +the operations normally modify the data. Signals are used to notify the user of changes. + +\code +interface WeatherStation { + real temperature; + void reset(); + signal error(string message); +} +\endcode + +\section1 Struct + +The struct is supposed to serve as a container to transport structured data. It supports neither +properties nor operations. + +\section1 Property + +Interfaces and structures data are carried by properties: syntax elements allowing to describe +some attributes of the entity. A property can be of any type, known to IDL. It can be marked as \e +{readonly}, in which case this attribute of the interface is not supposed to be written to from +the outside code. It's up to the generator to enforce this constraint. + +\section1 Enum/Flag +Enums and flags are the concepts known from many popular programming languages (C++,Java,etc). +They differ only in what values they can take: enums are allowed to take only a single value, +whereas flags can be an OR-ed combination of multiple values. + +\section1 Types + +Types are either local and can be referenced simply by their name, or they are from an external +module in which case they need to be referenced with the fully qualified name (module + '.' + +name). A type can be an interface, struct, enum or flag. + +A module consists of either one or more interfaces, structs and enums/flags. They can come in any +number or combination. The interface is the only type which can contain operations and signals. +A struct is merely a container to transport structured data. Enum and flags allows the user to +encode information used inside the struct or interface as datatype. + +The QFace library does not allow to extend interfaces. It is by design kept simple. + +Below is an example of a QFace file. + +\code +module entertainment.tuner 1.0; + +import common 1.0 + +interface Tuner { + // property currentStation + readonly Station currentStation; + // operation nextStation + void nextStation(); + // operation previousStation + void previousStation(); + // operation updateCurrentStation + void updateCurrentStation(int stationId); + + list<int> primitiveList; + list<Station> complexList; + model<int> primitiveModel; + model<Station> complexModel; +} + +\endcode + + +\section1 Annotations +\target annotations_reference + +Annotations is a way to add meta information to your interface definition. It is available to each +symbol in the interface. + +Annotations allows an interface author to extend the existing interface with additional meta +information, called tags, aka annotations. One or several annotations can precede a module, +interface, struct or enum. They are also allowed before an operation, property or signal. +Everywhere where a documentation comment is allowed you can also add annotations. + +An annotation looks like this: + +\code +@service: {port: 12345} +interface Tuner { +} +\endcode + +An in code annotation precedes a symbol and it starts with an @ sign. A symbol can have more than +one one annotation line. Each line should be one individual annotation. The content is YAML +content. All @ signs preceding a symbol are collected and then evaluated using a YAML parser. + +For larger annotations one can use the external annotation document feature. + +\code +@singleton: yes +@data: [1,2,3] +@config: { values: [LEFT, RIGHT, TOP] } +\endcode + +This will be result into a YAML content of + +\code +singleton: yes +data: [1,2,3] +config: { values: [LEFT, RIGHT, TOP] } +\endcode + +And the result as Python object would be + +\code +{ + "data": [ 1, 2, 3 ], + "singleton": true, + "config": { + "values": [ "LEFT", "RIGHT", "TOP" ] + } +} +\endcode + +\section1 Annotation Documents + +QFace allows also to specify these annotations in external documents using the YAML syntax. For +this you need to create a document with the same name as the QFace document but with the extension +.yaml. It should have roughly the following format + +\code +com.pelagicore.ivi.Tuner: + service: + port: 12345 +\endcode + +On the root level should be a fully qualified name of a symbol. The symbol will be looked up and +the following annotation information merged with the existing annotations from the QFace document. + +\section1 Merging Annotations + +The external annotations will be merged on top of the embedded annotations on per symbol base. +Dictionaries will be merged. If a merge can not be done then the external document based +annotations will override the embedded annotations. + +The annotation are available later when navigating the domain model. + +\code +{% if "service" in interface.tags %} +interface {{interface}} is served on port: {{interface.tags.service.port}} +{% else %} +interface {{interface}} is not served +{% endif %} +\endcode + +\note +QFace does not specify specific annotations, but defines just the annotation format. The set of +annotations supported must be defined and documented by the generator. + +\section1 Domain Model + +As a result of parsing the IDL document, a domain model object must be created. The domain model +resembles the structure of our system as objects. It is build by the parser and serves as the +input into the generator. + +The IDL is converted into an in memory domain model (see qface/idl/domain.py) + +\code +- System + - Module + - Import + - Interface + - Property + - Operation + - Event + - Enum + - Flag + - Struct + - Property +\endcode + +The domain model is the base for the code generation. You traverse the domain tree and trigger +your own code generation. + +Detailed description of QFace library API is found on the library \l +{http://qface.readthedocs.io/en/latest/api.html} {page} +*/ diff --git a/src/ivicore/doc/src/ivigenerator/ivigenerator.qdoc b/src/ivicore/doc/src/ivigenerator/ivigenerator.qdoc new file mode 100644 index 0000000..3a50a38 --- /dev/null +++ b/src/ivicore/doc/src/ivigenerator/ivigenerator.qdoc @@ -0,0 +1,46 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page ivigenerator.html +\title The Qt IVI Autogenerator +\keyword QFace + +Qt IVI provides a way to describe interfaces using its own IDL (interface definition language) and +then generate Qt/QML API code based on this definition. The generator is based on the QFace +library, which provides a generic autogeneration framework. + +\list + \li \l {QFace IDL syntax} + \li \l {Jinja template syntax} + \li \l {Autogenerator Usage} + \li \l {Filter Reference} + \li \l {QMake Integration} + \li \l {QtIVI Remote backends}{Remote backends} + \li \l {ivicore/qface-ivi-climate}{Generator Example} + \li \l {ivicore/qface-ivi-remote}{Remote Backend Example} +\endlist +*/ diff --git a/src/ivicore/doc/src/ivigenerator/qmake-integration.qdoc b/src/ivicore/doc/src/ivigenerator/qmake-integration.qdoc new file mode 100644 index 0000000..3085efc --- /dev/null +++ b/src/ivicore/doc/src/ivigenerator/qmake-integration.qdoc @@ -0,0 +1,121 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page qmake-integration.html +\title QMake Integration +\previouspage Autogenerator usage + +Qt IVI Generator has been integrated with QMake to generate all or part of projects. + +In it's simplest form, QMake can generate all the source code and the project only +need to configure what type of project is built. + +For complex setups, generated code can be combined with application specific code +which can extend and use it. + +Example: +\code +CONFIG += ivigenerator + +QT_FOR_CONFIG += ivicore +!qtConfig(ivigenerator): error("No ivigenerator available") + +QFACE_FORMAT = frontend +QFACE_SOURCES = example.qface +QFACE_MODULE_NAME = myModule +QFACE_OUTPUT_DIR = myOutputDir +\endcode + +Available QMake Variables: +\table + \row + \li QFACE_FORMAT + \li frontend (default), simulator_backend + \row + \li QFACE_SOURCES + \li list of .qface input files + \row + \li QFACE_MODULE_NAME + \li The (optional) name of the module that is using the generated code + \row + \li QFACE_OUTPUT_DIR + \li Output folder where the generated code will be created. The default + is to use the current build folder +\endtable + + +See \l {Autogenerator usage} for more details on the generator command line arguments. + +\quotation +\note As the ivigenerator has specific system dependencies, it may not be available in every QtIviCore installation. +In this case the ivigenerator qmake feature is also not available and this can result in build errors. + +The following code snippet makes sure to stop the build and give a meaningful error message in this case: +\code +QT_FOR_CONFIG += ivicore +!qtConfig(ivigenerator): error("No ivigenerator available") +\endcode +\endquotation + +\section1 QtModule support + +The Qmake Integration also supports generating code which enables you to compile the generated code +as a qt module. As it needs to work more closely with the Qt's module build system, it shouldn't be +loaded using the \e CONFIG variable, but using the \e load() function instead. The \e +ivigenerator_qt_module feature replaces the \e load(qt_module) call. The following shows how the +integration of the QtIviVehicleFunctions module is done. + +\badcode +TARGET = QtIviVehicleFunctions +QT = core core-private ivicore ivicore-private +CONFIG += c++11 ivigenerator + +QT_FOR_CONFIG += ivicore +!qtConfig(ivigenerator): error("No ivigenerator available") + +... + +QFACE_MODULE_NAME = QtIviVehicleFunctions +QFACE_SOURCES += ivivehiclefunctions.qface + +load(ivigenerator_qt_module) +\endcode + +In addition to the project file for the module library also the \e sync.profile needs to be +changed, as this is used to call the \e syncqt.pl script which generates the forwarding headers. +Usually the \e sync.profile is setup to search for the headers in the source folders. Using +\e $out_basedir it can be extended to also search in the build folder. + +\badcode +... +%modules = ( # path to module name map + "QtIviVehicleFunctions" => "$basedir/src/ivivehiclefunctions;$out_basedir/src/ivivehiclefunctions" +); +... +\endcode + +*/ diff --git a/src/ivicore/doc/src/ivigenerator/remotebackends.qdoc b/src/ivicore/doc/src/ivigenerator/remotebackends.qdoc new file mode 100644 index 0000000..064a062 --- /dev/null +++ b/src/ivicore/doc/src/ivigenerator/remotebackends.qdoc @@ -0,0 +1,70 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page remotebackends.html +\title QtIvi Remote Backends + +One of the features of the Qt IVI Generator is the possibility to create remote backends +that utilize the QtRemoteObjects module. +A remote backend may be an independently running process, even on a separate host machine, that can +be accessed by multiple clients, or frontends. Such frontends are e.g. the main infotainment system +UI, different applications running within the UI or mobile devices. + +\section1 Motivation + +The purpose of having remote backends is to enable the distribution of functionality and the sharing +of information. This may be between multiple processes and even between multiple host machines. +Separate processes improve the overall reliability of a complex system and make it possible to +separate computationally intensive code from the UI code. Additionally, remote backends can be +accessible by multiple frontend points, be it the central UI, separate applications or even mobile +devices or third party applications. +Combined with the automatic generation of code and uniform feature loading of QtIvi, the development +of distributed features comes with a minimal development overhead and interchangeability and +transparency on the UI code side. + +\section1 Code Generation + +The remote objects generator produces client side code as a QtIvi backend plugin and a remote server +stub. The client is generated using the \l {backend-qtro-template}{backend_qtro} template and the s +erver using the \l {server-qtro-template}{server_qtro} template. Both the plugin and the server +contain generated c++ code and an intermediate .rep -file that is further processed by Qt’s +\l [QtRemoteObjects] {Qt Remote Objects Compiler} {replica compiler} to produce the actual source +and replica classes. + +The generated plugin is loaded and used as any other QtIvi plugin and is interchangeable with any +other backend implementation with the same API. As all method calls over QtIvi feature interfaces +are asynchronous, the use of a remote backend is similar to any other type of backend. + +The generated plugin is buildable and usable as it is, and does not require further changes by the +developer. The task of the developer will be then to implement the intended functionality at the +server side. To support getting started with the server, there is a generated class that initializes +the connection. All connection parameters to the plugin and to the server are passed currently over +a config file, either in a default location or at an user specified path. + +For a steb-by-step introduction to remote backends, see the \l {ivicore/qface-ivi-remote}{Remote Backend Example}. + +*/ diff --git a/src/ivicore/doc/src/ivigenerator/template-syntax.qdoc b/src/ivicore/doc/src/ivigenerator/template-syntax.qdoc new file mode 100644 index 0000000..96a4b78 --- /dev/null +++ b/src/ivicore/doc/src/ivigenerator/template-syntax.qdoc @@ -0,0 +1,477 @@ +/**************************************************************************** +** +** Copyright (C) 2018 Pelagicore AG +** Copyright (C) 2017 Jinja Team. +** 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$ +** +****************************************************************************/ +/* + NOTE: Some content in this file was copied from the Jinja Template Engine Documentation + and from the QFace Documentation +*/ +/*! +\page template-syntax.html +\title Jinja template syntax +\previouspage QFace IDL syntax +\nextpage Autogenerator usage + +This page is about the Jinja template engine. While the most detailed description of the template +language can be found at \l {http://jinja.pocoo.org/docs/dev/templates/}{Jinja documentation}, +some basic concepts are given in this article. + + +\section1 Code Generation Principle + +The code generation is driven by a small script which iterates over the domain model and writes +files using the Python Jinja template language. + + +Given that generator script has read and parsed the IDL file into a domain model, this latter one +is then used as the root object for the code generation inside the template language. Below is an +example of the code traversing the domain model: + +\code +{% for module in system.modules %} + {%- for interface in module.interfaces -%} + SERVICE, {{module}}.{{interface}} + {% endfor -%} + {%- for struct in module.structs -%} + STRUCT , {{module}}.{{struct}} + {% endfor -%} + {%- for enum in module.enums -%} + ENUM , {{module}}.{{enum}} + {% endfor -%} +{% endfor %} +\endcode + +The template iterates over the domain objects and generates text which is written into a file. + +\section1 Laguage constructs +\section2 Synopsis + +A template contains variables and/or expressions, which get replaced with values when a template +is rendered; and tags, which control the logic of the template. + +There are a few kinds of delimiters. The default Jinja delimiters are configured as follows: + +\list + \li {% ... %} for Statements + \li {{ ... }} for Expressions to print to the template output + \li {# ... #} for Comments not included in the template output + \li # ... ## for \l {line_statements}{Line Statements} +\endlist + +\section2 Control structures + +A control structure refers to all those things that control the flow of a program - conditionals +(i.e. if/elif/else), for-loops, as well as things like macros and blocks. With the default syntax, +control structures appear inside {% ... %} blocks. + +\section3 For + +Loop over each item in a sequence. For example, to display a list of users provided in a variable +called users: + +\code +<h1>Members</h1> +<ul> +{% for user in users %} + <li>{{ user.username|e }}</li> +{% endfor %} +</ul> +\endcode + +As variables in templates retain their object properties, it is possible to iterate over +containers like dict: + +\code +<dl> +{% for key, value in my_dict.iteritems() %} + <dt>{{ key|e }}</dt> + <dd>{{ value|e }}</dd> +{% endfor %} +</dl> +\endcode + +Inside of a for-loop block some special variables are available: + +\table + \header + \li Variable + \li Description + \row + \li loop.index + \li The current iteration of the loop. (starting with \e 1) + \row + \li loop.index0 + \li The current iteration of the loop. (starting with \e 0) + \row + \li loop.revindex + \li The number of iterations from the end of the loop (starting with \e 1) + \row + \li loop.revindex0 + \li The number of iterations from the end of the loop (starting with \e 0) + \row + \li loop.first + \li True if first iteration. + \row + \li loop.last + \li True if last iteration. + \row + \li loop.length + \li The number of items in the sequence. +\endtable + +See for more \l{http://jinja.pocoo.org/docs/2.9/templates/#list-of-control-structures}{Jinja +documentation} + + +Unlike in Python, it’s not possible to break or continue in a loop. One can, however, filter the +sequence during iteration, which allows one to skip items. The following example skips all the +users which are hidden: + +\code +{% for user in users if not user.hidden %} + <li>{{ user.username|e }}</li> +{% endfor %} +\endcode + +The advantage is that the special loop variable will count correctly; thus not counting the users +not iterated over. + +If no iteration took place because the sequence was empty or the filtering removed all the items +from the sequence, one can render a default block by using else: + +\code +<ul> +{% for user in users %} + <li>{{ user.username|e }}</li> +{% else %} + <li><em>no users found</em></li> +{% endfor %} +</ul> +\endcode + +In Python, \e {else} blocks are executed whenever the corresponding loop did not break. Since +Jinja loops cannot break anyway, a slightly different behavior of the \e {else} keyword was chosen. + +It is also possible to use loops recursively. This is useful when dealing with recursive data such +as sitemaps or RDFa. To use loops recursively, one basically has to add the recursive modifier to +the loop definition and call the loop variable with the new iterable where recursion is needed. + +The following example implements a sitemap with recursive loops: + +\code +<ul class="sitemap"> +{%- for item in sitemap recursive %} + <li><a href="{{ item.href|e }}">{{ item.title }}</a> + {%- if item.children -%} + <ul class="submenu">{{ loop(item.children) }}</ul> + {%- endif %}</li> +{%- endfor %} +</ul> +\endcode + +The loop variable always refers to the closest (innermost) loop. If we there is more than one +level of loops, we can rebind the variable loop by writing {% set outer_loop = loop %} after the +loop that we want to use recursively. Then, we can call it using {{ outer_loop(...) }} + +Please note that assignments in loops will be cleared at the end of the iteration and cannot +outlive the loop scope. Older versions of Jinja2 had a bug where in some circumstances it appeared +that assignments would work. This is not supported. + +\section3 If + +The if statement in Jinja is comparable with the Python if statement. In the simplest form, one +can use it to test if a variable is defined, not empty and not false: + +\code +{% if users %} +<ul> +{% for user in users %} + <li>{{ user.username|e }}</li> +{% endfor %} +</ul> +{% endif %} +\endcode + +For multiple branches, elif and else can be used like in Python. One can use more complex +Expressions there, too: + +\code +{% if kenny.sick %} + Kenny is sick. +{% elif kenny.dead %} + You killed Kenny! You bastard!!! +{% else %} + Kenny looks okay --- so far +{% endif %} +\endcode + +\section2 Tests +Beside filters, there are also so-called “tests” available. Tests can be used to test a variable +against a common expression. To test a variable or expression, its name is used followed by the +name of the test. For example, to find out if a variable is defined, one can try \e {name is +defined}, which will then return true or false depending on whether name is defined in the current +template context. + +Tests can accept arguments, too. If the test only takes one argument, one can leave out the +parentheses. For example, the following two expressions do the same thing: + +\code +{% if loop.index is divisibleby 3 %} +{% if loop.index is divisibleby(3) %} +\endcode + +The List of builtin tests can be found on the \l{http://jinja.pocoo.org/docs/2.9/ +templates/#builtin-tests}{Jinja documentation page}. +\section2 Filters + +Variables can be modified by functions called filters. Filters are separated from the variable by +a pipe symbol (|) and may have optional arguments in parentheses. Multiple filters can be chained. +The output of one filter is applied to the next. + +For example, {{ name|striptags|title }} will remove all HTML Tags from variable name and +title-case the output (title(striptags(name))). + +Filters that accept arguments have parentheses around the arguments, just like a function call. +For example: \code {{ listx|join(', ') }}\endcode will join a list with commas (equivalent to +\code str.join(', ', listx)\endcode). Nevertheless, the variable filter is applying to is always +passed as a first argument to the filter function. + +One can define custom filters by registering a Python function as a new filter with the +Environment object: + +\code +def lower_first_filter(s): + s = str(s) + return s[0].lower() + s[1:] + + +env = Environment( + loader=FileSystemLoader(search_path), + trim_blocks=True, + lstrip_blocks=True + ) +env.filters['lowerfirst'] = lower_first_filter +\endcode + +After that filter called lower first will be available from the template: +\code +{{ var | lowerfirst }} +\endcode + +A list of all supported filters can be found in the \l{Filter Reference}. + + +\section2 Variables +Template variables are defined by the context dictionary passed to the template. Variables can be +complex object having their own attributes. + +One can use a dot (.) to access attributes of a variable in addition to the standard Python +__getitem__ “subscript” syntax ([]). + +The following lines are equivalent: + +\code +{{ foo.bar }} +{{ foo['bar'] }} +\endcode + +If a variable or attribute does not exist, its value will result to undefined value. The +interpretation of that kind of value depends on the application configuration: the default +behavior is to evaluate to an empty string if printed or iterated over, and to fail for every +other operation. + +\section2 Comments + +To comment-out part of a line in a template, use the comment syntax which is by default set to {# +... #}. This is useful to comment out parts of the template for debugging or to add information +for other template designers or yourself: + +\code +{# note: commented-out template because we no longer use this + {% for user in users %} + ... + {% endfor %} +#} +\endcode + +\section2 Line Statements +\target line_statements + +If line statements are enabled by the application, it’s possible to mark a line as a statement. +For example, if the line statement prefix is configured to #, the following two examples are +equivalent: + +\code +<ul> +# for item in seq + <li>{{ item }}</li> +# endfor +</ul> +\endcode + +\code +<ul> +{% for item in seq %} + <li>{{ item }}</li> +{% endfor %} +</ul> +\endcode + +The line statement prefix can appear anywhere on the line as long as no text precedes it. For +better readability, statements that start a block (such as for, if, elif etc.) may end with a +colon: + +\code +# for item in seq: + ... +# endfor +\endcode + +Line statements can span multiple lines if there are open parentheses, braces or brackets: + +\code +<ul> +# for href, caption in [('index.html', 'Index'), + ('about.html', 'About')]: + <li><a href="{{ href }}">{{ caption }}</a></li> +# endfor +</ul> +\endcode + +Since Jinja 2.2, line-based comments are available as well. For example, if the line-comment +prefix is configured to be ##, everything from ## to the end of the line is ignored (excluding the +newline sign): + +\code +# for item in seq: + <li>{{ item }}</li> ## this comment is ignored +# endfor +\endcode + +\section2 Assignments + +Inside code blocks, you can also assign values to variables. Assignments at top level (outside of +blocks, macros or loops) are exported from the template like top level macros and can be imported +by other templates. + +Assignments use the set tag and can have multiple targets: + +\code +{% set navigation = [('index.html', 'Index'), ('about.html', 'About')] %} +{% set key, value = call_something() %} +\endcode + +It is not possible to set variables inside a block and have them show up outside of it. This also +applies to loops. The only exception to that rule are if statements which do not introduce a scope. + + +\section2 Whitespace Control + +In the default configuration: + +\list + \li a single trailing newline is stripped if present + \li other whitespace (spaces, tabs, newlines etc.) is returned unchanged +\endlist + +If an application configures Jinja to trim_blocks, the first newline after a template tag is +removed automatically (like in PHP). The lstrip_blocks option can also be set to strip tabs and +spaces from the beginning of a line to the start of a block. (Nothing will be stripped if there +are other characters before the start of the block) + +With both trim_blocks and lstrip_blocks enabled, you can put block tags on their own lines, and +the entire block line will be removed when rendered, preserving the whitespace of the contents. +For example, without the trim_blocks and lstrip_blocks options, this template: + +\code +<div> + {% if True %} + yay + {% endif %} +</div> +\endcode + +gets rendered with blank lines inside the div: + +\code +<div> + + yay + +</div> +\endcode + +But with both trim_blocks and lstrip_blocks enabled, the template block lines are removed and +other whitespace is preserved: + +\code +<div> + yay +</div> +\endcode + +One can manually disable the lstrip_blocks behavior by putting a plus sign (+) at the start of a +block: + +\code +<div> + {%+ if something %}yay{% endif %} +</div> +\endcode + +It's also possible to strip whitespace in templates by hand. With a minus sign (-) at the start or +end of a block (e.g. a For tag), a comment, or a variable expression, the whitespaces before or +after that block will be removed: + +\code +{% for item in seq -%} + {{ item }} +{%- endfor %} +\endcode + +This will yield all elements without whitespace between them. If seq was a list of numbers from 1 +to 9, the output would be 123456789. + +If Line Statements are enabled, they strip leading whitespace automatically up to the beginning of +the line. + +By default, Jinja2 also removes trailing newlines. To keep single trailing newlines, configure +Jinja to keep_trailing_newline. + +\note + +One must not add whitespace between the tag and the minus sign. + +valid: +\code +{%- if foo -%}...{% endif %} +\endcode +invalid: +\code +{% - if foo - %}...{% endif %} +\endcode + +*/ diff --git a/src/ivicore/doc/src/models.qdoc b/src/ivicore/doc/src/models.qdoc new file mode 100644 index 0000000..ac9a366 --- /dev/null +++ b/src/ivicore/doc/src/models.qdoc @@ -0,0 +1,115 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page models.html +\title Models +\previouspage Dynamic Backend System +\nextpage The Qt IVI Query Language +\contentspage Concepts + +For interacting with lists in Qt applications, you usually want to use Qt's ListView classes, which +are based on the Model-View-Controller pattern. QtIvi offers support classes, making it easy to +provide your own models. + +\section1 The QIviAbstractFeatureListModel + +When designing features like a contacts list of a connected mobile phone, you may want to use +QtIvi's frontend/backend separation by deriving from QIviAbstractFeature and at the same time make +it possible to use this feature with a QAbstractItemView derived class to show your contacts in a +list form. + +QtIviCore provides QIviAbstractFeatureListModel for this use-case. The class is derived from +QAbstractListModel, but also provides all the functionality from QIviAbstractFeature. + +\section1 The QIviSearchAndBrowseModel + +The QIviSearchAndBrowseModel is not directly a base class, but intended to be used as-is. As the +name suggests, it provides a model, that supports searching the model content as well as browsing +through a set of model data. Let's go through all its features in more detail: + +\section2 Fetch Modes + +As we don't have control over the interfaces of the data providers, the +QIviSearchAndBrowseModel +supports two distinct fetch modes: +\list 1 +\li If the number of items in the model is \b not known from the +beginning, the \l{QIviSearchAndBrowseModel::FetchMore}{FetchMore} mode should be used. This mode +will fetch a number of items from the backend once they are needed and the backend tells the +frontend whether there is more data to be fetched. + +\li The second fetch mode - \l{QIviSearchAndBrowseModel::DataChanged}{DataChanged} - will fill the +complete model with empty data and use the \l{QAbstractItemModel::dataChanged()} signal to tell the +View about the actual content. For this mode to work correctly, the number of items in the list +needs to be known from the beginning. +\endlist + +See the QIviSearchAndBrowseModel documentation for a more detailed description of the fetch modes +and their (dis)advantages. + +\section2 Modifying the Content + +QIviSearchAndBrowseModel provides some generic methods for modifying the content of the model: + +\list + \li \l{QIviSearchAndBrowseModel::insert}{insert()} + \li \l{QIviSearchAndBrowseModel::remove}{remove()} + \li \l{QIviSearchAndBrowseModel::move}{move()} +\endlist + +\section2 Filtering and Sorting (Search) + +For filtering and sorting, QIviSearchAndBrowseModel uses \l{the Qt IVI Query Language}. This makes +the system very flexible and powerful at the same time. See the \l {The Qt IVI Query Language}{next +page} for more information about the query language. + +\section2 Browsing + +Although the Qt IVI Query Language supports very complex queries, enabling you to filter list +content, it might still not be suitable for all use-cases. With the query language, the frontend +developer defines which data is needed next. This is sometimes not possible, as the backend already +defines a specific browsing order. A DLNA backend for example already specifies that first an +artist needs to be selected and only then a list of all albums of that artist is presented. + +For this scenario, the QIviSearchAndBrowseModel provides some methods to navigate through the +models using the following methods: + +\list + \li \l{QIviSearchAndBrowseModel::canGoForward}{canGoForward(index)} + \li \l{QIviSearchAndBrowseModel::goForward}{goForward(index)} + \li \l{QIviSearchAndBrowseModel::canGoBack}{canGoBack()} + \li \l{QIviSearchAndBrowseModel::goBack}{goBack()} +\endlist + +\section2 Capabilities + +You might not need all of the above features at the same time or your backend doesn't even support +them. In this case, there is a capability system within the QIviSearchAndBrowseModel. The backend +reports which capabilities it can support. Based on that information, only the supported +functionalities are enabled in the frontend API. + +*/ diff --git a/src/ivicore/doc/src/qt_attribution.json b/src/ivicore/doc/src/qt_attribution.json new file mode 100644 index 0000000..ae70c34 --- /dev/null +++ b/src/ivicore/doc/src/qt_attribution.json @@ -0,0 +1,17 @@ +{ + "Id": "jinja-documentation", + "Name": "Jinja Documentation", + "QDocModule": "qtivi", + "QtUsage": "Used in the Documentation of the Jinja template language", + "Path": "template-syntax.qdoc", + + "Description": "Full featured template engine for python.", + "Homepage": "http://jinja.pocoo.org/", + "Version": "2.9.6", + + "License": "BSD 3-clause License", + "LicenseId": "BSD-3-Clause", + "LicenseFile": "JINJA_LICENSE", + "Copyright": "(c) 2009 by the Jinja Team, see AUTHORS for more details." +} + diff --git a/src/ivicore/doc/src/qtivi-backends.qdoc b/src/ivicore/doc/src/qtivi-backends.qdoc new file mode 100644 index 0000000..1345436 --- /dev/null +++ b/src/ivicore/doc/src/qtivi-backends.qdoc @@ -0,0 +1,46 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! +\page qtivi-backends.html +\title QtIvi Backends + +All supported QtIvi Backends by module + +\annotatedlist qtivi_backend_groups + +A list of all QtIvi Backends can be found \l {All QtIvi Backends}{here}. +*/ + +/*! +\page qtivi-all-backends.html +\title All QtIvi Backends + +All supported QtIvi Backends + +\annotatedlist qtivi_backend +*/ diff --git a/src/ivicore/doc/src/qtivi-examples.qdoc b/src/ivicore/doc/src/qtivi-examples.qdoc new file mode 100644 index 0000000..eef5a0c --- /dev/null +++ b/src/ivicore/doc/src/qtivi-examples.qdoc @@ -0,0 +1,34 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! + \group qtivi-examples + \title Qt IVI Examples + + \brief All Qt IVI Examples by module + + These are the Qt IVI examples. +*/ diff --git a/src/ivicore/doc/src/qtivi-modules.qdoc b/src/ivicore/doc/src/qtivi-modules.qdoc new file mode 100644 index 0000000..d40bfa7 --- /dev/null +++ b/src/ivicore/doc/src/qtivi-modules.qdoc @@ -0,0 +1,71 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! + \page qtivi-modules.html + \title Qt IVI C++ Classes + + \brief C++ classes for Qt IVI. + + \section1 Modules + + Qt IVI contains the following modules: + \annotatedlist qtivi_modules + + \section1 Classes + + \section2 Qt IVI Core C++ Classes + \generatelist classesbymodule QtIviCore + + \section2 Qt IVI Vehicle Functions C++ Classes + \generatelist classesbymodule QtIviVehicleFunctions + + \section2 Qt IVI Media C++ Classes + \generatelist classesbymodule QtIviMedia +*/ + +/*! + \page qtivi-qmlmodules.html + \title Qt IVI QML Types + + \brief QML types for Qt IVI. + + \section1 QML Modules + + Qt IVI contains the following QML modules: + \annotatedlist qtivi_qmlmodules + + \section1 QML Types + + \section2 Qt IVI Core QML Types + \generatelist qmltypesbymodule QtIvi + + \section2 Qt IVI VehicleFunctions QML Types + \generatelist qmltypesbymodule QtIvi.VehicleFunctions + + \section2 Qt IVI Media QML Types + \generatelist qmltypesbymodule QtIvi.Media +*/ diff --git a/src/ivicore/doc/src/qtivi.qdoc b/src/ivicore/doc/src/qtivi.qdoc new file mode 100644 index 0000000..e399cdd --- /dev/null +++ b/src/ivicore/doc/src/qtivi.qdoc @@ -0,0 +1,100 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! + \page qtivi-index.html + \title Qt IVI + \keyword QtIvi + + The Qt IVI (In-Vehicle Infotainment) module provides C++ classes and QML types + for accessing vehicle features, as well as a core API for implementing + new IVI features manually or using a \l {The Qt IVI Autogenerator}{auto generator}. + + The module is built around a pattern based on the separation of API facing the + application developer, the so called \e {Feature}, and the code implementing it, + the \e {Backend}. There can be multiple backends per feature and the Core module + provides support for finding the corresponding backend in an easy-to-use way. + + Common use cases driving this separation are: + + \list + \li \e {Early development}, where the UI can rely on a feature with a very basic backend + implementation. + \li \e {Testing / Simulation}, where the backends can be tested separately from the app and the + app can be tested using a specialized testing backend. + \li \e {Targets with different hardware configurations}, where certain parts of the system are + represented by simulated backends while others use a real hardware integration. + \li \e {Dynamically appearing services}, when services are available sometimes, but not always, + meaning that backends come and go over time. + \endlist + + The module provides an extendable set of reference APIs for automotive + features. It can be used to develop automotive applications and to provide + automotive features to Qt-based applications in a structured manner. + + \section1 Important Topics + + \list + \li \l{Configuration} + \li \l{Concepts} + \li \l{Using the Qt IVI Reference API} + \li \l{Extending Qt IVI} + \li \l{QtIvi Backends}{Available Backends} + \endlist + + \section1 Getting Started + + \list + \li \l {Getting Started Using the Qt IVI Generator} + \li \l {Qt IVI Vehicle Functions C++ Classes#Getting Started} + {Getting started with Qt IVI Vehicle Functions (C++)} + \li \l {Qt IVI Vehicle Functions QML Types#Getting Started} + {Getting started with Qt IVI Vehicle Functions (QML)} + \endlist + + \section1 Reference + + \list + \li \l {Qt IVI C++ Classes} + \li \l {Qt IVI QML Types} + \li \l {Qt IVI Examples} + \endlist + + \section1 Licenses and Attributions + + Qt IVI is available under commercial Qt Automotive Suite licenses. + In addition, it is available under the \l{GNU Lesser General Public License, version 3}, or + See \l{Qt Licensing} for further details. + + Executables on Windows potentially link against \l{The qtmain Library}. This library is available + under commercial licenses, and in addition under the \l{BSD 3-clause "New" or "Revised" License}. + + Furthermore Qt IVI potentially contains third party modules under following + permissive licenses: + + \generatelist{groupsbymodule attributions-qtivi} + +*/ diff --git a/src/ivicore/doc/src/query-language.qdoc b/src/ivicore/doc/src/query-language.qdoc new file mode 100644 index 0000000..e704dde --- /dev/null +++ b/src/ivicore/doc/src/query-language.qdoc @@ -0,0 +1,266 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page query-language.html +\title The Qt IVI Query Language +\keyword Qt IVI Query Language +\previouspage Models +\contentspage Concepts + +Automotive systems are getting bigger and bigger and with it also the feature-set in areas like +entertainment or connectivity. Modern system can handle phone calls, access the mobile phone's addressbook, and have a mediaplayer +which can manage a media database similar to desktop tools like iTunes. As addressbooks and media databases +are quite big these days, it's important to be able to filter, sort and search them in a convenient way. + +Because of this the Qt IVI Query Language was created and it provides you with an own minimal +language to express what exactly you want to be displayed and how it should be sorted. + +It was chosen to create a new language to be independent on the underlying architecture and +its (potentially) underlying database languages like SQL or PSQL. Other than the two named, the Qt IVI Query Language +is not specifying the actual data itself and is just used for filtering and sorting. + +\section1 Working with the Query Language + +Currently the QIviSearchAndBrowseModel is the only class which supports the usage of the query language. In this +case the backend of the model informs the query parser about the identifiers available for filtering and sorting. + +An identifier is the name of a column or the property which can be used in the query language. Let's say you use the QIviSearchAndBrowseModel +to access a list of QIviAudioTrackItems, then the available identfiers will be every property of the QIviAudioTrackItem. Writing the following +query would result in a search for tracks on the album "Nevermind": + +\code +album='Nevermind' +\endcode + +\section2 Filtering and Sorting + +The Qt IVI Query Language has two parts: the first part being the filter specification, and the second part defining the sort order. + +\code +album='Nevermind' [/trackNumber] +\endcode + +In the query shown above the first part is \c{album='Nevermind'}, and it indicates to only show tracks which are from the album "Nevermind". The second +part is specified by \c{[]} and defines the ordering: in this case the result should be sorted by trackNumber in ascending order. + +\section3 Filtering + +For filtering a result the following operators can be used to match a identifier to a value: + +\table +\header + \li Operator + \li Description +\row + \li = + \li Tests whether the identifier's value is equal to the passed value. In case of a string the comparison is case-sensitive. + The \c{==} operator is an alias and delivers the same result. + +\row + \li != + \li Tests whether the identifier's value is not equal to the passed value. In case of a string the comparison is case-sensitive. + +\row + \li ~= + \li Tests whether the identifier's value is equal to the passed value, but the comparison is done case-insensitive. + +\row + \li > + \li Tests whether the lefthand-side value is greater than the righthand-side value. (only works for numbers). + +\row + \li >= + \li Tests whether the lefthand-side value is greater than or equal to the righthand-side value. (only works for numbers). + +\row + \li < + \li Tests whether the lefthand-side value is less than the righthand-side value. (only works for numbers). + +\row + \li <= + \li Tests whether the lefthand-side value is less than or equal to the righthand-side value. (only works for numbers). + +\endtable + +When comparing an identifier against a string, the string always needs to be encapsulated either between two quotation marks - either single \c{'} or double \c{"} ones. +Numbers are supported in various formats, including signed and unsigned numbers and floats using an exponent e.g. -5.0E15. + +\section3 Sorting + +The second part of a query is used for sorting the result. It's optional and if not provided, the backend can decide in which order the result +should be listed. To sort by trackNumber in ascending order use the following code: + +\code +[/trackNumber] +\endcode + +to sort in descending order: + +\code +[\trackNumber] +\endcode + +Using this query on a big list of songs might not give the intendend result as there could be two different tracks having the same trackNumber. +For this case multiple sort orders can be provided. + +\code +[\trackNumber][/album] +\endcode + +The above query would sort the tracks by trackNumber in descending order and the track with the same trackNumber by album name in ascending order. + +\section2 Conjunctions + +Only adding a specific condition and defining the order is often not enough to achieve the wanted result. The Qt IVI Query Language also supports +basic boolean algebra. Multiple filters can be combined by using AND / OR conjunctions. The following query would only list the first 5 tracks +of the album 'Metallica': + +\code +album='Metallica' & trackNumber<=5 +\endcode + +Of course it's also supported to use brackets as well as to negate filters: + +\code +(album='Metallica') & !(trackNumber>5) +\endcode + +\section1 Backend integration + +For the backend, the query is translated from a string to a binary representation similar to an AST. Like the query itself, the representation is split into two +parts: the first part is a pointer to a QIviAbstractQueryTerm which can be cast to one of the following types: + +\annotatedlist qtivi_queryterms + +The second part is a QList<QIviOrderTerm> and provides the ordering the user wants the result to be in. + +Usually this C++ representation is translated into whatever form the backend supports. For getting the results from an SQL database this can look like this: + +First we need a function to translate the identifiers used in the query to the column names used in the database: +\code +QString SearchAndBrowseBackend::mapIdentifiers(const QString &type) +{ + if (type == QLatin1String("artist")) + return QLatin1String("artistName"); + else if (type == QLatin1String("album")) + return QLatin1String("albumName"); + else if (type == QLatin1String("track")) + return QLatin1String("trackName"); + else + return type; +} +\endcode + +Next we need functions to translate the QueryTerms and the OrderTerms into SQL clauses: + +\code +QString SearchAndBrowseBackend::createSortOrder(const QString &type, const QList<QIviOrderTerm> &orderTerms) +{ + QStringList order; + int i = 0; + for (const QIviOrderTerm & term : orderTerms) { + if (i) + order.append(","); + + order.append(mapIdentifiers(term.propertyName())); + if (term.isAscending()) + order.append("ASC"); + else + order.append("DESC"); + + i++; + } + + return order.join(' '); +} + +QString SearchAndBrowseBackend::createWhereClause(QIviAbstractQueryTerm *term) +{ + if (!term) + return QString(); + + switch (term->type()) { + case QIviAbstractQueryTerm::ScopeTerm: { + QIviScopeTerm *scope = static_cast<QIviScopeTerm*>(term); + return QString(QLatin1String("%1 (%2)")).arg(scope->isNegated() ? "NOT" : "",createWhereClause(scope->term())); + } + case QIviAbstractQueryTerm::ConjunctionTerm: { + QIviConjunctionTerm *conjunctionTerm = static_cast<QIviConjunctionTerm*>(term); + QString conjunction = QLatin1String("AND"); + if (conjunctionTerm->conjunction() == QIviConjunctionTerm::Or) + conjunction = QLatin1String("OR"); + + QString string; + QListIterator<QIviAbstractQueryTerm*> it(conjunctionTerm->terms()); + while (it.hasNext()) { + string += createWhereClause(it.next()); + if (it.hasNext()) + string += QLatin1Literal(" ") + conjunction + QLatin1Literal(" "); + } + return string; + } + case QIviAbstractQueryTerm::FilterTerm: { + QIviFilterTerm *filter = static_cast<QIviFilterTerm*>(term); + QString operatorString; + bool negated = filter->isNegated(); + QString value; + if (filter->value().type() == QVariant::String) + value = QString(QLatin1String("'%1'")).arg(filter->value().toString().replace('*', '%')); + else + value = filter->value().toString(); + + switch (filter->operatorType()){ + case QIviFilterTerm::Equals: operatorString = QLatin1String("="); break; + case QIviFilterTerm::EqualsCaseInsensitive: operatorString = QLatin1String("LIKE"); break; + case QIviFilterTerm::Unequals: operatorString = QLatin1String("="); negated = !negated; break; + case QIviFilterTerm::GreaterThan: operatorString = QLatin1String(">"); break; + case QIviFilterTerm::GreaterEquals: operatorString = QLatin1String(">="); break; + case QIviFilterTerm::LowerThan: operatorString = QLatin1String("<"); break; + case QIviFilterTerm::LowerEquals: operatorString = QLatin1String("<="); break; + } + + QStringList clause; + if (negated) + clause.append(QLatin1String("NOT")); + clause.append(mapIdentifiers(filter->propertyName())); + clause.append(operatorString); + clause.append(value); + + return clause.join(" "); + } + } + + return QString(); +} +\endcode + +The actual query can then be created like this: + +\code +QString query = QString(QLatin1String("SELECT * FROM tracks WHERE %1 ORDER BY %2")).arg(createWhereClause(queryTerm), createSortOrder(orderTerms)); +\endcode +*/ diff --git a/src/ivicore/doc/src/reference-api.qdoc b/src/ivicore/doc/src/reference-api.qdoc new file mode 100644 index 0000000..d1bab1d --- /dev/null +++ b/src/ivicore/doc/src/reference-api.qdoc @@ -0,0 +1,60 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page reference-api.html +\title Using the Qt IVI Reference API + +\section1 Overview + +The Qt IVI module contains a reference API providing interfaces to common automotive +functionality. These APIs rely on the separation of the front-end API and the backend +implementation. The Qt IVI module also introduces a set of concepts used in the APIs: +zones and property attributes. More about the concepts can be read \l {Concepts} {here}. + +\section1 Modules + +Qt IVI consists of the following C++ modules: + +\annotatedlist qtivi_modules + +\b {Qt IVI Core} provides core base classes for the Qt IVI features, +and handles the discovery of Qt IVI backend plugins. Application +developers do not need to use Qt IVI Core directly. It is only needed +when implementing a new IVI feature, such as Qt IVI Vehicle Functions +ClimateControl. + +\b {Qt IVI Vehicle Functions} provides interfaces to access vehicle +features. + +\b {Qt IVI Media} provides interfaces to access media related APIs e.g. +Managing your music playlist or controlling the radio tuner. + +The functionality provided by these modules is available to QML +applications: + +\annotatedlist qtivi_qmlmodules +*/ diff --git a/src/ivicore/ivicore.pro b/src/ivicore/ivicore.pro index 80dc964..8bfcc09 100644 --- a/src/ivicore/ivicore.pro +++ b/src/ivicore/ivicore.pro @@ -3,9 +3,19 @@ TARGET = QtIviCore QT = core core-private qml qml-private CONFIG += c++11 -OTHER_FILES += \ +build_online_docs: { + QMAKE_DOCS = $$PWD/doc/online/qtivi.qdocconf +} else { + QMAKE_DOCS = $$PWD/doc/qtivi.qdocconf +} + +DISTFILES += \ $$PWD/doc/*.qdocconf \ - $$PWD/doc/src/*.qdoc + $$PWD/doc/online/*.qdocconf \ + $$PWD/doc/src/*.qdoc \ + $$PWD/doc/src/ivigenerator/*.qdoc \ + $$PWD/doc/images/*.jpg \ + $$PWD/doc/images/*.png CMAKE_MODULE_TESTS = '-' @@ -64,3 +74,4 @@ SOURCES += \ include(queryparser/queryparser.pri) load(qt_module) +QMAKE_DOCS_TARGETDIR = qtivi diff --git a/src/ivicore/qiviabstractfeature.cpp b/src/ivicore/qiviabstractfeature.cpp index 858b7f4..bdcba6f 100644 --- a/src/ivicore/qiviabstractfeature.cpp +++ b/src/ivicore/qiviabstractfeature.cpp @@ -130,7 +130,7 @@ void QIviAbstractFeaturePrivate::onInitializationDone() QIviAbstractFeature is an abstract base class that needs to be subclassed to create an API for your Feature. - \chapter Subclassing + \section1 Subclassing When subclassing QIviAbstractFeature, you must provide implementations of the following functions: \list diff --git a/src/ivicore/qivipendingreply.cpp b/src/ivicore/qivipendingreply.cpp index 78e4559..e7bcde9 100644 --- a/src/ivicore/qivipendingreply.cpp +++ b/src/ivicore/qivipendingreply.cpp @@ -782,14 +782,14 @@ void QIviPendingReplyBase::setSuccessNoCheck(const QVariant &value) \fn QIviPendingReplyWatcher::valueChanged(const QVariant &value) Emitted when the result for the reply is ready. This signal is called when the reply is - successful as well as when it is failed. The \value argument holds the result and is a default + successful as well as when it is failed. The \a value argument holds the result and is a default constructed QVariant in the failed case. \sa setSuccess setFailed */ /*! - \fn QIviPendingReply::createFailedReply() + \fn template <class T> QIviPendingReply<T>::createFailedReply() Creates a reply object which is marked as failed. This is convenient in error cases inside functions returning a reply e.g. @@ -810,7 +810,7 @@ void QIviPendingReplyBase::setSuccessNoCheck(const QVariant &value) */ /*! - \fn QIviPendingReply::reply() const + \fn template <class T> QIviPendingReply<T>::reply() const Returns the result of the reply. If no result has been set yet or when the reply is marked as failed, a default constructed value is returned. @@ -819,7 +819,7 @@ void QIviPendingReplyBase::setSuccessNoCheck(const QVariant &value) */ /*! - \fn QIviPendingReply::setSuccess(const T &value) + \fn template <class T> QIviPendingReply<T>::setSuccess(const T &value) Sets the result of the reply to \a value and marks the reply as succeeded. @@ -829,10 +829,10 @@ void QIviPendingReplyBase::setSuccessNoCheck(const QVariant &value) */ /*! - \fn qIviRegisterPendingReplyType(const char *typeName) + \fn qIviRegisterPendingReplyType(const char *name) \relates QIviPendingReply - Registers the type name \a typeName for the type \c{T} for usage inside a QIviPendingReply. Any + Registers the type name \a name for the type \c{T} for usage inside a QIviPendingReply. Any class or struct that has a public default constructor, a public copy constructor and a public destructor can be registered. diff --git a/src/ivicore/qivipropertyattribute.cpp b/src/ivicore/qivipropertyattribute.cpp index 0e16ed0..0423a03 100644 --- a/src/ivicore/qivipropertyattribute.cpp +++ b/src/ivicore/qivipropertyattribute.cpp @@ -93,7 +93,7 @@ void QIviPropertyAttributeBase::registerTypes() */ /*! - \fn QIviPropertyAttribute::QIviPropertyAttribute() + \fn template <class T> QIviPropertyAttribute<T>::QIviPropertyAttribute() Constructs an invalid QIviPropertyAttribute. This constructor can be used to indicate that the property is not available. @@ -101,67 +101,67 @@ void QIviPropertyAttributeBase::registerTypes() */ /*! - \fn QIviPropertyAttribute::QIviPropertyAttribute(bool available) + \fn template <class T> QIviPropertyAttribute<T>::QIviPropertyAttribute(bool available) Constructs an QIviPropertyAttribute of type NoAttributes. The argument \a available defines whether the property is supported by the backend. */ /*! - \fn QIviPropertyAttribute::QIviPropertyAttribute(const T &minValue, const T &maxValue) + \fn template <class T> QIviPropertyAttribute<T>::QIviPropertyAttribute(const T &minValue, const T &maxValue) Constructs an QIviPropertyAttribute of type MinimumMaximum. The arguments \a minValue and \a maxValue define the boundaries the value of the property. */ /*! - \fn QIviPropertyAttribute::QIviPropertyAttribute(const QVector<T> &avValues) + \fn template <class T> QIviPropertyAttribute<T>::QIviPropertyAttribute(const QVector<T> &avValues) Constructs an QIviPropertyAttribute of type AvailableValues. The argument \a avValues defines the valid values for the property. */ /*! - \fn AttributeType QIviPropertyAttribute::type() const + \fn template <class T> AttributeType QIviPropertyAttribute<T>::type() const Returns the type of the attribute. */ /*! - \fn bool QIviPropertyAttribute::isAvailable() const + \fn template <class T> bool QIviPropertyAttribute<T>::isAvailable() const Returns true if the property is available for this backend. */ /*! - \fn T QIviPropertyAttribute::minimumValue() const + \fn template <class T> T QIviPropertyAttribute<T>::minimumValue() const Returns the minimum value of the property. If the attributeType is not MinimumMaximum, a default constructed value is returned. */ /*! - \fn T QIviPropertyAttribute::maximumValue() const + \fn template <class T> T QIviPropertyAttribute<T>::maximumValue() const Returns the maximum value of the property. If the attributeType is not MinimumMaximum, a default constructed value is returned. */ /*! - \fn QList<T> QIviPropertyAttribute::availableValues() const + \fn template <class T> QList<T> QIviPropertyAttribute<T>::availableValues() const Returns a list of valid values for this property. If the attributeType is not AvailableValues an empty list is returned. */ /*! - \fn QString QIviPropertyAttribute::toString() const + \fn template <class T> QString QIviPropertyAttribute<T>::toString() const Returns a QString with a string representation of the attribute. */ /*! - \fn bool QIviPropertyAttribute::operator==(const QIviPropertyAttribute& other) const + \fn template <class T> bool QIviPropertyAttribute<T>::operator==(const QIviPropertyAttribute& other) const Returns \c true if this QIviPropertyAttribute is equal to the \a other QIviPropertyAttribute; otherwise returns \c false. @@ -169,7 +169,7 @@ void QIviPropertyAttributeBase::registerTypes() */ /*! - \fn bool QIviPropertyAttribute::operator!=(const QIviPropertyAttribute& other) const + \fn template <class T> bool QIviPropertyAttribute<T>::operator!=(const QIviPropertyAttribute& other) const Returns \c true if this QIviPropertyAttribute is NOT equal to the \a other QIviPropertyAttribute; otherwise returns \c false. diff --git a/src/ivicore/qivipropertyfactory.cpp b/src/ivicore/qivipropertyfactory.cpp index 0dfafa0..72f320a 100644 --- a/src/ivicore/qivipropertyfactory.cpp +++ b/src/ivicore/qivipropertyfactory.cpp @@ -66,7 +66,7 @@ QT_BEGIN_NAMESPACE */ /*! - \fn QIviPropertyFactory::create(const QtPrivate::FunctionPointer<attributeGetterFunc>::Object *sender, attributeGetterFunc attributeGetter, attributeSignalFunc attributeSignal, valueGetterFunc valueGetter, valueSignalFunc valueSignal, valueSlotFunc valueSlot) + \fn template <class T, typename attributeGetterFunc, typename attributeSignalFunc, typename valueGetterFunc, typename valueSignalFunc, typename valueSlotFunc> QIviPropertyFactory<T>::create(const typename QtPrivate::FunctionPointer<attributeGetterFunc>::Object *sender, attributeGetterFunc attributeGetter, attributeSignalFunc attributeSignal, valueGetterFunc valueGetter, valueSignalFunc valueSignal, valueSlotFunc valueSlot) Returns an new QIviProperty instance for a attribute and value of type T. @@ -75,12 +75,10 @@ QT_BEGIN_NAMESPACE These arguments need to be of QIviPropertyAttribute<T>. \a valueGetter, \a valueSignal, and \a valueSlot need to be function pointers to the getter, signal, and setter for the value that should be stored in this QIviQmlProperty instance. The value functions need to have arguments and return values of type T. - - \sa QIviPropertyFactory::create(const QtPrivate::FunctionPointer<attributeGetterFunc>::Object *sender, attributeGetterFunc attributeGetter, attributeSignalFunc attributeSignal, valueGetterFunc valueGetter, valueSignalFunc valueSignal) */ /*! - \fn QIviPropertyFactory::create(const QtPrivate::FunctionPointer<attributeGetterFunc>::Object *sender, attributeGetterFunc attributeGetter, attributeSignalFunc attributeSignal, valueGetterFunc valueGetter, valueSignalFunc valueSignal) + \fn template <class T, typename attributeGetterFunc, typename attributeSignalFunc, typename valueGetterFunc, typename valueSignalFunc> QIviPropertyFactory<T>::create(const typename QtPrivate::FunctionPointer<attributeGetterFunc>::Object *sender, attributeGetterFunc attributeGetter, attributeSignalFunc attributeSignal, valueGetterFunc valueGetter, valueSignalFunc valueSignal) Returns a new QIviProperty instance for an attribute and value of type T. @@ -91,36 +89,34 @@ QT_BEGIN_NAMESPACE The value functions need to have arguments and return values of type T. \note This factory function will create a readonly property as no value setter needs to be provided - - \sa QIviPropertyFactory::create(const QtPrivate::FunctionPointer<attributeGetterFunc>::Object *sender, attributeGetterFunc attributeGetter, attributeSignalFunc attributeSignal, valueGetterFunc valueGetter, valueSignalFunc valueSignal, valueSlotFunc valueSlot) */ /*! - \fn bool QIviPropertyFactory::isAvailable() const + \fn template <class T> bool QIviPropertyFactory<T>::isAvailable() const \reimp */ /*! - \fn bool QIviPropertyFactory::minimumValue() const + \fn template <class T> bool QIviPropertyFactory<T>::minimumValue() const \reimp */ /*! - \fn bool QIviPropertyFactory::maximumValue() const + \fn template <class T> bool QIviPropertyFactory<T>::maximumValue() const \reimp */ /*! - \fn bool QIviPropertyFactory::availableValues() const + \fn template <class T> bool QIviPropertyFactory<T>::availableValues() const \reimp */ /*! - \fn bool QIviPropertyFactory::value() const + \fn template <class T> bool QIviPropertyFactory<T>::value() const \reimp */ diff --git a/src/ivicore/qivisearchandbrowsemodel.cpp b/src/ivicore/qivisearchandbrowsemodel.cpp index 637aecc..5c3b0b8 100644 --- a/src/ivicore/qivisearchandbrowsemodel.cpp +++ b/src/ivicore/qivisearchandbrowsemodel.cpp @@ -1300,7 +1300,7 @@ QIviPendingReply<void> QIviSearchAndBrowseModel::move(int cur_index, int new_ind /*! \fn void QIviSearchAndBrowseModel::indexOf(const QVariant &variant) - Determines the index of \a item in this model. + Determines the index of \a variant in this model. The result is returned as a QIviPendingReply. */ diff --git a/src/ivicore/qivisearchandbrowsemodelinterface.cpp b/src/ivicore/qivisearchandbrowsemodelinterface.cpp index 7342f6a..a549409 100644 --- a/src/ivicore/qivisearchandbrowsemodelinterface.cpp +++ b/src/ivicore/qivisearchandbrowsemodelinterface.cpp @@ -103,7 +103,7 @@ QSet<QString> QIviSearchAndBrowseModelInterface::supportedIdentifiers(const QStr /*! - \fn registerContentType(const QString &contentType) + \fn template <class T> QIviSearchAndBrowseModelInterface::registerContentType(const QString &contentType) Registers the type T with the name \a contentType. In addition all properties of type T will be registered as identifiers for the \l {Qt IVI Query Language} diff --git a/src/ivicore/qiviservicemanager.cpp b/src/ivicore/qiviservicemanager.cpp index ff6af67..b5de5c2 100644 --- a/src/ivicore/qiviservicemanager.cpp +++ b/src/ivicore/qiviservicemanager.cpp @@ -418,6 +418,17 @@ QIviServiceInterface *QIviServiceManagerPrivate::loadServiceBackendInterface(str */ /*! + \enum QIviServiceManager::Roles + \value NameRole + The name of the backend e.g. MediaPlugin + \value ServiceObjectRole + The actual QIviServiceObject, which can be used to connect a frontend API to this backend. + \note When using this role in the data() function, the backend plugin will be loaded and instantiated. + \value InterfacesRole + A list of interefaces the backend implements. +*/ + +/*! \enum QIviServiceManager::SearchFlag \value IncludeProductionBackends |
