Plasma's QML API

A rundown of the QML types shipped in KDE Frameworks

Intro

KDE Frameworks ships with a number of useful extensions to Qt's QML. The API documentation 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 available on GitLab.

PlasmaComponents Controls

QML ships with various controls, like CheckBox, RadioButton, ComboBox (dropdown menu), SpinBox, Slider, TextField, TextArea, Button, ToolButton. 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 Qt Quick Controls 2 components with defaults adapted to fit into Plasma widgets. Because PlasmaComponents 3 inherits from Qt Quick Controls 2, they have the same API, so the Qt documentation can be followed. For Plasma's specific behaviour changes, you can read the QML source code for each control in:

plasma-framework/src/declarativeimports/plasmacomponents3/

Removed in Plasma 6.0: PlasmaComponents 2 was used in Plasma 5. It used the older Qt Quick Controls 1.

Label

Labels 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 Label.qml source code.

contents/ui/main.qml

import QtQuick 2.0
import org.kde.plasma.components 3.0 as PlasmaComponents3

PlasmaComponents3.Label {
    text: i18n("Hello World")
}

CheckBox - Toggle

For a simple toggle, QML ships with CheckBox. For Plasma's specific changes, you can read the QML source code at:

contents/ui/main.qml

RadioButton - Multiple Choice

For multiple choices, QML ships with RadioButton. For Plasma's specific changes, you can read the QML source code at:

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

ComboBox - Multiple Choice

For multiple choices, QML also ships with ComboBox (dropdown menu). For Plasma's specific changes, you can read the QML source code at:

Note that ComboBox.valueRole and ComboBox.currentValue was introduced in Qt 5.14. Ubuntu 20.04 only has Qt 5.12 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.

contents/ui/main.qml

Slider - Numbers

To control Integer or Real numbers, QML ships with SpinBox and Slider. For Plasma's specific changes, you can read the QML source code at:

contents/ui/main.qml

SpinBox - Numbers

To control Integer or Real numbers, QML ships with SpinBox and Slider. For Plasma's specific changes, you can read the QML source code at:

contents/ui/main.qml

TextField, TextArea - Input

To enter text, QML ships with TextField and TextArea. For Plasma's specific changes, you can read the QML source code for each:

contents/ui/main.qml

contents/ui/main.qml

Button, ToolButton

For buttons, QML ships with Button and the flat ToolButton version. For Plasma's specific changes, you can read the QML source code for each:

contents/ui/main.qml

contents/ui/main.qml

ScrollView

To add a scrollbar to manage overflow, QML ships with ScrollView. For Plasma's specific changes, you can read the QML source code at:

contents/ui/main.qml

BusyIndicator

This draws widgets/busywidget.svg from the Plasma Style and spins it. If animation speed is Instant in System Settings, it will not rotate.

PlasmaExtras

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.

Heading, Paragraph

To be consistent with elsewhere in Plasma, Plasma ships with a couple different Label/Text types with preset default sizes. The first one is Heading for subsections of texts and the second one is Paragraph. Both wraps by default with Layout.fillWidth: true.

Screenshot Paragraph and Heading

contents/ui/main.qml

PlasmaCore

  • The very useful Theme and Units singletons.

  • A number of enums listed in Types.

  • Icon for drawing icons.

  • SvgItem, Svg and FrameSvgItem for drawing SVGs coloured with the Plasma Style color palette.

  • DataSource for connecting to a Plasma DataEngine.

See the API docs for the full list of types in PlasmaCore. You can also skim the generated .../core/plugins.qmltypes file.

PlasmaCore.Theme

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 full list of PlasmaCore.Theme color properties can be found in the QuickTheme class definition: plasma-framework/src/declarativeimports/core/quicktheme.h

The QuickTheme class extends Plasma::Theme which also contains:

  • PlasmaCore.Theme.defaultFont font

  • PlasmaCore.Theme.palette palette

  • PlasmaCore.Theme.smallestFont font

  • PlasmaCore.Theme.styleSheet string

  • PlasmaCore.Theme.themeName string

  • PlasmaCore.Theme.useGlobalSettings bool

  • PlasmaCore.Theme.wallpaperPath string

PlasmaCore.Units.devicePixelRatio

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.devicePixelRatio = QScreen::logicalDotsPerInchX / 96 (Primary Screen)

  • PlasmaCore.Units.smallSpacing = max(2, gridUnit/4)

  • PlasmaCore.Units.largeSpacing = gridUnit

  • PlasmaCore.Units.gridUnit (width of the capital letter M)

Note that Kirigami.Units does not use the exact same logic as PlasmaCore.Units.

PlasmaCore.Units.iconSizes

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

PlasmaCore.Units.shortDuration

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

PreviousQMLNextWidget Properties

Last updated