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
|
/****************************************************************************
**
** Copyright (C) 2021 The Qt Company Ltd.
** 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 Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt 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 system-ui.html
\ingroup qtappman
\ingroup qtappman-highlights
\title The System UI
\brief Describes the part of a UI which starts and stops any application, on a device
The System UI is the part of a UI which starts and stops any application, on a device. It's
responsible for managing the application windows and compositing them in a specific way. For
example, to display the applications in full-screen, or to allow multiple windows to be displayed
from different applications at the same time.
On desktop systems, the System UI is akin to the Microsoft Windows' Shell, or KDE's Plasmashell
plus the KWin compositor.
The System UI has the following tasks:
\table
\header
\li Task
\li Description
\row
\li Compositing
\li Manages multiple applications' surfaces, known as windows. \br
Arrange these windows on one or more physical screens, according to the required
design. \br
Handle window decoration, transition effects and other system-wide user experience.
\row
\li Communication Interface
\li Act as a channel to exchange information between applications and itself, such as to
switch the language.
\row
\li Input Handling
\li Switch focus between input events, according to the user's current focus. \br
Provide system input services, such as launch a virtual keyboard for touch-based
systems.
\row
\li Manage system-wide applications and services
\li Manage the application life-cycle, by starting applications upon user interaction and
stopping them in critical situations, such as low memory. \br
Provide a central UI to monitor the UI performance and all applications that have
started, by showing statistics such as frame rate, the amount of CPU currently used,
and memory resources.
\row
\li Manage idle time and display the \uicontrol{Home Screen}
\li Display the default view to the user after startup. \br
Display essential data, such as the current time. \br
Display a view composed of several selected applications.
\endtable
\section1 Implement a System UI
The System UI's main feature is its ability to manage multiple applications and windows.
Consequently, Linux-based systems are the recommended development environment, where multi-process
mode is enabled. On other Operating Systems, you can use the single-process mode. For more
information on the difference between single-process and multi-process, see
\l{Single-Process vs. Multi-Process Mode} and \l{Wayland and Qt}.
\section2 Window Management
The System UI's central role is to handle application windows. On the client side, you need to use
an \l{ApplicationManagerWindow}. On the System UI side, you need to implement a handler for
WindowManager::windowAdded. Whenever a client window becomes visible, the WindowManager::windowAdded
signal is emitted. The signal has one parameter, WindowObject, which is the System UI side
representation of the client side ApplicationManagerWindow.
To differentiate between client windows, you should use window properties. For instance, you could
attach a \c type property to a client window, to tell the System UI, whether it's a top-level
window, a popup, or something else. Both client and server side window representations can access
these properties. Typically, they are always in-sync; but the underlying Wayland protocol is
entirely asynchronous.
To include the WindowObject in the System UI's render tree, set the WindowObject as the \c window
property for a WindowItem. The WindowItem acts as a container \l{Item} for WindowObjects.
Consequently, the WindowItem determines the position, visibility, and so on, of the client window
in the System UI.
One example of a simple System UI is the one written for the "Hello World!" System UI Example:
\quotefromfile ../examples/applicationmanager/hello-world/system-ui.qml
\skipto Item {
\printuntil /^\}/
\section2 Notifications
In cases where you'd like to display notifications or pop-ups, applications or clients can
create these with \l{ApplicationInterface::createNotification()}. They are then made available
on the System UI via the \l{NotificationManager}.
The code snippet below is part of the \l{Desktop System UI Example} that illustrates how to
display pop-ups.
\quotefromfile ../examples/applicationmanager/minidesk/system-ui/main.qml
\skipto System UI for a notification
\printto Handler for WindowManager signals
\section2 Intents
The System UI and other applications can send and receive intents. This is exposed via the
\l{IntentObject} and \l{IntentServer} QML types. The Intent represents a single intent definition on
the System UI; the IntentServer is the singleton on the System UI-side that represents the
intents sub-system.
For more details on implementing support for intents, see the
\l{Intents System UI and Applications Example}.
\section2 Life-Cycle
The \l{ApplicationManager} provides APIs to start and stop an application. However, the
recommended approach is to use \l{ApplicationObject::start()} and \l{ApplicationObject::stop()}.
Optionally, you can also pass a \c documentUrl in the \l{ApplicationObject::start()}{start()}
function. Then, when you call \c{start()} several times, with a different \c documentUrl()
each time, you won't be restarting the application; but only triggering the
\l{ApplicationInterface::openDocument()} on the application or client side.
\l{ApplicationObject::stop()} triggers \l{ApplicationInterface::quit()} on the application
side. The application should do all the necessary clean-ups and then confirm that it can be
terminates with \l{ApplicationInterface::acknowledgeQuit()}.
You can implement other life-cycle management features that are tailored to the specific
requirements of IPC mechanisms like window properties, \l{Intents}, or proprietary IPCs.
For more information, see the \l{Desktop System UI Example}.
\section2 Monitoring
To monitor your application, you can use the \l{MonitorModel} to fetch data from various
sources at intervals and store a history of these values. You can use this data for analytical
purposes, such as to plot its previous values over time. For more information, see the
\l{Display Information about Application Processes Example}.
\section2 Application Installer
The \l{ApplicationManager} provides a list of all available applications in the
\l{ApplicationModel}. In addition to applications bundled with the System UI,
\e{system applications}, the ApplicationManager also provides a way to install new applications
at runtime. These applications are maintained by the \l{ApplicationInstaller} singleton.
To start an installation, use \l{ApplicationInstaller::startPackageInstallation}. Once all
metadata from the application's package is extracted, the
\l{ApplicationInstaller::taskRequestingInstallationAcknowledge} signal is emitted. This signal
can be used to give you more information about the package, such as the name, size, or
permissions. This installation needs to be confirmed using
\l{ApplicationInstaller::acknowledgePackageInstallation}. After the installation is complete,
you can start the new application, as described in the \l{Life-Cycle}. To remove applications
that have been installed, use \l{ApplicationInstaller::removePackage}.
For more information, see \l{Application Installer}.
\section1 Best Practices When You Write a System UI
Below are some key practices to consider when you write a System UI:
\list
\li \b{Always test your System UI and its applications on the target as early as possible.}
This is especially important because the combination of your target hardware and the
asynchronous Wayland protocol may result in some timing constraints on some parts of
the system. For example, when are window properties available to the System UI, after
an application has started. These constraints are best identified as early as possible.
To be able to run a fluent UI, hardware acceleration is necessary for the System UI as
well as for applications (or Wayland clients). This fluency is achieved via hardware
specific texture sharing mechanisms. Now, these mechanisms are hardware specific and
it's likely that a different mechanism is used on the target platform, compared to your
development machine. Testing on the target hardware as early as possible can help to
bring forward any issues with the sharing mechanism or side effects from other graphic
intense elements, such as shader effects or 3D engine integration.
\li \b{Allow the System UI to stop applications that take up too much memory or CPU.}
Design your system in such a way that lets the System UI stop applications when necessary,
particularly in situations where hardware resources like memory or CPU is low. This
provides better scalability.
\li \b{Always use two different plugin folders.}
One folder for System UI-specific or privileged applications. Another folder for other
applications that contain base elements, such as your UI style or the Items for your
different window types.
\endlist
\section1 Notes on The Root Element
\list
\li If the root element of the System UI is an Item, the application manager creates a
QQuickWindow for it and sets the Item as its root Item.
\li If the root element of the System UI is a Window, or an Item that is wrapped in a Window
the window is shown initially, regardless of the value of its \c visible property.
\endlist
\section1 Related Information
\list
\li \l{Writing Applications}
\li \l{QtApplicationManager.SystemUI QML module}
\endlist
*/
|
