File indexing completed on 2024-05-12 11:47:18
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 KCONFIGBASE_H 0012 #define KCONFIGBASE_H 0013 0014 #include <kconfigcore_export.h> 0015 0016 #include <QStringList> 0017 #include <QtGlobal> 0018 0019 class KConfigGroup; 0020 class KConfigBasePrivate; 0021 0022 /** 0023 * \class KConfigBase kconfigbase.h <KConfigBase> 0024 * \brief Interface to interact with configuration. 0025 * 0026 * KConfigBase allows a component of an application to persists its configuration 0027 * without the component knowing if it is storing the configuration into a top 0028 * level KConfig or a KConfigGroup inside a KConfig instance. 0029 */ 0030 class KCONFIGCORE_EXPORT KConfigBase 0031 { 0032 public: 0033 /** 0034 * Flags to control write entry 0035 * @see WriteConfigFlags 0036 */ 0037 enum WriteConfigFlag { 0038 Persistent = 0x01, 0039 /**< 0040 * Save this entry when saving the config object. 0041 */ 0042 Global = 0x02, 0043 /**< 0044 * Save the entry to the global %KDE config file instead of the 0045 * application specific config file. 0046 */ 0047 Localized = 0x04, 0048 /**< 0049 * Add the locale tag to the key when writing it. 0050 */ 0051 Notify = 0x08 | Persistent, 0052 /**< 0053 * Notify remote KConfigWatchers of changes (requires DBus support) 0054 * Implied persistent 0055 * @since 5.51 0056 */ 0057 Normal = Persistent, 0058 /**< 0059 * Save the entry to the application specific config file without 0060 * a locale tag. This is the default. 0061 */ 0062 0063 }; 0064 /** 0065 * Stores a combination of #WriteConfigFlag values. 0066 */ 0067 Q_DECLARE_FLAGS(WriteConfigFlags, WriteConfigFlag) 0068 0069 /** 0070 * Destructs the KConfigBase object. 0071 */ 0072 virtual ~KConfigBase(); 0073 0074 /** 0075 * Returns a list of groups that are known about. 0076 * 0077 * @return The list of groups. 0078 **/ 0079 virtual QStringList groupList() const = 0; 0080 0081 /** 0082 * Returns true if the specified group is known about. 0083 * 0084 * @param group name of group to search for 0085 * @return true if the group exists. 0086 */ 0087 bool hasGroup(const QString &group) const; 0088 /** 0089 * Overload for hasGroup(const QString&) const 0090 * 0091 * @param group name of group to search for, encoded in UTF-8 0092 */ 0093 bool hasGroup(const char *group) const; 0094 /** 0095 * Overload for hasGroup(const QString&) const 0096 * 0097 * @param group name of group to search for, encoded in UTF-8 0098 */ 0099 bool hasGroup(const QByteArray &group) const; 0100 0101 /** 0102 * Returns an object for the named subgroup. 0103 * 0104 * @param group the group to open. Pass an empty string here to the KConfig 0105 * object to obtain a handle on the root group. 0106 * @return config group object for the given group name. 0107 */ 0108 KConfigGroup group(const QString &group); 0109 /** 0110 * Overload for group(const QString&) 0111 * 0112 * @param group name of group, encoded in UTF-8 0113 */ 0114 KConfigGroup group(const QByteArray &group); 0115 /** 0116 * Overload for group(const QString&) 0117 * 0118 * @param group name of group, encoded in UTF-8 0119 */ 0120 KConfigGroup group(const char *group); 0121 0122 /** 0123 * Const overload for group(const QString&) 0124 */ 0125 const KConfigGroup group(const QString &group) const; 0126 /** 0127 * Const overload for group(const QString&) 0128 * 0129 * @param group name of group, encoded in UTF-8 0130 */ 0131 const KConfigGroup group(const QByteArray &group) const; 0132 /** 0133 * Const overload for group(const QString&) 0134 * 0135 * @param group name of group, encoded in UTF-8 0136 */ 0137 const KConfigGroup group(const char *group) const; 0138 0139 /** 0140 * Delete @p group. 0141 * This marks @p group as @em deleted in the config object. This effectively 0142 * removes any cascaded values from config files earlier in the stack. 0143 */ 0144 void deleteGroup(const QString &group, WriteConfigFlags flags = Normal); 0145 /** 0146 * Overload for deleteGroup(const QString&, WriteConfigFlags) 0147 * 0148 * @param group name of group to delete, encoded in UTF-8 0149 */ 0150 void deleteGroup(const QByteArray &group, WriteConfigFlags flags = Normal); 0151 /** 0152 * Overload for deleteGroup(const QString&, WriteConfigFlags) 0153 * 0154 * @param group name of group to delete, encoded in UTF-8 0155 */ 0156 void deleteGroup(const char *group, WriteConfigFlags flags = Normal); 0157 0158 /** 0159 * Syncs the configuration object that this group belongs to. 0160 * Unrelated concurrent changes to the same file are merged and thus 0161 * not overwritten. Note however, that this object is @em not automatically 0162 * updated with those changes. 0163 */ 0164 virtual bool sync() = 0; 0165 0166 /** 0167 * Reset the dirty flags of all entries in the entry map, so the 0168 * values will not be written to disk on a later call to sync(). 0169 */ 0170 virtual void markAsClean() = 0; 0171 0172 /** 0173 * Possible return values for accessMode(). 0174 */ 0175 enum AccessMode { 0176 NoAccess, 0177 ReadOnly, 0178 ReadWrite, 0179 }; 0180 0181 /** 0182 * Returns the access mode of the app-config object. 0183 * 0184 * Possible return values 0185 * are NoAccess (the application-specific config file could not be 0186 * opened neither read-write nor read-only), ReadOnly (the 0187 * application-specific config file is opened read-only, but not 0188 * read-write) and ReadWrite (the application-specific config 0189 * file is opened read-write). 0190 * 0191 * @return the access mode of the app-config object 0192 */ 0193 virtual AccessMode accessMode() const = 0; 0194 0195 /** 0196 * Checks whether this configuration object can be modified. 0197 * @return whether changes may be made to this configuration object. 0198 */ 0199 virtual bool isImmutable() const = 0; 0200 0201 /** 0202 * Can changes be made to the entries in @p group? 0203 * 0204 * @param group The group to check for immutability. 0205 * @return @c false if the entries in @p group can be modified, otherwise @c true 0206 */ 0207 bool isGroupImmutable(const QString &group) const; 0208 /** 0209 * Overload for isGroupImmutable(const QString&) const 0210 * 0211 * @param group name of group, encoded in UTF-8 0212 */ 0213 bool isGroupImmutable(const QByteArray &group) const; 0214 /** 0215 * Overload for isGroupImmutable(const QString&) const 0216 * 0217 * @param group name of group, encoded in UTF-8 0218 */ 0219 bool isGroupImmutable(const char *group) const; 0220 0221 protected: 0222 KConfigBase(); 0223 0224 /// @param group name of group, encoded in UTF-8 0225 virtual bool hasGroupImpl(const QByteArray &group) const = 0; 0226 /// @param group name of group, encoded in UTF-8 0227 virtual KConfigGroup groupImpl(const QByteArray &group) = 0; 0228 /// @param group name of group, encoded in UTF-8 0229 virtual const KConfigGroup groupImpl(const QByteArray &group) const = 0; 0230 /// @param group name of group, encoded in UTF-8 0231 virtual void deleteGroupImpl(const QByteArray &group, WriteConfigFlags flags = Normal) = 0; 0232 /// @param group name of group, encoded in UTF-8 0233 virtual bool isGroupImmutableImpl(const QByteArray &group) const = 0; 0234 0235 /** Virtual hook, used to add new "virtual" functions while maintaining 0236 * binary compatibility. Unused in this class. 0237 */ 0238 virtual void virtual_hook(int id, void *data); 0239 }; 0240 0241 Q_DECLARE_OPERATORS_FOR_FLAGS(KConfigBase::WriteConfigFlags) 0242 0243 #endif // KCONFIG_H