KConfig

kconfig.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 KCONFIG_H
12 #define KCONFIG_H
13 
14 #include "kconfigbase.h"
15 
16 #include <kconfigcore_export.h>
17 
18 #include <QByteArray>
19 #include <QList>
20 #include <QStandardPaths>
21 #include <QString>
22 #include <QVariant>
23 
24 class KConfigGroup;
25 class KEntryMap;
26 class KConfigPrivate;
27 
28 /**
29  * \class KConfig kconfig.h <KConfig>
30  *
31  * \brief The central class of the KDE configuration data system.
32  *
33  * Quickstart:
34  *
35  * Get the default application config object via KSharedConfig::openConfig().
36  *
37  * Load a specific configuration file:
38  * \code
39  * KConfig config( "/etc/kderc", KConfig::SimpleConfig );
40  * \endcode
41  *
42  * Load the configuration of a specific component:
43  * \code
44  * KConfig config( "pluginrc" );
45  * \endcode
46  *
47  * In general it is recommended to use KSharedConfig instead of
48  * creating multiple instances of KConfig to avoid the overhead of
49  * separate objects or concerns about synchronizing writes to disk
50  * even if the configuration object is updated from multiple code paths.
51  * KSharedConfig provides a set of open methods as counterparts for the
52  * KConfig constructors.
53  *
54  * \sa KSharedConfig, KConfigGroup, <a href="https://techbase.kde.org/index.php?title=Development/Tutorials/KConfig">the techbase HOWTO on KConfig</a>.
55  */
56 class KCONFIGCORE_EXPORT KConfig : public KConfigBase
57 {
58 public:
59  /**
60  * Determines how the system-wide and user's global settings will affect
61  * the reading of the configuration.
62  *
63  * If CascadeConfig is selected, system-wide configuration sources are used
64  * to provide defaults for the settings accessed through this object, or
65  * possibly to override those settings in certain cases.
66  *
67  * If IncludeGlobals is selected, the kdeglobals configuration is used
68  * as additional configuration sources to provide defaults. Additionally
69  * selecting CascadeConfig will result in the system-wide kdeglobals sources
70  * also getting included.
71  *
72  * Note that the main configuration source overrides the cascaded sources,
73  * which override those provided to addConfigSources(), which override the
74  * global sources. The exception is that if a key or group is marked as
75  * being immutable, it will not be overridden.
76  *
77  * Note that all values other than IncludeGlobals and CascadeConfig are
78  * convenience definitions for the basic mode.
79  * Do @em not combine them with anything.
80  * @see OpenFlags
81  */
82  enum OpenFlag {
83  IncludeGlobals = 0x01, ///< Blend kdeglobals into the config object.
84  CascadeConfig = 0x02, ///< Cascade to system-wide config files.
85 
86  SimpleConfig = 0x00, ///< Just a single config file.
87  NoCascade = IncludeGlobals, ///< Include user's globals, but omit system settings.
88  NoGlobals = CascadeConfig, ///< Cascade to system settings, but omit user's globals.
89  FullConfig = IncludeGlobals | CascadeConfig, ///< Fully-fledged config, including globals and cascading to system settings
90  };
91  /**
92  * Stores a combination of #OpenFlag values.
93  */
94  Q_DECLARE_FLAGS(OpenFlags, OpenFlag)
95 
96  /**
97  * Creates a KConfig object to manipulate a configuration file for the
98  * current application.
99  *
100  * If an absolute path is specified for @p file, that file will be used
101  * as the store for the configuration settings. If a non-absolute path
102  * is provided, the file will be looked for in the standard directory
103  * specified by type. If no path is provided, a default
104  * configuration file will be used based on the name of the main
105  * application component.
106  *
107  * @p mode determines whether the user or global settings will be allowed
108  * to influence the values returned by this object. See OpenFlags for
109  * more details.
110  *
111  * @note You probably want to use KSharedConfig::openConfig instead.
112  *
113  * @param file the name of the file. If an empty string is passed in
114  * and SimpleConfig is passed in for the OpenFlags, then an in-memory
115  * KConfig object is created which will not write out to file nor which
116  * requires any file in the filesystem at all.
117  * @param mode how global settings should affect the configuration
118  * options exposed by this KConfig object
119  * @param type The standard directory to look for the configuration
120  * file in
121  *
122  * @sa KSharedConfig::openConfig(const QString&, OpenFlags, QStandardPaths::StandardLocation)
123  */
124  explicit KConfig(const QString &file = QString(),
125  OpenFlags mode = FullConfig,
127 
128  /**
129  * @internal
130  *
131  * Creates a KConfig object using the specified backend. If the backend can not
132  * be found or loaded, then the standard configuration parser is used as a fallback.
133  *
134  * @param file the file to be parsed
135  * @param backend the backend to load
136  * @param type where to look for the file if an absolute path is not provided
137  *
138  * @since 4.1
139  */
141 
142  ~KConfig() override;
143 
144  /**
145  * Returns the standard location enum passed to the constructor.
146  * Used by KSharedConfig.
147  * @since 5.0
148  */
149  QStandardPaths::StandardLocation locationType() const;
150 
151  /**
152  * Returns the filename used to store the configuration.
153  */
154  QString name() const;
155 
156  /**
157  * @return the flags this object was opened with
158  * @since 5.3
159  */
160  OpenFlags openFlags() const;
161 
162  /// @reimp
163  bool sync() override;
164 
165  /// Returns true if sync has any changes to write out.
166  /// @since 4.12
167  bool isDirty() const;
168 
169  /// @reimp
170  void markAsClean() override;
171 
172  /// @{ configuration object state
173  /// @reimp
174  AccessMode accessMode() const override;
175 
176  /**
177  * Whether the configuration can be written to.
178  *
179  * If @p warnUser is true and the configuration cannot be
180  * written to (ie: this method returns @c false), a warning
181  * message box will be shown to the user telling them to
182  * contact their system administrator to get the problem fixed.
183  *
184  * The most likely cause for this method returning @c false
185  * is that the user does not have write permission for the
186  * configuration file.
187  *
188  * @param warnUser whether to show a warning message to the user
189  * if the configuration cannot be written to
190  *
191  * @returns true if the configuration can be written to, false
192  * if the configuration cannot be written to
193  */
194  bool isConfigWritable(bool warnUser);
195  /// @}
196 
197  /**
198  * Copies all entries from this config object to a new config
199  * object that will save itself to @p file.
200  *
201  * The configuration will not actually be saved to @p file
202  * until the returned object is destroyed, or sync() is called
203  * on it.
204  *
205  * Do not forget to delete the returned KConfig object if
206  * @p config was 0.
207  *
208  * @param file the new config object will save itself to
209  * @param config if not 0, copy to the given KConfig object rather
210  * than creating a new one
211  *
212  * @return @p config if it was set, otherwise a new KConfig object
213  */
214  KConfig *copyTo(const QString &file, KConfig *config = nullptr) const;
215 
216  /**
217  * Ensures that the configuration file contains a certain update.
218  *
219  * If the configuration file does not contain the update @p id
220  * as contained in @p updateFile, kconf_update is run to update
221  * the configuration file.
222  *
223  * If you install config update files with critical fixes
224  * you may wish to use this method to verify that a critical
225  * update has indeed been performed to catch the case where
226  * a user restores an old config file from backup that has
227  * not been updated yet.
228  *
229  * @param id the update to check
230  * @param updateFile the file containing the update
231  */
232  void checkUpdate(const QString &id, const QString &updateFile);
233 
234  /**
235  * Updates the state of this object to match the persistent storage.
236  * Note that if this object has pending changes, this method will
237  * call sync() first so as not to lose those changes.
238  */
239  void reparseConfiguration();
240 
241  /// @{ extra config files
242  /**
243  * Adds the list of configuration sources to the merge stack.
244  *
245  * Currently only files are accepted as configuration sources.
246  *
247  * The first entry in @p sources is treated as the most general and will
248  * be overridden by the second entry. The settings in the final entry
249  * in @p sources will override all the other sources provided in the list.
250  *
251  * The settings in @p sources will also be overridden by the sources
252  * provided by any previous calls to addConfigSources().
253  *
254  * The settings in the global configuration sources will be overridden by
255  * the sources provided to this method (@see IncludeGlobals).
256  * All the sources provided to any call to this method will be overridden
257  * by any files that cascade from the source provided to the constructor
258  * (@see CascadeConfig), which will in turn be
259  * overridden by the source provided to the constructor.
260  *
261  * Note that only the most specific file, ie: the file provided to the
262  * constructor, will be written to by this object.
263  *
264  * The state is automatically updated by this method, so there is no need to call
265  * reparseConfiguration().
266  *
267  * @param sources A list of extra config sources.
268  */
269  void addConfigSources(const QStringList &sources);
270 
271  /**
272  * Returns a list of the additional configuration sources used in this object
273  */
274  QStringList additionalConfigSources() const;
275 
276  /// @}
277  /// @{ locales
278  /**
279  * Returns the current locale.
280  */
281  QString locale() const;
282  /**
283  * Sets the locale to @p aLocale.
284  *
285  * The global locale is used by default.
286  *
287  * @note If set to the empty string, @b no locale will be matched. This effectively disables
288  * reading translated entries.
289  *
290  * @return @c true if locale was changed, @c false if the call had no
291  * effect (eg: @p aLocale was already the current locale for this
292  * object)
293  */
294  bool setLocale(const QString &aLocale);
295  /// @}
296 
297  /// @{ defaults
298  /**
299  * When set, all readEntry calls return the system-wide (default) values
300  * instead of the user's settings.
301  *
302  * This is off by default.
303  *
304  * @param b whether to read the system-wide defaults instead of the
305  * user's settings
306  */
307  void setReadDefaults(bool b);
308  /**
309  * @returns @c true if the system-wide defaults will be read instead of the
310  * user's settings
311  */
312  bool readDefaults() const;
313  /// @}
314 
315  /// @{ immutability
316  /// @reimp
317  bool isImmutable() const override;
318  /// @}
319 
320  /// @{ global
321 #if KCONFIGCORE_ENABLE_DEPRECATED_SINCE(4, 0)
322  /**
323  * Forces all following write-operations to be performed on @c kdeglobals,
324  * independent of the @c Global flag in writeEntry().
325  *
326  * @param force true to force writing to kdeglobals
327  * @see forceGlobal
328  * @deprecated Since 4.0
329  */
330  KCONFIGCORE_DEPRECATED_VERSION(4, 0, "Not recommended")
331  void setForceGlobal(bool force);
332 #endif
333 
334 #if KCONFIGCORE_ENABLE_DEPRECATED_SINCE(4, 0)
335  /**
336  * Returns whether all entries are being written to @c kdeglobals.
337  *
338  * @return @c true if all entries are being written to @c kdeglobals
339  * @see setForceGlobal
340  * @deprecated Since 4.0
341  */
342  KCONFIGCORE_DEPRECATED_VERSION(4, 0, "Not recommended")
343  bool forceGlobal() const;
344 #endif
345  /// @}
346 
347  /// @reimp
348  QStringList groupList() const override;
349 
350  /**
351  * Returns a map (tree) of entries in a particular group.
352  *
353  * The entries are all returned as strings.
354  *
355  * @param aGroup The group to get entries from.
356  *
357  * @return A map of entries in the group specified, indexed by key.
358  * The returned map may be empty if the group is empty, or not found.
359  * @see QMap
360  */
361  QMap<QString, QString> entryMap(const QString &aGroup = QString()) const;
362 
363  /**
364  * Sets the name of the application config file.
365  * @since 5.0
366  */
367  static void setMainConfigName(const QString &str);
368 
369  /**
370  * Get the name of application config file.
371  * @since 5.93
372  */
373  static QString mainConfigName();
374 
375 protected:
376  bool hasGroupImpl(const QByteArray &group) const override;
377  KConfigGroup groupImpl(const QByteArray &b) override;
378  const KConfigGroup groupImpl(const QByteArray &b) const override;
379  void deleteGroupImpl(const QByteArray &group, WriteConfigFlags flags = Normal) override;
380  bool isGroupImmutableImpl(const QByteArray &aGroup) const override;
381 
382  friend class KConfigGroup;
383  friend class KConfigGroupPrivate;
384  friend class KSharedConfig;
385 
386  /** Virtual hook, used to add new "virtual" functions while maintaining
387  * binary compatibility. Unused in this class.
388  */
389  void virtual_hook(int id, void *data) override;
390 
391  KConfigPrivate *const d_ptr;
392 
393  KConfig(KConfigPrivate &d);
394 
395 private:
396  friend class KConfigTest;
397 
398  QStringList keyList(const QString &aGroup = QString()) const;
399 
400  Q_DISABLE_COPY(KConfig)
401 
402  Q_DECLARE_PRIVATE(KConfig)
403 };
404 Q_DECLARE_OPERATORS_FOR_FLAGS(KConfig::OpenFlags)
405 
406 #endif // KCONFIG_H
virtual QStringList groupList() const =0
Returns a list of groups that are known about.
Interface to interact with configuration.
Definition: kconfigbase.h:30
OpenFlag
Determines how the system-wide and user's global settings will affect the reading of the configuratio...
Definition: kconfig.h:82
The central class of the KDE configuration data system.
Definition: kconfig.h:56
virtual AccessMode accessMode() const =0
Returns the access mode of the app-config object.
virtual bool sync()=0
Syncs the configuration object that this group belongs to.
virtual void deleteGroupImpl(const QByteArray &group, WriteConfigFlags flags=Normal)=0
AccessMode
Possible return values for accessMode().
Definition: kconfigbase.h:175
virtual bool isImmutable() const =0
Checks whether this configuration object can be modified.
virtual void virtual_hook(int id, void *data)
Virtual hook, used to add new "virtual" functions while maintaining binary compatibility.
Definition: kconfigbase.cpp:99
virtual bool isGroupImmutableImpl(const QByteArray &group) const =0
KConfig(const QString &file=QString(), OpenFlags mode=FullConfig, QStandardPaths::StandardLocation type=QStandardPaths::GenericConfigLocation)
Creates a KConfig object to manipulate a configuration file for the current application.
Definition: kconfig.cpp:246
virtual KConfigGroup groupImpl(const QByteArray &group)=0
virtual void markAsClean()=0
Reset the dirty flags of all entries in the entry map, so the values will not be written to disk on a...
virtual bool hasGroupImpl(const QByteArray &group) const =0
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Fri May 27 2022 04:09:36 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.