KQuickConfigModule Class

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

• Header: #include <KQuickConfigModule>
• Since: Qt 6.0
• CMake: find_package(KF6 REQUIRED COMPONENTS KCMUtilsQuick)
target_link_libraries(mytarget PRIVATE KF6::KCMUtilsQuick)
• Inherits: KAbstractConfigModule
• Inherited By: KQuickManagedConfigModule

List of all members, including inherited members

#Properties

• columnWidth : int
• currentIndex : int
• [read-only] depth : int
• [read-only] mainUi : QQuickItem* const

#Public Functions

• int columnWidth() const
• int currentIndex() const
• int depth() const
• std::shared_ptr<QQmlEngine> engine() const
• QString errorString() const
• QQuickItem *mainUi()
• void setColumnWidth(int width)
• void setCurrentIndex(int index)
• QQuickItem *subPage(int index) const

#Public Slots

• void pop()
• void push(const QString &fileName, const QVariantMap &initialProperties = QVariantMap())
• void push(QQuickItem *item)
• QQuickItem *takeLast()

#Signals

• void columnWidthChanged(int width)
• void currentIndexChanged(int index)
• void depthChanged(int index)
• void mainUiReady()
• void pagePushed(QQuickItem *page)
• void pageRemoved()

#Protected Functions

• KQuickConfigModule(QObject *parent, const KPluginMetaData &metaData)

#Detailed Description

Configuration modules are realized as plugins that are dynamically loaded.

All the necessary glue logic and the GUI bells and whistles are provided by the control center and must not concern the module author.

To write a config module, you have to create a C++ plugin and an accompanying QML user interface.

To allow KCMUtils to load your ConfigModule subclass, you must create a KPluginFactory implementation.

#include <KPluginFactory>

K_PLUGIN_CLASS_WITH_JSON(MyConfigModule, "yourmetadata.json")

The constructor of the ConfigModule then looks like this:

YourConfigModule::YourConfigModule(QObject *parent, const KPluginMetaData &metaData)
  : KQuickConfigModule(parent, metaData)
{
}

The QML part must be in the KPackage format, installed under share/kpackage/kcms.

The package must have the same name as the plugin filename, to be installed by CMake with the command:

kpackage_install_package(packagedir kcm_yourconfigmodule kcms)

The "packagedir" is the subdirectory in the source tree where the package sources are located, and "kcm_yourconfigmodule" is id of the plugin. Finally "kcms" is the literal string "kcms", so that the package is installed as a configuration module (and not some other kind of package).

The QML part can access all the properties of ConfigModule (together with the properties defined in its subclass) by accessing to the global object "kcm", or with the import of "org.kde.kcmutils" the ConfigModule attached property.

import QtQuick
import QtQuick.Controls as QQC2
import org.kde.kcmutils as KCMUtils
import org.kde.kirigami as Kirigami

Item {
    // implicit size will be used as initial size when loaded in kcmshell6
    implicitWidth: Kirigami.Units.gridUnit * 30
    implicitHeight: Kirigami.Units.gridUnit * 30

    KCMUtils.ConfigModule.buttons: KCMUtils.ConfigModule.Help | KCMUtils.ConfigModule.Apply

    QQC2.Label {
        // The following two bindings are equivalent:
        text: kcm.needsSave
        enabled: KCMUtils.ConfigModule.needsSave
    }
}

See https://develop.kde.org/docs/features/configuration/kcm/ for more detailed documentation.

See also KPackage::Package

#Property Documentation

#columnWidth : int

Access functions:

• int columnWidth() const
• void setColumnWidth(int width)

Notifier signal:

• void columnWidthChanged(int width)

#currentIndex : int

Access functions:

• int currentIndex() const
• void setCurrentIndex(int index)

Notifier signal:

• void currentIndexChanged(int index)

#[read-only] depth : int

Access functions:

• int depth() const

Notifier signal:

• void depthChanged(int index)

#[read-only] mainUi : QQuickItem* const

Access functions:

• QQuickItem *mainUi()

#Member Function Documentation

#[explicit protected] KQuickConfigModule::KQuickConfigModule(QObject *parent, const KPluginMetaData &metaData)

Base class for all QtQuick config modules.

Creates a new KQuickConfigModule with the given metaData as a child of parent. Use KQuickConfigModuleLoader to instantiate this class.

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

#int KQuickConfigModule::columnWidth() const

