KConfig

kconfigloader.h
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 
18 class 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  **/
91 class KCONFIGGUI_EXPORT KConfigLoader : public KConfigSkeleton
92 {
93 public:
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 
158 protected:
159  bool usrSave() override;
160 
161 private:
162  ConfigLoaderPrivate *const d;
163 };
164 
165 #endif // multiple inclusion guard
Class for handling preferences settings for an application.
virtual bool usrSave()
Perform the actual writing of the configuration file.
A KConfigSkeleton that populates itself based on KConfigXT XML.
Definition: kconfigloader.h:91
KConfigSkeletonItem * findItem(const QString &name) const
Lookup item by name.
Class for storing a preferences setting.
QVariant property(const char *name) const const
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Thu Feb 15 2024 04:07:59 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.