File indexing completed on 2024-04-28 03:53:15
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 /** 0090 * Returns an object for the named subgroup. 0091 * 0092 * @param group the group to open. Pass an empty string here to the KConfig 0093 * object to obtain a handle on the root group. 0094 * @return config group object for the given group name. 0095 */ 0096 KConfigGroup group(const QString &group); 0097 0098 /** 0099 * Const overload for group(const QString&) 0100 */ 0101 const KConfigGroup group(const QString &group) const; 0102 0103 /** 0104 * Delete @p group. 0105 * This marks @p group as @em deleted in the config object. This effectively 0106 * removes any cascaded values from config files earlier in the stack. 0107 */ 0108 void deleteGroup(const QString &group, WriteConfigFlags flags = Normal); 0109 0110 /** 0111 * Syncs the configuration object that this group belongs to. 0112 * Unrelated concurrent changes to the same file are merged and thus 0113 * not overwritten. Note however, that this object is @em not automatically 0114 * updated with those changes. 0115 */ 0116 virtual bool sync() = 0; 0117 0118 /** 0119 * Reset the dirty flags of all entries in the entry map, so the 0120 * values will not be written to disk on a later call to sync(). 0121 */ 0122 virtual void markAsClean() = 0; 0123 0124 /** 0125 * Possible return values for accessMode(). 0126 */ 0127 enum AccessMode { 0128 NoAccess, 0129 ReadOnly, 0130 ReadWrite, 0131 }; 0132 0133 /** 0134 * Returns the access mode of the app-config object. 0135 * 0136 * Possible return values 0137 * are NoAccess (the application-specific config file could not be 0138 * opened neither read-write nor read-only), ReadOnly (the 0139 * application-specific config file is opened read-only, but not 0140 * read-write) and ReadWrite (the application-specific config 0141 * file is opened read-write). 0142 * 0143 * @return the access mode of the app-config object 0144 */ 0145 virtual AccessMode accessMode() const = 0; 0146 0147 /** 0148 * Checks whether this configuration object can be modified. 0149 * @return whether changes may be made to this configuration object. 0150 */ 0151 virtual bool isImmutable() const = 0; 0152 0153 /** 0154 * Can changes be made to the entries in @p group? 0155 * 0156 * @param group The group to check for immutability. 0157 * @return @c false if the entries in @p group can be modified, otherwise @c true 0158 */ 0159 bool isGroupImmutable(const QString &group) const; 0160 0161 protected: 0162 KConfigBase(); 0163 0164 /// @param groupName name of group 0165 virtual bool hasGroupImpl(const QString &groupName) const = 0; 0166 /// @param groupName name of group 0167 virtual KConfigGroup groupImpl(const QString &groupName) = 0; 0168 /// @param groupName name of group 0169 virtual const KConfigGroup groupImpl(const QString &groupName) const = 0; 0170 /// @param groupName name of group 0171 virtual void deleteGroupImpl(const QString &groupName, WriteConfigFlags flags = Normal) = 0; 0172 /// @param groupName name of group 0173 virtual bool isGroupImmutableImpl(const QString &groupName) const = 0; 0174 0175 /** Virtual hook, used to add new "virtual" functions while maintaining 0176 * binary compatibility. Unused in this class. 0177 */ 0178 virtual void virtual_hook(int id, void *data); 0179 }; 0180 0181 Q_DECLARE_OPERATORS_FOR_FLAGS(KConfigBase::WriteConfigFlags) 0182 0183 #endif // KCONFIG_H