kconfiggroup.h

Go to the documentation of this file.

/*
   This file is part of the KDE libraries
   Copyright (c) 2006, 2007 Thomas Braxton <kde.braxton@gmail.com>
   Copyright (c) 1999 Preston Brown <pbrown@kde.org>
   Copyright (c) 1997 Matthias Kalle Dalheimer <kalle@kde.org>
   Copyright (c) 2001 Waldo Bastian <bastian@kde.org>

   This library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Library General Public
   License as published by the Free Software Foundation; either
   version 2 of the License, or (at your option) any later version.

   This library is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Library General Public License for more details.

   You should have received a copy of the GNU Library General Public License
   along with this library; see the file COPYING.LIB.  If not, write to
   the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
   Boston, MA 02110-1301, USA.
*/

#ifndef KCONFIGGROUP_H
#define KCONFIGGROUP_H

#include "kconfigbase.h"

#include <kdecore_export.h>

#include <QtCore/QExplicitlySharedDataPointer>
#include <QtCore/QVariant>
#include <QtCore/QStringList>

class KConfig;
class KConfigGroupPrivate;
class KSharedConfig;
template <typename T> class KSharedPtr;
typedef KSharedPtr<KSharedConfig> KSharedConfigPtr;

class KDECORE_EXPORT KConfigGroup : public KConfigBase
{
public:
    KConfigGroup();

    KConfigGroup(KConfigBase *master, const QString &group);
    KConfigGroup(KConfigBase *master, const char *group);

    KConfigGroup(const KConfigBase *master, const QString &group);
    KConfigGroup(const KConfigBase *master, const char *group);

    KConfigGroup(const KSharedConfigPtr &master, const QString &group);
    KConfigGroup(const KSharedConfigPtr &master, const char *group);

    KConfigGroup(const KConfigGroup &);
    KConfigGroup &operator=(const KConfigGroup &);

    ~KConfigGroup();

    bool isValid() const;

    QString name() const;

    bool exists() const;

    void sync();

    void markAsClean();

    AccessMode accessMode() const;

    KConfig* config();
    const KConfig* config() const;

#ifndef KDE_NO_DEPRECATED
    KDE_DEPRECATED void changeGroup(const QString &group);
#endif

#ifndef KDE_NO_DEPRECATED
    KDE_DEPRECATED void changeGroup(const char *group);
#endif

    void copyTo(KConfigBase *other, WriteConfigFlags pFlags = Normal) const;

    void reparent(KConfigBase *parent, WriteConfigFlags pFlags = Normal);

    KConfigGroup parent() const;

    QStringList groupList() const;

    QStringList keyList() const;

    void deleteGroup(WriteConfigFlags pFlags = Normal);
    using KConfigBase::deleteGroup;

    template <typename T>
        inline T readEntry(const QString &key, const T &aDefault) const
            { return readCheck(key.toUtf8().constData(), aDefault); }
    template <typename T>
        inline T readEntry(const char *key, const T &aDefault) const
            { return readCheck(key, aDefault); }

    QVariant readEntry(const QString &key, const QVariant &aDefault) const;
    QVariant readEntry(const char *key, const QVariant &aDefault) const;

    QString readEntry(const QString &key, const QString &aDefault) const;
    QString readEntry(const char *key, const QString &aDefault) const;

    QString readEntry(const QString &key, const char *aDefault = 0) const;
    QString readEntry(const char *key, const char *aDefault = 0) const;

    QVariantList readEntry(const QString &key, const QVariantList &aDefault) const;
    QVariantList readEntry(const char *key, const QVariantList &aDefault) const;

    QStringList readEntry(const QString &key, const QStringList &aDefault) const;
    QStringList readEntry(const char *key, const QStringList &aDefault) const;

    template<typename T>
        inline QList<T> readEntry(const QString &key, const QList<T> &aDefault) const
            { return readListCheck(key.toUtf8().constData(), aDefault); }
    template<typename T>
        inline QList<T> readEntry(const char *key, const QList<T> &aDefault) const
            { return readListCheck(key, aDefault); }

    QStringList readXdgListEntry(const QString &pKey, const QStringList &aDefault = QStringList()) const;
    QStringList readXdgListEntry(const char *pKey, const QStringList &aDefault = QStringList()) const;

    QString readPathEntry(const QString &pKey, const QString &aDefault) const;
    QString readPathEntry(const char *key, const QString &aDefault) const;

    QStringList readPathEntry(const QString &pKey, const QStringList &aDefault) const;
    QStringList readPathEntry(const char *key, const QStringList &aDefault) const;

