Configuration

main.xml is where you define the properties that will be serialized into ~/.config/plasma-org.kde.plasma.desktop-appletsrc. All properties will be accesible with plasmoid.configuration.variableName reguardless of was group it’s in.

KConfig has a variety of data types:

• Int for an Integer number
• Double for a double precision floating point number (Real)
• String for a string of characters to represent text
• Color for a hexidecimal color. The color defaults to #000000 (black) if the default is left empty.
• Path is a string that is specially treated as a file-path. In particular paths in the home directory are prefixed with $HOME when being stored in the configuration file.
• StringList for a comma seperated list of Strings

I’ve listed the more common usecases. More can be found on the wiki:
https://techbase.kde.org/Development/Tutorials/Using_KConfig_XT

I personally don’t recommend using Color if you want to default to a color from the color scheme (eg: PlasmaCore.ColorScope.textColor). I would instead suggest using a String that is empty by default. You can then use the following in the QML:

<entry name="labelColor" type="String">
    <default></default>
</entry>

PlasmaComponents.Label {
    color: plasmoid.configruation.labelColor || PlasmaCore.ColorScope.textColor
}

config.qml is where we define the tabs in the configuration window.

We import the ConfigModel and ConfigCategory, and define the tab name, icon, and qml file that will be loaded.

import QtQuick 2.0
import org.kde.plasma.configuration 2.0

ConfigModel {
    ConfigCategory {
        name: i18n("General")
        icon: "configure"
        source: "configGeneral.qml"
    }
    ConfigCategory {
        name: i18n("Another Tab")
        icon: "color-management"
        source: "configAnotherTab.qml"
    }
}

configGeneral.qml is where we can place all the checkboxes and textboxes.

Please note that your should not use PlasmaComponents.* controls in the config window, as those are styled and colored for the panel. The normal QtQuick.Controls are styled using your application window style + colors.

Kirigami.FormLayout is used to layout the controls in the center of the page. The Kirigami.FormData.label attached property is used to place labels in front of the controls. CheckBoxes have their own labels, so you don’t need to set a Kirigami label. You can use it for CheckBoxes as a section seperator though. You do not need to set a Kirigami label.

import QtQuick 2.0
import QtQuick.Controls 2.5
import QtQuick.Layouts 1.12
import org.kde.kirigami 2.4 as Kirigami

Item {
    id: page
    width: childrenRect.width
    height: childrenRect.height

    property alias cfg_showLabel: showLabel.checked
    property alias cfg_showIcon: showIcon.checked
    property alias cfg_labelText: labelText.text

    Kirigami.FormLayout {
        anchors.left: parent.left
        anchors.right: parent.right

        CheckBox {
            id: showLabel
            Kirigami.FormData.label: i18n("Section:")
            text: i18n("Show label")
        }
        CheckBox {
            id: showIcon
            text: i18n("Show icon")
        }
        TextField {
            id: labelText
            Kirigami.FormData.label: i18n("Label:")
            placeholderText: i18n("Placeholder")
        }
    }
}

By default, all values are copied to the top level Item of the file prefixed with cfg_ like page.cfg_variableName. This is so the user can hit discard or apply the changes. You will need to define each cfg_ property so you can bind the value with a QML control.

Note that you can use a property alias to a control’s property like checkBox.checked or textField.text.

// configGeneral.qml
import QtQuick 2.0
import QtQuick.Controls 2.5
import QtQuick.Layouts 1.0

Item {
    id: page
    property alias cfg_variableName: variableName.checked

    CheckBox {
        id: variableName
    }
}

A CheckBox is used for boolean on/off values. See the Visual Design Group’s tips on using CheckBoxes.

<!-- config/main.xml -->
<entry name="variableName" type="Bool">
    <default>true</default>
</entry>

// configGeneral.qml
import QtQuick 2.0
import QtQuick.Controls 2.5
import QtQuick.Layouts 1.0

Item {
    id: page
    property alias cfg_variableName: variableName.checked

    CheckBox {
        id: variableName
    }
}

A SpinBox is used for numbers.

If you want decimal places, a QtQuick.Controls 1.0 SpinBox is a little easier to use than the QtQuick.Controls 2.0 version. QtQuickControls1 has a SpinBox.decimals to easily switch from an Integer decimals: 0 to decimals: 3 to represent a Real number (the Double data type).

<!-- config/main.xml -->
<entry name="variableName" type="Int">
    <default>6</default>
