1/*
2 SPDX-FileCopyrightText: 2007 Aaron Seigo <aseigo@kde.org>
3
4 SPDX-License-Identifier: LGPL-2.0-or-later
5*/
6
7#ifndef KCONFIGLOADER_H
8#define KCONFIGLOADER_H
9
10#include <QIODevice>
11
12#include <kconfiggroup.h>
13#include <kconfigskeleton.h>
14#include <ksharedconfig.h>
15
16#include <kconfiggui_export.h>
17
18class ConfigLoaderPrivate;
19
20/*!
21 * \class KConfigLoader
22 * \inmodule KConfigGui
23 *
24 * \brief A KConfigSkeleton that populates itself based on KConfigXT XML.
25 *
26 * This class allows one to ship an XML file and reconstitute it into a
27 * KConfigSkeleton object at runtime. Common usage might look like this:
28 *
29 * \code
30 * QFile file(xmlFilePath);
31 * KConfigLoader appletConfig(configFilePath, &file);
32 * \endcode
33 *
34 * Alternatively, any QIODevice may be used in place of QFile in the
35 * example above.
36 *
37 * KConfigLoader is useful if it is not possible to use compiled code
38 * and by that the kconfig compiler cannot be used. Common examples are
39 * scripted plugins which want to provide a configuration interface.
40 * With the help of KConfigLoader a dynamically loaded ui file can be
41 * populated with the stored values and also stored back to the config
42 * file.
43 *
44 * An example for populating a QDialog with a dynamically populated UI
45 * with the help of a KConfigDialogManager:
46 * \code
47 * QDialog *dialog = new QDialog();
48 * QFile xmlFile("path/to/kconfigxt.xml");
49 * KConfigGroup cg = KSharedConfig::openConfig()->group(QString());
50 * KConfigLoader *configLoader = new KConfigLoader(cg, &xmlFile, this);
51 *
52 * // load the ui file
53 * QUiLoader *loader = new QUiLoader(this);
54 * QFile uiFile("path/to/userinterface.ui");
55 * uiFile.open(QFile::ReadOnly);
56 * QWidget *customConfigForm = loader->load(&uiFile, dialog);
57 * uiFile.close();
58 *
59 * KConfigDialogManager *manager = new KConfigDialogManager(customConfigForm, configLoader);
60 * if (dialog->exec() == QDialog::Accepted) {
61 * manager->updateSettings();
62 * }
63 * \endcode
64 *
65 * Currently the following data types are supported:
66 * \list
67 * \li bools
68 * \li colors
69 * \li datetimes
70 * \li times
71 * \li enumerations
72 * \li fonts
73 * \li ints
74 * \li passwords
75 * \li paths
76 * \li strings
77 * \li stringlists
78 * \li uints
79 * \li urls
80 * \li doubles
81 * \li int lists
82 * \li longlongs
83 * \li path lists
84 * \li points
85 * \li pointfs
86 * \li rects
87 * \li rectfs
88 * \li sizes
89 * \li sizefs
90 * \li ulonglongs
91 * \li url lists
92 * \endlist
93 **/
94class KCONFIGGUI_EXPORT KConfigLoader : public KConfigSkeleton
95{
96public:
97 /*!
98 * Creates a KConfigSkeleton populated using the definition found in
99 * the XML data passed in.
100 *
101 * \a configFile path to the configuration file to use
102 *
103 * \a xml the xml data; must be valid KConfigXT data
104 *
105 * \a parent optional QObject parent
106 **/
107 KConfigLoader(const QString &configFile, QIODevice *xml, QObject *parent = nullptr);
108
109 /*!
110 * Creates a KConfigSkeleton populated using the definition found in
111 * the XML data passed in.
112 *
113 * \a config the configuration object to use
114 *
115 * \a xml the xml data; must be valid KConfigXT data
116 *
117 * \a parent optional QObject parent
118 **/
119 KConfigLoader(KSharedConfigPtr config, QIODevice *xml, QObject *parent = nullptr);
120
121 /*!
122 * Creates a KConfigSkeleton populated using the definition found in
123 * the XML data passed in.
124 *
125 * \a config the group to use as the root for configuration items
126 *
127 * \a xml the xml data; must be valid KConfigXT data
128 *
129 * \a parent optional QObject parent
130 **/
131 KConfigLoader(const KConfigGroup &config, QIODevice *xml, QObject *parent = nullptr);
132
133 ~KConfigLoader() override;
134
135 /*!
136 * Finds the item for the given group and key.
137 *
138 * \a group the group in the config file to look in
139 *
140 * \a key the configuration key to find
141 *
142 * Returns the associated KConfigSkeletonItem, or \c nullptr if none
143 */
144 KConfigSkeletonItem *findItem(const QString &group, const QString &key) const;
145
146 /*!
147 * Finds an item by its name
148 */
149 KConfigSkeletonItem *findItemByName(const QString &name) const;
150
151 /*!
152 * Returns the property (variantized value) of the named item
153 */
154 QVariant property(const QString &name) const;
155
156 /*!
157 * Check to see if a group exists
158 *
159 * \a group the name of the group to check for
160 *
161 * Returns \c true if the group exists, or false if it does not
162 */
163 bool hasGroup(const QString &group) const;
164
165 /*!
166 * Returns the list of groups defined by the XML
167 */
168 QStringList groupList() const;
169
170protected:
171 bool usrSave() override;
172
173private:
174 ConfigLoaderPrivate *const d;
175};
176
177#endif // multiple inclusion guard
178

source code of kconfig/src/gui/kconfigloader.h