1/*
2 SPDX-FileCopyrightText: 1999 Matthias Hoelzer-Kluepfel <hoelzer@kde.org>
3 SPDX-FileCopyrightText: 2023 Alexander Lohnau <alexander.lohnau@gmx.de>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef KCMODULE_H
9#define KCMODULE_H
10
11#include "kcmutils_export.h"
12#include <KAbstractConfigModule>
13#include <KPluginMetaData>
14
15#include <QVariant>
16#include <QWidget>
17#include <memory>
18
19class KConfigDialogManager;
20class KCoreConfigSkeleton;
21class KConfigSkeleton;
22class KCModulePrivate;
23
24/**
25 * @class KCModule kcmodule.h KCModule
26 *
27 * The base class for QWidgets configuration modules.
28 * Configuration modules are loaded as plugins.
29 *
30 * The module in principle is a simple widget displaying the
31 * item to be changed. The module has a very small interface.
32 *
33 * To write a config module, you have to create a library
34 * that contains a factory class like the following:
35 *
36 * \code
37 * #include <KPluginFactory>
38 *
39 * K_PLUGIN_CLASS_WITH_JSON(MyKCModule, "mykcmodule.json")
40 * \endcode
41 *
42 * The constructor of the KCModule then looks like this:
43 * \code
44 * YourKCModule::YourKCModule(QWidget *parent, const KPluginMetaData &data)
45 * : KCModule(parent, data)
46 * {
47 * // KCModule does not directly extend QWidget due to ambiguity with KAbstractConfigModule
48 * // Because of this, you need to call widget() to get the parent widget
49 * auto label = new QLabel(widget());
50 * label->setText(QStringLiteral("Demo Text"));
51 * }
52 * \endcode
53 *
54 * This KCM can be loaded in a KCMultiDialog of kcmshell6
55 *
56 * @since 6.0
57 */
58class KCMUTILS_EXPORT KCModule : public KAbstractConfigModule
59{
60 Q_OBJECT
61
62public:
63 /**
64 * Base class for all QWidgets configuration modules.
65 *
66 * @note do not emit changed signals here, since they are not yet connected
67 * to any slot.
68 */
69 explicit KCModule(QWidget *parent, const KPluginMetaData &data);
70
71 /**
72 * Destroys the module.
73 */
74 ~KCModule() override;
75
76 /**
77 * @return a list of @ref KConfigDialogManager's in use, if any.
78 */
79 QList<KConfigDialogManager *> configs() const;
80
81 void load() override;
82 void save() override;
83 void defaults() override;
84
85 /**
86 * Utility function that marks the KCM as changed
87 */
88 void markAsChanged()
89 {
90 setNeedsSave(true);
91 }
92
93 /**
94 * Get the associated widget that can be embedded
95 * The returned widget should be used as a parent for widgets you create
96 *
97 * @note Overwriting this function should not be necessary for consumers!
98 */
99 virtual QWidget *widget();
100
101protected:
102 /**
103 * Adds a KCoreConfigskeleton @p config to watch the widget @p widget
104 *
105 * This function is useful if you need to handle multiple configuration files.
106 *
107 * @return a pointer to the KCoreConfigDialogManager in use
108 * @param config the KCoreConfigSkeleton to use
109 * @param widget the widget to watch
110 */
111 KConfigDialogManager *addConfig(KCoreConfigSkeleton *config, QWidget *widget);
112
113protected Q_SLOTS:
114 /**
115 * A managed widget was changed, the widget settings and the current
116 * settings are compared and a corresponding needsSaveChanged() signal is emitted
117 */
118 void widgetChanged();
119
120protected:
121 /**
122 * Returns the changed state of automatically managed widgets in this dialog
123 */
124 bool managedWidgetChangeState() const;
125
126 /**
127 * Returns the defaulted state of automatically managed widgets in this dialog
128 */
129 bool managedWidgetDefaultState() const;
130
131 /**
132 * Call this method when your manually managed widgets change state between
133 * changed and not changed
134 */
135 void unmanagedWidgetChangeState(bool);
136
137 /**
138 * Call this method when your manually managed widgets change state between
139 * defaulted and not defaulted
140 */
141 void unmanagedWidgetDefaultState(bool);
142
143 /**
144 * Utility overload to avoid having to take both parent and parentWidget
145 * KCModuleLoader::loadModule enforces the parent to be a QWidget anyway
146 */
147 explicit KCModule(QObject *parent, const KPluginMetaData &data)
148 : KCModule(qobject_cast<QWidget *>(parent), data)
149 {
150 }
151
152 /**
153 * Utility constructor for creating a KCModule that is embedded, for example in a KPluginWidget
154 * This constructor should not be used for KCMs that are part launched in systemsettings!
155 *
156 * @note do not emit changed signals here, since they are not yet connected
157 * to any slot.
158 */
159 explicit KCModule(QObject *parent)
160 : KCModule(qobject_cast<QWidget *>(parent), KPluginMetaData{})
161 {
162 }
163
164private:
165 std::unique_ptr<KCModulePrivate> const d;
166};
167
168#endif // KCMODULE_H
169

source code of kcmutils/src/kcmodule.h