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 * Base class for QML and QWidgets config modules.
20 *
21 * @author Alexander Lohnau
22 * @since 6.0
23 */
24class KCMUTILSCORE_EXPORT KAbstractConfigModule : public QObject
25{
26 Q_OBJECT
27
28 Q_PROPERTY(KAbstractConfigModule::Buttons buttons READ buttons WRITE setButtons NOTIFY buttonsChanged)
29 Q_PROPERTY(bool defaultsIndicatorsVisible READ defaultsIndicatorsVisible WRITE setDefaultsIndicatorsVisible NOTIFY defaultsIndicatorsVisibleChanged)
30 Q_PROPERTY(bool needsAuthorization READ needsAuthorization NOTIFY authActionNameChanged)
31 Q_PROPERTY(bool representsDefaults READ representsDefaults WRITE setRepresentsDefaults NOTIFY representsDefaultsChanged)
32 Q_PROPERTY(bool needsSave READ needsSave WRITE setNeedsSave NOTIFY needsSaveChanged)
33 Q_PROPERTY(QString name READ name CONSTANT)
34 Q_PROPERTY(QString description READ description CONSTANT)
35public:
36 /**
37 * An enumeration type for the buttons used by this module.
38 * You should only use Help, Default and Apply. The rest is obsolete.
39 * NoAdditionalButton can be used when we do not want have other button that Ok Cancel
40 *
41 * @see ConfigModule::buttons @see ConfigModule::setButtons
42 */
43 enum Button {
44 NoAdditionalButton = 0,
45 Help = 1,
46 Default = 2,
47 Apply = 4,
48 Export = 8,
49 };
50 Q_ENUM(Button)
51 Q_DECLARE_FLAGS(Buttons, Button)
52 Q_FLAG(Buttons)
53
54 explicit KAbstractConfigModule(QObject *parent, const KPluginMetaData &metaData);
55
56 ~KAbstractConfigModule() override;
57
58 /**
59 * @brief Set if the module's save() method requires authorization to be executed
60 *
61 * It will still have to execute the action itself using the KAuth library, so
62 * this method is not technically needed to perform the action, but
63 * using this method will ensure that hosting
64 * applications like System Settings or kcmshell behave correctly.
65 *
66 * @param action the action that will be used by this ConfigModule
67 */
68 void setAuthActionName(const QString &action);
69
70 /**
71 * Returns the action previously set with setAuthActionName(). By default this will be a empty string.
72 *
73 * @return The action that has to be authorized to execute the save() method.
74 */
75 QString authActionName() const;
76
77 /**
78 * The auth action name has changed
79 */
80 Q_SIGNAL void authActionNameChanged();
81
82 /**
83 * Set this property to true when the user changes something in the module,
84 * signaling that a save (such as user pressing Ok or Apply) is needed.
85 */
86 void setNeedsSave(bool needs);
87
88 /**
89 * True when the module has something changed and needs save.
90 */
91 bool needsSave() const;
92
93 /**
94 * Indicate that the state of the modules contents has changed.
95 *
96 * This signal is emitted whenever the state of the configuration
97 * shown in the module changes. It allows the module container to
98 * keep track of unsaved changes.
99 */
100 Q_SIGNAL void needsSaveChanged();
101
102 /**
103 * Set this property to true when the user sets the state of the module
104 * to the default settings (e.g. clicking Defaults would do nothing).
105 */
106 void setRepresentsDefaults(bool defaults);
107
108 /**
109 * True when the module state represents the default settings.
110 */
111 bool representsDefaults() const;
112
113 /**
114 * Indicate that the state of the modules contents has changed
115 * in a way that it might represents the defaults settings, or
116 * stopped representing them.
117 */
118 Q_SIGNAL void representsDefaultsChanged();
119
120 /**
121 * Sets the buttons to display.
122 *
123 * Help: shows a "Help" button.
124 *
125 * Default: shows a "Use Defaults" button.
126 *
127 * Apply: shows an "Ok", "Apply" and "Cancel" button.
128 *
129 * If Apply is not specified, kcmshell will show a "Close" button.
130 *
131 * @see ConfigModule::buttons
132 */
133 void setButtons(const Buttons btn);
134
135 /**
136 * Indicate which buttons will be used.
137 *
138 * The return value is a value or'ed together from
139 * the Button enumeration type.
140 *
141 * @see ConfigModule::setButtons
142 */
143 Buttons buttons() const;
144
145 /**
146 * Buttons to display changed.
147 */
148 Q_SIGNAL void buttonsChanged();
149
150 /**
151 * @return true, if the authActionName is not empty
152 * @sa setAuthActionName
153 */
154 bool needsAuthorization() const;
155
156 /**
157 * @returns the name of the config module
158 */
159 QString name() const;
160
161 /**
162 * @returns the description of the config module
163 */
164 QString description() const;
165
166 /**
167 * Change defaultness indicator visibility
168 * @param visible
169 */
170 void setDefaultsIndicatorsVisible(bool visible);
171
172 /**
173 * @returns defaultness indicator visibility
174 */
175 bool defaultsIndicatorsVisible() const;
176
177 /**
178 * Emitted when kcm need to display indicators for field with non default value
179 */
180 Q_SIGNAL void defaultsIndicatorsVisibleChanged();
181
182 /**
183 * Returns the metaData that was used when instantiating the plugin
184 */
185 KPluginMetaData metaData() const;
186
187 /**
188 * This signal will be emited by a single-instance application (such as
189 * System Settings) to request activation and update arguments to a module
190 * that is already running
191 *
192 * The module should connect to this signal when it needs to handle
193 * the activation request and specially the new arguments
194 *
195 * @param args A list of arguments that get passed to the module
196 */
197 Q_SIGNAL void activationRequested(const QVariantList &args);
198
199 /**
200 * Load the configuration data into the module.
201 *
202 * The load method sets the user interface elements of the
203 * module to reflect the current settings stored in the
204 * configuration files.
205 *
206 * This method is invoked whenever the module should read its configuration
207 * (most of the times from a config file) and update the user interface.
208 * This happens when the user clicks the "Reset" button in the control
209 * center, to undo all of his changes and restore the currently valid
210 * settings. It is also called right after construction.
211 */
212 virtual void load();
213
214 /**
215 * The save method stores the config information as shown
216 * in the user interface in the config files.
217 *
218 * This method is called when the user clicks "Apply" or "Ok".
219 *
220 */
221 virtual void save();
222
223 /**
224 * Sets the configuration to default values.
225 *
226 * This method is called when the user clicks the "Default"
227 * button.
228 */
229 virtual void defaults();
230
231private:
232 const std::unique_ptr<KAbstractConfigModulePrivate> d;
233};
234
235Q_DECLARE_OPERATORS_FOR_FLAGS(KAbstractConfigModule::Buttons)
236
237#endif // KABSTRACTCONFIGMODULE_H
238

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