</entry>

// configGeneral.qml
import QtQuick 2.0
import QtQuick.Controls 2.5
import QtQuick.Layouts 1.0

Item {
    id: page
    property alias cfg_variableName: variableName.value

    SpinBox {
        id: variableName
    }
}

If you want decimal places, a QtQuick.Controls 1.0 SpinBox is a little easier to use than the QtQuick.Controls 2.0 version. QtControls1 has a SpinBox.decimals property to easily switch from an Integer decimals: 0 to decimals: 3 to represent a Real number (the Double config data type).

<!-- config/main.xml -->
<entry name="variableName" type="Double">
    <default>3.1459</default>
</entry>

// configGeneral.qml
import QtQuick 2.0
import QtQuick.Controls 2.5
import QtQuick.Controls 1.0 as QtControls1
import QtQuick.Layouts 1.0

Item {
    id: page
    property alias cfg_variableName: variableName.value

    QtControls1.SpinBox {
        id: variableName
        decimals: 2
    }
}

A TextField is used for a single line of text. It can be used as a base for many other data types as well. You will also want to look at the base TextInput for more properties.

<!-- config/main.xml -->
<entry name="variableName" type="String">
    <default>Hello World</default>
</entry>

// configGeneral.qml
import QtQuick 2.0
import QtQuick.Controls 2.5
import QtQuick.Layouts 1.0

Item {
    id: page
    property alias cfg_variableName: variableName.text

    TextField {
        id: variableName
    }
}

A TextArea is used for paragraphs of text. You will also want to look at the base TextEdit for more properties.

<!-- config/main.xml -->
<entry name="variableName" type="String">
    <default>Hello World</default>
</entry>

// configGeneral.qml
import QtQuick 2.0
import QtQuick.Controls 2.5
import QtQuick.Layouts 1.0

Item {
    id: page
    property alias cfg_variableName: variableName.value

    TextArea {
        id: variableName
    }
}

// configGeneral.qml
import QtQuick 2.0
import QtQuick.Controls 2.5
import QtQuick.Layouts 1.0

Item {
    id: page

    CheckBox {
        id: variableName
        checked: plasmoid.configuration.variableName
        onCheckedChanged: plasmoid.configuration.variableName = checked
    }
}

I have written a few files that apply the above pattern of skipping “Apply” and updating right after you change the value. It still uses the QtQuick.Controls 1.0 controls at the moment however.

• ConfigCheckBox.qml for on/off booleans values.
• ConfigSpinBox.qml for Integer or Real numbers.
• ConfigString.qml for a single line of text.
• ConfigColor.qml for use with a String or Color config data type. If you use use a String data type, you can treat an empty string as a certain color theme color. Eg:

  ConfigColor {
    configKey: 'labelColor'
    defaultColor: PlasmaCore.ColorScope.textColor
  }
  

• ConfigIcon.qml based on the Application Launcher icon selector.
• ConfigStringList.qml Instead of a TextField, it uses a TextArea using a new line as the seperator.
• ConfigComboBox.qml is useful for creating enums using the String config data type. KConfig comes with a enum datatype as well, but you have to use hardcoded integers (with comments) in your QML code, rather than using strings.
  • ConfigFontFamily.qml inherits ConfigComboBox.qml and is populated with all available fonts.
• ConfigRadioButtonGroup.qml uses a similar model as ConfigComboBox.qml but displays the enum values differently.
• ConfigTextAlign.qml for use with an Int config data type. It has your typical 4 buttons for left/center/right/justify alignment. It serializes the Text.AlignHCenter enum, which is an Integer.
  • ConfigTextFormat.qml is used to config bold, italic, underline, and embeds the text alignment. For use with 3 Bool config keys and 1 Int config key (used for the embeded ConfigTextAlign.qml).

// ConfigCheckBox.qml
import QtQuick 2.0
import QtQuick.Controls 1.0 as QtControls1
import QtQuick.Layouts 1.0

QtControls1.CheckBox {
    id: configCheckBox

    property string configKey: ''
    checked: plasmoid.configuration[configKey]
    onClicked: plasmoid.configuration[configKey] = !plasmoid.configuration[configKey]
}

// configGeneral.qml
import QtQuick 2.0
import QtQuick.Controls 2.5
import QtQuick.Layouts 1.0

Item {
    id: page

    ConfigCheckBox {
        id: variableName
        configKey: 'variableName'
    }
}