Contents

KCModule Class

The base class for QWidgets configuration modules. More...

Header: #include <KCModule>
CMake: find_package(KF6 REQUIRED COMPONENTS KCMUtils)
target_link_libraries(mytarget PRIVATE KF6::KCMUtils)
Since: 6.0
Inherits: KAbstractConfigModule

Public Functions

KCModule(QWidget *parent, const KPluginMetaData &data)
virtual ~KCModule() override
QList<KConfigDialogManager *> configs() const
void markAsChanged()
virtual QWidget *widget()

Protected Functions

KCModule(QObject *parent)
KCModule(QObject *parent, const KPluginMetaData &data)
KConfigDialogManager *addConfig(KCoreConfigSkeleton *config, QWidget *widget)
bool managedWidgetChangeState() const
bool managedWidgetDefaultState() const
void unmanagedWidgetChangeState(bool)
void unmanagedWidgetDefaultState(bool)

Protected Slots

void widgetChanged()

Detailed Description

Configuration modules are loaded as plugins.

The module in principle is a simple widget displaying the item to be changed. The module has a very small interface.

To write a config module, you have to create a library that contains a factory class like the following:

#include <KPluginFactory>

K_PLUGIN_CLASS_WITH_JSON(MyKCModule, "mykcmodule.json")

The constructor of the KCModule then looks like this:

YourKCModule::YourKCModule(QWidget *parent, const KPluginMetaData &data)
  : KCModule(parent, data)
{
    // KCModule does not directly extend QWidget due to ambiguity with KAbstractConfigModule
    // Because of this, you need to call widget() to get the parent widget
    auto label = new QLabel(widget());
    label->setText(QStringLiteral("Demo Text"));
}

This KCM can be loaded in a KCMultiDialog of kcmshell6.

Member Function Documentation

[explicit protected] KCModule::KCModule(QObject *parent)

Utility constructor for creating a KCModule that is embedded, for example in a KPluginWidget.

This constructor should not be used for KCMs that are part launched in systemsettings!

Note: Do not emit changed signals here, since they are not yet connected to any slot.

parent The KCModule parent.

[explicit protected] KCModule::KCModule(QObject *parent, const KPluginMetaData &data)

Utility overload to avoid having to take both parent and parentWidget KCModuleLoader::loadModule enforces the parent to be a QWidget anyway.

parent The KCModule parent.

data The JSON metadata of the KCModule.

[explicit] KCModule::KCModule(QWidget *parent, const KPluginMetaData &data)

Base class for all QWidgets configuration modules.

parent The KCModule parent.

data The JSON metadata of the KCModule.

Note: Do not emit changed signals here, since they are not yet connected to any slot.

[override virtual noexcept] KCModule::~KCModule()

Destroys the module.

[protected] KConfigDialogManager *KCModule::addConfig(KCoreConfigSkeleton *config, QWidget *widget)

Adds a KCoreConfigskeleton config to watch the widget widget.

This function is useful if you need to handle multiple configuration files.

Returns a pointer to the KCoreConfigDialogManager in use.

config The KCoreConfigSkeleton to use.

widget The widget to watch.

QList<KConfigDialogManager *> KCModule::configs() const

Returns a list of KConfigDialogManager's in use, if any.

[protected] bool KCModule::managedWidgetChangeState() const

Returns the changed state of automatically managed widgets in this dialog.

[protected] bool KCModule::managedWidgetDefaultState() const

Returns the defaulted state of automatically managed widgets in this dialog.

void KCModule::markAsChanged()

Utility function that marks the KCM as changed.

[protected] void KCModule::unmanagedWidgetChangeState(bool)

Call this method when your manually managed widgets change state between "changed" and "not changed".

[protected] void KCModule::unmanagedWidgetDefaultState(bool)

Call this method when your manually managed widgets change state between "defaulted" and "not defaulted".

[virtual] QWidget *KCModule::widget()

Get the associated widget that can be embedded.

The returned widget should be used as a parent for widgets you create

Note: Overwriting this function should not be necessary for consumers!

[protected slot] void KCModule::widgetChanged()

A managed widget was changed, the widget settings and the current settings are compared, and a corresponding needsSaveChanged() signal is emitted.