Libksysguard

SensorFaceController.h
1 /*
2  Copyright (C) 2020 Marco Martin <[email protected]>
3 
4  This library is free software; you can redistribute it and/or
5  modify it under the terms of the GNU Library General Public
6  License as published by the Free Software Foundation; either
7  version 2 of the License, or (at your option) any later version.
8 
9  This library is distributed in the hope that it will be useful,
10  but WITHOUT ANY WARRANTY; without even the implied warranty of
11  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12  Library General Public License for more details.
13 
14  You should have received a copy of the GNU Library General Public License
15  along with this library; see the file COPYING.LIB. If not, write to
16  the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17  Boston, MA 02110-1301, USA.
18 */
19 
20 #pragma once
21 
22 #include <QObject>
23 #include <QPointer>
24 #include <QQuickItem>
25 #include <QAbstractItemModel>
26 
27 #include <KConfigGroup>
28 
29 #include "sensorfaces_export.h"
30 
31 namespace KDeclarative {
32  class ConfigPropertyMap;
33 }
34 
35 class QQmlEngine;
36 class KDesktopFile;
37 class KConfigLoader;
38 
39 namespace KSysGuard {
40 
41 class SensorFace;
42 class SensorFaceControllerPrivate;
43 
44 /**
45  * The SensorFaceController links sensor faces and applications in which these faces are shown. It
46  * abstracts the configuration and properties of faces.
47  *
48  * For faces it offers information about which sensors should be displayed and hints set by the
49  * application about how the information should be displayed. It can be accessed by faces using
50  * the `SensorFace::controller` property.
51  *
52  * Applications can use this class to instantiate faces from a given config and for querying the
53  * capabilities of faces.
54  *
55  * @since 5.19
56  */
57 class SENSORFACES_EXPORT SensorFaceController : public QObject
58 {
59  Q_OBJECT
60  /**
61  * A title for the face.
62  * @see showTitle
63  */
64  Q_PROPERTY(QString title READ title WRITE setTitle NOTIFY titleChanged)
65  /** Whether the title should be displayed or if it should be hidden instead
66  * @see title
67  */
68  Q_PROPERTY(bool showTitle READ showTitle WRITE setShowTitle NOTIFY showTitleChanged)
69  /**
70  * The id of the current face. For example `org.kde.ksysguard.textonly`
71  */
72  Q_PROPERTY(QString faceId READ faceId WRITE setFaceId NOTIFY faceIdChanged)
73  /**
74  * Sensors that are typically used to display a total in some way or form. For example in the pie
75  * char face they are not drawn as part of the chart but appear in the centre of it.
76  */
77  Q_PROPERTY(QJsonArray totalSensors READ totalSensors WRITE setTotalSensors NOTIFY totalSensorsChanged)
78  /**
79  * Sensors that should always be shown in the face. This is the main list of sensors that are of
80  * the most interest.
81  */
82  Q_PROPERTY(QJsonArray highPrioritySensorIds READ highPrioritySensorIds WRITE setHighPrioritySensorIds NOTIFY highPrioritySensorIdsChanged)
83  /**
84  * Maps sensorIds to colors that can be used when a color for something relating to a
85  * specific sensor is needed.
86  */
87  Q_PROPERTY(QVariantMap sensorColors READ sensorColors WRITE setSensorColors NOTIFY sensorColorsChanged)
88  /**
89  * Secondary list of sensors. These sensors do not necessarily appear in main part of the face.
90  * For example in most faces they are just added to the legend.
91  */
92  Q_PROPERTY(QJsonArray lowPrioritySensorIds READ lowPrioritySensorIds WRITE setLowPrioritySensorIds NOTIFY lowPrioritySensorIdsChanged)
93 
94  /**
95  * The name of the current face
96  */
97  Q_PROPERTY(QString name READ name NOTIFY faceIdChanged)
98  /**
99  * The icon of the current face
100  */
101  Q_PROPERTY(QString icon READ icon NOTIFY faceIdChanged)
102  /**
103  * Whether the current face supports sensor colors
104  */
105  Q_PROPERTY(bool supportsSensorsColors READ supportsSensorsColors NOTIFY faceIdChanged)
106  /**
107  * Whether the current face can display total sensors
108  */
109  Q_PROPERTY(bool supportsTotalSensors READ supportsTotalSensors NOTIFY faceIdChanged)
110  /**
111  * Whether the current face can display low priority sensors
112  */
113  Q_PROPERTY(bool supportsLowPrioritySensors READ supportsLowPrioritySensors NOTIFY faceIdChanged)
114  /**
115  * The amount of total sensors the current face supports
116  */
117  Q_PROPERTY(int maxTotalSensors READ maxTotalSensors NOTIFY faceIdChanged)
118  /**
119  * A map of config options and values that are specific to the current face as defined by the
120  * `main.xml` of the face.
121  * @see faceConfigUi
122  */
123  Q_PROPERTY(KDeclarative::ConfigPropertyMap *faceConfiguration READ faceConfiguration NOTIFY faceIdChanged)
124 
125  /**
126  * The full represenation of the current face. Typically includes additional elements like
127  * a legend or title
128  */
129  Q_PROPERTY(QQuickItem *fullRepresentation READ fullRepresentation NOTIFY faceIdChanged)
130  /**
131  * The compact represenation of the current face. Typically only includes the main visualization
132  * of the data without legend, title, etc.
133  */
134  Q_PROPERTY(QQuickItem *compactRepresentation READ compactRepresentation NOTIFY faceIdChanged)
135  /**
136  * A user interace that is suited for configuring the face specific options.
137  * Emits `configurationChanged` if a config value changed. To apply the changes call `saveConfig`
138  * on it.
139  * @see faceConfiguration
140  */
141  Q_PROPERTY(QQuickItem *faceConfigUi READ faceConfigUi NOTIFY faceIdChanged)
142  /**
143  * A user interface for configuring the general appearance of a face like the title and the used
144  * face.
145  * Emits `configurationChanged` if a config value changed. To apply the changes call `saveConfig`
146  * on it.
147  */
148  Q_PROPERTY(QQuickItem *appearanceConfigUi READ appearanceConfigUi NOTIFY faceIdChanged)
149  /**
150  * A user interface for configuring which sensors are displayed in a face
151  * Emits `configurationChanged` if a config value changed. To apply the changes call `saveConfig`
152  * on it.
153  */
154  Q_PROPERTY(QQuickItem *sensorsConfigUi READ sensorsConfigUi NOTIFY faceIdChanged)
155 
156  /**
157  * A list of all available faces. The name is available as the display role and the id as `pluginId`
158  */
159  Q_PROPERTY(QAbstractItemModel *availableFacesModel READ availableFacesModel CONSTANT)
160  /**
161  * A list of available face presets. The name is available as the display role, the id as `pluginId`.
162  * The properties of the preset can be accessed via the `config` role.
163  */
164  Q_PROPERTY(QAbstractItemModel *availablePresetsModel READ availablePresetsModel CONSTANT)
165 
166 public:
167  /**
168  * Creates a new SensorFaceController.
169  * This is only useful for applications that want display SensorFaces.
170  *
171  * SensorFaces can acces the controller that created them using their `SensorFace::controller`
172  * property.
173  * @param config The controller uses this config group to read and save the face configuration
174  * @param engine This engine will be used for creating the Qml components
175  */
176  SensorFaceController(KConfigGroup &config, QQmlEngine *engine);
178 
179  void setFaceId(const QString &face);
180  QString faceId() const;
181 
182  QQuickItem *fullRepresentation();
183  QQuickItem *compactRepresentation();
184  QQuickItem *faceConfigUi();
185  QQuickItem *appearanceConfigUi();
186  QQuickItem *sensorsConfigUi();
187 
188  KDeclarative::ConfigPropertyMap *faceConfiguration() const;
189 
190  QString title() const;
191  void setTitle(const QString &title);
192 
193  bool showTitle() const;
194  void setShowTitle(bool show);
195 
196  QJsonArray totalSensors() const;
197  void setTotalSensors(const QJsonArray &sensor);
198 
199  QJsonArray highPrioritySensorIds() const;
200  void setHighPrioritySensorIds(const QJsonArray &ids);
201 
202  QJsonArray sensors() const;
203 
204  QJsonArray lowPrioritySensorIds() const;
205  void setLowPrioritySensorIds(const QJsonArray &ids);
206 
207  QVariantMap sensorColors() const;
208  void setSensorColors(const QVariantMap &colors);
209 
210  // from face config, immutable by the user
211  QString name() const;
212  const QString icon() const;
213 
214  bool supportsSensorsColors() const;
215  bool supportsTotalSensors() const;
216  bool supportsLowPrioritySensors() const;
217 
218  int maxTotalSensors() const;
219 
220  QAbstractItemModel *availableFacesModel();
221  QAbstractItemModel *availablePresetsModel();
222 
223  /**
224  * Reload the configuration.
225  */
226  Q_INVOKABLE void reloadConfig();
227  /**
228  * Loads a specific preset
229  * @see availablePresetsModel
230  */
231  Q_INVOKABLE void loadPreset(const QString &preset);
232  /**
233  * Save the current configuration as a preset
234  */
235  Q_INVOKABLE void savePreset();
236  /**
237  * Uninstall a specific preset
238  */
239  Q_INVOKABLE void uninstallPreset(const QString &pluginId);
240 
241  /**
242  * Whether the controller should sync configuration changes
243  * @see setShouldSync
244  */
245  bool shouldSync() const;
246  /**
247  * Specifies if the controller should automatically sync configuration changes.
248  * @param sync If `true` applied config changes are written to the KConfigGroup that was
249  * specified in the @ref SensorFaceController::SensorFaceController "constructor". If `false`
250  * config changes are applied after calling `saveConfig` on a configuration ui but not written
251  * to the KConfigGroup.
252  */
253  void setShouldSync(bool sync);
254 
255 Q_SIGNALS:
256  void faceIdChanged();
257  void titleChanged();
258  void showTitleChanged();
259  void totalSensorsChanged();
260  void highPrioritySensorIdsChanged();
261  void lowPrioritySensorIdsChanged();
262  void sensorsChanged();
263  void sensorColorsChanged();
264 
265 private:
266  const std::unique_ptr<SensorFaceControllerPrivate> d;
267 };
268 }
The SensorFaceController links sensor faces and applications in which these faces are shown...
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Thu Mar 4 2021 23:09:25 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.