File indexing completed on 2024-04-21 03:53:12
0001 /* 0002 This file is part of the KDE libraries 0003 SPDX-FileCopyrightText: 2006, 2007 Thomas Braxton <kde.braxton@gmail.com> 0004 SPDX-FileCopyrightText: 2001 Waldo Bastian <bastian@kde.org> 0005 SPDX-FileCopyrightText: 1999 Preston Brown <pbrown@kde.org> 0006 SPDX-FileCopyrightText: 1997 Matthias Kalle Dalheimer <kalle@kde.org> 0007 0008 SPDX-License-Identifier: LGPL-2.0-or-later 0009 */ 0010 0011 #ifndef KCONFIG_H 0012 #define KCONFIG_H 0013 0014 #include "kconfigbase.h" 0015 0016 #include <kconfigcore_export.h> 0017 0018 #include <QByteArray> 0019 #include <QList> 0020 #include <QStandardPaths> 0021 #include <QString> 0022 #include <QVariant> 0023 0024 class KConfigGroup; 0025 class KConfigPrivate; 0026 0027 /** 0028 * \class KConfig kconfig.h <KConfig> 0029 * 0030 * \brief The central class of the KDE configuration data system. 0031 * 0032 * Quickstart: 0033 * 0034 * Get the default application config object via KSharedConfig::openConfig(). 0035 * 0036 * Load a specific configuration file: 0037 * \code 0038 * KConfig config("/etc/kderc", KConfig::SimpleConfig); 0039 * \endcode 0040 * 0041 * Load the configuration of a specific component: 0042 * \code 0043 * KConfig config("pluginrc"); 0044 * \endcode 0045 * 0046 * In general it is recommended to use KSharedConfig instead of 0047 * creating multiple instances of KConfig to avoid the overhead of 0048 * separate objects or concerns about synchronizing writes to disk 0049 * even if the configuration object is updated from multiple code paths. 0050 * KSharedConfig provides a set of open methods as counterparts for the 0051 * KConfig constructors. 0052 * 0053 * \sa KSharedConfig, KConfigGroup, <a href="https://techbase.kde.org/index.php?title=Development/Tutorials/KConfig">the techbase HOWTO on KConfig</a>. 0054 */ 0055 class KCONFIGCORE_EXPORT KConfig : public KConfigBase 0056 { 0057 public: 0058 /** 0059 * Determines how the system-wide and user's global settings will affect 0060 * the reading of the configuration. 0061 * 0062 * If CascadeConfig is selected, system-wide configuration sources are used 0063 * to provide defaults for the settings accessed through this object, or 0064 * possibly to override those settings in certain cases. 0065 * 0066 * If IncludeGlobals is selected, the kdeglobals configuration is used 0067 * as additional configuration sources to provide defaults. Additionally 0068 * selecting CascadeConfig will result in the system-wide kdeglobals sources 0069 * also getting included. 0070 * 0071 * Note that the main configuration source overrides the cascaded sources, 0072 * which override those provided to addConfigSources(), which override the 0073 * global sources. The exception is that if a key or group is marked as 0074 * being immutable, it will not be overridden. 0075 * 0076 * Note that all values other than IncludeGlobals and CascadeConfig are 0077 * convenience definitions for the basic mode. 0078 * Do @em not combine them with anything. 0079 * @see OpenFlags 0080 */ 0081 enum OpenFlag { 0082 IncludeGlobals = 0x01, ///< Blend kdeglobals into the config object. 0083 CascadeConfig = 0x02, ///< Cascade to system-wide config files. 0084 0085 SimpleConfig = 0x00, ///< Just a single config file. 0086 NoCascade = IncludeGlobals, ///< Include user's globals, but omit system settings. 0087 NoGlobals = CascadeConfig, ///< Cascade to system settings, but omit user's globals. 0088 FullConfig = IncludeGlobals | CascadeConfig, ///< Fully-fledged config, including globals and cascading to system settings 0089 }; 0090 /** 0091 * Stores a combination of #OpenFlag values. 0092 */ 0093 Q_DECLARE_FLAGS(OpenFlags, OpenFlag) 0094 0095 /** 0096 * Creates a KConfig object to manipulate a configuration file for the 0097 * current application. 0098 * 0099 * If an absolute path is specified for @p file, that file will be used 0100 * as the store for the configuration settings. If a non-absolute path 0101 * is provided, the file will be looked for in the standard directory 0102 * specified by type. If no path is provided, a default 0103 * configuration file will be used based on the name of the main 0104 * application component. 0105 * 0106 * @p mode determines whether the user or global settings will be allowed 0107 * to influence the values returned by this object. See OpenFlags for 0108 * more details. 0109 * 0110 * @note You probably want to use KSharedConfig::openConfig instead. 0111 * 0112 * @param file the name of the file. If an empty string is passed in 0113 * and SimpleConfig is passed in for the OpenFlags, then an in-memory 0114 * KConfig object is created which will not write out to file nor which 0115 * requires any file in the filesystem at all. 0116 * @param mode how global settings should affect the configuration 0117 * options exposed by this KConfig object 0118 * @param type The standard directory to look for the configuration 0119 * file in 0120 * 0121 * @sa KSharedConfig::openConfig(const QString&, OpenFlags, QStandardPaths::StandardLocation) 0122 */ 0123 explicit KConfig(const QString &file = QString(), 0124 OpenFlags mode = FullConfig, 0125 QStandardPaths::StandardLocation type = QStandardPaths::GenericConfigLocation); 0126 0127 /** 0128 * @internal 0129 * 0130 * Creates a KConfig object using the specified backend. If the backend can not 0131 * be found or loaded, then the standard configuration parser is used as a fallback. 0132 * 0133 * @param file the file to be parsed 0134 * @param backend the backend to load 0135 * @param type where to look for the file if an absolute path is not provided 0136 * 0137 * @since 4.1 0138 */ 0139 KConfig(const QString &file, const QString &backend, QStandardPaths::StandardLocation type = QStandardPaths::GenericConfigLocation); 0140 0141 ~KConfig() override; 0142 0143 /** 0144 * Returns the standard location enum passed to the constructor. 0145 * Used by KSharedConfig. 0146 * @since 5.0 0147 */ 0148 QStandardPaths::StandardLocation locationType() const; 0149 0150 /** 0151 * Returns the filename used to store the configuration. 0152 */ 0153 QString name() const; 0154 0155 /** 0156 * @return the flags this object was opened with 0157 * @since 5.3 0158 */ 0159 OpenFlags openFlags() const; 0160 0161 /// @reimp 0162 bool sync() override; 0163 0164 /// Returns true if sync has any changes to write out. 0165 /// @since 4.12 0166 bool isDirty() const; 0167 0168 /// @reimp 0169 void markAsClean() override; 0170 0171 /// @{ configuration object state 0172 /// @reimp 0173 AccessMode accessMode() const override; 0174 0175 /** 0176 * Whether the configuration can be written to. 0177 * 0178 * If @p warnUser is true and the configuration cannot be 0179 * written to (ie: this method returns @c false), a warning 0180 * message box will be shown to the user telling them to 0181 * contact their system administrator to get the problem fixed. 0182 * 0183 * The most likely cause for this method returning @c false 0184 * is that the user does not have write permission for the 0185 * configuration file. 0186 * 0187 * @param warnUser whether to show a warning message to the user 0188 * if the configuration cannot be written to 0189 * 0190 * @returns true if the configuration can be written to, false 0191 * if the configuration cannot be written to 0192 */ 0193 bool isConfigWritable(bool warnUser); 0194 /// @} 0195 0196 /** 0197 * Copies all entries from this config object to a new config 0198 * object that will save itself to @p file. 0199 * 0200 * The configuration will not actually be saved to @p file 0201 * until the returned object is destroyed, or sync() is called 0202 * on it. 0203 * 0204 * Do not forget to delete the returned KConfig object if 0205 * @p config was 0. 0206 * 0207 * @param file the new config object will save itself to 0208 * @param config if not 0, copy to the given KConfig object rather 0209 * than creating a new one 0210 * 0211 * @return @p config if it was set, otherwise a new KConfig object 0212 */ 0213 KConfig *copyTo(const QString &file, KConfig *config = nullptr) const; 0214 0215 /** 0216 * Ensures that the configuration file contains a certain update. 0217 * 0218 * If the configuration file does not contain the update @p id 0219 * as contained in @p updateFile, kconf_update is run to update 0220 * the configuration file. 0221 * 0222 * If you install config update files with critical fixes 0223 * you may wish to use this method to verify that a critical 0224 * update has indeed been performed to catch the case where 0225 * a user restores an old config file from backup that has 0226 * not been updated yet. 0227 * 0228 * @param id the update to check 0229 * @param updateFile the file containing the update 0230 */ 0231 void checkUpdate(const QString &id, const QString &updateFile); 0232 0233 /** 0234 * Updates the state of this object to match the persistent storage. 0235 * Note that if this object has pending changes, this method will 0236 * call sync() first so as not to lose those changes. 0237 */ 0238 void reparseConfiguration(); 0239 0240 /// @{ extra config files 0241 /** 0242 * Adds the list of configuration sources to the merge stack. 0243 * 0244 * Currently only files are accepted as configuration sources. 0245 * 0246 * The first entry in @p sources is treated as the most general and will 0247 * be overridden by the second entry. The settings in the final entry 0248 * in @p sources will override all the other sources provided in the list. 0249 * 0250 * The settings in @p sources will also be overridden by the sources 0251 * provided by any previous calls to addConfigSources(). 0252 * 0253 * The settings in the global configuration sources will be overridden by 0254 * the sources provided to this method (@see IncludeGlobals). 0255 * All the sources provided to any call to this method will be overridden 0256 * by any files that cascade from the source provided to the constructor 0257 * (@see CascadeConfig), which will in turn be 0258 * overridden by the source provided to the constructor. 0259 * 0260 * Note that only the most specific file, ie: the file provided to the 0261 * constructor, will be written to by this object. 0262 * 0263 * The state is automatically updated by this method, so there is no need to call 0264 * reparseConfiguration(). 0265 * 0266 * @param sources A list of extra config sources. 0267 */ 0268 void addConfigSources(const QStringList &sources); 0269 0270 /** 0271 * Returns a list of the additional configuration sources used in this object 0272 */ 0273 QStringList additionalConfigSources() const; 0274 0275 /// @} 0276 /// @{ locales 0277 /** 0278 * Returns the current locale. 0279 */ 0280 QString locale() const; 0281 /** 0282 * Sets the locale to @p aLocale. 0283 * 0284 * The global locale is used by default. 0285 * 0286 * @note If set to the empty string, @b no locale will be matched. This effectively disables 0287 * reading translated entries. 0288 * 0289 * @return @c true if locale was changed, @c false if the call had no 0290 * effect (eg: @p aLocale was already the current locale for this 0291 * object) 0292 */ 0293 bool setLocale(const QString &aLocale); 0294 /// @} 0295 0296 /// @{ defaults 0297 /** 0298 * When set, all readEntry calls return the system-wide (default) values 0299 * instead of the user's settings. 0300 * 0301 * This is off by default. 0302 * 0303 * @param b whether to read the system-wide defaults instead of the 0304 * user's settings 0305 */ 0306 void setReadDefaults(bool b); 0307 /** 0308 * @returns @c true if the system-wide defaults will be read instead of the 0309 * user's settings 0310 */ 0311 bool readDefaults() const; 0312 /// @} 0313 0314 /// @{ immutability 0315 /// @reimp 0316 bool isImmutable() const override; 0317 /// @} 0318 0319 /// @reimp 0320 QStringList groupList() const override; 0321 0322 /** 0323 * Returns a map (tree) of entries in a particular group. 0324 * 0325 * The entries are all returned as strings. 0326 * 0327 * @param aGroup The group to get entries from. 0328 * 0329 * @return A map of entries in the group specified, indexed by key. 0330 * The returned map may be empty if the group is empty, or not found. 0331 * @see QMap 0332 */ 0333 QMap<QString, QString> entryMap(const QString &aGroup = QString()) const; 0334 0335 /** 0336 * Sets the name of the application config file. 0337 * @since 5.0 0338 */ 0339 static void setMainConfigName(const QString &str); 0340 0341 /** 0342 * Get the name of application config file. 0343 * @since 5.93 0344 */ 0345 static QString mainConfigName(); 0346 0347 protected: 0348 bool hasGroupImpl(const QString &groupName) const override; 0349 KConfigGroup groupImpl(const QString &groupName) override; 0350 const KConfigGroup groupImpl(const QString &groupName) const override; 0351 void deleteGroupImpl(const QString &groupName, WriteConfigFlags flags = Normal) override; 0352 bool isGroupImmutableImpl(const QString &groupName) const override; 0353 0354 friend class KConfigGroup; 0355 friend class KConfigGroupPrivate; 0356 friend class KSharedConfig; 0357 0358 /** Virtual hook, used to add new "virtual" functions while maintaining 0359 * binary compatibility. Unused in this class. 0360 */ 0361 void virtual_hook(int id, void *data) override; 0362 0363 KConfigPrivate *const d_ptr; 0364 0365 KCONFIGCORE_NO_EXPORT explicit KConfig(KConfigPrivate &d); 0366 0367 private: 0368 friend class KConfigTest; 0369 0370 Q_DISABLE_COPY(KConfig) 0371 0372 Q_DECLARE_PRIVATE(KConfig) 0373 }; 0374 Q_DECLARE_OPERATORS_FOR_FLAGS(KConfig::OpenFlags) 0375 0376 #endif // KCONFIG_H