1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
|
/****************************************************************************
**
** Copyright (C) 2016 Pelagicore AG
** Contact: http://www.qt.io/ or http://www.pelagicore.com/
**
** This file is part of the documentation of the QtIVI module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL-PELAGICORE$
** Commercial License Usage
** Licensees holding valid commercial Qt IVI 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 Pelagicore. For licensing terms
** and conditions, contact us at http://www.pelagicore.com.
**
** 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$
**
****************************************************************************/
/*!
\module QtIVICore
\title Qt IVI Core C++ Classes
\ingroup modules
\ingroup qtivi_modules
\qtvariable ivicore
\brief C++ classes for the Qt IVI Core API.
Qt IVI provides a pattern for extending Qt with extendable APIs. It also comes with a set of
demonstrator APIs that can be used as a starting point or off-the-shelf in your projects.
The pattern is based around separation of the 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
\section1 Building Blocks
Qt IVI consists of a number of building blocks. Understanding the roles of these is key to using
Qt IVI.
\section2 Core
The core module provides base classes for writing features and backends as well as the
mechanisms for finding the correct backend for each feature.
The core also contains common classes and base classes for various models and shared types.
\section2 Feature
The feature is what an application developer uses. The feature contains the API facing the
applications, but also the backend interface, i.e. the interface that the corresponding backend
needs to implement. The object implementing the backend interface is called as service object.
The backend interface defines an interface name. This is a unique string identifying the
interface between the feature and the backend. It is commonly written using reverse domain name
notation, e.g. com.example.FeatureName. This is what is used by Core to find service objects
for a feature.
The feature is derived from the QtIVIAbstractFeature class. The backend interface is commonly
based on QObject.
To make the API useable from QML, the feature needs to include a QML plugin registering types
and classes. The QML plugin is derived from the QQmlExtensionPlugin class.
It is common to include a simple stubbed backend and a testing backend with each feature.
\section2 Backend
A backend implements the backend interface specified by the feature. The backend is derived from
the backend interface class defined by the feature, which is a QObject derived class.
The object implementing the backend is called as service object.
The backends are loaded by Core when the features request them. Each backend has to provide a Qt
IVI plugin that exposes a factory to the Core. This is what is used to load and create backends.
The plugin interface is called QtIVIServiceInterface.
\section2 Simple vs Dynamic Features
Most features are simple. This means that each feature element needs a single service object. By
setting the autoDiscover property of QtIVIAbstractFeature to true, the Core module provides the
first compatible service object to the feature and issues a warning if none or more than one
compatible service object is found.
When auto discovery is used, Core looks for the backend once during the creation of the feature
instance. When used from QML, this takes place when the feature element is completely
initialized. From C++, it is made when a call to the startAutoDiscovery method is called.
For dynamic features, there can be multiple service objects for each feature. This means that
the auto discovery mechanism does not work. Instead the application must take responsibility for
finding the right service object for each feature instance.
QtIVIServiceManager 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 QtIVIServiceManager 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 Extending Qt IVI
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}.
Notice that it is possible to have multiple feature element classes in a single module. For
instance, the media module of Qt IVI contains both source discovery, media search, and media
browse APIs.
Having decided on a name and a backend interface name prefix, the template module can be checked
out from git. Then the renamer script is used to create the module, for example:
\code
./renamer.sh Oem MyFeature com.pelagicore
\endcode
This will result in the \e {OemMyFeature} module to be created and the backend interfaces
prefixed with \e {com.pelagicore}, e.g. \e {com.pelagicore.MyFeature}.
The resulting directory structure is described in the table below.
\table
\header
\li Path
\li Description
\row
\li \c {examples}
\li Examples top-level directory
\row
\li \c {examples/feature}
\li Feature specific example directory
\row
\li \c {example/feature/feature_qml}
\li Template QML-based feature example
\row
\li \c {example/feature/feature_widgets}
\li Template widgets-based feature example
\row
\li \c {src}
\li Source code top-level directory
\row
\li \c {src/feature}
\li Feature source code. Includes feature APIs as well as backend interfaces
\row
\li \c {src/feature/doc}
\li Feature documentation configuration
\row
\li \c {src/imports}
\li QML import modules top-level directory
\row
\li \c {src/imports/feature}
\li Template feature QML import module
\row
\li \c {src/plugins}
\li Qt IVI backend plugins directory
\row
\li \c {src/plugins/feature}
\li Feature Qt IVI backends directory
\row
\li \c {src/plugin/feature/feature_stub}
\li Stubbed template feature Qt IVI backend
\row
\li \c {tests}
\li Unit tests top-level directory
\row
\li \c {tests/auto}
\li Automatic tests directory
\row
\li \c {tests/auto/feature}
\li Template feature unit test
\row
\li \c {sync.profile}
\li Qt module control script
\endtable
To add more feature APIs, simply add them into \c {src/feature} and
\c {src/imports/feature}. To add more backends, add them to \c {src/plugins/feature}.
If another OEM specific feature is needed there is no need to create the whole folder structure
again. Simply add your feature’s code into the example \c {src} and \c {tests} folders and add
it to the \c {sync.profile} file.
To create a backend for an existing feature, simply create a new Qt project based on the feature
module in question and build a Qt IVI backend plugin.
\section1 Creating a Qt Module
\section1 Creating a Feature
\section1 Creating a Backend
*/
/*!
\qmlmodule QtIVICore 1.0
\title Qt IVI Core QML Types
\ingroup qmlmodules
\ingroup qtivi_qmlmodules
\brief QML types for the Qt IVI Core API.
The Qt IVI Core QML API provides core functions for in-vehicle infotainment QML types.
\section1 QML Types
*/
|
