Developer
MyWidget Settings...
. By default it will contain a form to set a global shortcut to activate your widget.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 numberDouble
for a double precision floating point number (Real)String
for a string of characters to represent textColor
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 StringsI’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
}
<?xml version="1.0" encoding="UTF-8"?>
<kcfg xmlns="http://www.kde.org/standards/kcfg/1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.kde.org/standards/kcfg/1.0 http://www.kde.org/standards/kcfg/1.0/kcfg.xsd">
<kcfgfile name=""/>
<group name="General">
<entry name="variableName" type="Bool">
<default>true</default>
</entry>
<entry name="integerExample" type="Int">
<default>6</default>
</entry>
<entry name="floatingPointExample" type="Double">
<default>3.1459</default>
</entry>
<entry name="textExample" type="String">
<default>Hello World</default>
</entry>
<entry name="listExample" type="StringList">
<default>First Item,Second Item,Third Item</default>
</entry>
<entry name="colorExample" type="Color">
<default>#336699</default>
</entry>
</group>
<group name="AnotherGroup">
<entry name="secondGroupExample" type="Bool">
<default>false</default>
</entry>
</group>
</kcfg>
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. Kirigami labels are optional, so you do not need to use them for CheckBoxes which have their own labels on the right.
import QtQuick 2.0
import QtQuick.Controls 2.5
import QtQuick.Layouts 1.12
import org.kde.kirigami 2.4 as Kirigami
Kirigami.FormLayout {
id: page
property alias cfg_showLabel: showLabel.checked
property alias cfg_showIcon: showIcon.checked
property alias cfg_labelText: labelText.text
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
}
}
plasmoid.configuration.variableName
if necessary in the configruation window or anywhere else in your widget. If you do this in the configuration page, you will skip the “apply” process and the property will be applied right away. I leave this up to the reader wither this is a pro or con.// 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
}
}
To learn by example, we can look at a couple widgets:
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.
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
}
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.ConfigComboBox.qml
and is populated with all available fonts.ConfigComboBox.qml
but displays the enum values differently.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.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'
}
}