Configuration
Adding user configured settings to your widget
Configuration Intro
Every widget by default has a configure action when you right click the widget called MyWidget Settings...
. By default it will contain a form to set a global shortcut to activate your widget.
contents/config/main.xml
main.xml
is where you define the properties that will be serialized into ~/.config/plasma-org.kde.plasma.desktop-appletsrc
. All properties will be accessible with plasmoid.configuration.variableName
regardless of what 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 hexadecimal 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 separated list of Strings
I've listed the more common use cases. More can be found in KConfigXT's documentation.
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:
contents/config/main.xml
contents/config/config.qml
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. {{< /section-left >}} {{< section-right >}}
contents/config/config.qml
contents/ui/configGeneral.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.
contents/ui/configGeneral.qml
configPage.cfg_variableName
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
.
contents/ui/configGeneral.qml
CheckBox - Boolean
A CheckBox is used for boolean on/off values.
contents/config/main.xml
contents/ui/configGeneral.qml
SpinBox - Integer
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).
contents/config/main.xml
contents/ui/configGeneral.qml
SpinBox - Double/Real
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).
contents/config/main.xml
If you really want to use QtQuick.Controls 2.0
, look at Zren's libconfig/SpinBox.qml for an example on implementing the decimals
property.
contents/ui/configGeneral.qml
TextField - String/Text
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.
contents/config/main.xml
contents/ui/configGeneral.qml
TextArea - Multi-Line String/Text
A TextArea is used for paragraphs of text. You will also want to look at the base TextEdit for more properties.
contents/config/main.xml
contents/ui/configGeneral.qml
ColorButton - Color
KDE Frameworks has ColorButton
which provides a preview of the selected color and will open QtQuick's ColorDialog
for selecting a color.
contents/config/main.xml
I personally don't recommend using the Color
data type in main.xml
if you want the default color to be 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:
Unfortunately KDE Framework's ColorButton
doesn't easily support this pattern as it stores the value in a QML color
property which will read the empty string and cast it as the default color #000000
(black). I worked around this issue in the [No-Apply Control Library]({{< ref "#no-apply-control-library" >}})'s libconfig/ColorField.qml
. I used a TextField
to store the value as a string, and displayed the default color scheme color as placeholderText
.
contents/ui/configGeneral.qml
FileDialog - Path
When we need to store a filepath in the config, we should use the Path
or PathList
config type. It will substitute /home/user/...
with $HOME/...
. To properly layout the file selector, we need a RowLayout
with a TextField
and Button
which opens a FileDialog
. We can specify the default folder the dialog opens to with FileDialog
's shortcuts
property (eg: shortcuts.pictures
).
Note that we place the Kirigami.FormData.label
in the RowLayout
as it is the direct child of Kirigami.FormLayout
.
contents/config/main.xml
contents/ui/configGeneral.qml
IconDialog - Icon
KQuickAddons.IconDialog
makes it easy to search and preview icons.
See the [configurable icon example]({{< ref "examples.md#configurable-icon" >}}) for an example of KQuickAddons.IconDialog based on the Application Launcher's (aka kickoff) icon selector code.
Assigning to plasmoid.configuration.varName
You can also assign directly to plasmoid.configuration.variableName
if necessary in the configuration 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 whether this is a pro or con.
contents/ui/configGeneral.qml
Configuration Examples
To learn by example, we can look at a couple widgets:
Application Launcher
No-Apply Control Library
Zren has written a few files that apply the above pattern of skipping "Apply" and updating right after you change the value.
https://github.com/Zren/plasma-applet-lib/tree/master/package/contents/ui/libconfig
libconfig/CheckBox.qml for on/off booleans values.
libconfig/ColorField.qml for use with a
String
orColor
config data type. If you use use aString
data type, you can treat an empty string as a certain color theme color. Eg:libconfig/ComboBox.qml is useful for creating enums using the
String
config data type. KConfig comes with a enum datatype as well, but you have to either use hardcoded integers (with comments), or declare the enum in your QML code and keep it in sync. String comparison is less efficient but is easier to program with.FontFamily.qml inherits
ComboBox.qml
and is populated with all available fonts.
libconfig/IconField.qml based on the Application Launcher icon selector.
libconfig/RadioButtonGroup.qml takes a similar model as
ComboBox.qml
but will display the options asRadioButton
.libconfig/SpinBox.qml for Integer or Real numbers.
libconfig/TextAlign.qml for use with an
Int
config data type. It has your typical 4 buttons for left/center/right/justify alignment. It serializes theText.AlignHCenter
enum.TextFormat.qml is used to toggle bold, italic, underline, and embeds the text alignment. For use with 3
Bool
config keys and 1Int
config key (used for the embeddedTextAlign.qml
).
libconfig/TextArea.qml for a string with multiple lines of text.
TextAreaStringList.qml overloads
TextArea.qml
'svalueToText(value)
andtextToValue(text)
functions to treat a new line as the separator for theStringList
type.
libconfig/TextField.qml for a single line of text.
contents/ui/libconfig/CheckBox.qml
contents/ui/configGeneral.qml
Last updated