    QString readEntryUntranslated(const QString &pKey,
                                  const QString &aDefault = QString()) const;
    QString readEntryUntranslated(const char *key,
                                  const QString &aDefault = QString()) const;

    void writeEntry(const QString &key, const QVariant &value,
                    WriteConfigFlags pFlags = Normal);
    void writeEntry(const char *key, const QVariant &value,
                    WriteConfigFlags pFlags = Normal);

    void writeEntry(const QString &key, const QString &value,
                    WriteConfigFlags pFlags = Normal);
    void writeEntry(const char *key, const QString &value,
                    WriteConfigFlags pFlags = Normal);

    void writeEntry(const QString &key, const QByteArray &value,
                    WriteConfigFlags pFlags = Normal);
    void writeEntry(const char *key, const QByteArray &value,
                    WriteConfigFlags pFlags = Normal);

    void writeEntry(const QString &key, const char *value, WriteConfigFlags pFlags = Normal);
    void writeEntry(const char *key, const char *value, WriteConfigFlags pFlags = Normal);

    template <typename T>
        inline void writeEntry(const char *key, const T &value, WriteConfigFlags pFlags = Normal)
            { writeCheck( key, value, pFlags ); }
    template <typename T>
        inline void writeEntry(const QString &key, const T &value, WriteConfigFlags pFlags = Normal)
            { writeCheck( key.toUtf8().constData(), value, pFlags ); }

    void writeEntry(const QString &key, const QStringList &value,
                    WriteConfigFlags pFlags = Normal);
    void writeEntry(const char *key, const QStringList &value,
                    WriteConfigFlags pFlags = Normal);

    void writeEntry(const QString &key, const QVariantList &value,
                    WriteConfigFlags pFlags = Normal);
    void writeEntry(const char *key, const QVariantList &value,
                    WriteConfigFlags pFlags = Normal);

    template <typename T>
        inline void writeEntry(const QString &key, const QList<T> &value, WriteConfigFlags pFlags = Normal)
            { writeListCheck( key.toUtf8().constData(), value, pFlags ); }
    template <typename T>
        inline void writeEntry(const char *key, const QList<T> &value, WriteConfigFlags pFlags = Normal)
            { writeListCheck( key, value, pFlags ); }

    void writeXdgListEntry(const QString &pKey, const QStringList &value,
                           WriteConfigFlags pFlags = Normal);
    void writeXdgListEntry(const char *pKey, const QStringList &value,
                           WriteConfigFlags pFlags = Normal);

    void writePathEntry(const QString &pKey, const QString &path,
                        WriteConfigFlags pFlags = Normal);
    void writePathEntry(const char *pKey, const QString &path,
                        WriteConfigFlags pFlags = Normal);

    void writePathEntry(const QString &pKey, const QStringList &value,
                        WriteConfigFlags pFlags = Normal);
    void writePathEntry(const char *pKey, const QStringList &value,
                        WriteConfigFlags pFlags = Normal);

    void deleteEntry(const QString &pKey, WriteConfigFlags pFlags = Normal);
    void deleteEntry(const char *pKey, WriteConfigFlags pFlags = Normal);

    bool hasKey(const QString &key) const;
    bool hasKey(const char *key) const;

    bool isImmutable() const;

    bool isEntryImmutable(const QString &key) const;
    bool isEntryImmutable(const char *key) const;

    void revertToDefault(const QString &key);
    void revertToDefault(const char* key);

    bool hasDefault(const QString &key) const;
    bool hasDefault(const char *key) const;

    QMap<QString, QString> entryMap() const;

protected:
    bool hasGroupImpl(const QByteArray &group) const;
    KConfigGroup groupImpl(const QByteArray &b);
    const KConfigGroup groupImpl(const QByteArray &b) const;
    void deleteGroupImpl(const QByteArray &group, WriteConfigFlags flags);
    bool isGroupImmutableImpl(const QByteArray &aGroup) const;

private:
    QExplicitlySharedDataPointer<KConfigGroupPrivate> d;

    template<typename T>
    inline T readCheck(const char *key, const T &defaultValue) const;

    template<typename T>
    inline QList<T> readListCheck(const char *key, const QList<T> &defaultValue) const;

    template<typename T>
    inline void writeCheck(const char *key, const T &value, WriteConfigFlags pFlags);

    template<typename T>
    inline void writeListCheck(const char *key, const QList<T> &value, WriteConfigFlags pFlags);

    friend class KConfigGroupPrivate;

    static QVariant convertToQVariant(const char *pKey, const QByteArray &value, const QVariant &aDefault);
    friend class KServicePrivate; // XXX yeah, ugly^5
};

