Development/Tutorials/Plasma5/QML2/HelloWorld

Note

This is very much a work in progress. I only have so much free time each day. Keep checking back.

Welcome!

This tutorial will take you through the process of creating a simple "Hello World"-style plasmoid. It is written primarily in QML2 and intended for the Plasma 5.10+ desktop. There will also be a bit of Javascript mixed in, and it will be called out when used. An explanation of the various plasmoid testing and installation tools will be covered as well.

Tools and Prerequisites

You're going to need a text editor, preferably one that can highlight QML syntax. The Atom editor is free and has a QML syntax plugin. The ultimate in Qt/QML development is Qt Creator, which is the integrated development environment (IDE) that ships with the Qt framework, which powers the entire Plasma interface. It's overkill for our purposes, so it's recommended you stick with a fairly basic text editor for now.

You will not have to spend hours downloading and compiling source code in order to develop plasmoids. Everything you'll need is probably already included in your KDE-based distribution.

File Structure

The plasmoid system relies on a common file structure, so open up a terminal and create the following directories. The example shows the highest level as ~/projects, but feel free to create an empty folder anywhere in your personal workspace. That root directory will be omitted during the rest of the tutorial - it's just a convenient place for you to store your code.

~/projects/
     hellomoid/
     hellomoid/plasmoid/
     hellomoid/plasmoid/contents/
     hellomoid/plasmoid/contents/ui

There are also two important configuration files. First off is CMakeLists.txt, which defines some of the underlying dependencies to turn your plasmoid source code into a runnable program.

Create a new file in your editor and use the following template:

# set minimum CMake version (req'd for CMake 3.0 or later)
cmake_minimum_required(VERSION 2.8.12)

# use Extra CMake Modules (ECM) for common functionality
find_package(ECM REQUIRED NO_MODULE)
# needed by find_package(KF5Plasma) below.
set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH} ${ECM_KDE_MODULE_DIR} ${CMAKE_MODULE_PATH})

# Locate plasma_install_package macro
find_package(KF5Plasma REQUIRED)

# Add installation target ("make install")
plasma_install_package(plasmoid.org.kde.hellomoid)

Save this file as hellomoid/CMakeLists.txt. At least for the sake of this tutorial, you probably won't need to touch it again. So just create it and file it away.

Next up is metadata.desktop, which contains many more configurable options. We'll start with the template, then explain which options are safe to change while keeping your plasmoid running.

[Desktop Entry]
Encoding=UTF-8
Name=Hellomoid
Comment=Hello World example plasmoid
Icon=face-cool
Type=Service

X-KDE-ParentApp=
X-KDE-PluginInfo-Author=Your Name
[email protected]
X-KDE-PluginInfo-License=GPL
X-KDE-PluginInfo-Name=org.kde.hellomoid
X-KDE-PluginInfo-Version=1.0
X-KDE-PluginInfo-Website=plasma.kde.org
X-KDE-ServiceTypes=Plasma/Applet
X-KDE-PluginInfo-Category=Windows and Tasks

X-Plasma-API=declarativeappletscript
X-Plasma-MainScript=ui/main.qml
X-Plasma-RemoteLocation=

Feel free to change the PluginInfo-Author and PluginInfo-Email definitions with your own information. Go ahead and change the Comment line if you'd like a different tag line for your example. Please don't change the Name or PluginIn-Name fields. The rest of the tutorial depends on these remaining the same as the example.

Save this file as hellomoid/plasmoid/metadata.desktop

Your First QML Code

We're done with the boilerplate setup for now. It's time to start creating something interesting. Back in the metadata.desktop file, we defined the property X-Plasma-MainScript and set the value to ui/main.qml. It's time to create that file.

import QtQuick 2.0
import org.kde.plasma.plasmoid 2.0
import org.kde.plasma.core 2.0 as PlasmaCore

Item {
	PlasmaCore.IconItem {
		source: "face-smile"
		width: parent.width
    	        height: parent.width
	}
}

Save this file as hellomoid/plasmoid/contents/ui/main.qml. It does three simple things:

• imports the libraries necessary for the plasmoid to function
• defines an IconItem, which, naturally, displays an icon
• sets the source and size for the icon

You're probably eager to see your plasmoid in action, even though it doesn't do much right now. To preview your plasmoid, we use the plasmoidviewer tool.

From your terminal prompt, enter the following command:

plasmoidviewer --applet ~/projects/hellomoid/plasmoid/

You should be rewarded with a window like this: