The widget QML API

SonicDE's frameworks add a number of QML types to what Qt ships. The API documentation describes each type's properties: see PlasmaComponents, PlasmaExtras, PlasmaCore, Kirigami and KSvg. The sources of the widget components are in sonic-interface-libraries/src/declarativeimports.

The root item of a widget's main.qml must be a PlasmoidItem, as the QML page explains. To stay short, the examples here show only the items that go inside it.

#PlasmaComponents controls

PlasmaComponents is a QML library that extends the Qt Quick Controls with defaults for desktop widgets. Its controls are drawn with the SVGs of the desktop theme, and they follow the color scheme of the panel they are in.

They inherit from Qt Quick Controls and have the same API, so the Qt documentation applies. For the behavior specific to SonicDE, read each control's QML source in plasmacomponents3/.

import org.kde.plasma.components as PlasmaComponents

#Label

A Label displays text to the user. Plasma's Label.qml adds defaults such as a text color that follows the panel's color scheme.

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

#CheckBox

A CheckBox is a simple toggle. Source: CheckBox.qml.

PlasmaComponents.CheckBox {
    text: i18n("Hello World")
    checked: true
}

#RadioButton

A RadioButton offers one of several choices. Source: RadioButton.qml.

With more than three options, the Human Interface Guidelines suggest a ComboBox instead.

import QtQuick.Layouts

ColumnLayout {
    PlasmaComponents.RadioButton {
        text: i18n("Top")
        checked: true
        autoExclusive: true
    }
    PlasmaComponents.RadioButton {
        text: i18n("Bottom")
        autoExclusive: true
    }
}

#ComboBox

A ComboBox is a dropdown menu. Read the selected value from currentValue. Source: ComboBox.qml.

PlasmaComponents.ComboBox {
    textRole: "text"
    valueRole: "value"
    model: [
        { value: "a", text: i18n("A") },
        { value: "b", text: i18n("B") },
        { value: "c", text: i18n("C") },
    ]
}

#Slider

A Slider controls an integer or real number. This example keeps the label next to it wide enough for the largest value, so the slider doesn't change size as the value changes. Source: Slider.qml.

import QtQuick
import QtQuick.Layouts

RowLayout {
    PlasmaComponents.Slider {
        id: slider
        Layout.fillWidth: true
        from: 0
        to: 100
        value: 50
        stepSize: 5
    }
    PlasmaComponents.Label {
        id: sliderValueLabel
        function formatText(value) {
            return i18n("%1%", value)
        }
        text: formatText(slider.value)

        TextMetrics {
            id: textMetrics
            font: sliderValueLabel.font
            text: sliderValueLabel.formatText(slider.to)
        }
        Layout.minimumWidth: textMetrics.width
    }
}

#SpinBox

A SpinBox also controls a number, with buttons and a text field. Source: SpinBox.qml.

import QtQuick.Layouts

RowLayout {
    PlasmaComponents.Label {
        text: i18n("Label:")
        Layout.alignment: Qt.AlignRight
    }
    PlasmaComponents.SpinBox {
        from: 0
        to: 100
        value: 25
        stepSize: 1
    }
}

#TextField and TextArea

TextField enters one line of text and TextArea several. Sources: TextField.qml, TextArea.qml.

import QtQuick.Layouts

RowLayout {
    PlasmaComponents.Label {
        Layout.alignment: Qt.AlignRight
        text: i18n("Name:")
    }
    PlasmaComponents.TextField {
        placeholderText: i18n("Name")
    }
}

PlasmaComponents.TextArea {
    text: "Lorem ipsum\ndolor sit amet,\nconsectetur adipisicing elit"
}

#Button and ToolButton

Button is a regular button and ToolButton its flat version. Sources: Button.qml, ToolButton.qml.

PlasmaComponents.Button {
    icon.name: "view-refresh"
    text: i18n("Refresh")
}

PlasmaComponents.ToolButton {
    icon.name: "view-refresh-symbolic"
    text: i18n("Refresh")
}

#ScrollView

A ScrollView adds a scrollbar to manage overflow. Source: ScrollView.qml.

import QtQuick

PlasmaComponents.ScrollView {
    ListView {
        model: 100
        delegate: PlasmaComponents.CheckBox {
            required property int index
            text: i18n("CheckBox #%1", index + 1)
        }
    }
}

#BusyIndicator

A BusyIndicator draws widgets/busywidget.svg from the desktop theme and spins it. If the animation speed in System Settings is set to instant, it doesn't rotate. Sources: BusyIndicator.qml, the default busywidget.svg.

#PlasmaExtras

PlasmaExtras holds components with an API of their own, made for widgets. Among them are Heading, PlasmoidHeading, Representation, PlaceholderMessage and ExpandableListItem.

