Pages

API Documentation

• User Documentation
• Developer Documentation
• API Documentation

Search API documentation

On this page

KCModule Class

The base class for QWidgets configuration modules. This class was introduced in Qt 6.0. More...

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

List of all members, including inherited members

#Public Functions

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

#Public Slots

• void widgetChanged()

#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)

#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.