File indexing completed on 2024-05-05 17:39:47
0001 /* 0002 SPDX-FileCopyrightText: 2020 Marco Martin <mart@kde.org> 0003 0004 SPDX-License-Identifier: LGPL-2.0-or-later 0005 */ 0006 0007 #pragma once 0008 0009 #include <QAbstractItemModel> 0010 #include <QObject> 0011 #include <QPointer> 0012 #include <QQuickItem> 0013 0014 #include <KConfigGroup> 0015 0016 #include "sensorfaces_export.h" 0017 0018 class KConfigPropertyMap; 0019 class QQmlEngine; 0020 class KDesktopFile; 0021 class KConfigLoader; 0022 0023 namespace KSysGuard 0024 { 0025 class SensorFace; 0026 class SensorFaceControllerPrivate; 0027 0028 /** 0029 * The SensorFaceController links sensor faces and applications in which these faces are shown. It 0030 * abstracts the configuration and properties of faces. 0031 * 0032 * For faces it offers information about which sensors should be displayed and hints set by the 0033 * application about how the information should be displayed. It can be accessed by faces using 0034 * the `SensorFace::controller` property. 0035 * 0036 * Applications can use this class to instantiate faces from a given config and for querying the 0037 * capabilities of faces. 0038 * 0039 * @since 5.19 0040 */ 0041 class SENSORFACES_EXPORT SensorFaceController : public QObject 0042 { 0043 Q_OBJECT 0044 /** 0045 * A title for the face. 0046 * @see showTitle 0047 */ 0048 Q_PROPERTY(QString title READ title WRITE setTitle NOTIFY titleChanged) 0049 /** Whether the title should be displayed or if it should be hidden instead 0050 * @see title 0051 */ 0052 Q_PROPERTY(bool showTitle READ showTitle WRITE setShowTitle NOTIFY showTitleChanged) 0053 /** 0054 * The id of the current face. For example `org.kde.ksysguard.textonly` 0055 */ 0056 Q_PROPERTY(QString faceId READ faceId WRITE setFaceId NOTIFY faceIdChanged) 0057 /** 0058 * Sensors that are typically used to display a total in some way or form. For example in the pie 0059 * char face they are not drawn as part of the chart but appear in the centre of it. 0060 */ 0061 Q_PROPERTY(QJsonArray totalSensors READ totalSensors WRITE setTotalSensors NOTIFY totalSensorsChanged) 0062 /** 0063 * Sensors that should always be shown in the face. This is the main list of sensors that are of 0064 * the most interest. 0065 */ 0066 Q_PROPERTY(QJsonArray highPrioritySensorIds READ highPrioritySensorIds WRITE setHighPrioritySensorIds NOTIFY highPrioritySensorIdsChanged) 0067 /** 0068 * Maps sensorIds to colors that can be used when a color for something relating to a 0069 * specific sensor is needed. 0070 */ 0071 Q_PROPERTY(QVariantMap sensorColors READ sensorColors WRITE setSensorColors NOTIFY sensorColorsChanged) 0072 0073 /** 0074 * Maps sensorIds to user configurable labels than should be displayed instead of the name of the sensor. 0075 */ 0076 Q_PROPERTY(QVariantMap sensorLabels READ sensorLabels WRITE setSensorLabels NOTIFY sensorLabelsChanged) 0077 0078 /** 0079 * Secondary list of sensors. These sensors do not necessarily appear in main part of the face. 0080 * For example in most faces they are just added to the legend. 0081 */ 0082 Q_PROPERTY(QJsonArray lowPrioritySensorIds READ lowPrioritySensorIds WRITE setLowPrioritySensorIds NOTIFY lowPrioritySensorIdsChanged) 0083 0084 /** 0085 * The name of the current face 0086 */ 0087 Q_PROPERTY(QString name READ name NOTIFY faceIdChanged) 0088 /** 0089 * The icon of the current face 0090 */ 0091 Q_PROPERTY(QString icon READ icon NOTIFY faceIdChanged) 0092 /** 0093 * Whether the current face supports sensor colors 0094 */ 0095 Q_PROPERTY(bool supportsSensorsColors READ supportsSensorsColors NOTIFY faceIdChanged) 0096 /** 0097 * Whether the current face can display total sensors 0098 */ 0099 Q_PROPERTY(bool supportsTotalSensors READ supportsTotalSensors NOTIFY faceIdChanged) 0100 /** 0101 * Whether the current face can display low priority sensors 0102 */ 0103 Q_PROPERTY(bool supportsLowPrioritySensors READ supportsLowPrioritySensors NOTIFY faceIdChanged) 0104 /** 0105 * The amount of total sensors the current face supports 0106 */ 0107 Q_PROPERTY(int maxTotalSensors READ maxTotalSensors NOTIFY faceIdChanged) 0108 /** 0109 * A map of config options and values that are specific to the current face as defined by the 0110 * `main.xml` of the face. 0111 * @see faceConfigUi 0112 */ 0113 Q_PROPERTY(KConfigPropertyMap *faceConfiguration READ faceConfiguration NOTIFY faceConfigurationChanged) 0114 0115 /** 0116 * The full representation of the current face. Typically includes additional elements like 0117 * a legend or title 0118 */ 0119 Q_PROPERTY(QQuickItem *fullRepresentation READ fullRepresentation NOTIFY faceIdChanged) 0120 /** 0121 * The compact representation of the current face. Typically only includes the main visualization 0122 * of the data without legend, title, etc. 0123 */ 0124 Q_PROPERTY(QQuickItem *compactRepresentation READ compactRepresentation NOTIFY faceIdChanged) 0125 /** 0126 * A user interface that is suited for configuring the face specific options. 0127 * Emits `configurationChanged` if a config value changed. To apply the changes call `saveConfig` 0128 * on it. 0129 * @see faceConfiguration 0130 */ 0131 Q_PROPERTY(QQuickItem *faceConfigUi READ faceConfigUi NOTIFY faceIdChanged) 0132 /** 0133 * A user interface for configuring the general appearance of a face like the title and the used 0134 * face. 0135 * Emits `configurationChanged` if a config value changed. To apply the changes call `saveConfig` 0136 * on it. 0137 */ 0138 Q_PROPERTY(QQuickItem *appearanceConfigUi READ appearanceConfigUi NOTIFY faceIdChanged) 0139 /** 0140 * A user interface for configuring which sensors are displayed in a face 0141 * Emits `configurationChanged` if a config value changed. To apply the changes call `saveConfig` 0142 * on it. 0143 */ 0144 Q_PROPERTY(QQuickItem *sensorsConfigUi READ sensorsConfigUi NOTIFY faceIdChanged) 0145 0146 /** 0147 * A list of all available faces. The name is available as the display role and the id as `pluginId` 0148 */ 0149 Q_PROPERTY(QAbstractItemModel *availableFacesModel READ availableFacesModel CONSTANT) 0150 /** 0151 * A list of available face presets. The name is available as the display role, the id as `pluginId`. 0152 * The properties of the preset can be accessed via the `config` role. 0153 */ 0154 Q_PROPERTY(QAbstractItemModel *availablePresetsModel READ availablePresetsModel CONSTANT) 0155 /** 0156 * The minimum time that needs to elapse, in milliseconds, between updates of the face. 0157 */ 0158 Q_PROPERTY(int updateRateLimit READ updateRateLimit WRITE setUpdateRateLimit NOTIFY updateRateLimitChanged) 0159 /** 0160 * Contains the paths of missing sensors, if there are any. 0161 */ 0162 Q_PROPERTY(QJsonArray missingSensors READ missingSensors NOTIFY missingSensorsChanged) 0163 0164 public: 0165 /** 0166 * Creates a new SensorFaceController. 0167 * This is only useful for applications that want display SensorFaces. 0168 * 0169 * SensorFaces can access the controller that created them using their `SensorFace::controller` 0170 * property. 0171 * @param config The controller uses this config group to read and save the face configuration 0172 * @param engine This engine will be used for creating the Qml components 0173 */ 0174 SensorFaceController(KConfigGroup &config, QQmlEngine *engine); 0175 ~SensorFaceController() override; 0176 0177 /** 0178 * Retrieve the KConfigGroup this controller is using to store configuration. 0179 * 0180 * This is primarily intended to allow adding child groups to the face 0181 * configuration. 0182 */ 0183 KConfigGroup configGroup() const; 0184 0185 void setFaceId(const QString &face); 0186 QString faceId() const; 0187 0188 QQuickItem *fullRepresentation(); 0189 QQuickItem *compactRepresentation(); 0190 QQuickItem *faceConfigUi(); 0191 QQuickItem *appearanceConfigUi(); 0192 QQuickItem *sensorsConfigUi(); 0193 0194 KConfigPropertyMap *faceConfiguration() const; 0195 0196 QString title() const; 0197 void setTitle(const QString &title); 0198 0199 bool showTitle() const; 0200 void setShowTitle(bool show); 0201 0202 QJsonArray totalSensors() const; 0203 void setTotalSensors(const QJsonArray &sensor); 0204 0205 QJsonArray highPrioritySensorIds() const; 0206 void setHighPrioritySensorIds(const QJsonArray &ids); 0207 0208 QJsonArray sensors() const; 0209 0210 QJsonArray lowPrioritySensorIds() const; 0211 void setLowPrioritySensorIds(const QJsonArray &ids); 0212 0213 QJsonArray missingSensors() const; 0214 0215 QVariantMap sensorColors() const; 0216 void setSensorColors(const QVariantMap &colors); 0217 0218 QVariantMap sensorLabels() const; 0219 void setSensorLabels(const QVariantMap &labels); 0220 0221 int updateRateLimit() const; 0222 void setUpdateRateLimit(int limit); 0223 0224 // from face config, immutable by the user 0225 QString name() const; 0226 const QString icon() const; 0227 0228 bool supportsSensorsColors() const; 0229 bool supportsTotalSensors() const; 0230 bool supportsLowPrioritySensors() const; 0231 0232 int maxTotalSensors() const; 0233 0234 QAbstractItemModel *availableFacesModel(); 0235 QAbstractItemModel *availablePresetsModel(); 0236 0237 /** 0238 * Reload the configuration. 0239 */ 0240 Q_INVOKABLE void reloadConfig(); 0241 /** 0242 * Loads a specific preset 0243 * @see availablePresetsModel 0244 */ 0245 Q_INVOKABLE void loadPreset(const QString &preset); 0246 /** 0247 * Save the current configuration as a preset 0248 */ 0249 Q_INVOKABLE void savePreset(); 0250 /** 0251 * Uninstall a specific preset 0252 */ 0253 Q_INVOKABLE void uninstallPreset(const QString &pluginId); 0254 0255 /** 0256 * Whether the controller should sync configuration changes 0257 * @see setShouldSync 0258 */ 0259 bool shouldSync() const; 0260 /** 0261 * Specifies if the controller should automatically sync configuration changes. 0262 * @param sync If `true` applied config changes are written to the KConfigGroup that was 0263 * specified in the @ref SensorFaceController::SensorFaceController "constructor". If `false` 0264 * config changes are applied after calling `saveConfig` on a configuration ui but not written 0265 * to the KConfigGroup. 0266 */ 0267 void setShouldSync(bool sync); 0268 0269 /** 0270 * Reload only the face configuration. 0271 * 0272 * This does not touch sensors, colors or anything else, only the config 0273 * loaded from the face package is reloaded. 0274 */ 0275 Q_INVOKABLE void reloadFaceConfiguration(); 0276 0277 /** 0278 * Replace one sensor with another. 0279 * 0280 * This replaces a configured sensor with a new one. This replacement happens 0281 * inside the configuration, bypassing thing like the sensor properties which 0282 * are populated with resolved sensor ids rather than the configured entries. 0283 * 0284 * You should call @ref reloadConfig once you have made all replacements. 0285 */ 0286 Q_INVOKABLE void replaceSensors(const QString &from, const QString &to); 0287 0288 Q_SIGNALS: 0289 void faceIdChanged(); 0290 void titleChanged(); 0291 void showTitleChanged(); 0292 void totalSensorsChanged(); 0293 void highPrioritySensorIdsChanged(); 0294 void lowPrioritySensorIdsChanged(); 0295 void sensorsChanged(); 0296 void sensorColorsChanged(); 0297 void sensorLabelsChanged(); 0298 void updateRateLimitChanged(); 0299 void faceConfigurationChanged(); 0300 void missingSensorsChanged(); 0301 0302 private: 0303 const std::unique_ptr<SensorFaceControllerPrivate> d; 0304 }; 0305 }