KConfig

kconfigbase.h
1 /*
2  This file is part of the KDE libraries
3  SPDX-FileCopyrightText: 2006, 2007 Thomas Braxton <[email protected]>
4  SPDX-FileCopyrightText: 2001 Waldo Bastian <[email protected]>
5  SPDX-FileCopyrightText: 1999 Preston Brown <[email protected]>
6  SPDX-FileCopyrightText: 1997 Matthias Kalle Dalheimer <[email protected]>
7 
8  SPDX-License-Identifier: LGPL-2.0-or-later
9 */
10 
11 #ifndef KCONFIGBASE_H
12 #define KCONFIGBASE_H
13 
14 #include <kconfigcore_export.h>
15 
16 #include <QStringList>
17 #include <QtGlobal>
18 
19 class KConfigGroup;
20 class KConfigBasePrivate;
21 
22 /**
23  * \class KConfigBase kconfigbase.h <KConfigBase>
24  * \brief Interface to interact with configuration.
25  *
26  * KConfigBase allows a component of an application to persists its configuration
27  * without the component knowing if it is storing the configuration into a top
28  * level KConfig or a KConfigGroup inside a KConfig instance.
29  */
30 class KCONFIGCORE_EXPORT KConfigBase
31 {
32 public:
33  /**
34  * Flags to control write entry
35  * @see WriteConfigFlags
36  */
38  Persistent = 0x01,
39  /**<
40  * Save this entry when saving the config object.
41  */
42  Global = 0x02,
43  /**<
44  * Save the entry to the global %KDE config file instead of the
45  * application specific config file.
46  */
47  Localized = 0x04,
48  /**<
49  * Add the locale tag to the key when writing it.
50  */
51  Notify = 0x08 | Persistent,
52  /**<
53  * Notify remote KConfigWatchers of changes (requires DBus support)
54  * Implied persistent
55  * @since 5.51
56  */
57  Normal = Persistent,
58  /**<
59  * Save the entry to the application specific config file without
60  * a locale tag. This is the default.
61  */
62 
63  };
64  /**
65  * Stores a combination of #WriteConfigFlag values.
66  */
68 
69  /**
70  * Destructs the KConfigBase object.
71  */
72  virtual ~KConfigBase();
73 
74  /**
75  * Returns a list of groups that are known about.
76  *
77  * @return The list of groups.
78  **/
79  virtual QStringList groupList() const = 0;
80 
81  /**
82  * Returns true if the specified group is known about.
83  *
84  * @param group name of group to search for
85  * @return true if the group exists.
86  */
87  bool hasGroup(const QString &group) const;
88  /**
89  * Overload for hasGroup(const QString&) const
90  *
91  * @param group name of group to search for, encoded in UTF-8
92  */
93  bool hasGroup(const char *group) const;
94  /**
95  * Overload for hasGroup(const QString&) const
96  *
97  * @param group name of group to search for, encoded in UTF-8
98  */
99  bool hasGroup(const QByteArray &group) const;
100 
101  /**
102  * Returns an object for the named subgroup.
103  *
104  * @param group the group to open. Pass an empty string here to the KConfig
105  * object to obtain a handle on the root group.
106  * @return config group object for the given group name.
107  */
108  KConfigGroup group(const QString &group);
109  /**
110  * Overload for group(const QString&)
111  *
112  * @param group name of group, encoded in UTF-8
113  */
114  KConfigGroup group(const QByteArray &group);
115  /**
116  * Overload for group(const QString&)
117  *
118  * @param group name of group, encoded in UTF-8
119  */
120  KConfigGroup group(const char *group);
121 
122  /**
123  * Const overload for group(const QString&)
124  */
125  const KConfigGroup group(const QString &group) const;
126  /**
127  * Const overload for group(const QString&)
128  *
129  * @param group name of group, encoded in UTF-8
130  */
131  const KConfigGroup group(const QByteArray &group) const;
132  /**
133  * Const overload for group(const QString&)
134  *
135  * @param group name of group, encoded in UTF-8
136  */
137  const KConfigGroup group(const char *group) const;
138 
139  /**
140  * Delete @p group.
141  * This marks @p group as @em deleted in the config object. This effectively
142  * removes any cascaded values from config files earlier in the stack.
143  */
144  void deleteGroup(const QString &group, WriteConfigFlags flags = Normal);
145  /**
146  * Overload for deleteGroup(const QString&, WriteConfigFlags)
147  *
148  * @param group name of group to delete, encoded in UTF-8
149  */
150  void deleteGroup(const QByteArray &group, WriteConfigFlags flags = Normal);
151  /**
152  * Overload for deleteGroup(const QString&, WriteConfigFlags)
153  *
154  * @param group name of group to delete, encoded in UTF-8
155  */
156  void deleteGroup(const char *group, WriteConfigFlags flags = Normal);
157 
158  /**
159  * Syncs the configuration object that this group belongs to.
160  * Unrelated concurrent changes to the same file are merged and thus
161  * not overwritten. Note however, that this object is @em not automatically
162  * updated with those changes.
163  */
164  virtual bool sync() = 0;
165 
166  /**
167  * Reset the dirty flags of all entries in the entry map, so the
168  * values will not be written to disk on a later call to sync().
169  */
170  virtual void markAsClean() = 0;
171 
172  /**
173  * Possible return values for accessMode().
174  */
175  enum AccessMode {
176  NoAccess,
177  ReadOnly,
178  ReadWrite,
179  };
180 
181  /**
182  * Returns the access mode of the app-config object.
183  *
184  * Possible return values
185  * are NoAccess (the application-specific config file could not be
186  * opened neither read-write nor read-only), ReadOnly (the
187  * application-specific config file is opened read-only, but not
188  * read-write) and ReadWrite (the application-specific config
189  * file is opened read-write).
190  *
191  * @return the access mode of the app-config object
192  */
193  virtual AccessMode accessMode() const = 0;
194 
195  /**
196  * Checks whether this configuration object can be modified.
197  * @return whether changes may be made to this configuration object.
198  */
199  virtual bool isImmutable() const = 0;
200 
201  /**
202  * Can changes be made to the entries in @p group?
203  *
204  * @param group The group to check for immutability.
205  * @return @c false if the entries in @p group can be modified, otherwise @c true
206  */
207  bool isGroupImmutable(const QString &group) const;
208  /**
209  * Overload for isGroupImmutable(const QString&) const
210  *
211  * @param group name of group, encoded in UTF-8
212  */
213  bool isGroupImmutable(const QByteArray &group) const;
214  /**
215  * Overload for isGroupImmutable(const QString&) const
216  *
217  * @param group name of group, encoded in UTF-8
218  */
219  bool isGroupImmutable(const char *group) const;
220 
221 protected:
222  KConfigBase();
223 
224  /// @param group name of group, encoded in UTF-8
225  virtual bool hasGroupImpl(const QByteArray &group) const = 0;
226  /// @param group name of group, encoded in UTF-8
227  virtual KConfigGroup groupImpl(const QByteArray &group) = 0;
228  /// @param group name of group, encoded in UTF-8
229  virtual const KConfigGroup groupImpl(const QByteArray &group) const = 0;
230  /// @param group name of group, encoded in UTF-8
231  virtual void deleteGroupImpl(const QByteArray &group, WriteConfigFlags flags = Normal) = 0;
232  /// @param group name of group, encoded in UTF-8
233  virtual bool isGroupImmutableImpl(const QByteArray &group) const = 0;
234 
235  /** Virtual hook, used to add new "virtual" functions while maintaining
236  * binary compatibility. Unused in this class.
237  */
238  virtual void virtual_hook(int id, void *data);
239 };
240 
241 Q_DECLARE_OPERATORS_FOR_FLAGS(KConfigBase::WriteConfigFlags)
242 
243 #endif // KCONFIG_H
Interface to interact with configuration.
Definition: kconfigbase.h:30
AccessMode
WriteConfigFlag
Flags to control write entry.
Definition: kconfigbase.h:37
AccessMode
Possible return values for accessMode().
Definition: kconfigbase.h:175
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Wed Sep 27 2023 04:07:29 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.