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
18 * \inmodule KCMUtilsQuick
19 * \brief 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 ~KQuickManagedConfigModule() override;
46
47public Q_SLOTS:
48 /*!
49 * \brief Loads the configuration data into the module.
50 *
51 * This method is invoked whenever the module should read its configuration
52 * (most of the times from a config file) and update the user interface.
53 * This happens when the user clicks the "Reset" button in the control
54 * center, to undo all of his changes and restore the currently valid
55 * settings. It is also called right after construction.
56 *
57 * By default this will load the settings from the child setting objects
58 * of this module.
59 */
60 void load() override;
61
62 /*!
63 * \brief Saves the configuration data.
64 *
65 * The save method stores the config information as shown
66 * in the user interface in the config files.
67 * It is called when the user clicks "Apply" or "Ok".
68 *
69 * By default this will save the child setting objects
70 * of this module.
71 */
72 void save() override;
73
74 /*!
75 * \brief Sets the configuration to sensible default values.
76 *
77 * This method is called when the user clicks the "Default"
78 * button. It should set the display to useful values.
79 *
80 * By default this will reset to defaults the child setting objects
81 * of this module.
82 */
83 void defaults() override;
84
85protected Q_SLOTS:
86 /*!
87 * \brief Forces the module to reevaluate the saveNeeded and
88 * representsDefault state.
89 *
90 * This is required for some modules which might have
91 * some settings managed outside of KConfigXT objects.
92 */
93 void settingsChanged();
94
95 /*!
96 * \brief Allows to register manually settings class generated from a kcfg file.
97 * Used by derived class when automatic discovery is not possible.
98 * After \a skeleton is registered it will automatically call settingsChanged().
99 */
100 void registerSettings(KCoreConfigSkeleton *skeleton);
101
102protected:
103 /*!
104 * \brief Base class for all KControlModules.
105 *
106 * Creates a new KQuickManagedConfigModule with the given \a metaData as a child of \a parent.
107 * Use KQuickConfigModuleLoader to instantiate this class.
108 *
109 * \note Do not emit changed signals here, since they are not yet connected to any slot.
110 */
111 explicit KQuickManagedConfigModule(QObject *parent, const KPluginMetaData &metaData);
112
113private:
114 /*!
115 * \brief Allows to indicate if the module requires saving.
116 *
117 * By default this returns false, it needs to be overridden only
118 * if the module has state outside of the settings declared in
119 * the KConfigXT classes it uses.
120 */
121 virtual bool isSaveNeeded() const;
122
123 /*!
124 * \brief Allows to indicate if the module state is representing its defaults.
125 *
126 * By default this returns true, it needs to be overridden only
127 * if the module has state outside of the settings declared in
128 * the KConfigXT classes it uses.
129 */
130 virtual bool isDefaults() const;
131
132 const std::unique_ptr<KQuickManagedConfigModulePrivate> d;
133 friend class KQuickManagedConfigModulePrivate;
134};
135
136#endif // MANAGEDCONFIGMODULE_H
137

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