#define KCONFIGGROUP_ENUMERATOR_ERROR(ENUM) \
"The Qt MetaObject system does not seem to know about \"" ENUM \
"\" please use Q_ENUMS or Q_FLAGS to register it."

#define KCONFIGGROUP_DECLARE_ENUM_QOBJECT(Class, Enum)                     \
inline Class::Enum readEntry(const KConfigGroup& group, const char* key, const Class::Enum& def) \
{                                                                          \
const QMetaObject* M_obj = &Class::staticMetaObject;                       \
const int M_index = M_obj->indexOfEnumerator(#Enum);                       \
kFatal(M_index == -1) << KCONFIGGROUP_ENUMERATOR_ERROR(#Enum) << endl;     \
const QMetaEnum M_enum = M_obj->enumerator(M_index);                       \
const QByteArray M_data = group.readEntry(key, QByteArray(M_enum.valueToKey(def)));\
return static_cast<Class::Enum>(M_enum.keyToValue(M_data.constData()));    \
}                                                                          \
inline void writeEntry(KConfigGroup& group, const char* key, const Class::Enum& value, KConfigBase::WriteConfigFlags flags = KConfigBase::Normal)\
{                                                                          \
const QMetaObject* M_obj = &Class::staticMetaObject;                       \
const int M_index = M_obj->indexOfEnumerator(#Enum);                       \
kFatal(M_index == -1) << KCONFIGGROUP_ENUMERATOR_ERROR(#Enum) << endl;     \
const QMetaEnum M_enum = M_obj->enumerator(M_index);                       \
group.writeEntry(key, QByteArray(M_enum.valueToKey(value)), flags);              \
}

#define KCONFIGGROUP_DECLARE_FLAGS_QOBJECT(Class, Flags)                    \
inline Class::Flags readEntry(const KConfigGroup& group, const char* key, const Class::Flags& def) \
{                                                                           \
const QMetaObject* M_obj = &Class::staticMetaObject;                        \
const int M_index = M_obj->indexOfEnumerator(#Flags);                       \
kFatal(M_index == -1) << KCONFIGGROUP_ENUMERATOR_ERROR(#Flags) << endl;     \
const QMetaEnum M_enum = M_obj->enumerator(M_index);                        \
const QByteArray M_data = group.readEntry(key, QByteArray(M_enum.valueToKeys(def)));\
return static_cast<Class::Flags>(M_enum.keysToValue(M_data.constData()));   \
}                                                                           \
inline void writeEntry(KConfigGroup& group, const char* key, const Class::Flags& value, KConfigBase::WriteConfigFlags flags = KConfigBase::Normal)\
{                                                                           \
const QMetaObject* M_obj = &Class::staticMetaObject;                        \
const int M_index = M_obj->indexOfEnumerator(#Flags);                       \
kFatal(M_index == -1) << KCONFIGGROUP_ENUMERATOR_ERROR(#Flags) << endl;     \
const QMetaEnum M_enum = M_obj->enumerator(M_index);                        \
group.writeEntry(key, QByteArray(M_enum.valueToKeys(value)), flags);              \
}

#include "conversion_check.h"

template <typename T>
T KConfigGroup::readCheck(const char *key, const T &defaultValue) const
{
  ConversionCheck::to_QVariant<T>();
  return qvariant_cast<T>(readEntry(key, qVariantFromValue(defaultValue)));
}

template <typename T>
QList<T> KConfigGroup::readListCheck(const char *key, const QList<T> &defaultValue) const
{
  ConversionCheck::to_QVariant<T>();
  ConversionCheck::to_QString<T>();

  QVariantList data;

  Q_FOREACH(const T& value, defaultValue)
    data.append(qVariantFromValue(value));

  QList<T> list;
  Q_FOREACH (const QVariant &value, readEntry<QVariantList>(key, data)) {
    Q_ASSERT(qVariantCanConvert<T>(value));
    list.append(qvariant_cast<T>(value));
  }

  return list;
}

template <typename T>
void KConfigGroup::writeCheck(const char *key, const T &value,
                              WriteConfigFlags pFlags)
{
    ConversionCheck::to_QVariant<T>();
    writeEntry(key, qVariantFromValue(value), pFlags);
}

template <typename T>
void KConfigGroup::writeListCheck(const char *key, const QList<T> &list,
                                  WriteConfigFlags pFlags)
{
  ConversionCheck::to_QVariant<T>();
  ConversionCheck::to_QString<T>();
  QVariantList data;
  Q_FOREACH(const T &value, list) {
    data.append(qVariantFromValue(value));
  }

  writeEntry(key, data, pFlags);
}

#endif // KCONFIGGROUP_H