Contents

KCoreConfigSkeleton Class

Class for handling preferences settings for an application. More...

Header: #include <KCoreConfigSkeleton>
CMake: find_package(KF6 REQUIRED COMPONENTS Config)
target_link_libraries(mytarget PRIVATE KF6::ConfigCore)
Inherited By:

KConfigSkeleton

Public Types

class ItemBool
class ItemDateTime
class ItemDouble
class ItemEnum
class ItemInt
class ItemIntList
class ItemLongLong
class ItemPassword
class ItemPath
class ItemPathList
class ItemPoint
class ItemPointF
class ItemProperty
class ItemRect
class ItemRectF
class ItemSize
class ItemSizeF
class ItemString
class ItemStringList
(since 6.16) class ItemTime
class ItemUInt
class ItemULongLong
class ItemUrl
class ItemUrlList
enum DisambiguateConstructor { IsStdUniqPtr }

Public Functions

KCoreConfigSkeleton(KSharedConfig::Ptr config, QObject *parent = nullptr)
KCoreConfigSkeleton(const QString &configname = QString(), QObject *parent = nullptr)
(since 6.23) KCoreConfigSkeleton(std::unique_ptr<KConfig> config, KCoreConfigSkeleton::DisambiguateConstructor value, QObject *parent = nullptr)
void addItem(KConfigSkeletonItem *item, const QString &name = QString())
KCoreConfigSkeleton::ItemBool *addItemBool(const QString &name, bool &reference, bool defaultValue = false, const QString &key = QString())
KCoreConfigSkeleton::ItemDateTime *addItemDateTime(const QString &name, QDateTime &reference, const QDateTime &defaultValue = QDateTime(), const QString &key = QString())
KCoreConfigSkeleton::ItemDouble *addItemDouble(const QString &name, double &reference, double defaultValue = 0.0, const QString &key = QString())
KCoreConfigSkeleton::ItemInt *addItemInt(const QString &name, qint32 &reference, qint32 defaultValue = 0, const QString &key = QString())
KCoreConfigSkeleton::ItemIntList *addItemIntList(const QString &name, QList<int> &reference, const QList<int> &defaultValue = QList<int>(), const QString &key = QString())
KCoreConfigSkeleton::ItemLongLong *addItemLongLong(const QString &name, qint64 &reference, qint64 defaultValue = 0, const QString &key = QString())
KCoreConfigSkeleton::ItemPassword *addItemPassword(const QString &name, QString &reference, const QString &defaultValue = QLatin1String(""), const QString &key = QString())
KCoreConfigSkeleton::ItemPath *addItemPath(const QString &name, QString &reference, const QString &defaultValue = QLatin1String(""), const QString &key = QString())
KCoreConfigSkeleton::ItemPoint *addItemPoint(const QString &name, QPoint &reference, const QPoint &defaultValue = QPoint(), const QString &key = QString())
KCoreConfigSkeleton::ItemPointF *addItemPointF(const QString &name, QPointF &reference, const QPointF &defaultValue = QPointF(), const QString &key = QString())
KCoreConfigSkeleton::ItemProperty *addItemProperty(const QString &name, QVariant &reference, const QVariant &defaultValue = QVariant(), const QString &key = QString())
KCoreConfigSkeleton::ItemRect *addItemRect(const QString &name, QRect &reference, const QRect &defaultValue = QRect(), const QString &key = QString())
KCoreConfigSkeleton::ItemRectF *addItemRectF(const QString &name, QRectF &reference, const QRectF &defaultValue = QRectF(), const QString &key = QString())
KCoreConfigSkeleton::ItemSize *addItemSize(const QString &name, QSize &reference, const QSize &defaultValue = QSize(), const QString &key = QString())
KCoreConfigSkeleton::ItemSizeF *addItemSizeF(const QString &name, QSizeF &reference, const QSizeF &defaultValue = QSizeF(), const QString &key = QString())
KCoreConfigSkeleton::ItemString *addItemString(const QString &name, QString &reference, const QString &defaultValue = QLatin1String(""), const QString &key = QString())
KCoreConfigSkeleton::ItemStringList *addItemStringList(const QString &name, QStringList &reference, const QStringList &defaultValue = QStringList(), const QString &key = QString())
(since 6.16) KCoreConfigSkeleton::ItemTime *addItemTime(const QString &name, QTime &reference, QTime defaultValue = QTime(), const QString &key = QString())
KCoreConfigSkeleton::ItemUInt *addItemUInt(const QString &name, quint32 &reference, quint32 defaultValue = 0, const QString &key = QString())
KCoreConfigSkeleton::ItemULongLong *addItemULongLong(const QString &name, quint64 &reference, quint64 defaultValue = 0, const QString &key = QString())
void clearItems()
KConfig *config()
const KConfig *config() const
QString currentGroup() const
KConfigSkeletonItem *findItem(const QString &name) const
bool isDefaults() const
bool isImmutable(const QString &name) const
bool isSaveNeeded() const
KConfigSkeletonItem::List items() const
void load()
void read()
void removeItem(const QString &name)
(since 6.23) void setConfig(std::unique_ptr<KConfig> config)
void setCurrentGroup(const QString &group)
virtual void setDefaults()
void setSharedConfig(KSharedConfig::Ptr pConfig)
KSharedConfig::Ptr sharedConfig() const
virtual bool useDefaults(bool b)

