1/*
2 SPDX-FileCopyrightText: 2019 Kevin Ottens <kevin.ottens@enioka.com>
3 SPDX-License-Identifier: LGPL-2.0-or-later
4*/
5
6#ifndef MANAGEDCONFIGMODULE_H
7#define MANAGEDCONFIGMODULE_H
8
9#include "kquickconfigmodule.h"
10#include <memory>
11
12class KCoreConfigSkeleton;
13
14class KQuickManagedConfigModulePrivate;
15
16/**
17 * @class KQuickManagedConfigModule managedconfigmodule.h KQuickAddons/ManagedConfigModule
18 *
19 * The base class for configuration modules using KConfigXT settings.
20 *
21 * We are assuming here that SettingsObject is a class generated from a kcfg file
22 * and that it will be somehow exposed as a constant property to be used from the QML side.
23 * It will be automatically discovered by ManagedConfigModule which will update
24 * the saveNeeded and defaults inherited properties by itself. Thus by inheriting from
25 * this class you shall not try to manage those properties yourselves.
26 * By passing in "this" as a parent, we prevent memory leaks and allow KQuickManagedConfigModule to
27 * automatically find the created settings object.
28 *
29 * The constructor of the ConfigModule then looks like this:
30 * \code
31 * YourConfigModule::YourConfigModule(QObject *parent, const KPluginMetaData &metaData)
32 * : ManagedConfigModule(parent, metaData)
33 * , m_settingsObject(new SettingsObject(this))
34 * {
35 * }
36 * \endcode
37 *
38 * @since 6.0
39 */
40class KCMUTILSQUICK_EXPORT KQuickManagedConfigModule : public KQuickConfigModule
41{
42 Q_OBJECT
43
44public:
45 /**
46 * Destroys the module.
47 */
48 ~KQuickManagedConfigModule() override;
49
50public Q_SLOTS:
51 /**
52 * Load the configuration data into the module.
53 *
54 * This method is invoked whenever the module should read its configuration
55 * (most of the times from a config file) and update the user interface.
56 * This happens when the user clicks the "Reset" button in the control
57 * center, to undo all of his changes and restore the currently valid
58 * settings. It is also called right after construction.
59 *
60 * By default this will load the settings from the child setting objects
61 * of this module.
62 */
63 void load() override;
64
65 /**
66 * Save the configuration data.
67 *
68 * The save method stores the config information as shown
69 * in the user interface in the config files.
70 * It is called when the user clicks "Apply" or "Ok".
71 *
72 * By default this will save the child setting objects
73 * of this module.
74 */
75 void save() override;
76
77 /**
78 * Sets the configuration to sensible default values.
79 *
80 * This method is called when the user clicks the "Default"
81 * button. It should set the display to useful values.
82 *
83 * By default this will reset to defaults the child setting objects
84 * of this module.
85 */
86 void defaults() override;
87
88protected Q_SLOTS:
89 /**
90 * Forces the module to reevaluate the saveNeeded and
91 * representsDefault state.
92 *
93 * This is required for some modules which might have
94 * some settings managed outside of KConfigXT objects.
95 */
96 void settingsChanged();
97
98 /**
99 * Allow to register manually settings class generated from a kcfg file.
100 * Used by derived class when automatic discovery is not possible.
101 * After skeleton is registered it will automatically call settingsChanged().
102 */
103 void registerSettings(KCoreConfigSkeleton *skeleton);
104
105protected:
106 /**
107 * Base class for all KControlModules.
108 * Use KQuickConfigModuleLoader to instantiate this class
109 *
110 * @note do not emit changed signals here, since they are not yet connected to any slot.
111 */
112 explicit KQuickManagedConfigModule(QObject *parent, const KPluginMetaData &metaData);
113
114private:
115 /**
116 * Allows to indicate if the module requires saving.
117 *
118 * By default this returns false, it needs to be overridden only
119 * if the module has state outside of the settings declared in
120 * the KConfigXT classes it uses.
121 */
122 virtual bool isSaveNeeded() const;
123
124 /**
125 * Allows to indicate if the module state is representing its defaults.
126 *
127 * By default this returns true, it needs to be overridden only
128 * if the module has state outside of the settings declared in
129 * the KConfigXT classes it uses.
130 */
131 virtual bool isDefaults() const;
132
133 const std::unique_ptr<KQuickManagedConfigModulePrivate> d;
134 friend class KQuickManagedConfigModulePrivate;
135};
136
137#endif // MANAGEDCONFIGMODULE_H
138

source code of kcmutils/src/qml/kquickmanagedconfigmodule.h