Libksysguard

SensorFaceController.h
1/*
2 SPDX-FileCopyrightText: 2020 Marco Martin <mart@kde.org>
3
4 SPDX-License-Identifier: LGPL-2.0-or-later
5*/
6
7#pragma once
8
9#include <QAbstractItemModel>
10#include <QObject>
11#include <QPointer>
12#include <QQuickItem>
13
14#include <KConfigGroup>
15
16#include "sensorfaces_export.h"
17
19class QQmlEngine;
20class KDesktopFile;
21class KConfigLoader;
22
23namespace KSysGuard
24{
25class SensorFace;
26class SensorFaceControllerPrivate;
27
28/**
29 * The SensorFaceController links sensor faces and applications in which these faces are shown. It
30 * abstracts the configuration and properties of faces.
31 *
32 * For faces it offers information about which sensors should be displayed and hints set by the
33 * application about how the information should be displayed. It can be accessed by faces using
34 * the `SensorFace::controller` property.
35 *
36 * Applications can use this class to instantiate faces from a given config and for querying the
37 * capabilities of faces.
38 *
39 * @since 5.19
40 */
41class SENSORFACES_EXPORT SensorFaceController : public QObject
42{
43 Q_OBJECT
44 /**
45 * A title for the face.
46 * @see showTitle
47 */
48 Q_PROPERTY(QString title READ title WRITE setTitle NOTIFY titleChanged)
49 /** Whether the title should be displayed or if it should be hidden instead
50 * @see title
51 */
52 Q_PROPERTY(bool showTitle READ showTitle WRITE setShowTitle NOTIFY showTitleChanged)
53 /**
54 * The id of the current face. For example `org.kde.ksysguard.textonly`
55 */
56 Q_PROPERTY(QString faceId READ faceId WRITE setFaceId NOTIFY faceIdChanged)
57 /**
58 * Sensors that are typically used to display a total in some way or form. For example in the pie
59 * char face they are not drawn as part of the chart but appear in the centre of it.
60 */
61 Q_PROPERTY(QJsonArray totalSensors READ totalSensors WRITE setTotalSensors NOTIFY totalSensorsChanged)
62 /**
63 * Sensors that should always be shown in the face. This is the main list of sensors that are of
64 * the most interest.
65 */
66 Q_PROPERTY(QJsonArray highPrioritySensorIds READ highPrioritySensorIds WRITE setHighPrioritySensorIds NOTIFY highPrioritySensorIdsChanged)
67 /**
68 * Maps sensorIds to colors that can be used when a color for something relating to a
69 * specific sensor is needed.
70 */
71 Q_PROPERTY(QVariantMap sensorColors READ sensorColors WRITE setSensorColors NOTIFY sensorColorsChanged)
72
73 /**
74 * Maps sensorIds to user configurable labels than should be displayed instead of the name of the sensor.
75 */
76 Q_PROPERTY(QVariantMap sensorLabels READ sensorLabels WRITE setSensorLabels NOTIFY sensorLabelsChanged)
77
78 /**
79 * Secondary list of sensors. These sensors do not necessarily appear in main part of the face.
80 * For example in most faces they are just added to the legend.
81 */
82 Q_PROPERTY(QJsonArray lowPrioritySensorIds READ lowPrioritySensorIds WRITE setLowPrioritySensorIds NOTIFY lowPrioritySensorIdsChanged)
83
84 /**
85 * The name of the current face
86 */
87 Q_PROPERTY(QString name READ name NOTIFY faceIdChanged)
88 /**
89 * The icon of the current face
90 */
91 Q_PROPERTY(QString icon READ icon NOTIFY faceIdChanged)
92 /**
93 * Whether the current face supports sensor colors
94 */
95 Q_PROPERTY(bool supportsSensorsColors READ supportsSensorsColors NOTIFY faceIdChanged)
96 /**
97 * Whether the current face can display total sensors
98 */
99 Q_PROPERTY(bool supportsTotalSensors READ supportsTotalSensors NOTIFY faceIdChanged)
100 /**
101 * Whether the current face can display low priority sensors
102 */
103 Q_PROPERTY(bool supportsLowPrioritySensors READ supportsLowPrioritySensors NOTIFY faceIdChanged)
104 /**
105 * The amount of total sensors the current face supports
106 */
107 Q_PROPERTY(int maxTotalSensors READ maxTotalSensors NOTIFY faceIdChanged)
108 /**
109 * A map of config options and values that are specific to the current face as defined by the
110 * `main.xml` of the face.
111 * @see faceConfigUi
112 */
113 Q_PROPERTY(KConfigPropertyMap *faceConfiguration READ faceConfiguration NOTIFY faceConfigurationChanged)
114
115 /**
116 * The full representation of the current face. Typically includes additional elements like
117 * a legend or title
118 */
119 Q_PROPERTY(QQuickItem *fullRepresentation READ fullRepresentation NOTIFY faceIdChanged)
120 /**
121 * The compact representation of the current face. Typically only includes the main visualization
122 * of the data without legend, title, etc.
123 */
124 Q_PROPERTY(QQuickItem *compactRepresentation READ compactRepresentation NOTIFY faceIdChanged)
125 /**
126 * A user interface that is suited for configuring the face specific options.
127 * Emits `configurationChanged` if a config value changed. To apply the changes call `saveConfig`
128 * on it.
129 * @see faceConfiguration
130 */
131 Q_PROPERTY(QQuickItem *faceConfigUi READ faceConfigUi NOTIFY faceIdChanged)
132 /**
133 * A user interface for configuring the general appearance of a face like the title and the used
134 * face.
135 * Emits `configurationChanged` if a config value changed. To apply the changes call `saveConfig`
136 * on it.
137 */
138 Q_PROPERTY(QQuickItem *appearanceConfigUi READ appearanceConfigUi NOTIFY faceIdChanged)
139 /**
140 * A user interface for configuring which sensors are displayed in a face
141 * Emits `configurationChanged` if a config value changed. To apply the changes call `saveConfig`
142 * on it.
143 */
144 Q_PROPERTY(QQuickItem *sensorsConfigUi READ sensorsConfigUi NOTIFY faceIdChanged)
145
146 /**
147 * A list of all available faces. The name is available as the display role and the id as `pluginId`
148 */
149 Q_PROPERTY(QAbstractItemModel *availableFacesModel READ availableFacesModel CONSTANT)
150 /**
151 * A list of available face presets. The name is available as the display role, the id as `pluginId`.
152 * The properties of the preset can be accessed via the `config` role.
153 */
154 Q_PROPERTY(QAbstractItemModel *availablePresetsModel READ availablePresetsModel CONSTANT)
155 /**
156 * The minimum time that needs to elapse, in milliseconds, between updates of the face.
157 */
158 Q_PROPERTY(int updateRateLimit READ updateRateLimit WRITE setUpdateRateLimit NOTIFY updateRateLimitChanged)
159 /**
160 * Contains the paths of missing sensors, if there are any.
161 */
162 Q_PROPERTY(QJsonArray missingSensors READ missingSensors NOTIFY missingSensorsChanged)
163
164public:
165 /**
166 * Creates a new SensorFaceController.
167 * This is only useful for applications that want display SensorFaces.
168 *
169 * SensorFaces can access the controller that created them using their `SensorFace::controller`
170 * property.
171 * @param config The controller uses this config group to read and save the face configuration
172 * @param engine This engine will be used for creating the Qml components
173 */
175 ~SensorFaceController() override;
176
177 /**
178 * Retrieve the KConfigGroup this controller is using to store configuration.
179 *
180 * This is primarily intended to allow adding child groups to the face
181 * configuration.
182 */
183 KConfigGroup configGroup() const;
184
185 void setFaceId(const QString &face);
186 QString faceId() const;
187
188 QQuickItem *fullRepresentation();
189 QQuickItem *compactRepresentation();
190 QQuickItem *faceConfigUi();
191 QQuickItem *appearanceConfigUi();
192 QQuickItem *sensorsConfigUi();
193
194 KConfigPropertyMap *faceConfiguration() const;
195
196 QString title() const;
197 void setTitle(const QString &title);
198
199 bool showTitle() const;
200 void setShowTitle(bool show);
201
202 QJsonArray totalSensors() const;
203 void setTotalSensors(const QJsonArray &sensor);
204
205 QJsonArray highPrioritySensorIds() const;
206 void setHighPrioritySensorIds(const QJsonArray &ids);
207
208 QJsonArray sensors() const;
209
210 QJsonArray lowPrioritySensorIds() const;
211 void setLowPrioritySensorIds(const QJsonArray &ids);
212
213 QJsonArray missingSensors() const;
214
215 QVariantMap sensorColors() const;
216 void setSensorColors(const QVariantMap &colors);
217
218 QVariantMap sensorLabels() const;
219 void setSensorLabels(const QVariantMap &labels);
220
221 int updateRateLimit() const;
222 void setUpdateRateLimit(int limit);
223
224 // from face config, immutable by the user
225 QString name() const;
226 const QString icon() const;
227
228 bool supportsSensorsColors() const;
229 bool supportsTotalSensors() const;
230 bool supportsLowPrioritySensors() const;
231
232 int maxTotalSensors() const;
233
234 QAbstractItemModel *availableFacesModel();
235 QAbstractItemModel *availablePresetsModel();
236
237 /**
238 * Reload the configuration.
239 */
240 Q_INVOKABLE void reloadConfig();
241 /**
242 * Loads a specific preset
243 * @see availablePresetsModel
244 */
245 Q_INVOKABLE void loadPreset(const QString &preset);
246 /**
247 * Save the current configuration as a preset
248 */
249 Q_INVOKABLE void savePreset();
250 /**
251 * Uninstall a specific preset
252 */
253 Q_INVOKABLE void uninstallPreset(const QString &pluginId);
254
255 /**
256 * Whether the controller should sync configuration changes
257 * @see setShouldSync
258 */
259 bool shouldSync() const;
260 /**
261 * Specifies if the controller should automatically sync configuration changes.
262 * @param sync If `true` applied config changes are written to the KConfigGroup that was
263 * specified in the @ref SensorFaceController::SensorFaceController "constructor". If `false`
264 * config changes are applied after calling `saveConfig` on a configuration ui but not written
265 * to the KConfigGroup.
266 */
267 void setShouldSync(bool sync);
268
269 /**
270 * Reload only the face configuration.
271 *
272 * This does not touch sensors, colors or anything else, only the config
273 * loaded from the face package is reloaded.
274 */
275 Q_INVOKABLE void reloadFaceConfiguration();
276
277 /**
278 * Replace one sensor with another.
279 *
280 * This replaces a configured sensor with a new one. This replacement happens
281 * inside the configuration, bypassing thing like the sensor properties which
282 * are populated with resolved sensor ids rather than the configured entries.
283 *
284 * You should call @ref reloadConfig once you have made all replacements.
285 */
286 Q_INVOKABLE void replaceSensors(const QString &from, const QString &to);
287
288Q_SIGNALS:
289 void faceIdChanged();
290 void titleChanged();
291 void showTitleChanged();
292 void totalSensorsChanged();
293 void highPrioritySensorIdsChanged();
294 void lowPrioritySensorIdsChanged();
295 void sensorsChanged();
296 void sensorColorsChanged();
297 void sensorLabelsChanged();
298 void updateRateLimitChanged();
299 void faceConfigurationChanged();
300 void missingSensorsChanged();
301
302private:
303 const std::unique_ptr<SensorFaceControllerPrivate> d;
304};
305}
The SensorFaceController links sensor faces and applications in which these faces are shown.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Tue Mar 26 2024 11:21:23 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.