Public Slots

bool save()

Signals

void configChanged()

Protected Functions

virtual void usrRead()
virtual bool usrSave()
virtual void usrSetDefaults()
virtual bool usrUseDefaults(bool b)

Detailed Description

This class provides an interface to settings that can be used to create preferences UIs. Use KConfigSkeleton if you need GUI types like QColor and QFont as well.

Preferences items can be registered by the addItem() function corresponding to the data type of the setting. KCoreConfigSkeleton then handles reading and writing of config files and setting of default values.

Normally you will subclass KCoreConfigSkeleton, add data members for the preferences settings and register the members in the constructor of the subclass.

Example:

class MyPrefs : public KCoreConfigSkeleton
{
  public:
    MyPrefs()
    {
      setCurrentGroup("MyGroup");
      addItemBool("MySetting1", mMyBool, false);
      addItemPoint("MySetting2", mMyPoint, QPoint(100, 200));

      setCurrentGroup("MyOtherGroup");
      addItemDouble("MySetting3", mMyDouble, 3.14);
    }

    bool mMyBool;
    QPoint mMyPoint;
    double mMyDouble;
}

It might be convenient in many cases to make this subclass of KCoreConfigSkeleton a singleton for global access from all over the application without passing references to the KCoreConfigSkeleton object around.

You can write the data to the configuration file by calling save() and read the data from the configuration file by calling readConfig(). If you want to watch for config changes, use the configChanged() signal.

If you have items which are not covered by the existing addItem() functions you can add customized code for reading, writing and default setting by implementing the functions usrUseDefaults(), usrRead() and usrSave().

Internally preferences settings are stored in instances of subclasses of KConfigSkeletonItem. You can also add KConfigSkeletonItem subclasses for your own types and call the generic addItem() to register them.

In many cases you don't have to write the specific KCoreConfigSkeleton subclasses yourself, but you can use The KDE Configuration Compiler to automatically generate the C++ code from an XML description of the configuration options.

See also KConfigSkeletonItem.

Member Type Documentation

enum KCoreConfigSkeleton::DisambiguateConstructor

It is added to disambiguate with the other constructor otherwise ambiguate in case of default nullptr KCoreConfigSkeleton(KSharedConfig::Ptr(nullptr)) or KCoreConfigSkeleton(std::unique_ptr<KConfig> (nullptr)) with parent = nullptr.

ConstantValue
KCoreConfigSkeleton::IsStdUniqPtr0

Member Function Documentation

[explicit] KCoreConfigSkeleton::KCoreConfigSkeleton(KSharedConfig::Ptr config, QObject *parent = nullptr)

Constructs a KCoreConfigSkeleton object with the given KSharedConfig config and parent.

[explicit] KCoreConfigSkeleton::KCoreConfigSkeleton(const QString &configname = QString(), QObject *parent = nullptr)

Constructs a KCoreConfigSkeleton object with the given configname and parent.

If no name is given, the default config file as returned by KSharedConfig::openConfig() is used.

[explicit, since 6.23] KCoreConfigSkeleton::KCoreConfigSkeleton(std::unique_ptr<KConfig> config, KCoreConfigSkeleton::DisambiguateConstructor value, QObject *parent = nullptr)

