summaryrefslogtreecommitdiffstats
path: root/examples/interfaceframework
diff options
context:
space:
mode:
authorNicholas Bennett <nicholas.bennett@qt.io>2021-10-21 09:40:16 +0300
committerNicholas Bennett <nicholas.bennett@qt.io>2021-11-02 19:13:48 +0300
commit3b71d309d8cd32e2bd89f75ce12b61f5ec600d71 (patch)
tree348dad1e45b56e329ea02a895a30c03ddfda0116 /examples/interfaceframework
parentff0db1360ca9dd83661acc41ab4795d7dae42029 (diff)
Docs: 6.2 release review
Spelling and grammar check Applied principles of Qt Documentation guidelines where applicable Update the index page with some info from the "big picture" section from the extending qtIF page. Focused on the core module in this review. Future work could include breaking the chapters in the qface tutorial out into pages. Task-number: QTBUG-97118 Pick-to: 6.2 Change-Id: I3ac094f0ccafbb82995d7a4c8f3969d92db429be Reviewed-by: Dominik Holland <dominik.holland@qt.io>
Diffstat (limited to 'examples/interfaceframework')
-rw-r--r--examples/interfaceframework/qface-addressbook/doc/src/qface-addressbook.qdoc33
-rw-r--r--examples/interfaceframework/qface-climate/doc/src/qface-climate.qdoc53
-rw-r--r--examples/interfaceframework/qface-tutorial/doc/src/qface-tutorial.qdoc208
3 files changed, 149 insertions, 145 deletions
diff --git a/examples/interfaceframework/qface-addressbook/doc/src/qface-addressbook.qdoc b/examples/interfaceframework/qface-addressbook/doc/src/qface-addressbook.qdoc
index b6958c35..227c1b8c 100644
--- a/examples/interfaceframework/qface-addressbook/doc/src/qface-addressbook.qdoc
+++ b/examples/interfaceframework/qface-addressbook/doc/src/qface-addressbook.qdoc
@@ -45,30 +45,31 @@ general introduction to the Qt Interface Framework Generator, please have a look
\section2 Walkthrough
-The IDL file used in the example represents an addressbook API. It contains a single interface
-providing the contacts as a model and a struct definition for the actual contact.
+The Interface Definition Language (IDL) file used in the example represents an address book API.
+It contains a single interface providing the contacts as a model and a \c struct
+definition for the actual contact.
\snippet interfaceframework/qface-addressbook/example-addressbook.qface 0
The \e contact property is defined to be of type \e model<Contact>. The \l frontend template will
create a C++ property of type \l {QIfPagingModel}{QIfPagingModel*}. The getter function of this
-property returns a valid instance once a backend is connected and the properties are initialized.
+property returns a valid instance once a back end is connected and the properties are initialized.
This QIfPagingModel instance can be used from C++, as well as from QML and already provides the
basic functionality for retrieving its data in an optimized fashion using the so called \e
Pagination concept.
-For the backend interface the property type is different and will be a \l QIfPagingModelInterface
+For the back end interface the property type is different and will be a \l QIfPagingModelInterface
pointer. This is needed as the QIfPagingModel is also a QtInterfaceFramework feature and, like all features, it
-uses a backend interface for the frontend-backend separation. For more information, see
+uses a back end interface for the front end-back end separation. For more information, see
\l{Concepts and Architecture}.
-The backend plugin needs to implement the \l QIfPagingModelInterface class for every exposed
+The back end plugin needs to implement the \l QIfPagingModelInterface class for every exposed
property.
The \l backend_simulator template already takes care of this and generates all the needed code.
-\section1 Configuring the Simulation Backend Plugin
+\section1 Configuring the Simulation Back End Plugin
-By default the generated simulation backend does not populate any data for the model, as the
+By default the generated simulation back end does not populate any data for the model, as the
template doesn't know what content it should provide.
For this use-case the \l {config_simulator_default}{default} annotation can be used to configure
@@ -79,7 +80,7 @@ This is done in the example-addressbook.yaml file:
\quotefile interfaceframework/qface-addressbook/example-addressbook.yaml
The JSON fragment assigned to the \l {config_simulator_default}{default} variable is parsed by the
-Qt Interface Framework Generator and will be used to generate a simulation backend which creates two Contact
+Qt Interface Framework Generator and will be used to generate a simulation back end which creates two Contact
instances and returns them as content for the contacts model.
\section1 Demo Application
@@ -115,16 +116,16 @@ resource file is added to the build system like this.
\section2 Providing the simulation behavior in QML
-The autogenerated simulation backend code loads the simulation behavior from a QML file using a
-QIfSimulationEngine. This special engine makes sure the autogenerated backend interfaces are
+The auto-generated simulation back end code loads the simulation behavior from a QML file using a
+QIfSimulationEngine. This special engine makes sure the auto-generated back end interfaces are
provided to the QML file and they can be extended from there. It also makes sure that the
interfaces are available only to this engine instance and to no other engine running in the same
process (e.g. in the frontend). See the QIfSimulationEngine documentation for more information
about how the engine works.
-Using the ifcodegen for the simulation backend, the simulation interfaces are provided in the \e
-example.if.addressbook.simulation uri. The provided types are named after the backend interfaces
-implemented by the simulation backend. For our example two types are registered:
+Using the ifcodegen for the simulation back end, the simulation interfaces are provided in the \e
+example.if.addressbook.simulation uri. The provided types are named after the back end interfaces
+implemented by the simulation back end. For our example two types are registered:
\list
\li AddressBookBackend
@@ -140,13 +141,13 @@ the Component.onCompleted handler.
To implement the behavior for the insertContact function, a JS function is added to the
AddressBookBackend object in QML. This function takes three arguments, the first one is an
-PendingReply object used to notify the frontend once the request was successful or failed. The
+PendingReply object used to notify the front end once the request was successful or failed. The
other arguments are as defined in the IDL file.
To insert the provided contact to our list we use the \e contacts property which hold the
implementation of the QIfPagingModelInterface for the contacts property. This implementation
provides some extra convenience functions which can be used by the simulation to modify the model
-in an easy way. In our case we just call the \c insert() function and let the autogenerated
+in an easy way. In our case we just call the \c insert() function and let the auto-generated
implementation do the rest.
*/
diff --git a/examples/interfaceframework/qface-climate/doc/src/qface-climate.qdoc b/examples/interfaceframework/qface-climate/doc/src/qface-climate.qdoc
index 7cfc0ac1..cac8f585 100644
--- a/examples/interfaceframework/qface-climate/doc/src/qface-climate.qdoc
+++ b/examples/interfaceframework/qface-climate/doc/src/qface-climate.qdoc
@@ -36,19 +36,20 @@
\section1 Introduction
-This example shows you how you can use the Qt Interface Framework Generator to build a new component. Based on a
-single QFace IDL file, the example generates:
+This example shows you how you can use the Qt Interface Framework Generator to
+build a new component. Based on a single QFace Interface Definition Language
+(IDL) file, the example generates:
\list
- \li a shared library with the frontend code
- \li a backend simulator plugin
+ \li a shared library with the front end code
+ \li a back end simulator plugin
\li a demo application that shows the values in the current module
\endlist
\section1 The IDL File
-The IDL file used in this example represents a simplified climate control interface that contains a
-single interface and some enumerated types.
+The IDL file used in this example represents a simplified climate control
+interface that contains a single interface and some enumerated types.
Let's take a look at a minimal version of the same QFace IDL file:
@@ -179,7 +180,7 @@ Here's an overview of all the annotations used in this example and what they do:
instances.
\endtable
-In addition to the IDL file, a YAML file with the same basename is used to add extra
+In addition to the IDL file, a YAML file with the same base name is used to add extra
configurations. These configurations may also be added directly into the IDL file, but we choose
to keep them separate for readability.
@@ -201,11 +202,11 @@ Some of these extra configurations are highlighted below:
config_simulator:
default: RecirculationMode.RecirculationOff
\endcode
- \li Specifies the default value assigned to a property in the simulator backend plugin.
+ \li Specifies the default value assigned to a property in the simulator back end plugin.
\endtable
-\section1 Frontend Library
+\section1 Front End Library
Now we want to use the Interface Framework Generator to generate a shared library that contains a C++
implementation of our module and its interface.
@@ -248,12 +249,13 @@ additional code to report errors:
The other part of the project file is a normal library setup which should work on Linux, macOS,
and Windows.
-\section1 Backend Simulator Plugin
+\section1 Back End Simulator Plugin
-Since the \c frontend library uses the \l {Dynamic Backend System}, we need a corresponding
-\c backend plugin, for the library to provide some functionality. To generate a mock version of
-the backend plugin called "Simulator Backend", you can use the \c backend_simulator template from
-the same IDL file as the \c frontend library. The build system integration works in the same way, but it
+Since the \c{front end} library uses the \l {Dynamic Backend System}, we need a corresponding
+\c{back end} plugin, for the library to provide some functionality. To generate a mock version of
+the back end plugin called "Simulator Backend", you can use the \c backend_simulator template from
+the same IDL file as the \c{front end} library uses the \l {Dynamic Backend System}, we need a corresponding
+\c{back end} plugin, fo library. The build system integration works in the same way, but it
uses a different generation template.
\e CMake:
@@ -274,21 +276,21 @@ For the plugin to compile correctly it needs to get the backend interface header
created library. However, this header is not part of our source tree but the build tree, because it
is also generated. We provide this header by adding it to the include path using the following code:
-\e CMake:
-
-\snippet interfaceframework/qface-climate/backend_simulator/CMakeLists.txt 1
-
\e qmake:
\snippet interfaceframework/qface-climate/backend_simulator/backend_simulator.pro 1
+\e CMake:
+
+\snippet interfaceframework/qface-climate/backend_simulator/CMakeLists.txt 1
+
The \c backend_simulator template makes use of the \b @config_simulator annotations explained
-\l{Annotations}{above}. This means that the generated backend provides the default values defined
+\l{Annotations}{above}. This means that the generated back end provides the default values defined
in the annotations and checks the boundaries of new values using the \c minimum/maximum or \c range
annotations.
-Using the \c zones annotations, the generated backend provides individual values for every zone
-and communicates the available zones to the frontend library. For more information, see the
+Using the \c zones annotations, the generated back end provides individual values for every zone
+and communicates the available zones to the front end library. For more information, see the
\l {Climate Control QML Example}.
\section1 Demo Application
@@ -296,9 +298,9 @@ and communicates the available zones to the frontend library. For more informati
The demo application presents a simple QML interface with all the properties of the generated
interface.
-Since we do not provide a QML plugin, the application needs to link to the generated frontend
+Since we do not provide a QML plugin, the application needs to link to the generated front end
library and call the \c {ClimateModule::registerTypes} and \c {ClimateModule::registerQmlTypes}
-methods that are generated in the module singleton to register all autogenerated interfaces and
+methods that are generated in the module singleton to register all auto-generated interfaces and
types with the QML engine.
In our QML application, we still need to import the module using the same module URI used
@@ -307,12 +309,13 @@ in the IDL file. Afterwards, the interface can be instantiated like a regular QM
\snippet interfaceframework/qface-climate/demo/main.qml 0
\dots 0
-Our application doesn't know about our backend plugin, so, we need to put this plugin in the folder
+Our application doesn't know about our back end plugin, so, we need to put this plugin in the folder
where our application looks for plugins. By default, Qt looks in the \b plugins folder within its
installation directory or in the application's current working directory. For QtInterfaceFramework plugins to be
found, they need to be placed within a \b interfaceframework sub-folder.
-To make sure this is done automatically, we add the following line to our backend build system file:
+To make sure this is done automatically, we add the following line to our back end
+build system file:
\e CMake:
diff --git a/examples/interfaceframework/qface-tutorial/doc/src/qface-tutorial.qdoc b/examples/interfaceframework/qface-tutorial/doc/src/qface-tutorial.qdoc
index 0d03ce58..031f0143 100644
--- a/examples/interfaceframework/qface-tutorial/doc/src/qface-tutorial.qdoc
+++ b/examples/interfaceframework/qface-tutorial/doc/src/qface-tutorial.qdoc
@@ -33,20 +33,20 @@
\title Qt Interface Framework Generator Tutorial
\image qface-tutorial.png
- This tutorial demonstrates how you can extend a QML application with your own autogenerated
+ This tutorial demonstrates how you can extend a QML application with your own auto-generated
Middleware API. We use an existing QML Instrument Cluster application and proceed through the
following steps:
\list 1
- \li \l{chapter1}{Integrate a basic interface without a backend}
+ \li \l{chapter1}{Integrate a basic interface without a back-end}
\li \l{chapter2}{Extend the interface and add annotations}
- \li \l{chapter3}{Add a simulation backend and corresponding simulation annotations; with a QML plugin}
+ \li \l{chapter3}{Add a simulation back end and corresponding simulation annotations; with a QML plugin}
\li \l{chapter4}{Add a custom simulation behavior}
- \li \l{chapter5}{Add a simulation server and use it from a Qt Remote Objects Backend}
- \li \l{chapter6}{Develop a production backend that connects to a DBus interface}
+ \li \l{chapter5}{Add a simulation server and use it from a Qt Remote Objects Back End}
+ \li \l{chapter6}{Develop a production back end that connects to a DBus interface}
\endlist
- Before we start the actual Middleware integration, let's take a look at the existing Instrument
+ Before we start the actual middleware integration, let's take a look at the existing Instrument
Cluster QML code and all the features it supports:
\list
\li \c images -- This folder contains all images used in the QML code.
@@ -82,13 +82,13 @@
In this chapter we integrate a Middleware API into the existing Instrument Cluster QML code.
Instead of manually writing all of these parts ourselves, which is done in most basic
- \l{https://doc.qt.io/qt-5/qtquick-codesamples.html}{QML examples}, we'll use the Interface Framework Generator
- to autogenerate the required parts.
+ \l{https://doc.qt.io/qt-6/qtquick-codesamples.html}{QML examples}, we'll use the Interface Framework Generator
+ to auto-generate the required parts.
\target define-speed-property
\section2 Interface Definition Language
- To be able to autogenerate the Middleware API, the Interface Framework Generator needs some input on what to
+ To be able to auto-generate the Middleware API, the Interface Framework Generator needs some input on what to
generate. This input is given in form of an Interface Definition Language (IDL), QFace, which
describes the API in a very simple way.
@@ -113,12 +113,12 @@
Each property definition must contain at least a type and a name. Most of the basic types are
built-in and can be found in the \l{QFace IDL Syntax}.
- \section2 Autogeneration
+ \section2 Auto-generation
- Now that our first version of the IDL file is ready, it's time to autogenerate API from it,
+ Now that our first version of the IDL file is ready, it's time to auto-generate an API from it,
using the \l{Qt Interface Framework Generator}{Interface Framework Generator tool}. Similar to
- \l{https://doc.qt.io/qt-5/moc.html}{moc}, this autogeneration process is integrated into the
- Build System and is done on compile time.
+ \l{Using the Meta-Object Compiler (moc)}{moc}, this auto-generation process is integrated into the
+ build system and is done at compile time.
In the following snippets we build a C++ library based on our IDL file:
@@ -133,7 +133,7 @@
output name, as well as the output directory are set. As we need to link to this library in the
future, it is easier to put the file into the upper directory.
- By calling the \l {qt6_ifcodegen_extend_target} function, the autogenerator is called and the
+ By calling the \l {qt6_ifcodegen_extend_target} function, the \c autogenerator is called and the
previously defined library is extended with the generated files. The input file is specified
using the \e IDL_FILES argument. See \l{Build System Integration} for more information.
@@ -155,12 +155,12 @@
using the QFace file that we specify in \c IFCODEGEN_SOURCES. For more information, see
\l{Build System Integration}.
- \section2 Which Files are Autogenerated
+ \section2 Which Files are Auto-generated
The Interface Framework Generator works based on generation templates. These templates define what content
- should be generated from a QFace file. Using qmake the template needs to be defined by the
+ should be generated from a QFace file. Using qmake, the template needs to be defined by the
\c IFCODEGEN_TEMPLATE variable. If it is not defined, it defaults to the "frontend" template.
- In CMake the template neeeds to be specified using the \c TEMPLATE argument of
+ In CMake the template needs to be specified using the \c TEMPLATE argument of
\l {qt6_ifcodegen_extend_target} and friends.
For more details on these templates, see \l{Use the Generator}.
@@ -173,20 +173,20 @@
To inspect the C++ code yourself, you can view these files in the your library's build folder.
- Right now, the most important autogenerated file for us, is the resulting C++ class for our
+ Right now, the most important auto-generated file for us, is the resulting C++ class for our
defined interface. It looks like this:
\quotefile interfaceframework/qface-tutorial/chapter1-basics/frontend/instrumentcluster.h
- As you can see, the autogenerated C++ class implements a \c speed property, that we previously
+ As you can see, the auto-generated C++ class implements a \c speed property, that we previously
defined in the QFace file. By using the \c Q_OBJECT and \c Q_PROPERTY macros, the class is now
ready for use directly in your QML code.
- \section2 Integrate the Frontend Library with the QML Code
+ \section2 Integrate the Front End Library with the QML Code
- For this integration, we use the autogenerated frontend library from the QML code. For the sake
+ For this integration, we use the auto-generated front end library from the QML code. For the sake
of simplicity, we follow the standard Qt example pattern and use a small C++ main function
- which registers our autogenerated types to QML and loads the Instrument Cluster QML code into
+ which registers our auto-generated types to QML and loads the Instrument Cluster QML code into
the QQmlApplicationEngine:
\quotefromfile interfaceframework/qface-tutorial/chapter1-basics/instrument-cluster/main.cpp
@@ -272,7 +272,7 @@
\printuntil enum
\printuntil }
- In the autogenerated code, this results in an enum which is part of the module class, making it
+ In the auto-generated code, this results in an enum which is part of the module class, making it
possible for the same enum to be used by multiple classes which are part of the same module:
\quotefile interfaceframework/qface-tutorial/chapter2-enums-structs/frontend/instrumentclustermodule.h
@@ -313,31 +313,31 @@
\printuntil }
\target chapter3
- \section1 Chapter 3: Add a Simulation Backend and Annotations with a QML plugin
+ \section1 Chapter 3: Add a Simulation Back End and Annotations with a QML plugin
In the previous two chapters, we wrote a Middleware API using a QFace file and used the Interface Framework
- Generator to autogenerate a C++ API in the form of a library. Now, in this chapter, we extend
- this further by introducing a simulation backend and using annotations to define default values
+ Generator to auto-generate a C++ API in the form of a library. Now, in this chapter, we extend
+ this further by introducing a simulation back end and using annotations to define default values
for our simulation.
- \section2 Separation between the Frontend and Backend
+ \section2 Separation between the Front End and Back End
- Both QtInterfaceFramework and the Interface Framework Generator enable you to write code that separates the frontend from the
- backend -- to split an API from its actual implementation. Already, Qt uses this concept in a
+ Both QtInterfaceFramework and the Interface Framework Generator enable you to write code that separates the front end from the
+ back end. This allows you to split an API from its actual implementation. Already, Qt uses this concept in a
lot of areas, most prominently in the underlying window system technology on various Qt
platforms like XCB on Linux and Cocoa on macOS.
- The same separation is done for our Middleware API, where the frontend provides the API as
- a library; the backend provides an implementation of this API. This implementation is based on
- QtInterfaceFramework's \l{Dynamic Backend System} which enables us to switch between such backends at runtime.
+ The same separation is done for our Middleware API, where the front end provides the API as
+ a library; the back end provides an implementation of this API. This implementation is based on
+ QtInterfaceFramework's \l{Dynamic Backend System} which enables us to switch between such back ends at runtime.
\image feature-backend.png
- \section2 Add a Simulation Backend
+ \section2 Add a Simulation Back End
- For our Instrument Cluster, we'd like to add such a backend to provide actual values. For now,
+ For our Instrument Cluster, we'd like to add such a back end to provide actual values. For now,
we'd like to just have some simulation behavior as we can't connect it easily to a real car.
- This is why such backends are called "simulation backend". To add this type of backend, once
+ This is why such back ends are called "simulation backend". To add this type of back end, once
again, we use the Interface Framework Generator to do the heavy lifting for us and generate one. This work
is done in a similar way to when we generated a library with the "frontend" template. But now,
we are using the "backend_simulator" template:
@@ -348,11 +348,11 @@
\skipto find_package
\printto target_link_libraries
- Similar to the frontend library, first the used components are imported using \e find_package.
+ Similar to the front end library, first the used components are imported using \e find_package.
As we want to build a plugin (dynamic library) which is loaded at runtime instead of linking
against it, we use the \l {qt_add_plugin} function instead. One important aspect
here is that the library name ends with "_simulation", which is a way to tell QtInterfaceFramework that this
- is a simulation backend. When a "production" backend is available, it is preferred over the
+ is a simulation back end. When a "production" back end is available, it is preferred over the
"simulation" one. For more information, see \l{Dynamic Backend System}.
As before, the Interface Framework Generator is called by using the \l{qt6_ifcodegen_extend_target}
@@ -367,10 +367,10 @@
\skipto IFCODEGEN_TEMPLATE
\printto CONFIG += install_ok
- Just like for the frontend library, the project file builds a \c lib and defines the library
+ Just like for the front end library, the project file builds a \c lib and defines the library
name using \c qtLibraryTarget to also support the Windows debug postfix. One important aspect
here is that the library name ends with "_simulation", which is a way to tell QtInterfaceFramework that this
- is a simulation backend. When a "production" backend is available, it is preferred over the
+ is a simulation back end. When a "production" back end is available, it is preferred over the
"simulation" one. For more information, see \l{Dynamic Backend System}.
Enabling the Interface Framework Generator is also done in the same way as we did earlier: by using the same
@@ -381,12 +381,12 @@
\section2 Link Settings and Locating Plugins
Trying to build the project file just as it is, right now, would result in compilation and
- linking errors. This is because: to do the frontend and backend separation, we need to have the
- backend implement a defined interface class, that is known to the frontend. This interface is
- aptly called "backend interface" and is automatically generated as part of the frontend
+ linking errors. This is because: to do the front end and back end separation, we need to have the
+ back end implement a defined interface class, that is known to the front end. This interface is
+ aptly called "backend interface" and is automatically generated as part of the front end
library. Because this class provides signals and slots and uses QObject for its base class, you
- need to link to the frontend library when you inherit from it. As this is needed for the
- backend plugin, we need to add the following lines in addition:
+ need to link to the front end library when you inherit from it. As this is needed for the
+ back end plugin, we need to add the following lines in addition:
\e CMake:
@@ -394,7 +394,7 @@
\skipto target_link_libraries
\printto install
- By defining the frontent library named \e libIc_chapter3 as a target link library the include
+ By defining the front end library named \e libIc_chapter3 as a target link library the include
path gets updated accordingly.
\e qmake:
@@ -422,9 +422,9 @@
has it's own sub-folder, such as \c platforms, for the platform plugins used to talk to the
underlying platform API and the windowing system.
- Similarly, QtInterfaceFramework searches for its backend plugins in the \c interfaceframework folder.
+ Similarly, QtInterfaceFramework searches for its back end plugins in the \c interfaceframework folder.
- To make sure our simulation backend ends up in such a folder, we add the following changes in
+ To make sure our simulation back end ends up in such a folder, we add the following changes in
our build system file:
\e CMake:
@@ -448,7 +448,7 @@
function or using the \c QT_PLUGIN_PATH environment variable. For more information, see
\l{https://doc.qt.io/qt-5/plugins-howto.html}{How to create Qt Plugins}.
- Now everything is in place, but because our plugin links against the frontend library, we need
+ Now everything is in place, but because our plugin links against the front end library, we need
to make sure the library can be found by the dynamic linker. This can be achieved by
setting the \c LD_LIBRARY_PATH environment variable to our library folder. But this results
in the problem, that every user would need to set this variable to be able to use our
@@ -456,7 +456,7 @@
\e CMake:
- Using CMake, the location of our frontend library is automatically added as a \e RUNPATH to the
+ Using CMake, the location of our front end library is automatically added as a \e RUNPATH to the
the binary and no further steps are needed.
\e qmake:
@@ -471,9 +471,9 @@
\section2 Export the QML Types in a QML Plugin
- In the first chapter, we extended our \c main.cpp to register all types of our autogenerated
+ In the first chapter, we extended our \c main.cpp to register all types of our auto-generated
Middleware APIs. Although this works fine, in bigger projects it's common to use a QML Plugin
- instead and be able to use qmlscene for development. Although the code for doing this is
+ instead and be able to use \c qmlscene for development. Although the code for doing this is
not complex, the Interface Framework Generator supports this as well and makes it even easier.
From the first chapter, we know that the module name is used for the QML import URI. This is
@@ -491,7 +491,7 @@
import the generated code into CMake and pass it to the \l {qt_add_qml_module} function.
The \l {qt6_ifcoegen_import_variables} function will call the generator and export variables
starting with \e CLUSTER as prefix to the current CMake scope.
- Those variables reference autogenerated code, but also expose other information like the QML
+ Those variables reference auto-generated code, but also expose other information like the QML
import URI.
In the next call, the variables are used to define a QML Module with the correct URI and version
(as specified in our IDL file). By using the \e OUTPUT_DIRECTORY variable we can make sure that
@@ -504,7 +504,7 @@
\printto target.path
All lines until \c IFCODEGEN_SOURCES should be familiar. We use \c CONFIG to build a plugin, then
- define the settings for the linker to link against our frontend library. Then, we use
+ define the settings for the linker to link against our front end library. Then, we use
\c IFCODEGEN_TEMPLATE to define "qmlplugin" as the generation template. Instead of adding
\c ifcodegen to \c CONFIG, this time we use
\l{https://doc.qt.io/qt-5/qmake-test-function-reference.html#load-feature}
@@ -516,12 +516,12 @@
what files are part of the plugin, and under which URI. For more information, see
\l{https://doc.qt.io/qt-5/qtqml-modules-qmldir.html}{Module Definition qmldir Files}. Both this
\c qmldir file and a \c plugins.qmltypes file which provides information about code-completion,
- are autogenerated by the Interface Framework Generator; but they need to be placed next to the library. To do
+ are auto-generated by the Interface Framework Generator; but they need to be placed next to the library. To do
so, we add the files to a scope similar to an \c INSTALL target, but add it to the \c COPIES
variable instead. This makes sure that the files are copied when the plugin is built.
Now the plugin is ready for use, but our Instrument Cluster application doesn't know where to
- search for it and is still using the old hardcoded registration. So, we can now remove the
+ search for it and is still using the old hard-coded registration. So, we can now remove the
linking step in the \c instrument-cluster build system file and change our main file
accordingly:
@@ -536,9 +536,9 @@
\section1 Chapter 4: Add a Custom Simulation
So far, we've created a Middleware API and integrated it into our Instrument Cluster QML code,
- extended it with a QML plugin, and generated a simulation backend. In the background, quite a
+ extended it with a QML plugin, and generated a simulation back end. In the background, quite a
lot has happened to support us; but on the UI side not much has changed till now. This chapter
- is about bringing our simulation backend to life by defining sane default values and starting
+ is about bringing our simulation back end to life by defining sane default values and starting
to simulate a real car ride.
\section2 Define Default Values
@@ -548,7 +548,7 @@
property, and so on. For this use case we use the \c config_simulator annotation. For more
information, see \l{annotations-yaml}{Annotations}.
- Currently, in our Instrument Cluster, the temperatur defaults to 0. Let's change this to a
+ Currently, in our Instrument Cluster, the temperature defaults to 0. Let's change this to a
temperature in spring, 15 degrees Celsius, with the following YAML fragment:
\quotefromfile interfaceframework/qface-tutorial/chapter4-simulation-behavior/instrument-cluster.qface
@@ -561,19 +561,19 @@
\quotefile interfaceframework/qface-tutorial/chapter4-simulation-behavior/backend_simulator/instrumentclustermodule.json
- But how is this JSON file related to the actual simulation backend code? The autogenerated
- simulation backend code uses QIfSimulationEngine, that reads the JSON file and provides its
- data to a QML simulation file. A default QML file is also autogenerated and loaded from the
+ But how is this JSON file related to the actual simulation back end code? The auto-generated
+ simulation back end code uses QIfSimulationEngine, that reads the JSON file and provides its
+ data to a QML simulation file. A default QML file is also auto-generated and loaded from the
QIfSimulationEngine. This default QML file provides the behavior of what should happen in the
- the simulation backend.
+ the simulation back end.
Later, in the next section, we take a look at the QML file and how we can change it. But first,
let's see how we can change the default values in a more dynamic way.
The QIfSimulationEngine allows us to override which JSON file should be loaded into the
engine, when we set the \c QTIF_SIMULATION_DATA_OVERRIDE environment variable. Since there can
- be multiple engines run by different backends, we need to define which engine we're referring
- to. In the autogenerated code, the module name is always used as the engine specifier. For this
+ be multiple engines run by different back ends, we need to define which engine we're referring
+ to. In the auto-generated code, the module name is always used as the engine specifier. For this
chapter, we already prepared a second JSON file which is part of our source directory. Setting
the environment variable as follows, changes the \c systemType to mph instead of km/h:
@@ -583,9 +583,9 @@
\section2 Define a QML Behavior
- Before we define our custom behavior, let's see what's been autogenerated for us. There are two
+ Before we define our custom behavior, let's see what's been auto-generated for us. There are two
QML files: The first is \c instrumentcluster_simulation.qml and rather simple. It defines an
- entry point that istantiates the second file, an \c InstrumentClusterSimulation.qml file. This
+ entry point that instantiates the second file, an \c InstrumentClusterSimulation.qml file. This
split is done as there can be multiple interfaces defined as part of the same module.
\note A QML Engine can only have one entry point. While QIfSimulationEngine has this same
@@ -609,19 +609,19 @@
Afterwards, the actual behavior is defined by instantiating an \c InstrumentClusterBackend Item
and extending it with more functions. The \c InstrumentClusterBackend is the interface towards
- our \c InstrumentCluster QML frontend class. But, apart from the frontend, these properties are
+ our \c InstrumentCluster QML front end class. But, apart from the front end, these properties are
also writable to make it possible to change them to provide a useful simulation.
- Each time a frontend instance connects to a backend, the \c initialize() function is called.
+ Each time a front end instance connects to a back end, the \c initialize() function is called.
The same applies to the QML simulation: as the \c initialize() C++ function forwards this to
- the QML instance. This also applies to all other functions, like setter and getters, for
+ the QML instance. This also applies to all other functions, like setters and getters, for
properties or methods. For more details, see \l{QIfSimulationEngine}.
Inside the QML \c initialize() function, we call \c{IfSimulator.initializeDefault()}, to read
the default values from the \c simulationData object and initialize all properties. This is
- done only \b once, as we don't want the properties be reset to default when the next frontend
- instance connects to the backend. Lastly, the base implementation is called to make sure that
- the \c initializationDone signal is sent to the frontend.
+ done only \b once, as we don't want the properties be reset to default when the next front end
+ instance connects to the back end. Lastly, the base implementation is called to make sure that
+ the \c initializationDone signal is sent to the front end.
Similarly, a setter function is defined for each property; they use the
\c{IfSimulator.checkSettings()} to read specific constraint settings for the property from
@@ -631,7 +631,7 @@
\section2 Define Our Own QML Simulation
- As mentioned above, the \c InstrumentClusterBackend Item does provide all the properties of our
+ As mentioned above, the \c InstrumentClusterBackend item provides all the properties of our
QFace file. This can be used to simulate a behavior by changing the properties to the values
we want. The simplest form for this would be value assignment, but this would be rather static
not exactly what we'd like to achieve. Instead, we use QML Animation objects to change the
@@ -659,7 +659,7 @@
\skipto import
The next step is to tell the Interface Framework Generator and the QIfSimulationEngine about our new
- simulation file. Similar to QML files, the best aproach here is to put the simulation file into
+ simulation file. Similar to QML files, the best approach here is to put the simulation file into
a resource file. In our example, we add a new file called \c simulation.qrc which contains our
\c simulation.qml using the \c{/} prefix.
@@ -669,13 +669,13 @@
\printuntil module
\dots
- Now, rebuilding the simulation backend embeds the simulation file into the plugin and hands the
+ Now, rebuilding the simulation back end embeds the simulation file into the plugin and hands the
file over to the QIfSimulationEngine, which starts the simulation when loaded.
\target chapter5
\section1 Chapter 5: Add a Simulation Server Combined with QtRemoteObjects
- In this chapter we extend our Instrument Cluster to use an Inter-Process Communication (IPC)
+ In this chapter we extend our instrument cluster to use an Inter-Process Communication (IPC)
mechanism and use two processes. At the moment, the simulation is loaded as a plugin that
causes it to be part of the same service. Although this is good enough for a small example
application, it's not how it's done in modern multi-process architectures, where multiple
@@ -689,8 +689,8 @@
\section2 Add a QtRemoteObjects Integration
The IPC for this example is QtRemoteObjects, because the Interface Framework Generator already supports it
- out of the box. To use QtRemoteObjects we generate a second plugin, a "production" backend,
- this time. Production backends are automatically preferred over the simulation backend we
+ out of the box. To use QtRemoteObjects we generate a second plugin, a "production" back end,
+ this time. Production back ends are automatically preferred over the simulation back end we
introduced before.
This is done with the following build system files:
@@ -706,14 +706,14 @@
\quotefromfile interfaceframework/qface-tutorial/chapter5-ipc/backend_qtro/backend_qtro.pro
\printto CONFIG += install_ok
- These files are almost identical to the ones we used earlier for our simulation backend.
+ These files are almost identical to the ones we used earlier for our simulation back end.
For now we highlight what's changed.
The name of the plugin doesn't end with "_simulation" to indicate that this is a "production"
- backend. The template is now changed to "backend_qtro" to generate a backend that uses
- QtRemoteObjects Replicas to connect to a QtRemoteObjects Source that provides the values. In
- addition to a QtRemoteObject-based backend, we also need a QtRemoteObject-based server. This
- part can also be autogenerated using the Interface Framework Generator in a similar fashion:
+ back end. The template is now changed to "backend_qtro" to generate a back end that uses
+ \l{Qt Remote Objects Replicas} to connect to a \l{Qt Remote Objects Source} that provides the values. In
+ addition to a back end based on QtRemoteObject, we also need a server based on QtRemoteObject . This
+ part can also be auto-generated using the Interface Framework Generator in a similar fashion:
\e CMake:
@@ -736,12 +736,12 @@
Now, if you start the server and then the Instrument Cluster, you don't see the simulation
from our previous chapter anymore. The reason for this, is that the simulation code is part of
- our simulation backend, but this backend is no longer used as we added the
- QtRemoteObjects-based "production" backend.
+ our simulation back end, but this back end is no longer used as we added the
+ QtRemoteObjects-based "production" back end.
Because we used the "server_qtro_simulator" generation template, this can easily be fixed, as
the generated server code is also using the QIfSimulationEngine and supports to use the same
- simulation file than our simulation backend. We just need to extend the project file in the
+ simulation file than our simulation back end. We just need to extend the project file in the
same way as we did before and are also able to use the same resource file for this.
\e CMake:
@@ -766,11 +766,11 @@
\image qface-tutorial-sync.gif
\target chapter6
- \section1 Chapter 6: Develop a Production Backend with D-Bus
+ \section1 Chapter 6: Develop a Production Back End with D-Bus
Previously, we extended our Instrument Cluster code by using QtRemoteObjects as IPC and
- autogenerated a backend for it, as well as a server that provides the simulation. In this
- chapter, we'd like to write our own backend \b manually using D-Bus as IPC.
+ auto-generated a back end for it, as well as a server that provides the simulation. In this
+ chapter, we'd like to write our own back end \b manually using D-Bus as IPC.
We've already prepared a working D-Bus server which provides limited simulation.
@@ -791,17 +791,17 @@
"Example.If.InstrumentCluster". To simulate some values, we keep it simple and use a timer
event to change the speed value every 100 milliseconds. Then, we start from 0, once the
maximum of 250 is reached. Similarly, the \c rpm value is increased to 5000. For all other
- properties, we provide hardcoded values.
+ properties, we provide hard-coded values.
\quotefromfile interfaceframework/qface-tutorial/chapter6-own-backend/demo_server/instrumentcluster.cpp
\skipto timerEvent
\printuntil }
- \section2 Write Our own D-Bus Backend
+ \section2 Write Our own D-Bus Back End
- Let's start with a build system file for our backend. This is very similar to previous
+ Let's start with a build system file for our back end. This is very similar to previous
files, but it doesn't use the Interface Framework Generator. Instead, it uses \c DBUS_INTERFACES
- for qmake to autogenerate some client code which sends and receives messages over D-Bus.
+ for qmake to auto-generate some client code which sends and receives messages over D-Bus.
In the CMake case the \l {qt6_add_dbus_interface} function is used to do the same.
Now, we need to define an entry point for our plugin. This plugin class needs to derive from
@@ -819,7 +819,7 @@
\quotefile interfaceframework/qface-tutorial/chapter6-own-backend/backend_dbus/instrumentcluster_dbus.json
- We need this list, as it gives QtInterfaceFramework the chance to know which interfaces a backend supports,
+ We need this list, as it gives QtInterfaceFramework the chance to know which interfaces a back end supports,
before instantiating it and loading only the plugins which the application code needs.
Our plugin code looks like this:
@@ -829,10 +829,10 @@
\printto
In \c interfaces() we use the IID which is defined in \c{instrumentclusterbackendinterface.h}
- from our autogenerated library. In \c insterfaceInstance() we check for the correct string and
- return an instance of the instrument cluster backend we implemented.
+ from our auto-generated library. In \c insterfaceInstance() we check for the correct string and
+ return an instance of the instrument cluster back-end we implemented.
- This backend is defined in \c instrumentclusterbackend.h and derives from
+ This back end is defined in \c instrumentclusterbackend.h and derives from
\c InstrumentClusterBackendInterface. In our \c InstrumentClusterBackend class, we need to
implement all pure virtual functions from InstrumentClusterBackendInterface and derived classes.
@@ -841,12 +841,12 @@
well. We don't need to implement getters for our properties, because QtInterfaceFramework uses the changed
signals during the initialization phase to get information about the current state. Although
the generated D-Bus interface class would provide getters to retrieve the properties from our
- server, it's not recommended to use these when you develop a backend. These getters are
+ server, it's not recommended to use these when you develop a back-end. These getters are
implemented by using synchronous calls, which means they will block the event loop until an
answer is received by the client. Since this can lead to performance issues, we recommend to
use \b asynchronous calls instead.
- In our backend, we define a fetch function for each property that's implemented like this:
+ In our back end, we define a fetch function for each property that's implemented like this:
\quotefromfile interfaceframework/qface-tutorial/chapter6-own-backend/backend_dbus/instrumentclusterbackend.cpp
\skipto ::fetchSpeed
@@ -856,7 +856,7 @@
Next, we use the \c asyncCall() function to call the getter for the \c speed property and use a
\c QDBusPendingCallWatcher to wait for the result. Once the result is ready, the lambda removes
the property again from our \c fetchList, uses the \c onSpeedChanged() function to store the
- value and notifies the frontend about it. Since we don't need the watcher anymore, we delete it
+ value and notifies the front end about it. Since we don't need the watcher anymore, we delete it
in the next event loop run using \c deleteLater(), and call the \c checkInitDone() function.
The \c checkInitDone() function is defined as follows:
@@ -865,10 +865,10 @@
\skipto ::checkInitDone
\printto onSpeedChanged
- It ensures that the \c initializationDone() signal is sent to the frontend once all our
+ It ensures that the \c initializationDone() signal is sent to the front end once all our
properties are fetched from the server, and the initialization is complete.
- In addition to retrieving the current state from the server, we also need to inform our frontend
+ In addition to retrieving the current state from the server, we also need to inform our front end
every time a property changes. This is done by emitting the corresponding change signal when the
server changes one of its properties. To handle this, we define a slot for each property. This
slot saves the property in our class an emits the change signal:
@@ -880,12 +880,12 @@
The same slot is also used during the initialization phase to save and emit the value.
You might wonder why saving the value is needed at all, if we can just emit the signal. This is
- because the backend plugin is used directly by every instance of the \c InstrumentCluster class
+ because the back end plugin is used directly by every instance of the \c InstrumentCluster class
and every instance calls the \c initialize() function to retrieve the current state. Instead of
fetching all properties again, the second \c initialize() call just emits values that were
already saved; and the slots keep them up to date.
- Now, when we start the Instrument Cluster, our backend should connect to our D-Bus server and
+ Now, when we start the Instrument Cluster, our back end should connect to our D-Bus server and
look like this:
\image qface-tutorial-dbus.gif