1/*
2 * Copyright 2007 Aaron Seigo <aseigo@kde.org>
3 *
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU Library General Public License as
6 * published by the Free Software Foundation; either version 2, or
7 * (at your option) any later version.
8 *
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details
13 *
14 * You should have received a copy of the GNU Library General Public
15 * License along with this program; if not, write to the
16 * Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 */
19
20#ifndef PLASMA_CONFIGLOADER_H
21#define PLASMA_CONFIGLOADER_H
22
23#include <kconfiggroup.h>
24#include <kconfigskeleton.h>
25#include <ksharedconfig.h>
26
27#include <plasma/plasma_export.h>
28
29/**
30 * @class ConfigLoader plasma/configloader.h <Plasma/ConfigLoader>
31 *
32 * @short A KConfigSkeleton that populates itself based on KConfigXT XML
33 *
34 * This class allows one to ship an XML file and reconstitute it into a
35 * KConfigSkeleton object at runtime. Common usage might look like this:
36 *
37 * \code
38 * QFile file(xmlFilePath);
39 * Plasma::ConfigLoader appletConfig(configFilePath, &file);
40 * \endcode
41 *
42 * Alternatively, any QIODevice may be used in place of QFile in the
43 * example above.
44 *
45 * Currently the following data types are supported:
46 *
47 * @li bools
48 * @li colors
49 * @li datetimes
50 * @li enumerations
51 * @li fonts
52 * @li ints
53 * @li passwords
54 * @li paths
55 * @li strings
56 * @li stringlists
57 * @li uints
58 * @li urls
59 * @li doubles
60 * @li int lists
61 * @li longlongs
62 * @li path lists
63 * @li points
64 * @li rects
65 * @li sizes
66 * @li ulonglongs
67 * @li url lists
68 **/
69
70namespace Plasma
71{
72
73class ConfigLoaderPrivate;
74
75class PLASMA_EXPORT ConfigLoader : public KConfigSkeleton
76{
77public:
78 /**
79 * Creates a KConfigSkeleton populated using the definition found in
80 * the XML data passed in.
81 *
82 * @param configFile path to the configuration file to use
83 * @param xml the xml data; must be valid KConfigXT data
84 * @param parent optional QObject parent
85 **/
86 ConfigLoader(const QString &configFile, QIODevice *xml, QObject *parent = 0);
87
88 /**
89 * Creates a KConfigSkeleton populated using the definition found in
90 * the XML data passed in.
91 *
92 * @param config the configuration object to use
93 * @param xml the xml data; must be valid KConfigXT data
94 * @param parent optional QObject parent
95 **/
96 ConfigLoader(KSharedConfigPtr config, QIODevice *xml, QObject *parent = 0);
97
98 /**
99 * Creates a KConfigSkeleton populated using the definition found in
100 * the XML data passed in.
101 *
102 * @param config the group to use as the root for configuration items
103 * @param xml the xml data; must be valid KConfigXT data
104 * @param parent optional QObject parent
105 **/
106 ConfigLoader(const KConfigGroup *config, QIODevice *xml, QObject *parent = 0);
107 ~ConfigLoader();
108
109 /**
110 * Finds the item for the given group and key.
111 *
112 * @param group the group in the config file to look in
113 * @param key the configuration key to find
114 * @return the associated KConfigSkeletonItem, or 0 if none
115 */
116 KConfigSkeletonItem *findItem(const QString &group, const QString &key);
117
118 /**
119 * Finds an item by its name
120 */
121 KConfigSkeletonItem *findItemByName(const QString &name);
122
123 /**
124 * Returns the property (variantized value) of the named item
125 */
126 QVariant property(const QString &name);
127
128 /**
129 * Check to see if a group exists
130 *
131 * @param group the name of the group to check for
132 * @return true if the group exists, or false if it does not
133 */
134 bool hasGroup(const QString &group) const;
135
136 /**
137 * @return the list of groups defined by the XML
138 */
139 QStringList groupList() const;
140
141protected:
142 /**
143 * Hack used to force writing when no default exists in config file.
144 */
145 void usrWriteConfig();
146
147private:
148 friend class Service;
149 ConfigLoaderPrivate * const d;
150};
151
152} // Plasma namespace
153
154#endif //multiple inclusion guard
155