Constructs a KCoreConfigSkeleton object with the given KConfig config and parent.

The value must be DisambiguateConstructor::IsStdUniqPtr.

This function was introduced in 6.23.

void KCoreConfigSkeleton::addItem(KConfigSkeletonItem *item, const QString &name = QString())

Registers a custom KConfigSkeletonItem item with a given name.

If name is a null string, take the name from KConfigSkeletonItem::key().

Note: All names must be unique but multiple entries can have the same key if they reside in different groups.

KCoreConfigSkeleton takes ownership of item.

KCoreConfigSkeleton::ItemBool *KCoreConfigSkeleton::addItemBool(const QString &name, bool &reference, bool defaultValue = false, const QString &key = QString())

Registers a bool item with a unique name by passing a reference pointer to the variable and the given defaultValue for the key used in the config file.

If key is a null string, name is used as key.

Returns the created item.

KCoreConfigSkeleton::ItemDateTime *KCoreConfigSkeleton::addItemDateTime(const QString &name, QDateTime &reference, const QDateTime &defaultValue = QDateTime(), const QString &key = QString())

Registers a QDateTime item with a unique name by passing a reference pointer to the variable and the given defaultValue for the key used in the config file.

If key is a null string, name is used as key.

Returns the created item.

KCoreConfigSkeleton::ItemDouble *KCoreConfigSkeleton::addItemDouble(const QString &name, double &reference, double defaultValue = 0.0, const QString &key = QString())

Registers a double item with a unique name by passing a reference pointer to the variable and the given defaultValue for the key used in the config file.

If key is a null string, name is used as key.

Returns the created item.

KCoreConfigSkeleton::ItemInt *KCoreConfigSkeleton::addItemInt(const QString &name, qint32 &reference, qint32 defaultValue = 0, const QString &key = QString())

Registers a qint32 item with a unique name by passing a reference pointer to the variable and the given defaultValue for the key used in the config file.

If key is a null string, name is used as key.

Returns the created item.

KCoreConfigSkeleton::ItemIntList *KCoreConfigSkeleton::addItemIntList(const QString &name, QList<int> &reference, const QList<int> &defaultValue = QList<int>(), const QString &key = QString())

Registers an int list item with a unique name by passing a reference pointer to the variable and the given defaultValue for the key used in the config file.

If key is a null string, name is used as key.

Returns the created item.

KCoreConfigSkeleton::ItemLongLong *KCoreConfigSkeleton::addItemLongLong(const QString &name, qint64 &reference, qint64 defaultValue = 0, const QString &key = QString())

Registers a qint64 item with a unique name by passing a reference pointer to the variable and the given defaultValue for the key used in the config file.

If key is a null string, name is used as key.

Returns the created item.

KCoreConfigSkeleton::ItemPassword *KCoreConfigSkeleton::addItemPassword(const QString &name, QString &reference, const QString &defaultValue = QLatin1String(""), const QString &key = QString())

Registers a password item of type QString with a unique name by passing a reference pointer to the variable and the given defaultValue for the key used in the config file.

If key is a null string, name is used as key.

The string value is written encrypted to the config file.

Returns the created item.

Note: The current encryption scheme is very weak.

KCoreConfigSkeleton::ItemPath *KCoreConfigSkeleton::addItemPath(const QString &name, QString &reference, const QString &defaultValue = QLatin1String(""), const QString &key = QString())

Registers a path item of type QString with a unique name by passing a reference pointer to the variable and the given defaultValue for the key used in the config file.

If key is a null string, name is used as key.

The string value is interpreted as a path. This means dollar expansion is activated for this value, so that for example $HOME gets expanded.

Returns the created item.

KCoreConfigSkeleton::ItemPoint *KCoreConfigSkeleton::addItemPoint(const QString &name, QPoint &reference, const QPoint &defaultValue = QPoint(), const QString &key = QString())

Registers a QPoint item with a unique name by passing a reference pointer to the variable and the given defaultValue for the key used in the config file.

If key is a null string, name is used as key.

Returns the created item.

KCoreConfigSkeleton::ItemPointF *KCoreConfigSkeleton::addItemPointF(const QString &name, QPointF &reference, const QPointF &defaultValue = QPointF(), const QString &key = QString())

Registers a QPointF item with a unique name by passing a reference pointer to the variable and the given defaultValue for the key used in the config file.

