1/*
2 SPDX-FileCopyrightText: 2022 Alexander Lohnau <alexander.lohnau@gmx.de>
3 SPDX-License-Identifier: LGPL-2.0-or-later
4*/
5
6#ifndef KABSTRACTCONFIGMODULE_H
7#define KABSTRACTCONFIGMODULE_H
8
9#include "kcmutilscore_export.h"
10
11#include <QObject>
12
13#include <memory>
14
15class KPluginMetaData;
16class KAbstractConfigModulePrivate;
17
18/*!
19 * \class KAbstractConfigModule
20 * \inmodule KCMUtilsCore
21 * \brief Base class for QML and QWidgets config modules.
22 *
23 * \since 6.0
24 */
25class KCMUTILSCORE_EXPORT KAbstractConfigModule : public QObject
26{
27 Q_OBJECT
28
29 /*! \property KAbstractConfigModule::buttons */
30 Q_PROPERTY(KAbstractConfigModule::Buttons buttons READ buttons WRITE setButtons NOTIFY buttonsChanged)
31 /*! \property KAbstractConfigModule::defaultsIndicatorsVisible */
32 Q_PROPERTY(bool defaultsIndicatorsVisible READ defaultsIndicatorsVisible WRITE setDefaultsIndicatorsVisible NOTIFY defaultsIndicatorsVisibleChanged)
33 /*! \property KAbstractConfigModule::needsAuthorization */
34 Q_PROPERTY(bool needsAuthorization READ needsAuthorization NOTIFY authActionNameChanged)
35 /*! \property KAbstractConfigModule::representsDefaults */
36 Q_PROPERTY(bool representsDefaults READ representsDefaults WRITE setRepresentsDefaults NOTIFY representsDefaultsChanged)
37 /*! \property KAbstractConfigModule::needsSave */
38 Q_PROPERTY(bool needsSave READ needsSave WRITE setNeedsSave NOTIFY needsSaveChanged)
39 /*! \property KAbstractConfigModule::name */
40 Q_PROPERTY(QString name READ name CONSTANT)
41 /*! \property KAbstractConfigModule::description */
42 Q_PROPERTY(QString description READ description CONSTANT)
43 /*!
44 * \property KAbstractConfigModule::supportsInstantApply
45 *
46 * \since 6.16
47 */
48 Q_PROPERTY(bool supportsInstantApply READ supportsInstantApply WRITE setSupportsInstantApply NOTIFY supportsInstantApplyChanged)
49public:
50 /*!
51 * \enum KAbstractConfigModule::Button
52 * An enumeration type for the buttons used by this module.
53 *
54 * If Apply is not specified, kcmshell will show a "Close" button.
55 *
56 * \value NoAdditionalButton
57 * Shows the "Ok" and "Cancel" buttons.
58 * \value Help
59 * Shows a "Help" button.
60 * \value Default
61 * Shows a "Use Defaults" button.
62 * \value Apply
63 * Shows the "Ok", "Apply", and "Cancel" buttons.
64 * \value Export
65 * Obsolete.
66 *
67 * \sa buttons
68 * \sa setButtons
69 */
70 enum Button {
71 NoAdditionalButton = 0,
72 Help = 1,
73 Default = 2,
74 Apply = 4,
75 Export = 8,
76 };
77 Q_ENUM(Button)
78 Q_DECLARE_FLAGS(Buttons, Button)
79 Q_FLAG(Buttons)
80
81 /*!
82 *
83 */
84 explicit KAbstractConfigModule(QObject *parent, const KPluginMetaData &metaData);
85
86 ~KAbstractConfigModule() override;
87
88 /*!
89 * \brief Set if the module's save() method requires authorization to be executed.
90 *
91 * It will still have to execute the action itself using the KAuth library, so
92 * this method is not technically needed to perform the action, but
93 * using this method will ensure that hosting
94 * applications like System Settings or kcmshell behave correctly.
95 *
96 * \a action The action that will be used by this ConfigModule.
97 */
98 void setAuthActionName(const QString &action);
99
100 /*!
101 * \brief Returns the action previously set with setAuthActionName() and that is authorized to execute the save() method.
102 *
103 * By default this will be a empty string.
104 */
105 QString authActionName() const;
106
107 /*!
108 * \brief Emitted when the auth action name has changed.
109 */
110 Q_SIGNAL void authActionNameChanged();
111
112 /*!
113 * \brief Set this property to \c true when the user changes something in the module,
114 * signaling that it \a needs a save (such as user pressing Ok or Apply).
115 */
116 void setNeedsSave(bool needs);
117
118 /*!
119 * \brief Returns \c true when the module has something changed and needs save.
120 */
121 bool needsSave() const;
122
123 /*!
124 * \brief Emitted when the state of the modules contents has changed.
125 *
126 * This signal is emitted whenever the state of the configuration
127 * shown in the module changes. It allows the module container to
128 * keep track of unsaved changes.
129 */
130 Q_SIGNAL void needsSaveChanged();
131
132 /*!
133 * \brief Set this property to \c true when the user sets the state of the module
134 * to the \a defaults settings (e.g. clicking Defaults would do nothing).
135 */
136 void setRepresentsDefaults(bool defaults);
137
138 /*!
139 * \brief Returns \c true when the module state represents the default settings.
140 */
141 bool representsDefaults() const;
142
143 /*!
144 * \brief Emitted when the state of the modules contents has changed
145 * in a way that it might represents the defaults settings, or
146 * stopped representing them.
147 */
148 Q_SIGNAL void representsDefaultsChanged();
149
150 /*!
151 * \brief Sets the \a btn to display.
152 * \sa buttons
153 */
154 void setButtons(const Buttons btn);
155
156 /*!
157 * \brief Indicate which buttons will be used.
158 *
159 * The return value is a value or'ed together from
160 * the Button enumeration type.
161 *
162 * \sa setButtons
163 */
164 Buttons buttons() const;
165
166 /*!
167 * \brief Emitted when the buttons to display have changed.
168 */
169 Q_SIGNAL void buttonsChanged();
170
171 /*!
172 * \brief Returns \c true if the authActionName is not empty.
173 * \sa setAuthActionName
174 */
175 bool needsAuthorization() const;
176
177 /*!
178 * \brief Returns the name of the config module.
179 */
180 QString name() const;
181
182 /*!
183 * \brief Returns the description of the config module.
184 */
185 QString description() const;
186
187 /*!
188 * \brief Changes the defaultness indicator visibility.
189 *
190 * \a visible Whether the indicator should be visible.
191 */
192 void setDefaultsIndicatorsVisible(bool visible);
193
194 /*!
195 * \brief Returns the defaultness indicator visibility.
196 */
197 bool defaultsIndicatorsVisible() const;
198
199 /*!
200 * \brief Emitted when the KCM needs to display indicators for field with non default value.
201 */
202 Q_SIGNAL void defaultsIndicatorsVisibleChanged();
203
204 /*!
205 * \brief Indicate whether a config module supports instant apply.
206 *
207 * \a supportes The config module supports instant apply. If false,
208 * the settings application is exptected show Apply/OK buttons.
209 *
210 * The default is \c true.
211 *
212 * \since 6.16
213 */
214 void setSupportsInstantApply(bool supported);
215
216 /*!
217 * \brief Returns if the config module supports instant apply.
218 *
219 * Config modules that do not support instant apply only save their
220 * settings once Apply/OK are clicked by the user. The settings
221 * application is expected to show these buttons.
222 *
223 * The default is \c true.
224 *
225 * \since 6.16
226 */
227 bool supportsInstantApply() const;
228
229 /*!
230 * \brief Emitted when the KCM's supportsInstantApply property changes.
231 *
232 * \since 6.16
233 */
234 Q_SIGNAL void supportsInstantApplyChanged();
235
236
237 /*!
238 * \brief Returns the metaData that was used when instantiating the plugin.
239 */
240 KPluginMetaData metaData() const;
241
242 /*!
243 * \brief Emitted by a single-instance application (such as
244 * System Settings) to request activation and update \a args to a module
245 * that is already running.
246 *
247 * The module should connect to this signal when it needs to handle
248 * the activation request and specially the new arguments.
249 *
250 * \a args A list of arguments that get passed to the module.
251 */
252 Q_SIGNAL void activationRequested(const QVariantList &args);
253
254 /*!
255 * \brief Loads the configuration data into the module.
256 *
257 * The load method sets the user interface elements of the
258 * module to reflect the current settings stored in the
259 * configuration files.
260 *
261 * This method is invoked whenever the module should read its configuration
262 * (most of the times from a config file) and update the user interface.
263 * This happens when the user clicks the "Reset" button in the control
264 * center, to undo all of his changes and restore the currently valid
265 * settings. It is also called right after construction.
266 */
267 virtual void load();
268
269 /*!
270 * \brief The save method stores the config information as shown
271 * in the user interface in the config files.
272 *
273 * This method is called when the user clicks "Apply" or "Ok".
274 */
275 virtual void save();
276
277 /*!
278 * \brief Sets the configuration to default values.
279 *
280 * This method is called when the user clicks the "Default"
281 * button.
282 */
283 virtual void defaults();
284
285private:
286 const std::unique_ptr<KAbstractConfigModulePrivate> d;
287};
288
289Q_DECLARE_OPERATORS_FOR_FLAGS(KAbstractConfigModule::Buttons)
290
291#endif // KABSTRACTCONFIGMODULE_H
292

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