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
|
/****************************************************************************
**
** Copyright (C) 2019 Luxoft Sweden AB
** Copyright (C) 2018 Pelagicore AG
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Luxoft Application Manager.
**
** $QT_BEGIN_LICENSE:FDL-QTAS$
** Commercial License Usage
** Licensees holding valid commercial Qt Automotive Suite licenses may use
** this file in accordance with the commercial license agreement provided
** with the Software or, alternatively, in accordance with the terms
** contained in a written agreement between you and The Qt Company. For
** licensing terms and conditions see https://www.qt.io/terms-conditions.
** For further information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\example applicationmanager/hello-world
\brief Learn how to write your first System UI.
\ingroup applicationmanager-examples
\title "Hello World!" System UI Example
\image hello-world-example.png The Hello World example with two applications running.
\section1 Introduction
This example shows a very simple System UI implementation that showcases Qt Application Manager's
fundamental building blocks.
The applications' icons and names are on the left. You can click on their respective icons to start
and stop them. The column layout on the right shows their windows.
The applications display "Hello World!" against a background of a specific color.
\section1 Files and Folder Structure
This example comprises of four separate QML applications: a System UI and three sample
applications: "Hello Red", "Hello Green" and "Hello Blue". The System UI is also a QML application,
albeit a special one.
Each application is put in a separate directory as follows:
\list
\li \tt system-ui.qml
\li \tt{\b{apps}}
\list
\li \tt{\b{hello-world.blue}}
\list
\li \tt icon.png
\li \tt info.yaml
\li \tt main.qml
\endlist
\li \tt{\b{hello-world.red}}
\list
\li \tt icon.png
\li \tt info.yaml
\li \tt main.qml
\endlist
\li \tt{\b{hello-world.green}}
\list
\li \tt icon.png
\li \tt info.yaml
\li \tt main.qml
\endlist
\endlist
\endlist
Each application has a \c main.qml file, an icon, and an \l{Manifest Definition}{\c info.yaml}.
This YAML file contains application metadata such as the name of the application, its icon
filename, and more.
\section1 Run the System UI
Verify that you have the \c appman binary in your path. Otherwise, you have to explicitly specify
the location for your \c appman binary when you use it.
If you have the \c appman binary in your path, you can run the System UI as follows:
\badcode
examples/applicationmanager/hello-world$ appman --builtin-apps-manifest-dir ./apps system-ui.qml
\endcode
The \c --builtin-apps-manifest-dir command line parameter tells \c appman where to find bult-in
applications, in this case the \c apps subdirectory. Built-in applications are those that come
pre-installed and cannot be removed via the ApplicationInstaller APIs. The next parameter is the
System UI's \c main.qml filename, \c system-ui.qml.
The screenshot below is what you should see:
\image hello-world-launched.png
For more information on the command line options, run \c {appman --help}.
\section1 Implement the System UI
Like any simple QML application, our example's code starts with some imports and a plain Item at
the root. The only difference is that our System UI also imports the
\c QtApplicationManager.SystemUI module, besides \c QtQuick.
\quotefromfile applicationmanager/hello-world/system-ui.qml
\skipto import QtQuick
\printuntil height:
Next, we have a Column on the left side of the root Item where we place the icons of the available
applications along with their names.
\printto Show windows
We use the \c ApplicationManager singleton, as a model, which provides a row for each application
available. In each row, we have:
\list
\li an \c icon role with the icon URL
\li a \c name role with the localized application's name
\li a boolean \c isRunning that provides the application's status
\li an \c application role that contains its ApplicationObject
\endlist
For information on the other roles available, see \l{ApplicationManager}{ApplicationManager QML Type}.
Clicking on an icon either starts its application or stops it if it's already running.
Next, we place a \c Column anchored to the right side of the root \c Item. In this column, we lay
out the existing windows for all applications that are currently running:
\printto /^\}/
This time, we use the \c WindowManager singleton as the model. There's a row for each window, with
its WindowObject in the \c window role.
To have a window rendered in our System UI, we have to assign its WindowObject to a WindowItem,
as we did above. By default, the window is resized to match the size of the WindowItem rendering
it.
\section1 Implement the Application
Our Hello World applications display a "Hello World!" text against a colored background.
\quotefromfile applicationmanager/hello-world/apps/hello-world.blue/main.qml
\skipto import QtQuick
\printuntil /^\}/
The only difference between this example and a plain QML application is that the root element is
an ApplicationManagerWindow, provided by the \c QtApplicationManager.Application module.
\section2 Application Metadata
The \c info.yaml file contains the metadata about an application. It starts with some boilerplate
desribing that this file contains Qt Application Manager application metadata.
\quotefromfile applicationmanager/hello-world/apps/hello-world.blue/info.yaml
\printuntil --
Then comes the application ID, which uniquely identifies the application. It's recommended to
follow a reverse DNS scheme, but it's not enforced. Here it's the "Blue" application from the
"Hello World" example UI.
\printline id:
Then the icon filename:
\printline icon:
The \c code field specifies the entry point of the application. For QML applications, this means
the filename of its main QML file.
\printline code:
The \c runtime field specifies the runtime used by the application. In this example, all
applications are written in QML and hence we use the \c 'qml' runtime. Another runtime is
\c 'native' for instance, used for compiled, executable, applications where the \c code
entry would point to its binary executable filename.
\printline runtime:
And finally comes the user-visible name of the application in any number of languages. For this
example, we only provide English:
\printuntil
*/
|