If key is a null string, name is used as key.

Returns the created item.

KCoreConfigSkeleton::ItemProperty *KCoreConfigSkeleton::addItemProperty(const QString &name, QVariant &reference, const QVariant &defaultValue = QVariant(), const QString &key = QString())

Registers a property item of type QVariant with a unique name by passing a reference pointer to the variable and the given defaultValue for the key used in the config file.

If key is a null string, name is used as key.

Returns the created item.

Note: The following QVariant types are allowed: String, StringList, Font, Point, PointF, Rect, RectF, Size, SizeF, Color, Int, UInt, Bool, Double, DateTime and Date.

KCoreConfigSkeleton::ItemRect *KCoreConfigSkeleton::addItemRect(const QString &name, QRect &reference, const QRect &defaultValue = QRect(), const QString &key = QString())

Registers a QRect item with a unique name by passing a reference pointer to the variable and the given defaultValue for the key used in the config file.

If key is a null string, name is used as key.

Returns the created item.

KCoreConfigSkeleton::ItemRectF *KCoreConfigSkeleton::addItemRectF(const QString &name, QRectF &reference, const QRectF &defaultValue = QRectF(), const QString &key = QString())

Registers a QRectF item with a unique name by passing a reference pointer to the variable and the given defaultValue for the key used in the config file.

If key is a null string, name is used as key.

Returns the created item.

KCoreConfigSkeleton::ItemSize *KCoreConfigSkeleton::addItemSize(const QString &name, QSize &reference, const QSize &defaultValue = QSize(), const QString &key = QString())

Registers a QSize item with a unique name by passing a reference pointer to the variable and the given defaultValue for the key used in the config file.

If key is a null string, name is used as key.

Returns the created item.

KCoreConfigSkeleton::ItemSizeF *KCoreConfigSkeleton::addItemSizeF(const QString &name, QSizeF &reference, const QSizeF &defaultValue = QSizeF(), const QString &key = QString())

Registers a QSizeF item with a unique name by passing a reference pointer to the variable and the given defaultValue for the key used in the config file.

If key is a null string, name is used as key.

Returns the created item.

KCoreConfigSkeleton::ItemString *KCoreConfigSkeleton::addItemString(const QString &name, QString &reference, const QString &defaultValue = QLatin1String(""), const QString &key = QString())

Registers a string item with a unique name by passing a reference pointer to the variable and the given defaultValue for the key used in the config file.

If key is a null string, name is used as key.

Returns the created item.

KCoreConfigSkeleton::ItemStringList *KCoreConfigSkeleton::addItemStringList(const QString &name, QStringList &reference, const QStringList &defaultValue = QStringList(), const QString &key = QString())

Registers a string list item with a unique name by passing a reference pointer to the variable and the given defaultValue for the key used in the config file.

If key is a null string, name is used as key.

Returns the created item.

[since 6.16] KCoreConfigSkeleton::ItemTime *KCoreConfigSkeleton::addItemTime(const QString &name, QTime &reference, QTime defaultValue = QTime(), const QString &key = QString())

Registers a QTime item with a unique name by passing a reference pointer to the variable and the given defaultValue for the key used in the config file.

If key is a null string, name is used as key.

Returns the created item.

This function was introduced in 6.16.

KCoreConfigSkeleton::ItemUInt *KCoreConfigSkeleton::addItemUInt(const QString &name, quint32 &reference, quint32 defaultValue = 0, const QString &key = QString())

Registers a quint32 item with a unique name by passing a reference pointer to the variable and the given defaultValue for the key used in the config file.

If key is a null string, name is used as key.

Returns the created item.

KCoreConfigSkeleton::ItemULongLong *KCoreConfigSkeleton::addItemULongLong(const QString &name, quint64 &reference, quint64 defaultValue = 0, const QString &key = QString())

Registers a quint64 item with a unique name by passing a reference pointer to the variable and the given defaultValue for the key used in the config file.

If key is a null string, name is used as key.

Returns the created item.

void KCoreConfigSkeleton::clearItems()

Removes and deletes all items.

KConfig *KCoreConfigSkeleton::config()

Returns the KConfig object used for reading and writing the settings.

See also setConfig().

const KConfig *KCoreConfigSkeleton::config() const

Returns the const KConfig object used for reading and writing the settings.

