1/*
2 SPDX-FileCopyrightText: 2020 Benjamin Port <benjamin.port@enioka.com>
3
4 SPDX-License-Identifier: LGPL-2.0-only
5*/
6
7#ifndef KCMODULEDATA_H
8#define KCMODULEDATA_H
9
10#include <QObject>
11#include <QVariantList>
12#include <kcmutilscore_export.h>
13#include <memory>
14
15class KCModuleDataPrivate;
16class KCoreConfigSkeleton;
17
18class QAction;
19
20/*!
21 * \class KCModuleData
22 * \inmodule KCMUtilsCore
23 * \brief A base class that offers information about a KCModule state.
24 * \since 5.74
25 */
26class KCMUTILSCORE_EXPORT KCModuleData : public QObject
27{
28 Q_OBJECT
29public:
30 /*!
31 *
32 */
33 explicit KCModuleData(QObject *parent = nullptr);
34 ~KCModuleData() override;
35
36 /*!
37 * \brief Checks if the configuration is identical to the default one.
38 *
39 * Returns \c true if the module configuration is in the default state, \c false otherwise.
40 */
41 virtual bool isDefaults() const;
42
43 /*!
44 * \brief Reverts the module to default values and saves them.
45 */
46 virtual void revertToDefaults();
47
48 /*!
49 * \brief Returns whether this module matches a given \a query.
50 *
51 * The \a query is not expected to be a regex pattern but a full text search.
52 */
53 virtual bool matchesQuery(const QString &query) const;
54
55 /*!
56 * \brief An auxiliary action associated with this KCM.
57 *
58 * \since 6.18
59 */
60 QAction *auxiliaryAction() const;
61
62 /**
63 * \brief Whether this KCM is relevant in the current environment.
64 *
65 * The displaying application might not show this KCM if it is
66 * not relevant. For example, a KCM for configuring touchscreens
67 * could be hidden if no touchscreen is present.
68 *
69 * Default is true.
70 *
71 * \since 6.18
72 */
73 bool isRelevant() const;
74
75Q_SIGNALS:
76 /*!
77 * \brief Emitted when KCModuleData is loaded.
78 */
79 void loaded();
80
81 /*!
82 * \internal
83 * \brief Triggers the emit of \sa loaded() signal.
84 *
85 * This is the default behavior.
86 *
87 * To handle when loaded() is emitted in subclass,
88 * disconnect this signal in the derived constructor.
89 */
90 void aboutToLoad(QPrivateSignal);
91
92 /*!
93 * \brief Emitted when the auxiliary action changes.
94 *
95 * \note The QAction can change its state (e.g. being enabled)
96 * without the action object itself being replaced.
97 *
98 * \since 6.18
99 */
100 void auxiliaryActionChanged(QAction *action);
101
102 /*!
103 * \brief Emitted when the relevancy of this KCM changes.
104 *
105 * For example, after (un)plugging a relevant device.
106 *
107 * \since 6.18
108 */
109 void relevantChanged(bool relevant);
110
111protected:
112 /*!
113 * \brief Sets an auxiliary action for this KCM.
114 *
115 * This can be displayed alongside this KCM in a list of settings
116 * and provide quick access to a feature in the KCM without opening
117 * it.
118 *
119 * For example, a "Pair new device" action or, in case of a checkable
120 * action, a Switch to turn on/off a certain feature or device.
121 */
122 void setAuxiliaryAction(QAction *action);
123
124 /*!
125 * \brief Sets whether this KCM is relevant in the current environment.
126 *
127 * This can hide the KCM in a list of settings when it is currently
128 * not relevant.
129 *
130 * For example to show touchscreen settings only when a touchscreen
131 * is present. Default is true.
132 */
133 void setRelevant(bool relevant);
134
135protected Q_SLOTS:
136 /*!
137 * \brief Allow to manually register a \a skeleton class.
138 *
139 * Used by a derived class when automatic discovery is not possible.
140 */
141 void registerSkeleton(KCoreConfigSkeleton *skeleton);
142
143 /*!
144 * \brief Automatically register child skeletons.
145 *
146 * Call it in your subclass constructor after skeleton creation
147 */
148 void autoRegisterSkeletons();
149
150private:
151 const std::unique_ptr<KCModuleDataPrivate> d;
152 friend class KCModuleDataPrivate;
153};
154
155#endif
156

source code of kcmutils/src/core/kcmoduledata.h