Returns the width the kcm wants in column mode.

If a columnWidth is valid ( > 0 ) and less than the systemsettings' view width, more than one will be visible at once, and the first page will be a sidebar to the last page pushed. As default, this is -1 which will make the shell always show only one page at a time.

Note: Getter function for property columnWidth.

See also setColumnWidth()

#[signal] void KQuickConfigModule::columnWidthChanged(int width)

Emitted when the wanted column width of the KCM changes.

Note: Notifier signal for property columnWidth.

#int KQuickConfigModule::currentIndex() const

Returns the index of the page this KCM should display.

Note: Getter function for property currentIndex.

See also setCurrentIndex()

#[signal] void KQuickConfigModule::currentIndexChanged(int index)

Emitted when the index of the current page changed.

Note: Notifier signal for property currentIndex.

#int KQuickConfigModule::depth() const

Returns how many pages this kcm has.

It is guaranteed to be at least 1 (the main ui) plus how many times a new page has been pushed without pop.

Note: Getter function for property depth.

#[signal] void KQuickConfigModule::depthChanged(int index)

Emitted when the number of pages changed, and so their index.

Note: Notifier signal for property depth.

#std::shared_ptr<QQmlEngine> KQuickConfigModule::engine() const

Returns the qml engine that built the main config UI.

#QString KQuickConfigModule::errorString() const

The error string in case the mainUi failed to load.

#QQuickItem *KQuickConfigModule::mainUi()

Returns the main UI for this configuration module.

It's a QQuickItem coming from the QML package named the same as the KAboutData's component name for this config module.

Normally, ui/main.qml will be loaded from the qrc baked into the plugin. However, if the PLASMA_PLATFORM environmental variable is set, the module will try to load a platform-specific QML file as its mainUi starting point.

For example:

environment has set export PLASMA_PLATFORM=phone:handset

The module will try to find main_phone.qml, then main_handset.qml, then main.qml. The first file that is found will be used as mainUi. If none is found and main.qml doesn't exist, the module is broken and an error will be displayed.

Note: Getter function for property mainUi.

#[signal] void KQuickConfigModule::mainUiReady()

Emitted when the main Ui has loaded successfully and mainUi() is available.

#[signal] void KQuickConfigModule::pagePushed(QQuickItem *page)

Emitted when a new sub page is pushed.

#[signal] void KQuickConfigModule::pageRemoved()

Emitted when a sub page is popped.

#[slot] void KQuickConfigModule::pop()

Pop the last page of the KCM hierarchy, the page is destroyed.

#[slot] void KQuickConfigModule::push(const QString &fileName, const QVariantMap &initialProperties = QVariantMap())

Push a new sub page with the given fileName with optional initialProperties in the KCM hierarchy: pages will be seen as a Kirigami PageRow.

Note: This slot is overloaded. To connect to this slot:

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        kQuickConfigModule, qOverload<const QString &, const QVariantMap &>(&KQuickConfigModule::push));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        kQuickConfigModule, [receiver = kQuickConfigModule](const QString &fileName, const QVariantMap &initialProperties) { receiver->push(fileName, initialProperties); });

For more examples and approaches, see connecting to overloaded slots.

#[slot] void KQuickConfigModule::push(QQuickItem *item)

Push a given QQuick item as a new sub page in the KCM hierarchy.

Note: This slot is overloaded. To connect to this slot:

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        kQuickConfigModule, qOverload<QQuickItem *>(&KQuickConfigModule::push));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        kQuickConfigModule, [receiver = kQuickConfigModule](QQuickItem *item) { receiver->push(item); });

For more examples and approaches, see connecting to overloaded slots.

#void KQuickConfigModule::setColumnWidth(int width)

Sets the column width we want.

Note: Setter function for property columnWidth.

See also columnWidth()

#void KQuickConfigModule::setCurrentIndex(int index)

Sets the current page index this KCM should display.

Note: Setter function for property currentIndex.

See also currentIndex()

#QQuickItem *KQuickConfigModule::subPage(int index) const

Returns a subpage at a given depth index.

Note: This does not include the mainUi. That is, a depth of 2 is a mainUi and one subPage at index 0.

#[slot] QQuickItem *KQuickConfigModule::takeLast()

Remove and return the last page of the KCM hierarchy.

The popped page won't be deleted, it's the caller's responsibility to manage the lifetime of the returned item.

Returns the last page if any, nullptr otherwise.