import org.kde.plasma.extras as PlasmaExtras

#Heading

PlasmaExtras.Heading is a label with a preset size for its level, wrapped by default. For a block of body text, use a PlasmaComponents.Label with wrapMode: Text.Wrap.

import QtQuick
import QtQuick.Layouts

ColumnLayout {
    spacing: 0

    Repeater {
        model: 5
        PlasmaExtras.Heading {
            required property int index
            Layout.fillWidth: true
            level: index + 1
            text: i18n("Heading level %1", level)
        }
    }

    PlasmaComponents.Label {
        Layout.fillWidth: true
        wrapMode: Text.Wrap
        text: i18n("Lorem ipsum dolor sit amet, consectetur adipiscing elit.")
    }
}

#PlasmaCore

import org.kde.plasma.core as PlasmaCore

PlasmaCore has the widget-level types ToolTipArea, WindowThumbnail, Dialog, AppletPopup and Window, along with the enums of Plasma::Types, such as form factors and screen locations.

Colors, sizes and icons are no longer in PlasmaCore; the porting guide lists what replaced them. They are described below.

#Icons and SVGs

Kirigami.Icon draws icons.

import org.kde.kirigami as Kirigami

Kirigami.Icon {
    source: "view-refresh"
    implicitWidth: Kirigami.Units.iconSizes.small
    implicitHeight: implicitWidth
}

KSvg draws SVGs, colored with the desktop theme's palette: SvgItem one element of an image, FrameSvgItem a resizable frame, and Svg the image itself.

import org.kde.ksvg as KSvg

KSvg.SvgItem {
    imagePath: "widgets/configuration-icons"
    elementId: "configure"
}

KSvg.FrameSvgItem {
    imagePath: "widgets/background"
}

#Kirigami.Theme

Kirigami.Theme holds the current color palette and the fonts.

• Kirigami.Theme.textColor
• Kirigami.Theme.disabledTextColor
• Kirigami.Theme.highlightColor
• Kirigami.Theme.highlightedTextColor
• Kirigami.Theme.backgroundColor
• Kirigami.Theme.alternateBackgroundColor
• Kirigami.Theme.linkColor
• Kirigami.Theme.visitedLinkColor
• Kirigami.Theme.positiveTextColor
• Kirigami.Theme.neutralTextColor
• Kirigami.Theme.negativeTextColor
• Kirigami.Theme.defaultFont
• Kirigami.Theme.smallFont
• Kirigami.Theme.fixedWidthFont

There are no separate properties for the color groups. Instead, an item sets Kirigami.Theme.colorSet to one of View, Window, Button, Selection, Tooltip, Complementary or Header, and Kirigami.Theme.inherit: false to stop following its parent; the same color properties then give the colors of that set. Colors and themes describes this in more detail.

#Kirigami.Units

Kirigami.Units holds preset values, so that widgets stay consistent with the rest of the desktop.

#Spacing

• Kirigami.Units.gridUnit: 18
• Kirigami.Units.smallSpacing: 4
• Kirigami.Units.mediumSpacing: 6
• Kirigami.Units.largeSpacing: 8

These are logical pixels: there is no devicePixelRatio to multiply by, because Qt scales the whole interface for the display. A plain size such as the 4 below scales the same way.

import QtQuick
import QtQuick.Layouts
import org.kde.kirigami as Kirigami

RowLayout {
    spacing: Kirigami.Units.smallSpacing
    Rectangle {
        implicitWidth: 4
        Layout.fillHeight: true
        color: Kirigami.Theme.highlightColor
    }
    PlasmaComponents.Label {
        text: i18n("Label")
    }
}

#Icon sizes

• Kirigami.Units.iconSizes.small: 16
• Kirigami.Units.iconSizes.smallMedium: 22
• Kirigami.Units.iconSizes.medium: 32
• Kirigami.Units.iconSizes.large: 48
• Kirigami.Units.iconSizes.huge: 64
• Kirigami.Units.iconSizes.enormous: 128

iconSizes.sizeForLabels is the icon size that fits the height of the default font, and iconSizes.roundedIconSize(value) rounds a size down to a standard icon size (sizes below 16 or from 64 up stay as they are).

#Durations

These are scaled by the animation speed in System Settings; the values below are at the default speed.

• Kirigami.Units.veryShortDuration: 50 ms
• Kirigami.Units.shortDuration: 100 ms
• Kirigami.Units.longDuration: 200 ms
• Kirigami.Units.veryLongDuration: 400 ms

Kirigami.Units.humanMoment (2000 ms) isn't scaled and shouldn't be used for animations. Use it to measure how long to wait before telling the user something, or as the limit before something starts automatically.