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.