Plasmoid Tutorial 3 – Blending In

Till now we have dealt with basic QtQuick Text items. Whilst they work, they will look out of place on a Plasma desktop. More importantly it's quite likely that you can get a situation where you can get black text on a black background, or another unreadable combination.

If we run our current applet as soon as we change to another theme we get a problem.

We want to have consistent visual style amongst plasmoids that follows the user's themes, along with consistent spacing throughout the shell. We want all "third party" plasmoids to follow these rules too.

We provide a set of imports that help make this happen.

The visual Plasma import come under 3 categories:

org.kde.plasma.core

This contain low level shapes; such as varying frames, SVG loading and icons, as well as a utility to get DPI independent sizes to use for spacing and other metrics. Useful for keeping things consistent.

org.kde.plasma.components

This contains the standard set of "widgets"; text boxes, spin boxes and labels and much more.

org.kde.plasma.extras

This is extra utilities that may be useful in your plasmoid.

Best Practices

• Avoid hardcoding fonts and colours. Use the ones from the user's theme.
  If you must hardcode, make sure you never hardcode on top of a theme background or parts could end up unreadable.
• Avoid using the Text element from the QtQuick import, instead use Label from Plasma components, it will set the right fonts and sizes automatically.
• Do not adjust font sizes and styles. For headings use the Plasma Heading element with the appropriate level set to affect font size.
• Set all animations to Theme.ShortAnimation or Theme.LongAnimation as appropriate.
• Don't use QtQuick.Controls directly from inside the main plasmoid view

Continuing The RSS Viewer example

If we apply that to our current RSS viewer, our main view code should end up looking something like this:

import QtQuick 2.0
import org.kde.plasma.core 2.0 as PlasmaCore
import org.kde.plasma.components 2.0 as PlasmaComponents
import org.kde.plasma.extras 2.0 as PlasmaExtras


Item {
    PlasmaExtras.ScrollArea {
        anchors.fill: parent
        ListView {
            id: mainList
            focus: true
            boundsBehavior: Flickable.StopAtBounds

            model: RssModel {
                id: rssModel
                source: "http://planetkde.org/rss20.xml"
            }

            delegate: PlasmaComponents.ListItem {
                PlasmaComponents.Label {
                    anchors.left: parent.left
                    anchors.right: parent.right
                    height: implicitHeight

                    elide: Text.ElideRight
                    text: model.title

                }
                MouseArea {
                    anchors.fill: parent
                    onClicked: Qt.openUrlExternally(model.link)
                }
            }
        }
    }

    PlasmaComponents.BusyIndicator {
        anchors.centerIn: parent
        //whilst the model is loading, stay visible
        //we use opacity rather than visible to force an animation
        opacity: rssModel.loading ? 1: 0

        Behavior on opacity {
            PropertyAnimation {
                //this comes from PlasmaCore
                duration: units.shortDuration
            }
        }
    }
}

I've added a busy indicator (a spinning wheel) whilst we're fetching the RSS feed, just as a way to show how we use units.ShortAnimation

Finally, we end up with something like this: which looks good on all Plasma themes.