[signal] void KCoreConfigSkeleton::configChanged()

This signal is emitted when the configuration changes.

See also KConfigBase::WriteConfigFlags.

QString KCoreConfigSkeleton::currentGroup() const

Returns the current group used for addItem() calls.

See also setCurrentGroup().

KConfigSkeletonItem *KCoreConfigSkeleton::findItem(const QString &name) const

Looks up an item by name.

bool KCoreConfigSkeleton::isDefaults() const

Returns if all the registered items are set to their default value.

[invokable] bool KCoreConfigSkeleton::isImmutable(const QString &name) const

Returns whether the item with the given name is immutable.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

bool KCoreConfigSkeleton::isSaveNeeded() const

Returns if any registered item has a different value than the previously loaded value.

KConfigSkeletonItem::List KCoreConfigSkeleton::items() const

Returns the list of items managed by this KCoreConfigSkeleton object.

void KCoreConfigSkeleton::load()

Reads preferences from the config file. All registered items are set to the values read from disk.

This method calls usrRead() after reading the settings of the registered items from the KConfig. You can override usrRead() in derived classes if you have special requirements.

void KCoreConfigSkeleton::read()

Reads preferences from the KConfig object. This method assumes that the KConfig object was previously loaded, i.e. it uses the in-memory values from KConfig without reloading from disk.

This method calls usrRead() after reading the settings of the registered items from the KConfig. You can override usrRead() in derived classes if you have special requirements.

void KCoreConfigSkeleton::removeItem(const QString &name)

Removes and deletes an item by name.

[slot] bool KCoreConfigSkeleton::save()

Writes preferences to the config file. The values of all registered items are written to disk and returns true upon success.

This method calls usrSave() after writing the settings from the registered items to the KConfig.

You can override usrSave() in derived classes if you have special requirements.

[since 6.23] void KCoreConfigSkeleton::setConfig(std::unique_ptr<KConfig> config)

Sets the KConfig config object used for reading and writing the settings.

This function was introduced in 6.23.

See also config().

void KCoreConfigSkeleton::setCurrentGroup(const QString &group)

Set the config file group for subsequent addItem() calls.

It is valid until setCurrentGroup() is called with a new argument. Call this before you add any items.

The default value is "No Group".

See also currentGroup().

[virtual] void KCoreConfigSkeleton::setDefaults()

Sets all registered items to their default values.

This method calls usrSetDefaults() after setting the defaults for the registered items. You can override usrSetDefaults() in derived classes if you have special requirements.

If you need more fine-grained control of setting the default values of the registered items you can override setDefaults() in a derived class.

See also isDefaults().

void KCoreConfigSkeleton::setSharedConfig(KSharedConfig::Ptr pConfig)

Sets the KSharedConfig pConfig object used for reading and writing the settings.

See also sharedConfig().

KSharedConfig::Ptr KCoreConfigSkeleton::sharedConfig() const

Returns the KSharedConfig object used for reading and writing the settings.

This might return null if the internal config is a std::unique_ptr<KConfig>.

See also setSharedConfig(), config(), and KCoreConfigSkeleton::DisambiguateConstructor.

[virtual] bool KCoreConfigSkeleton::useDefaults(bool b)

Changes the state of this object to reflect the default values (b = true) or replaces the default values with the current values (b = false).

This method is implemented by usrUseDefaults(), which can be overridden in derived classes if you have special requirements and can call usrUseDefaults() directly.

If you don't have control whether useDefaults() or usrUseDefaults() is called override useDefaults() directly.

Returns the state prior to this call.

[virtual protected] void KCoreConfigSkeleton::usrRead()

Performs the actual reading of the configuration file.

Override in derived classes to read special config values.

Called from read().

[virtual protected] bool KCoreConfigSkeleton::usrSave()

Performs the actual writing of the configuration file and returns true upon success.

Override in derived classes to write special config values.

Called from save().

[virtual protected] void KCoreConfigSkeleton::usrSetDefaults()

Performs the actual setting of default values.

Override in derived classes to set special default values.

Called from setDefaults().

[virtual protected] bool KCoreConfigSkeleton::usrUseDefaults(bool b)

Changes the state of this object to reflect the default values (b = true) or replaces the default values with the current values (b = false).

Called from useDefaults().

Implemented by subclasses that use special defaults.

Returns the state prior to this call.