KCMUtils

kcmodule.h
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
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 */
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
Base class for QML and QWidgets config modules.
virtual void defaults()
Sets the configuration to default values.
void setNeedsSave(bool needs)
Set this property to true when the user changes something in the module, signaling that a save (such ...
virtual void save()
The save method stores the config information as shown in the user interface in the config files.
virtual void load()
Load the configuration data into the module.
The base class for QWidgets configuration modules.
Definition kcmodule.h:59
KCModule(QObject *parent, const KPluginMetaData &data)
Utility overload to avoid having to take both parent and parentWidget KCModuleLoader::loadModule enfo...
Definition kcmodule.h:147
void markAsChanged()
Utility function that marks the KCM as changed.
Definition kcmodule.h:88
KCModule(QObject *parent)
Utility constructor for creating a KCModule that is embedded, for example in a KPluginWidget This con...
Definition kcmodule.h:159
Q_SLOTSQ_SLOTS
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri May 24 2024 11:50:24 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.