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

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