File indexing completed on 2024-05-12 03:54:28
0001 /* 0002 SPDX-FileCopyrightText: 2007 Aaron Seigo <aseigo@kde.org> 0003 0004 SPDX-License-Identifier: LGPL-2.0-or-later 0005 */ 0006 0007 #ifndef KCONFIGLOADER_H 0008 #define KCONFIGLOADER_H 0009 0010 #include <QIODevice> 0011 0012 #include <kconfiggroup.h> 0013 #include <kconfigskeleton.h> 0014 #include <ksharedconfig.h> 0015 0016 #include <kconfiggui_export.h> 0017 0018 class ConfigLoaderPrivate; 0019 0020 /** 0021 * @class KConfigLoader kconfigloader.h <KConfigLoader> 0022 * 0023 * @short A KConfigSkeleton that populates itself based on KConfigXT XML 0024 * 0025 * This class allows one to ship an XML file and reconstitute it into a 0026 * KConfigSkeleton object at runtime. Common usage might look like this: 0027 * 0028 * \code 0029 * QFile file(xmlFilePath); 0030 * KConfigLoader appletConfig(configFilePath, &file); 0031 * \endcode 0032 * 0033 * Alternatively, any QIODevice may be used in place of QFile in the 0034 * example above. 0035 * 0036 * KConfigLoader is useful if it is not possible to use compiled code 0037 * and by that the kconfig compiler cannot be used. Common examples are 0038 * scripted plugins which want to provide a configuration interface. 0039 * With the help of KConfigLoader a dynamically loaded ui file can be 0040 * populated with the stored values and also stored back to the config 0041 * file. 0042 * 0043 * An example for populating a QDialog with a dynamically populated UI 0044 * with the help of a KConfigDialogManager: 0045 * \code 0046 * QDialog *dialog = new QDialog(); 0047 * QFile xmlFile("path/to/kconfigxt.xml"); 0048 * KConfigGroup cg = KSharedConfig::openConfig()->group(QString()); 0049 * KConfigLoader *configLoader = new KConfigLoader(cg, &xmlFile, this); 0050 * 0051 * // load the ui file 0052 * QUiLoader *loader = new QUiLoader(this); 0053 * QFile uiFile("path/to/userinterface.ui"); 0054 * uiFile.open(QFile::ReadOnly); 0055 * QWidget *customConfigForm = loader->load(&uiFile, dialog); 0056 * uiFile.close(); 0057 * 0058 * KConfigDialogManager *manager = new KConfigDialogManager(customConfigForm, configLoader); 0059 * if (dialog->exec() == QDialog::Accepted) { 0060 * manager->updateSettings(); 0061 * } 0062 * \endcode 0063 * 0064 * Currently the following data types are supported: 0065 * 0066 * @li bools 0067 * @li colors 0068 * @li datetimes 0069 * @li enumerations 0070 * @li fonts 0071 * @li ints 0072 * @li passwords 0073 * @li paths 0074 * @li strings 0075 * @li stringlists 0076 * @li uints 0077 * @li urls 0078 * @li doubles 0079 * @li int lists 0080 * @li longlongs 0081 * @li path lists 0082 * @li points 0083 * @li pointfs 0084 * @li rects 0085 * @li rectfs 0086 * @li sizes 0087 * @li sizefs 0088 * @li ulonglongs 0089 * @li url lists 0090 **/ 0091 class KCONFIGGUI_EXPORT KConfigLoader : public KConfigSkeleton 0092 { 0093 public: 0094 /** 0095 * Creates a KConfigSkeleton populated using the definition found in 0096 * the XML data passed in. 0097 * 0098 * @param configFile path to the configuration file to use 0099 * @param xml the xml data; must be valid KConfigXT data 0100 * @param parent optional QObject parent 0101 **/ 0102 KConfigLoader(const QString &configFile, QIODevice *xml, QObject *parent = nullptr); 0103 0104 /** 0105 * Creates a KConfigSkeleton populated using the definition found in 0106 * the XML data passed in. 0107 * 0108 * @param config the configuration object to use 0109 * @param xml the xml data; must be valid KConfigXT data 0110 * @param parent optional QObject parent 0111 **/ 0112 KConfigLoader(KSharedConfigPtr config, QIODevice *xml, QObject *parent = nullptr); 0113 0114 /** 0115 * Creates a KConfigSkeleton populated using the definition found in 0116 * the XML data passed in. 0117 * 0118 * @param config the group to use as the root for configuration items 0119 * @param xml the xml data; must be valid KConfigXT data 0120 * @param parent optional QObject parent 0121 **/ 0122 KConfigLoader(const KConfigGroup &config, QIODevice *xml, QObject *parent = nullptr); 0123 0124 ~KConfigLoader() override; 0125 0126 /** 0127 * Finds the item for the given group and key. 0128 * 0129 * @param group the group in the config file to look in 0130 * @param key the configuration key to find 0131 * @return the associated KConfigSkeletonItem, or @c nullptr if none 0132 */ 0133 KConfigSkeletonItem *findItem(const QString &group, const QString &key) const; 0134 0135 /** 0136 * Finds an item by its name 0137 */ 0138 KConfigSkeletonItem *findItemByName(const QString &name) const; 0139 0140 /** 0141 * Returns the property (variantized value) of the named item 0142 */ 0143 QVariant property(const QString &name) const; 0144 0145 /** 0146 * Check to see if a group exists 0147 * 0148 * @param group the name of the group to check for 0149 * @return true if the group exists, or false if it does not 0150 */ 0151 bool hasGroup(const QString &group) const; 0152 0153 /** 0154 * @return the list of groups defined by the XML 0155 */ 0156 QStringList groupList() const; 0157 0158 protected: 0159 bool usrSave() override; 0160 0161 private: 0162 ConfigLoaderPrivate *const d; 0163 }; 0164 0165 #endif // multiple inclusion guard