Libksysguard

Sensor.h
1/*
2 SPDX-FileCopyrightText: 2019 Vlad Zahorodnii <vlad.zahorodnii@kde.org>
3 SPDX-FileCopyrightText: 2020 Arjen Hiemstra <ahiemstra@heimr.nl>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#pragma once
9
10#include <memory>
11
12#include <QObject>
13#include <QQmlParserStatus>
14#include <QString>
15#include <QVariant>
16
17#include "formatter/Unit.h"
18
19#include "sensors_export.h"
20
21namespace KSysGuard
22{
23class SensorData;
24class SensorInfo;
25class SensorQuery;
26
27/**
28 * An object encapsulating a backend sensor.
29 *
30 * This class represents a sensor as exposed by the backend. It allows querying
31 * various metadata properties of the sensor as well as the current value.
32 */
33class SENSORS_EXPORT Sensor : public QObject, public QQmlParserStatus
34{
35 Q_OBJECT
36 Q_INTERFACES(QQmlParserStatus)
37
38 /**
39 * The path to the backend sensor this Sensor represents.
40 */
41 Q_PROPERTY(QString sensorId READ sensorId WRITE setSensorId NOTIFY sensorIdChanged)
42 /**
43 * The user-visible name of this Sensor.
44 */
45 Q_PROPERTY(QString name READ name NOTIFY metaDataChanged)
46 /**
47 * A shortened name that can be displayed when space is constrained.
48 *
49 * The value is the same as name if shortName was not provided by the backend.
50 */
51 Q_PROPERTY(QString shortName READ shortName NOTIFY metaDataChanged)
52 /**
53 * A description of the Sensor.
54 */
55 Q_PROPERTY(QString description READ description NOTIFY metaDataChanged)
56 /**
57 * The unit of this Sensor.
58 */
59 Q_PROPERTY(KSysGuard::Unit unit READ unit NOTIFY metaDataChanged)
60 /**
61 * The minimum value this Sensor can have.
62 */
63 Q_PROPERTY(qreal minimum READ minimum NOTIFY metaDataChanged)
64 /**
65 * The maximum value this Sensor can have.
66 */
67 Q_PROPERTY(qreal maximum READ maximum NOTIFY metaDataChanged)
68 /**
69 * The QVariant type for this sensor.
70 *
71 * This is used to create proper default values.
72 */
73 Q_PROPERTY(QVariant::Type type READ type NOTIFY metaDataChanged)
74 /**
75 * The status of the sensor.
76 *
77 * Due to the asynchronous nature of the underlying code, sensors are not
78 * immediately available on construction. Instead, they need to request data
79 * from the daemon and wait for it to arrive. This property reflects where
80 * in that process this sensor is.
81 */
82 Q_PROPERTY(Status status READ status NOTIFY statusChanged)
83 /**
84 * The current value of this sensor.
85 */
86 Q_PROPERTY(QVariant value READ value NOTIFY valueChanged)
87 /**
88 * A formatted version of \property value.
89 */
90 Q_PROPERTY(QString formattedValue READ formattedValue NOTIFY valueChanged)
91 /**
92 * Should this Sensor check for changes?
93 *
94 * Note that if set to true, the sensor will only be enabled when the parent
95 * is also enabled.
96 */
97 Q_PROPERTY(bool enabled READ enabled WRITE setEnabled NOTIFY enabledChanged)
98 /**
99 * The time in milliseconds between each update of the sensor.
100 *
101 * This is primarily intended to match sampling rate to the update rate of
102 * the sensor, like when used by KQuickCharts's HistorySource.
103 *
104 * \note Currently, the update rate of the backend is fixed and this method
105 * simply matches the value from the backend. Eventually the idea is
106 * that we can support per-sensor update rates.
107 */
108 Q_PROPERTY(uint updateInterval READ updateInterval NOTIFY updateIntervalChanged)
109 /**
110 * The minimum time between updates, in milliseconds.
111 *
112 * If this is set to a positive non-zero value, at least this many
113 * milliseconds need to elapse before another value update happens, otherwise
114 * it is ignored. This effectively rate-limits the updates and will prevent
115 * value updates.
116 */
117 Q_PROPERTY(int updateRateLimit READ updateRateLimit WRITE setUpdateRateLimit NOTIFY updateRateLimitChanged RESET resetUpdateRateLimit)
118
119public:
120 /**
121 * This enum type is used to specify status of the Sensor.
122 */
123 enum class Status {
124 Unknown, ///< The sensor has no ID assigned.
125 Loading, ///< The sensor is currently being loaded.
126 Ready, ///< The sensor has been loaded.
127 Error, ///< An error occurred or the sensor has been removed.
128 Removed, ///< Removed from backend
129 };
130 Q_ENUM(Status)
131
132 explicit Sensor(QObject *parent = nullptr);
133 explicit Sensor(const QString &id, QObject *parent = nullptr);
134 /**
135 * Construct a Sensor from a SensorQuery result and index.
136 *
137 * This avoids an extra lookup for the sensor metadata.
138 */
139 Sensor(const SensorQuery &query, int index, QObject *parent = nullptr);
140 ~Sensor() override;
141
142 bool event(QEvent *event) override;
143
144 QString sensorId() const;
145 void setSensorId(const QString &id);
146 Q_SIGNAL void sensorIdChanged() const;
147
148 Status status() const;
149 Q_SIGNAL void statusChanged() const;
150
151 QString name() const;
152 QString shortName() const;
153 QString description() const;
154 KSysGuard::Unit unit() const;
155 qreal minimum() const;
156 qreal maximum() const;
157 QVariant::Type type() const;
158 /**
159 * This signal is emitted when any of the metadata properties change.
160 */
161 Q_SIGNAL void metaDataChanged() const;
162
163 /**
164 * Returns the output of the sensor.
165 *
166 * The returned value is the most recent sensor data received from the ksysguard
167 * daemon, it's not necessarily the actual current output value.
168 *
169 * The client can't control how often the sensor data is sampled. The ksysguard
170 * daemon is in charge of picking the sample rate. When the Sensor receives new
171 * output value, dataChanged signal will be emitted.
172 *
173 * @see dataChanged
174 */
175 QVariant value() const;
176 QString formattedValue() const;
177 Q_SIGNAL void valueChanged() const;
178
179 bool enabled() const;
180 void setEnabled(bool newEnabled);
181 Q_SIGNAL void enabledChanged();
182
183 uint updateInterval() const;
184 Q_SIGNAL void updateIntervalChanged();
185
186 int updateRateLimit() const;
187 void setUpdateRateLimit(int newUpdateRateLimit);
188 void resetUpdateRateLimit();
189 Q_SIGNAL void updateRateLimitChanged();
190
191 void classBegin() override;
192 void componentComplete() override;
193
194private:
195 void onMetaDataChanged(const QString &sensorId, const SensorInfo &metaData);
196 void onValueChanged(const QString &sensorId, const QVariant &value);
197 void onEnabledChanged();
198
199 class Private;
200 const std::unique_ptr<Private> d;
201};
202
203} // namespace KSysGuard
An object to query the daemon for a list of sensors and their metadata.
Definition SensorQuery.h:26
An object encapsulating a backend sensor.
Definition Sensor.h:34
Status
This enum type is used to specify status of the Sensor.
Definition Sensor.h:123
Q_SIGNAL void metaDataChanged() const
This signal is emitted when any of the metadata properties change.
Q_SCRIPTABLE CaptureState status()
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.