Plasma's QML API
A rundown of the QML types shipped in KDE Frameworks
Last updated
A rundown of the QML types shipped in KDE Frameworks
Last updated
KDE Frameworks ships with a number of useful extensions to Qt's QML. The is a good start if you need to know what a specific property does. If you want to browse any of the sources easier, it's also .
QML ships with various controls, like , , (dropdown menu), , , , , , . Plasma extends these controls to style them using the SVGs from the Plasma Style. It also assigns a number of default settings like setting the text color to follow the panel's color scheme.
PlasmaComponents 3 is a QML library that extends the with defaults adapted to fit into Plasma widgets. Because PlasmaComponents 3 inherits from Qt Quick Controls 2, they have the same API, so the can be followed. For Plasma's specific behaviour changes, you can read the QML source code for each control in:
Removed in Plasma 6.0: was used in Plasma 5. It used the older .
are used for displaying text to the user. Plasma's Label are assigned a number of defaults. One thing is it sets the text color to follow the panel's color scheme.
For the specifics, you can read the .
contents/ui/main.qml
contents/ui/main.qml
Note that the [KDE Human Interface Guidelines]({{< ref "/hig/getting_input" >}}) suggest using a ComboBox when there are more than 3 options.
contents/ui/main.qml
contents/ui/main.qml
contents/ui/main.qml
contents/ui/main.qml
contents/ui/main.qml
contents/ui/main.qml
contents/ui/main.qml
contents/ui/main.qml
contents/ui/main.qml
This draws widgets/busywidget.svg from the Plasma Style and spins it. If animation speed is Instant in System Settings, it will not rotate.
To be consistent with elsewhere in Plasma, Plasma ships with a couple of special components. These components have their own API and are particularly helpful when creating a Plasma Widget.
You will need to import PlasmaExtras to use them.
contents/ui/main.qml
The very useful Theme and Units singletons.
PlasmaCore.Theme contains the [Plasma Style]({{< ref "../theme/_index.md" >}}) color palette.
PlasmaCore.Theme.textColor
PlasmaCore.Theme.highlightColor
PlasmaCore.Theme.highlightedTextColor
PlasmaCore.Theme.backgroundColor
PlasmaCore.Theme.linkColor
PlasmaCore.Theme.visitedLinkColor
PlasmaCore.Theme.positiveTextColor
PlasmaCore.Theme.neutralTextColor
PlasmaCore.Theme.negativeTextColor
PlasmaCore.Theme.disabledTextColor
There is also properties for the various color groups using a prefix.
PlasmaCore.Theme.buttonTextColor
PlasmaCore.Theme.viewTextColor
PlasmaCore.Theme.complementaryTextColor
PlasmaCore.Theme.headerTextColor
The QuickTheme class extends Plasma::Theme which also contains:
In order to scale an Item by display scaling to support HiDPI monitors, you will need to multiply a pixel value by PlasmaCore.Units.devicePixelRatio. Plasma also ships with a few preset values for consistent spacing throughout Plasma.
PlasmaCore.Units.smallSpacing = max(2, gridUnit/4)
PlasmaCore.Units.largeSpacing = gridUnit
PlasmaCore.Units.gridUnit (width of the capital letter M)
PlasmaCore.Units.iconSizes is scaled by DPI.
PlasmaCore.Units.iconSizes.small = 16px
PlasmaCore.Units.iconSizes.smallMedium = 22px
PlasmaCore.Units.iconSizes.medium = 32px
PlasmaCore.Units.iconSizes.large = 48px
PlasmaCore.Units.iconSizes.huge = 64px
PlasmaCore.Units.iconSizes.enormous = 128px
These properties are scaled by the Animation Speed in System Settings.
PlasmaCore.Units.veryShortDuration = 50ms
PlasmaCore.Units.shortDuration = 100ms
PlasmaCore.Units.longDuration = 200ms
PlasmaCore.Units.veryLongDuration = 400ms
This property is a hardcoded value and shouldn't be used for animations. Instead, it can be used to measure how long to wait until the user should be informed of something, or can be used as the limit for how long something should wait before being automatically initiated.
PlasmaCore.Units.humanMoment = 2000ms
For a simple toggle, QML ships with . For Plasma's specific changes, you can read the QML source code at:
For multiple choices, QML ships with . For Plasma's specific changes, you can read the QML source code at:
For multiple choices, QML also ships with (dropdown menu). For Plasma's specific changes, you can read the QML source code at:
Note that and was introduced in Qt 5.14. so you will need to use your own _valueRole and _currentValue properties until Ubuntu 22.04. Make sure to not define a valueRole or currentValue property or it will break when your users upgrade to Qt 5.14.
To control Integer or Real numbers, QML ships with and . For Plasma's specific changes, you can read the QML source code at:
To control Integer or Real numbers, QML ships with and . For Plasma's specific changes, you can read the QML source code at:
To enter text, QML ships with and . For Plasma's specific changes, you can read the QML source code for each:
For buttons, QML ships with and the flat version. For Plasma's specific changes, you can read the QML source code for each:
To add a scrollbar to manage overflow, QML ships with . For Plasma's specific changes, you can read the QML source code at:
To be consistent with elsewhere in Plasma, Plasma ships with a couple different Label/Text types with preset default sizes. The first one is for subsections of texts and the second one is . Both wraps by default with Layout.fillWidth: true.
A number of enums listed in .
for drawing icons.
, and for drawing SVGs coloured with the Plasma Style color palette.
for connecting to a Plasma DataEngine.
for the full list of types in PlasmaCore. You can also skim the generated file.
The full list of PlasmaCore.Theme color properties can be found in the QuickTheme class definition:
PlasmaCore.Theme.defaultFont
PlasmaCore.Theme.palette
PlasmaCore.Theme.smallestFont
PlasmaCore.Theme.styleSheet
PlasmaCore.Theme.themeName
PlasmaCore.Theme.useGlobalSettings
PlasmaCore.Theme.wallpaperPath
PlasmaCore.Units.devicePixelRatio = / 96 (Primary Screen)
Note that does not use the exact same logic as .
