Plasmoid Tutorial 1

With Plasma 5.2 out I wanted to update the tutorials on how to write a Plasmoid. Going through all of the steps from hello world, to using Plasma Components to configuration through to differing form factors.

It made sense to publish them as blog posts before I copy them to the wiki.

Behold, the first rather wordy blog post in a series of 7.

Intro

With Plasma5 we have embraced QML as our technology of choice. It is the only method of writing the UI for plasmoids.

Whilst Plasma4 offered a range of language, QML is the only way of interacting with QtQuick, the technology that powers the Plasma Shell. By using this we we get to provide a better developer experience as there is a wealth of existing QML resources. Some of the best links are:

  • http://doc.qt.io/qt-5/qml-tutorial1.html
  • http://qmlbook.org/

Before you get started with writing plasmoids, it is recommended to read through the basics of these and have a bit of playing to get used to the language.

Writing plasmoids is effectively the same as writing any other QtQuick QML, with a few extensions:

  • We have a specific folder structure with metadata for our plasmashell to be able to load the files.
  • We provide a massive collection of libraries that extend the QtQuick library both with functionality and widgets that blend in with the Plasma theme.
  • Special API exists to interact with the shell, allowing you to save configurations or set default sizes.

In this series of tutorials we'll go through the steps of writing a real plasmoid from scratch, using some of the plasma libraries.

By the end we should have a completely working, deployable RSS reader.

Hello world

Initial Folder Structure

Plasmoids follow the simple KPackage structure. In the top-most folder there should be a file titled metadata.desktop and a single folder called "contents".

Inside the contents folder we place all our QML, assets and other additional files. We split the contents into subdirectories: config, data and ui to make things easier.

In our tutorial we will be making an RSS reader so everything is named appropriately to that.

The basic directory structure should be as follows:

myrssplasmoid/metadata.desktop
myrssplasmoid/contents/ui/main.qml

metadata.desktop

[Desktop Entry]
Name=RSS Plasmoid
Comment=Shows RSS Feeds
Encoding=UTF-8
Icon=applications-rss
ServiceTypes=Plasma/Applet
Type=Service
X-KDE-PluginInfo-Author=David Edmundson
X-KDE-PluginInfo-Email=davidedmundson@kde.org
X-KDE-PluginInfo-Name=org.example.rssplasmoid
X-KDE-PluginInfo-License=LGPL
X-KDE-PluginInfo-Version=1.0
X-KDE-PluginInfo-Website=http://techbase.kde.org
X-Plasma-API=declarativeappletscript
X-Plasma-MainScript=ui/main.qml

Most of the fields here should be fairly self explanatory.
If in doubt, copy this and change the relevant fields.

main.qml

import QtQuick 2.0

Item {
    Text {
        anchors.centerIn: parent
        text: "Hello World!";
    }
}

Providing you have followed the recommended reading this should be fairly self-explanatory, we have a text item in the middle of the plasmoid which will say "Hello World".

Over the next few tutorials this will get somewhat larger, we will also see some of the problems with this example; here translations aren't implemented and the text won't match the Plasma theme colour.

Installation

From the directory above run

plasmapkg2 --install myrssplasmoid

It should now be visible in the plasmashell in the "Add widgets" option along with every other plasmoid.

We can then it to our desktop or panel like any other installed plasmoid.

Next

Next tutorial, we will cover getting data from external sources.

7 thoughts on “Plasmoid Tutorial 1”

  1. David, hoping you can help me. I cannot get your, or anybody’s, hello world plasmoid tutorial to work. Which seems nuts because it certainly seems very, very easy and straight-forward. In trying yours just now it won’t install. When I make the directories and files exactly as you have them, then run > plasmapkg2 –install myrssplasmoid < from terminal, in what I believe to be the right directory, it just gives me the help readout for plasmapkg2 – which incidentally also informs me that the installer has been replaced with kpackagetool5; which also doesn't work. I have been trying for days and days to just get a simple plasmoid to work, all to no avail. And online resources to help are scarce to non existent. Anything you can do to help me, including pointing me to maybe some more recent tutorials or books or something would be greatly appreciated. fwiw, I am on Fedora 27.

    1. You should run it from the directory above your plasmoid. I.e

      If I have
      /home/david/myrssplasmoid/metdata.desktop
      /home/david/myrssplasmoid/contents/ui/main.qml

      I would run this from /home/david

      1. Yes, I ran it from the parent directory. I actually tried it from both parent and child. But I just now did run across another reference that shows the install command using kpackagetools5 where you specify the package type, and it worked. Which is a huge milestone for me at long last. So the install command that worked is:

        kpackagetool5 -t Plasma/Applet –install myrssplasmoid

        So now I will work my way through the rest of your tutorial and see how it goes. And thanks for the quick response!

        1. I’m slowly working my way through the meager tutorials I can find. On my system (Kubuntu 17.10 & Plasma 5.12beta) “plasmapkg2” is now just a pointer to kpackagetool5. I used the same syntax as you and had success.

          However, I can’t get my packaged plasmoid(s) to show up in plasmoidviewer. I just get a window with the tool buttons at the bottom but no plasmoid. I was able to put the “Hello World” version of this plasmoid on my desktop from the lefthand desktop panel. It didn’t have an icon in the display listing, but that may be my icon theme’s fault.

          1. I haven’t yet tried to use plasmoidviewer, so don’t know if that will work for me or not. (I’ve, sadly, been too busy with my ‘day job’ sucking up too much of my time.) I also haven’t even thought about the icon in the display. I figure I’ll stumble upon that eventually as I go. My goal now is to figure out to make a RESTapi call from the QML. Which, oddly, is also lacking in clear explanation. QML is supposed to be easy; and I suppose with some instructions it would be. But at the moment, oddly, just writing a full-blown C program is easier for me.

          2. I couldn’t write “Hello World” in C, so we’re equals. QML makes a little more sense to me because I’ve done some programming in PyQt, which is the Qt library adapted for coding in Python.

            Part of the complication with learning to code these plasmoids is that we’re learning two things at once: the QML engine, and the Plasma frameworks that display the results. We’re also working with stuff that’s absolutely current, so tutorial content is hard to find. I’ve signed up as a KDE contributor and made a few small edits to the TechBase wiki with what I’ve learned.

            With all due respect, this tutorial won’t run any longer. I think it’s just out of date. I managed to hack at it and got the list of articles to display and be clickable links. But the display part is still all jacked up (the representations and layout concepts are still a work in progress for me).

            I’ll post my updates when I make more progress. This tutorial also borrows from a QML tutorial on the qt.io website (search RSS). Theirs is more complicated, but it showed me how to use an XML “engine” as opposed to the “RSS” engine shown in Part 3 of this article.

            We’ll get there. Gonna take time.

          3. Totally agree with you re the Plasma frameworks complication. The straight-up QML docs aren’t half bad; but the Plasma documentation is just non-existent. Cudos to you for becoming a KDE contributor. I’ll be tracking your progress!

Leave a Reply to Dito Cancel reply

Your email address will not be published. Required fields are marked *