wilderjds
/
kconfig
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

API dox: state explicitly expected encoding for KConfig key & group names

Browse Source 
While the API might have been once designed to allow random byte strings
to be used as ids and only converted QString to UTF-8, the current
implementation in many places assumes the byte strings passed via
const char* or QByteArray are also in of UTF-8 encoding
(or at least ASCII7-only).
See e.g. KConfigGroup::entryMap() or KConfigGroup::name().

Stating the supported encoding explicitly should avoid any misassumptions.
wilder
Friedrich W. H. Kossebau 6 years ago
parent f0cf93864b
commit d1edad3cc4
3 changed files with 212 additions and 57 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 94
      src/core/kconfigbase.h
  2. 173
      src/core/kconfiggroup.h
  3. 2
      src/core/kconfigwatcher.h

94
src/core/kconfigbase.h
Unescape View File

@ -81,37 +81,78 @@ public:
/**
* Returns true if the specified group is known about.
*
* @param group The group to search for.
* @param group name of group to search for
* @return true if the group exists.
*/
bool hasGroup(const QString &group) const;
/**
* Overload for hasGroup(const QString&) const
*
* @param group name of group to search for, encoded in UTF-8
*/
bool hasGroup(const char *group) const;
/**
* Overload for hasGroup(const QString&) const
*
* @param group name of group to search for, encoded in UTF-8
*/
bool hasGroup(const QByteArray &group) const;
/**
* Returns an object for the named subgroup.
*
* @param group the group to open. Pass a null string on to the KConfig
* @param group the group to open. Pass an empty string here to the KConfig
* object to obtain a handle on the root group.
* @return The list of groups.
**/
KConfigGroup group(const QByteArray &group);
* @return config group object for the given group name.
*/
KConfigGroup group(const QString &group);
/**
* Overload for group(const QString&)
*
* @param group name of group, encoded in UTF-8
*/
KConfigGroup group(const QByteArray &group);
/**
* Overload for group(const QString&)
*
* @param group name of group, encoded in UTF-8
*/
KConfigGroup group(const char *group);
/**
* @overload
**/
const KConfigGroup group(const QByteArray &group) const;
* Const overload for group(const QString&)
*/
const KConfigGroup group(const QString &group) const;
/**
* Const overload for group(const QString&)
*
* @param group name of group, encoded in UTF-8
*/
const KConfigGroup group(const QByteArray &group) const;
/**
* Const overload for group(const QString&)
*
* @param group name of group, encoded in UTF-8
*/
const KConfigGroup group(const char *group) const;
/**
* Delete @p aGroup. This marks @p aGroup as @em deleted in the config object. This effectively
* Delete @p group.
* This marks @p group as @em deleted in the config object. This effectively
* removes any cascaded values from config files earlier in the stack.
*/
void deleteGroup(const QByteArray &group, WriteConfigFlags flags = Normal);
void deleteGroup(const QString &group, WriteConfigFlags flags = Normal);
/**
* Overload for deleteGroup(const QString&, WriteConfigFlags)
*
* @param group name of group to delete, encoded in UTF-8
*/
void deleteGroup(const QByteArray &group, WriteConfigFlags flags = Normal);
/**
* Overload for deleteGroup(const QString&, WriteConfigFlags)
*
* @param group name of group to delete, encoded in UTF-8
*/
void deleteGroup(const char *group, WriteConfigFlags flags = Normal);
/**
@ -154,23 +195,38 @@ public:
virtual bool isImmutable() const = 0;
/**
* Can changes be made to the entries in @p aGroup?
* Can changes be made to the entries in @p group?
*
* @param group The group to check for immutability.
* @return @c false if the entries in @p group can be modified, otherwise @c true
*/
bool isGroupImmutable(const QString &group) const;
/**
* Overload for isGroupImmutable(const QString&) const
*
* @param group name of group, encoded in UTF-8
*/
bool isGroupImmutable(const QByteArray &group) const;
/**
* Overload for isGroupImmutable(const QString&) const
*
* @param aGroup The group to check for immutability.
* @return @c false if the entries in @p aGroup can be modified.
* @param group name of group, encoded in UTF-8
*/
bool isGroupImmutable(const QByteArray &aGroup) const;
bool isGroupImmutable(const QString &aGroup) const;
bool isGroupImmutable(const char *aGroup) const;
bool isGroupImmutable(const char *group) const;
protected:
KConfigBase();
/// @param group name of group, encoded in UTF-8
virtual bool hasGroupImpl(const QByteArray &group) const = 0;
virtual KConfigGroup groupImpl(const QByteArray &b) = 0;
virtual const KConfigGroup groupImpl(const QByteArray &b) const = 0;
/// @param group name of group, encoded in UTF-8
virtual KConfigGroup groupImpl(const QByteArray &group) = 0;
/// @param group name of group, encoded in UTF-8
virtual const KConfigGroup groupImpl(const QByteArray &group) const = 0;
/// @param group name of group, encoded in UTF-8
virtual void deleteGroupImpl(const QByteArray &group, WriteConfigFlags flags = Normal) = 0;
virtual bool isGroupImmutableImpl(const QByteArray &aGroup) const = 0;
/// @param group name of group, encoded in UTF-8
virtual bool isGroupImmutableImpl(const QByteArray &group) const = 0;
/** Virtual hook, used to add new "virtual" functions while maintaining
* binary compatibility. Unused in this class.

173
src/core/kconfiggroup.h
Unescape View File

@ -51,10 +51,14 @@ public:
* This allows the creation of subgroups by passing another
* group as @p master.
*
* @p group is the group name encoded in UTF-8.
* @param group name of group
*/
KConfigGroup(KConfigBase *master, const QString &group);
/** Overload for KConfigGroup(KConfigBase*,const QString&) */
/**
* Overload for KConfigGroup(KConfigBase*,const QString&)
*
* @param group name of group, encoded in UTF-8
*/
KConfigGroup(KConfigBase *master, const char *group);
/**
@ -66,12 +70,20 @@ public:
* as @p master.
*/
KConfigGroup(const KConfigBase *master, const QString &group);
/** Overload for KConfigGroup(const KConfigBase*,const QString&) */
/**
* Overload for KConfigGroup(const KConfigBase*,const QString&)
*
* @param group name of group, encoded in UTF-8
*/
KConfigGroup(const KConfigBase *master, const char *group);
/** Overload for KConfigGroup(const KConfigBase*,const QString&) */
KConfigGroup(const QExplicitlySharedDataPointer<KSharedConfig> &master, const QString &group);
/** Overload for KConfigGroup(const KConfigBase*,const QString&) */
/**
* Overload for KConfigGroup(const KConfigBase*,const QString&)
*
* @param group name of group, encoded in UTF-8
*/
KConfigGroup(const QExplicitlySharedDataPointer<KSharedConfig> &master, const char *group);
/**
@ -143,6 +155,8 @@ public:
/**
* Overload for changeGroup(const QString&)
*
* @param group name of group, encoded in UTF-8
*
* @deprecated Since 5.0.
* Create another KConfigGroup from the parent of this group instead.
*/
@ -237,7 +251,10 @@ public:
{
return readEntry(key.toUtf8().constData(), aDefault);
}
/** Overload for readEntry(const QString&, const T&) const */
/**
* Overload for readEntry<T>(const QString&, const T&) const
* @param key name of key, encoded in UTF-8
*/
template <typename T>
T readEntry(const char *key, const T &aDefault) const;
@ -251,7 +268,10 @@ public:
* @see writeEntry(), deleteEntry(), hasKey()
*/
QVariant readEntry(const QString &key, const QVariant &aDefault) const;
/** Overload for readEntry(const QString&, const QVariant&) */
/**
* Overload for readEntry(const QString&, const QVariant&) const
* @param key name of key, encoded in UTF-8
*/
QVariant readEntry(const char *key, const QVariant &aDefault) const;
/**
@ -266,12 +286,18 @@ public:
* @see readPathEntry(), writeEntry(), deleteEntry(), hasKey()
*/
QString readEntry(const QString &key, const QString &aDefault) const;
/** Overload for readEntry(const QString&, const QString&) */
/**
* Overload for readEntry(const QString&, const QString&) const
* @param key name of key, encoded in UTF-8
*/
QString readEntry(const char *key, const QString &aDefault) const;
/** Overload for readEntry(const QString&, const QString&) */
/** Overload for readEntry(const QString&, const QString&) const */
QString readEntry(const QString &key, const char *aDefault = nullptr) const;
/** Overload for readEntry(const QString&, const QString&) */
/**
* Overload for readEntry(const QString&, const QString&) const
* @param key name of key, encoded in UTF-8
*/
QString readEntry(const char *key, const char *aDefault = nullptr) const;
/**
@ -283,7 +309,10 @@ public:
* readEntry(const char*, const QList<T>&) const
*/
QVariantList readEntry(const QString &key, const QVariantList &aDefault) const;
/** Overload for readEntry(const QString&, const QVariantList&) */
/**
* Overload for readEntry(const QString&, const QVariantList&) const
* @param key name of key, encoded in UTF-8
*/
QVariantList readEntry(const char *key, const QVariantList &aDefault) const;
/**
@ -296,7 +325,10 @@ public:
* @see readXdgListEntry(), writeEntry(), deleteEntry(), hasKey()
*/
QStringList readEntry(const QString &key, const QStringList &aDefault) const;
/** Overload for readEntry(const QString&, const QStringList&) */
/**
* Overload for readEntry(const QString&, const QStringList&) const
* @param key name of key, encoded in UTF-8
*/
QStringList readEntry(const char *key, const QStringList &aDefault) const;
/**
@ -313,7 +345,10 @@ public:
{
return readEntry(key.toUtf8().constData(), aDefault);
}
/** Overload for readEntry(const QString&, const QList<T>&) */
/**
* Overload for readEntry<T>(const QString&, const QList<T>&) const
* @param key name of key, encoded in UTF-8
*/
template<typename T>
QList<T> readEntry(const char *key, const QList<T> &aDefault) const;
@ -328,8 +363,11 @@ public:
* @see readEntry(const QString&, const QStringList&) const
*/
QStringList readXdgListEntry(const QString &pKey, const QStringList &aDefault = QStringList()) const;
/** Overload for readXdgListEntry(const QString&, const QStringList&) */
QStringList readXdgListEntry(const char *pKey, const QStringList &aDefault = QStringList()) const;
/**
* Overload for readXdgListEntry(const QString&, const QStringList&) const
* @param key name of key, encoded in UTF-8
*/
QStringList readXdgListEntry(const char *key, const QStringList &aDefault = QStringList()) const;
/**
* Reads a path
@ -343,7 +381,10 @@ public:
* @return The value for this key. Can be QString() if @p aDefault is null.
*/
QString readPathEntry(const QString &pKey, const QString &aDefault) const;
/** Overload for readPathEntry(const QString&, const QString&) */
/**
* Overload for readPathEntry(const QString&, const QString&) const
* @param key name of key, encoded in UTF-8
*/
QString readPathEntry(const char *key, const QString &aDefault) const;
/**
@ -358,7 +399,10 @@ public:
* @return the list, or @p aDefault if the key does not exist
*/
QStringList readPathEntry(const QString &pKey, const QStringList &aDefault) const;
/** Overload for readPathEntry(const QString&, const QStringList&) */
/**
* Overload for readPathEntry(const QString&, const QStringList&) const
* @param key name of key, encoded in UTF-8
*/
QStringList readPathEntry(const char *key, const QStringList &aDefault) const;
/**
@ -372,7 +416,10 @@ public:
*/
QString readEntryUntranslated(const QString &pKey,
const QString &aDefault = QString()) const;
/** Overload for readEntryUntranslated(const QString&, const QString&) */
/**
* Overload for readEntryUntranslated(const QString&, const QString&) const
* @param key name of key, encoded in UTF-8
*/
QString readEntryUntranslated(const char *key,
const QString &aDefault = QString()) const;
@ -387,30 +434,45 @@ public:
*/
void writeEntry(const QString &key, const QVariant &value,
WriteConfigFlags pFlags = Normal);
/** Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags) */
/**
* Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)
* @param key name of key, encoded in UTF-8
*/
void writeEntry(const char *key, const QVariant &value,
WriteConfigFlags pFlags = Normal);
/** Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags) */
void writeEntry(const QString &key, const QString &value,
WriteConfigFlags pFlags = Normal);
/** Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags) */
/**
* Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)
* @param key name of key, encoded in UTF-8
*/
void writeEntry(const char *key, const QString &value,
WriteConfigFlags pFlags = Normal);
/** Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags) */
void writeEntry(const QString &key, const QByteArray &value,
WriteConfigFlags pFlags = Normal);
/** Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags) */
/**
* Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)
* @param key name of key, encoded in UTF-8
*/
void writeEntry(const char *key, const QByteArray &value,
WriteConfigFlags pFlags = Normal);
/** Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags) */
void writeEntry(const QString &key, const char *value, WriteConfigFlags pFlags = Normal);
/** Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags) */
/**
* Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)
* @param key name of key, encoded in UTF-8
*/
void writeEntry(const char *key, const char *value, WriteConfigFlags pFlags = Normal);
/** Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags) */
/**
* Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)
* @param key name of key, encoded in UTF-8
*/
template <typename T>
void writeEntry(const char *key, const T &value, WriteConfigFlags pFlags = Normal);
/** Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags) */
@ -423,14 +485,20 @@ public:
/** Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags) */
void writeEntry(const QString &key, const QStringList &value,
WriteConfigFlags pFlags = Normal);
/** Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags) */
/**
* Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)
* @param key name of key, encoded in UTF-8
*/
void writeEntry(const char *key, const QStringList &value,
WriteConfigFlags pFlags = Normal);
/** Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags) */
void writeEntry(const QString &key, const QVariantList &value,
WriteConfigFlags pFlags = Normal);
/** Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags) */
/**
* Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)
* @param key name of key, encoded in UTF-8
*/
void writeEntry(const char *key, const QVariantList &value,
WriteConfigFlags pFlags = Normal);
@ -440,7 +508,10 @@ public:
{
writeEntry(key.toUtf8().constData(), value, pFlags);
}
/** Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags) */
/**
* Overload for writeEntry(const QString&, const QVariant&, WriteConfigFlags)
* @param key name of key, encoded in UTF-8
*/
template <typename T>
void writeEntry(const char *key, const QList<T> &value, WriteConfigFlags pFlags = Normal);
@ -456,8 +527,11 @@ public:
*/
void writeXdgListEntry(const QString &pKey, const QStringList &value,
WriteConfigFlags pFlags = Normal);
/** Overload for writeXdgListEntry(const QString&, const QStringList&, WriteConfigFlags) */
void writeXdgListEntry(const char *pKey, const QStringList &value,
/**
* Overload for writeXdgListEntry(const QString&, const QStringList&, WriteConfigFlags)
* @param key name of key, encoded in UTF-8
*/
void writeXdgListEntry(const char *key, const QStringList &value,
WriteConfigFlags pFlags = Normal);
/**
@ -475,8 +549,11 @@ public:
*/
void writePathEntry(const QString &pKey, const QString &path,
WriteConfigFlags pFlags = Normal);
/** Overload for writePathEntry(const QString&, const QString&, WriteConfigFlags) */
void writePathEntry(const char *pKey, const QString &path,
/**
* Overload for writePathEntry(const QString&, const QString&, WriteConfigFlags)
* @param key name of key, encoded in UTF-8
*/
void writePathEntry(const char *Key, const QString &path,
WriteConfigFlags pFlags = Normal);
/**
@ -494,8 +571,11 @@ public:
*/
void writePathEntry(const QString &pKey, const QStringList &value,
WriteConfigFlags pFlags = Normal);
/** Overload for writePathEntry(const QString&, const QStringList&, WriteConfigFlags) */
void writePathEntry(const char *pKey, const QStringList &value,
/**
* Overload for writePathEntry(const QString&, const QStringList&, WriteConfigFlags)
* @param key name of key, encoded in UTF-8
*/
void writePathEntry(const char *key, const QStringList &value,
WriteConfigFlags pFlags = Normal);
/**
@ -509,8 +589,11 @@ public:
* @see deleteGroup(), readEntry(), writeEntry()
*/
void deleteEntry(const QString &pKey, WriteConfigFlags pFlags = Normal);
/** Overload for deleteEntry(const QString&, WriteConfigFlags) */
void deleteEntry(const char *pKey, WriteConfigFlags pFlags = Normal);
/**
* Overload for deleteEntry(const QString&, WriteConfigFlags)
* @param key name of key, encoded in UTF-8
*/
void deleteEntry(const char *key, WriteConfigFlags pFlags = Normal);
/**
* Checks whether the key has an entry in this group
@ -528,7 +611,10 @@ public:
* @see readEntry()
*/
bool hasKey(const QString &key) const;
/** Overload for hasKey(const QString&) const */
/**
* Overload for hasKey(const QString&) const
* @param key name of key, encoded in UTF-8
*/
bool hasKey(const char *key) const;
/**
@ -549,7 +635,10 @@ public:
* group object, @c true otherwise
*/
bool isEntryImmutable(const QString &key) const;
/** Overload for isEntryImmutable(const QString&) const */
/**
* Overload for isEntryImmutable(const QString&) const
* @param key name of key, encoded in UTF-8
*/
bool isEntryImmutable(const char *key) const;
/**
@ -572,9 +661,16 @@ public:
void revertToDefault(const QString &key);
void revertToDefault(const QString &key, WriteConfigFlags pFlag);
/** Overload for revertToDefault(const QString&) */
// TODO KF6 merge with the other one
/**
* Overload for revertToDefault(const QString&)
* @param key name of key, encoded in UTF-8
*/
void revertToDefault(const char *key);
/**
* Overload for revertToDefault(const QString&, WriteConfigFlags)
* @param key name of key, encoded in UTF-8
*/
void revertToDefault(const char *key, WriteConfigFlags pFlag);
/**
@ -605,7 +701,10 @@ public:
* for @p key in this group, @c false otherwise
*/
bool hasDefault(const QString &key) const;
/** Overload for hasDefault(const QString&) const */
/**
* Overload for hasDefault(const QString&) const
* @param key name of key, encoded in UTF-8
*/
bool hasDefault(const char *key) const;
/**

2
src/core/kconfigwatcher.h
Unescape View File

@ -50,7 +50,7 @@ Q_SIGNALS:
* The config will be reloaded before this signal is emitted
*
* @arg group the config group that has changed
* @arg names a list of entries that have changed within that group
* @arg names a list of entries that have changed within that group (UTF-8 encoded)
*/
void configChanged(const KConfigGroup &group, const QByteArrayList &names);

Write Preview
Loading…
Cancel
Save